diff options
Diffstat (limited to 'site/spec.html')
| -rw-r--r-- | site/spec.html | 125 |
1 files changed, 66 insertions, 59 deletions
diff --git a/site/spec.html b/site/spec.html index c8b3c6e..9435812 100644 --- a/site/spec.html +++ b/site/spec.html @@ -29,7 +29,6 @@ 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 <code>.pom</code> file extension to identify themselves. </p> <p> Every file describes a <i>configuration</i>, which is a mapping from keys to values. @@ -138,11 +137,11 @@ time = 35 min </div> <h2>Error handling</h2> <p> - 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. + 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 library author. + Warnings may also be issued according to the judgment of the parser author. </p> <h2>Text encoding</h2> <p> @@ -168,7 +167,7 @@ time = 35 min and does not contain two dots in a row (<code>..</code>). </p> <p> - Any string of non-zero Unicode scalar values (U+0080–10FFFF, but not U+D800–U+DFFF) is a valid value. + Any string of non-zero Unicode scalar values (U+0001–10FFFF, but not U+D800–U+DFFF) is a valid value. </p> <h2>Parsing</h2> <p> @@ -204,7 +203,7 @@ time = 35 min <li>If the line does not end with <code>]</code> optionally succeeded by any number of accepted-spaces, an error occurs.</li> <li> The current-section is set to the text in between the initial <code>[</code> and final <code>]</code> - (white space between the <code>[</code> and <code>]</code> is <em>not</em> trimmed). + (white space after the <code>[</code> and before the <code>]</code> is <em>not</em> trimmed). </li> <li> If the new current-section is not empty and not a valid key (see above), an error occurs. @@ -226,7 +225,7 @@ time = 35 min Let <i>c</i> be the first character after the <code>=</code> and any succeeding accepted-spaces. </li> <li> - If <i>c</i> is one of <code>"'`</code> (U+0022 QUOTATION MARK, U+0027 APOSTROPHE, U+0060 GRAVE ACCENT), + If <i>c</i> is <code>"</code> (U+0022 QUOTATION MARK) or <code>`</code> (U+0060 GRAVE ACCENT), the value is <i>quoted</i>, and spans from the first character after <i>c</i> to the next unescaped instance of <i>c</i> in the file (which may be on a different line). In this case, <ol> @@ -241,8 +240,14 @@ time = 35 min </ol> </li> <li> - Otherwise, accepted-spaces at the end of the line are removed; - then, the value is the text starting from <i>c</i> and going to the end of the line. + Otherwise, the value is <i>unquoted</i>. In this case, + <ol> + <li>accepted-spaces at the end of the line are removed.</li> + <li> + The value is the exact text starting from <i>c</i> and going + to the end of the line (escape sequences are not processed). + </li> + </ol> </li> <li>If the value is not a valid value (i.e. it contains a null character), an error occurs.</li> <li> @@ -307,7 +312,7 @@ time = 35 min As a consequence, an empty string is considered to be an empty list. </p> <p> - If a list's order is irrelevant and it might be large or benefit from labelling its entries, + 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 <code>ingredients</code> “list” in the opening example). </p> @@ -333,7 +338,7 @@ time = 35 min <td><code>z</code></td> </tr> <tr> - <td><code>things = `\,,,76`</code></td> + <td><code>things = \,,,76</code></td> <td><code>,</code></td> <td><code></code></td> <td><code>76</code></td> @@ -359,7 +364,7 @@ time = 35 min </ol> <p> (Likewise, an ordered series of configurations <i>A<sub>1</sub></i>, …, <i>A<sub>n</sub></i> - can be merged by merging <i>A<sub>n-1</sub></i> into <i>A<sub>n</sub></i>, then <i>A<sub>n-2</sub></i> into + can be merged by merging <i>A<sub>2</sub></i> into <i>A<sub>1</sub></i>, then <i>A<sub>3</sub></i> into the resulting configuration, etc.) </p> <p> @@ -379,7 +384,7 @@ time = 35 min some will have to be enforced by the application. </p> <p> - Every schema key is of the form <i>k</i><code>.</code><i>rule</i>, where <i>k</i> is a valid key, + Every schema key must be of the form <i>k</i><code>.</code><i>rule</i>, where <i>k</i> is a valid key, and <i>rule</i> is one of the rule names listed below. </p> <p> @@ -387,12 +392,12 @@ time = 35 min </p> <ul> <li>Break <i>k</i> down into its <i>n</i> components.</li> - <li>For each schema key <i>s</i> with <i>n</i> components: + <li>For each schema key <i>s</i>.<i>rule</i> where <i>s</i> has <i>n</i> components: <ul> <li>Match up the components of <i>s</i> with the components of <i>k</i>.</li> <li> - If all the components of <i>s</i> not equal to <code>*</code> are equal to the corresponding components - of <code>k</code>, add <i>s</i> to the <i>candidate-list</i>. + If every component of <i>s</i> is equal to <code>*</code> or the corresponding component + of <i>k</i>, add <i>s</i>.<i>rule</i> to the <i>candidate-list</i>. </li> </ul></li> <li>If the candidate-list is empty, use the default value for the rule.</li> @@ -416,7 +421,7 @@ vehicle.*.id.type = UInt vehicle.car.id.type = String </code></pre> <p> -The value of <code>type</code> rule for vehicle.car.id is String, +The value of the <code>type</code> 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, @@ -435,7 +440,7 @@ and for my.nephews.car.id is String (no schema key matches, so the default of St <li><code>String</code> — accepts any value</li> <li><code>None</code> — accepts an unset value (special—see below)</li> <li><code>Empty</code> — accepts an empty value</li> - <li><code>Bool</code> — accepts <code>true</code>, <code>on</code>, <code>yes</code>, + <li><code>Bool</code> — accepts <code>true</code>, <code>on</code>, <code>yes</code>, <code>false</code>, <code>off</code>, <code>no</code> (case-sensitive).</li> <li><code>UInt</code> — accepts any unsigned integer that fits in 63 [sic] bits, written in decimal or <code>0x</code> or <code>0X</code>-prefixed hexadecimal. @@ -448,8 +453,7 @@ and for my.nephews.car.id is String (no schema key matches, so the default of St A floating-point number, written in ordinary decimal (e.g. <code>-1.234</code>, <code>7.</code>, <code>265</code>) or in scientific notation (e.g. <code>3e5</code>, <code>3.E-5</code>, <code>-3.7e+5</code>). A leading <code>+</code> (or, of course, <code>-</code>) is permitted. - <li><code>'</code><i>value</i><code>'</code> — accepts the literal value <i>value</i>. Note that this must be written like - <code>thing.type = "'special_string'"</code> in the schema. Note also that <i>value</i> cannot contain a literal apostrophe <code>'</code>. </li> + <li><code>'</code><i>value</i><code>'</code> — accepts the literal value <i>value</i>. <i>value</i> cannot contain a literal apostrophe <code>'</code>. </li> <li><i>T</i><code> | </code><i>U</i>, where <i>T</i>, <i>U</i> are types — accepts a value of type <i>T</i> or <i>U</i>.</li> <li><code>Optional[</code><i>T</i><code>]</code>, where <i>T</i> is a type — equivalent to <i>T</i><code> | None</code>.</li> <li><code>List[</code><i>T</i><code>]</code>, where <i>T</i> is a type — accepts a list of entries of type <i>T</i> (see description @@ -472,18 +476,19 @@ and for my.nephews.car.id is String (no schema key matches, so the default of St <p> If a key is encountered in a configuration and the value of its <code>allow_unknown</code> rule is <code>no</code>, - and it has no matching <code>type</code> rule, + and it has no matching <code>type</code>, <code>maxlength</code>, or <code>default</code> rule, the configuration does not follow the schema. </p> <h3><code>min</code>, <code>max</code> rules</h3> <p> - This schema key's value sets the minimum/maximum value for the key's value. This must not be set if <code>type</code> - does not explicitly allow numeric values (i.e. it does not contain a type <code>Int</code>/<code>UInt</code>/<code>Float</code>). + This schema key’s value sets the minimum/maximum value for the key’s value. This may only be set if <code>type</code> + explicitly allows numeric values (i.e. it contains a type <code>Int</code>/<code>UInt</code>/<code>Float</code>). </p> <h3><code>maxlength</code> rule</h3> <p> - The value of this rule must be a non-negative integer no greater than 2<sup>31</sup>−1. - Specifies that the value of a key can be no longer than that number of UTF-8 bytes. + This schema key’s value must be a non-negative integer no greater than 2<sup>31</sup>−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. </p> <h3><code>default</code> rule</h3> <p> @@ -498,7 +503,7 @@ then a configuration must contain the key <i>k</i> to follow the schema. <p> Additionally, if there is a schema key <i>j</i><code>.*.</code><i>k</i><code>.type</code> that does not allow unset values and no correspoding <code>default</code> schema key, where <i>k</i> does not contain any <code>*</code>-components, then a configuration -which contains a key <i>x</i> matching <i>j</i><code>.*</code> must also contain the key <i>x</i><code>.</code><i>k</i>. +containing a key <i>x</i> matching <i>j</i><code>.*</code> must also contain the key <i>x</i><code>.</code><i>k</i>. </p> <h2>Extensions</h2> @@ -522,11 +527,11 @@ which contains a key <i>x</i> matching <i>j</i><code>.*</code> must also contain </li> <li> <code>load_string(string: String) -> Configuration</code><br> - Load a configuration from a string. + Load a configuration from a string (may be overloaded with <code>load</code> if language supports it). </li> <li> <code>load_path(path: String) -> Configuration</code><br> - Convenience function for loading by path (may be overloaded with <code>load</code> if language supports it). + Convenience function for loading by path. </li> <li> <code>print(conf: Configuration)</code><br> @@ -546,7 +551,7 @@ which contains a key <i>x</i> matching <i>j</i><code>.*</code> must also contain <li> <code>location(conf: Configuration, key: String) -> Optional<Location></code><br> Location of the definition of <code>key</code> in the configuration (file and line number). - Useful for reporting invalid values when the value format is more complicated than integer/float/boolean. + Useful for reporting invalid values when the format of valid values can’t be described by a schema type. </li> <li> <code>get(conf: Configuration, key: String) -> Optional<String></code><br> @@ -559,14 +564,16 @@ which contains a key <i>x</i> matching <i>j</i><code>.*</code> must also contain <li> <code>get_int(conf: Configuration, key: String) -> Optional<Int></code><br> <code>get_int_or_default(conf: Configuration, key: String, default: Int) -> Int</code><br> - Get value associated with <code>key</code>, if any exists, and parse it as a signed 64-bit integer + Get value associated with <code>key</code>, if any exists, and parse it as a signed 64-bit integer, + following the <code>Int</code> schema type described above (returning <code>default</code> if the key doesn’t exist). - Return an error if the key exists but its value is not a valid signed 64-bit integer. + Returns an error if the key exists but its value is not a valid signed 64-bit integer. </li> <li> <code>get_uint(conf: Configuration, key: String) -> Optional<UInt></code><br> <code>get_uint_or_default(conf: Configuration, key: String, default: UInt) -> UInt</code><br> - Get value associated with <code>key</code>, if any exists, and parse it as an unsigned 63-bit [sic] integer + Get value associated with <code>key</code>, if any exists, and parse it as an unsigned 63-bit [sic] integer, + following the <code>UInt</code> schema type described above (returning <code>default</code> if the key doesn’t exist). Returns an error if the key exists but its value is not a valid unsigned 63-bit integer. </li> @@ -574,7 +581,7 @@ which contains a key <i>x</i> matching <i>j</i><code>.*</code> must also contain <code>get_float(conf: Configuration, key: String) -> Optional<Float></code><br> <code>get_float_or_default(conf: Configuration, key: String, default: Float) -> Float</code><br> Get value associated with <code>key</code>, if any exists, and parse it as a 64-bit IEEE-754 double precision - floating-point number, following the description of the <code>Float</code> schema type above + floating-point number, following the <code>Float</code> schema type described above (returning <code>default</code> if the key doesn’t exist). Returns an error if the key exists but its value is not a valid floating-point number. </li> @@ -584,7 +591,7 @@ which contains a key <i>x</i> matching <i>j</i><code>.*</code> must also contain Get value associated with <code>key</code>, if any exists, and parse it as a boolean, taking <code>true</code>, <code>on</code>, <code>yes</code> to be <code>true</code>, and <code>false</code>, <code>off</code>, <code>no</code> to be <code>false</code> (case-sensitive). - Returns an error if the key exists but is not one of the above values. + Returns an error if the key exists but is not one of those values. </li> <li> <code>get_list(conf: Configuration, key: String) -> Optional<List<String>></code><br> @@ -594,16 +601,16 @@ which contains a key <i>x</i> matching <i>j</i><code>.*</code> must also contain </li> <li> <code>section(conf: Configuration, key: String) -> Configuration</code><br> - Get the sub-configuration consisting of the descendants of <code>key</code>, i.e. keys starting with <code>key.</code> - (with the initial <code>key.</code> removed) and their corresponding values. - Returns an empty configuration if there are no descendants of <code>key</code>. + Get the sub-configuration consisting of the descendants of <code>key</code> (i.e. keys starting with <code>key.</code>), + with the initial <code>key.</code> removed, and their corresponding values. + Returns an empty configuration if there are no descendants of <code>key</code> defined. </li> <li> - <code>check_schema(schema: Configuration, conf: Configuration) -> Configuration</code> (<i>optional</i>)<br> - Check if configuration <code>conf</code> follows the schema <code>schema</code> (and that <code>schema</code> - is a valid schema), + <code>check_against_schema(conf: Configuration, schema: Configuration) -> Configuration</code> (<i>optional</i>)<br> + Check that <code>schema</code> + is a valid schema and that <code>conf</code> follows it, returning an error with detailed information - if it does not. If successful, returns a configuration with default values filled out. + if not. If successful, returns a configuration with default values filled out. </li> <li> <code>merge(conf_a: Configuration, conf_b: Configuration) -> Configuration</code><br> @@ -621,16 +628,16 @@ which contains a key <i>x</i> matching <i>j</i><code>.*</code> must also contain This is a configuration which demonstrates almost all of the syntactic forms of POM. <pre><code> -title = Crème brûlée +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 +author == `Jean\0\\"P." D'Martingale [ingredients.flour] - quantity= '100 g' + quantity= "100 g" type="all-purpose" [ingredients.sugar] quantity = 50 g - type = 'br\x6f\u{77}n' + type = "br\x6f\u{77}n" [ingrédients] œufs.quantité=3 œufs.type = "extra large\,farm fresh\\,free-range" @@ -650,10 +657,10 @@ This configuration has the following mapping of keys to values: <tr><th>Key</th><th>Value</th></tr> </thead> <tbody> - <tr><td>title</td><td>Crème brûlée</td></tr> + <tr><td>title</td><td>'Crème brûlée'</td></tr> <tr><td>0-*/_description_/*-0</td><td>A 'beautiful' crème brûlée recipe<br> that's sure to delight your friends!</td></tr> - <tr><td>author</td><td>= Jean\0\\"P."D'Martingale</td></tr> + <tr><td>author</td><td>= `Jean\0\\"P." D'Martingale</td></tr> <tr><td>ingredients.flour.quantity</td><td>100 g</td></tr> <tr><td>ingredients.flour.type</td><td>all-purpose</td></tr> <tr><td>ingredients.sugar.quantity</td><td>50 g</td></tr> @@ -669,10 +676,10 @@ that's sure to delight your friends!</td></tr> <h3>Configuration for a text editor</h3> <pre><code> -indent-using-spaces = yes +indentation-type = tabs show-line-numbers = yes tab-size = 4 -font-size = 18 +font-size = "18" [file-extensions] C = .c @@ -699,7 +706,7 @@ This configuration has the following mapping of keys to values: <tr><th>Key</th><th>Value</th></tr> </thead> <tbody> - <tr><td>indent-using-spaces</td><td>yes</td></tr> + <tr><td>indentation-type</td><td>tabs</td></tr> <tr><td>show-line-numbers</td><td>yes</td></tr> <tr><td>tab-size</td><td>4</td></tr> <tr><td>font-size</td><td>18</td></tr> @@ -714,7 +721,7 @@ This configuration has the following mapping of keys to values: </tbody> </table> -<h3>Schema for text editor's configuration</h3> +<h3>Schema for text editor’s configuration</h3> <p> Here is a schema which a text editor might use. The example text editor configuration above follows it. </p> @@ -723,7 +730,7 @@ This configuration has the following mapping of keys to values: *.allow_unknown = no # must put this in your config! I can't make the decision for you! -indent-using-spaces.type = Bool +indentation-type.type = 'spaces' | 'tabs' show-line-numbers.type = Bool show-line-numbers.default = on @@ -740,14 +747,14 @@ 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 +[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 +settings.allow_unknown = yes [file-extensions] C.type = List[String] |