XML Path Language (XPath) 4.0 WG Review Draft

4.12.2 Let Expressions

XPath allows a variable to be declared and bound to a value using a let expression.

A let expression is evaluated as follows:

1. If the let expression uses multiple variables, it is first expanded to a set of nested let expressions, each of which uses only one variable. Specifically, any separating comma is replaced by let.

   Example:

   The expression:

   let $x := 4, $y := 3 return $x + $y

   is expanded to:

   let $x := 4 let $y := 3 return $x + $y

2. In a LetValueBinding such as let $V as T := EXPR:

   1. The variable V is called the range variable.

   2. The sequence type T is called the declared type. If there is no declared type, then item()* is assumed.

   3. The expression EXPR is evaluated, and its value is converted to the declared type by applying the coercion rules. The resulting value is called the binding sequence.

3. In a LetSequenceBinding such as let $( $A1 as T1, $A2 as T2, ... , $An as Tn ) as ST := EXPR:

   1. The sequence type ST is called the declared sequence type. If there is no declared sequence type, then item()* is assumed.

   2. The expression EXPR is evaluated, and its value is converted to the declared sequence type ST by applying the coercion rules. Call the resulting (coerced) value V.

   3. Each variable A_i (for i in 1 to n) is effectively replaced by a LetValueBinding of the form let Ai as Ti := items-at(V, i). That is, a range variable named A_i is declared, whose binding sequence is the item V[ i ], after coercion to the type T_i if specified. If T_i is absent, no further coercion takes place (the default is effectively item()?).Each variable A_i (for i in 1 to n-1) is effectively replaced by a LetValueBinding of the form let Ai as Ti := items-at(V, i). That is, a range variable named A_i is declared, whose binding sequence is the item V[ i ], after coercion to the type T_i if specified. If T_i is absent, no further coercion takes place (the default is effectively item()?).Each variable A_i (for i in 1 to n-1) is effectively replaced by a LetValueBinding of the form let Ai as Ti := items-at(V, i). That is, a range variable named A_i is declared, whose binding sequence is the item V[ i ], after coercion to the type T_i if specified. If T_i is absent, no further coercion takes place (the default is effectively item()?).

      Note:

      If i exceeds the length of the sequence V, then A_i is bound to an empty sequence. This will cause a type error if type T_i does not permit an empty sequence.

      Note:

      It is permissible to bind several variables with the same name; all but the last are occluded. A useful convention is therefore to bind items in the sequence that are of no interest to the variable $_: for example let $( $_, $_, $x ) := EXPR effectively binds $x to the third item in the sequence and causes the first two items to be ignored.

      Example:

      The expression:

      let $( $a, $b as xs:integer, $local:c ) := (2, 4, 6)
      return $a + $b + $local:c

      is expanded to:

      let $temp := (2, 4, 6)
      let $a := fn:items-at($temp, 1)
      let $b as xs:integer := fn:items-at($temp, 2)
      let $local:c := fn:items-at($temp, 3)
      return $a + $b + $local:c

      where $temp is some variable name that is otherwise unused.

       

      Example:

      Consider the element $E := <e A="p q r" B="x y z"/>, where $E has been validated against a schema that defines both attributes A and B as being lists of strings.

      Then the expression:

      let $( $a as xs:string*, $b as xs:string* ) := $E/(@A, @B)

      binds $a to the sequence ("p", "q", "r") and $b to the sequence ("x", "y", "z"). The evaluation of the expression $E/(@A, @B) returns a sequence of two attribute nodes; the value of $a is formed by atomizing the first of these nodes, while $b is formed by atomizing the second.

   4. The last variable A_n is effectively replaced by a LetValueBinding of the form let An as Tn := subsequence(V, n). That is, the last variable is bound to the rest of the binding sequence (or to the empty sequence if the binding sequence has fewer items than the number of variables).

   5. The last variable A_n is effectively replaced by a LetValueBinding of the form let An as Tn := subsequence(V, n). That is, the last variable is bound to the rest of the binding sequence (or to the empty sequence if the binding sequence has fewer items than the number of variables).

   Note:

   If i exceeds the length of the sequence V, then A_i is bound to an empty sequence. This will cause a type error if type T_i does not permit an empty sequence.

   Note:

   It is permissible to bind several variables with the same name; all but the last are occluded. A useful convention is therefore to bind items in the sequence that are of no interest to the variable $_: for example let $( $_, $_, $x ) := EXPR effectively binds $x to the third item in the sequence and causes the first two items to be ignored.

   Example:

   The expression:

   let $( $a, $b as xs:integer, $local:c ) := (2, 4, 6)
   return $a + $b + $local:c

   is expanded to:

   let $temp := (2, 4, 6)
   let $a := fn:items-at($temp, 1)
   let $b as xs:integer := fn:items-at($temp, 2)
   let $local:c := fn:subsequence($temp, 3)
   return $a + $b + $local:c

   where $temp is some variable name that is otherwise unused.

    

   Example:

   Consider the element $E := <e A="p q r" B="x y z"/>, where $E has been validated against a schema that defines both attributes A and B as being lists of strings.

   Then the expression:

   let $( $a as xs:string*, $b as xs:string* ) := $E/(@A, @B)

   binds $a to the sequence ("p", "q", "r") and $b to the sequence ("x", "y", "z"). The evaluation of the expression $E/(@A, @B) returns a sequence of two attribute nodes; the value of $a is formed by atomizing the first of these nodes, while $b is formed by atomizing the second.

