POM Language Specification, v. 0.1.0

Introduction

POM is a “markup” language, primarily intended for software configuration, and designed to be easy to parse and use. The POM specification is quite strict, to avoid cases where dubious files can be accepted by some parsers while being rejected by others. POM files should use the .pom file extension to identify themselves.

Every file describes a configuration, which is a mapping from keys to values. A key is a string consisting of components separated by dots (.). A value is a string whose interpretation is entirely decided by the application. Notably there is no distinction in POM’s syntax between, say, the number 5 and the string 5. A configuration, such as the one obtained from the POM file

[ingredients.sugar]
amount = 50 g
type = brown

[ingredients.flour]
amount = 100 g
type = all-purpose

[baking]
temperature = 150 °C
time = 35 min

can either be seen as a simple mapping from keys to values:

Key	Value
ingredients.sugar.amount	50 g
ingredients.sugar.type	brown
ingredients.flour.amount	100 g
ingredients.flour.type	all-purpose
baking.temperature	150 °C
baking.time	35 min

or a tree of keys, with a value associated to each leaf node:

Error handling

All error conditions are described in this specification. A compliant POM parser should not reject any file in any other case, outside of exceptional circumstances such as running out of memory. When an error occurs, it should be reported, ideally with information about the file name and line number, and the file must be entirely rejected (i.e. parsers must not attempt to preserve only the correct parts of an erroneous file). Warnings may also be issued according to the judgment of the library author.

Text encoding

All POM files are encoded using UTF-8. Both LF and CRLF line endings may be used (see below). If invalid UTF-8 is encountered, including overlong sequences and UTF-16 surrogate halves (U+D800-DFFF), an error occurs.

Valid keys/values

Keys in a POM file may contain the following characters

The ASCII characters a–z, A–Z, 0–9, as well as each of ./-+*_.
Any non-ASCII code point (U+0080–10FFFF).

A non-empty string containing only these characters is a valid key if and only if it does not start or end with a dot and does not contain two dots in a row (..).

Any string of non-zero Unicode code points (U+0001–U+10FFFF) is a valid value.

Parsing

If a “byte order mark” of EF BB BF appears at the start of the file, it is ignored. Every carriage return character (U+000D) which immediately precedes a line feed (U+000A) is deleted. Then, if any control characters in the range U+0000 to U+001F other than the line feed and horizontal tab (U+0009) are present in the file, an error occurs.

The current-section is a string variable which should be maintained during parsing. It is initally equal to the empty string.

An accepted-space is either a space (U+0020) or horizontal tab (U+0009) character.

Parsing now proceeds line-by-line, with lines being delimited by line feed characters. For each line:

Any accepted-spaces that appear at the start of the line are removed.
If the line begins with #%disable warnings or #%enable warnings, warnings should be disabled/enabled if any are implemented.
If the line is empty or begins with #, parsing proceeds to the next line.
If the line begins with [, it is interpreted as a section header. In this case:
1. If the line does not end with ] optionally succeeded by any number of accepted-spaces, an error occurs.
2. The current-section is set to the text in between the initial [ and final ] (white space between the [ and ] is not trimmed).
3. If the new current-section is not empty and not a valid key (see above), an error occurs.
Otherwise, the line is now interpreted as a key-value assignment. In this case:
1. If the line does not contain an equal sign (=), an error occurs.
2. The relative-key is the text preceding the =, not including any space or horizontal tab characters immediately before the =.
3. If the relative-key is not a valid key (see above), an error occurs.
4. Let c be the first character after the = and any succeeding accepted-spaces.
5. If c is one of "'` (U+0022 QUOTATION MARK, U+0027 APOSTROPHE, U+0060 GRAVE ACCENT), the value is quoted, and spans from the first character after c to the next unescaped instance of c in the file (which may be on a different line). In this case,
  1. Escape sequences are processed as described below.
  2. Following the closing instance of c, there must be a line feed, optionally preceded by any number of accepted-spaces; otherwise an error occurs.
6. Otherwise, accepted-spaces at the end of the line are removed; then, the value is the text starting from c and ending at the next line feed.
7. If the value is not a valid value (see above), an error occurs.
8. The key is equal to the relative-key if the current-section is empty; otherwise, it is equal to the concatenation of current-section, a dot, and the relative-key.
9. The key is assigned to the value.

Escape sequences

POM defines the following escape sequences, which may appear in quoted values. If a backslash character occurs in a quoted value but does not form a defined escape sequence, an error occurs.

