About.ey

About.ey is an eYAML
specifier file that describes an available API or System to the
IDE and to ENIGMA.
These files are a part of the Module
hierarchy. Remember that eYAML files must
use the UTF-8 character set (this only affects files with special
characters).

Format

The file layout is as follows:

 %e-yaml
 ---

 Name: The human-readable name of the system.
 Identifier: The folder under which it can be accessed.
 Depends: A parent key with children naming relevant systems on which this API depends. (See below for "relevant systems")
 Represents: A parent key with children naming relevant systems for which it is the default. (See below for "relevant systems")
 Description: A human-readable description of this system (especially when compared to others).
 Author: The individual(s) responsible for the system.

 Build-Platforms: In Platforms/, this lists the operating systems or devices -on- which the API will function.

 ## The following is for use in Platforms/ subdirectories only. (See below)
 Links: A list of libraries and other linkages the system requires to function.

Lists shall be comma delimited.

Relevant systems

When an About file specifies a relevant system, it names the category of
said system as the key. The value is then the identifier of that system.
Note that it is also possible to have multiple API system categories
specified for a single Depends/Represents. For example, consider DirectX
and DirectSound; we want both to depend on Windows, as that is the only
platform for which ENIGMA presently compiles that supports them, but we
want DirectSound to default itself for DirectX while OpenAL would be the
default for OpenGL, which also works for Windows. As such, our codes
would look something like the following:

% DirectX/About.ey
---
Depends:
  Platforms: Windows
Represents:
  Platforms: Windows

% DirectSound/About.ey
---
Depends:
  Platforms: Windows
Represents:
  Graphics: DirectX

% OpenGL/About.ey
---

Depends:
  Platforms: Windows, Linux, MacOSX
Represents:
  Platforms: Linux, MacOSX


% OpenAL/About.ey
---
Depends:
  Platforms: Windows, Linux, MacOSX
Represents:
  Graphics: OpenGL

To demonstrate multiple API system categories, we could imagine a
hypothetical About.ey:

Depends:
  Platforms: Windows
  Graphics: OpenGL, DirectX
Represents:
  Platforms: Windows
  Graphics: OpenGL, DirectX

Additionally, the following keywords can be used as values of
Represents sub-keys:

• Keyword All, indicating that all systems fulfill the
  requirement. Using this keyword will place the system as the default
  for any system under that category which is not claimed specifically
  in another file. In other words, it will be the default for this
  system as long as another file does not specifically list it by
  name.
• Keyword None, indicating that it should never be chosen as the
  default in its setting. This is intended for use with systems which
  are often an option, but never a default.

That said, a practical implementation could determine which system to
use as default by iterating through them and counting up the matches;
the "All" keyword would count as .5, while a full match would count as
1.0.

These keywords are not useful under the Depends: setting, and therefore
are not supported. Depending on nothing is implied if no other
depenedency is given, and depending on everything is meaningless.

For more information, consult the Module
hierarchy.