lumas module com.tech-know-ware.my-example;
/*
An example Lumas definition
*/
import com.tech-know-ware.general as tkwg;
struct my-example
{
int <0..255> participant-id as ?;
Action action as ?;
struct my-addition[0..1]
as new.tech-know-ware.com plugin
{
bool tkw-app-capable as ?;
};
};
union Action
{
Join join;
Message message as msg;
void leave;
};
struct Join
{
unicode<0..63> name;
};
struct Message
{
int <0..255> to-participants[1..127] as to;
unicode<1..255> message as msg;
[ // Version 2 additions
tkwg::Priority priority;
]
[ // Version 5 additions
ascii<0..16> font-name[0..1] as font;
void bold[0..1];
void italic[0..1];
void underlined[0..1] as ul;
]
};
The first construct (in this case the struct my-example) is the root of all messages for the protocol. Each message identifies a participant using an integer in the range 0 to 255, called 'participant-id'. When encoded on the wire, this parameter will be untagged due to the 'as ?' specification.
Each message then has an action, which is also untagged. The type of the action parameter is not immediately specified, and instead references the 'Action' definition.
The Action definition is a union in which only one of the specified parameters may appear in an instance of the Action construct. This effectively represents a fork in the semantics of any given message. The options within Action can indicate that somebody has joined the meeting, left the meeting, or is sending a message to other participants.
There is no explicit tag for the 'join' and 'leave' options, so these will be tagged on-the-wire by the parameters' names, 'join' and 'leave' respectively. Conversely, an explicit tag for the 'message' parameter is specified, and hence the message option will be tagged by 'msg' on-the-wire.
The join parameter also has a referenced definition. For the purposes of this example, when a person joins a meeting, all the other participants are informed of their name. The name is a Unicode string that has a minimum length of 0 characters and a maximum length of 63 characters.
The message option is also a referenced definition. Conceptually, to send a message, the 'participant-id' is used to identify the sender, and the 'to-participants' field contains the participant ids of all the people to whom the message is being sent. On-the-wire, the to-participants parameter will be tagged with 'to'. Between 1 and 127 (inclusive) instances of the to-participants parameter may appear in a message.
Also, the message itself is included. The message will consist of Unicode characters and can be between 1 and 255 Unicode characters long. On-the-wire, the message parameter will have the tag 'msg'.
The priority field within the message struct has been added in a later version of the protocol. This is indicated by the square brackets in which the parameter is wrapped. Similarly, font-name, and the associated parameters have, according to the comment, been added in version 5 of the protocol. The type of the 'priority' parameter is defined in an external module that has the alias 'tkwg'. The 'import' directive at the beginning of the example indicates that the 'tkwg' alias corresponds to the module 'com.tech-know-ware.general', and it is in this module that the definition of 'Priority' is located. The definition indicates that 'font-name' is an ASCII string. The reader should already understand enough of the definition language to understand the meaning of the other fields.
Returning to the 'my-example' root, a third-party has added an extension to the protocol in the form of the 'my-addition' parameter. It is identified as not being part of the base specification by the keyword 'plugin'. On-the-wire, the additional parameter will be identified by the tag 'new.tech-know-ware.com' to differentiate it from additions that may be made by other third parties.
1
join = { "Alice" }
new.tech-know-ware.com = { True }
and:
1
msg = { to = 2, 5, 8, 58
msg = "Where are we going for dinner"
font = 'Arial'
ul }
and:
1
leave