builtin.jq: whilst

docs/content/manual/manual.yml

@@ -1819,22 +1819,37 @@ sections:
             input: '"useful but not for é"'
             output: ['"USEFUL BUT NOT FOR é"']
 
-      - title: "`while(cond; update)`"
+      - title: "`while(cond; update)`, `whilst(cond; update)`"
         body: |
 
-          The `while(cond; update)` function allows you to repeatedly
+          These two functions allow you to repeatedly
           apply an update to `.` until `cond` is false.
 
-          Note that `while(cond; update)` is internally defined as a
-          recursive jq function.  Recursive calls within `while` will
-          not consume additional memory if `update` produces at most one
-          output for each input.  See advanced topics below.
+          `while(cond; update)` begins by emitting its input
+          unconditionally, and then applies `update` to that value; if
+          the updated value exists and is truthy (i.e. neither `false`
+          nor `null`), then that value is applied to `while(cond;
+          update)` recursively.
+
+          `whilst(cond; update)` is similar but begins by applying
+          `update` to the input without emitting it; if the updated
+          value exists and is truthy, it is output, and then applied
+          to `whilst(cond; update)` recursively.
+
+          Note that both `while` and `whilst` are defined as recursive
+          jq functions.  Recursive calls within these functions will
+          not consume additional memory if `update` produces at most
+          one output for each input.  See advanced topics below.
 
         examples:
           - program: '[while(.<100; .*2)]'
             input: '1'
             output: ['[1,2,4,8,16,32,64]']
 
+          - program: '[whilst(.<100; .*2)]'
+            input: '1'
+            output: ['[2,4,8,16,32,64,128]']
+
       - title: "`repeat(exp)`"
         body: |
 

src/builtin.jq

@@ -139,13 +139,18 @@ def gsub($re; s): sub($re; s; "g");
 ########################################################################
 # generic iterator/generator
 def while(cond; update):
-     def _while:
-         if cond then ., (update | _while) else empty end;
-     _while;
+  def _while:
+    if cond then ., (update | _while) else empty end;
+    _while;
+    # like while/2 but emit the final term rather than the first one
+def whilst(cond; update):
+  def _whilst: if cond then update | (., _whilst) else empty end;
+  _whilst;
 def until(cond; next):
-     def _until:
-         if cond then . else (next|_until) end;
-     _until;
+  def _until:
+  if cond then . else (next|_until) end;
+  _until;
+
 def limit($n; exp):
     if $n > 0 then label $out | foreach exp as $item ($n; .-1; $item, if . <= 0 then break $out else empty end)
     elif $n == 0 then empty

tests/jq.test

@@ -280,6 +280,10 @@ null
 1
 [1,2,4,8,16,32,64]
 
+[whilst(.<100; .*2)]
+1
+[2,4,8,16,32,64,128]
+
 [(label $here | .[] | if .>1 then break $here else . end), "hi!"]
 [0,1,2]
 [0,1,"hi!"]