More work on the site.

- Tweaked the design a bunch. - Started filling in core library docs. - Fixed some other prose.
2026-01-11 22:28:45 +01:00 · 2014-08-24 09:09:10 -07:00
parent d5f68d70f0
commit 4dcb68d9b9
5 changed files with 342 additions and 21 deletions
--- a/doc/site/core-libraries.markdown
+++ b/doc/site/core-libraries.markdown
@ -1,4 +0,0 @@
-^title Core Libraries
-^category reference
-
-**TODO**
--- a/doc/site/core-library.markdown
+++ b/doc/site/core-library.markdown
@ -0,0 +1,313 @@
+^title Core Library
+^category reference
+
+## Object Class
+
+### **==**(other) and **!=**(other) operators
+
+Compares two objects using built-in equality. This compares numbers by value, and all other objects are compared by identity&mdash;two objects are equal only if they are the exact same object.
+
+### **toString**
+
+A default string representation of the object.
+
+### **type**
+
+The [Class](#class-class) of the object.
+
+## Class Class
+
+### **name**
+
+The name of the class.
+
+## Bool Class
+
+Boolean values. There are two instances, `true` and `false`.
+
+### **!** operator
+
+Negates the value.
+
+    > !true
+    false
+    > !false
+    true
+
+### toString
+
+The string representation of the value, either `"true"` or `"false"`.
+
+## Fiber Class
+
+A lightweight coroutine. [Here](fibers.html) is a gentle introduction.
+
+### new **Fiber**(function)
+
+Creates a new fiber that executes `function` in a separate coroutine when the fiber is run. Does not immediately start running the fiber.
+
+    :::dart
+    var fiber = new Fiber {
+      IO.print("I won't get printed")
+    }
+
+### Fiber.**yield**
+
+Pauses the current fiber and transfers control to the parent fiber. "Parent" here means the last fiber that was started using `call` and not `run`.
+
+    :::dart
+    var fiber = new Fiber {
+      IO.print("Before yield")
+      Fiber.yield
+      IO.print("After yield")
+    }
+
+    fiber.call              // "Before yield"
+    IO.print("After call")  // "After call"
+    fiber.call              // "After yield"
+
+When resumed, the parent fiber's `call` method returns `null`.
+
+If a yielded fiber is resumed by calling `call()` or `run()` with an argument, `yield` returns that value.
+
+    :::dart
+    var fiber = new Fiber {
+      IO.print(Fiber.yield) // "value"
+    }
+
+    fiber.call          // Run until the first yield.
+    fiber.call("value") // Resume the fiber.
+
+If it was resumed by calling `call` or `run` with no argument, returns `null`.
+
+It is a runtime error to call this when there is no parent fiber to return to.
+
+    :::dart
+    Fiber.yield // ERROR
+
+    new Fiber {
+      Fiber.yield // ERROR
+    }.run
+
+### Fiber.**yield**(value)
+
+Similar to `Fiber.yield` but provides a value to return to the parent fiber's `call`.
+
+    :::dart
+    var fiber = new Fiber {
+      Fiber.yield("value")
+    }
+
+    IO.print(fiber.call) // "value"
+
+### **call**
+
+**TODO**
+
+### **call**(value)
+
+**TODO**
+
+### **isDone**
+
+Whether the fiber's main function has completed and the fiber can no longer be run. This returns `false` if the fiber is currently running or has yielded.
+
+### **run**
+
+**TODO**
+
+### **run**(value)
+
+**TODO**
+
+## Fn Class
+
+A first class function&mdash;an object that wraps an executable chunk of code. [Here](functions.html) is a friendly introduction.
+
+### new **Fn**(function)
+
+Creates a new function from... `function`. Of course, `function` is already be a function, so this really just returns the argument. It exists mainly to let you create a "bare" function when you don't want to immediately pass it as a [block argument](functions.html#creating-functions) to some other method.
+
+    :::dart
+    var fn = new Fn {
+      IO.print("The body")
+    }
+
+It is a runtime error if `block` is not a function.
+
+### **call**(args...)
+
+**TODO**
+
+## Num Class
+
+**TODO**
+
+### **abs**
+
+The absolute value of the number.
+
+    :::dart
+    -123.abs // 123
+
+### **ceil**
+
+**TODO**
+
+### **cos**
+
+The cosine of the number.
+
+### **floor**
+
+**TODO**
+
+### **isNan**
+
+Whether the number is [not a number](http://en.wikipedia.org/wiki/NaN). This is `false` for normal number values and infinities, and `true` for the result of `0/0`, the square root of a negative number, etc.
+
+### **sin**
+
+The sine of the number.
+
+### **sqrt**
+
+The square root of the number. Returns `nan` if the number is negative.
+
+### **-** operator
+
+Negates the number.
+
+    :::dart
+    var a = 123
+    -a // -123
+
+### **-**(other), **+**(other), **/**(other), **\***(other) operators
+
+The usual arithmetic operators you know and love. All of them do 64-bit floating point arithmetic. It is a runtime error if the right-hand operand is not a number. Wren doesn't roll with implicit conversions.
+
+### **%**(denominator) operator
+
+The floating-point remainder of this number divided by `denominator`.
+
+It is a runtime error if `denominator` is not a number.
+
+### **&lt;**(other), **&gt;**(other), **&lt;=**(other), **&gt;=**(other) operators
+
+Compares this and `other`, returning `true` or `false` based on how the numbers are ordered. It is a runtime error if `other` is not a number.
+
+### **~** operator
+
+Performs *bitwise* negation on the number. The number is first converted to a 32-bit unsigned value, which will truncate any floating point value. The bits of the result of that are then negated, yielding the result.
+
+### **&**(other) operator
+
+Performs bitwise and on the number. Both numbers are first converted to 32-bit unsigned values. The result is then a 32-bit unsigned number where each bit is `true` only where the corresponding bits of both inputs were `true`.
+
+It is a runtime error if `other` is not a number.
+
+### **|**(other) operator
+
+Performs bitwise or on the number. Both numbers are first converted to 32-bit unsigned values. The result is then a 32-bit unsigned number where each bit is `true` only where the corresponding bits of both inputs were `true`.
+
+It is a runtime error if `other` is not a number.
+
+### **..**(other) operator
+
+**TODO**
+
+### **...**(other) operator
+
+**TODO**
+
+## String Class
+
+**TODO**
+
+### **contains**(other)
+
+**TODO**
+
+### **count**
+
+**TODO**
+
+### **+**(other) operator
+
+**TODO**
+
+### **==**(other) operator
+
+**TODO**
+
+### **!=**(other) operator
+
+**TODO**
+
+### **[**index**]** operator
+
+**TODO**
+
+## List Class
+
+**TODO**
+
+### **add**(item)
+
+Appends `item` onto the end of the list.
+
+### **clear**
+
+Removes all items from the list.
+
+### **count**
+
+The number of items in the list.
+
+### **insert**(item, index)
+
+**TODO**
+
+### **iterate**(iterator), **iteratorValue**(iterator)
+
+**TODO**
+
+### **removeAt**(index)
+
+**TODO**
+
+### **[**index**]** operator
+
+**TODO**
+
+### **[**index**]=**(item) operator
+
+**TODO**
+
+## Range Class
+
+**TODO**
+
+### **from**
+
+**TODO**
+
+### **to**
+
+**TODO**
+
+### **min**
+
+**TODO**
+
+### **max**
+
+**TODO**
+
+### **isInclusive**
+
+**TODO**
+
+### **iterate**(iterator), **iteratorValue**(iterator)
+
+**TODO**
--- a/doc/site/functions.markdown
+++ b/doc/site/functions.markdown
@ -60,7 +60,7 @@ Once you have a function, how do you invoke it? Like everything in Wren, you do
      }
    }

