MainAPISyntax

API Syntax

Commands and answers of the uDraw(Graph) API are so called "terms" that can be built hierarchically by applying substitution rules of the syntax definition. The syntax of commands and answers is defined in a "Backus-Naur" form. This syntax grammar is a set of substitution rules where each rule has a left and right hand side separated by "::=". A rule may have different alternative cases on the right hand side, separated by vertical bars "|". Terminal symbols of the grammar are written in bold face and have to occur in the term. Non-terminal symbols are links to other rules and have to be substituted by one of the cases of the particular rule. This substitution process continues until no non-terminal symbols remain. To say it in another word: commands and answers are exclusively composed of terminal symbols. The start symbol for the commands is the rule uDG_command and for the answers uDG_answer.

For example, consider the following rules:

uDG_command::=
	tcl(tcl_cmd)
|	... other cases ...
tcl_cmd::=
	eval(string)
|	eval_file(filename).
filename::=
	string.

Here are some examples for valid commands with respect to this simple grammar:

Usually, white space (i.e. space, tab or return/newline characters between non-terminal symbols) is allowed, but should not be used in a term to reduce the amount of transmitted data. Return or newline characters must not be used in a term if sent to the API. The reason for this restriction is that a newline character is required to signal the end of a command if sent on a pipe. So with a newline inside, the term will be split at this position, resulting in a syntax error for the command fragment. If you need to have newline characters inside of a string (e.g. to visualize a node with multi-line text), you can use the escape mechanism known from the "C" programming language (i.e. "\n").

Note: Because Tcl/Tk is used for the implementation of the uDraw(Graph) user interface, some characters have a special meaning. Braces ("{" and "}") are used as delimiters for sending strings to Tcl/Tk. As a restriction, you cannot use unbalanced braces somewhere inside of an API string, even if they are escaped with "\". Using strings like "}" or "{" inside of an API command will result in Tcl/Tk error messages on command-line, whereas a balanced "{}" is allowed. So you have to avoid sending strings with unbalanced braces.