Context item → Context value?

[ChristianGruen]

This has already been discussed before at various places, I’d like to raise it again: What about generalizing the context item and allowing it to reference sequences? Are there definitive showstoppers?

The Context Item

As its name says, the context item is a container for a single item in the current context. A value that is bound to the context item is referenced with the Context Item Expression, the single dot: ..

The context item shares many similarities with variables. The main difference is that it currently cannot be used for sequences. I propose to generalize the semantics and introduce a “context value”:

• Items that have formerly been bound to the context item (via the Context Item Declaration, within predicates, the simple map operator, path expressions, the transform with expression, etc.) are now bound to the context value.
• The revised Context Item Expression returns sequences instead of single items.
• We cannot drop context items completely – for example, we have a Context Item Declaration in the prolog of XQuery expressions, which uses the item keyword – but we can treat it as a secondary concept.

Context Value Declaration

It has become a common pattern to use declare context item to bind a document to the context item and process queries on that item:

declare context item := doc('flowers');
.//flower[name = 'Tigridia']

If data can be distributed across multiple documents (which is often, if not the standard case, in databases), this approach does not work. It would work if we could bind sequences:

declare context value := collection('flowers');
.//flower[name = 'Tigridia']

External Bindings

Many processors allow users to bind external values to the context item. This approach is particularly restricting for databases, in which data is often distributed across multiple documents. With the generalized concept, it would get possible to bind sequences and collections to the context. Paths like the following one could be used, no matter if the contents are stored in a single document or in a collection:

//flower[name = 'Iridaceae']

Focus Functions

The focus function provides a compact syntax for common arity-one functions. The single argument is bound it to the context item:

sort($flowers, (), function { @petals })

With the generalization to values, we could easily enhance focus functions to accept arbitrary sequences:

array:sort($flower-species, (), function { count(.) })

let $flowers := array:join(
  for $flower in //flower
  group by $_ := $flower/name
  return [ $flower ]
)
(: some $p in petals satisfies $p gt 4 :)
return array:filter($flowers, function { petals > 4 })

Use Case: Arrow Expressions

The arrow expression provides an intuitive syntax for performing multiple subsequent operations on a given input. With the context value generalization, we could also process chained sequences:

//flower[name = 'Psychotria']
=> function { count(.) || ' flower(s) found' }()

[rhdunn]

I like the idea of supporting the EnclosedExpr syntax on fat arrows for consistency and symmetry between the new syntax.

I also like the idea of passing a context value (sequence) to a query.

This needs to work with the current focus definition (https://qt4cg.org/branch/master/xquery-40/xquery-40-diff.html#dt-focus), where context item, context position, and context size in the dynamic context form the focus.

We would therefore need something that binds to the context item -- such as function () { ... } or array { ... }, which don't quite work -- that when used evaluates to the contents of the sequence for the purpose of evaluating the items in that sequence. In the case of the function, we would want the context value . to be evaluated as .().

To achieve this, we can define a context value as a sequence bound to the context item that when evaluated returns the content of its containing sequence. If we wanted a syntax for this, we could have something like sequence { 1, 2, 3 }. Then U => EnclosedExpr would bind the context item to the context value of the evaluated UnaryExpr.

[ChristianGruen]

I would hope that we can effectively replace the term context item by context value, and indicate in the Change Log that the context value was formerly restricted to a single item.

As I see no general stumbling blocks, I’m trying to adapt the definitions and parts of the further context references. It could read as follows:

---

2.1.1 Static Context

[Definition: Context value static type. This component defines the static sequence type of the context value.]

2.1.2 Dynamic Context

[Definition: The first three components of the dynamic context (context value, context position, and context size) are called the focus of the expression.] The focus enables the processor to keep track of which items are being processed by the expression. If any component in the focus is defined, all components of the focus are defined. [Definition: A singleton focus is a focus that refers to a single item; in a singleton focus, context value is set to the item, context position = 1 and context size = 1.]
…

• [Definition: The context value is the value currently being processed.] [Definition: When the context value is a single node, it can also be referred to as the context node.] The context value is returned by an expression consisting of a single dot (.). When an expression E1/E2 or E1[E2] is evaluated, each item in the sequence obtained by evaluating E1 becomes the context value in the inner focus for an evaluation of E2.
  [Definition: In the dynamic context of every module in a query, the context value component must have the same setting. If this shared setting is not absent, it is referred to as the initial context value.]
• [Definition: If a sequence of items is processed and successively bound to the context value, the context position is the position within this sequence.]] It changes whenever the context value changes. When the focus is defined, the value of the context position is an integer greater than zero. The context position is returned by the expression fn:position(). When an expression E1/E2 or E1[E2] is evaluated, the context position in the inner focus for an evaluation of E2 is the position in the sequence obtained by evaluating E1. The position of the first item in a sequence is always 1 (one). The context position is always less than or equal to the context size.

