POM homepage

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 without any third-party libraries (e.g. for looking up Unicode classes or matching regular expressions), while still being terse and legible. The POM specification is quite strict, to avoid cases where dubious files can be accepted by some parsers while being rejected by others.

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:

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

Error handling

All error conditions are described in this specification. A general-purpose POM parser should not reject a 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 parser 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 Unicode scalar value (U+0080–10FFFF, but not U+D800–U+DFFF).

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 scalar values (U+0001–10FFFF, but not U+D800–U+DFFF) 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:

1. Any accepted-spaces that appear at the start of the line are removed.
2. If the line begins with #%disable warnings or #%enable warnings, warnings should be disabled/enabled if any are implemented.
3. If the line is empty or begins with #, parsing proceeds to the next line.
4. 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 after the [ and before the ] is not trimmed).
   3. If the new current-section is not empty and not a valid key (see above), an error occurs.
5. 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 " (U+0022 QUOTATION MARK) or ` (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 no characters other than accepted-spaces until the next line feed or the end of the file; otherwise an error occurs.
   6. Otherwise, the value is unquoted. In this case,
      1. accepted-spaces at the end of the line are removed.
      2. The value is the exact text starting from c and going to the end of the line (escape sequences are not processed).
   7. If the value is not a valid value (i.e. it contains a null character), 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.

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 and \\ as a literal backslash, then removing any accepted-spaces surrounding list entries.

List entries may be empty, but if the last entry in a list is empty, it is removed (if there are two or more empty entries at the end of a list, only one is removed). As a consequence, 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

The following lines describe 3-entry lists.

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

1. The value associated with k in B, if any.
2. 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₂ into A₁, then A₃ 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).

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.

POM’s schema format is not powerful to enforce all possible restrictions; some will have to be enforced by the application.

Every schema key must be 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 for k is determined as follows:

• Break k down into its n components.
• For each schema key s.rule where s has n components:
  • Match up the components of s with the components of k.
  • If every component of s is equal to * or the corresponding component of k, add s.rule 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 of that schema 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.

Example

Given the following schema:

*.*.id.type = Int
vehicle.*.id.type = UInt
*.truck.id.type = Float
vehicle.car.id.type = String

The value of the type rule for vehicle.car.id is String, for vehicle.truck.id is UInt, for my.truck.id is Float, for my.car.id is Int, and for my.nephews.car.id is Any (no schema key matches, so the default is used).

type rule

Default: Any.

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

• Any or String — accepts any value
• None — accepts an unset value (special—see below)
• Empty — accepts an empty value (equivalent to '')
• Bool — accepts true, on, yes, false, off, no (case- and white space- sensitive).
• UInt — accepts any unsigned integer strictly less than 2⁵³, written in decimal or 0x or 0X-prefixed hexadecimal. A leading + is permitted, but -0 is not. Leading zeroes are not permitted for decimal integers. White space around the integer is not permitted. Only 53 bits are allowed to support languages (JavaScript) with a double type, but no 64-bit integer type.
• Int — accepts any signed integer whose absolute value is strictly less than 2⁵³, written in decimal or 0x or 0X-prefixed hexadecimal. Leading zeroes are not permitted for decimal integers. White space around the integer is not permitted. A leading + (or, of course, -) is permitted.
• Float — A floating-point number, written in ordinary decimal (e.g. -1.234, 7., 265) or in C-like scientific notation (e.g. 3e5, 3.E-5, -3.7e+005). Excessive leading zeroes are not permitted (0.0 is allowed, but not 00.0). Values which overflow to ±∞ are allowed (e.g. 1e999), but NaN and explicit inf/Infinity are not. White space around the number is not permitted. The decimal point (if one is present) must be preceded and succeeded by digits. A leading + (or, of course, -) is permitted.
• 'value' — accepts the literal value value. 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.

A type may optionally have accepted-spaces on either side; this does not change its meaning.

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, and it has no matching type, maxlength, or default rule, the configuration does not follow the schema.

min, max rules

This schema key’s value must be a valid Float as described above. It sets the minimum/maximum value for configuration keys’ values. It only applies if the configuration key’s value can be parsed as a Float.

maxlength rule

This schema key’s value must be a positive integer no greater than 2³¹−1, written in decimal with no leading sign. It 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 containing a key x matching j.* must also contain the key x.k.

Extensions

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

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_string(string: String) -> Configuration
  Load a configuration from a string (may be overloaded with load if language supports it).
• load_path(path: String) -> Configuration
  Convenience function for loading by path.
