Node:Extracted grammar, Next:Writing Clients, Previous:Measured Properties, Up:Top

Extracted grammars (informative)

The file Protocol-A.texi is the authoritative standard for protocol A. However, it has a two problems:

• The Texinfo markup makes it hard for a program to extract information-and once a program is written, we might change the Texinfo markup, so that the program has to be updated.
• We often rename requests and data types, in order to have good names for the most recommended functions and types. However, a program that uses a data type might fail if that type suddenly is altered.

To overcome these problems, and better server client writers that want to generate the protocol-level code automatically from the specification, a few variants of the grammar is available as separate files. In some of these files, the names have been changed to stable names that will not change as the protocol evolves. Currently, these three grammars exists:

protocol-a-full.txt

The full Protocol A specification, with stable names.

protocol-a-recommended.txt

The recommended requests and asynchronous messages, and all types they need, with stable names.

protocol-a-current.txt

The recommended requests and asynchronous messages, with the names used in this specification.

The files are generated by doc/checkargs.py in the lyskom-server distribution. Adding more output formats is fairly easy. Let us know, preferably via Bugzilla, if a new output format would be useful for you. It is the intention that the format of the above-mentioned files will not change. The file format should be self-explanatory once you have read the protocol specification. It does contain some comments that should be useful.

The stable names are generated by this process:

• Don't modify builtin types such as INT32.
• Remove the suffixes -old, -older and -Old, unless that would introduce an ambiguity.
• Unless the name already has a version suffix, add one.

All files mentioned above are reachable via http://www.lysator.liu.se/lyskom/protocol/.