Deploy to GitHub Pages:

control-flow.html

@@ -263,6 +263,19 @@ for (i in [1, 2, 3, 4]) {
 }                           //> 3
 </pre>
 
+<h2>Continue statements <a href="#continue-statements" name="continue-statements" class="header-anchor">#</a></h2>
+<p>During the execution of a loop body, you might decide that you want to skip the 
+rest of this iteration and move on to the next one. You can use a <code>continue</code> 
+statement to do that. It&rsquo;s just the <code>continue</code> keyword all by itself. Execution
+will immediately jump to the beginning of the next loop iteration (and check the
+loop conditions).</p>
+<pre class="snippet">
+for (i in [1, 2, 3, 4]) {
+  System.print(i)           //> 1
+  if (i == 2) continue      //> 3
+}                           //> 4
+</pre>
+
 <h2>Numeric ranges <a href="#numeric-ranges" name="numeric-ranges" class="header-anchor">#</a></h2>
 <p>Lists are one common use for <code>for</code> loops, but sometimes you want to walk over a
 sequence of numbers, or loop a number of times. For that, you can create a

embedding/configuring-the-vm.html

@@ -108,19 +108,49 @@ executed, it relies on the host application to locate and read the source code
 for a module.</p>
 <p>The signature of this function is:</p>
 <pre class="snippet" data-lang="c">
-char* loadModule(WrenVM* vm, const char* name)
+WrenLoadModuleResult loadModule(WrenVM* vm, const char* name)
 </pre>
 
 <p>When a module is imported, Wren calls this and passes in the module&rsquo;s name. The
-host should return the source code for that module. Memory for the source should
-be allocated using the same allocator that the VM uses for other allocation (see
-below). Wren will take ownership of the returned string and free it later.</p>
+host should return the source code for that module in a <code>WrenLoadModuleResult</code> struct.</p>
+<pre class="snippet" data-lang="c">
+WrenLoadModuleResult myLoadModule(WrenVM* vm, const char* name) {
+  WrenLoadModuleResult result = {0};
+    result.source = getSourceForModule(name);
+  return result;
+}
+</pre>
+
 <p>The module loader is only be called once for any given module name. Wren caches
 the result internally so subsequent imports of the same module use the
 previously loaded code.</p>
 <p>If your host application isn&rsquo;t able to load a module with some name, it should
-return <code>NULL</code> and Wren will report that as a runtime error.</p>
-<p>If you don&rsquo;t use any <code>import</code> statements, you can leave this <code>NULL</code>.</p>
+make sure the <code>source</code> value is <code>NULL</code> when returned. Wren will then report that as a runtime error.</p>
+<p>If you don&rsquo;t use any <code>import</code> statements, you can leave the <code>loadModuleFn</code> field in
+the configuration set to <code>NULL</code> (the default).</p>
+<p>Additionally, the <code>WrenLoadModuleResult</code> allows us to add a callback for when Wren is 
+done with the <code>source</code>, so we can free the memory if needed.</p>
+<pre class="snippet" data-lang="c">
+
+static void loadModuleComplete(WrenVM* vm, 
+                               const char* module,
+                               WrenLoadModuleResult result) 
+{
+  if(result.source) {
+    //for example, if we used malloc to allocate
+    our source string, we use free to release it.
+    free((void*)result.source);
+  }
+}
+
+WrenLoadModuleResult myLoadModule(WrenVM* vm, const char* name) {
+  WrenLoadModuleResult result = {0};
+    result.onComplete = loadModuleComplete;
+    result.source = getSourceForModule(name);
+  return result;
+}
+</pre>
+
 <h3><strong><code>bindForeignMethodFn</code></strong> <a href="#bindforeignmethodfn" name="bindforeignmethodfn" class="header-anchor">#</a></h3>
 <p>The callback Wren uses to find a foreign method and bind it to a class. See
 <a href="/embedding/calling-c-from-wren.html">this page</a> for details. If your application defines no foreign
@@ -185,7 +215,7 @@ or function.</p>
 <h3><strong><code>reallocateFn</code></strong> <a href="#reallocatefn" name="reallocatefn" class="header-anchor">#</a></h3>
 <p>This lets you provide a custom memory allocation function. Its signature is:</p>
 <pre class="snippet" data-lang="c">
-void* reallocate(void* memory, size_t newSize)
+void* reallocate(void* memory, size_t newSize, void* userData)
 </pre>
 
 <p>Wren uses this one function to allocate, grow, shrink, and deallocate memory.

modularity.html

@@ -149,6 +149,16 @@ if (thirsty) {
 }
 </pre>
 
