DRAFT: Kueea Module Declaration Language

This document is a live working draft. Do not implement.

KMDL documents declare one Kueea Module per document. Their syntax is designed to be human-readable and fairly easy to read and write using the most simple text editors.

KMDL processors take KMDL documents as input. The primary output are source files in a given programming language. Other output include module documentation in HTML or other formats. They are part of tool chains that build Kueea Module implementations.

Keywords

The key words ‘MUST,’ ‘MUST NOT,’ ‘REQUIRED,’ ‘SHALL,’ ‘SHALL NOT,’ ‘SHOULD,’ ‘SHOULD NOT,’ ‘RECOMMENDED,’ ‘NOT RECOMMENDED,’ ‘MAY,’ and ‘OPTIONAL’ in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

Overview

Processing a KMDL document produces a tree of items.

The root of the tree is the module item. Items declared in the document are its children.

Each item is associated with the module level at which it is introduced. Higher module levels include all items declared at lower levels.

Items are defined in this document as sets of variables. Variables of an item are referenced in prose like this: item.variable (using a dot separator).

Items have an associated human-readable textual description. Conceptually, it is a list of format-line pairs.

Descriptions are treated as opaque data by a KMDL processor. They are only considered when generating output for human users.

When generating such document, the pairs in the list are iterated. Lines are passed in succession to an extenal text processor until the format changes, which is interpreted as the end of input to the current text processor and the beginning of input to another, or when there is no more pairs in the list.

Output of text processors depend on what the KMDL processor outputs.

In other words, the information a KMDL document encodes is a tree of items, where each item is associated with some textual data, in some format.

Syntax

A KMDL document is a sequence of Unicode characters. The documents are read and processed line by line. Maximum length of a line is 1024 octets, including the line separator.

Lines are sequences of characters separated by a sequence of two characters: U+000D CARRIAGE RETURN and U+000A LINE FEED.

Whitespace is either U+0020 SPACE or U+0009 HORIZONTAL TAB.

There are three kinds of lines:

processor instructions,
item descriptions, and
comments.

Comments

Comments are lines that are read and discarded. There are two kinds of comments.

One-line comments are lines beginning with optional whitespace followed by no more than one consecutive U+0023 NUMBER SIGN character.

# This is a one-line comment.
  # This is a one-line comment.
THIS IS NOT A COMMENT.
# # # This is a one-line comment.

Multi-line comments begin and end with a line beginning with optional whitespace followed by 2 consecutive U+0023 NUMBER SIGN characters.

## This is the first line of a multi-line comment.
This is a comment.
.This is a comment.
# # This is inside a multi-line comment.
  ## This is the last line of a multi-line comment.
THIS IS NOT A COMMENT.

Instructions

Instructions declare items and change processor state. These lines begin with optional whitespace followed by one U+002E FULL STOP character and the instruction name. Instruction arguments, each preceeded by whitespace. follow the name.

Instruction names are case-sensitive. They MUST be written with small letters and are four-character long.

.inst arg1 arg2
   .inst arg1

Item descriptions

Any other line is text - a human-readable textual description of the currently active item.

These lines are passed as input to another program when generating module documentation or are ignored if the information is unneeded.

Their syntax is out of scope of this document.

.item example1
Description of the example1 item.

Description of the example1 item.

.item example2

Description of the example2 item.

Line indentation

The preceeding whitespace on an instruction line sets the amount of ignored preceeding whitespace for the text lines that come after it.

Both of the whitespace characters count as one.

Consider the following example:

   .inst first
   Line 1-1.
     Line 1-2.
  Line 1-3.
.inst second
   Line 2-1.
     Line 2-2.
Line 2-3.

The first line is an instruction indented by 3 whitespace characters. The ignored indentation becomes 3.

The second line is text indented by 3 whitespace characters. The parser removes the first 3 whitespace characters. The resulting line has no preceeding whitespace characters.

The third line is text indented by 5 whitespace characters. The parser removes the first 3 whitespace characters. The resulting line has 2 preceeding whitespace characters.

The fourth line is text indented by 2 whitespace characters. The parser removes the first 3 whitespace characters. In this case, the line has less whitespace, so all is removed. The resulting line has 0 preceeding whitespace characters.

The item description for the first item is thus:

Line 1-1.
  Line 1-2.
Line 1-3.

The fifth line is an instruction indented by 0 whitespace characters. The ignored indentation becomes 0.

The sixth line is text indented by 3 whitespace characters. The parser removes the first 0 whitespace characters. The resulting line has 3 preceeding whitespace characters.

The seventh line is text indented by 5 whitespace characters. The parser removes the first 0 whitespace characters. The resulting line has 5 preceeding whitespace characters.