Escape sequence	Value
`\n`	Line feed (U+000A)
`\r`	Carriage return (U+000D)
`\t`	Horizontal tab (U+0009)
`\\`	Literal `\` (U+005C)
`\"`	Literal `"` (U+0022)
`\'`	Literal `'` (U+0027)
\`	Literal ` (U+0060)
`\,`	Literal `\,` (U+005C U+002C)
`\x`NM	ASCII character with code NM, interpreted as hexadecimal (must be in the range 01–7F).
`\u{`digits`}`	Unicode code point digits, interpreted as hexidecimal digits must be 1–6 characters long, and may contain leading zeros, but must not be zero.

Lists

Although POM does not have a way of specially designating a value as being a list, there is a recommended syntax for encoding them. Specifically, a value can be treated as a list by first splitting it into comma-delimited parts (treating \, as a literal comma in a list entry), then removing any accepted-spaces surrounding list entries. List entries may be empty.

An empty string is considered to be an empty list.

If a list's order is irrelevant and it might be large or benefit from labelling its entries, a key prefix should be used instead (see the ingredients “list” in the opening example).

Examples

POM line	Entry 1	Entry 2	Entry 3
`fonts = monospace, sans-serif, serif`	`monospace`	`sans-serif`	`serif`
`files = " foo.txt, weird\,name,z "`	`foo.txt`	`weird,name`	`z`
things = `\,,,76`	`,`		`76`

Merging configurations

A configuration B can be merged into another configuration A by parsing both of them and setting the value associated with a key k to be

The value associated with k in B, if any.
Otherwise, the value associated with k in A, if any.

(Likewise, an ordered series of configurations A₁, …, A_n can be merged by merging A_n-1 into A_n, then A_n-2 into the resulting configuration, etc.)

This is useful, for example, when you want to have a global configuration for a piece of software installed on a multi-user machine where individual settings can be overriden by each user (in this case, the user configuration would be merged into the global configuration).

Extensions

If needed for a particular domain, an parser may accept an extended form of the POM syntax. Ideally, extensions should use lines beginning with invalid key characters (e.g. !&%) so that there is no ambiguity, and the file cannot be interpreted without the extension.

Schemas

A schema is a POM file that describes how other POM files should be formatted (i.e. what keys they should include, and what values they can be associated with). A configuration can be said to follow a schema when it obeys all of the schema’s rules.

Every schema key is of the form k.rule, where k is a valid key, and rule is one of the rule names listed below.

For any valid key k the value of the rule rule is determined for k as follows:

Break k down into its n components.
For each schema key s with n components:
- Match up the components of s with the components of k.
- If all the components of s not equal to * are equal to the corresponding components of k, add s to the candidate-list.
If the candidate-list is empty, use the default value for the rule.
If the candidate-list has exactly one schema key, use the value for that key.
Otherwise select the schema key in the candidate-list with the latest first *-component (in terms of component index), preferring keys with no *, breaking ties by the latest second *-component, preferring keys with only one *, etc. Use its value for the key.

`type` rule

Default: String.

This describes what values a key is allowed to be associated with. The following types are defined:

String — accepts any value
None — accepts an unset value (special—see below)
Empty — accepts an empty value
Bool — accepts true, on, yes, false, off, no (case-sensitive).
UInt — accepts any unsigned integer that fits in 63 [sic] bits, written in decimal or 0x-prefixed hexadecimal. A leading + is permitted, but -0 is not. Only 63 bits are allowed to support languages (Java) with no 64-bit unsigned integers.
Int — accepts any (two’s complement) signed integer that fits in 64 bits, written in decimal or 0x-prefixed hexadecimal. A leading + (or, of course, -) is permitted.
Float — A floating-point number, written ordinarily (e.g. -1.234, 7., 265) or in scientific notation (e.g. 3e5, 3.E-5, -3.7e+5). A leading + (or, of course, -) is permitted.
'value' — accepts the literal value value. Note that this must be written like thing.type = "'special_string'" in the schema. Note also that value cannot contain a literal apostrophe '.
T | U, where T, U are types — accepts a value of type T or U.
Optional[T], where T is a type — equivalent to T | None.
List[T], where T is a type — accepts a list of entries of type T (see description of lists above). Nested lists are not permitted.

`allow_unknown` rule

Default: inherited from parent (i.e. if k = j.component, look up the allow_unknown rule for j), or yes if k has no parent (does not contain a dot).

This describes whether or the key k is allowed if it is not described in the schema. It must be set to either yes or no.

If a key is encountered in a configuration and the value of its allow_unknown rule is no, the configuration does not follow the schema.

`min`, `max` rules

This schema key's value sets the minimum/maximum value for the key's value. This must not be set if type does not explicitly allow numeric values (i.e. it does not contain a type Int/UInt/Float).

