XML Path Language (XPath) 4.0 WG Review Draft

4.13.3.1 Postfix Lookup Expressions

A Lookup has two parts: the KeySpecifier determines which entries (in a map) or members (in an array) are selected, and the Modifier determines how they are delivered in the result. The default modifier is items, which delivers the result as a flattened sequence of items.

To take a simple example, given $A as an array [ ("a", "b"), ("c", "d"), ("e", "f"), 42 ], some example Lookup expressions are:

("a", "b", "c", "d", "e", "f", 42)

({ "key": 1, "value": ("a", "b") }, 
 { "key": 2, "value": ("c", "d") }, 
 { "key": 3, "value": ("e", "f") },
 { "key": 4, "value": 42 })

([ "a", "b" ], [ "c", "d" ], [ "e", "f" ], [42])

(1, 2, 3, 4)

("c", "d")

({ "key": 2, "value":("c", "d") })

([ "c", "d" ])

(2)

("e", "f", "a", "b")

({ "key": 3, "value": ("e", "f") }, 
 { "key": 1, "value": ("a", "b") })

([ "e", "f" ][ "a", "b" ])

(3, 1)

42

4

(1, 2, 3)

Similarly, given $M as a map { "X": ("a", "b"), "Y": ("c", "d"), "Z": ("e", "f"), "N": 42 }, some example lookup expressions are as follows.

("a", "b", "c", "d", "e", "f", 42)

({ "key": "X", "value": ("a", "b") }, 
 { "key": "Y", "value": ("c", "d") }, 
 { "key": "Z", "value": ("e", "f") },
 { "key": "N", "value": 42 })

([ "a", "b" ], [ "c", "d" ], [ "e", "f" ], [42])

("X", "Y", "Z", "N")

("c", "d")

({ "key": "Y", "value":("c", "d") })

([ "c", "d" ])

("Y")

("e", "f", "a", "b")

({ "key": "Z", "value": ("e", "f") }, 
 { "key": "X", "value": ("a", "b") })

([ "e", "f" ][ "a", "b" ])

("Z", "X")

42

"N"

("X", "Y", "Z")

The semantics of a postfix lookup expression E?pairs::KS are defined as follows. The results with other modifiers can be derived from this result, as explained below.

1. E is evaluated to produce a value $V.

2. If $V is not a singleton (that is if count($V) ne 1), then the result (by recursive application of these rules) is the value of for $v in $V return $v?pairs::KS.

3. If $V is a singleton array item (that is, if $V instance of array(*)) then:

   1. If the KeySpecifierKS is a ParenthesizedExpr, then it is evaluated to produce a value $K and the result is:

      data($K) ! { "key": ., "value": array:get($V, .) }

      Note:

      The focus for evaluating the key specifier expression is the same as the focus for the Lookup expression itself.

   2. If the KeySpecifierKS is an IntegerLiteral with value $i, the result is the same as $V?pairs::($i).

   3. If the KeySpecifierKS is an NCNameor StringLiteral, the expression raises a type error [err:XPTY0004].

   4. If the KeySpecifierKS is a wildcard (*), the result is the same as $V?pairs::(1 to array:size($V)):

      Note:

      Note that array items are returned in order.

   5. If the KeySpecifierKS is a TypeSpecifier~[T], the result is the same as $V?pairs::*[?value instance of T].

4. If $V is a singleton map item (that is, if $V instance of map(*)) then:

   1. If the KeySpecifierKS is a ParenthesizedExpr, then it is evaluated to produce a value $K and the result is:

      data($K) ! { "key": ., "value": map:get($V, .) }

      Note:

      The focus for evaluating the key specifier expression is the same as the focus for the Lookup expression itself.

   2. If the KeySpecifierKS is an NCName or a StringLiteral, with value $S, the result is the same as $V?pairs::($S)

   3. If the KeySpecifierKS is an IntegerLiteral with value $N, the result is the same as $V?pairs::($N).

   4. If the KeySpecifierKS is a wildcard (*), the result is the same as $V?pairs::(map:keys($V)).

      Note:

      The order of entries in the result sequence reflects the entry order^DM of the map.

   5. If the KeySpecifierKS is a TypeSpecifier~T, the result is the same as $V?pairs::*[?value instance of T]. Note that T is in general a sequence type: if there is an occurrence indicator, then it must be written within parentheses, but if it is a plain item type with no occurrence indicator, then the parentheses may be omitted.

5. Otherwise (that is, if $V is neither a map nor an array) a type error is raised [err:XPTY0004].

For modifiers other than pairs, the resulting key-value pair is post-processed as follows:

• If the modifier is items (explicitly or by default), and the key specifier is an NCName or StringLiteral, then the result of $V?items::KS is the result of the expression:

  for $KVP in $V?pairs::KS
  let $value := map:get($KVP, 'value')
  return if ($value instance of %method function(*))
         then bind-focus($value, $V)
         else $value

  where bind-focus($F, $V) is a function that takes a function item $F and returns a modified function item whose captured context has the focus set to $V: for more detail see 4.5.6.1 Methods.

  Note:

  The effect of this is that if any of the selected values is a singletonmethod, the selected function item is modified by binding the context value to the containing map $V. In other cases the result is the sequence concatenation of the value parts.

• If the modifier is items (explicitly or by default), and tbe key specifier is not an NCName nor a StringLiteral, then the result of $V?items::KS is the result of the expression $V?pairs::KS ! map:get(., "value"). This returns the sequence concatenation of the selected values.If the modifier is items (explicitly or by default), and the key specifier is not an NCName nor a StringLiteral, then the result of $V?items::KS is the result of the expression $V?pairs::KS ! map:get(., "value"). This returns the sequence concatenation of the selected values.If the modifier is items (explicitly or by default), and tbethe key specifier is not an NCName nor a StringLiteral, then the result of $V?items::KS is the result of the expression $V?pairs::KS ! map:get(., "value"). This returns the sequence concatenation of the selected values.

• If the modifier is values, the result of $V?values::KS is the same as the result of $V?pairs::KS ! array { map:get(., "value") }. This returns each value as an array.

• If the modifier is keys, the result of $V?keys::KS is the same as the result of $V?pairs::KS ! map:get(., "key"). This returns the keys (integer indexes in the case of an array) without the values.

Examples:

• { "first" : "Jenna", "last" : "Scott" }?first evaluates to "Jenna"

• { "first name" : "Jenna", "last name" : "Scott" }?"first name" evaluates to "Jenna"

• [ 4, 5, 6 ]?2 evaluates to 5.

• ({ "first": "Tom" }, { "first": "Dick" }, { "first": "Harry" })?first evaluates to the sequence ("Tom", "Dick", "Harry").

• ([ 1, 2, 3 ], [ 4, 5, 6 ])?2 evaluates to the sequence (2, 5).

• ([ 1, [ "a", "b" ], [ 4, 5, [ "c", "d"] ])?value::*[. instance of array(xs:string)] evaluates to the sequence ([ "a", "b" ], [ "c", "d" ]).

• [ "a", "b" ]?3 raises a dynamic error [err:FOAY0001]^FO40