From 0dc4a92a69be5ca401bea49fbd6051ad4b6f0d0b Mon Sep 17 00:00:00 2001 From: Lars Willighagen Date: Mon, 10 Oct 2022 22:25:25 +0200 Subject: [PATCH] Replace use of non-defined 'tag' term (#310) Fixes: https://github.com/kdl-org/kdl/issues/306 In the specifications of KQL and JiK, replace the usage of 'tag' with 'type annotation', as that is the term in the main KDL specification. --- JSON-IN-KDL.md | 14 +++++++------- QUERY-SPEC.md | 10 +++++----- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/JSON-IN-KDL.md b/JSON-IN-KDL.md index c256612..4a0c717 100644 --- a/JSON-IN-KDL.md +++ b/JSON-IN-KDL.md @@ -41,14 +41,14 @@ Arguments and children can be mixed, if desired. The preceding example could als } ``` -Two otherwise-ambiguous cases must be manually annotated with an `(array)` tag: +Two otherwise-ambiguous cases must be manually annotated with an `(array)` type annotation: * A single-element array (such as `[1]`) written using arguments (as `- 1`) would be ambiguous with a literal node. To indicate this is an array, it must be written as `(array)- 1` (Or rewritten to use child nodes, like `- { - 1 }`.) -* An empty array (JSON `[]`) must use the `(array)` tag, like `(array)-`. +* An empty array (JSON `[]`) must use the `(array)` type annotation, like `(array)-`. -The `(array)` tag can be used on any other valid array node if desired, but has no effect in such cases. +The `(array)` type annotation can be used on any other valid array node if desired, but has no effect in such cases. ---- @@ -97,14 +97,14 @@ The properties and/or children of the node represent the items of the object, with the property names and child nodenames as each item's key. All "keys" in an object node must be unique. -As with arrays, there are two ambiguous cases that must be manually annoted with the `(object)` tag: +As with arrays, there are two ambiguous cases that must be manually annoted with the `(object)` type annotation: * An object containing a single item whose key is "-" (like `{"-": 1}`) written using children (like `- { - 1 }`) would be ambiguous with an array node. To indicate this is an object, it must be written as `(object)- { - 1 }`. (Or, if the sole item's value is a literal, as in this example, it can be rewritten to use properties, as `- -=1`.) -* An empty object (JSON `{}`) must use the `(object)` tag, like `(object)-`. +* An empty object (JSON `{}`) must use the `(object)` type annotation, like `(object)-`. As with array nodes, `(object)` can be used on any valid object node if desired. @@ -116,9 +116,9 @@ Only valid JiK nodes can be encoded to JSON; if a JiK document contains an inval * A literal node is valid if it contains a single unnamed argument. -* An array node is valid if it contains only unnamed arguments and/or child nodes named "-". If it contains no arguments and no child nodes, its nodename *must* have the `(array)` tag. +* An array node is valid if it contains only unnamed arguments and/or child nodes named "-". If it contains no arguments and no child nodes, its nodename *must* have the `(array)` type annotation. -* An object node is valid if it contains only named properties and/or child nodes. Additionally, all "keys" must be unique within the node, whether they're encoded as property names or child node names. If it contains no properties and no child nodes, its nodename *must* have the `(object)` tag. +* An object node is valid if it contains only named properties and/or child nodes. Additionally, all "keys" must be unique within the node, whether they're encoded as property names or child node names. If it contains no properties and no child nodes, its nodename *must* have the `(object)` type annotation. ---- diff --git a/QUERY-SPEC.md b/QUERY-SPEC.md index 766794f..bec0cc4 100644 --- a/QUERY-SPEC.md +++ b/QUERY-SPEC.md @@ -32,8 +32,8 @@ binary operators. * `top()`: Returns all toplevel children of the current document. * `top() > []`: Equivalent to `top()` on its own. -* `(foo)`: Selects any element with a tag named `foo`. -* `()`: Selects any element with any tag. +* `(foo)`: Selects any element whose type annotation is `foo`. +* `()`: Selects any element with any type annotation. * `[val()]`: Selects any element with a value. * `[val(1)]`: Selects any element with a second value. * `[prop(foo)]`: Selects any element with a property named `foo`. @@ -44,8 +44,8 @@ Attribute matchers support certain binary operators: * `[val() = 1]`: Selects any element whose first value is 1. * `[prop(name) = 1]`: Selects any element with a property `name` whose value is 1. * `[name = 1]`: Equivalent to the above. -* `[name() = "hi"]`: Selects any element whose _node name_ is "hi". Equivalent to just `hi`, but more useful when using string operators. -* `[tag() = "hi"]`: Selects any element whose tag is "hi". Equivalent to just `(hi)`, but more useful when using string operators. +* `[name() = "hi"]`: Selects any element whose _node name_ is `"hi"`. Equivalent to just `hi`, but more useful when using string operators. +* `[tag() = "hi"]`: Selects any element whose type annotation is `"hi"`. Equivalent to just `(hi)`, but more useful when using string operators. * `[val() != 1]`: Selects any element whose first value exists, and is not 1. The following operators work with any `val()` or `prop()` values. @@ -67,7 +67,7 @@ If the value is not a string, the matcher will always fail: The following operators work only with `val()` or `prop()` values. If the value is not one of those, the matcher will always fail: -* `[val() = (foo)]`: Selects any element whose tag is "foo". +* `[val() = (foo)]`: Selects any element whose type annotation is `foo`. ## Map Operator