deploy: 2518073

index.html

@@ -645,18 +645,34 @@
 keep in mind that all the values were sequentially pushed into the <code>generated</code> field, and we see only the final value.</p>
 <pre><code class="language-json"><span class="hl-1">&gt; .init -f example/myGenerator.json --xf example/myGenerator.mjs</span><br/><span class="hl-1">{</span><br/><span class="hl-1">  </span><span class="hl-5">&quot;generated&quot;</span><span class="hl-1">: </span><span class="hl-2">&quot;${$myGenerator()}&quot;</span><br/><span class="hl-1">}</span><br/><span class="hl-1">&gt; .out</span><br/><span class="hl-1">{</span><br/><span class="hl-1">  </span><span class="hl-5">&quot;generated&quot;</span><span class="hl-1">: </span><span class="hl-6">10</span><br/><span class="hl-1">}</span>
 </code><button>Copy</button></pre>
+<p>If you are familiar with generators in JS, you know that generated values take a verbose form in which 
+a <code>{value, done}</code> object is <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncGenerator/next#return_value">returned</a>.
+If you wish to use the more verbose JS style of yielded/returned object, you can pass your generator 
+to <code>$generate</code> and disable <code>valuesOnly</code>, as follows. Notice how the yielded values now contain the JS style 
+<code>{value, done}</code></p>
+<pre><code class="language-json"><span class="hl-1">&gt; .init -f example/myGeneratorVerbose.json --xf example/myGenerator.mjs</span><br/><span class="hl-1">{</span><br/><span class="hl-1">  </span><span class="hl-5">&quot;generated&quot;</span><span class="hl-1">: </span><span class="hl-2">&quot;${$myGenerator()~&gt;$generate({&#39;valueOnly&#39;:false})}&quot;</span><br/><span class="hl-1">}</span><br/><span class="hl-1">&gt; .out</span><br/><span class="hl-1">{</span><br/><span class="hl-1">  </span><span class="hl-5">&quot;generated&quot;</span><span class="hl-1">: {</span><br/><span class="hl-1">    </span><span class="hl-5">&quot;value&quot;</span><span class="hl-1">: </span><span class="hl-6">10</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-5">&quot;done&quot;</span><span class="hl-1">: </span><span class="hl-4">true</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-5">&quot;return&quot;</span><span class="hl-1">: </span><span class="hl-2">&quot;{function:}&quot;</span><br/><span class="hl-1">  }</span><br/><span class="hl-1">}</span>
+</code><button>Copy</button></pre>
 <p>A slight variation on the example accumulates every value yielded by the generator:</p>
-<pre><code class="language-json"><span class="hl-1">&gt; .init -f example/myGenerator</span><span class="hl-6">2</span><span class="hl-1">.json --xf example/myGenerator.mjs</span><br/><span class="hl-1">{</span><br/><span class="hl-1">   </span><span class="hl-5">&quot;generated&quot;</span><span class="hl-1">: </span><span class="hl-2">&quot;${$myGenerator()}&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">   </span><span class="hl-5">&quot;onGenerated&quot;</span><span class="hl-1">: </span><span class="hl-2">&quot;${$set(&#39;/accumulator/-&#39;, $$.generated)}&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">   </span><span class="hl-5">&quot;accumulator&quot;</span><span class="hl-1">: []</span><br/><span class="hl-1">}</span>
+<pre><code class="language-json"><span class="hl-1">&gt;  .init -f example/myGenerator</span><span class="hl-6">2</span><span class="hl-1">.json --xf example/myGenerator.mjs</span><br/><span class="hl-1">{</span><br/><span class="hl-1">  </span><span class="hl-5">&quot;generated&quot;</span><span class="hl-1">: </span><span class="hl-2">&quot;${$myGenerator()}&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-5">&quot;onGenerated&quot;</span><span class="hl-1">: </span><span class="hl-2">&quot;${$set(&#39;/accumulator/-&#39;, $$.generated)}&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-5">&quot;accumulator&quot;</span><span class="hl-1">: []</span><br/><span class="hl-1">}</span><br/>
 </code><button>Copy</button></pre>
 <pre><code class="language-json"><span class="hl-1">&gt; .init -f example/myGenerator</span><span class="hl-6">2</span><span class="hl-1">.json --xf example/myGenerator.mjs --tail </span><span class="hl-2">&quot;/accumulator until $=[1,2,3,4,5,6,7,8,9,10]&quot;</span><br/><span class="hl-1">Started tailing... Press Ctrl+C to stop.</span><br/><span class="hl-1">[</span><br/><span class="hl-6">1</span><span class="hl-1">,</span><br/><span class="hl-6">2</span><span class="hl-1">,</span><br/><span class="hl-6">3</span><span class="hl-1">,</span><br/><span class="hl-6">4</span><span class="hl-1">,</span><br/><span class="hl-6">5</span><span class="hl-1">,</span><br/><span class="hl-6">6</span><span class="hl-1">,</span><br/><span class="hl-6">7</span><span class="hl-1">,</span><br/><span class="hl-6">8</span><span class="hl-1">,</span><br/><span class="hl-6">9</span><span class="hl-1">,</span><br/><span class="hl-6">10</span><br/><span class="hl-1">]</span><br/>
 </code><button>Copy</button></pre>
-<p>Or, you can use the built in <code>$generate</code> method, which takes an optional delay in ms, and turns the array
-into an AsyncGenerator. In the example below the values 1 to 10 are pumped into the <code>generated</code> field
-with 10 ms temporal separation.</p>
-<pre><code class="language-json"><span class="hl-1">&gt; .init -f example/generate.json</span><br/><span class="hl-1">{</span><br/><span class="hl-1">  </span><span class="hl-5">&quot;delayMs&quot;</span><span class="hl-1">: </span><span class="hl-6">250</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-5">&quot;generated&quot;</span><span class="hl-1">:</span><span class="hl-2">&quot;${[1..10]~&gt;$generate(delayMs)}&quot;</span><br/><span class="hl-1">}</span>
+<p>You already saw hoe the built-in <code>$generate</code> function can accept a JS AsyncGeneraotr, and options. But $generate 
+can also be used to convert ordinary arrays or functions into async generators. When provided, the <code>interval</code> option, 
+causes the provided array to yield its elements periodically. When a function is provided, as opposed to an array, the
+function is called periodically.</p>
+<pre><code class="language-json"><span class="hl-1">&gt; .init -f example/generate.json</span><br/><span class="hl-1">{</span><br/><span class="hl-1">  </span><span class="hl-5">&quot;delayMs&quot;</span><span class="hl-1">: </span><span class="hl-6">250</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-5">&quot;generated&quot;</span><span class="hl-1">:</span><span class="hl-2">&quot;${[1..10]~&gt;$generate({&#39;interval&#39;:delayMs})}&quot;</span><br/><span class="hl-1">}</span>
 </code><button>Copy</button></pre>
 <pre><code class="language-json"><span class="hl-1">&gt; .init -f example/generate.json --tail </span><span class="hl-2">&quot;/ until generated=10&quot;</span><br/><span class="hl-1">Started tailing... Press Ctrl+C to stop.</span><br/><span class="hl-1">{</span><br/><span class="hl-5">&quot;delayMs&quot;</span><span class="hl-1">: </span><span class="hl-6">10</span><span class="hl-1">,</span><br/><span class="hl-5">&quot;generated&quot;</span><span class="hl-1">: </span><span class="hl-6">10</span><br/><span class="hl-1">}</span><br/>
 </code><button>Copy</button></pre>
+<p>This <code>example/myGenerator3.yaml</code> shows how you can call <code>return</code> and stop a generator.</p>
+<pre><code class="language-yaml"><span class="hl-11">generated</span><span class="hl-1">: </span><span class="hl-12">${$generate($random, {&#39;interval&#39;:10, &#39;valueOnly&#39;:false})}</span><br/><span class="hl-11">onGenerated</span><span class="hl-1">: </span><span class="hl-8">|</span><br/><span class="hl-12">  ${</span><br/><span class="hl-12">    $count(accumulator)&lt;3</span><br/><span class="hl-12">      ? $set(&#39;/accumulator/-&#39;, $$.generated.value)</span><br/><span class="hl-12">      : generated.return() /* shut off the generator when the accumulator has 10 items */</span><br/><span class="hl-12">  }</span><br/><span class="hl-11">accumulator</span><span class="hl-1">: []</span>
+</code><button>Copy</button></pre>
+<pre><code class="language-json"><span class="hl-1">&gt; .init -f example/myGenerator</span><span class="hl-6">3</span><span class="hl-1">.yaml --tail </span><span class="hl-2">&quot;/ until $count(accumulator)=3&quot;</span><br/><span class="hl-1">Started tailing... Press Ctrl+C to stop.</span><br/><span class="hl-1">{</span><br/><span class="hl-1">  </span><span class="hl-5">&quot;generated&quot;</span><span class="hl-1">: {</span><br/><span class="hl-1">    </span><span class="hl-5">&quot;value&quot;</span><span class="hl-1">: </span><span class="hl-6">0.23433826655570145</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-5">&quot;done&quot;</span><span class="hl-1">: </span><span class="hl-4">false</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-5">&quot;return&quot;</span><span class="hl-1">: </span><span class="hl-2">&quot;{function:}&quot;</span><br/><span class="hl-1">  },</span><br/><span class="hl-1">  </span><span class="hl-5">&quot;onGenerated&quot;</span><span class="hl-1">: {</span><br/><span class="hl-1">    </span><span class="hl-5">&quot;value&quot;</span><span class="hl-1">: </span><span class="hl-4">null</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-5">&quot;done&quot;</span><span class="hl-1">: </span><span class="hl-4">true</span><br/><span class="hl-1">  },</span><br/><span class="hl-1">  </span><span class="hl-5">&quot;accumulator&quot;</span><span class="hl-1">: [</span><br/><span class="hl-1">    </span><span class="hl-6">0.23433826655570145</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-6">0.23433826655570145</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-6">0.23433826655570145</span><br/><span class="hl-1">  ]</span><br/><span class="hl-1">}</span><br/><br/>
+</code><button>Copy</button></pre>
+<p>The <code>maxYield</code> parameter can also be used to stop a generator:</p>
+<pre><code class="language-json"><span class="hl-1">&gt; .init -f example/myGenerator</span><span class="hl-6">4</span><span class="hl-1">.yaml</span><br/><span class="hl-1">{</span><br/><span class="hl-1">  </span><span class="hl-5">&quot;generated&quot;</span><span class="hl-1">: </span><span class="hl-2">&quot;${$generate($random, {&#39;interval&#39;:10, &#39;maxYield&#39;:5})}&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-5">&quot;onGenerated&quot;</span><span class="hl-1">: </span><span class="hl-2">&quot;${$set(&#39;/accumulator/-&#39;, $$.generated)}&quot;</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-5">&quot;accumulator&quot;</span><span class="hl-1">: []</span><br/><span class="hl-1">}</span><br/><span class="hl-1">&gt; .init -f example/myGenerator</span><span class="hl-6">4</span><span class="hl-1">.yaml --tail </span><span class="hl-2">&quot;/ until $count(accumulator)=5&quot;</span><br/><span class="hl-1">{</span><br/><span class="hl-1">  </span><span class="hl-5">&quot;generated&quot;</span><span class="hl-1">: </span><span class="hl-6">0.5289126250886866</span><span class="hl-1">,</span><br/><span class="hl-1">  </span><span class="hl-5">&quot;onGenerated&quot;</span><span class="hl-1">: [</span><br/><span class="hl-1">    </span><span class="hl-2">&quot;/accumulator/-&quot;</span><br/><span class="hl-1">  ],</span><br/><span class="hl-1">  </span><span class="hl-5">&quot;accumulator&quot;</span><span class="hl-1">: [</span><br/><span class="hl-1">    </span><span class="hl-6">0.3260049204634301</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-6">0.4477190160739559</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-6">0.9414436597923774</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-6">0.8593436891141426</span><span class="hl-1">,</span><br/><span class="hl-1">    </span><span class="hl-6">0.5289126250886866</span><br/><span class="hl-1">  ]</span><br/><span class="hl-1">}</span>
+</code><button>Copy</button></pre>
 <a id="md:settimeout" class="tsd-anchor"></a><h3><a href="#md:settimeout">$setTimeout</a></h3><p><code>$setTimeout</code> is the JavaScript <code>setTimeout</code> function. It receives a function and an timeout
 expressed as milliseconds. The function is called after the timeout. Example <code>ex15.json</code> demonstrates an 
 intersting use of <code>$setTimout</code>. The <code>counter</code> variable is updates, which causes <code>upCount$</code> to re-evaluate due to