EEF modified by Hugh Greene

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

ENIGMA's Extensible Enumeration Format (EEF) is a format created
to allow plain-text storage of a variety of data in a linear fashion,
without compromising the ability to extend the format later without
invalidating outdated readers.

Specification

Structure

The format is based on newlines with
length-prefixing. Information stored in
this format is organized into Data Blocks,
which assign definite length patterns.

Comments

EEF comments are defined to commence with any single consistent
combination of the following symbols: # ; % / ', and to be
terminated by the end of the line. A file defines what comment
combination it will be using by starting the file with those symbols as
the very first symbols in the file, or if none are specified, it is
assumed the file has no comments. The remainder of the file must
consistently use that comment combination. This is to allow for the
storage of multi-lingual code-snippets without alienating generic EEF
readers as a parse option.

A valid comment symbol combination can be as simple as ; (as in
Assembly), # (as in bash) or // (as in C), or can be as complex as
/%#%/ (for the express purpose of not conflicting with the
aforementioned languages), however, remember, in the latter case, the
comment begins with the full /%#%/ and ends with a newline. Multi-line
comments are not available - instead, simply precede each comment line
with the comment sequence.

As of version one of the EEF specification, only one comment symbol
pattern can be defined per file. This restriction may be revised later.

After the first non-comment line in the file, no further lines can be
left entirely commented unless said lines would be otherwise blank.
Hence, these lines will be exclusively attribute lines: a comment cannot
appear as the complete line anywhere that a reader would expect to find
a Data Block indicator. This is done to promote ease of skipping unknown
Data Blocks.

Quotes

The EEF specification defines quotes for use in Small
Attribute listing. The double quote
symbol (") or single quote symbol (') may be used except where the
latter is defined as a Comment pattern. The
escape sequences \\, \" and \' are defined; all others are to be
handled application-side.

Indentation

Indentation is optional, and should be done as-desired to make the
format visually pleasing and computationally simple. Generally, where
unimportant, these indentation characters will be discarded by readers.
Many indentation characters are supported, including tab ('\t'), space
(' '), and any combination thereof.

Data Blocks

Similar to binary data chunks in the PNG specification, EEF Data Blocks
are multi-line sections of text defined to contain at most one of the
following:

A set of {N} subsequent Data Entries
A set of [N] Attribute Lines.

Data Block Indicator

These blocks are set off by a single line which names the Data Type. The
format for a data block indicator is as follows:

Type`` ``Name(plural){Number of containedData`` ``Blocks}

The data block indicator may appear on its own at the root of the
file or after any Data Entry
Indicators

Data Entries

Data entries are typically members of data blocks, but are permitted to
appear at the root of the file if no higher level is
required. Data entries define an instance of their Data

Data Entry Indicator

Data entry indicators

Type`` ``Name(*primary`` ``id):Small`` ``Attributesor*[Number of additionalLine`` ``Attributes]**

Attributes

EEF specifies two methods of associating attributes with each Data
Block. Small data is typically stored in Small
Attributes, while larger snippets of data
are better suited to storage in Line
Attributes

Small Attributes

Small Attributes are those which appear after a Data Entry
Indicator; they can be completely
scalar, or can be given a value using a pair of parentheses. For
example, take this code:

Examples{1}
Example: "yellow" Shape(Round)

Our Example entry is declared with two attributes. The first is the
valueless attribute "Yellow", which speaks for itself. The second is a
Shape attribute, which has been set to the value "Round". Quotes may
appear around any attribute, and are completely optional except where
otherwise ambiguous (for instance, the attribute "lime green" must be
quoted even though "yellow" may be left alone). Since attribute values
are surrounded by parentheses, quotes are generally unnecessary in them.

Line Attributes

Line Attributes follow any Data Entries
which define a non-zero count inside a pair of square brackets[]. Line
Attributes are Attributes which are given an entire line to themselves.
They may, semantically, instead be a single very large attribute which
spans multiple lines, but this is up to the application to determine;
this spec only mandates that the number of lines used is given up front
for the purposes of skipping or isolating.

Type Name

The name of the members of the Data Block.
When used in the Data Block
Indicator, it should be pluralized.
When used in a Data Entry Indicator,
it should be singular. The difference between the singular and plural
form shall be implementation-specific. By convention, the reader must
warn if the plural string doesn't match the singular string using
according to some regular expression generated from the singular string.
This generated regular expression can be anything from
/singulare?s?/ to /.*/. Since this requirement is purely
conventional, no check must actually be made by the implementation for
the latter expression.

More advanced plurality checks can be accomplished loosely by starting
with the expression /singulare?s?/, and applying any expressions
in the following table to the singular
string:

Find	Replace with	To support
`y`	`[yi]`	Property, Entry, Assembly...
`f`	`[fv]`	Leaf, Hoof, Elf, Self, Knife...
`ex`	`(ex\\|ic)`	Vertex, Index
`ix`	`(ix\\|ic)`	Matrix, Appendix
`ous`	`(ous\\|ic)`	Mouse, Louse
`oo`	`(oo\\|ee)`	Goose, Tooth, Feet
`on$`	`(on\\|a)`	Criterion, Phenomenon
`um$`	`(um\\|a)`	Bacterium, Curriculum, Medium, Datum
`is$`	`(is)?`	Axis, Analysis, Thesis
`us$`	`(us\\|i\\|.ra)`	Cactus, Fungus, Octopus, Alumnus, Succubus... Genus, Corpus, Viscus
`an$`	`[ae]n`	Man, Woman
`$`	`(r?en)?`	Children, Oxen
`$`	`x?`	Beau, Bureau, Tableau

There only plural not covered by the entirety of the above table is
"person" -> "people".

Primary ID

Each Data Entry should give itself a name or
ID, or some primary data affiliated with that particular entry. It does
not necessarily have to be unique, or even scalar. The primary ID is
simply a place to put the most important information about the entry.

Root

Any line which lies outside the scope of lines claimed by any of the
above is considered to be at the root of the file.

Length-prefixing

In other extensible formats, such as PNG, length-prefixed chunks and
chunk-IDs (or similar devices) are used to allow various readers to
ignore sets of data they are incapable of reading. In EEF, different
brackets are used to indicate various lengths.

Curly braces {} are used to indicate a number of repetitions of
Data Blocks. The data that is repeated
can be multiple lines, and the number of additional lines can vary.
See the next point.
Square brackets [] are used in Data
Entries to indicate that a fixed number
of lines follows which describe or belong to the current data block.

Example File

## Sample EEF file
Items{3} ## The {} tells us we'll be reading 3 fields of varying size before this block is over.
  Item("Sword"): "Weapon" Damage(4) "Magic" Text[2] ## Note the use of [] to indicate lines we can skip if we don't know what this is.
    A magical sword
    Given to you by an elf or something.
  Item("Pen"): "Weapon" Damage(.5) Text[2]
    An ordinary pen
    Just a regular pen. Doesn't do much damage, but it's still mightier than the sword, right?
  Item("Apple"): "Food" Health(10) Text[2]
    A delicious apple
    Probably came from a tree, or something. Who knows. Restores 10HP and doesn't afraid of anything.
Collectables{1} ## Now that all three Items have been defined, we can end the file or declare new. We'll do the latter.
  Collectable("Watch fob"): Text[2]
    A beautiful golden watch fob
    It has absolutely no use.

Recent changes to EEF