Write up documentation for the built-in functions and macros.

4 files changed, 1225 insertions, 16 deletions

diff --git a/actinide/stdlib.py b/actinide/stdlib.py
index 0e4165d..5e46f3a 100644
--- a/actinide/stdlib.py
+++ b/actinide/stdlib.py
@@ -60,20 +60,26 @@ def equal_p(a, b):
     return op.eq(a, b)
 
 @An.fn
-def and_(a, b):
-    return op.and_(a, b)
+def and_(*vals):
+    return all(vals)
 
 @An.fn
-def or_(a, b):
-    return op.or_(a, b)
+def or_(*vals):
+    return any(vals)
 
 @An.fn
 def not_(a):
     return not a
 
 def let(symbols, bindings, *body):
+    def beginify(*forms):
+        if len(forms) == 1:
+            form, = forms
+            return form
+        return list(symbols['begin'], *forms)
+
     if nil_p(bindings):
-        return list(*body)
+        return beginify(*body)
 
     binding, bindings = uncons(bindings)
     name, value = flatten(binding)
@@ -81,7 +87,7 @@ def let(symbols, bindings, *body):
     return list(
         append(
             list(symbols['lambda'], list(name)),
-            let(symbols, bindings, *body),
+            list(let(symbols, bindings, *body)),
         ),
         value
     )
diff --git a/actinide/types.py b/actinide/types.py
index fd86757..1674b5e 100644
--- a/actinide/types.py
+++ b/actinide/types.py
@@ -24,10 +24,6 @@ nil = An.bind('nil', None)
 def nil_p(value):
     return value is None
 
-@An.fn
-def read_nil(value):
-    return nil
-
 def display_nil(value):
     return '()'
 
@@ -42,7 +38,6 @@ false = An.bind('#f', False)
 def boolean_p(value):
     return value is true or value is false
 
-@An.fn
 def read_boolean(value):
     if value == '#t':
         return true
@@ -67,7 +62,6 @@ def integer(value):
 def integer_p(value):
     return isinstance(value, int)
 
-@An.fn
 def read_integer(value):
     try:
         return integer(value)
@@ -89,7 +83,6 @@ def decimal(value):
 def decimal_p(value):
     return isinstance(value, Decimal)
 
-@An.fn
 def read_decimal(value):
     try:
         return decimal(value)
@@ -111,7 +104,6 @@ def string(value):
 def string_p(value):
     return not symbol_p(value) and isinstance(value, str)
 
-@An.fn
 def read_string(value):
     value = value[1:-1]
     value = value.replace('\\"', '"')
@@ -146,7 +138,6 @@ def symbol(string, symbol_table):
 def symbol_p(value):
     return isinstance(value, Symbol)
 
-@An.fn
 def read_symbol(value, symbol_table):
     return symbol(value, symbol_table)
 
@@ -213,7 +204,7 @@ def append(list, *lists):
     return cons(value, append(next, *lists))
 
 @An.fn
-def len(list):
+def length(list):
     l = 0
     while not nil_p(list):
         l += 1
