From 649a6d50cd9a8e14a6e2262f82bcbfe46cbe301c Mon Sep 17 00:00:00 2001 From: Michael Kay Date: Fri, 3 Jan 2025 12:33:14 +0000 Subject: [PATCH] Improve introductory text for item types --- specifications/xquery-40/src/errors.xml | 6 + specifications/xquery-40/src/expressions.xml | 354 ++++++++++--------- 2 files changed, 201 insertions(+), 159 deletions(-) diff --git a/specifications/xquery-40/src/errors.xml b/specifications/xquery-40/src/errors.xml index 50230945f..1c2bb3c84 100644 --- a/specifications/xquery-40/src/errors.xml +++ b/specifications/xquery-40/src/errors.xml @@ -1133,6 +1133,12 @@ It is a static error if the name of a feature in EQName.

+ +

It is a static error + if a key type named in a is not a + .

+ + diff --git a/specifications/xquery-40/src/expressions.xml b/specifications/xquery-40/src/expressions.xml index 02be3610b..a05bd6622 100644 --- a/specifications/xquery-40/src/expressions.xml +++ b/specifications/xquery-40/src/expressions.xml @@ -3635,7 +3635,19 @@ defined in values that can be bound to variables, used in expressions, or passed to functions. It then describes how these relate to schema types, - that is, the simple and complex types defined in an XSD schema.

+ that is, the simple and complex types defined in an XSD schema.

+ +

In many situations the terms item type and + sequence type are used interchangeably to refer either to the type itself, + or to the syntactic construct that designates the type: so in the expression + $x instance of xs:string*, the construct xs:string* + uses the SequenceType syntax to designate a + whose instances are sequences of strings. + When more precision is required, the specification is careful to use the terms + and to + refer to the actual types, while using the production names ItemType + and SequenceType to refer to the syntactic + designators of these types.

 Sequence Types @@ -3645,28 +3657,13 @@ defined in A sequence type is a type that can be expressed using the SequenceType syntax. Sequence types are used whenever it is necessary to refer to a type in an &language; expression. - The term sequence type suggests that this syntax is used to describe the type of an &language; value, - which is always a sequence. + Since all values are sequences, every value matches one or more sequence types.

-

- An item type is a type that can be expressed using the ItemType syntax, which forms part of the SequenceType - syntax. Item types match individual items. - - In most cases, the set of items matched by an item type consists either - exclusively of atomic items, - exclusively of nodes, - or exclusively of function items. - Exceptions include the generic types item(), which matches all items, xs:error, - which matches no items, and choice item types, - which can match any combination of types. -

- - + -

Whenever it is necessary to refer to a type in an &language; expression, the Whenever it is necessary to refer to a sequence type + in an &language; expression, the SequenceType syntax is used.

@@ -3676,39 +3673,21 @@ defined in -

In many situations the terms item type and - sequence type are used interchangeably to refer either to the type itself, - or to the syntactic construct that designates the type: so in the expression - $x instance of xs:string*, the construct xs:string* - uses the SequenceType syntax to designate a - whose instances are sequences of strings. - When more precision is required, the specification is careful to use the terms - and to - refer to the actual types, while using the production names ItemType - and SequenceType to refer to the syntactic - designators of these types.

+

A sequence type designator is a syntactic construct conforming to the grammar rule SequenceType. A sequence type designator is said to designate a .

-

An - item type designator is a syntactic construct conforming to the grammar rule - ItemType. An item type designator is said - to designate an .

- -

Two item type designators may designate the - same item type. For example, element() and element(*) are equivalent, - as are attribute(A) and attribute(A, xs:anySimpleType).

 - +

With the exception of the special type empty-sequence(), a sequence type consists of an -item type that constrains the type of each item in the + that constrains the type of each item in the sequence, and a cardinality that constrains the number of items in the sequence. Apart from the item type item(), which permits any kind of item, item types divide into node @@ -3716,30 +3695,12 @@ types (such as element()), generalized atomic types (such as xs:integer) and function types (such as function() as item()*).

