diff options
Diffstat (limited to 'site/spec.html')
| -rw-r--r-- | site/spec.html | 266 |
1 files changed, 33 insertions, 233 deletions
diff --git a/site/spec.html b/site/spec.html index 2e45352..481a32f 100644 --- a/site/spec.html +++ b/site/spec.html @@ -401,178 +401,6 @@ time = 35 min be merged into the global configuration). </p> -<h2>Schemas</h2> -<p> - A <i>schema</i> 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 <i>follow</i> a schema - when it obeys all of the schema’s rules. -</p> -<p> - POM’s schema format is not powerful to enforce all possible restrictions; - some will have to be enforced by the application. -</p> -<p> - 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> - For any valid key <i>k</i> the value of the rule <i>rule</i> for <i>k</i> is determined as follows: -</p> -<ul> - <li>Break <i>k</i> down into its <i>n</i> components.</li> - <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 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> - <li>If the candidate-list has exactly one schema key, use the value of that schema key.</li> - <li> - Otherwise select the schema key in the candidate-list with the - latest first <code>*</code>-component (in terms of component index), - preferring keys with no <code>*</code>, - breaking ties by the latest second <code>*</code>-component, - preferring keys with only one <code>*</code>, etc. Use its value. - </li> -</ul> - -<h3>Example</h3> -<p> -Given the following schema: -</p> -<pre><code> -*.*.id.type = Int -vehicle.*.id.type = UInt -*.truck.id.type = Float -vehicle.car.id.type = String -</code></pre> -<p> -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, -and for my.nephews.car.id is Any (no schema key matches, so the default is used). -</p> - -<h3><code>type</code> rule</h3> -<p> - Default: <code>Any</code>. -</p> -<p> - This describes what values a key is allowed to be associated with. - The following types are defined: -</p> -<ul> - <li><code>Any</code> or <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 (equivalent to <code>''</code>)</li> - <li> - <code>Bool</code> — accepts <code>true</code>, <code>on</code>, <code>yes</code>, - <code>false</code>, <code>off</code>, <code>no</code> (case- and white space- sensitive). - </li> - <li> - <code>UInt</code> — accepts any unsigned integer strictly less than 2<sup>53</sup>, - written in decimal or <code>0x</code> or <code>0X</code>-prefixed hexadecimal. - A leading <code>+</code> is permitted, but <code>-0</code> 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. - </li> - <li> - <code>Int</code> — accepts any signed integer whose absolute value - is strictly less than 2<sup>53</sup>, written in decimal or - <code>0x</code> or <code>0X</code>-prefixed hexadecimal. - Leading zeroes are not permitted for decimal integers. - White space around the integer is not permitted. - A leading <code>+</code> (or, of course, <code>-</code>) is permitted. - </li> - <li> - <code>Float</code> — A floating-point number, written in ordinary decimal - (e.g. <code>-1.234</code>, <code>7.</code>, <code>265</code>) or in C-like scientific notation - (e.g. <code>3e5</code>, <code>3.E-5</code>, <code>-3.7e+005</code>). - Excessive leading zeroes are not permitted (<code>0.0</code> is allowed, but not <code>00.0</code>). - Values which overflow to ±∞ are allowed (e.g. <code>1e999</code>), but NaN and explicit - <code>inf</code>/<code>Infinity</code> 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 <code>+</code> (or, of course, <code>-</code>) is permitted. - <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 - of lists above). Nested lists are not permitted. - </li> -</ul> -<p> - A type may optionally have accepted-spaces on either side; this does not change its meaning. -</p> - -<h3><code>allow_unknown</code> rule</h3> -<p> - Default: inherited from parent (i.e. if <i>k</i> = <i>j</i><code>.</code><i>component</i>, - look up the <code>allow_unknown</code> rule for <i>j</i>), - or <code>yes</code> if <i>k</i> has no parent (does not contain a dot). -</p> -<p> - This describes whether or the key <i>k</i> is allowed if it is not described in the schema. - It must be set to either <code>yes</code> or <code>no</code>. -</p> -<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>, <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 must be a valid <code>Float</code> 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 <code>Float</code>. -</p> -<h3><code>maxlength</code> rule</h3> -<p> - This schema key’s value must be a positive 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> - Sets the default value for a key. -</p> -<h3>Missing values</h3> -<p> - If there is a schema key <i>k</i><code>.type</code>, where <i>k</i> - does not contain any <code>*</code>-components, - and the type does not allow unset values (<code>None</code>), - and there is no schema key <i>k</i><code>.default</code>, - then a configuration must contain the key <i>k</i> to follow the schema. -</p> -<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 - 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> <p> If needed for a particular domain, an parser may accept an extended form of the POM syntax. @@ -624,8 +452,7 @@ and for my.nephews.car.id is Any (no schema key matches, so the default is used) <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 format of valid values can’t be described by a schema type. + Useful for reporting invalid values. If a key <i>k</i> isn’t given a value in the configuration, but a key of the form <i>k</i><code>.</code><i>j</i> is, then the location of the definition of an arbitrary such key @@ -643,27 +470,44 @@ and for my.nephews.car.id is Any (no schema key matches, so the default is used) <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 integer, - following the <code>Int</code> schema type described above + if any exists, and parse it as a signed integer (returning <code>default</code> if the key doesn’t exist). - Returns an error if the key exists but its value is not a valid signed 64-bit integer. + The integer’s absolute value must be strictly less than 2<sup>53</sup>, + written in decimal or + <code>0x</code>/<code>0X</code>-prefixed hexadecimal. + Leading zeroes are not permitted for decimal integers. + White space around or within the integer is not permitted. + A leading <code>+</code> (or, of course, <code>-</code>) is permitted. + If the key exists but its value does not follow these rules, an error is returned. </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 integer, - following the <code>UInt</code> schema type described above + and parse it as an unsigned integer (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. + The integer must be at least 0 and strictly less than 2<sup>53</sup>, + written in decimal or <code>0x</code> or <code>0X</code>-prefixed hexadecimal. + A leading <code>+</code> is permitted, but <code>-0</code> is not. + Leading zeroes are not permitted for decimal integers. + White space around or within the integer is not permitted. + If the key exists but its value does not follow these rules, an error is returned. </li> <li> <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 <code>Float</code> schema type described above - (returning <code>default</code> if the key doesn’t exist). + floating-point number (returning <code>default</code> if the key doesn’t exist). + The number must be written in ordinary decimal + (e.g. <code>-1.234</code>, <code>7.</code>, <code>265</code>) or in C-like scientific notation + (e.g. <code>3e5</code>, <code>3.E-5</code>, <code>-3.7e+005</code>). + Excessive leading zeroes are not permitted (<code>0.0</code> is allowed, but not <code>00.0</code>). + Values which overflow to ±∞ are allowed (e.g. <code>1e999</code>), but NaN and explicit + <code>inf</code>/<code>Infinity</code> are not. + White space around or within the number is not permitted. + The decimal point (if one is present) must be preceded and succeeded by digits. + A leading <code>+</code> (or, of course, <code>-</code>) is permitted. Returns an error if the key exists but its value is not a valid floating-point number. </li> <li> @@ -692,14 +536,13 @@ and for my.nephews.car.id is Any (no schema key matches, so the default is used) Returns the result of merging <code>conf_b</code> into <code>conf_a</code>. </li> <li> - <code>parse_schema(conf: Configuration) -> Schema</code> (<i>optional</i>)<br> - Parse <code>conf</code> as a schema, returning an error if it is invalid. - </li> - <li> - <code>check_against_schema(conf: Configuration, schema: Schema) -> Configuration</code> (<i>optional</i>)<br> - Check <code>conf</code> follows <code>schema</code>, - returning an error with detailed information - if not. If successful, returns a configuration with default values filled out. + <code>unread_keys(conf: Configuration) -> List<String></code><br> + Returns a list of all keys which have not been the target of a <code>get</code> / <code>get_*</code> + call, either directly or through a section obtained from the <code>section</code> function, + in an arbitrary order. + When configurations are merged, the gotten-ness of the values is preserved. + Whether or not getting values from the merged configuration affects the original configurations’ + gotten-nesses is unspecified (and should rarely matter). </li> </ul> @@ -806,49 +649,6 @@ This configuration has the following mapping of keys to values: </tbody> </table> -<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> -<pre><code> -# 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 -</code></pre> - <h3>Errors</h3> <p> This section lists some erroneous lines that might appear in a POM file: |