From 4dcb68d9b9596312815a4aae87124c173fecef79 Mon Sep 17 00:00:00 2001 From: Bob Nystrom Date: Sun, 24 Aug 2014 09:09:10 -0700 Subject: [PATCH] More work on the site. - Tweaked the design a bunch. - Started filling in core library docs. - Fixed some other prose. --- doc/site/core-libraries.markdown | 4 - doc/site/core-library.markdown | 313 +++++++++++++++++++++++++++++++ doc/site/functions.markdown | 4 +- doc/site/style.scss | 38 ++-- doc/site/template.html | 4 +- 5 files changed, 342 insertions(+), 21 deletions(-) delete mode 100644 doc/site/core-libraries.markdown create mode 100644 doc/site/core-library.markdown diff --git a/doc/site/core-libraries.markdown b/doc/site/core-libraries.markdown deleted file mode 100644 index 7f6809c1..00000000 --- a/doc/site/core-libraries.markdown +++ /dev/null @@ -1,4 +0,0 @@ -^title Core Libraries -^category reference - -**TODO** \ No newline at end of file diff --git a/doc/site/core-library.markdown b/doc/site/core-library.markdown new file mode 100644 index 00000000..1d473abe --- /dev/null +++ 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—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—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. + +### **<**(other), **>**(other), **<=**(other), **>=**(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** diff --git a/doc/site/functions.markdown b/doc/site/functions.markdown index 96c7e8ac..755d711e 100644 --- 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| diff --git a/doc/site/style.scss b/doc/site/style.scss index 157ebce2..78368548 100644 --- 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; diff --git a/doc/site/template.html b/doc/site/template.html index 77f32ceb..5297944c 100644 --- a/doc/site/template.html +++ b/doc/site/template.html @@ -48,7 +48,7 @@

reference