Meson/wren
1
0
Fork 0
forked from Mirror/wren
Code Pull Requests Activity

Reorganize core library docs.

Browse Source
This commit is contained in:
Bob Nystrom
2015-01-18 15:36:36 -08:00
parent 50c0cbe8c3
commit 2a4804bbc9
17 changed files with 543 additions and 418 deletions
Download Patch File Download Diff File Expand all files Collapse all files

399
doc/site/core-library.markdown
View File

@ -1,399 +0,0 @@
^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
Returns the logical complement of 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#block-arguments) 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**
## Null Class
### **!** operator
Returns `true`, since `null` is considered [false](control-flow.html#truth).
> !null
true
## 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**
## Object Class
### **!** operator
Returns `false`, since most objects are considered [true](control-flow.html#truth).
## String Class
A string of Unicode code points stored in UTF-8.
### **contains**(other)
Checks if `other` is a substring of the string.
It is a runtime error if `other` is not a string.
### **count**
Returns the length of the string.
### **endsWith(suffix)**
Checks if the string ends with `suffix`.
It is a runtime error if `suffix` is not a string.
### **indexOf(search)**
Returns the index of `search` in the string or -1 if `search` is not a
substring of the string.
It is a runtime error if `search` is not a string.
### **startsWith(prefix)**
Checks if the string starts with `prefix`.
It is a runtime error if `prefix` is not a string.
### **+**(other) operator
Returns a new string that concatenates this string and `other`.
It is a runtime error if `other` is not a string.
### **==**(other) operator
Checks if the string is equal to `other`.
### **!=**(other) operator
Check if the string is not equal to `other`.
### **[**index**]** operator
Returns a one character string of the value at `index`.
It is a runtime error if `index` is greater than the length of the string.
*Note: This does not currently handle UTF-8 characters correctly.*
## List Class
**TODO**
Extends [Sequence](#sequence-class).
### **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**
Extends [Sequence](#sequence-class).
### **from**
**TODO**
### **to**
**TODO**
### **min**
**TODO**
### **max**
**TODO**
### **isInclusive**
**TODO**
### **iterate**(iterator), **iteratorValue**(iterator)
**TODO**
## Sequence Class
An abstract base class for any iterable object. It provides a number of methods for working with sequences based on the core [iterator protocol](control-flow.html#the-iterator-protocol).
### **all**(predicate)
Tests whether all the elements in the list pass the `predicate`.
### **reduce**(function)
Reduces the sequence down to a single value. `function` is a function that takes two arguments, the accumulator and sequence item and returns the new accumulator value. The accumulator is initialized from the first item in the sequence. Then, the function is invoked on each remaining item in the sequence, iteratively updating the accumulator.
It is a runtime error to call this on an empty sequence.
### **reduce**(seed, function)
Similar to above, but uses `seed` for the initial value of the accumulator. If the sequence is empty, returns `seed`.

17
doc/site/core/bool.markdown Normal file
View File

@ -0,0 +1,17 @@
^title Bool Class
^category core
Boolean values. There are two instances, `true` and `false`.
### **!** operator
Returns the logical complement of the value.
> !true
false
> !false
true
### toString
The string representation of the value, either `"true"` or `"false"`.

6
doc/site/core/class.markdown Normal file
View File

@ -0,0 +1,6 @@
^title Class Class
^category core
### **name**
The name of the class.

87
doc/site/core/fiber.markdown Normal file
View File

@ -0,0 +1,87 @@
^title Fiber Class
^category core
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**

23
doc/site/core/fn.markdown Normal file
View File

@ -0,0 +1,23 @@
^title Fn Class
^category core
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#block-arguments) 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**

4
doc/site/core/index.markdown Normal file
View File

@ -0,0 +1,4 @@
^title Core Library
^category core
**TODO**

38
doc/site/core/list.markdown Normal file
View File

@ -0,0 +1,38 @@
^title List Class
^category core
**TODO**
Extends [Sequence](sequence.html).
### **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**

9
doc/site/core/null.markdown Normal file
View File

@ -0,0 +1,9 @@
^title Null Class
^category core
### **!** operator
Returns `true`, since `null` is considered [false](../control-flow.html#truth).
> !null
true

92
doc/site/core/num.markdown Normal file
View File

@ -0,0 +1,92 @@
^title Num Class
^category core
**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**

20
doc/site/core/object.markdown Normal file
View File

@ -0,0 +1,20 @@
^title Object Class
^category core
### **!** operator
Returns `false`, since most objects are considered [true](control-flow.html#truth).
### **==**(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.

30
doc/site/core/range.markdown Normal file
View File

@ -0,0 +1,30 @@
^title Range Class
^category core
**TODO**
Extends [Sequence](sequence.html).
### **from**
**TODO**
### **to**
**TODO**
### **min**
**TODO**
### **max**
**TODO**
### **isInclusive**
**TODO**
### **iterate**(iterator), **iteratorValue**(iterator)
**TODO**

18
doc/site/core/sequence.markdown Normal file
View File

@ -0,0 +1,18 @@
^title Sequence Class
^category core
An abstract base class for any iterable object. It provides a number of methods for working with sequences based on the core [iterator protocol](../control-flow.html#the-iterator-protocol).
### **all**(predicate)
Tests whether all the elements in the list pass the `predicate`.
### **reduce**(function)
Reduces the sequence down to a single value. `function` is a function that takes two arguments, the accumulator and sequence item and returns the new accumulator value. The accumulator is initialized from the first item in the sequence. Then, the function is invoked on each remaining item in the sequence, iteratively updating the accumulator.
It is a runtime error to call this on an empty sequence.
### **reduce**(seed, function)
Similar to above, but uses `seed` for the initial value of the accumulator. If the sequence is empty, returns `seed`.

55
doc/site/core/string.markdown Normal file
View File

@ -0,0 +1,55 @@
^title String Class
^category core
A string of Unicode code points stored in UTF-8.
### **contains**(other)
Checks if `other` is a substring of the string.
It is a runtime error if `other` is not a string.
### **count**
Returns the length of the string.
### **endsWith(suffix)**
Checks if the string ends with `suffix`.
It is a runtime error if `suffix` is not a string.
### **indexOf(search)**
Returns the index of `search` in the string or -1 if `search` is not a
substring of the string.
It is a runtime error if `search` is not a string.
### **startsWith(prefix)**
Checks if the string starts with `prefix`.
It is a runtime error if `prefix` is not a string.
### **+**(other) operator
Returns a new string that concatenates this string and `other`.
It is a runtime error if `other` is not a string.
### **==**(other) operator
Checks if the string is equal to `other`.
### **!=**(other) operator
Check if the string is not equal to `other`.
### **[**index**]** operator
Returns a one character string of the value at `index`.
It is a runtime error if `index` is greater than the length of the string.
*Note: This does not currently handle UTF-8 characters correctly.*

52
doc/site/style.scss
View File

@ -24,6 +24,11 @@ $link-hover: hsl(210, 100%, 80%);
$link-dark: hsl(210, 60%, 20%); $link-dark: hsl(210, 60%, 20%);
$link-glow: hsla(210, 100%, 50%, 0.4); $link-glow: hsla(210, 100%, 50%, 0.4);
$core-link: hsl(150, 70%, 40%);
$core-link-hover: hsl(130, 70%, 70%);
$core-link-dark: hsl(160, 60%, 25%);
$core-link-glow: hsla(130, 90%, 50%, 0.4);
* { * {
-moz-box-sizing: border-box; -moz-box-sizing: border-box;
box-sizing: border-box; box-sizing: border-box;
@ -238,6 +243,53 @@ footer {
span.se { color: hsl(30, 80%, 50%); } span.se { color: hsl(30, 80%, 50%); }
} }
// Have a different primary color for the core library docs.
body.core {
header {
a {
color: $gray-20;
}
a:hover {
color: $core-link-hover;
text-shadow: 0 0 6px $core-link-glow;
}
}
a {
color: $core-link;
}
a:hover {
color: $core-link-dark;
}
.header-anchor {
color: $light;
}
main {
h1, h2, h3 {
color: $core-link;
}
h2:hover > .header-anchor:hover,
h3:hover > .header-anchor:hover {
color: $core-link-dark;
}
}
footer {
a {
color: $core-link-hover;
}
a:hover {
color: $core-link;
}
}
}
// Bar charts on the performance page. // Bar charts on the performance page.
table.chart { table.chart {
width: 100%; width: 100%;

56
doc/site/template-core.html Normal file
View File

@ -0,0 +1,56 @@
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-type" content="text/html;charset=UTF-8" />
<title>{title} – Wren</title>
<link rel="stylesheet" type="text/css" href="../style.css" />
<link href='//fonts.googleapis.com/css?family=Source+Sans+Pro:400,700,400italic,700italic|Source+Code+Pro:400|Lato:400|Sanchez:400italic,400' rel='stylesheet' type='text/css'>
<!-- Tell mobile browsers we're optimized for them and they don't need to crop
the viewport. -->
<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1"/>
</head>
<body id="top" class="core">
<header>
<div class="page">
<div class="main-column">
<h1><a href="../">wren</a></h1>
<h2>a classy little scripting language</h2>
</div>
</div>
</header>
<div class="page">
<nav>
<ul>
<li><a href="./">Core Library</a></li>
</ul>
<section>
<h2>core classes</h2>
<ul>
<li><a href="bool.html">Bool</a></li>
<li><a href="class.html">Class</a></li>
<li><a href="fiber.html">Fiber</a></li>
<li><a href="fn.html">Fn</a></li>
<li><a href="list.html">List</a></li>
<li><a href="null.html">Null</a></li>
<li><a href="num.html">Num</a></li>
<li><a href="object.html">Object</a></li>
<li><a href="range.html">Range</a></li>
<li><a href="sequence.html">Sequence</a></li>
<li><a href="string.html">String</a></li>
</ul>
</section>
</nav>
<main>
<h1>{title}</h1>
{html}
</main>
</div>
<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 <a href="http://journal.stuffwithstuff.com/">Bob Nystrom</a>.</p>
<div class="main-column">
</div>
</footer>
</body>
</html>

4
doc/site/template.html
View File

@ -13,7 +13,7 @@
<header> <header>
<div class="page"> <div class="page">
<div class="main-column"> <div class="main-column">
<h1><a href="index.html">wren</a></h1> <h1><a href="./">wren</a></h1>
<h2>a classy little scripting language</h2> <h2>a classy little scripting language</h2>
</div> </div>
</div> </div>
@ -47,7 +47,7 @@
<section> <section>
<h2>reference</h2> <h2>reference</h2>
<ul> <ul>
<li><a href="core-library.html">Core Library</a></li> <li><a href="core">Core Library</a></li>
<li><a href="embedding-api.html">Embedding API</a></li> <li><a href="embedding-api.html">Embedding API</a></li>
<li><a href="performance.html">Performance</a></li> <li><a href="performance.html">Performance</a></li>
<li><a href="contributing.html">Contributing</a></li> <li><a href="contributing.html">Contributing</a></li>

51
script/generate_docs.py
View File

@ -1,7 +1,7 @@
#!/usr/bin/env python #!/usr/bin/env python
import glob import glob
import markdown import fnmatch
import os import os
import shutil import shutil
import subprocess import subprocess
@ -10,6 +10,20 @@ import time
import re import re
from datetime import datetime from datetime import datetime
import markdown
with open("doc/site/template.html") as f:
template = f.read()
with open("doc/site/template-core.html") as f:
template_core = f.read()
def ensure_dir(path):
if not os.path.exists(path):
os.mkdir(path)
def is_up_to_date(path, out_path): def is_up_to_date(path, out_path):
# See if it's up to date. # See if it's up to date.
source_mod = os.path.getmtime(path) source_mod = os.path.getmtime(path)
@ -24,9 +38,10 @@ def format_file(path, skip_up_to_date):
basename = os.path.basename(path) basename = os.path.basename(path)
basename = basename.split('.')[0] basename = basename.split('.')[0]
out_path = "build/docs/" + basename + ".html" in_path = os.path.join('doc/site', path)
out_path = "build/docs/" + os.path.splitext(path)[0] + ".html"
if skip_up_to_date and is_up_to_date(path, out_path): if skip_up_to_date and is_up_to_date(in_path, out_path):
# It's up to date. # It's up to date.
return return
@ -35,7 +50,7 @@ def format_file(path, skip_up_to_date):
# Read the markdown file and preprocess it. # Read the markdown file and preprocess it.
contents = "" contents = ""
with open(path, "r") as input: with open(in_path, "r") as input:
# Read each line, preprocessing the special codes. # Read each line, preprocessing the special codes.
for line in input: for line in input:
stripped = line.lstrip() stripped = line.lstrip()
@ -68,9 +83,13 @@ def format_file(path, skip_up_to_date):
html = markdown.markdown(contents, ['def_list', 'codehilite']) html = markdown.markdown(contents, ['def_list', 'codehilite'])
modified = datetime.fromtimestamp(os.path.getmtime(path)) modified = datetime.fromtimestamp(os.path.getmtime(in_path))
mod_str = modified.strftime('%B %d, %Y') mod_str = modified.strftime('%B %d, %Y')
page_template = template
if category == 'core':
page_template = template_core
fields = { fields = {
'title': title, 'title': title,
'html': html, 'html': html,
@ -78,14 +97,13 @@ def format_file(path, skip_up_to_date):
'category': category 'category': category
} }
with open("doc/site/template.html") as f:
template = f.read()
# Write the html output. # Write the html output.
with open(out_path, 'w') as out: ensure_dir(os.path.dirname(out_path))
out.write(template.format(**fields))
print("converted " + basename) with open(out_path, 'w') as out:
out.write(page_template.format(**fields))
print("converted " + path)
def check_sass(): def check_sass():
@ -105,17 +123,16 @@ def check_sass():
def format_files(skip_up_to_date): def format_files(skip_up_to_date):
check_sass() check_sass()
for f in glob.iglob("doc/site/*.markdown"): for root, dirnames, filenames in os.walk('doc/site'):
format_file(f, skip_up_to_date) for filename in fnmatch.filter(filenames, '*.markdown'):
f = os.path.relpath(os.path.join(root, filename), 'doc/site')
format_file(f, skip_up_to_date)
# Clean the output directory. # Clean the output directory.
if not os.path.exists("build"):
os.mkdir("build")
if os.path.exists("build/docs"): if os.path.exists("build/docs"):
shutil.rmtree("build/docs") shutil.rmtree("build/docs")
os.mkdir("build/docs") ensure_dir("build/docs")
# Process each markdown file. # Process each markdown file.
format_files(False) format_files(False)