-

- Lexical QNames appearing in a sequence type have their - prefixes expanded to namespace URIs by means of the - statically known namespaces and (where applicable) the - . - Equality of QNames is defined by the eq operator.

- - -

Item types representing element -and attribute nodes may specify the required type annotations of those nodes in -the form of a schema -type. Thus the item type element(*, us:address) -denotes any element node whose type annotation is (or is derived from) -the schema type named us:address.

- -

The occurrence indicators +, *, and ? bind to the last The cardinality of a is represented + in the syntax by + an . + The occurrence indicators +, *, and ? + bind to the last ItemType in the SequenceType, as described in the occurrence-indicators constraint.

@@ -4004,6 +3965,52 @@ the schema type named us:address.

Item Types +

+ An item type is a type that can be expressed using the ItemType syntax, which forms part of the SequenceType + syntax. Item types match individual items.

+ +

While this definition is adequate for the purpose of defining the syntax + of &language;, it ignores the fact that there are also item types that cannot be + expressed using &language; syntax: specifically, item types that reference + an anonymous simple type or complex type defined in a schema. Such types + can appear as type annotations on nodes following schema validation.

 + +

In most cases, the set of items matched by an item type consists either + exclusively of atomic items, + exclusively of nodes, + or exclusively of function items. + Exceptions include the generic types item(), which matches all items, xs:error, + which matches no items, and choice item types, + which can match any combination of types. +

+ +

An + item type designator is a syntactic construct conforming to the grammar rule + ItemType. An item type designator is said + to designate an .

+ +

Two item type designators may designate the + same item type. For example, element() and element(*) are equivalent, + as are attribute(A) and attribute(A, xs:anySimpleType).

 + +

+ Lexical QNames appearing in an (other than within + a ) have their + prefixes expanded to namespace URIs by means of the + statically known namespaces and (where applicable) the + . + Equality of QNames is defined by the eq operator.

+ + + + + + @@ -4128,7 +4135,8 @@ the schema type named us:address.

A generalized atomic type is an item type whose instances are all + >A generalized atomic type is an + whose instances are all atomic items. Generalized atomic types include (a) atomic types, either built-in (for example xs:integer) or imported from a schema, @@ -4450,16 +4458,23 @@ declare variable $orange-fruit as my:fruit := "orange"; -

Some of the constructs described in this section include a TypeName. This appears +

Node types are item types whose + instances are all nodes.

+ +

The syntax for node types is also used for node tests + within path expressions. This explains why the production rules have names such as + NodeTest rather than NodeType.

+ +

Some of the constructs described in this section include a TypeName. This appears as T in:

- +

element(N, T)

attribute(N, T)

document-node(element(N, T))

 -

In these constructs, the type name T is expanded using the +

Like other lexical QNames, the type name T is expanded using the in the , using the if it is unprefixed. The resulting QName must identify a type in the . This can be any : either a simple type, @@ -4467,6 +4482,9 @@ declare variable $orange-fruit as my:fruit := "orange"; list type. It can be a built-in type (such as xs:integer) or a user-defined type. It must however be the name of a type defined in a schema; it cannot be a .

+ + + Simple Node Types @@ -4779,7 +4797,7 @@ matches any nilled or non-nilled element node whose type annotation is

Where a TypeName is included in an - ElementTest T, and element node will only + ElementTest T, an element node will only match the test if it has been validated against a schema that defines type T; furthermore, T must be present in the of the static context of the @@ -5184,80 +5202,102 @@ name.

MapTest, and RecordTest, with no change in meaning. + +

A FunctionType matches selected function items, + potentially checking their signature + (which includes the types of the arguments and results).

+ + -

A FunctionType matches selected function items, - potentially checking their signature - (which includes the types of the arguments and results, and also their annotations, - as described in )).

- +

The keywords function and fn are synonyms.

+ +

If the contains an + , then this is interpreted as a + , as described below.

+

