From Core Protocols
Refer to the glossary for definitions of the terms used below. The primary message protocol consists of commands (from commanders to actors) and replies (from actors, but might not have been solicited). Both types of message include keywords.
Information about parsing message strings is collected here.
Keywords consist of a name optionally followed by a list of comma-separated values, for example:
start constants = 2.71828,3.14159
White space (space and tab characters) surrounding the equals sign or commas is not significant. A keyword name must begin with a letter A-Z or a-z and can only contain letters, numbers (0-9) and the punctuation dot (.) and underscore (_). Note that the keyword validation framework considers keyword names to be case insensitive, although capitalization is encouraged to improve readability. Also, the keyword namespace provided by a Keys dictionary is case insensitive.
Values are treated as strings so invalid number formats are still considered valid keyword values. A value must be quoted if it it is empty "" or else contains any of the following characters:
For commands only, the value "raw" (and all of its upper/lower case variations) must also be quoted. Values can be quoted with either 'single' or "double" quotes and the quotes are not considered part of the value. A value may contain quote characters as long as they are 'escape\'d' or else do not match the enclosing 'quote"s'. Values that do not require quoting can still be enclosed in quotes.
A formal grammar for parsing keywords is given below. NAME_OR_VALUE is a token that is both a valid keyword name and keyword value. VALUE is an unquoted value that, because of the characters it contains, could not be a valid keyword name.
keyword : NAME_OR_VALUE
| NAME_OR_VALUE values
values : '=' value
| values ',' value
value : NAME_OR_VALUE
| VALUE
| QUOTED
The keyword name "raw" (and all of its case variations) has a special interpretation in commands (see below) and may not be used in replies.
A reply string consists of keywords separated by semicolons, for example:
drink=coffee ; blend = 20:80, Kenyan,Bolivian
White space surrounding the semicolons or appearing at the start or end of a reply is not significant. No semicolon is required if there is only one keyword present in the reply. The order of keywords is generally not meaningful but will be preserved by parsing. The grouping of keywords into a reply implies that their corresponding values are valid simultaneously and, by default, should be assigned a common time stamp when being archived. A keyword name will not normally be repeated within a reply although this is not considered an error. The keyword name "raw" (and all of its case variations) is reserved and may not be used in replies.
A formal grammar for replies is given below.
reply : reply_keywords
reply_keywords : keyword
| reply_keywords SEMICOLON keyword
A reply string is normally preceded by a text header, for example:
tui.tcc 123 hub ! drink=coffee;...
where drink=coffee;... is the reply string described above. The header consists of the following four white-space separated fields:
The commander name is further subdivided into the following subfields separated by the dot character (.):
The program name is optional and can be left blank, for example when a human is typing commands interactively. The actor stack is also optional and, if present, encodes the history of actors involved in generating this reply and will contain dots. The following are all valid commander names:
.user program.user program.user.actor1 program.user.actor1.actor2.actor3 .user.actor1.actor2
The program name and user name must be valid python identifiers.
The message parsing documentation has details about the reply header fields.
A command string consists of a verb optionally followed by sequence of keywords, for example:
make_coffee type=decaf blend = 20:80, Kenyan,Bolivian drink
White space surrounding the verb and keywords or appearing at the start or end a command is not significant. The order of keywords supplied to a command is generally meaningful and a keyword name may be repeated within a command. Valid verb names are valid keyword names but with two additional restrictions: "raw" (and all of its case variations) is not permitted and verb names may not contain the dot (.) character.
If the keyword "raw" appears in a command, it must be followed by an equals sign. The "raw" keyword has a single value consisting of all remaining characters in the command, including any white space, immediately following the equals sign. No further parsing of the command line is performed and any characters can safely be used without quoting or escaping. For example, the following command has two keywords: "lang" and "raw", and the value of "raw" is " : *+ * + ;"
passthru lang = forth raw = : *+ * + ;
A verb may be followed by one or more values that are associated with the verb itself and not with any keyword. For example,
drink coffee,tea type=decaf
A command such as:
drink coffee
is potentially ambiguous since "coffee" could be a value associated with the verb "drink" or else the name of a keyword with no associated values. The formal grammar adopted here resolves this ambiguity in favor of the keyword interpretation. Note that there is no ambiguity when the second word is not a valid keyword name or is quoted, so the following would specify "coffee" as a value associated with "drink":
drink "coffee"
Note: one of our requirements is that actors avoid such ambiguities. The simplest solution is to never allow strings or keywords for the value list following the verb, but instead use an associated keyword for all string and keyword values, e.g. drink type=coffee, which will be automatically be parsed the same way as drink type="coffee". If you insist on allowing strings or keywords for the value list after the verb, then you are responsible for resolving the ambiguity yourself, e.g. your actor must treat drink coffee and drink "cofee" identically even though the parser has parsed them differently.
A formal grammar for commands is given below. The last clause augments the keyword definition to include the special "raw" form. The cmd_keywords clause differs from reply_keywords in two ways: an empty set is permitted and keywords are white-space delimeted.
command : NAME_OR_VALUE
| NAME_OR_VALUE NAME_OR_VALUE cmd_keywords
| NAME_OR_VALUE RAW LINE
| NAME_OR_VALUE NAME_OR_VALUE values cmd_keywords
| verb_with_values cmd_keywords
verb_with_values : NAME_OR_VALUE VALUE
| NAME_OR_VALUE QUOTED
| NAME_OR_VALUE NAME_OR_VALUE ',' NAME_OR_VALUE
| verb_with_values ',' value
cmd_keywords : (empty)
| cmd_keywords keyword
keyword : NAME_OR_VALUE
| NAME_OR_VALUE values
| RAW LINE