Meta Values and Commands

Meta values and commands are not part of the configuration content, but play a role in the configuration language. The generic EBNF syntax for meta values is defined in chapter Named Values. The difference between a meta value and command is that the first defines a value while the second performs an action. The syntax of both is the same. Meta values are part of the core language, meta commands are a standard feature.

@version: "1.0"            # Define a required language version.
@features: "regex, float"   # Require some features.

[main]
Value: 10.9

Basic Rules for Meta Values

Name: The name of a meta value starts with the at-character (@), immediately followed by a regular name as defined in Names. All other rules of regular names also apply to the names of meta values.
```
@version
@features
@parser_strict
```
Valid Names in the Core Language: A parser must support the names @version, @features, @signature and @include, even if it does not support its functionality.
```
@signature
@version
@features
@include
```
Parser Extensions: A parser can introduce custom meta values and commands. The names of such meta values and commands must start with @parser_. The name @parser_unknown is reserved for testing, and must never be used.
```
@parser_strict_check
@parser_debug
```
Value After the Name: The value of meta values and commands must be one of: text, integer or boolean. Other types are not allowed for meta values and commands.
```
@parser_strict_checks : "integer32"
@parser_debug         : Yes
```

Location: Meta value must be defined before the first section in a document.

@version: "1.0"
@features: "regex, float"

[main]
Value: 10.9

[main]
Value: 10.9

@version: "1.0"  # ERROR! Must not be defined in or after a section.

Name Conflicts: Meta values are local to individual documents, not to a whole configuration that may consists of multiple documents. Each meta value must be defined only once per document.
```
@version: "1.0"
@version: "1.0"  # ERROR! Already defined in this document.
```
Behaviour for Unknown Meta Values and Commands: If a parser reads an unknown meta value or command, it must stop with an error.
```
@unknown: "text"     # ERROR! The meta value "unknown" is not valid.
```

The Meta Value “Version”

The meta value @version sets and at the same time requires a given configuration language version. At the moment, there is only version “1.0” of the Erbsland Configuration Language, if in the future, new major version of the language introduces incompatible changes - requiring an older version will allow parsers to read a document in a compatibility mode.

Rules

Value: The @version meta value requires a text value, with the language version in the format <major>.<minor> where major and minor consist of one decimal digit. At the moment, the only valid text is 1.0.
```
@version: "1.0"
```
Behaviour: If a parser does not support or know the specified version, it must stop parsing with an Unsupported error.
```
@version: "9.7"  # ERROR! Unsupported version.
```
Define it once only: The @version meta value must be defined at most once in a configuration document. Defining it more than once is considered a syntax error.
```
@version: "1.0"
@version: "1.0"  # ERROR! Duplicate @version definition.
```

The Meta Value “Features”

The meta value @features requires a given set of features for a document. If a parser does not support one of the specified features, it must stop with an Unsupported error. By defining this meta value in a document, parsing of a document can be stopped early, with a clear error message when a feature isn’t supported on a platform.

Micro-Parsers

A micro-parser can simply accept an empty or core text and raise an error in every other case. This is perfectly acceptable behaviour.

Rules

Value: The @features meta value requires a text value, with a space separated list of feature identifiers. See Feature Identifiers for a list of all feature identifiers.
```
@features: "value-list multi-line code"
```
Behaviour: A parser must compare each feature identifier, case-insensitive, with its built-in list of supported features. If it reads an unknown or unsupported feature, it must stop with an error.
```
@features: "example"  # ERROR! Unsupported, because unknown feature.
```
Define only once: The @features meta value must be defined at most once in a configuration document. Defining it more than once is considered a syntax error.
```
@features: "value-list multi-line code"
@features: "float"   # ERROR! Duplicate @features definition.
```

Features

Feature	Coverage
core	`@version` and `@features` are part of the core language
include	`@include` is a standard feature.
signature	`@signature` is an advanced feature.

Errors

Error Code	Causes
	All errors from names, text, integer and boolean
Syntax	If a meta value or command is at the wrong place. If a meta value has the wrong type of value. If `@version` or `@features` is defined more than once.
Unsupported	Raised if the parser does not support a meta value or command.