The eigth line is text indented by 0 whitespace characters. The parser removes the first 0 whitespace characters. The resulting line has 0 preceeding whitespace characters.

The item description for the second item is thus:

   Line 2-1.
     Line 2-2.
Line 2-3.

ABNF (formal syntax)

The following KMDL rule expresses the syntax in ABNF. The encoding of the document MUST be UTF-8.

KMDL  = docv CRLF *( line CRLF )
docv  = %s".kmdl" SP 1*4DIGIT
line  = comm / inst / text

comm  = cmul / cone
cmul  = *WSP "##" *OCTET CRLF *WSP "##" *OCTET
cone  = *WSP  "#" *OCTET

inst  = *WSP  "." *( WSP / VCHAR )
text  = [ *WSP "\" ] *OCTET

ABNF rules are referenced in prose like this: <rule>.

The first non-whitespace character of <text> MAY be a U+005C REVERSE SOLIDUS. If so, the \ character is removed before further processing of the line. This is an escape mechanism in case the line begins with # or ..

Items

This section contains format definition of items.

All items contain a desc variable, which is a list of objects which MUST consist of at least:

data: textual data,
format: format of the data.

When pushing a new object n to desc, where o is the last object in desc: if n.format equals to o.format, data in n.data MAY be appended to o.data with a preceeding line separator instead of pushing a new object.

Module

Representation of a module MUST consist of at least:

mid: module identifier,
mlv: module level,
data: list of data members,
enum: set of named values,
func: set of function members,
types: set of classes,
mrefs: set of external module references, tuples of: name (alias), module identifier and target module level.

Class

Representation of a class MUST consist of at least:

cid: class identifier,
clv: current class level,
creg: register type,
data: list of data members,
enum: set of named values,
func: set of function members,
tags: set of tags,
name: name of the class.

Data member

Representation of a data member MUST consist of at least:

next: data member (for unions),
mlv: module level,
clv: class level,
sid: symbol identifier,
tags: set of tags,
type: reference to a class,
align: memory alignment,
array: length of the array,
value: default value,
name: name of the object.

Array length

Representation of an array length MUST consist of at least:

var: member holding the current value,
min: minimum amount of elements,
max: maximum amount of elements.

Parsing examples:

       [10] => min = 10, max =  10, var = ""
      [1:2] => min =  1, max =   2, var = ""
[len:0:255] => min =  0, max = 255, var = "len"

Function member

Representation of a function member MUST consist of at least:

mlv: module level,
clv: class level,
sid: symbol identifier,
tags: set of tags,
params: list of function parameters,
rval: data member (return value),
name: name of the function.

Function parameter

Representation of a function parameter MUST consist of at least:

type_in: input type,
type_out: output type,
name: parameter name.

Symbol identifiers

Some items have an associated symbol identifier. They are 64-bit unsigned integers.

There MUST NOT be two symbol identifiers of the same value within a module.

By default, the value is the result of passing a character string to the 64-bit FNV-1a (Fowler-Noll-Vo) hash function:

hash = 0xCBF29CE484222325
for each octet_of_data to be hashed
  hash = hash XOR octet_of_data
  hash = hash * 0x100000001B3
return hash

Symbol identifiers should only be explicitly declared in case of a collision. The encoding of the string is the same as for the document - UTF-8.

The hashed string consists of names of items separated by a U+0024 DOLLAR SIGN character.

Examples:

global_object, value 0x8EAE284DFC37BA58;
iface$function, value 0x59976F93E8833DA3;
class$0000$function, value 0x713BC2D41B847A6F.

Processor

A KMDL processor consists of a line parser, an instruction parser and the functions the latter invokes.

Both the line parser and the functions have access to the processor's shared state in addition to their own, private state.

Shared state

Shared state of the processor consists of the following variables:

mset: set of modules (object),
mbeg: current module (reference),
item: current item (reference),
desc: current item description (reference),
text: current text format (US-ASCII string).

An implementation also needs to be able to determine the type of the current item in item.

Loading algorithm

The processor loads a module using the following algorithm.

The function takes 3 parameters: a module identifier, a module level and an external function for fetching KMDL documents. These are mentioned in steps 1-3.

Let mid be the identifier of the loaded module.
Let mlv be the level of the loaded module.
Let loader be the extenal fetcher.
Search mset for a module m with m.mid equal to mid.
If found and m.mlv is no less than mlv, return success.
If found and m.mlv is less than mlv, remove m from mset.
Obtain a document kmdl by calling loader, passing mid and mlv as arguments.
If loader has failed, return failure.
Set mbeg to a newly created module representation.
Set mbeg.mid to mid.
Set item to nothing,
Set text to markdown.
Invoke the line parser on kmdl.
If the parser failed, delete mbeg and return failure.
If the mbeg.mlv is less than mid, delete mbeg and return failure.
Insert mbeg into mset.
Iterate mbeg.mrefs and recursively call this algorithm with the arguments from the tuple; if any of the referenced modules failed to load, return failure.
Return success.

After the loading algorithm successfully finishes, the processor resolves all references in the loaded module and generates the requested output.

Line parser

State of the line parser consists of the following variables:

line: current line (Unicode string),
wslv: current line indentation (integer),
skip: ignored line indentation (ingeter).

The line parser takes a stream of octets as input. It loads lines and processes them until the end of the stream.

The parser loads a line as follows:

Let cr be a boolean.
Let input be the input stream of octets.
Set line to an empty string.
Set cr to false.
While input is not empty:
1. Decode the next character c from input.
2. If line is longer than 1024 characters, return failure.
3. Append c to line.
4. If cr is true and c is U+000A LINE FEED, remove the last character in line and return success.
5. If c is U+000D CARRIAGE RETURN, set cr to true; otherwise, set cr to false.
Return success.

After each line is loaded, it is processed.

The first line is special.

The first line

docv  = %s".kmdl" SP 1*4DIGIT

If line does not exactly match the <docv> rule above, the line parser MUST return failure and load no further lines.

The DIGITs encode the version of a KMDL processor. If the version is higher (more) than the implemented one, the line parser MUST return failure and load no further lines.

This document defines version 1.

Other lines

The parser counts the amount of whitespace at the beginning of line and stores the resulting value in wslv.

Further processing depends on the first character after the whitespace.

If the line is a one-line comment, the line is ignored.

If the line is a multi-line comment, the parser loads subsequent lines until another multi-line comment is encountered. All of these lines are ignored.

If the line is an instruction, skip is set to wslv. Whitespace at the beginning and end of line is removed. The U+002E FULL STOP at the beginning is removed. The line is then fed to the instruction parser. In case of an error, the parser MUST fail and load no further lines.

Otherwise, the line is text. Up to skip whitespace characters are removed since the beginning of line. If the first character after the removal is \, the character is removed.

If desc reference an object, create and push an object o with o.data equal to line and o.format equal to text, to desc.

Instruction parser

cmd1  = fun1 *( 1*WSP arg1 )
fun1  = 4LOALPHA
arg1  = UUID / UINT / TAGS / VREG / TYPE / IREF / NAME / ALEN

Instructions MUST match the <cmd1> rule.

The instruction parser converts the instruction line into a list of typed arguments and calls the function named by the instruction.

Instructions begin with a four-letter function name, followed by argument tokens, each preceeded by whitespace.

Some arguments are optional and may be omitted from the line.

The parser MUST fail on any unrecognized function or argument.

Instruction parameters

This section defines instruction parameters.

Parameter rules use capital letters by convention.

Universally Unique Identifier

UUID = 8HEXDIGIT 3( "-" 4HEXDIGIT ) 8HEXDIGIT / %s"NOID"
; example: 12345678-1234-AbCd-1234-aBcD12345678

Modules, classes and interfaces are identified by 128-bit values. These values are globally unique and are treated as opaque data.

It is expected that the value is a Universally Unique Identifier. The value MAY NOT be a valid UUID, although it SHOULD be.

The value 00000000-0000-0000-0000-000000000000 is reserved as the no-value (nil) value and can be written as NOID.

Unsigned integer

UINT  = udec / uhex
udec  = 1*20DIGIT
uhex  = "0x" 1*16HEXDIGIT

Integer arguments are unsigned and may be at most 64-bit long. They are written in decimal or hexadecimal notation.

Register value

VREG = "=" ( valf / vals / valu )
vhex = "0x" 1*HEXDIGIT
vdec = 1*DIGIT
valu = vhex / vdec
vals = ( "+" / "-" ) valu
valf = [ "+" / "-" ] valu [ "." valu ] [ "e" valu ]

The value is typed as one of:

unsigned integer,
signed integer,
floating-point number.

Object type

TYPE = hndt / cref

hndt = hndr "<" ( cref / %s"handle" / %s"?" ) ">"
hndr = %s"none" / %s"read" / %s"rdex" / %s"rdwr" / %s"rwex"

cref = %s"octet" / IREF ":" UINT

There are only two predefined types of objects: octets and handles. All other types are classes defined in a module.

An octet is, well, an octet: 8 bits with no associated meaning. The register type of an octet is an 8-bit unsigned integer.

A handle consists of 24 octets aligned to 8 octets: a 64-bit address and a 128-bit node identifier. The register type of a handle is a memory reference.

Handles are specified as access rights together with the class of object.

none: No access rights.
read: Read-only access.
rdex: Read and execute rights.
rdwr: Read and write rights.
rwex: Read, write and execute rights.

Syntax of handles begin with access rights associated with the handle, followed by a type of referenced object in angle brackets. Handles may also reference objects of undefined (?) type.

A class reference begins with an item reference to a class, followed by its level after a colon.

For example, read means a read-only handle to an instance of class buffer at level 0 from module stream.

Item reference

IREF = [ mref ] 1*( "." NAME )
mref = NAME / UUID

An item reference begins with a module reference, followed by a sequence of item names, each referring to an item declared as part of the preceeding item.

The module reference may be omitted as a shorthand for referencing the module declared by the currently parsed document.

References are resolved after all modules are loaded. Referenced item MAY be declared later in a document.

Name

NAME = LOALPHA *( LOALPHA / DIGIT / "_" )

Items are given a human-readable name for reference. All letters in names MUST be small.

It is RECOMMENDED that names of functions be composed in subject-object-verb order, for example object_units_replace. This name requirement is for consistency.

Note that one can generate aliases in camelCase, too, if needed. Source code could be converted back and forth.

Array length

ALEN = "[" [ [ mlen ":" ] UINT ":" ] UINT "]"
mlen = NAME *( "." NAME )

Semantics of the <ALEN> rule are:

0: No array.
UINT: Implicit constant length.
UINT ":" UINT: Implicit variable length.
mlen ":" UINT ":" UINT: Explicit variable length stored in member <mlen>, within a range.

Maximum length is 2³²-1.

Processor functions

Functions are defined by listing their parameters in ascending order, describing the function and formally specifiying its outcome.

Processor state consists of the following variables:

mfin: level finalization state (boolean),
clvl: current class level (integer),
cbeg: current container (reference),
func: current function (reference).

The `text` function

Updates the format of item descriptions.

<NAME> format: The new format.

The syntax of item descriptions is Markdown by default and may be changed at any point with this function.

Format names SHOULD be subtypes of text/ Internet Media Types.

An example:

This will be interpreted as _Markdown_ text.
.text html
<p>This will be interpreted as <b>HTML</b> text.</p>

Implementations MUST modify the state as follows:

Set text to format.

The `load` function

References an external module.

<UUID> mid: Module identifier.
<UINT> mlv: Required minimum level of the module.
<NAME> name (optional): Alias for the module.

Modules reference items defined in other modules. These modules must be loaded or else dereference phase will fail.

The instruction can appear at any point in the document. It does not have to appear before any reference to the module. It is RECOMMENDED that these instructions appear at the beginning of a document, though.

Implementations MUST return failure if any of the following is true:

mid is nil.
mlv is equal to or more than 2¹⁶.
name was given and mbeg.mrefs has a tuple t with t.name equal to name.

Implementations MUST modify the state as follows:

Find a tuple t in mbeg.mrefs with t.mid equal to mid.
If found and t.mlvl is less than mlv, set t.mid to mlv.
Otherwise, insert a new tuple (mid, mlv, name) into mbeg.mrefs.

The `mbeg` function

Begins declaration of the module.

<UUID> mid: Module identifier.

It SHOULD NOT appear more than once in a KMDL document.

Modules are a special kind of classes. Kueea Nodes have at most one instance of these classes. All loaded implementations share the same instance. In other words, modules are singleton objects.

The instance is temporary, stored in volatile memory.

The following functions are implicitly declared:

_create: Creates a new instance of the module.; Returns: Read-write handle to an instance.
_upgrade: Upgrades a module instance from a lower level.; Parameter: Read-write handle to the old instance.; Returns: Read-write handle to the new instance.

Both of these functions are called by the kernel only.

The _create function is called when there is no instance available.

The _upgrade function is called when the lowest level of all loaded implementations is higher than the level of the current instance.

This also means that it is not possible to load an implementation of a module at level lower than the level of the current module instance.

Implementations MUST return failure if any of the following is true:

mid is nil.
mbeg.mid is not mid.
mbeg.data is not empty.
mbeg.enum is not empty.
mbeg.func is not empty.
mbeg.types is not empty.

Implementations MUST modify the state as follows:

Set mbeg.mlv to 0.
Set mfin to true.
Set cbeg to nothing.
Set func to nothing.
Set item to mbeg.
Set desc to item.desc.

The `mlvl` function

Increases the current level of the module.

<UINT> mlv: Module level.
<TAGS> tags: Module level finalization flag.

The new level applies to all items declared after the instruction.

tags contains either +final or +draft. If the level is final, no changes to it and lower ones will ever be made.

Implementations MUST return failure if any of the following is true:

mlv is equal to or more than 2¹⁶.
mlv is less than mbeg.mlv.
Both +final and +draft are in tags.
Neither +final or +draft are in tags.
No +draft in tags and mfin is false.

Implementations MUST modify the state as follows:

Set cbeg to nothing.
Set func to nothing.
Set item to mbeg.
Set desc to item.desc.
Set mfin to false if +draft in tags.
Set mbeg.mlv to mlv.

The `cbeg` function

Begins a class declaration.

<NAME> name: Name of the class.
<TAGS> tags: Type of the class.
<UUID> id (optional): Identifier of the class.

If omitted, id becomes a version 5 UUID (namespace, SHA-1). The namespace UUID is the UUID of the module. The name is the name of the class (encoded in UTF-8).

If id is the nil UUID, the class will not have a descriptor. It will not have any creation functions. This is used to declare complex members for other classes.

tags can contain either +alias or +iface.

The presence of +alias in tags changes the class declaration into a class alias declaration. The aliased class is referenced by its ID.

The presence of +iface in tags changes the class declaration into an interface declaration. Interfaces must have an ID which cannot be nil.

Implementations MUST return failure if any of the following is true:

Both +alias and +iface are in tags.
There is +alias in tags and id is nil.
There is +iface in tags and id is nil.
There is an item i in mbeg.data, mbeg.enum or mbeg.func, of which i.name is equal to name.
There is a class c in mbeg.types, of which c.name is equal to name and c.cid is not equal to id.
No +alias in tags, id is not nil and there is a class c in mbeg.types, of which c.cid is equal to id and c.name is not equal to name.

Implementations MUST modify the state as follows:

Find the class c in mbeg.types, of which c.name is equal to name.
If not found, set c to a new class and insert c into mbeg.types.
If found, increase c.clv by one; otherwise set c.cid to id, c.clv to 0, c.name to name and c.tags to tags.
Set cbeg to c.
Set func to nothing.
Set item to c.
Set desc to item.desc.

The `cend` function

Explicitly ends a class declaration.

No parameters.

Implementations MUST modify the state as follows:

Set cbeg to nothing,
Set func to nothing,
Set item to mbeg.
Set desc to item.desc.

The `clvl` function

Increases the level of the current class.

<UINT> level: New level.

Implementations MUST return failure if any of the following is true:

cbeg is nothing.
cbeg.tags contains +alias.
level is equal to or more than 2¹⁶.
level is less than or equal to cbeg.clv.
For each data member d in cbeg.data: d.cid is less than or equal to level.

Implementations MUST modify the state as follows:

Set cbeg.clv to level.
Set func to nothing.
Set item to cbeg.
Set desc to item.desc.

The `creg` function

Assigns a register type to a class.

<NAME> type: Register type.

This instruction declares that the class is a register class. Register classes are those for which exists a conversion between an object stored in memory and a register type stored in CPU registers.

reg1 = regf / regs / regu
regu = %s"u" (  "8" / "16" / "32" /  "64" )
regs = %s"s" (  "8" / "16" / "32" /  "64" )
regf = %s"f" ( "16" / "32" / "64" / "128" )

The first character of <reg1> is the class of a register. Remaining characters specify N - the width of the register.

u: integer in the range [0, 2^N-1]
s: integer in the range [-2^N-1, 2^N-1-1]
f: real number representable by the IEEE 754 binaryN format

Such classes implicitly declare the following read-write function members:

_save: Saves a value to memory.; Parameter: Register type; the value.; Returns: Nothing.
_load: Loads a value from memory.; Returns: Register type; the value.

Additionally, for integers:

_add: Loads, adds a value, saves.; Parameter: Register type; addend.; Returns: Boolean; value of the carry flag.
_sub: Loads, subtracts a value, saves.; Parameter: Register type; subtrahent.; Returns: Boolean; value of the carry flag.
_mul: Loads, multiplies by a value, saves.; Parameter: Register type; multiplier.; Returns: Register type; high bits of the result.
_div: Loads, divides by a value, saves.; Parameter: Register type; divisor.; Returns: Register type; remainder.
_neg: Only for signed integers.; Loads, negates the value, saves.; Returns: Register type; the saved value.
_and: Loads, does a bitwise AND, saves.; Parameter: Register type; bit mask.; Returns: Register type; the saved value.
_xor: Loads, does a bitwise XOR, saves.; Parameter: Register type; bit mask.; Returns: Register type; the saved value.
_inv: Loads, inverts all bits, saves.; Returns: Register type; the saved value.
_set: Loads, sets specified bits (bitwise OR), saves.; Parameter: Register type; bit mask.; Returns: Register type; the saved value.
_clr: Loads, clears specified bits, saves.; Parameter: Register type; bit mask.; Returns: Register type; the saved value.

Implementations MUST return failure if any of the following is true:

type does not match <reg1>.
cbeg is nothing.
cbeg.tags contains +alias.
cbeg.creg is non-empty.

Implementations MUST modify the state as follows:

Set cbeg.creg to type.

The `data` function

Declares the next data member in memory order.

<TYPE> type: Type of the object.
<NAME> name: Name of the object.
<UINT> sid (optional): Symbol identifier.
<ALEN> array (optional): Length of the array.
<VREG> value (optional): Default value of an object.
<UINT> align (optional): Memory alignment.
<TAGS> tags (optional): Tags.

Data members are laid out in memory in the order they are declared.

In the case of handles, the access rights are bound to an instance. If there are two handles to the same object, only one of them needs to have rights to the object.

If sid is omitted: if cbeg is not nothing, sid is computed over the concatenation of: cbeg.name, one U+0024 DOLLAR SIGN, name; otherwise, sid must be omitted as there is no symbol.

An array is valid if, and only if:

array.max is equal to or more than 2³²,
array.min is equal to or more than 2³²,
array.min is more than array.max.

Also, array.var MUST reference a previously defined member. This member MUST NOT be tagged as read-only. It holds the current length of the array.

The range in array does not specify how much memory is allocated. The values are used in calculation of the minimum and maximum lengths of a class instance, which is part of a class descriptor. Offsets of all subsequent members are calculated at runtime.

The following tags are recognized in tags:

+ro: Member is read-only.
+iface: Member is an object of an implemented interface.

align is an override of the default memory address alignment requirement of the member. Padding is inserted before the member if it is not properly aligned. Authors must consider alignment and padding when designing classes.

An align is valid if, and only if:

align is equal to or more than 2³²,
align is not a power of 2. Implementations MUST return failure if any of the following is true:

array is invalid.
align is invalid.

If cbeg is nothing:

For each data member d in mbeg.data: d.sid is equal to sid or d.name is equal to name or: for each data member u while following d.next: u.name is equal to name.
For each function f in mbeg.func: f.name is equal to name or f.sid is equal to sid.
For each named value v in mbeg.enum: v.name is equal to name.

Otherwise, if cbeg is not nothing:

cbeg.tags contains +alias.
sid is not omitted.
For each data member d in cbeg.data: d.name is equal to name or: for each data member u while following d.next: u.name is equal to name.
For each function f in cbeg.func: f.name is equal to name.
For each named value v in cbeg.enum: v.name is equal to name.

Additionaly, these tests MUST be done once in the dereference phase:

if an array and array.var is not an integer register class,
if there is a value and the type of the member is not a register class,
if there is a value and it is out of range or has incorrect syntax.

Implementations MUST modify the state as follows:

Create a new data member d.
Set d.type to type, d.tags to tags, d.array to array, d.align to align, d.value to value, d.mlv to mbeg.mlv, d.sid to sid, d.name to name.
If cbeg is not nothing, set d.clv to cbeg.clv.
Append d to mbeg.data if cbeg is nothing; otherwise, append d to cbeg.data.
Set func to nothing.
Set item to d.
Set desc to item.desc.

The `dalt` function

Declares an alternate member at the current memory position.

<TYPE> type: Type of the object.
<NAME> name: Name of the object.
<ALEN> array (optional): Length of the array.
<UINT> align (optional): Memory alignment.
<TAGS> tags (optional): Tags.

The alignment of the union is the widest alignment of all its members.

The only recognized tag is +nodesc, which tell the processor to keep the description association with the current item.

If cbeg is nothing, let data be mbeg.data; otherwise let data be cbeg.data. Implementations MUST return failure if any of the following is true:

item is not a data member.
cbeg is not nothing and cbeg.tags contains +alias.
array is invalid.
align is invalid.
For each data member d in data: d.name is equal to name or: for each data member u while following d.next: u.name is equal to name.

Additionaly, these tests MUST be done once in the dereference phase:

if an array and array.var is not an integer register class,
if there is a value and the type of the member is not a register class,
if there is a value and it is out of range or has incorrect syntax.

Implementations MUST modify the state as follows:

Create a new data member d.
Set d.type to type, d.array to array, d.align to align, d.value to value, d.tags to tags, d.mlv to mbeg.mlv, d.name to name.
Set d.next to item.
Set item to d.
If tags does not contain +nodesc, set desc to d.desc.

The `enum` function

Declares a named value.

<NAME> name: Name of the value.
<VREG> value: Named value.

The `func` function

Begins declaration of a normal function member.

<NAME> name: Name of the function.
<UINT> sid (optional): Symbol identifier.
<TAGS> tags (optional): Tags.

If sid is omitted: if cbeg is not nothing, sid is computed over the concatenation of: cbeg.name, one U+0024 DOLLAR SIGN, name; otherwise, it is computed over just name.

The following tags are recognized in tags:

+ro: Function does not write to the class instance.
+mod: Function requires access to the module instance.
+krn: Function requires access to the kernel instance.
+var: Function expects more parameters than declared.

Implementations MUST return failure if any of the following is true:

If cbeg is nothing:

For each data member d in mbeg.data: d.name is equal to name or d.sid is equal to sid.
For each function f in mbeg.func: f.name is equal to name or f.sid is equal to sid.
For each named value v in mbeg.enum: v.name is equal to name.

Otherwise, if cbeg is not nothing:

cbeg.tags contains +alias.
For each data member d in cbeg.data: d.name is equal to name.
For each function f in cbeg.func: f.name is equal to name or f.sid is equal to sid.
For each named value v in cbeg.enum: v.name is equal to name.

Implementations MUST modify the state as follows:

Create a new function member f.
Set f.tags to tags, f.mlv to mbeg.mlv, f.sid to sid, f.name to name.
If cbeg is not nothing, set f.clv to cbeg.clv.
Insert f into mbeg.func if cbeg is nothing; otherwise, insert f to cbeg.func.
Set func to f.
Set item to f.
Set desc to item.desc.

The `fret` function

Declares the type of the return value of the current function.

<TYPE> type: Type of the value.

If the function does not return a value, then the document simply does not declare any return value.

Implementations MUST return failure if any of the following is true:

func is nothing.
func.rval is not nothing.
func.tags contains +init.

Implementations MUST modify the state as follows:

Create a new data member r.
Set r.type to type.
Set func.rval to r.
Set item to r.
Set desc to item.desc.

The `farg` function

Declares the next in-order parameter to the current function.

<TYPE> type_in: Input type of the parameter.
<TYPE> type_out (optional): Output type of the parameter.
<NAME> name: Name of the parameter.

The type of a function parameter is one of:

an object passed by value of length up to 128 octets,
an object passed by handle (by memory reference),
an object passed by reference to a handle (bidirectional handle),
a reference to an instance of a register class that is guaranteed to be modified only by the function.

Objects passed by value are specified by simply writing a class reference.

.farg module.class:0 by_value

Objects passed by handle are written by specifying the handle.

.farg read<module.class:0> by_handle1 ; read-only  access
.farg rdwr<module.class:0> by_handle2 ; read-write access

Objects passed by a bidirectional handle (one that gives access to the function and back to the caller) are written as two handles.

.farg none<module.class:0> rdwr<module.class:0> bidi_handle1
.farg rdwr<module.class:0> rdwr<module.class:1> bidi_handle2

The bidi_handle1 parameter in the example is a reference to a handle. The function is not given any access rights to the refrenced memory. Upon return, the handle contains an address to an instance of module.class at level 0 and the caller receives read-write access to this object.

The bidi_handle2 parameter in the example is a reference to a handle. The function is given read-write access rights to an instance of module.class at level 0. Upon return, the handle contains an address to an instance of module.class at level 1 and the caller receives read-write access to this object.

The last category is written as two class references. The two references MUST reference a register class.

.farg int.u8 int.u8 u8_ref

Their primary use is returning a small object in a situation when passing a buffer by handle would expose too much data to the function. This is also faster than passing by handle (no handle processing).

The referenced object may be safely copied before the call is made and then copied back to the original buffer upon returning back.

Implementations MUST return failure if any of the following is true:

func is nothing.
type_in is a handle, type_out was not omitted and is not a handle.
type_in is a class reference, type_out was not omitted and is not a class reference.

Additionaly, these tests MUST be done once in the dereference phase:

if type_in and type_out are class references and the referenced types are not a register classes.

Implementations MUST modify the state as follows:

Create a new function parameter p.
Set p.name to name, p.type_in to type_in, p.type_out to type_out.
Append p to func.params.
Set item to p.
Set desc to item.desc.

The `init` function

Begins declaration of a class constructor.

<NAME> name: Name of the constructor.
<UINT> sid_init (optional): Symbol identifier for the initializer.
<UINT> sid_create (optional): Symbol identifier for the creator.
<TAGS> tags (optional): Tags.

This function declares two function members: name_init and name_create.

The name_init function is a normal member function which takes the defined parameters as arguments and returns a status boolean.

The name_create function is a static member function which takes kernel-defined parameters first and then the defined parameters as arguments. The function returns a read-write handle to an instance of the class. It always requires access to the module context (to the class descriptor).

Compute name_init as follows:

Let n be an empty string.
Append init to n.
If name is equal to default, return n.
Append one U+0024 DOLLAR SIGN to n.
Append name to n.
Return n.

Compute name_create as follows:

Let n be an empty string.
Append create to n.
If name is equal to default, return n.
Append one U+0024 DOLLAR SIGN to n.
Append name to n.
Return n.

If omitted, sid_init is computed over the concatenation of: cbeg.name, one U+0024 DOLLAR SIGN, name_init.

If omitted, sid_create is computed over the concatenation of: cbeg.name, one U+0024 DOLLAR SIGN, name_create.

The following tags are recognized in tags:

+mod: Function requires access to the module instance.
+krn: Function requires access to the kernel instance.

By convention, destructors SHOULD be called fini. Prototype is defined by the kernel's object interface.

Implementations MUST return failure if any of the following is true:

cbeg is nothing.
cbeg.tags contains +alias.
For each function f in cbeg.func: f.sid is equal to sid_init or f.sid is equal to sid_create.

Implementations MUST modify the state as follows:

Create a new function member create.
Set create.tags to tags, create.mlv to mbeg.mlv, create.clv to cbeg.clv, create.sid to sid_create, create.name to name_create.
Add +create to create.tags.
Insert create into cbeg.func.
Create a new function member init.
Set init.tags to tags, init.mlv to mbeg.mlv, init.clv to cbeg.clv, init.sid to sid_init, init.name to name_init.
Add +init to init.tags.
Insert init into cbeg.func.
Set func to init.
Set item to init.
Set desc to item.desc.

The `evnt` function

Begins declaration of an event.

<NAME> name: Name of the event.
<UINT> sid_install (optional): Symbol identifier for a handler installer.
<UINT> sid_uninstall (optional): Symbol identifier for a handler uninstaller.

Compute name_func as follows:

Let n be an empty string.
Append name to n.
Append one U+0024 DOLLAR SIGN to n.
Append func to n.
Return n.

Compute name_uninstall as follows:

Let n be an empty string.
Append name to n.
Append one U+0024 DOLLAR SIGN to n.
Append uninstall to n.
Return n.

Compute name_uninstall as follows:

Let n be an empty string.
Append name to n.
Append one U+0024 DOLLAR SIGN to n.
Append uninstall to n.
Return n.

If omitted, sid_install is computed over: if cbeg is nothing, name_install; otherwise the concatenation of: cbeg.name, one U+0024 DOLLAR SIGN, name_install.

If omitted, sid_uninstall is computed over: if cbeg is nothing, name_uninstall; otherwise the concatenation of: cbeg.name, one U+0024 DOLLAR SIGN, name_uninstall.

The `mesg` function

Begins declaration of a message function.

<NAME> name: Name of the message.
<UINT> sid (optional): Symbol identifier.

Message functions always return a human-readable message.

The `impl` function

Declares an implementation of a function prototype.

<NAME> name: Name of the function.
<IREF> type: Reference to the function prototype.
<UINT> sid (optional): Symbol identifier.
<TAGS> tags (optional): Tags.

File Format URI

File Format URI of KMDL documents is rd://74RDM3TULLIOIPQ6V2GC3EZ3/2020/KMDL#Document.

Internet Media Type

Media type of KMDL documents is text/prs.kueea.kmdl.

The charset parameter MUST be included with the value UTF-8.

DRAFT: Kueea Module Declaration Language

Keywords

Overview

Syntax

Comments

Instructions

Item descriptions

Line indentation

ABNF (formal syntax)

Items

Module

Class

Data member

Array length

Function member

Function parameter

Symbol identifiers

Processor

Shared state

Loading algorithm

Line parser

The first line

Other lines

Instruction parser

Instruction parameters

Universally Unique Identifier

Unsigned integer

Tags

Register value

Object type

Item reference

Name

Array length

Processor functions

The text function

The load function

The mbeg function

The mlvl function

The cbeg function

The cend function

The clvl function

The creg function

The data function

The dalt function

The enum function

The func function

The fret function

The farg function

The init function

The evnt function

The mesg function

The impl function

File Format URI

Internet Media Type

The `text` function

The `load` function

The `mbeg` function

The `mlvl` function

The `cbeg` function

The `cend` function

The `clvl` function

The `creg` function

The `data` function

The `dalt` function

The `enum` function

The `func` function

The `fret` function

The `farg` function

The `init` function

The `evnt` function

The `mesg` function

The `impl` function