An AnyFunctionType - matches any item that is a function.

+ matches any , including a map or an array. For example, + the following expressions all return true:

+ + +

fn:name#1 instance of function(*)

 +

fn{@id} instance of function(*)

 +

fn:random-number-generator() instance of function(*)

 +

[1, 2, 3] instance of fn(*)

 +

{} instance of fn(*)

 + -

A TypedFunctionType matches an - item if it is a and the function’s type signature (as defined in +

A TypedFunctionType matches + a if the function’s type signature (as defined in ) is a subtype of the TypedFunctionType.

-

The keywords function and fn are synonymous.

 - -

In addition, a TypedFunctionType + +

In consequence, a TypedFunctionType may match certain maps and arrays, as described in and

- Here are some examples of FunctionTypes: + Here are some examples of expressions that + use a TypedFunctionType:

- +

- function(*) matches any function, including maps and arrays.

-

This can also be written fn(*).

 + fn:count#1 instance of function(item()*) as xs:integer returns true, + because the signature of the function item fn:count#1 + is function(item()*) as xs:integer. +

- +

- %my:assertion function(*) matches any function if the implementation-defined function assertion %my:assertion is satisfied. -

+ fn:count#1 instance of function(xs:string*) as item() returns true, + because the signature of the function item fn:count#1 + is a subtype of function(xs:string*) as item(). +

- +

- function(xs:int, xs:int) as xs:int matches any $F instance of %my:assertion function(*) is true if + $F is a function item with the function signature function(xs:int, xs:int) as xs:int. -

-

This can also be written fn(xs:int, xs:int) as xs:int.

 + >function that satisfies the implementation-defined + function assertion %my:assertion. +

- %my:assertion function(xs:int, xs:int) as xs:int matches any $F instance of %my:assertion function(xs:int, xs:int) as xs:int + is true if $F is a with the function signature function(xs:int, xs:int) as xs:int - if the implementation-defined function assertion %my:assertion is satisfied. + that satisfies the implementation-defined function assertion %my:assertion.

- function(xs:anyAtomicType) as item()* matches any map, or any function with the required signature.

+ function(xs:anyAtomicType) as item()* matches any map, + or any other function item with the required signature.

- function(xs:integer) as item()* matches any array, or any function with the required signature.

+ function(xs:integer) as item()* matches any array, + or any other function item with the required signature.

 - +

specifications in the XQuery family may also use function assertions in the future.

-

An unprefixed QName is taken to refer to the namespace +

An unprefixed QName used + within a is taken to refer to the namespace http://www.w3.org/2012/xquery. Since this is a reserved namespace, and no assertions are currently defined in this namespace, this means that @@ -5319,13 +5360,15 @@ name.

- - - Map Types + +

A MapType designates an item type that + either matches any map, or that matches maps whose keys and values + are constrained to specific types.

+ @@ -5335,8 +5378,10 @@ name.

+

An + map(*) matches any map.

+

The MapType - map(*) matches any map. The MapType map(K, V) matches any map where every key is an instance of K and every value is an instance of V.

@@ -5345,13 +5390,12 @@ name.

Although the grammar for TypedMapType allows the key to be described using the full ItemType syntax, the item type used must be - a . [TODO: error code].

+ a .

-

Examples:

- -

Given a map $M whose keys are integers and whose + +

For example, given a map $M whose keys are integers and whose results are strings, such as { 0: "no", 1: "yes" }, - consider the results of the following expressions: + the following following expressions deliver the result shown:

@@ -5372,12 +5416,12 @@ name.

- not($M instance of map(xs:int, xs:string)) returns true() + $M instance of map(xs:int, xs:string) returns false()

- not($M instance of map(xs:integer, xs:token)) returns true() + $M instance of map(xs:integer, xs:token)) returns false()

@@ -5425,32 +5469,9 @@ name.

-