4. In a LetArrayBinding such as let $[ $A1 as T1, $A2 as T2, ... , $An as Tn ] as AT := EXPR:

   1. The sequence type AT is called the declared array type. If there is no declared array type, then array(*) is assumed.

   2. The expression EXPR is evaluated, and its value is converted to the declared array type AT by applying the coercion rules. A type error [err:XPTY0004] is raised if the result is not a singleton array. Call the resulting (coerced) value V.

   3. Each variable A_i (for i in 1 to n) is effectively replaced by a LetValueBinding of the form let Ai as Ti := array:get(V, i, ()). That is, a range variable named A_i is declared, whose binding sequence is the array member V ? i, after coercion to the type T_i if specified. If T_i is absent, no further coercion takes place (the default is effectively item()*).Each variable A_i (for i in 1 to n) is effectively replaced by a LetValueBinding of the form let Ai as Ti := array:get(V, i). That is, a range variable named A_i is declared, whose binding sequence is the array member V ? i, after coercion to the type T_i if specified. If T_i is absent, no further coercion takes place (the default is effectively item()*).Each variable A_i (for i in 1 to n) is effectively replaced by a LetValueBinding of the form let Ai as Ti := array:get(V, i, ()). That is, a range variable named A_i is declared, whose binding sequence is the array member V ? i, after coercion to the type T_i if specified. If T_i is absent, no further coercion takes place (the default is effectively item()*).

      Note:

      If i exceeds the length of the array V, then A_i is bound to an empty sequence. This will cause a type error if type T_i does not permit an empty sequence.

      If i exceeds the length of the array V, then a dynamic error [err:FOAR0001]^FO is raised.

      Note:

      It is permissible to bind several variables with the same name; all but the last are occluded. A useful convention is therefore to bind items in the sequence that are of no interest to the variable $_: for example let $( $_, $_, $x ) := EXPR effectively binds $x to the third item in the sequence and causes the first two items to be ignored.

      Example:

      The expression:

      let $[ $a, $b as xs:integer, $local:c ] := [ 2, 4, 6 ]
      return $a + $b + $local:c

      is expanded to:

      let $temp := [ 2, 4, 6 ]
      let $a := array:get($temp, 1, ())
      let $b as xs:integer := array:get($temp, 2, ())
      let $local:c := array:get($temp, 3, ())
      return $a + $b + $local:c

      where $temp is some variable name that is otherwise unused.

5. In a LetMapBinding such as let ${ $A1 as T1, $A2 as T2, ... , $An as Tn } as MT := EXPR:

   1. The sequence type MT is called the declared map type. If there is no declared map type, then map(*) is assumed.

   2. The expression EXPR is evaluated, and its value is converted to the declared map type MT by applying the coercion rules. A type error [err:XPTY0004] is raised if the result is not a singleton map. Call the resulting (coerced) value V.

   3. Each variable A_i (for i in 1 to n) is effectively replaced by a LetValueBinding of the form let Ai as Ti := map:get(V, "Ni", ()), where N_i is the local part of the name of the variable A_i. That is, a range variable named A_i is declared, whose binding sequence is the value of the map entry in V whose key is an xs:string (or xs:anyURI or xs:untypedAtomic) equal to the local part of the variable name, after coercion to the type T_i if specified. If T_i is absent, no further coercion takes place (the default is effectively item()*).

      Note:

      If there is no entry in the map with a key corresponding to the variable name, then the variable A_i is bound to an empty sequence. This will cause a type error if type T_i does not permit an empty sequence.

      Note:

      It is not possible to use this mechanism to bind variables to values in a map unless the keys in the map are strings in the form of NCNames.

      Example:

      The expression:

      let ${ $a, $b as xs:integer, $local:c } := { "a": 2, "b": 4, "c": 6, "d": 8 }
      return $a + $b + $local:c

      is expanded to:

      let $temp := { "a": 2, "b": 4, "c": 6 }
      let $a := map:get($temp, "a", ())
      let $b as xs:integer := map:get($temp, "b", ())
      let $local:c := map:get($temp, "c", ())
      return $a + $b + $local:c

      where $temp is some variable name that is otherwise unused.

6. The expression in the ForLetReturn part (that is, the following LetExpr or ForExpr, or the ExprSingle that follows the return keyword) is called the return expression. The result of the let expression is obtained by evaluating the return expression with a dynamic context in which each range variable is bound to the corresponding binding sequence.

The scope of a variable bound in a let expression is the return expression. The scope does not include the expression to which the variable is bound. The following example illustrates how a variable binding may reference another variable bound earlier in the same let expression:

let $x := doc('a.xml')/*, $y := $x//*
return $y[@value gt $x/@min]

let $x := "[A fine romance]"
let $x := substring-after($x, "[")
let $x := substring-before($x, "]")
return upper-case($x)