Lumas Example

Lumas is a simple language and for those that a familiar with C, it should be possible to get an understanding of the language without much effort. This page presents a simple example message definition that presents many of the features of the language and some sample encoded messages.

Example Lumas Message Definition

The following is a simple example Lumas message definition taken from the specification. It loosely models a simple meeting controller. An explanation of the example is presented after the example.
      lumas module;
      An example Lumas definition
      import as tkwg;

      struct  my-example
            int <0..255>    participant-id  as  ?;
            Action          action  as  ?;
            struct          my-addition[0..1] 
                                   as 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 '', 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 '' to differentiate it from additions that may be made by other third parties.

On the wire examples

Examples of the on-the-wire encoding are:

      join = { "Alice" }  =  { True }
      msg = { to = 2, 5, 8, 58  
            msg = "Where are we going for dinner"
            font = 'Arial'
            ul }  

[Back to Lumas Home Page]