+<p>If you need to import a variable under a different name, you can use 
+<code>import "..." for Name as OtherName</code>. This looks up the top-level variable
+<code>Name</code> in <em>that</em> module, but declares a variable called <code>OtherName</code> in <em>this</em> module
+with its value.</p>
+<pre class="snippet">
+import "liquids" for Water //Water is now taken
+import "beverages" for Coffee, Water as H2O, Tea
+// var water = H2O.new()
+</pre>
+
 <p>If you want to load a module, but not bind any variables from it, you can omit
 the <code>for</code> clause:</p>
 <pre class="snippet">
@@ -182,16 +192,16 @@ WrenVM* vm = wrenNewVM(&config);
 
 <p>That function has this signature:</p>
 <pre class="snippet" data-lang="c">
-char* WrenLoadModuleFn(WrenVM* vm, const char* name);
+WrenLoadModuleResult WrenLoadModuleFn(WrenVM* vm, const char* name);
 </pre>
 
 <p>Whenever a module is imported, the VM calls this and passes it the name of the
 module. The embedder is expected to return the source code contents of the
-module. When you embed Wren in your app, you can handle this however you want:
-reach out to the file system, look inside resources bundled into your app,
-whatever.</p>
-<p>You can return <code>NULL</code> from this function to indicate that a module couldn&rsquo;t be
-found. When you do this, Wren will report it as a runtime error.</p>
+module in a <code>WrenLoadModuleResult</code>. When you embed Wren in your app, you can handle
+this however you want: reach out to the file system, look inside resources bundled
+into your app, whatever.</p>
+<p>You can return the source field as <code>NULL</code> from this function to indicate that a module
+couldn&rsquo;t be found. When you do this, Wren will report it as a runtime error.</p>
 <h3>The command-line loader <a href="#the-command-line-loader" name="the-command-line-loader" class="header-anchor">#</a></h3>
 <p>The <a href="getting-started.html#using-the-wren-cli">Wren CLI command-line tool</a> has a very simple
 lookup process. It appends the module name and &ldquo;.wren&rdquo; to the directory where

modules/core/fiber.html

@@ -217,6 +217,22 @@ var error = fiber.try()
 System.print("Caught error: " + error)
 </pre>
 
+<p>If the called fiber raises an error, it can no longer be used.</p>
+<h3><strong>try</strong>(value) <a href="#try(value)" name="try(value)" class="header-anchor">#</a></h3>
+<p>Tries to run the fiber. If a runtime error occurs
+in the called fiber, the error is captured and is returned as a string.
+If the fiber is being
+started for the first time, and its function takes a parameter, <code>value</code> is
+passed to it.</p>
+<pre class="snippet">
+var fiber = Fiber.new {|value|
+  value.badMethod
+}
+
+var error = fiber.try("just a string")
+System.print("Caught error: " + error)
+</pre>
+
 <p>If the called fiber raises an error, it can no longer be used.</p>
 <h3><strong>transfer</strong>() <a href="#transfer()" name="transfer()" class="header-anchor">#</a></h3>
 <p><strong>TODO</strong></p>

modules/core/list.html

@@ -97,6 +97,14 @@
 <p>Removes all elements from the list.</p>
 <h3><strong>count</strong> <a href="#count" name="count" class="header-anchor">#</a></h3>
 <p>The number of elements in the list.</p>
+<h3><strong>indexOf(value)</strong> <a href="#indexof(value)" name="indexof(value)" class="header-anchor">#</a></h3>
+<p>Returns the index of <code>value</code> in the list, if found. If not found, returns -1.</p>
+<pre class="snippet">
+var list = [0, 1, 2, 3, 4]
+System.print(list.indexOf(3)) //> 3
+System.print(list.indexOf(20)) //> -1
+</pre>
+
 <h3><strong>insert</strong>(index, item) <a href="#insert(index,-item)" name="insert(index,-item)" class="header-anchor">#</a></h3>
 <p>Inserts the <code>item</code> at <code>index</code> in the list.</p>
 <pre class="snippet">
@@ -145,6 +153,32 @@ System.print(["a", "b", "c"].removeAt(1)) //> b
 </pre>
 
 <p>It is a runtime error if the index is not an integer or is out of bounds.</p>