diff --git a/docs/builtin.rst b/docs/builtin.rst
new file mode 100644
index 0000000..e6da907
--- /dev/null
+++ b/docs/builtin.rst
@@ -0,0 +1,1211 @@
+.. _functions:
+
+##################
+Built-In Reference
+##################
+
+This document catalogues the built-in functions, built-in values, and macros
+provided by Actinide. Host environments may provide additional functions and
+macros.
+
+\+
+~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (+ val...)
+
+Arguments:
+
+This function has no fixed arity, and takes zero or more arguments:
+
+* ``val``: any integer or decimal.
+
+Returns:
+
+* The sum of the ``val`` arguments. If all arguments are integers, then the
+  result will be an integer. If the arguments include at least one decimal,
+  then the result will be a decimal.
+
+\-
+~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (- val)
+    (- val val...)
+
+Arguments:
+
+This function has no fixed arity, and takes one or more arguments:
+
+* ``val``: any integer or decimal.
+
+Returns:
+
+With one argument:
+
+* The negation of ``val``.
+
+With multiple arguments:
+
+* The result of subtracting the second and subsequent arguments, in order, from
+  the first argument.
+
+\*
+~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (* val val...)
+
+Arguments:
+
+This function has no fixed arity, and takes one or more arguments:
+
+* ``val``: any integer or decimal.
+
+Returns:
+
+* The product of the ``val`` arguments. If all arguments are integers, then the
+  result will be an integer; if any argument is a decimal, then the result will
+  be a decimal.
+
+/
+~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (/ val val...)
+
+Arguments:
+
+This function has no fixed arity, and takes one or more arguments:
+
+* ``val``: any integer or decimal.
+
+Returns:
+
+* The quotient of dividing the first argument by the second and subsequent
+  arguments, in order.
+
+If all arguments are integers, the result will be an integer, and the division
+will round intermediate results towards negative infinity. If any argument is a
+decimal, then all intermediate results will be decimals, with any
+unrepresentable intermediate results rounded to the nearest representable value
+out to an unspecified number of decimal places.
+
+.. _op-equal:
+
+=
+~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (= left right)
+
+Arguments:
+
+* ``left``: any Actinide value.
+* ``right``: any Actinide value.
+
+Returns:
+
+* ``#t`` if the arguments ``left`` and ``right`` are *equivalent*, ``#f``
+  otherwise.
+
+Any two strings with the same sequence of characters are equivalent.
+
+Any two symbols are equivalent if they have the same string representation and
+are interned in the same symbol table.
+
+Any two numbers (integers or decimals, or one of each) are equivalent if they
+have the same magnitude.
+
+Any two booleans are equivalent if they have the same logical meaning.
+
+Any two conses are equivalent if their heads are equivalent and their tails are
+equivalent.
+
+.. note::
+
+    Note to implementors: this falls through to the python ``==`` operator for
+    values it doesn't recognize.
+
+!=
+~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (!= left right)
+
+Arguments:
+
+* ``left``: any Actinide value.
+* ``right``: any Actinide value.
+
+Returns:
+
+* ``#t`` if the arguments ``left`` and ``right`` are not equivalent, ``#f``
+  otherwise.
+
+Any two strings with the same sequence of characters are equivalent.
+
+Any two symbols are equivalent if they have the same string representation and
+are interned in the same symbol table.
+
+Any two numbers (integers or decimals, or one of each) are equivalent if they
+have the same magnitude.
+
+Any two booleans are equivalent if they have the same logical meaning.
+
+Any two conses are equivalent if their heads are equivalent and their tails are
+equivalent.
+
+<
+~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (< left right)
+
+Arguments:
+
+* ``left``: any integer or decimal.
+* ``right``: any integer or decimal.
+
+Returns:
+
+* ``#t`` if ``left`` is strictly less than ``right``, ``#f`` otherwise.
+
+<=
+~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (<= left right)
+
+Arguments:
+
+* ``left``: any integer or decimal.
+* ``right``: any integer or decimal.
+
+Returns:
+
+* ``#t`` if ``left`` is less than or equal to ``right``, ``#f`` otherwise.
+
+>
+~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (> left right)
+
+Arguments:
+
+* ``left``: any integer or decimal.
+* ``right``: any integer or decimal.
+
+Returns:
+
+* ``#t`` if ``left`` is strictly greater than ``right``, ``#f`` otherwise.
+
+>=
+~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (>= left right)
+
+Arguments:
+
+* ``left``: any integer or decimal.
+* ``right``: any integer or decimal.
+
+Returns:
+
+* ``#t`` if ``left`` is greater than or equal to ``right``, ``#f`` otherwise.
+
+and
+~~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (and val...)
+
+Arguments:
+
+This function has no fixed arity, and takes zero or more arguments:
+
+* ``val``: any Actinide value, but boolean values are preferred.
+
+Returns:
+
+* ``#f`` if any argument is equal to, or coerces to, ``#f``, ``#t`` otherwise.
+
+append
+~~~~~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (append list...)
+
+Arguments:
+
+This function has no fixed arity, and takes zero or more arguments:
+
+* ``list``: any list.
+
+Returns:
+
+* A list composed by appending the arguments to one another, in left-to-right
+  order.
+
+Append joins lists, producing a new list whose elements are the elements of the
+first argument, followed by the elements of the second, and so on, ending with
+the elements of the last argument.
+
+boolean?
+~~~~~~~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (boolean val)
+
+Arguments:
+
+* ``val``: any Actinide value.
+
+Returns:
+
+* ``#t`` if ``val`` is one of the boolean values ``#t`` or ``#f``, ``#f``
+  otherwise.
+
+.. _cons:
+
+concat
+~~~~~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (concat string...)
+
+Arguments:
+
+This function has no fixed arity, and takes zero or more arguments:
+
+* ``string``: any string.
+
+Returns:
+
+* The concatenation of the ``string`` arguments, in left-to-right order.
+
+cons
+~~~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (cons head tail)
+
+Arguments:
+
+* ``head``: any Actinide value.
+* ``tail``: any Actinide value.
+
+Returns:
+
+* A cons cell whose head and tail are the ``head`` and ``tail`` arguments.
+
+See also:
+
+* :ref:`head`
+* :ref:`tail`
+
+cons?
+~~~~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (cons? val)
+
+Arguments:
+
+* ``val``: any Actinide value.
+
+Returns:
+
+* ``#t`` if ``val`` is a cons, including ``nil``; ``#f`` for all other values.
+
+decimal
+~~~~~~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (decimal val)
+
+Arguments:
+
+* ``val``: a string, integer, or decimal value to convert to a decimal.
+
+Returns:
+
+* The decimal value of ``val``, as below.
+
+Converts a value to a decimal.
+
+For strings, this conversion parses the string as if it were an Actinide
+decimal literal, and returns the result. If the string cannot be converted in
+this manner, this generates an error and aborts computation.
+
+For integers, this conversion returns a decimal value with equal magnitude
+whose fractional part is zero.
+
+For decimals, this conversion returns the value unchanged.
+
+decimal?
+~~~~~~~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (decimal? val)
+
+Arguments:
+
+* ``val``: any Actinide value.
+
+Returns:
+
+* ``#t`` if ``val`` is a decimal, ``#f`` for all other values.
+
+.. _display:
+
+display
+~~~~~~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (display val)
+
+Arguments:
+
+* ``val``: any Actinide value.
+
+Returns:
+
+* A string representation of ``val``.
+
+Converts a value into its string representation. For values which are Actinide
+forms, the representation can be read back using :ref:`read` to reconstruct
+``val``.
+
+See also:
+
+* :ref:`string`
+
+.. note::
+
+    Note to implementors: ``display`` falls back to the Python ``repr()``
+    function if it cannot determine the string representation of a value.
+
+eq?
+~~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (eq? left right)
+
+Arguments:
+
+* ``left``: any Actinide value.
+* ``right``: any Actinide value.
+
+Returns:
+
+* ``#t`` if ``left`` is identical to ``right``, ``#f`` otherwise.
+
+Identity is somewhat loosely defined. The following cases are guaranteed to be
+identical:
+
+* Two expressions that reduce to the same cons.
+* Two expressions that reduce to the same vector.
+* Two expressions that reduce to the same symbol.
+* Two expressions that produce the same boolean value.
+
+Some other cases are also identical as an implementation detail.
+
+.. note::
+
+    Note to implementors: ``eq?`` uses the Python ``is`` operator under the
+    hood.
+
+equal?
+~~~~~~
+
+See :ref:`= <op-equal>`.
+
+eval
+~~~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (eval form)
+
+Arguments:
+
+* ``form``: an Actinide form (a symbol, literal, or list whose elements are
+  forms)
+
+Returns:
+
+* Any type, determined by the result of evaluating ``form``.
+
+Expands and evaluates the Actinide form ``form`` in the top-level environment.
+
+.. _read:
+
+expand
+~~~~~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (expand form)
+
+Arguments:
+
+* ``form``: an Actinide form, which may contain macro calls and other
+  unexpanded syntax.
+
+Returns:
+
+* An Actinide form containing no unexpanded macros or unexpanded syntax.
+
+Expands a form, applying macro expansion and converting shorthand forms into
+their longhand equivalents.
+
+.. _head:
+
+head
+~~~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (head cons)
+
+Arguments:
+
+* ``cons``: any cons.
+
+Returns:
+
+* The ``head`` value contained in ``cons``.
+
+See also:
+
+* :ref:`cons`
+* :ref:`tail`
+
+integer
+~~~~~~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (integer val)
+
+Arguments:
+
+* ``val``: a string, integer, or decimal value to convert to an integer.
+
+Returns:
+
+* The integer value of ``val``, as below.
+
+Converts a value to an integer.
+
+For strings, this conversion parses the string as if it were an Actinide
+integer literal, and returns the result. If the string cannot be converted in
+this manner, this generates an error and aborts computation.
+
+For integers, this conversion returns the integer unchanged.
+
+For decimals, this conversion truncates the fractional part of the
+decimal (rounding towards zero), and returns the resulting integral part as an
+Actinide integer.
+
+integer?
+~~~~~~~~
+
+.. code-block:: scheme
+
+    (integer? val)
+
+Arguments:
+
+* ``val``: Any Actinide value.
+
+Returns:
+
+* ``#t`` if the value is an Actinide integer (not including a decimal whose
+  fractional part is equal to zero), ``#f`` for all other values.
+
+length
+~~~~~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (length val)
+
+Arguments:
+
+* ``val``: any string or list.
+
+Returns:
+
+* The number of elements in ``val``.
+
+The length of the empty list ``nil`` is zero. The length of any other list is
+one greater than the length of its own tail.
+
+The length of a string is the number of characters in that string.
+
+let
+~~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (let (binding...) body...)
+
+A ``binding`` is an expression of the form
+
+.. code-block:: scheme
+
+    (symb form)
+
+Where ``symb`` is a single symbol, and ``form`` is an expression reducing to a
+single value.
+
+This macro introduces *local bindings*, which are in effect for the duration of
+the ``body`` forms. If the let macro is invoked with an empty list of
+``binding`` expressions, it expands to the ``body`` forms (wrapping them in a
+``begin`` if necessary), and the result is the result of the last ``body``
+
+form. Otherwise, if the ``let`` macro is invoked with one or more bindings, the
+macro creates a local environment with the leftmost binding, then expands
+another copy of the ``let`` macro in that environment with the leftmost binding
+removed.
+
+Because ``let`` recurses in this manner, binding expressions can refer to any
+binding to their left in the same ``let`` expression, but not to bindings to
+their right.
+
+Example:
+
+.. code-block:: scheme
+
+    (let ((x 1)         ; x = 1
+          (y (+ x 1)))  ; y = 2
+         (+ x y))       ; result = x + y = 3
+
+This program reduces to ``3``, without creating bindings for ``x`` and ``y``
+that live beyond the evaluation of the ``let`` form.
+
+list
+~~~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (list elem...)
+
+Arguments:
+
+This function has no fixed arity, and takes zero or more arguments:
+
+* ``elem``: any Actinide value
+
+Returns:
+
+* A list of the ``elem`` values, in left-to-right order.
+
+A *list* is either nil (the result of ``(list)`` without arguments), or a cons
+whose head is the value at that position and whose tail is a list. This
+function constructs a list from its arguments, with the leftmost argument in
+the first position of the resulting list and the rightmist argument in the last.
+
+See also:
+
+* :ref:`cons`
+
+list?
+~~~~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (list? val)
+
+Arguments:
+
+* ``val``: any Actinide value
+
+Returns:
+
+* ``#t`` if ``val`` is a list, ``#f`` for all other values.
+
+list-to-vector
+~~~~~~~~~~~~~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (list-to-vector list)
+
+Arguments:
+
+* ``list``: any list.
+
+Returns:
+
+* A vector containing the same elements as ``list``, in the same order.
+
+.. _nil:
+
+nil
+~~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    nil
+
+Returns:
+
+* The empty list.
+
+nil?
+~~~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (nil? val)
+
+Arguments:
+
+* ``val``: any value.
+
+Returns:
+
+* A boolean. ``#t`` if ``val`` is equal to :ref:`nil`, otherwise ``#f``.
+
+Checks if a value is nil.
+
+not
+~~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (not val)
+
+Arguments:
+
+* ``val``: any Actinide value, although a boolean is preferred.
+
+Returns:
+
+* The boolean negation of ``val``: ``#t`` if the argument ``val`` is ``#f``, or
+  ``#f`` if ``val`` is ``#t``.
+
+or
+~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (or val...)
+
+Arguments:
+
+This function has no fixed arity, and takes zero or more arguments:
+
+* ``val``: any Actinide value, although boolean values are preferred.
+
+Returns:
+
+* ``#t`` if any argument is ``#t`` or coerces to true, ``#f`` otherwise.
+
+peek-port
+~~~~~~~~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (peek-port port len)
+
+Arguments:
+
+* ``port``: an input port.
+* ``len``: an integer length.
+
+Returns:
+
+* Up to ``len`` characters from ``port``, without consuming them.
+
+This will peek ahead into the port, reading into an internal buffer if
+necessary, and return at least 1 and up to ``len`` characters that will be
+available to ``read-port``. If the stream is fully consumed, this returns the
+empty string.
+
+procedure?
+~~~~~~~~~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (procedure? val)
+
+Arguments:
+
+* ``val``: any Actinide value.
+
+Returns:
+
+* ``#t`` if ``val`` is a procedure (either produced by a ``lambda`` form or a
+  built-in procedure provided by the host environment or the implementation),
+  ``#f`` for all other values.
+
+read
+~~~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (read port)
+
+Arguments:
+
+* ``port``: an input port. By default, input ports can be created from strings
+  using :ref:`string-to-input-port`; the host environment may provide other
+  facilities.
+
+Returns:
+
+* A form, or the special uninterned symbol ``#<end-of-file>``.
+
+Reads one form from the given input port ``port`` and returns it. If the reader
+encounters the end of input, this returns a generated symbol indicating end of
+input.
+
+read-port
+~~~~~~~~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (read-port port len)
+
+Arguments:
+
+* ``port``: an input port.
+* ``len``: an integer length.
+
+Returns:
+
+* Up to ``len`` characters read from ``port``.
+
+This consumes the characters returned - they will not be returned in future
+calls to ``peek-port`` or ``read-port`` on the same port. If the port is fully
+consumed, this will return the empty string.
+
+read-port-fully
+~~~~~~~~~~~~~~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (read-port-fully port)
+
+Arguments:
+
+* ``port``: an input port.
+
+Returns:
+
+* All remaining characters in ``port``.
+
+This consumes the characters returned - they will not be returned in future
+calls to ``peek-port`` or ``read-port`` on the same port. If the port is fully
+consumed, this will return the empty string.
+
+.. _string:
+
+string
+~~~~~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (string val)
+
+Arguments:
+
+* ``val``: any Actinide value.
+
+Returns:
+
+* A human-readable string representation of that value.
+
+Converts a value to a human-readable string.
+
+For strings, this returns the value unchanged.
+
+For integers and decimals, this returns a string representation of the number.
+
+See also:
+
+* :ref:`display`
+
+.. note::
+
+    Note to implementors: this falls back to the Python ``str()`` function if
+    it cannot determine a string representation of the value.
+
+string?
+~~~~~~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (string? val)
+
+Arguments:
+
+* ``val``: any Actinide value.
+
+Returns:
+
+* ``#t`` if ``val`` is a string, ``#f`` for all other values.
+
+.. _string-to-input-port:
+
+string-to-input-port
+~~~~~~~~~~~~~~~~~~~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (string-to-input-port str)
+
+Arguments:
+
+* ``str``: any string.
+
+Returns:
+
+* A fresh input port, whose characters will be drawn from ``str`` in order.
+
+This is the only built-in procedure Actinide provides for constructing input
+ports from within Actinide programs.
+
+symbol
+~~~~~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (symbol string)
+
+Arguments:
+
+* ``string``: a string.
+
+Returns:
+
+* An interned symbol.
+
+Converts a string ``string`` into an equivalent symbol, interning it if necessary. The following equivalences hold for all strings ``S``:
+
+.. code-block:: scheme
+
+    (= (symbol S) (symbol S))
+    (eq? (symbol S) (symbol S))
+
+.. note::
+
+    Note to host program implementors: Symbols are interned on a per-session
+    basis. The above equivalences do not hold for symbols obtained from
+    different sessions.
+
+symbol?
+~~~~~~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (symbol? val)
+
+Arguments:
+
+* ``val``: any Actinide value.
+
+Returns:
+
+* ``#t`` if ``val`` is a symbol, ``#f`` for all other values.
+
+.. _tail:
+
+tail
+~~~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (tail cons)
+
+Arguments:
+
+* ``cons``: any cons.
+
+Returns:
+
+* The ``tail`` value contained in ``cons``.
+
+See also:
+
+* :ref:`cons`
+* :ref:`head`
+
+uncons
+~~~~~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (uncons cons)
+
+Arguments:
+
+* ``cons``: any cons.
+
+Returns:
+
+This function returns two values:
+
+* The ``head`` contained in the cons, and
+* The ``tail`` contained in the cons.
+
+vector
+~~~~~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (vector elem...)
+
+Arguments:
+
+This function has no fixed arity, and takes zero or more arguments:
+
+* ``elem``: any Actinide value.
+
+Returns:
+
+* A vector containing the given elements, in left-to-right order.
+
+A *vector* is an ordered container guaranteeing amortized constant-time indexed
+access to its elements (compared to a list's amortized linear time access to a
+specific index).
+
+vector?
+~~~~~~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (vector? val)
+
+Arguments:
+
+* ``val``: any Actinide value.
+
+Returns:
+
+* ``#t`` if ``val`` is a vector, ``#f`` for all other values.
+
+vector-add
+~~~~~~~~~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (vector-add vec elem...)
+
+Arguments:
+
+This argument has no fixed arity, and takes one or more arguments:
+
+* ``vec``: any vector.
+* ``elem``: any Actinide value.
+
+Returns:
+
+* ``vec``.
+
+This function modifies ``vec`` as a side effect, appending each ``elem`` to the
+end of the vector, in left-to-right order (so that the last argument is the
+vector's new last element).
+
+vector-get
+~~~~~~~~~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (vector-get vec idx)
+
+Arguments:
+
+* ``vec``: any vector.
+* ``idx``: an integer index.
+
+Returns:
+
+* The element of ``vec`` at index ``idx``.
+
+The index ``idx`` must be no less than zero, and less than the vector's
+``vector-length``. Values outside of this range will raise an error and abort
+computation.
+
+vector-length
+~~~~~~~~~~~~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (vector-length vec)
+
+Arguments:
+
+* ``vec``: any vector.
+
+Returns:
+
+* The number of elements in ``vec``.
+
+vector-set
+~~~~~~~~~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (vector-set vec idx elem)
+
+Arguments:
+
+* ``vec``: any vector.
+* ``idx``: an integer intex.
+* ``elem``: any Actinide value.
+
+Returns:
+
+* ``vec``.
+
+This function modifies ``vec`` as a side effect. The element at index ``idx``
+is replaced with ``elem``. As with ``vector-get``, the index ``idx`` must be no
+less than zero and less than the vector's ``vector-length``.
+
+vector-to-list
+~~~~~~~~~~~~~~
+
+Syntax:
+
+.. code-block:: scheme
+
+    (vector-to-list vec)
+
+Arguments:
+
+* ``vec``: any vector.
+
+Returns:
+
+* A list containing the same elements as ``vec``, in the same order.
+
+
diff --git a/index.rst b/index.rst
index 8d722e5..5e8f1ab 100644
--- a/index.rst
+++ b/index.rst
@@ -4,5 +4,6 @@
 
    docs/intro
    docs/language
+   docs/builtin
    docs/embedding
    docs/security