Documentation

The CDDL constructor takes three arguments: 1. Top level comments that precede the first definition 2. The root definition 3. All the other top level comments and definitions This ensures that CDDL is correct by construction.

Sort the CDDL Rules on the basis of their names

A name can consist of any of the characters from the set {A to Z, "a" to "z", "0" to "9", "_", "-", "", ".", "$"}, starting with an alphabetic character (including "", "_", "$") and ending in such a character or a digit.

• Names are case sensitive.
• It is preferred style to start a name with a lowercase letter.
• The hyphen is preferred over the underscore (except in a "bareword" (Section 3.5.1), where the semantics may actually require an underscore).
• The period may be useful for larger specifications, to express some module structure (as in "tcp.throughput" vs. "udp.throughput").
• A number of names are predefined in the CDDL prelude, as listed in Appendix D.
• Rule names (types or groups) do not appear in the actual CBOR encoding, but names used as "barewords" in member keys do.

rule = typename [genericparm] S assignt S type / groupname [genericparm] S assigng S grpent

typename = id groupname = id

A rule defines a name for a type expression (production "type") or for a group expression (production "grpent"), with the intention that the semantics does not change when the name is replaced by its (parenthesized if needed) definition. Note that whether the name defined by a rule stands for a type or a group isn't always determined by syntax alone: e.g., "a = b" can make "a" a type if "b" is a type, or a group if "b" is a group. More subtly, in "a = (b)", "a" may be used as a type if "b" is a type, or as a group both when "b" is a group and when "b" is a type (a good convention to make the latter case stand out to the human reader is to write "a = (b,)"). (Note that the same dual meaning of parentheses applies within an expression but often can be resolved by the context of the parenthesized expression. On the more general point, it may not be clear immediately either whether "b" stands for a group or a type -- this semantic processing may need to span several levels of rule definitions before a determination can be made.)

assignt = "=" "=" assigng = "=" "/="

A plain equals sign defines the rule name as the equivalent of the expression to the right; it is an error if the name was already defined with a different expression. A "=" or "/=" extends a named type or a group by additional choices; a number of these could be replaced by collecting all the right-hand sides and creating a single rule with a type choice or a group choice built from the right-hand sides in the order of the rules given. (It is not an error to extend a rule name that has not yet been defined; this makes the right-hand side the first entry in the choice being created.)

Generics

Using angle brackets, the left-hand side of a rule can add formal parameters after the name being defined, as in:

messages = message"now" / message1..100 messagev = {type: t, value: v}

When using a generic rule, the formal parameters are bound to the actual arguments supplied (also using angle brackets), within the scope of the generic rule (as if there were a rule of the form parameter = argument).

Generic rules can be used for establishing names for both types and groups.

A type can be given as a choice between one or more types. The choice matches a data item if the data item matches any one of the types given in the choice.

Two types can be combined with a range operator (see below)

A range operator can be used to join two type expressions that stand for either two integer values or two floating-point values; it matches any value that is between the two values, where the first value is always included in the matching set and the second value is included for ".." and excluded for "...".

An optional _occurrence_ indicator can be given in front of a group entry. It is either (1) one of the characters "?" (optional), "*" (zero or more), or "+" (one or more) or (2) of the form n*m, where n and m are optional unsigned integers and n is the lower limit (default 0) and m is the upper limit (default no limit) of occurrences.

If no occurrence indicator is specified, the group entry is to occur exactly once (as if 1*1 were specified). A group entry with an occurrence indicator matches sequences of name/value pairs that are composed by concatenating a number of sequences that the basic group entry matches, where the number needs to be allowed by the occurrence indicator.

A group matches any sequence of key/value pairs that matches any of the choices given (again using PEG semantics).

A group entry can be given by a value type, which needs to be matched by the value part of a single element; and, optionally, a memberkey type, which needs to be matched by the key part of the element, if the memberkey is given. If the memberkey is not given, the entry can only be used for matching arrays, not for maps. (See below for how that is modified by the occurrence indicator.)

Key types can be given by a type expression, a bareword (which stands for a type that just contains a string value created from this bareword), or a value (which stands for a type that just contains this value). A key value matches its key type if the key value is a member of the key type, unless a cut preceding it in the group applies (see Section 3.5.4 for how map matching is influenced by the presence of the cuts denoted by "^" or ":" in previous entries).