EYAML modified by Hugh Greene

Hugh Greene — Fri, 20 Jan 2023 12:15:26 -0000

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).

Uses

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.

Similarity to 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.

Specification

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.

Maps and Lists

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.

Nodes and Trees

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.

Recent changes to EYAML

EYAML modified by Hugh Greene

Uses

Similarity to Properties

Specification

Maps and Lists

Nodes and Trees