Next: Variables, Previous: Chart Designs, Up: Reference for Common Language Elements [Contents]

### 8.11 Procedures

Procedures allow you to store some chart text and replay it later. They are useful to save typing, promote re-use instead of copy/paste. Since procedures can take parameters their result can be customized.

To define a procedure, use the `defproc` command.

    defproc proc_name {
       ...chart text for procedure...
    };

    defproc proc_name($param_name[=default value, ...) {
       ...chart text for procedure...
    };

You can list parameters and their (optional) default value, as well. Parameter names should begin with the dollar sign (`$`). They can be used anywhere a string or number is needed, such as for attribute values, attribute names, entity and node names, etc. You can not invoke a keyword using a parameter.

The `\Q()` text formatting escape can be used to substitute a parameter value into a label. The tilde (`~`) character can be used to append or prepend string constants to a parameter, enabling string composition. In graphviz the `+` character can also be used. The double-dollar special symbol (`$$`) can be used to denote an string that is always unique for each procedure replay but when printed it is empty. This can be used, when you want to define a node (or entity or marker for signalling charts) for each time the procedure is replayed, but you do not want to pass a procedure parameter to compose with (such a `$group_name` above).

As you can see you can fall back to the default value of parameters, even if they are not the last one.

It is possible to replay a procedure within another procedure. Do not use recursion. It is not allowed to define a procedure in another procedure, however. If you replay a procedure inside another one, the parameters of the outer procedure will not be visible in the inner procedure.

When you refer to a style, color or procedure name, or an entity, node or marker from within a procedure definition, their value will be substituted at the place of the replay. Thus their existence cannot be verified at the time of definition. A full parsing and verification is performed at replay. In order to avoid repeating error messages as much as possible, if an error is already caught at procedure definition time, the procedure cannot be replayed.

Color Syntax Highlighting is also limited for procedures, for example, styles cannot be determined to exist, so they are never marked for error.

Styles and colors defined inside a procedure are local to that procedure (since the procedure has its own scope). If you want to export these after a replay, you can use the `[export=yes]` attribute at the procedure definition. This enables you to create procedures that define styles based on some parameters.

Finally, inside procedures you may use conditional statements that execute or don’t based on the value of some parameters. After the `if` statement you can use either a single parameter or two strings (potentially composed of multiple substrings with `~`) compared with one of the following operators: `<=`, `<`, `==`, `>`, `>=` and `<>` (the latter for non-equal). String comparison is UTF-8 and not numeric (thus "2" is larger than "10"). If you use only a single parameter, the condition is true if the parameter is any non-empty string.

Note that you can use braces to include more than one statement for the then or else branches.

Next: Variables, Previous: Chart Designs, Up: Reference for Common Language Elements [Contents]