From f3cc109b06a7599bc125240dd55f8639582eea4e Mon Sep 17 00:00:00 2001 From: pommicket Date: Wed, 10 Sep 2025 11:57:21 -0400 Subject: Remove schemas, add unread_keys. I think that is all a schema was really needed for in the end, since you can just check the types of things when you are getting them. --- site/spec.html | 266 ++++++------------------------------------ tests/README.md | 2 - tests/schema/README.md | 0 tests/schema_errors/README.md | 0 4 files changed, 33 insertions(+), 235 deletions(-) delete mode 100644 tests/schema/README.md delete mode 100644 tests/schema_errors/README.md 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).

-

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

- - -

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

- -

- 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 231−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. @@ -624,8 +452,7 @@ and for my.nephews.car.id is Any (no schema key matches, so the default is used)

  • 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. + Useful for reporting invalid values. 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 @@ -643,27 +470,44 @@ and for my.nephews.car.id is Any (no schema key matches, so the default is used) 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 + if any exists, and parse it as a signed integer (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. + The integer’s absolute value must be strictly less than 253, + written in decimal or + 0x/0X-prefixed hexadecimal. + Leading zeroes are not permitted for decimal integers. + White space around or within the integer is not permitted. + A leading + (or, of course, -) is permitted. + If the key exists but its value does not follow these rules, an error is returned.
  • 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 + and parse it as an unsigned 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. + The integer must be at least 0 and strictly less than 253, + 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 or within the integer is not permitted. + If the key exists but its value does not follow these rules, an error is returned.
  • 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). + floating-point number (returning default if the key doesn’t exist). + The number must be 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 or within 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. Returns an error if the key exists but its value is not a valid floating-point number.
  • @@ -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 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. + unread_keys(conf: Configuration) -> List<String>
    + Returns a list of all keys which have not been the target of a get / get_* + call, either directly or through a section obtained from the section 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).
    • @@ -806,49 +649,6 @@ 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: diff --git a/tests/README.md b/tests/README.md index c4f3532..82c3eb3 100644 --- a/tests/README.md +++ b/tests/README.md @@ -7,5 +7,3 @@ They are described below: - [`location/`](location/README.md) — for testing that definition location of keys is correctly determined - [`errors/`](errors/README.md) — for testing that error conditions are detected and gracefully handled - [`interpretation/`](interpretation/README.md) — for testing that numbers, booleans, and lists are parsed correctly -- [`schema/`](schema/README.md) — for testing that schemas are implemented correctly -- [`schema_errors/`](schema_errors.md) — for testing that schema errors are detected and gracefully handled diff --git a/tests/schema/README.md b/tests/schema/README.md deleted file mode 100644 index e69de29..0000000 diff --git a/tests/schema_errors/README.md b/tests/schema_errors/README.md deleted file mode 100644 index e69de29..0000000 -- cgit v1.2.3