Because of the rules for subtyping of function - types according to their signature, it follows that the item type - function(A) as item()*, where A is an , - also matches any map, regardless of the type of the keys actually - found in the map. For example, a map whose keys are all strings can be - supplied where the required type is function(xs:integer) as item()*; - a call on the map that treats it as a function with an integer argument - will always succeed, and will always return an empty sequence.

- + -

The function signature of a map matching type - map(K, V), treated as a function, is - function(xs:anyAtomicType) as V?. It is thus always a - subtype of function(xs:anyAtomicType) as item()* regardless of the - actual types of the keys and values in the map. The rules for - function coercion mean that any map can be supplied as a value in a - context where the required type has a more specific return type, - such as function(xs:anyAtomicType) as xs:integer, even when the map - does not match in the sense required to satisfy the instance of - operator. In such cases, a type error will occur only if an actual - call on the map (treated as a function) returns a value that is not - an instance of the required return type. -

Examples:

@@ -5516,6 +5537,22 @@ name.

The syntax record() is allowed; the only thing it matches is an empty map. + +

A RecordType matches maps that meet specific criteria.

+ +

For example, the RecordType + record(r as xs:double, i as xs:double) + matches a map if the map has exactly two entries: an entry with key "r" + whose value is a singleton xs:double value, and an entry with key "i" + whose value is also a singleton xs:double value.

+ +

Record types describe a subset of the value space of maps. They do not define any new kinds of + values, or any additional operations. They are useful in many cases to describe more accurately the + type of a variable, function parameter, or function result, giving benefits both in the readability + of the code, and in the ability of the processor to detect and diagnose type errors and to optimize + execution.

+ + @@ -5528,14 +5565,7 @@ name.

 -

A RecordType matches maps that meet specific criteria.

- -

For example, the RecordType - record(r as xs:double, i as xs:double) - matches a map if the map has exactly two entries: an entry with key "r" - whose value is a singleton xs:double value, and an entry with key "i" - whose value is also a singleton xs:double value.

- +

If the list of fields ends with ",*" then the record type is said to be extensible. For example, the RecordType @@ -5549,7 +5579,7 @@ name.

is not extensible. The only thing it matches is an empty map.

The syntax record(*) defines an extensible record type that has no explicit field declarations. It is equivalent to the item type - map(*): that is, it allows any map.

 + map(*): that is, it matches any map.

A record type can constrain only those entries whose keys are strings, but when the record @@ -5590,11 +5620,7 @@ name.

-

Record types describe a subset of the value space of maps. They do not define any new kinds of - values, or any additional operations. They are useful in many cases to describe more accurately the - type of a variable, function parameter, or function result, giving benefits both in the readability - of the code, and in the ability of the processor to detect and diagnose type errors and to optimize - execution.

+

If a variable $rec is known to conform to a particular record type, then when a lookup expression $rec?field is used, (a) the processor @@ -5762,6 +5788,10 @@ declare record Particle ( Array Types + +

An ArrayType designates an item type that + either matches all arrays, or that matches arrays whose members + are constrained to a specific type.

@@ -5771,9 +5801,9 @@ declare record Particle ( -

The AnyArrayType - array(*) matches any - array. The An + array(*) matches any array.

+

The TypedArrayType array(X) matches any array in which every array member matches the [ (1, 2), (3, 4) ] instance of array(xs:integer+) returns true()

+ +

+ [ [1, 2], [3, 4] ] instance of array(array(xs:integer+)) returns true() +

+

An array also matches certain other item types, @@ -5887,12 +5922,13 @@ declare record Particle ( - xs:error -

The type xs:error has an empty value space; it never appears as a dynamic type or as the content type of a dynamic element or attribute type. + The type xs:error +

The item type xs:error has an empty value space; + it never appears as a dynamic type or as the content type of a dynamic element or attribute type. - It was defined in XML Schema in the interests of making the type system complete and closed, and it is also available in &language; - for similar reasons.

+ It was defined in XML Schema in the interests of making the type system complete and closed, + and it is also available in &language; for similar reasons.

Even though it cannot occur in an instance, xs:error is a valid type name in a sequence type. The