chore: reorganize doc site structure by moving core docs under modules/ and removing category metadata
Restructure the documentation hierarchy to prepare for documenting additional built-in modules. Move all core library documentation from `doc/site/core/` to `doc/site/modules/core/`, rename `modules.markdown` to `modularity.markdown`, remove `^category` metadata lines from all affected pages, update cross-reference links to use relative paths under the new structure, and add a TODO placeholder to the Class class page.
This commit is contained in:
Bob Nystrom
@@ -0,0 +1,19 @@
|
||||
^title Bool Class
|
||||
|
||||
Boolean [values][]. There are two instances, `true` and `false`.
|
||||
|
||||
[values]: ../../values.html
|
||||
|
||||
## Methods
|
||||
|
||||
### **!** operator
|
||||
|
||||
Returns the logical complement of the value.
|
||||
|
||||
:::wren
|
||||
System.print(!true) //> false
|
||||
System.print(!false) //> true
|
||||
|
||||
### toString
|
||||
|
||||
The string representation of the value, either `"true"` or `"false"`.
|
||||
@@ -0,0 +1,29 @@
|
||||
^title Class Class
|
||||
|
||||
**TODO**
|
||||
|
||||
## Methods
|
||||
|
||||
### **name**
|
||||
|
||||
The name of the class.
|
||||
|
||||
### **supertype**
|
||||
|
||||
The superclass of this class.
|
||||
|
||||
:::wren
|
||||
class Crustacean {}
|
||||
class Crab is Crustacean {}
|
||||
|
||||
System.print(Crab.supertype) //> Crustacean
|
||||
|
||||
A class with no explicit superclass implicitly inherits Object:
|
||||
|
||||
:::wren
|
||||
System.print(Crustacean.supertype) //> Object
|
||||
|
||||
Object forms the root of the class hierarchy and has no supertype:
|
||||
|
||||
:::wren
|
||||
System.print(Object.supertype) //> null
|
||||
@@ -0,0 +1,141 @@
|
||||
^title Fiber Class
|
||||
|
||||
A lightweight coroutine. [Here][fibers] is a gentle introduction.
|
||||
|
||||
[fibers]: ../../concurrency.html
|
||||
|
||||
### Fiber.**new**(function)
|
||||
|
||||
Creates a new fiber that executes `function` in a separate coroutine when the
|
||||
fiber is run. Does not immediately start running the fiber.
|
||||
|
||||
:::wren
|
||||
var fiber = Fiber.new {
|
||||
System.print("I won't get printed")
|
||||
}
|
||||
|
||||
## Static Methods
|
||||
|
||||
### Fiber.**current**
|
||||
|
||||
The currently executing fiber.
|
||||
|
||||
### Fiber.**suspend**()
|
||||
|
||||
Pauses the current fiber, and stops the interpreter. Control returns to the
|
||||
host application.
|
||||
|
||||
To resume execution, the host application will need to invoke the interpreter
|
||||
again. If there is still a reference to the suspended fiber, it can be resumed.
|
||||
|
||||
### 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`.
|
||||
|
||||
:::wren
|
||||
var fiber = Fiber.new {
|
||||
System.print("Before yield")
|
||||
Fiber.yield()
|
||||
System.print("After yield")
|
||||
}
|
||||
|
||||
fiber.call() //> Before yield
|
||||
System.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.
|
||||
|
||||
:::wren
|
||||
var fiber = Fiber.new {
|
||||
System.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, it returns
|
||||
`null`.
|
||||
|
||||
If there is no parent fiber to return to, this exits the interpreter. This can
|
||||
be useful to pause execution until the host application wants to resume it
|
||||
later.
|
||||
|
||||
:::wren
|
||||
Fiber.yield()
|
||||
System.print("this does not get reached")
|
||||
|
||||
### Fiber.**yield**(value)
|
||||
|
||||
Similar to `Fiber.yield` but provides a value to return to the parent fiber's
|
||||
`call`.
|
||||
|
||||
:::wren
|
||||
var fiber = Fiber.new {
|
||||
Fiber.yield("value")
|
||||
}
|
||||
|
||||
System.print(fiber.call()) //> value
|
||||
|
||||
## Methods
|
||||
|
||||
### **call**()
|
||||
|
||||
Starts or resumes the fiber if it is in a paused state.
|
||||
|
||||
:::wren
|
||||
var fiber = Fiber.new {
|
||||
System.print("Fiber called")
|
||||
Fiber.yield()
|
||||
System.print("Fiber called again")
|
||||
}
|
||||
|
||||
fiber.call() // Start it.
|
||||
fiber.call() // Resume after the yield() call.
|
||||
|
||||
When the called fiber yields, control is transferred back to the fiber that
|
||||
called it.
|
||||
|
||||
If the called fiber is resuming from a yield, the `yield()` method returns
|
||||
`null` in the called fiber.
|
||||
|
||||
:::wren
|
||||
var fiber = Fiber.new {
|
||||
System.print(Fiber.yield())
|
||||
}
|
||||
|
||||
fiber.call()
|
||||
fiber.call() //> null
|
||||
|
||||
### **call**(value)
|
||||
|
||||
Invokes the fiber or resumes the fiber if it is in a paused state and sets
|
||||
`value` as the returned value of the fiber's call to `yield`.
|
||||
|
||||
:::wren
|
||||
var fiber = Fiber.new {
|
||||
System.print(Fiber.yield())
|
||||
}
|
||||
|
||||
fiber.call()
|
||||
fiber.call("value") //> value
|
||||
|
||||
### **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.
|
||||
|
||||
### **transfer**()
|
||||
|
||||
**TODO**
|
||||
|
||||
### **transfer**(value)
|
||||
|
||||
**TODO**
|
||||
|
||||
### **transferError**(error)
|
||||
|
||||
**TODO**
|
||||
@@ -0,0 +1,45 @@
|
||||
^title Fn Class
|
||||
|
||||
A first class function—an object that wraps an executable chunk of code.
|
||||
[Here][functions] is a friendly introduction.
|
||||
|
||||
[functions]: ../../functions.html
|
||||
|
||||
### Fn.**new**(function)
|
||||
|
||||
Creates a new function from... `function`. Of course, `function` is already 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.
|
||||
|
||||
:::wren
|
||||
var fn = Fn.new {
|
||||
System.print("The body")
|
||||
}
|
||||
|
||||
It is a runtime error if `function` is not a function.
|
||||
|
||||
## Methods
|
||||
|
||||
### **arity**
|
||||
|
||||
The number of arguments the function requires.
|
||||
|
||||
:::wren
|
||||
System.print(Fn.new {}.arity) //> 0
|
||||
System.print(Fn.new {|a, b, c| a }.arity) //> 3
|
||||
|
||||
### **call**(args...)
|
||||
|
||||
Invokes the function with the given arguments.
|
||||
|
||||
:::wren
|
||||
var fn = Fn.new { |arg|
|
||||
System.print(arg) //> Hello world
|
||||
}
|
||||
|
||||
fn.call("Hello world")
|
||||
|
||||
It is a runtime error if the number of arguments given is less than the arity
|
||||
of the function. If more arguments are given than the function's arity they are
|
||||
ignored.
|
||||
@@ -0,0 +1,24 @@
|
||||
^title Core Module
|
||||
|
||||
Because Wren is designed for [embedding in applications][embedding], its core
|
||||
module is minimal and is focused on working with objects within Wren. For
|
||||
stuff like file IO, graphics, etc., it is up to the host application to provide
|
||||
interfaces for this.
|
||||
|
||||
All Wren source files automatically have access to the following classes:
|
||||
|
||||
* [Bool](bool.html)
|
||||
* [Class](class.html)
|
||||
* [Fiber](fiber.html)
|
||||
* [Fn](fn.html)
|
||||
* [List](list.html)
|
||||
* [Map](map.html)
|
||||
* [Null](null.html)
|
||||
* [Num](num.html)
|
||||
* [Object](object.html)
|
||||
* [Range](range.html)
|
||||
* [Sequence](sequence.html)
|
||||
* [String](string.html)
|
||||
* [System](system.html)
|
||||
|
||||
[embedding]: ../../embedding-api.html
|
||||
@@ -0,0 +1,99 @@
|
||||
^title List Class
|
||||
|
||||
Extends [Sequence](sequence.html).
|
||||
|
||||
An indexable contiguous collection of elements. More details [here][lists].
|
||||
|
||||
[lists]: ../../lists.html
|
||||
|
||||
## Methods
|
||||
|
||||
### **add**(item)
|
||||
|
||||
Appends `item` to the end of the list.
|
||||
|
||||
### **clear**()
|
||||
|
||||
Removes all elements from the list.
|
||||
|
||||
### **count**
|
||||
|
||||
The number of elements in the list.
|
||||
|
||||
### **insert**(index, item)
|
||||
|
||||
Inserts the `item` at `index` in the list.
|
||||
|
||||
:::wren
|
||||
var list = ["a", "b", "c", "d"]
|
||||
list.insert(1, "e")
|
||||
System.print(list) //> [a, e, b, c, d]
|
||||
|
||||
The `index` may be one past the last index in the list to append an element.
|
||||
|
||||
:::wren
|
||||
var list = ["a", "b", "c"]
|
||||
list.insert(3, "d")
|
||||
System.print(list) //> [a, b, c, d]
|
||||
|
||||
If `index` is negative, it counts backwards from the end of the list. It bases this on the length of the list *after* inserted the element, so that `-1` will append the element, not insert it before the last element.
|
||||
|
||||
:::wren
|
||||
var list = ["a", "b"]
|
||||
list.insert(-1, "d")
|
||||
list.insert(-2, "c")
|
||||
System.print(list) //> [a, b, c, d]
|
||||
|
||||
Returns the inserted item.
|
||||
|
||||
:::wren
|
||||
System.print(["a", "c"].insert(1, "b")) //> b
|
||||
|
||||
It is a runtime error if the index is not an integer or is out of bounds.
|
||||
|
||||
### **iterate**(iterator), **iteratorValue**(iterator)
|
||||
|
||||
Implements the [iterator protocol][] for iterating over the elements in the
|
||||
list.
|
||||
|
||||
[iterator protocol]: ../../control-flow.html#the-iterator-protocol
|
||||
|
||||
### **removeAt**(index)
|
||||
|
||||
Removes the element at `index`. If `index` is negative, it counts backwards
|
||||
from the end of the list where `-1` is the last element. All trailing elements
|
||||
are shifted up to fill in where the removed element was.
|
||||
|
||||
:::wren
|
||||
var list = ["a", "b", "c", "d"]
|
||||
list.removeAt(1)
|
||||
System.print(list) //> [a, c, d]
|
||||
|
||||
Returns the removed item.
|
||||
|
||||
System.print(["a", "b", "c"].removeAt(1)) //> b
|
||||
|
||||
It is a runtime error if the index is not an integer or is out of bounds.
|
||||
|
||||
### **[**index**]** operator
|
||||
|
||||
Gets the element at `index`. If `index` is negative, it counts backwards from
|
||||
the end of the list where `-1` is the last element.
|
||||
|
||||
:::wren
|
||||
var list = ["a", "b", "c"]
|
||||
System.print(list[1]) //> b
|
||||
|
||||
It is a runtime error if the index is not an integer or is out of bounds.
|
||||
|
||||
### **[**index**]=**(item) operator
|
||||
|
||||
Replaces the element at `index` with `item`. If `index` is negative, it counts
|
||||
backwards from the end of the list where `-1` is the last element.
|
||||
|
||||
:::wren
|
||||
var list = ["a", "b", "c"]
|
||||
list[1] = "new"
|
||||
System.print(list) //> [a, new, c]
|
||||
|
||||
It is a runtime error if the index is not an integer or is out of bounds.
|
||||
@@ -0,0 +1,62 @@
|
||||
^title Map Class
|
||||
|
||||
An associative collection that maps keys to values. More details [here](../maps.html).
|
||||
|
||||
## Methods
|
||||
|
||||
### **clear**()
|
||||
|
||||
Removes all entries from the map.
|
||||
|
||||
### **containsKey**(key)
|
||||
|
||||
Returns `true` if the map contains `key` or `false` otherwise.
|
||||
|
||||
### **count**
|
||||
|
||||
The number of entries in the map.
|
||||
|
||||
### **keys**
|
||||
|
||||
A [Sequence](sequence.html) that can be used to iterate over the keys in the
|
||||
map. Note that iteration order is undefined. All keys will be iterated over,
|
||||
but may be in any order, and may even change between invocations of Wren.
|
||||
|
||||
### **iterate**(iterator), **iteratorValue**(iterator)
|
||||
|
||||
Implements the [iterator protocol](../control-flow.html#the-iterator-protocol)
|
||||
for iterating over the elements in the list.
|
||||
|
||||
### **remove**(key)
|
||||
|
||||
Removes [key] and the value associated with it from the map. Returns the value.
|
||||
|
||||
If the key was not present, returns `null`.
|
||||
|
||||
### **values**
|
||||
|
||||
A [Sequence](sequence.html) that can be used to iterate over the values in the
|
||||
map. Note that iteration order is undefined. All values will be iterated over,
|
||||
but may be in any order, and may even change between invocations of Wren.
|
||||
|
||||
If multiple keys are associated with the same value, the value will appear
|
||||
multiple times in the sequence.
|
||||
|
||||
### **[**key**]** operator
|
||||
|
||||
Gets the value associated with `key` in the map. If `key` is not present in the
|
||||
map, returns `null`.
|
||||
|
||||
:::wren
|
||||
var map = {"george": "harrison", "ringo": "starr"}
|
||||
System.print(map["ringo"]) //> starr
|
||||
System.print(map["pete"]) //> null
|
||||
|
||||
### **[**key**]=**(value) operator
|
||||
|
||||
Associates `value` with `key` in the map. If `key` was already in the map, this
|
||||
replaces the previous association.
|
||||
|
||||
It is a runtime error if the key is not a [Bool](bool.html),
|
||||
[Class](class.html), [Null](null.html), [Num](num.html), [Range](range.html),
|
||||
or [String](string.html).
|
||||
@@ -0,0 +1,10 @@
|
||||
^title Null Class
|
||||
|
||||
## Methods
|
||||
|
||||
### **!** operator
|
||||
|
||||
Returns `true`, since `null` is considered [false](../control-flow.html#truth).
|
||||
|
||||
:::wren
|
||||
System.print(!null) //> true
|
||||
@@ -0,0 +1,163 @@
|
||||
^title Num Class
|
||||
|
||||
## Static Methods
|
||||
|
||||
### Num.**fromString**(value)
|
||||
|
||||
Attempts to parse `value` as a decimal literal and return it as an instance of
|
||||
`Num`. If the number cannot be parsed `null` will be returned.
|
||||
|
||||
It is a runtime error if `value` is not a string.
|
||||
|
||||
### Num.**pi**
|
||||
|
||||
The value of π.
|
||||
|
||||
## Methods
|
||||
|
||||
### **abs**
|
||||
|
||||
The absolute value of the number.
|
||||
|
||||
:::wren
|
||||
System.print(-123.abs) //> 123
|
||||
|
||||
### **acos**
|
||||
|
||||
The arc cosine of the number.
|
||||
|
||||
### **asin**
|
||||
|
||||
The arc sine of the number.
|
||||
|
||||
### **atan**
|
||||
|
||||
The arc tangent of the number.
|
||||
|
||||
### **atan**(x)
|
||||
|
||||
The arc tangent of the number when divided by `x`, using the signs of the two
|
||||
numbers to determine the quadrant of the result.
|
||||
|
||||
### **ceil**
|
||||
|
||||
Rounds the number up to the nearest integer.
|
||||
|
||||
:::wren
|
||||
System.print(1.5.ceil) //> 2
|
||||
System.print((-3.2).ceil) //> -3
|
||||
|
||||
### **cos**
|
||||
|
||||
The cosine of the number.
|
||||
|
||||
### **floor**
|
||||
|
||||
Rounds the number down to the nearest integer.
|
||||
|
||||
:::wren
|
||||
System.print(1.5.floor) //> 1
|
||||
System.print((-3.2).floor) //> -4
|
||||
|
||||
### **isInfinity**
|
||||
|
||||
Whether the number is positive or negative infinity or not.
|
||||
|
||||
:::wren
|
||||
System.print(99999.isInfinity) //> false
|
||||
System.print((1/0).isInfinity) //> true
|
||||
|
||||
### **isInteger**
|
||||
|
||||
Whether the number is an integer or has some fractional component.
|
||||
|
||||
:::wren
|
||||
System.print(2.isInteger) //> true
|
||||
System.print(2.3.isInteger) //> false
|
||||
|
||||
### **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.
|
||||
|
||||
### **tan**
|
||||
|
||||
The tangent of the number.
|
||||
|
||||
### **-** operator
|
||||
|
||||
Negates the number.
|
||||
|
||||
:::wren
|
||||
var a = 123
|
||||
System.print(-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
|
||||
|
||||
Creates a [Range](range.html) representing a consecutive range of numbers
|
||||
from the beginning number to the ending number.
|
||||
|
||||
:::wren
|
||||
var range = 1.2..3.4
|
||||
System.print(range.min) //> 1.2
|
||||
System.print(range.max) //> 3.4
|
||||
System.print(range.isInclusive) //> true
|
||||
|
||||
### **...**(other) operator
|
||||
|
||||
Creates a [Range](range.html) representing a consecutive range of numbers
|
||||
from the beginning number to the ending number not including the ending number.
|
||||
|
||||
:::wren
|
||||
var range = 1.2...3.4
|
||||
System.print(range.min) //> 1.2
|
||||
System.print(range.max) //> 3.4
|
||||
System.print(range.isInclusive) //> false
|
||||
@@ -0,0 +1,53 @@
|
||||
^title Object Class
|
||||
|
||||
## Static Methods
|
||||
|
||||
### **same**(obj1, obj2)
|
||||
|
||||
Returns `true` if *obj1* and *obj2* are the same. For [value
|
||||
types](../values.html), this returns `true` if the objects have equivalent
|
||||
state. In other words, numbers, strings, booleans, and ranges compare by value.
|
||||
|
||||
For all other objects, this returns `true` only if *obj1* and *obj2* refer to
|
||||
the exact same object in memory.
|
||||
|
||||
This is similar to the built in `==` operator in Object except that this cannot
|
||||
be overriden. It allows you to reliably access the built-in equality semantics
|
||||
even on user-defined classes.
|
||||
|
||||
## Methods
|
||||
|
||||
### **!** operator
|
||||
|
||||
Returns `false`, since most objects are considered [true][].
|
||||
|
||||
[true]: control-flow.html#truth
|
||||
|
||||
### **==**(other) and **!=**(other) operators
|
||||
|
||||
Compares two objects using built-in equality. This compares [value
|
||||
types](../values.html) by value, and all other objects are compared by
|
||||
identity—two objects are equal only if they are the exact same object.
|
||||
|
||||
### **is**(class) operator
|
||||
|
||||
Returns `true` if this object's class or one of its superclasses is `class`.
|
||||
|
||||
:::wren
|
||||
System.print(123 is Num) //> true
|
||||
System.print("s" is Num) //> false
|
||||
System.print(null is String) //> false
|
||||
System.print([] is List) //> true
|
||||
System.print([] is Sequence) //> true
|
||||
|
||||
It is a runtime error if `class` is not a [Class][].
|
||||
|
||||
### **toString**
|
||||
|
||||
A default string representation of the object.
|
||||
|
||||
### **type**
|
||||
|
||||
The [Class][] of the object.
|
||||
|
||||
[class]: class.html
|
||||
@@ -0,0 +1,57 @@
|
||||
^title Range Class
|
||||
|
||||
A range defines a bounded range of values from a starting point to a possibly
|
||||
exclusive endpoint. [Here](../range.html) is a friendly introduction.
|
||||
|
||||
Extends [Sequence](sequence.html).
|
||||
|
||||
## Methods
|
||||
|
||||
### **from**
|
||||
|
||||
The starting point of the range. A range may be backwards, so this can be
|
||||
greater than [to].
|
||||
|
||||
:::wren
|
||||
System.print((3..5).min) //> 3
|
||||
System.print((4..2).min) //> 4
|
||||
|
||||
### **to**
|
||||
|
||||
The endpoint of the range. If the range is inclusive, this value is included,
|
||||
otherwise it is not.
|
||||
|
||||
:::wren
|
||||
System.print((3..5).min) //> 5
|
||||
System.print((4..2).min) //> 2
|
||||
|
||||
### **min**
|
||||
|
||||
The minimum bound of the range. Returns either `from`, or `to`, whichever is
|
||||
lower.
|
||||
|
||||
:::wren
|
||||
System.print((3..5).min) //> 3
|
||||
System.print((4..2).min) //> 2
|
||||
|
||||
### **max**
|
||||
|
||||
The maximum bound of the range. Returns either `from`, or `to`, whichever is
|
||||
greater.
|
||||
|
||||
:::wren
|
||||
System.print((3..5).min) //> 5
|
||||
System.print((4..2).min) //> 4
|
||||
|
||||
### **isInclusive**
|
||||
|
||||
Whether or not the range includes `to`. (`from` is always included.)
|
||||
|
||||
:::wren
|
||||
System.print((3..5).isInclusive) //> true
|
||||
System.print((3...5).isInclusive) //> false
|
||||
|
||||
### **iterate**(iterator), **iteratorValue**(iterator)
|
||||
|
||||
Iterates over the range. Starts at `from` and increments by one towards `to`
|
||||
until the endpoint is reached.
|
||||
@@ -0,0 +1,170 @@
|
||||
^title Sequence Class
|
||||
|
||||
An abstract base class for any iterable object. Any class that implements the
|
||||
core [iterator protocol][] can extend this to get a number of helpful methods.
|
||||
|
||||
[iterator protocol]: ../../control-flow.html#the-iterator-protocol
|
||||
|
||||
## Methods
|
||||
|
||||
### **all**(predicate)
|
||||
|
||||
Tests whether all the elements in the sequence pass the `predicate`.
|
||||
|
||||
Iterates over the sequence, passing each element to the function `predicate`.
|
||||
If it returns something [false](../control-flow.html#truth), stops iterating
|
||||
and returns the value. Otherwise, returns `true`.
|
||||
|
||||
:::wren
|
||||
System.print([1, 2, 3].all {|n| n > 2}) //> false
|
||||
System.print([1, 2, 3].all {|n| n < 4}) //> true
|
||||
|
||||
### **any**(predicate)
|
||||
|
||||
Tests whether any element in the sequence passes the `predicate`.
|
||||
|
||||
Iterates over the sequence, passing each element to the function `predicate`.
|
||||
If it returns something [true][], stops iterating and
|
||||
returns that value. Otherwise, returns `false`.
|
||||
|
||||
[true]: ../../control-flow.html#truth
|
||||
|
||||
:::wren
|
||||
System.print([1, 2, 3].any {|n| n < 1}) //> false
|
||||
System.print([1, 2, 3].any {|n| n > 2}) //> true
|
||||
|
||||
### **contains**(element)
|
||||
|
||||
Returns whether the sequence contains any element equal to the given element.
|
||||
|
||||
### **count**
|
||||
|
||||
The number of elements in the sequence.
|
||||
|
||||
Unless a more efficient override is available, this will iterate over the
|
||||
sequence in order to determine how many elements it contains.
|
||||
|
||||
### **count**(predicate)
|
||||
|
||||
Returns the number of elements in the sequence that pass the `predicate`.
|
||||
|
||||
Iterates over the sequence, passing each element to the function `predicate`
|
||||
and counting the number of times the returned value evaluates to `true`.
|
||||
|
||||
:::wren
|
||||
System.print([1, 2, 3].count {|n| n > 2}) //> 1
|
||||
System.print([1, 2, 3].count {|n| n < 4}) //> 3
|
||||
|
||||
### **each**(function)
|
||||
|
||||
Iterates over the sequence, passing each element to the given `function`.
|
||||
|
||||
:::wren
|
||||
["one", "two", "three"].each {|word| System.print(word) }
|
||||
|
||||
### **isEmpty**
|
||||
|
||||
Returns whether the sequence contains any elements.
|
||||
|
||||
This can be more efficient that `count == 0` because this does not iterate over
|
||||
the entire sequence.
|
||||
|
||||
### **join**(separator)
|
||||
|
||||
Converts every element in the sequence to a string and then joins the results
|
||||
together into a single string, each separated by `separator`.
|
||||
|
||||
It is a runtime error if `separator` is not a string.
|
||||
|
||||
### **join**()
|
||||
|
||||
Converts every element in the sequence to a string and then joins the results
|
||||
together into a single string.
|
||||
|
||||
### **map**(transformation)
|
||||
|
||||
Creates a new sequence that applies the `transformation` to each element in the
|
||||
original sequence while it is iterated.
|
||||
|
||||
:::wren
|
||||
var doubles = [1, 2, 3].map {|n| n * 2 }
|
||||
for (n in doubles) {
|
||||
System.print(n) //> 2
|
||||
//> 4
|
||||
//> 6
|
||||
}
|
||||
|
||||
The returned sequence is *lazy*. It only applies the mapping when you iterate
|
||||
over the sequence, and it does so by holding a reference to the original
|
||||
sequence.
|
||||
|
||||
This means you can use `map(_)` for things like infinite sequences or sequences
|
||||
that have side effects when you iterate over them. But it also means that
|
||||
changes to the original sequence will be reflected in the mapped sequence.
|
||||
|
||||
To force eager evaluation, just call `.toList` on the result.
|
||||
|
||||
:::wren
|
||||
var numbers = [1, 2, 3]
|
||||
var doubles = numbers.map {|n| n * 2 }.toList
|
||||
numbers.add(4)
|
||||
System.print(doubles) //> [2, 4, 6]
|
||||
|
||||
### **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`.
|
||||
|
||||
### **toList**
|
||||
|
||||
Creates a [list][] containing all the elements in the sequence.
|
||||
|
||||
[list]: list.html
|
||||
|
||||
:::wren
|
||||
System.print((1..3).toList) //> [1, 2, 3]
|
||||
|
||||
If the sequence is already a list, this creates a copy of it.
|
||||
|
||||
### **where**(predicate)
|
||||
|
||||
Creates a new sequence containing only the elements from the original sequence
|
||||
that pass the `predicate`.
|
||||
|
||||
During iteration, each element in the original sequence is passed to the
|
||||
function `predicate`. If it returns `false`, the element is skipped.
|
||||
|
||||
:::wren
|
||||
var odds = (1..6).where {|n| n % 2 == 1 }
|
||||
for (n in odds) {
|
||||
System.print(n) //> 1
|
||||
//> 3
|
||||
//> 5
|
||||
}
|
||||
|
||||
The returned sequence is *lazy*. It only applies the filtering when you iterate
|
||||
over the sequence, and it does so by holding a reference to the original
|
||||
sequence.
|
||||
|
||||
This means you can use `where(_)` for things like infinite sequences or
|
||||
sequences that have side effects when you iterate over them. But it also means
|
||||
that changes to the original sequence will be reflected in the filtered
|
||||
sequence.
|
||||
|
||||
To force eager evaluation, just call `.toList` on the result.
|
||||
|
||||
:::wren
|
||||
var numbers = [1, 2, 3, 4, 5, 6]
|
||||
var odds = numbers.where {|n| n % 2 == 1 }.toList
|
||||
numbers.add(7)
|
||||
System.print(odds) //> [1, 3, 5]
|
||||
@@ -0,0 +1,176 @@
|
||||
^title String Class
|
||||
|
||||
A string is an immutable array of bytes. Strings usually store text, in which
|
||||
case the bytes are the UTF-8 encoding of the text's code points. But you can put
|
||||
any kind of byte values in there you want, including null bytes or invalid
|
||||
UTF-8.
|
||||
|
||||
There are a few ways to think of a string:
|
||||
|
||||
* As a searchable chunk of text composed of a sequence of textual code points.
|
||||
|
||||
* As an iterable sequence of code point numbers.
|
||||
|
||||
* As a flat array of directly indexable bytes.
|
||||
|
||||
All of those are useful for some problems, so the string API supports all three.
|
||||
The first one is the most common, so that's what methods directly on the string
|
||||
class cater to.
|
||||
|
||||
In UTF-8, a single Unicode code point—very roughly a single
|
||||
"character"—may encode to one or more bytes. This means you can't
|
||||
efficiently index by code point. There's no way to jump directly to, say, the
|
||||
fifth code point in a string without walking the string from the beginning and
|
||||
counting them as you go.
|
||||
|
||||
Because counting code points is relatively slow, the indexes passed to string
|
||||
methods are *byte* offsets, not *code point* offsets. When you do:
|
||||
|
||||
:::wren
|
||||
someString[3]
|
||||
|
||||
That means "get the code point starting at *byte* three", not "get the third
|
||||
code point in the string". This sounds scary, but keep in mind that the methods
|
||||
on strings *return* byte indexes too. So, for example, this does what you want:
|
||||
|
||||
:::wren
|
||||
var metalBand = "Fäcëhämmër"
|
||||
var hPosition = metalBand.indexOf("h")
|
||||
System.print(metalBand[hPosition]) //> h
|
||||
|
||||
If you want to work with a string as a sequence numeric code points, call the
|
||||
`codePoints` getter. It returns a [Sequence](sequence.html) that decodes UTF-8
|
||||
and iterates over the code points, returning each as a number.
|
||||
|
||||
If you want to get at the raw bytes, call `bytes`. This returns a Sequence that
|
||||
ignores any UTF-8 encoding and works directly at the byte level.
|
||||
|
||||
## Static Methods
|
||||
|
||||
### String.**fromCodePoint**(codePoint)
|
||||
|
||||
Creates a new string containing the UTF-8 encoding of `codePoint`.
|
||||
|
||||
:::wren
|
||||
String.fromCodePoint(8225) //> ‡
|
||||
|
||||
It is a runtime error if `codePoint` is not an integer between `0` and
|
||||
`0x10ffff`, inclusive.
|
||||
|
||||
## Methods
|
||||
|
||||
### **bytes**
|
||||
|
||||
Gets a [`Sequence`](sequence.html) that can be used to access the raw bytes of
|
||||
the string and ignore any UTF-8 encoding. In addition to the normal sequence
|
||||
methods, the returned object also has a subscript operator that can be used to
|
||||
directly index bytes.
|
||||
|
||||
:::wren
|
||||
System.print("hello".bytes[1]) //> 101 (for "e")
|
||||
|
||||
The `count` method on the returned sequence returns the number of bytes in the
|
||||
string. Unlike `count` on the string itself, it does not have to iterate over
|
||||
the string, and runs in constant time instead.
|
||||
|
||||
### **codePoints**
|
||||
|
||||
Gets a [`Sequence`](sequence.html) that can be used to access the UTF-8 decode
|
||||
code points of the string *as numbers*. Iteration and subscripting work similar
|
||||
to the string itself. The difference is that instead of returning
|
||||
single-character strings, this returns the numeric code point values.
|
||||
|
||||
:::wren
|
||||
var string = "(ᵔᴥᵔ)"
|
||||
System.print(string.codePoints[0]) //> 40 (for "(")
|
||||
System.print(string.codePoints[4]) //> 7461 (for "ᴥ")
|
||||
|
||||
If the byte at `index` does not begin a valid UTF-8 sequence, or the end of the
|
||||
string is reached before the sequence is complete, returns `-1`.
|
||||
|
||||
:::wren
|
||||
var string = "(ᵔᴥᵔ)"
|
||||
System.print(string.codePoints[2]) //> -1 (in the middle of "ᵔ")
|
||||
|
||||
### **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 number of code points in the string. Since UTF-8 is a
|
||||
variable-length encoding, this requires iterating over the entire string, which
|
||||
is relatively slow.
|
||||
|
||||
If the string contains bytes that are invalid UTF-8, each byte adds one to the
|
||||
count as well.
|
||||
|
||||
### **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 the first byte matching `search` in the string or `-1` if
|
||||
`search` was not found.
|
||||
|
||||
It is a runtime error if `search` is not a string.
|
||||
|
||||
### **iterate**(iterator), **iteratorValue**(iterator)
|
||||
|
||||
Implements the [iterator protocol](../control-flow.html#the-iterator-protocol)
|
||||
for iterating over the *code points* in the string:
|
||||
|
||||
:::wren
|
||||
var codePoints = []
|
||||
for (c in "(ᵔᴥᵔ)") {
|
||||
codePoints.add(c)
|
||||
}
|
||||
|
||||
System.print(codePoints) //> [(, ᵔ, ᴥ, ᵔ, )]
|
||||
|
||||
If the string contains any bytes that are not valid UTF-8, this iterates over
|
||||
those too, one byte at a time.
|
||||
|
||||
### **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 string containing the code point starting at byte `index`.
|
||||
|
||||
:::wren
|
||||
System.print("ʕ•ᴥ•ʔ"[5]) //> ᴥ
|
||||
|
||||
Since `ʕ` is two bytes in UTF-8 and `•` is three, the fifth byte points to the
|
||||
bear's nose.
|
||||
|
||||
If `index` points into the middle of a UTF-8 sequence or at otherwise invalid
|
||||
UTF-8, this returns a one-byte string containing the byte at that index:
|
||||
|
||||
:::wren
|
||||
System.print("I ♥ NY"[3]) //> (one-byte string [153])
|
||||
|
||||
It is a runtime error if `index` is greater than the number of bytes in the
|
||||
string.
|
||||
@@ -0,0 +1,47 @@
|
||||
^title System Class
|
||||
|
||||
The System class is a grab-bag of functionality exposed by the VM, mostly for
|
||||
use during development or debugging.
|
||||
|
||||
## Static Methods
|
||||
|
||||
### System.**clock**
|
||||
|
||||
Returns the number of seconds (including fractional seconds) since the program
|
||||
was started. This is usually used for benchmarking.
|
||||
|
||||
### System.**gc**()
|
||||
|
||||
Requests that the VM perform an immediate garbage collection to free unused
|
||||
memory.
|
||||
|
||||
### System.**print**()
|
||||
|
||||
Prints a single newline to the console.
|
||||
|
||||
### System.**print**(object)
|
||||
|
||||
Prints [object] to the console followed by a newline. If not already a string,
|
||||
the object is converted to a string by calling `toString` on it.
|
||||
|
||||
:::wren
|
||||
System.print("I like bananas") //> I like bananas
|
||||
|
||||
### System.**printAll**(sequence)
|
||||
|
||||
Iterates over [sequence] and prints each element, then prints a single newline
|
||||
at the end. Each element is converted to a string by calling `toString` on it.
|
||||
|
||||
:::wren
|
||||
System.printAll([1, [2, 3], 4]) //> 1[2, 3]4
|
||||
|
||||
### System.**write**(object)
|
||||
|
||||
Prints a single value to the console, but does not print a newline character
|
||||
afterwards. Converts the value to a string by calling `toString` on it.
|
||||
|
||||
:::wren
|
||||
System.write(4 + 5) //> 9
|
||||
|
||||
In the above example, the result of `4 + 5` is printed, and then the prompt is
|
||||
printed on the same line because no newline character was printed afterwards.
|
||||
@@ -0,0 +1,98 @@
|
||||
<!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="module">
|
||||
<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 class="big">
|
||||
<ul>
|
||||
<li><a href="../">Modules</a></li>
|
||||
<li><a href="./">Core</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="map.html">Map</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>
|
||||
<li><a href="system.html">System</a></li>
|
||||
</ul>
|
||||
</section>
|
||||
</nav>
|
||||
<nav class="small">
|
||||
<table>
|
||||
<tr>
|
||||
<td><a href="../">Modules</a></td>
|
||||
<td><a href="./">Core</a></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td colspan="2"><h2>core classes</h2></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<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="map.html">Map</a></li>
|
||||
<li><a href="null.html">Null</a></li>
|
||||
</ul>
|
||||
</td>
|
||||
<td>
|
||||
<ul>
|
||||
<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>
|
||||
<li><a href="system.html">System</a></li>
|
||||
</ul>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
</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>
|
||||
— Made with ❤ by
|
||||
<a href="http://journal.stuffwithstuff.com/">Bob Nystrom</a> and
|
||||
<a href="https://github.com/munificent/wren/blob/master/AUTHORS">friends</a>.
|
||||
</p>
|
||||
<div class="main-column">
|
||||
</div>
|
||||
</footer>
|
||||
</body>
|
||||
</html>
|
||||
Reference in New Issue
Block a user