+<h3><strong>sort</strong>(), <strong>sort</strong>(comparer) <a href="#sort(),-sort(comparer)" name="sort(),-sort(comparer)" class="header-anchor">#</a></h3>
+<p>Sorts the elements of a list in-place; altering the list. The default sort is implemented using the quicksort algorithm.</p>
+<pre class="snippet">
+var list = [4, 1, 3, 2].sort()
+System.print(list) //> [1, 2, 3, 4]
+</pre>
+
+<p>A comparison function <code>comparer</code> can be provided to customise the element sorting. The comparison function must return a boolean value specifying the order in which elements should appear in the list.</p>
+<p>The comparison function accepts two arguments <code>a</code> and <code>b</code>, two values to compare, and must return a boolean indicating the inequality between the arguments. If the function returns true, the first argument <code>a</code> will appear before the second <code>b</code> in the sorted results.</p>
+<p>A compare function like <code>{|a, b| true }</code> will always put <code>a</code> before <code>b</code>. The default compare function is <code>{|a, b| a &lt; b }</code>.</p>
+<pre class="snippet">
+var list = [9, 6, 8, 7]
+list.sort {|a, b| a < b}
+System.print(list) //> [6, 7, 8, 9]
+</pre>
+
+<p>It is a runtime error if <code>comparer</code> is not a function.</p>
+<h3><strong>swap</strong>(index0, index1) <a href="#swap(index0,-index1)" name="swap(index0,-index1)" class="header-anchor">#</a></h3>
+<p>Swaps values inside the list around. Puts the value from <code>index0</code> in <code>index1</code>,
+and the value from <code>index1</code> at <code>index0</code> in the list.</p>
+<pre class="snippet">
+var list = [0, 1, 2, 3, 4]
+list.swap(0, 3)
+System.print(list) //> [3, 1, 2, 0, 4]
+</pre>
+
 <h3><strong>[</strong>index<strong>]</strong> operator <a href="#[index]-operator" name="[index]-operator" class="header-anchor">#</a></h3>
 <p>Gets the element at <code>index</code>. If <code>index</code> is negative, it counts backwards from
 the end of the list where <code>-1</code> is the last element.</p>

modules/core/num.html

@@ -87,8 +87,15 @@
 <p>Attempts to parse <code>value</code> as a decimal literal and return it as an instance of
 <code>Num</code>. If the number cannot be parsed <code>null</code> will be returned.</p>
 <p>It is a runtime error if <code>value</code> is not a string.</p>
+<h3>Num.<strong>infinity</strong> <a href="#num.infinity" name="num.infinity" class="header-anchor">#</a></h3>
+<p>The value of &infinity;.</p>
+<h3>Num.<strong>nan</strong> <a href="#num.nan" name="num.nan" class="header-anchor">#</a></h3>
+<p>One value representing a NaN.</p>
+<p>Provides a default sane NaN number suitable for the vm internal values.</p>
 <h3>Num.<strong>pi</strong> <a href="#num.pi" name="num.pi" class="header-anchor">#</a></h3>
 <p>The value of &pi;.</p>
+<h3>Num.<strong>tau</strong> <a href="#num.tau" name="num.tau" class="header-anchor">#</a></h3>
+<p>The value of &tau;.</p>
 <h3>Num.<strong>largest</strong> <a href="#num.largest" name="num.largest" class="header-anchor">#</a></h3>
 <p>The largest representable numeric value.</p>
 <h3>Num.<strong>smallest</strong> <a href="#num.smallest" name="num.smallest" class="header-anchor">#</a></h3>
@@ -149,6 +156,14 @@ System.print(2.3.isInteger) //> false
 <p>The binary (base-2) logarithm of the number. Returns <code>nan</code> if the base is negative.</p>
 <h3><strong>exp</strong> <a href="#exp" name="exp" class="header-anchor">#</a></h3>
 <p>The exponential <code>e</code> (Euler’s number) raised to the number. This: <code>eⁿ</code>. </p>
+<h3><strong>min</strong>(other) <a href="#min(other)" name="min(other)" class="header-anchor">#</a></h3>
+<p>Returns the minimum value when comparing this number and <code>other</code>.</p>
+<h3><strong>max</strong>(other) <a href="#max(other)" name="max(other)" class="header-anchor">#</a></h3>
+<p>Returns the maximum value when comparing this number and <code>other</code>.</p>
+<h3><strong>clamp</strong>(min, max) <a href="#clamp(min,-max)" name="clamp(min,-max)" class="header-anchor">#</a></h3>
+<p>Clamps a number into the range of <code>min</code> and <code>max</code>. If this number is less than min, 
+<code>min</code> is returned. If bigger than <code>max</code>, <code>max</code> is returned. Otherwise, the number 
+itself is returned.</p>
 <h3><strong>pow</strong>(power) <a href="#pow(power)" name="pow(power)" class="header-anchor">#</a></h3>
 <p>Raises this number (the base) to <code>power</code>. Returns <code>nan</code> if the base is negative.</p>
 <h3><strong>round</strong> <a href="#round" name="round" class="header-anchor">#</a></h3>

syntax.html

@@ -142,7 +142,7 @@ even if the code already contains block comments.</p>
 <p>One way to get a quick feel for a language&rsquo;s style is to see what words it
 reserves. Here&rsquo;s what Wren has:</p>
 <pre class="snippet">
-break class construct else false for foreign if import
+as break class construct else false for foreign if import
 in is null return static super this true var while
 </pre>