2.4.4 Input Sources

An expression can access input data either by calling one of these input functions or by referencing some part of the dynamic context that is initialized by the external environment, such as a variable or context value.

4.3.4 Context Item Expression

ContextValueExpr   ::=   "."

A context value expression evaluates to the context value, which may be an arbitrary sequences of nodes, atomic values and functions.

If the context value is absent, a context value expression raises a dynamic error [err:XPDY0002].

4.4.2.1 Evaluating Dynamic Function Calls

Example: Using the Context Value in an Anonymous Function

The following example will raise a dynamic error [err:XPDY0002]:

let $vat := function() { @vat + @price }
return shop/article/$vat()

Instead, the context value can be implicitly bound with a function item expression and the => symbol …

declare context value := collection('items')/shop/article;
=> { ./(@vat + @price) }()

…or one by one with the -> symbol:

let $vat := -> { @vat + @price }
return shop/article/$vat(.)

5.17 Context Item Declaration

If a module contains more than one context item declaration and context value declaration altogether, a static error is raised [err:XQST0099].

Should be treated as special-case legacy version of the “Context Value Expression”.

5.xx Context Value Declaration (…parts)

ContextValueDecl ::= "declare" "context" "value" ("as" SequenceType)? ((":=" VarValue) |
                     ("external" (":=" VarDefaultValue)?))`

A context value declaration allows a query to specify the static type, value, or default value for the initial context value.

In every module that does not contain a context value declaration, the effect is as if the declaration

declare context value as item()* external;

appeared in that module.

If a module contains more than one context value declaration and context item declaration altogether, a static error is raised [err:XQST0099].

During query evaluation, a focus is created in the dynamic context for the evaluation of the QueryBody in the main module, and for the initializing expression of every variable declaration in every module. The context value of this focus is called the initial context value, …

---

“The context value is the value currently being processed” is still misleading. It’s already the original definition “The context item is the item currently being processed.” that I found confusing: It matches well for a singleton focus that’s temporarily created for the evaluation of a predicate or simple map expression, but it doesn’t really fit if the context item is declared in the prolog and globally available in the main module.

[rhdunn]

For the prolog and main module, the "currently being processed" will be in the context of the QueryBody, so that should be fine. The ContextItemDecl documentation (and thus equivalently also the ContextValueDecl documentation) as you reference describes how that is determined in that case.

[graydon2014]

• [Definition: In the dynamic context of every module in a query, the context value component must have the same setting. If this shared setting is not absent, it is referred to as the initial context value.]

That second sentence is defeating me.

I think the first sentence is something like "there is one and only one focus at any point in time in an entire query, so the context value component of the dynamic context must have the same setting everywhere in the query."

But there MUST be a focus, conceptually; there has to be a dynamic context if the query can be evaluated. So I think the second sentence might be "If the context value component has a defined value, it is referred to as the initial context value."

[ChristianGruen]

For the prolog and main module, the "currently being processed" will be in the context of the QueryBody, so that should be fine.

Yes, I assume it's logically correct. Maybe something like “The context value is available for reference within the corresponding context.” would sound more intuitive to me, in accordance with the definition of in-scope variables.

That second sentence is defeating me.

The original definition is as follows:

• [Definition: In the dynamic context of every module in a query, the context item component must have the same setting. If this shared setting is not absentDM31, it is referred to as the initial context item. ]

I imagine that the set of definitions needs to be rephrased as a whole in order to get consistent again.

[michaelhkay]

I'm concerned about the sheer number of things in the spec that would need to change.

I'm also concerned about performance. If we can't statically infer that "." is a singleton, there's a significant risk that existing code slows down because existing optimisations are no longer safe.

At the same time, I recognise the need - for example, when iterating over an array. But I feel it's a bridge too far.

[ChristianGruen]

I’m pretty optimistic that performance shouldn't be something that cannot be resolved. At least that's the impression I got when implementing it by myself, including all corner cases I managed to find.

[michaelhkay]

In XQuery I think you can always statically determine what expression provides the focus for any occurrence of ".". That's not true in XSLT (and it's not true for XPath if the context item is supplied by the host language, as will often be the case). XSLT is much more heavily dependent on the context item than XQuery is.