eYAML - hpgDesigns/hpgdesigns-dev.io GitHub Wiki

eYAML (ENIGMA's extended/easy YAML) is a simplified extension to YAML. It is a structured textual format for properties, settings, extensions, dependencies, etc., similar in purpose to XML. It is designed to keep the core elements of YAML while eliminating the more complex elements, thus making parsing the format much easier. YAML was chosen over XML for its simplicity, human-readability, small filesize, ease of parsing, and general prettiness compared to the ugly and redundant tags of XML.

eYAML files must use the UTF-8 character set (this only affects files with special characters).

ENIGMA makes use of the format to store various properties, settings, configurations, module definitions, extensions, and dependencies.

• Compilers/ are defined by one eYAML file per platform compiler.
• About.ey files define an available API or System.
• Extensions/ are defined by them.
• EGM format uses it to format resource properties.

On the simplest level, and the most common case seen throughout ENIGMA, the 'structure' is minimal, yielding a basic list of `key: value` pairs, not unlike a Properties file. In fact, for such cases, it is extremely common for a Properties parser to be used in place of an eYAML parser, and the EGM format heavily relies on this fact.

The specification for the format is unclear or informal because the existing parsers do not follow any specifications attempted to be written for them, and no specifications have been written to reflect the parsers. Generally, they begin with the `%e-yaml` indicator on its own line, optionally followed by a start of document `---` on its own line. From there, the remainder of the document is broken into nodes which are structured by indentation, which is usually denoted by the space character, and not the tab character (the tab character is forbidden in YAML for indentation). In this sense, the format resembles that of the Python language.

eYAML conserves the idea of Maps and Sequences from YAML, however the simplified parsers tend to treat them interchangeably, meaning that a bunch of children to a node would be interpreted depending on how the program decides to use them. A map is denoted by a `key: value` pair, while a sequence is usually denoted by either a hyphen preceding the node `- node` or using brackets around the elements, delimited by commas: `[1,2,3,4]`. Notice that a map allows the value to appear on a newline with indentation exceeding the key, in which case the value would be either its own mapping or sequence of nodes, each as a child to the parent key.

The first level of indentation (or no indentation) are root nodes. They should all be the same type of node (e.g. all maps or all sequences - not to be used interchangeably), but again, the 'type' essentially gets erased by current parsers. Children nodes are on lines following a parent node but preceding any siblings to the parent node, and are indented more than the parent node. Children may themselves have children, or may be 'leaf' nodes, creating a genuine tree structure, not unlike a fully expanded graphical UI tree.