`maxlength` rule

The value of this rule must be a non-negative integer no greater than 2³¹−1. Specifies that the value of a key can be no longer than that number of UTF-8 bytes.

`default` rule

Sets the default value for a key.

Missing values

If there is a schema key k.type, where k does not contain any *-components, and the type does not allow unset values (None), and there is no schema key k.default, then a configuration must contain the key k to follow the schema.

Additionally, if there is a schema key j.*.k.type that does not allow unset values and no correspoding default schema key, where k does not contain any *-components, then a configuration which contains a key x matching j.* must also contain the key x.k.

API recommendations

The following functions are (lightly) recommended in any general-purpose library for parsing POM files (their exact names/signatures can be changed to fit the style of the language).

load(file: File) -> Configuration
Load a configuration from a file.
load_path(path: String) -> Configuration
Convenience function for loading by path (may be overloaded with load if language supports it).
get(conf: Configuration, key: String) -> Optional<String>
Get value associated with key, if any exists.
has(conf: Configuration, key: String) -> Bool
Returns whether key is associated with any value.
get_or_default(conf: Configuration, key: String, default: String) -> String
Get value associated with key, if any exists, returning default if not.
get_int(conf: Configuration, key: String) -> Optional<Int>
get_int_or_default(conf: Configuration, key: String, default: Int) -> Int
Get value associated with key, if any exists, and parse it as a signed 64-bit integer (returning default if the key doesn’t exist). Return an error if the key exists but its value is not a valid signed 64-bit integer.
get_uint(conf: Configuration, key: String) -> Optional<UInt>
get_uint_or_default(conf: Configuration, key: String, default: UInt) -> UInt
Get value associated with key, if any exists, and parse it as an unsigned 63-bit [sic] integer (returning default if the key doesn’t exist). Returns an error if the key exists but its value is not a valid unsigned 63-bit integer.
get_float(conf: Configuration, key: String) -> Optional<Float>
get_float_or_default(conf: Configuration, key: String, default: Float) -> Float
Get value associated with key, if any exists, and parse it as a 64-bit IEEE-754 double precision floating-point number (returning default if the key doesn’t exist). Returns an error if the key exists but its value is not a valid floating-point number.
get_bool(conf: Configuration, key: String) -> Optional<Bool>
get_bool_or_default(conf: Configuration, key: String, default: Bool) -> Bool
Get value associated with key, if any exists, and parse it as a boolean, taking true, on, yes to be true, and false, off, no to be false (case-sensitive). Returns an error if the key exists but is not one of the above values.
get_list(conf: Configuration, key: String) -> List<String>
Get value associated with key, if any exists, and parse it as a list, returning an empty list if the key isn’t present.
section(conf: Configuration, key: String) -> Configuration
Get the sub-configuration consisting of the descendants of key, i.e. keys starting with key. (with the initial key. removed) and their corresponding values. Returns an empty configuration if there are no descendants of key.
check_schema(schema: Configuration, conf: Configuration) -> Configuration (optional)
Check if configuration conf follows the schema schema (and that schema is a valid schema), returning an error with detailed information if it does not. If successful, returns a configuration with default values filled out.
merge(conf_a: Configuration, conf_b: Configuration) -> Configuration
Returns the result of merging conf_b into conf_a.

Examples

A schema for a text editor's configuration


# don't allow unknown keys by default
*.allow_unknown = no

# must put this in your config! I can't make the decision for you!
indent-using-spaces.type = Bool

show-line-numbers.type = Bool
show-line-numbers.default = on

[tab-size]
type = UInt
min = 1
default = 4

[font-size]
# allow fractional font sizes; why not!
type = Float
min = 0.5
max = 100
default = 14

[plug-in]
*.path.type = String
# everyone be nice to the Microsoft Windows
*.path.maxlength = 260
# allow arbitrary keys in plug-ins' settings
*.settings.allow_unknown = yes

[file-extensions]
C.type = List[String]
C.default = .c, .h
C++.type = List[String]
C++.default = .cpp, .hpp, .cc, .hh
C-sharp.type = List[String]
C-sharp.default = .cs

POM Language Specification, v. 0.1.0

Introduction

Error handling

Text encoding

Valid keys/values

Parsing

Escape sequences

Lists

Examples

Merging configurations

Extensions

Schemas

type rule

allow_unknown rule

min, max rules

maxlength rule

default rule

Missing values

API recommendations

Examples

A schema for a text editor's configuration

`type` rule

`allow_unknown` rule

`min`, `max` rules

`maxlength` rule

`default` rule