About.ey

From ENIGMA
Jump to navigation Jump to search

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.