diff --git a/doc/site/core/index.markdown b/doc/site/core/index.markdown index f8353e62..3a2dfe0a 100644 --- a/doc/site/core/index.markdown +++ b/doc/site/core/index.markdown @@ -1,4 +1,24 @@ ^title Core Library ^category core -**TODO** \ No newline at end of file +Because Wren is designed for [embedding in applications][embedding], its core +library 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) + +[embedding]: ../embedding-api.html \ No newline at end of file diff --git a/doc/site/core/list.markdown b/doc/site/core/list.markdown index 2e7e5863..14ded6dc 100644 --- a/doc/site/core/list.markdown +++ b/doc/site/core/list.markdown @@ -7,7 +7,7 @@ An indexable contiguous collection of elements. More details [here](../lists.htm ### **add**(item) -Appends `item` onto the end of the list. +Appends `item` to the end of the list. ### **clear** @@ -28,12 +28,36 @@ for iterating over the elements in the list. ### **removeAt**(index) -**TODO** +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. + + :::dart + var list = ["a", "b", "c", "d"] + list.removeAt(1) + IO.print(list) // "[a, c, d]". + +It is a runtime error if the index is not an integer or is out of bounds. ### **[**index**]** operator -**TODO** +Gets the element at `index`. If `index` is negative, it counts backwards from +the end of the list where `-1` is the last element. + + :::dart + var list = ["a", "b", "c"] + IO.print(list[1]) // "b". + +It is a runtime error if the index is not an integer or is out of bounds. ### **[**index**]=**(item) operator -**TODO** +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. + + :::dart + var list = ["a", "b", "c"] + list[1] = "new" + IO.print(list) // "[a, new, c]". + +It is a runtime error if the index is not an integer or is out of bounds. diff --git a/doc/site/core/map.markdown b/doc/site/core/map.markdown new file mode 100644 index 00000000..189f58b2 --- /dev/null +++ b/doc/site/core/map.markdown @@ -0,0 +1,53 @@ +^title Map Class +^category core + +An associative collection that maps keys to values. More details [here](../maps.html). + +### **clear** + +Removes all entries + +### **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. + +### **removeAt**(key) + +### **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`. + + :::dart + var map = {"george": "harrison", "ringo": "starr"} + IO.print(map["ringo"]) // "starr". + IO.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). diff --git a/doc/site/maps.markdown b/doc/site/maps.markdown index bf0ca205..badd0397 100644 --- a/doc/site/maps.markdown +++ b/doc/site/maps.markdown @@ -1,5 +1,44 @@ ^title Maps ^category types -Wren will have a built-in hash table type similar to objects in JavaScript and -tables in Lua, but they haven't been implemented yet. \ No newline at end of file +A map is an *associative* collection. It holds a set of entries, each of which +maps a *key* to a *value*. The same data structure has a variety of names in +other languages: hash table, dictionary, association, table, etc. + +You can create a map by placing a series of comma-separated entries inside +curly braces. Each entry is a key and a value separated by a colon: + + :::dart + { + "george": "harrison", + "john": "lennon", + "paul": mccartney", + "ringo": "starr" + } + +This creates a map that maps the first names of the Beatles to their last +names. Here, we're using strings for both keys and values. + +Values can be any Wren object, and multiple keys may map to the same value. + +Keys have a few limitations. They must be one of the immutable built-in [value +types](values.html) in Wren. In other words, a number, string, range, bool, or +`null`. You can also use a [class object](classes.html) as a key. Any given key +can only be present in the map once. If you use it twice, the latter replaces +the former's value. + +## Adding entries + +**TODO** + +## Looking up values + +**TODO** + +## Removing entries + +**TODO** + +## Iterating over the contents + +**TODO** diff --git a/doc/site/template-core.html b/doc/site/template-core.html index 1452859c..64b1f38c 100644 --- a/doc/site/template-core.html +++ b/doc/site/template-core.html @@ -31,6 +31,7 @@
  • Fiber
  • Fn
  • List
  • +
  • Map
  • Null
  • Num
  • Object
  • diff --git a/doc/site/values.markdown b/doc/site/values.markdown index ed2c2692..7265339d 100644 --- a/doc/site/values.markdown +++ b/doc/site/values.markdown @@ -10,7 +10,7 @@ character array modified in place. ## Booleans A boolean value represents truth or falsehood. There are two boolean literals, -`true` and `false`. Their class is `Bool`. +`true` and `false`. Their class is [Bool](core/bool.html). ## Numbers @@ -26,12 +26,12 @@ from other languages: 1.0 -12.34 -Numbers are instances of the `Num` class. +Numbers are instances of the [Num](core/num.html) class. ## Strings -Strings are chunks of text stored as UTF-8. Their class is `String`. String -literals are surrounded in double quotes: +Strings are chunks of text stored as UTF-8. Their class is +[String](core/string.html). String literals are surrounded in double quotes: :::dart "hi there" @@ -78,9 +78,12 @@ example: var slice = list[1..3] IO.print(slice) // ["b", "c", "d"] +Their class is [Range](core/range.html) + ## Null Wren has a special value `null`, which is the only instance of the class -`Null`. (Note the difference in case.) It functions a bit like `void` in some -languages: it indicates the absence of a value. If you call a method that -doesn't return anything and get its returned value, you get `null` back. +[Null](core/null.html). (Note the difference in case.) It functions a bit like +`void` in some languages: it indicates the absence of a value. If you call a +method that doesn't return anything and get its returned value, you get `null` +back. diff --git a/doc/site/variables.markdown b/doc/site/variables.markdown index dd1554cd..94d3c6da 100644 --- a/doc/site/variables.markdown +++ b/doc/site/variables.markdown @@ -65,3 +65,5 @@ assigned value. :::dart var a = "before" IO.print(a = "after") // Prints "after". + +**TODO: Top-level names.**