Merge pull request #1686 from ChristianGruen/1685

1685 Pipeline Operator
qt4cg · Jan 21, 2025 · aa69f32 · aa69f32
2 parents 8a537a9 + e2b7d56
commit aa69f32
Show file tree

Hide file tree

Showing 2 changed files with 103 additions and 0 deletions.
diff --git a/specifications/grammar-40/xpath-grammar.xml b/specifications/grammar-40/xpath-grammar.xml
@@ -1553,6 +1553,11 @@ ErrorVal ::= "$" VarName
         </g:sequence>
       </g:postfix>
     </g:level>
+    <g:level>
+      <g:binary name="PipelineExpr" condition="&gt; 1" if="xpath40 xquery40">
+        <g:string>-></g:string>
+      </g:binary>
+    </g:level>
     <g:level>
       <g:postfix name="ArrowExpr" prefix-seq-type="*" condition="&gt; 1" if="xpath40 xquery40">
         <g:sequence>

diff --git a/specifications/xquery-40/src/expressions.xml b/specifications/xquery-40/src/expressions.xml
@@ -22119,6 +22119,104 @@ raised <errorref
          </div3>
       </div2>
 
+      <div2 id="id-pipeline-operator">
+         <head>Pipeline operator</head>
+
+         <changes>
+            <change issue="1685" PR="1686" date="2025-01-09">
+               With the pipeline operator <code>-></code>, the result of an expression
+               can be bound to the context value before evaluating another expression.
+            </change>
+         </changes>
+
+         <scrap>
+            <head/>
+            <prodrecap id="PipelineExpr" ref="PipelineExpr"/>
+         </scrap>
+
+         <p diff="add" at="A"><termdef term="pipeline operator" id="dt-pipeline-operator">
+            The <term>pipeline operator</term> <code>-></code> evaluates an expression and
+            binds the result to the context value before evaluating another expression.</termdef></p>
+
+         <p>Each operation <code><var>E1</var> -> <var>E2</var></code> is evaluated as follows: 
+            Expression <var>E1</var> is evaluated to a sequence <code>S</code>. 
+            <var>S</var> then serves in turn to provide an inner <termref def="dt-fixed-focus"/>
+            (with the context value set to <var>S</var>) for an evaluation of <var>E2</var> in the
+            <termref def="dt-dynamic-context">dynamic context</termref>.
+            Unlike the <specref ref="id-map-operator"/>, the result of <var>E1</var> is bound
+            just once and as a whole to the context value.
+         </p>
+
+         <p>The following examples illustrate the use of pipeline operators:</p>
+         <example>
+            <ulist>
+               <item>
+                  <p>Tokenizes a string, counts the tokens, creates a concatenated string and returns
+                     <code>count=3</code>:</p>
+                  <eg role="parse-test">'a b c' -> tokenize(.) -> count(.) -> concat('count=', .)
+</eg>
+                  <p>An equivalent expression is:
+                     <eg role="parse-test">
+let $string := 'a b c'
+let $tokens := tokenize($string)
+let $count := count($tokens)
+return concat('count=', $count)
+                     </eg>
+                  </p>
+               </item>
+               <item>
+                  <p>Calculates the sum of powers of <code>2</code> and returns
+                     <code>2046</code>.</p>
+                  <eg role="parse-test">(1 to 10) ! math:pow(2, .) -> sum(.)</eg>
+                  <p>An equivalent expression is:
+                     <eg role="parse-test">
+let $powers := (
+  for $exp in 1 to 10
+  return math:pow(2, $exp)
+)
+return sum($powers)
+                     </eg>
+                  </p>
+               </item>
+               <item>
+                  <p>Doubles the values of a sequence, compares the values pairwise with another
+                     sequence, checks if some comparisons were successful, and returns
+                     <code>true</code>.</p>
+                  <eg role="parse-test">
+(1 to 4)
+-> for-each(., op('+'))
+-> for-each-pair(4 to 7, ., op('>'))
+-> some(.)
+                  </eg>
+                  <p>An equivalent expression is:
+                     <eg role="parse-test">
+let $data := 1 to 4
+let $data := for-each($data, op('+'))
+let $data := for-each-pair(4 to 7, $data, op('>'))
+return some($data)
+                     </eg>
+                  </p>
+               </item>
+               <item>
+                  <p>Reduces a long sequence to at most 9 elements, with dots appended,
+                  and returns a single string.</p>
+                  <eg role="parse-test">
+$dictionary/word
+-> (if(count(.) &lt; 10) then . else (.[1 to 9], '…'))
+-> string-join(., '; ')
+                  </eg>
+                  <p>An equivalent expression is:
+                     <eg role="parse-test">
+let $words := $dictionary/word
+let $chopped := (if(count($words) &lt; 10) then $words else ($words[1 to 9], '…'))
+return string-join($chopped, '; ')
+                     </eg>
+                  </p>
+               </item>
+            </ulist>
+         </example>
+      </div2>
+
       <div2 id="id-map-operator">
          <head>Simple map operator (<code>!</code>)</head>