Divided documentation pages into separate files

docs/dict.md

@@ -0,0 +1,12 @@
+
+    {$dict.get {human 2 dog 4} snake 0}
+
+*dict.get* returns the value associated with a dictionary key. If the key is not found and a fallback value was specified, that value is returned. Otherwise, an error condition is triggered.
+
+    {$dict.set $legs snake 0}
+
+*dict.set* associates a value with a dictionary key. If the key already exists, the value associated with it is replaced.
+
+    {$dict.unset $legs snake}
+
+*dict.unset* removes a key from a dictionary.

docs/eval.md

@@ -0,0 +1,15 @@
+
+    {$eval {[$+ 4 5]}}
+
+*eval* evaluates an expression.
+
+    {$repr {hello world}}
+
+*repr* returns a human-readable, printable representation of an object.
+
+    {$call {
+    	{$stdout writeln a}
+    	{$stdout writeln b}
+    }}
+
+*call* executes a list of statements.

docs/exc.md

@@ -0,0 +1,16 @@
+
+    {$try {
+    	{$/ 4 0}
+    } {
+    	{$stdout writeln $_}
+    } {
+    	{$stdout writeln {}}
+    }}
+
+*try* receives a list of statements and runs it.
+
+If an error condition is triggered, a second list of statements is executed.
+
+Finally, a third list of statements is executed.
+
+**If only one lists of statements has been specified**, error conditions triggered by the first list of statements are silenced.

docs/flow.md

@@ -0,0 +1,37 @@
+
+    {$if [$== 4 3] {
+    	{$stdout writeln a}
+    } {
+    	{$stdout writeln b}
+    }}
+
+*if* executes a list of statements if a condition is true. Otherwise, if the condition is false and a second list of statements was specified, it is executed instead.
+
+    {$return}
+    {$return 5}
+
+*return* stops the execution of the currently running procedure and sets its return value. If no return value is specified, the procedure returns an empty string.
+
+    {$continue}
+
+*continue* stops the current iteration of a loop.
+
+    {$break}
+
+*break* stops the execution of a loop.
+
+    {$throw}
+    {$throw {error message}}
+
+*throw* triggers an error condition. Error conditions are propagated until caught by a *try* block, or until they reach the global scope. In the latter case, the script exits immediately with a non-zero exit code.
+
+    {$exit}
+    {$exit 1}
+
+*exit* stops the execution of the script.
+
+    {$yield}
+
+*yield* switches to another thread, if there is one.
+
+*yield* should be called only by threads that repeatedly check for a certain condition, which is guaranteed to be false unless another thread performs some action. For example, a thread that runs a loop which removes an item from a list and performs a certain action on it, should call *yield* every time the list is empty, since no item will be added to the list until another thread has a chance to do so. The *yield* call improves efficiency because it allows the polling thread to postpone the next iteration of its polling loop, when the polled condition is guaranteed to be false if polled again immediately.

docs/index.md

@@ -0,0 +1,36 @@
+# Overview
+
+**b6b** is a simple, dynamic, procedural and reflective scripting language inspired by [Tcl](http://www.tcl.tk/), [CPython](http://www.python.org/), Lisp, shell scripting and various ideas or views in western philosophy.
+
+**b6b** follows five design principles:
+
+1. Everything is an object
+2. Every object is a string
+3. Every object is a procedure
+4. Every statement is a procedure call
+5. Transparent parallelism
+
+# Use Cases
+
+**b6b** is especially useful as:
+
+1. A more powerful, yet simple alternative to shell scripting
+2. A thin layer above C and system calls, which provides exceptions, garbage collection and a dynamic type system
+3. An embedded interpreter in a big software project
+4. An extremely lightweight scripting language, for rapid development of fault-tolerant embedded software
+
+# License
+
+    Copyright 2017 Dima Krasner
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.

docs/interp.md

@@ -0,0 +1,4 @@
+
+    {[$b6b {a b}] call {{$stdout writeln $@}}}
+
+**b6b** creates a new interpreter with given global scope parameters. The interpreter object provides a 'call' method, which runs a list of statements.

docs/bindings.md → docs/linenoise.md

@@ -1,14 +1,3 @@
-# zlib
-
-    {$deflate [[$open file.txt ru] read] 9}
-
-*deflate* compresses a string.
-
-    {$inflate [$deflate [[$open file.txt ru] read]]}
-
-*inflate* decompresses a string compressed using *deflate*.
-
-# linenoise
 
     {$linenoise.read {> }}
 

docs/list.md

@@ -0,0 +1,36 @@
+
+    {$list.new a b c {d e}}
+
+*list.new* creates a new list containing its arguments.
+
+    {$list.len {a b c}}
+
+*list.len* returns the length of a list.
+
+    {$list.append $list f}
+
+*list.append* appends an item to a list.
+
+    {$list.extend $list {f g}}
+
+*list.extend* adds all items of a list to an existing list.
+
+    {$list.index {a b c} 0}
+
+*list.index* returns the list item at a given index.
+
+    {$list.range {a b c d e f} 2 4}
+
+*list.range* returns the items of a list, between two indices.
+
+    {$list.in a {a b c}}
+
+*list.in* determines whether an item belongs to a list.
+
+    {$list.pop $list 1}
+
+*list.pop* removes the item at a given index from a list.
+
+    {$choice {a b c}}
+
+*choice* returns a pseudo-random list item.

docs/loop.md

@@ -0,0 +1,18 @@
+
+    {$map {a b} [$range 0 9] {
+    	{$+ $a $b}
+    }}
+
+*map* receives a list of object names and a list, then repeatedly runs a list of statements with local named objects that specify the next items of the list. The return value of *map* is a list of values returned by all iterations of the loop.
+
+If an iteration of the loop calls *continue*, its return value is ignored.
+
+    {$loop {
+    	{$stdout writeln a}
+    }}
+
+*loop* repeatedly runs a list of statements.
+
+    {$range 1 5}
+
+*range* returns a list of all whole numbers in a given range.

docs/meson.build

@@ -14,6 +14,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-foreach md: ['bindings.md', 'evloop.md', 'fs.md', 'introduction.md', 'stdlib.md', 'streams.md', 'tutorial.md', 'use_cases.md']
+foreach md: ['dict.md', 'eval.md', 'evloop.md', 'exc.md', 'flow.md', 'fs.md', 'index.md', 'interp.md', 'linenoise.md', 'list.md', 'loop.md', 'objects.md', 'proc.md', 'str.md', 'streams.md', 'thread.md', 'tutorial.md', 'zlib.md']
 	install_data(md, install_dir: docdir)
 endforeach

docs/objects.md

@@ -0,0 +1,13 @@
+
+    {$local number 5}
+
+*local* assigns a name to object, in the local scope.
+
+    {$global number 5}
+
+*global* assigns a name to object, in the global scope.
+
+    {$export number}
+    {$export number 5}
+
+*export* assigns a name to object, in the calling scope. If no object is specified, *export* uses the object with the same name in the local scope.

docs/proc.md

@@ -0,0 +1,7 @@
+
+    {$proc append_stuff {
+    	{$list.append $. c}
+    	{$return $.}
+    } {a b}}
+
+*proc* creates a new procedure. If optional private data is specified, it is named *.* and preserved across procedure calls.