From 6a58f4bebafc418ed9d3b96c10f40f06baa3fbaf Mon Sep 17 00:00:00 2001 From: pommicket Date: Sun, 7 Sep 2025 12:41:28 -0400 Subject: finish initial draft of spec --- site/404.html | 1 + site/index.html | 1 + site/main.css | 7 -- site/spec.html | 244 +++++++++++++++++++++++++++++++++++++++++++++++++------- 4 files changed, 218 insertions(+), 35 deletions(-) delete mode 100644 site/main.css diff --git a/site/404.html b/site/404.html index 3f9e5ac..b5a6bc4 100644 --- a/site/404.html +++ b/site/404.html @@ -3,6 +3,7 @@ +

Page not found

diff --git a/site/index.html b/site/index.html index 026778b..ce3d6e7 100644 --- a/site/index.html +++ b/site/index.html @@ -3,6 +3,7 @@ +

Coming soon

diff --git a/site/main.css b/site/main.css deleted file mode 100644 index b771e2a..0000000 --- a/site/main.css +++ /dev/null @@ -1,7 +0,0 @@ -td, th { - border: 2px solid black; - padding: 0.5em; -} -table { - border-collapse: collapse; -} diff --git a/site/spec.html b/site/spec.html index c3ae3fa..90573d6 100644 --- a/site/spec.html +++ b/site/spec.html @@ -3,7 +3,15 @@ - + POM Language Specification @@ -16,7 +24,9 @@

Introduction

POM is a “markup” language, primarily intended for software configuration, - and designed to be easy to parse and use. + 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. POM files should use the .pom file extension to identify themselves. @@ -147,7 +157,7 @@ time = 35 min

+

Example

+

+Given the following schema: +

+

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

+The value of 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 String (no schema key matches, so the default of String is used). +

+

type rule

Default: String. @@ -418,6 +456,9 @@ time = 35 min 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

@@ -430,7 +471,9 @@ time = 35 min

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. + and the value of its allow_unknown rule is no, + and it has no matching type rule, + the configuration does not follow the schema.

min, max rules

@@ -457,6 +500,15 @@ Additionally, if there is a schema key j.*.k.ty 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.

+ +

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 @@ -472,14 +524,14 @@ which contains a key x matching j.* must also contain 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(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. @@ -514,9 +566,10 @@ which contains a key x matching j.* must also contain 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. + 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
    @@ -538,8 +591,112 @@ which contains a key x matching j.* must also contain

    Examples

    +

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

    + +

    All syntax

    +This is a configuration which demonstrates almost all of the syntactic forms of POM. -

    A schema for a text editor's configuration

    +
    
+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: +

    + + + + + + + + + + + + + + + + +
    KeyValue
    titleCrème brûlée
    0-*/_description_/*-0A 'beautiful' crème brûlée recipe
    +that's sure to delight your friends!
    author= Jean\0\\"P."D'Martingale
    ingredients.flour.quantity100 g
    ingredients.flour.typeall-purpose
    ingredients.sugar.quantity50 g
    ingredients.sugar.typebrown
    ingrédients.œufs.quantité3
    ingrédients.œufs.typeextra 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!

    + +

    Configuration for a text editor

    +
    
+indent-using-spaces = yes
+show-line-numbers = yes
+tab-size = 4
+font-size = 18
+
+[file-extensions]
+C = .c
+C++ = .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: +

    + + + + + + + + + + + + + + + + + + +
    KeyValue
    indent-using-spacesyes
    show-line-numbersyes
    tab-size4
    font-size18
    file-extensions.C.c
    file-extensions.C++.cpp, .h, .hpp
    plug-in.edit-over-ssh.path~/misc/edit-over-ssh.so
    plug-in.edit-over-ssh.enabledyes
    plug-in.edit-over-ssh.settings.favourite-hostmy-web-server
    plug-in.edit-over-ssh.settings.hosts.my-web-server.addressexample.org
    plug-in.edit-over-ssh.settings.hosts.my-web-server.port22
    plug-in.edit-over-ssh.settings.hosts.my-web-server.ssh-key~/.ssh/id_ed25519
    + +

    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
@@ -563,6 +720,8 @@ 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
@@ -578,6 +737,35 @@ C-sharp.type = List[String]
 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
+
    + -- cgit v1.2.3