• print(conf: Configuration)
  Print key = value on a separate line for each key in conf, sorted alphabetically by key. The value format doesn’t need to match POM’s format exactly, since this function should only be used for debugging anyways.
• has(conf: Configuration, key: String) -> Bool
  Returns whether key is associated with any value.
• keys(conf: Configuration) -> List<String>
  Returns a list of all unique first components of keys in the configuration, in an arbitrary order.
• all_values(conf: Configuration) -> List<Pair<String, String>>
  Returns a list of all defined keys in the configuration and their values, in an arbitrary order.
• location(conf: Configuration, key: String) -> Optional<Location>
  Location of the definition of key in the configuration (file and line number). Useful for reporting invalid values when the format of valid values can’t be described by a schema type. If a key k isn’t given a value in the configuration, but a key of the form k.j is, then the location of the definition of an arbitrary such key should be considered the location of k.
• get(conf: Configuration, key: String) -> Optional<String>
  Get value associated with key, if any exists.
• 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 integer, following the Int schema type described above (returning default if the key doesn’t exist). Returns 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 integer, following the UInt schema type described above (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, following the Float schema type described above (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 those values.
• get_list(conf: Configuration, key: String) -> Optional<List<String>>
get_list_or_default(conf: Configuration, key: String, default: List<String>) -> List<String>
  Get value associated with key, if any exists, and parse it as a list (returning default 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 defined.
• merge(conf_a: Configuration, conf_b: Configuration) -> Configuration
  Returns the result of merging conf_b into conf_a.
• parse_schema(conf: Configuration) -> Schema (optional)
  Parse conf as a schema, returning an error if it is invalid.
• check_against_schema(conf: Configuration, schema: Schema) -> Configuration (optional)
  Check conf follows schema, returning an error with detailed information if not. If successful, returns a configuration with default values filled out.

Examples

This section lists some examples of POM files. For more examples, see the tests/ directory in the main POM repository.

All syntax

title = 'Crème brûlée'
0-*/_description_/*-0 =`A 'beautiful' crème br\u{FB}l\u{0000e9}e recipe
that\'s sure to delight your friends!`
author == `Jean\0\\"P." D'Martingale
[ingredients.flour]
	quantity= "100 g"
	type="all-purpose"
[ingredients.sugar]
	quantity		=	   50 g
	type = "br\x6f\u{77}n"
[ingrédients]
	œufs.quantité=3
	œufs.type = "extra large\,farm fresh\\,free-range"
[]
DIRECTIONS.en_CA.version.5 = "
1. Separate the egg yolks from the \"whites\".
2. Mix the yolks in a bowl with the sugar.
…
59. Enjoy!
"

This configuration has the following mapping of keys to values:

Configuration for a text editor

indentation-type = tabs
show-line-numbers = yes
tab-size = 4
font-size = "18"

[file-extensions]
C = .c
Cpp = .cpp, .h, .hpp

[plug-in.edit-over-ssh]
path = ~/misc/edit-over-ssh.so
enabled = yes

[plug-in.edit-over-ssh.settings]
favourite-host = my-web-server

[plug-in.edit-over-ssh.settings.hosts.my-web-server]
address = example.org
port = 22
ssh-key = ~/.ssh/id_ed25519

This configuration has the following mapping of keys to values:

Schema for text editor’s configuration

Here is a schema which a text editor might use. The example text editor configuration above follows it.

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

# must put this in your config! I can't make the decision for you!
indentation-type.type = 'spaces' | 'tabs'

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.*]
enabled.type = Bool
enabled.default = yes
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]
*.type = List[String]
C.default = .c, .h
Cpp.default = .cpp, .hpp, .cc, .hh
C-sharp.default = .cs

Errors

This section lists some erroneous lines that might appear in a POM file:

# Invalid key character '!'
cool-key! = 23
# Invalid key character ' '
fun times = yes
# Missing equals
music is on
# No closing ]
[my.section
# Invalid key character ' '
[ my.section ]
# Invalid escape sequence "\?"
no_trigraph = "a?\?=b"
# Invalid escape sequence "\xCE" — even though "\xCE\x92" is valid UTF-8.
#     ("\u{392}" should be used instead)
capital_beta = "\xCE\x92"
# Invalid escape sequence "\x00" / Invalid character in value (null character)
C_string = "Hello, world!\x00"
# Stray characters after closing "
name = "Andy" B
# Duplicate key 'tab-size'
tab-size = 4
tab-size = 8