-Functions expose a `call` method that executes the body of the function. Of course, this is dynamically-dispatched like other methods, so you can define your own "function-like" classes and pass them to methods that expect real functions.
+Functions expose a `call` method that executes the body of the function. This method is dynamically-dispatched like any other, so you can define your own "function-like" classes and pass them to methods that expect "real" functions.

    :::dart
    class FakeFn {
@ -73,7 +73,7 @@ Functions expose a `call` method that executes the body of the function. Of cour

 ## Function parameters

-Of course, functions aren't very useful if you can't pass values to them. The functions that we've seen so far take no parameters. To change that, you can provide a parameter list surrounded by `|` immediately after the opening brace of the body, like so:
+Of course, functions aren't very useful if you can't pass values to them. The functions that we've seen so far take no arguments. To change that, you can provide a parameter list surrounded by `|` immediately after the opening brace of the body, like so:

    :::dart
    blondie.callMe {|first, last|
--- a/doc/site/style.scss
+++ b/doc/site/style.scss
@ -4,6 +4,7 @@ $body: "Source Sans Pro", georgia, serif;
 $code: "Source Code Pro", Menlo, Monaco, Consolas, monospace;

 $dark: hsl(200, 20%, 30%);
+$darker: hsl(200, 20%, 10%);
 $light: hsl(0, 0%, 100%);
 $gray-10: mix($dark, $light, 10%);
 $gray-20: mix($dark, $light, 20%);
@ -16,11 +17,11 @@ $gray-80: mix($dark, $light, 80%);
 $text: mix($light, #000, 30%);

 $code-color: hsl(200, 20%, 40%);
-$code-bg:    hsl(200, 20%, 97%);
+$code-bg:    hsl(200, 20%, 98%);

 $link:        hsl(200, 40%, 50%);
 $link-hover:  hsl(200, 100%, 80%);
-$link-dark:   hsl(200, 80%, 30%);
+$link-dark:   hsl(200, 60%, 20%);
 $link-glow:  hsla(200, 100%, 50%, 0.4);

 * {
@ -36,7 +37,7 @@ body, code, h1, h2, h3, p, pre {
 body {
  background: $light;
  color: $text;
-  font: 17px/26px $body;
+  font: 16px/25px $body;
 }

 .page {
@ -57,12 +58,14 @@ body {
 }

 header {
+  text-shadow: 0 1px 1px $darker;
+
  .page {
    height: 120px;
  }

-  background: $gray-80;
-  border-bottom: solid 1px $dark;
+  background: $dark;
+  border-bottom: solid 1px $darker;

  h1 {
    position: absolute;
@ -133,7 +136,7 @@ h2 {
 }

 h3 {
-  font: 500 24px $header;
+  font: 18px $body;
  margin: 24px 0 0 0;
  color: $link;
 }
@ -176,38 +179,46 @@ p + p {
  margin-top: 20px;
 }

+main > p, main > pre {
+  margin-left: 25px;
+}
+
 code, pre {
  color: $code-color;
-  font: 14px $code;
+  font: 13px $code;
  background: $code-bg;
  border-radius: 2px;
-  border: solid 1px hsl(200, 20%, 93%);
-  border-bottom: solid 1px hsl(200, 20%, 80%);
+  border: solid 1px hsl(200, 20%, 95%);
+  border-bottom: solid 1px hsl(200, 20%, 90%);
 }

 code {
-  padding: 1px 3px;
+  padding: 1px 2px;
  white-space: nowrap;
 }

 pre {
  margin: 10px 0;
-  line-height: 20px;
+  line-height: 18px;
  padding: 10px;

  // Scroll horizontally if not wide enough.
  overflow: auto;
+
+  margin-left: 25px;
 }

 footer {
  margin-top: 20px;
  padding: 20px 0 40px 0;
  font: 14px $body;
-  background: $gray-80;
+  background: $dark;
  color: $gray-20;
-  border-top: solid 1px $dark;
+  border-top: solid 1px $darker;
  text-align: center;

+  text-shadow: 0 1px 1px $darker;
+
  a {
    color: $link-hover;
  }
@ -236,6 +247,7 @@ footer {
 // Bar charts on the performance page.
 table.chart {
  width: 100%;
+  padding-left: 25px;

  td, th {
    line-height: 14px;
--- a/doc/site/template.html
+++ b/doc/site/template.html
@ -48,7 +48,7 @@
    <section>
      <h2>reference</h2>
      <ul>
-        <li><a href="core-libraries.html">Core Libraries</a></li>
+        <li><a href="core-library.html">Core Library</a></li>
        <li><a href="embedding-api.html">Embedding API</a></li>
        <li><a href="performance.html">Performance</a></li>
        <li><a href="contributing.html">Contributing</a></li>
@ -64,7 +64,7 @@
 <footer>
  <div class="page">
    <div class="main-column">
-    <p>Wren lives <a href="https://github.com/munificent/wren">on GitHub</a> &mdash; Made with &#x2764; by Bob Nystrom.</p>
+    <p>Wren lives <a href="https://github.com/munificent/wren">on GitHub</a> &mdash; Made with &#x2764; by <a href="http://journal.stuffwithstuff.com/">Bob Nystrom</a>.</p>
    <div class="main-column">
  </div>
 </footer>