Repository: asteroid-lang/asteroid (language: python)

Issue:
OS module
A module that allows the user to access OS functionality such as `argv` and path manipulation.
OS module
A module that allows the user to access OS functionality such as `argv` and path manipulation.


Discussion / hints:

Fix patch:
diff --git a/.github/workflows/generate_documentation.yml b/.github/workflows/generate_documentation.yml
index 1a9f9c11..d0c4ddfd 100644
--- a/.github/workflows/generate_documentation.yml
+++ b/.github/workflows/generate_documentation.yml
@@ -1,6 +1,6 @@
 name: Documentation Generation
 on:
-    push:
+    pull_request:
         branches:
             - '!master'
 env:
diff --git a/asteroid/__init__.py b/asteroid/__init__.py
index 2b005d97..b14400fd 100755
--- a/asteroid/__init__.py
+++ b/asteroid/__init__.py
@@ -8,6 +8,7 @@
 import cProfile
 import sys
 import os
+import os.path
 from asteroid.interp import interp
 from asteroid.repl import repl
 from asteroid.version import VERSION
@@ -52,21 +53,28 @@ def main():
     }
 
     flag_names = list(flags.keys())
-
-    if len(sys.argv) == 1:
-        repl(redundancy=flags['-r'],
-             prologue=flags['-p'],
-             functional_mode=flags['-F'])
-        sys.exit(0)
-
-    for fl in sys.argv:
-        if fl[0] != '-':
-            continue
-        elif fl not in flag_names:
-            print("unknown flag {}".format(fl))
-            sys.exit(0)
-        flags[fl] = not flags[fl]
-
+    argv_ix = 1
+    asteroid_ext = '.ast'
+
+    # logic of command line parameters
+    # - process all flags to Asteroid interpreter
+    # - determine if we need to respond to special flags and exit
+    # - determine if we are starting in interactive mode or not
+    #  if not in interactive mode execute the asteroid script
+
+    # process all flags to interpreter
+    while argv_ix < len(sys.argv):
+        fl = sys.argv[argv_ix]
+        if fl[0] == '-':
+            if fl not in flag_names:
+                raise ValueError("unknown flag {}".format(fl))
+            else:
+                flags[fl] = not flags[fl]
+            argv_ix += 1
+        else:
+            break
+
+    # determine if we need to respond to special flags and exit
     if flags['--help'] or flags['-h']:
         display_help()
         sys.exit(0)
@@ -75,25 +83,38 @@ def main():
         print("** Asteroid Version {} **".format(VERSION))
         sys.exit(0)
 
-    input_file = sys.argv[-1]
+    debug_flag = flags['--adb'] or flags['-g']
 
-    if input_file[0] == '-':
-        if flags['--adb']:
-            print("Please provide a file to debug")
-            sys.exit(1)
+    # determine if we are starting in interactive mode or not
+    # Note: first non-switch argument has to be an Asteroid source file
+    if len(sys.argv) == argv_ix:
+        input_file = ''
+    else:
+        input_file = sys.argv[argv_ix]
+    (input_root,input_ext) = os.path.splitext(input_file)
+    if input_file and input_ext != asteroid_ext:
+        print("error: file '{}' is not an Asteroid source file".format(input_file))
+        sys.exit(1)
+
+    # run the REPL
+    if input_ext == '' and not debug_flag:
         repl(redundancy=flags['-r'],
              prologue=flags['-p'],
              functional_mode=flags['-F'])
         sys.exit(0)
 
-    if not os.path.isfile(input_file):
-        print("unknown file {}".format(input_file))
-        sys.exit(0)
+    # we have an input file, check if it exists
+    if input_file and not os.path.isfile(input_file):
+        print("error: unknown file '{}'".format(input_file))
+        sys.exit(1)
 
-    if flags['--adb'] or flags['-g']:
+    # run the debugger
+    if debug_flag:
+        if input_ext == '':
+            print("error: please provide a file to debug")
+            sys.exit(1)
         # Create a new debugger
         db = adb.ADB()
-
         # Set the debugger's internal interpretation options
         db.interp_options = {
             'redundancy': flags['-r'],
@@ -101,10 +122,10 @@ def main():
             'functional_mode': flags['-F'],
             'exceptions': flags['-e'],
         }
-
         db.run(input_file)
         sys.exit(0)
 
+    # execute the interpreter
     f = open(input_file, 'r')
     input_stream = f.read()
     f.close()
diff --git a/asteroid/grammar.txt b/asteroid/grammar.txt
index 2ecc7385..0c540c7b 100644
--- a/asteroid/grammar.txt
+++ b/asteroid/grammar.txt
@@ -137,7 +137,7 @@
     | function_const
     | TYPEMATCH           // TYPEMATCH == '%'<typename>
 
-// Note: binding lists are only supported for constraint patterns
+/* Note: binding lists are only supported for constraint patterns */
 
   binding_list
     : BIND binding_list_suffix
diff --git a/asteroid/modules/bitwise.ast b/asteroid/modules/bitwise.ast
index 91bb887d..8ef19dc0 100644
--- a/asteroid/modules/bitwise.ast
+++ b/asteroid/modules/bitwise.ast
@@ -14,9 +14,9 @@ structure __BITWISE_MODULE__
 with
 
 ------------------------------------------------------------------
- -- Bitwise AND
 function band
 ------------------------------------------------------------------
+ -- Bitwise AND
 with(x:%integer, y:%integer) do return escape
 "
 global __retval__
@@ -28,9 +28,9 @@ __retval__ = ('integer', x_val[1] & y_val[1])
 end
 
 ------------------------------------------------------------------
- -- Bitwise OR
 function bor
 ------------------------------------------------------------------
+ -- Bitwise OR
 with(x:%integer, y:%integer) do return escape
 "
 global __retval__
@@ -42,9 +42,9 @@ __retval__ = ('integer', x_val[1] | y_val[1])
 end
 
 ------------------------------------------------------------------
- -- Bitwise NOT
 function bnot
 ------------------------------------------------------------------
+ -- Bitwise NOT
 with(x:%integer) do return escape
 "
 global __retval__
@@ -55,9 +55,9 @@ __retval__ = ('integer', ~x_val[1])
 end
 
 ------------------------------------------------------------------
- -- Bitwise XOR
 function bxor
 ------------------------------------------------------------------
+ -- Bitwise XOR
 with(x:%integer, y:%integer) do return escape
 "
 global __retval__
@@ -69,9 +69,9 @@ __retval__ = ('integer', x_val[1] ^ y_val[1])
 end
 
 ------------------------------------------------------------------
- -- Bitwise left shift
 function blshift
 ------------------------------------------------------------------
+ -- Bitwise left shift
 with(x:%integer, y:%integer) do return escape
 "
 global __retval__
@@ -83,9 +83,9 @@ __retval__ = ('integer', x_val[1] << y_val[1])
 end
 
 ------------------------------------------------------------------
- -- Bitwise right shift
 function brshift
 ------------------------------------------------------------------
+ -- Bitwise right shift
 with(x:%integer, y:%integer) do return escape
 "
 global __retval__
@@ -97,9 +97,9 @@ __retval__ = ('integer', x_val[1] >> y_val[1])
 end
 
 ------------------------------------------------------------------
--- Bitwise left rotate
 function blrotate
 ------------------------------------------------------------------
+-- Bitwise left rotate
 with(x:%integer, i:%integer) do return escape
 "
 global __retval__
@@ -117,9 +117,9 @@ __retval__ = ('integer', final)
 end
 
 ------------------------------------------------------------------
--- Bitwise right rotate
 function brrotate
 ------------------------------------------------------------------
+-- Bitwise right rotate
 with(x:%integer, i:%integer) do return escape
 "
 global __retval__
@@ -138,9 +138,9 @@ __retval__ = ('integer', final)
 end
 
 ------------------------------------------------------------------
--- Set the ith bit
 function bsetbit
 ------------------------------------------------------------------
+-- Set the ith bit
 with(x:%integer, i:%integer) do return escape
 "
 global __retval__
@@ -153,9 +153,9 @@ __retval__ = ('integer', final)
 end
 
 ------------------------------------------------------------------
--- Clear the ith bit
 function bclearbit
 ------------------------------------------------------------------
+-- Clear the ith bit
 with(x:%integer, i:%integer) do return escape
 "
 global __retval__
@@ -168,9 +168,9 @@ __retval__ = ('integer' , final)
 end
 
 ------------------------------------------------------------------
--- Get the bit size
 function bsize
 ------------------------------------------------------------------
+-- Get the bit size
 with(x:%integer) do return escape
 "
 global __retval__
diff --git a/asteroid/modules/hash.ast b/asteroid/modules/hash.ast
index 07449628..c57e3366 100644
--- a/asteroid/modules/hash.ast
+++ b/asteroid/modules/hash.ast
@@ -5,16 +5,19 @@
 --
 -- (c) Lutz Hamel, University of Rhode Island
 ------------------------------------------------------------------
+load system type.
 
 ------------------------------------------------------------------
-structure __HASHTABLE__
+structure __HASH__ with
 ------------------------------------------------------------------
 -- Asteroid hash table implementation using Python dictionaries
-with
 
+------------------------------------------------------------------
 data table.
 
+------------------------------------------------------------------
 function __init__
+------------------------------------------------------------------
 -- constructor for HashTable initializes the underlying dictionary
 with none do escape
 "
@@ -29,10 +32,11 @@ this_val = state.symbol_table.lookup_sym('this')
 # store the dictionary as a foreign object in this slot
 memory[0] = ('foreign', dict())
 "
-return none
-end
+end -- __init__
 
+------------------------------------------------------------------
 function insert
+------------------------------------------------------------------
 with (name,value) do escape
 "
 this_val = state.symbol_table.lookup_sym('this')
@@ -49,10 +53,15 @@ value_val = state.symbol_table.lookup_sym('value')
 (FOREIGN, dictionary) = memory[0]
 dictionary[name_val] = value_val
 "
-return none
-end
+with item_list:%list do
+  for (k,v) in item_list do
+    this @insert (k,v).
+  end
+end -- insert
 
+------------------------------------------------------------------
 function get
+------------------------------------------------------------------
 with name do return escape
 "
 global __retval__
@@ -73,9 +82,11 @@ if name_val not in dictionary.keys():
 else:
     __retval__ = dictionary[name_val]
 "
-end
+end -- get
 
+------------------------------------------------------------------
 function aslist
+------------------------------------------------------------------
 with none do return escape
 "
 global __retval__
@@ -104,9 +115,16 @@ for (i,t) in l:
 
 __retval__ = ('list', out_list)
 "
-end
+end -- aslist
+
+------------------------------------------------------------------
+function __str__
+------------------------------------------------------------------
+with none do
+  return type @tostring (this @aslist ()).
+end -- __str__
 
-end -- __HASHTABLE__
+end -- __HASH__
 
 ------------------------------------------------------------------
 structure __HASH_MODULE__
@@ -114,7 +132,7 @@ structure __HASH_MODULE__
 with
 
 function hash with none do
-   return __HASHTABLE__().
+   return __HASH__().
 end
 
 end -- __HASH_MODULE__
diff --git a/asteroid/modules/math.ast b/asteroid/modules/math.ast
index 3ac54a59..2e89c9e7 100644
--- a/asteroid/modules/math.ast
+++ b/asteroid/modules/math.ast
@@ -14,31 +14,23 @@ structure __MATH_MODULE__ with
 ------------------------------------------------------------------
 data pi.
 data e.
-data tau.
 
 function __init__ with none do
 
-let this @pi = escape
+let this @pi = escape -- init pi constant
 "
 from math import pi
 global __retval__
 __retval__ = ('real',pi)
 "
 
-let this @e = escape
+let this @e = escape -- init e constant
 "
 from math import e
 global __retval__
 __retval__ = ('real',e)
 "
 
-let this @tau = escape
-"
-from math import tau
-global __retval__
-__retval__ = ('real',tau)
-"
-
 end -- __init__
 
 ------------------------------------------------------------------
@@ -68,7 +60,7 @@ function log
 --
 -- With two arguments, return the logarithm of x to the given base,
 -- calculated as log(x)/log(base).
-with (x) do return escape
+with x do return escape
 "
 global __retval__
 import math
@@ -77,7 +69,7 @@ val_x = state.symbol_table.lookup_sym('x')
 
 __retval__ = ('real', math.log(val_x[1]))
 "
-with (x,base) do return escape
+with (x,base:%integer) do return escape
 "
 global __retval__
 import math
@@ -131,14 +123,13 @@ end
 function abs
 ------------------------------------------------------------------
 -- Return the absolute value of x.
-with (x) do return escape
+with x do return escape
 "
 global __retval__
-import math
 
 val_x = state.symbol_table.lookup_sym('x')
 
-__retval__ = (val_x[0], math.fabs(val_x[1]))
+__retval__ = (val_x[0], abs(val_x[1]))
 "
 end
 
@@ -180,7 +171,6 @@ function gcd
 with (a:%integer,b:%integer) do return escape
 "
 global __retval__
-from asteroid.state import state
 from math import gcd
 
 val_a = state.symbol_table.lookup_sym('a')
@@ -196,8 +186,6 @@ function isclose
 ------------------------------------------------------------------
 -- Return True if the values a and b are close to each other
 -- and false otherwise.  Default tolerance 1e-09
---
--- TODO: once we have scientific notation add a tolerance parameter.
 with (a,b) do return escape
 "
 global __retval__
diff --git a/asteroid/modules/os.ast b/asteroid/modules/os.ast
new file mode 100644
index 00000000..3e5c8106
--- /dev/null
+++ b/asteroid/modules/os.ast
@@ -0,0 +1,404 @@
+------------------------------------------------------------------
+-- os.ast
+--
+-- interface to the host OS
+--
+-- (c) University of Rhode Island
+------------------------------------------------------------------
+-- modeled after the Python os, os.path, and sys modules
+------------------------------------------------------------------
+load system hash.
+
+structure __OS_MODULE__ with
+
+------------------------------------------------------------------
+-- The list of command line arguments passed to an Asteroid script. 
+-- argv[0] is the name of the Asteroid script (it is operating 
+-- system dependent whether this is a full pathname or not).
+-- In interactive mode argv[0] will be the empty string.
+data argv.
+
+------------------------------------------------------------------
+-- A hash table where keys and values are strings that represent 
+-- the process environment. For example, 
+--    os @env @get "HOME"
+--  is the pathname of your home directory (on some platforms), 
+-- and is equivalent to getenv("HOME") in C.
+data env.
+
+------------------------------------------------------------------
+-- This string contains a platform identifier.
+data platform.
+
+------------------------------------------------------------------
+function __init__ 
+------------------------------------------------------------------
+-- constructor for the __OS_MODULE__
+with none do
+   let this @argv = this @__getargv().
+   let this @platform = this @__getplatform().
+   -- construct the env hashtable
+   let l = this @__getenv(). -- list of key/value pairs
+   let this @env = hash @hash ().
+   this @env @insert l.
+end
+
+------------------------------------------------------------------
+function __getargv 
+------------------------------------------------------------------
+with none do return escape
+"
+global __retval__
+import sys
+import copy
+import os
+import os.path
+argv = copy.copy(sys.argv)
+# pop the Asteroid interpreter
+argv.pop(0)
+# pop the flags to the Asteroid interpreter
+while len(argv) > 0 and argv[0][0] == '-':
+   argv.pop(0)
+if len(argv) == 0:
+   # if in interactive mode set argv[0] to the empty string
+   argv.append('')
+else:
+   # prepend current dir
+   if not os.path.dirname(argv[0]):
+      cwd = os.getcwd()
+      argv[0] = os.path.join(cwd,argv[0])
+# turn argv into an Asteroid list of strings
+out = []
+for e in argv:
+   out.append(('string',e))
+__retval__ = ('list', out)
+"
+end -- __getargv
+
+------------------------------------------------------------------
+function __getenv
+------------------------------------------------------------------
+with none do return escape
+"
+global __retval__
+from os import environ
+# turn dictionary into an Asteroid list
+outlist_val = []
+for (k,v) in environ.items():
+   outlist_val.append(('tuple',[('string',k),('string',v)]))
+__retval__ = ('list', outlist_val)
+"
+end -- __getplatform
+
+------------------------------------------------------------------
+function __getplatform
+------------------------------------------------------------------
+with none do return escape
+"
+global __retval__
+from sys import platform
+__retval__ = ('string', platform)
+"
+end -- __getplatform
+
+------------------------------------------------------------------
+function basename
+------------------------------------------------------------------
+-- Return the base name of pathname path. This is the second element of the pair
+-- returned by passing path to the function split(). Note that the result of this
+-- function is different from the Unix basename program; where basename for '/foo/bar/'
+-- returns 'bar', the basename() function returns an empty string ('').
+with path:%string do return escape
+"
+global __retval__
+from os.path import basename
+(STRING, path_val) = state.symbol_table.lookup_sym('path')
+__retval__ = ('string', basename(path_val))
+"
+end -- basename
+
+------------------------------------------------------------------
+function chdir
+------------------------------------------------------------------
+-- Change the current working directory to path.
+with path:%string do escape
+"
+from os.path import chdir
+(STRING, path_val) = state.symbol_table.lookup_sym('path')
+chdir(path_val)
+"
+end -- chdir
+
+------------------------------------------------------------------
+function dirname
+------------------------------------------------------------------
+-- Return the directory name of pathname path. This is the first element of the 
+-- pair returned by passing path to the function split().
+with path:%string do return escape
+"
+global __retval__
+from os.path import dirname
+(STRING, path_val) = state.symbol_table.lookup_sym('path')
+__retval__ = ('string', dirname(path_val))
+"
+end -- dirname
+
+------------------------------------------------------------------
+function exists
+------------------------------------------------------------------
+-- Return true if path refers to an existing path or an open file descriptor. 
+-- Returns false for broken symbolic links. On some platforms, this function 
+-- may return False if permission is not granted to execute os.stat() on 
+-- the requested file, even if the path physically exists.
+with path:%string do return escape
+"
+global __retval__
+from os.path import exists
+(STRING, path_val) = state.symbol_table.lookup_sym('path')
+__retval__ = ('string', exists(path_val))
+"
+end -- exists
+
+------------------------------------------------------------------
+function exit
+------------------------------------------------------------------
+-- Signaling an intention to exit the interpreter.
+-- When an argument value other than none is provided
+-- it is considered a status value. If it is 
+-- an integer, zero is considered “successful termination” and any 
+-- nonzero value is considered “abnormal termination” by shells and 
+-- the like. Most systems require it to be in the range 0–127, and 
+-- produce undefined results otherwise. Some systems have a 
+-- convention for assigning specific meanings to specific exit codes, 
+-- but these are generally underdeveloped; Unix programs generally 
+-- use 2 for command line syntax errors and 1 for all other kind 
+-- of errors. If none is given as an argument value then is it
+-- is considered to be a successful exit equivalent to passing a zero. 
+-- If a string is passed then it is printed printed to 
+-- __STDERR__ and results in an exit code of 1. In particular, 
+-- sys.exit("some error message") is a quick way to exit a program 
+-- when an error occurs.
+with none do escape
+"
+import sys
+sys.exit(0)
+"
+with v:%integer do escape
+"
+import sys
+v_val = state.symbol_table.lookup_sym('v')
+sys.exit(v_val[1])
+"
+with msg:%string do escape
+"
+import sys
+msg_val = state.symbol_table.lookup_sym('msg')
+sys.exit(msg_val[1])
+"
+end
+
+------------------------------------------------------------------
+function getdir
+------------------------------------------------------------------
+-- Return a string representing the current working directory.
+with none do return escape
+"
+global __retval__
+from os import getcwd
+__retval__ = ('string', getcwd())
+"
+end -- getdir
+
+------------------------------------------------------------------
+function getpathtime
+------------------------------------------------------------------
+-- Returns a triple with (creation,access,modification) times.
+-- By default the return value is a triple of real numbers
+-- giving the number of seconds since 1/1/1970.  If the flag is set
+-- to true then a triple of strings is returned where each string
+-- represents the respective local time. Throws an exception if the file 
+-- does not exist or is inaccessible.
+with path:%string do return escape
+"
+global __retval__
+from os.path import getctime, getatime, getmtime
+(STRING, path_val) = state.symbol_table.lookup_sym('path')
+ct = ('real', getctime(path_val))
+at = ('real', getatime(path_val))
+mt = ('real', getmtime(path_val))
+__retval__ = ('tuple',[ct, at, mt])
+"
+with (path:%string,flag:%boolean) do return escape
+"
+global __retval__
+from os.path import getctime, getatime, getmtime
+from time import ctime
+(STRING, path_val) = state.symbol_table.lookup_sym('path')
+(BOOLEAN, flag_val) = state.symbol_table.lookup_sym('flag')
+
+if not flag_val:
+   ct = ('real', getctime(path_val))
+   at = ('real', getatime(path_val))
+   mt = ('real', getmtime(path_val))
+else:
+   ct = ('string', ctime(getctime(path_val)))
+   at = ('string', ctime(getatime(path_val)))
+   mt = ('string', ctime(getmtime(path_val)))
+
+__retval__ = ('tuple',[ct, at, mt])
+"
+end -- getpathtime
+
+------------------------------------------------------------------
+function getsize
+------------------------------------------------------------------
+-- Return the size, in bytes, of path. Throws exception if the file 
+-- does not exist or is inaccessible.
+with path:%string do return escape
+"
+global __retval__
+from os.path import getsize
+(STRING, path_val) = state.symbol_table.lookup_sym('path')
+__retval__ = ('integer', getsize(path_val))
+"
+end -- getsize
+
+------------------------------------------------------------------
+function isfile
+------------------------------------------------------------------
+-- Return true if path is an existing regular file. This follows 
+-- symbolic links.
+with path:%string do return escape
+"
+global __retval__
+from os.path import isfile
+(STRING, path_val) = state.symbol_table.lookup_sym('path')
+__retval__ = ('boolean', isfile(path_val))
+"
+end -- isfile
+
+------------------------------------------------------------------
+function isdir
+------------------------------------------------------------------
+-- Return true if path is an existing directory. This follows 
+-- symbolic links.
+with path:%string do return escape
+"
+global __retval__
+from os.path import isdir
+(STRING, path_val) = state.symbol_table.lookup_sym('path')
+__retval__ = ('boolean', isdir(path_val))
+"
+end -- isdir
+
+------------------------------------------------------------------
+function join
+------------------------------------------------------------------
+-- Join path1 and path2 components intelligently. The return value 
+-- is the concatenation of path and any members of *paths with 
+-- exactly one directory separator following each non-empty part 
+-- except the last, meaning that the result will only end in a 
+-- separator if the last part is empty. If the second component is an 
+-- absolute path, the first component is thrown away. 
+--
+-- On Windows, the drive letter is not reset when an absolute 
+-- path component (e.g., r'\foo') is encountered. If a component 
+-- contains a drive letter, all previous components are thrown away 
+-- and the drive letter is reset. Note that since there is a current 
+-- directory for each drive, os.path.join("c:", "foo") represents a 
+-- path relative to the current directory on drive C: (c:foo), not c:\foo.
+with (path1:%string,path2:%string) do return escape
+"
+global __retval__
+from os.path import join
+(STRING, path1_val) = state.symbol_table.lookup_sym('path1')
+(STRING, path2_val) = state.symbol_table.lookup_sym('path2')
+__retval__ = ('string', join(path1_val,path2_val))
+"
+end -- join
+
+------------------------------------------------------------------
+function split
+------------------------------------------------------------------
+-- Split the pathname path into a pair, (head, tail) where tail is 
+-- the last pathname component and head is everything leading up to 
+-- that. The tail part will never contain a slash; if path ends in 
+-- a slash, tail will be empty. If there is no slash in path, head 
+-- will be empty. If path is empty, both head and tail are empty. 
+-- Trailing slashes are stripped from head unless it is the root 
+-- (one or more slashes only). Also see the functions dirname and 
+-- basename.
+with path:%string do return escape
+"
+global __retval__
+from os.path import split
+(STRING, path_val) = state.symbol_table.lookup_sym('path')
+(head, tail) = split(path_val)
+__retval__ = ('tuple', [('string',head),('string',tail)])
+"
+end -- split
+
+------------------------------------------------------------------
+function splitdrive
+------------------------------------------------------------------
+-- Split the pathname path into a pair (drive, tail) where drive is 
+-- either a mount point or the empty string. On systems which do not 
+-- use drive specifications, drive will always be the empty string. 
+-- In all cases, drive + tail will be the same as path.
+--
+-- On Windows, splits a pathname into drive/UNC sharepoint and 
+-- relative path.
+--
+-- If the path contains a drive letter, drive will contain everything 
+-- up to and including the colon.
+with path:%string do return escape
+"
+global __retval__
+from os.path import splitdrive
+(STRING, path_val) = state.symbol_table.lookup_sym('path')
+(drive, tail) = splitdrive(path_val)
+__retval__ = ('tuple', [('string',drive),('string',tail)])
+"
+end -- splitdrive
+
+------------------------------------------------------------------
+function splitext
+------------------------------------------------------------------
+-- Split the pathname path into a pair (root, ext) such that 
+-- root + ext == path, and the extension, ext, is empty or begins 
+-- with a period and contains at most one period. If the path contains 
+-- no extension, ext will be the empty string.
+with path:%string do return escape
+"
+global __retval__
+from os.path import splitext
+(STRING, path_val) = state.symbol_table.lookup_sym('path')
+(root, ext) = splitext(path_val)
+__retval__ = ('tuple', [('string',root),('string',ext)])
+"
+end -- splitext
+
+------------------------------------------------------------------
+function syscmd
+------------------------------------------------------------------
+-- Execute a command (a string) in a subshell. This is implemented 
+-- by calling the Standard C function system(), and has the same 
+-- limitations. If command generates any output, it will be 
+-- sent to the interpreter standard output stream. 
+-- The C standard does not specify the meaning of the return value of 
+-- the C function, so the return value of this function is 
+-- system-dependent.
+with cmd:%string do return escape
+"
+global __retval__
+from os import system
+(STRING, cmd_val) = state.symbol_table.lookup_sym('cmd')
+status = sytem(cmd_val)
+__retval__ = ('integer', status)
+"
+end -- syscmd
+
+end -- __OS_MODULE__
+
+------------------------------------------------------------------
+let os = __OS_MODULE__().
diff --git a/asteroid/modules/pick.ast b/asteroid/modules/pick.ast
index bb40b348..c1f2e79f 100644
--- a/asteroid/modules/pick.ast
+++ b/asteroid/modules/pick.ast
@@ -12,20 +12,24 @@ load system random.
 structure __PICK__
 ------------------------------------------------------------------
 -- A pick object holds a list of items that
--- we can randomly pick from with the 'pick'
+-- we can randomly pick from with the 'pickitems'
 -- member function
 
   with
 
   data items.
 
-  function pick with n:%integer do
-      let l = [].
-      for i in 1 to n do
-          let ix = random @randint(0, this @items @length()-1).
-          l @append(this @items @ix).
-      end
-      return l.
+  function pickitems
+    with none do
+        let ix = random @randint(0, this @items @length()-1).
+        return this @items @ix.
+    with n:%integer do
+        let l = [].
+        for i in 1 to n do
+            let ix = random @randint(0, this @items @length()-1).
+            l @append(this @items @ix).
+        end
+        return l.
   end
 
   --make sure that we only pass lists into the constructor
diff --git a/asteroid/modules/prologue.ast b/asteroid/modules/prologue.ast
index 1f952912..8f8ceef1 100644
--- a/asteroid/modules/prologue.ast
+++ b/asteroid/modules/prologue.ast
@@ -101,7 +101,7 @@ function range
 ------------------------------------------------------------------
 function getid
 ------------------------------------------------------------------
-# get the id (physical memory address) of 'x' as an Asteroid integer
+-- get the id (physical memory address) of 'x' as an Asteroid integer
 with x do return escape
 "
 global __retval__
@@ -116,12 +116,10 @@ function isdefined
 -- return true if a variable or type name is defined in the
 -- current environment otherwise return false
 -- the variable and type name is given as a string
-with __x__ do return escape
+with __x__:%string do return escape
 "
 global __retval__
 (STRING, v)  = state.symbol_table.lookup_sym('__x__')
-if STRING != 'string':
-   raise ValueError('expected a string argument')
 try:
    state.symbol_table.lookup_sym(v)
 except ValueError:
@@ -217,8 +215,7 @@ end
 function __list_extend__
 ------------------------------------------------------------------
 -- Extend the list by appending all the items
--- from the item where item is either a list,
--- a string or a tuple.
+-- from the item where item is either a list or a tuple.
 with item do return escape
 "
 global __retval__
@@ -226,7 +223,7 @@ global __retval__
 this_val = state.symbol_table.lookup_sym('this')
 item_val = state.symbol_table.lookup_sym('item')
 
-if item_val[0] not in ['list', 'string', 'tuple']:
+if item_val[0] not in ['list', 'tuple']:
     raise ValueError('extend expected a list, string, or tuple, got \'{}\''
                 .format(item_val[0]))
 
diff --git a/asteroid/modules/random.ast b/asteroid/modules/random.ast
index f160997e..6deaedbf 100644
--- a/asteroid/modules/random.ast
+++ b/asteroid/modules/random.ast
@@ -28,7 +28,7 @@ end
 function randint -- random interval
 ------------------------------------------------------------------
 -- return a random value N in the interval lo <= N <= hi.
--- The of the random value depends on the types of the
+-- The type of the random value depends on the types of the
 -- values specifying the interval.
 with (lo:%integer,hi:%integer) do return escape
 "
diff --git a/asteroid/modules/set.ast b/asteroid/modules/set.ast
index a3885203..af69f9a5 100644
--- a/asteroid/modules/set.ast
+++ b/asteroid/modules/set.ast
@@ -14,49 +14,49 @@ structure __SET_MODULE__
 with
 
 ------------------------------------------------------------------
-function toset
+function diff
 ------------------------------------------------------------------
-with (lst:%list) do return escape
+with (a:%list,b:%list) do return escape
 "
 global __retval__
-lst_val = state.symbol_table.lookup_sym('lst')
-__retval__ = ('list', list(set(lst_val[1])))
+a_val = state.symbol_table.lookup_sym('a')
+b_val = state.symbol_table.lookup_sym('b')
+__retval__ = ('list', list(set(a_val[1]) - set(b_val[1])))
 "
 end
 
 ------------------------------------------------------------------
-function diff
+function intersection
 ------------------------------------------------------------------
 with (a:%list,b:%list) do return escape
 "
 global __retval__
 a_val = state.symbol_table.lookup_sym('a')
 b_val = state.symbol_table.lookup_sym('b')
-__retval__ = ('list', list(set(a_val[1]) - set(b_val[1])))
+__retval__ = ('list', list(set(a_val[1]) & set(b_val[1])))
 "
 end
 
 ------------------------------------------------------------------
-function union
+function toset
 ------------------------------------------------------------------
-with (a:%list,b:%list) do return escape
+with (lst:%list) do return escape
 "
 global __retval__
-a_val = state.symbol_table.lookup_sym('a')
-b_val = state.symbol_table.lookup_sym('b')
-__retval__ = ('list', list(set(a_val[1]) | set(b_val[1])))
+lst_val = state.symbol_table.lookup_sym('lst')
+__retval__ = ('list', list(set(lst_val[1])))
 "
 end
 
 ------------------------------------------------------------------
-function intersection
+function union
 ------------------------------------------------------------------
 with (a:%list,b:%list) do return escape
 "
 global __retval__
 a_val = state.symbol_table.lookup_sym('a')
 b_val = state.symbol_table.lookup_sym('b')
-__retval__ = ('list', list(set(a_val[1]) & set(b_val[1])))
+__retval__ = ('list', list(set(a_val[1]) | set(b_val[1])))
 "
 end
 
diff --git a/asteroid/modules/stream.ast b/asteroid/modules/stream.ast
index b2c4a109..020c3f0e 100644
--- a/asteroid/modules/stream.ast
+++ b/asteroid/modules/stream.ast
@@ -25,6 +25,11 @@ function __init__
     let this @curr_ix = 0.
   end
 
+function append
+  with item do
+    this @stream @append item.
+  end
+
 function eof
   with none do
     if this @curr_ix == this @stream @length() do
@@ -34,15 +39,6 @@ function eof
     end
   end
 
-function peek
-  with none do
-    if this @eof() do
-      return none.
-    else do
-      return this @stream @(this @curr_ix).
-    end
-  end
-
 function get
   with none do
     if this @eof() do
@@ -54,11 +50,6 @@ function get
     end
   end
 
-function rewind
-  with none do
-    let this @curr_ix = 0.
-  end
-
 function map
   with f:%function do
     for i in range(this @stream @length()) do
@@ -66,9 +57,18 @@ function map
     end
   end
 
-function append
-  with item do
-    this @stream @append item.
+function peek
+  with none do
+    if this @eof() do
+      return none.
+    else do
+      return this @stream @(this @curr_ix).
+    end
+  end
+
+function rewind
+  with none do
+    let this @curr_ix = 0.
   end
 
 function __string__
diff --git a/asteroid/modules/type.ast b/asteroid/modules/type.ast
index 91d716bf..33705436 100644
--- a/asteroid/modules/type.ast
+++ b/asteroid/modules/type.ast
@@ -47,45 +47,68 @@ structure __TYPE_MODULE__ with
 ------------------------------------------------------------------
 
 ------------------------------------------------------------------
-function tointeger
+function tobase
 ------------------------------------------------------------------
-with (item:%string,base:%integer) do return escape
+-- represent the given integer x as a numeral in different bases
+with (x:%integer,base:%integer) do return escape
 "
 global __retval__
-item_val = state.symbol_table.lookup_sym('item')
+
+x_val = state.symbol_table.lookup_sym('x')
 base_val = state.symbol_table.lookup_sym('base')
-__retval__ = ('integer', int(item_val[1], base=base_val[1]))
+
+if base_val[1] == 2:
+  __retval__ = ('string', format(x_val[1],'b'))
+elif base_val[1] == 8:
+  __retval__ = ('string', format(x_val[1],'o'))
+elif base_val[1] == 16:
+  __retval__ = ('string', format(x_val[1],'X'))
+else:
+  raise ValueError('illegal base value {}'
+          .format(base_val[1]))
 "
+end
+
+------------------------------------------------------------------
+function toboolean
+------------------------------------------------------------------
 with item do return escape
 "
 global __retval__
 
 item_val = state.symbol_table.lookup_sym('item')
-__retval__ = ('integer', int(item_val[1]))
+__retval__ = ('boolean', bool(item_val[1]))
 "
 end
 
 ------------------------------------------------------------------
-function toreal
+function tointeger
 ------------------------------------------------------------------
+with (item:%string,base:%integer) do return escape
+"
+global __retval__
+item_val = state.symbol_table.lookup_sym('item')
+base_val = state.symbol_table.lookup_sym('base')
+__retval__ = ('integer', int(item_val[1], base=base_val[1]))
+"
 with item do return escape
 "
 global __retval__
 
 item_val = state.symbol_table.lookup_sym('item')
-__retval__ = ('real', float(item_val[1]))
+__retval__ = ('integer', int(item_val[1]))
 "
 end
 
 ------------------------------------------------------------------
-function toboolean
+function toreal
 ------------------------------------------------------------------
 with item do return escape
 "
 global __retval__
 
 item_val = state.symbol_table.lookup_sym('item')
-__retval__ = ('boolean', bool(item_val[1]))
+__retval__ = ('real', float(item_val[1]))
 "
 end
 
@@ -166,29 +189,6 @@ with l:%integer do
   return __STRINGFORMAT__(l).
 end
 
-------------------------------------------------------------------
-function tobase
-------------------------------------------------------------------
--- represent the given integer x as a numeral in different bases
-with (x:%integer,base:%integer) do return escape
-"
-global __retval__
-
-x_val = state.symbol_table.lookup_sym('x')
-base_val = state.symbol_table.lookup_sym('base')
-
-if base_val[1] == 2:
-  __retval__ = ('string', format(x_val[1],'b'))
-elif base_val[1] == 8:
-  __retval__ = ('string', format(x_val[1],'o'))
-elif base_val[1] == 16:
-  __retval__ = ('string', format(x_val[1],'X'))
-else:
-  raise ValueError('illegal base value {}'
-          .format(base_val[1]))
-"
-end
-
 ------------------------------------------------------------------
 -- TYPE QUERY FUNCTIONS --
 ------------------------------------------------------------------
@@ -201,17 +201,17 @@ with item do
 end
 
 ------------------------------------------------------------------
-function isscalar
+function isnone
 ------------------------------------------------------------------
-with item do
-  return (item is %integer) or (item is %real).
+with x do
+  return x is %none.
 end
 
 ------------------------------------------------------------------
-function isnone
+function isscalar
 ------------------------------------------------------------------
-with x do
-  return x is %none.
+with item do
+  return (item is %integer) or (item is %real).
 end
 
 ------------------------------------------------------------------
diff --git a/asteroid/modules/util.ast b/asteroid/modules/util.ast
index 5fd74165..7698a8ff 100644
--- a/asteroid/modules/util.ast
+++ b/asteroid/modules/util.ast
@@ -9,26 +9,47 @@
 load system type.
 
 ------------------------------------------------------------------
-structure __UTIL_MODULE__ with
+structure __UTIL_MODULE__ 
+------------------------------------------------------------------
+with
 
 ------------------------------------------------------------------
--- UTILITY FUNCTIONS --
+function achar
 ------------------------------------------------------------------
+-- given a decimal ASCII code return the corresponding character symbol
+with item:%integer do return escape
+"
+global __retval__
+item_val = state.symbol_table.lookup_sym('item')
+__retval__ = ('string', str(chr(item_val[1])))
+"
+end
 
 ------------------------------------------------------------------
-function exit
+function ascii
 ------------------------------------------------------------------
-with none do escape
+-- given a char return the corresponding ASCII code.
+with item:%string do return escape
 "
-import sys
-sys.exit(1)
+global __retval__
+item_val = state.symbol_table.lookup_sym('item')
+__retval__ = ('integer', ord(item_val[1]))
 "
-with msg:%string do escape
+end
+
+------------------------------------------------------------------
+function cls
+------------------------------------------------------------------
+-- clear screen
+with none do escape
 "
-import sys
-msg_val = state.symbol_table.lookup_sym('msg')
-print(msg_val[1])
-sys.exit(1)
+import os
+import platform
+
+if platform.win32_ver()[0]:
+    os.system('cls')
+else:
+    os.system('clear')
 "
 end
 
@@ -46,18 +67,17 @@ __retval__ = copy.deepcopy(obj_val)
 end
 
 ------------------------------------------------------------------
-function cls
+function ctime
 ------------------------------------------------------------------
--- clear screen
-with none do escape
+-- Converts the time as a real value in secs since 1/1/1970 into
+-- string representing local time.
+with t:%real do return escape
 "
-import os
-import platform
+global __retval__
+from time import ctime
+(REAL, t_val) = state.symbol_table.lookup_sym('t')
 
-if platform.win32_ver()[0]:
-    os.system('cls')
-else:
-    os.system('clear')
+__retval__ = ('string', ctime(t_val))
 "
 end
 
@@ -67,33 +87,21 @@ function sleep
 -- program sleep for secs seconds
 with secs if type @isscalar(secs) do escape
 "
-import time
+from time import sleep
 secs_val = state.symbol_table.lookup_sym('secs')
-time.sleep(secs_val[1])
+sleep(secs_val[1])
 "
 end
 
 ------------------------------------------------------------------
-function zip
+function time
 ------------------------------------------------------------------
--- implements Python's zip function
-with (list1:%list,list2:%list) do return escape
+-- Returns the local time as a real value in secs since 1/1/1970
+with none do return escape
 "
 global __retval__
-
-list1_val = state.symbol_table.lookup_sym('list1')
-list2_val = state.symbol_table.lookup_sym('list2')
-
-# zip it with Python's zip
-l = list(zip(list1_val[1], list2_val[1]))
-
-# turn Python tuples into Asteroid tuples and
-# put them onto an output list
-out_list = []
-for (i,t) in l:
-  out_list.append(('tuple',[i,t]))
-
-__retval__ = ('list', out_list)
+from time import time
+__retval__ = ('real', time())
 "
 end
 
@@ -119,26 +127,26 @@ __retval__ = ('tuple', [('list', c1list), ('list',c2list)])
 end
 
 ------------------------------------------------------------------
-function ascii
+function zip
 ------------------------------------------------------------------
--- given a char return the corresponding ASCII code.
-with item:%string do return escape
+-- implements Python's zip function
+with (list1:%list,list2:%list) do return escape
 "
 global __retval__
-item_val = state.symbol_table.lookup_sym('item')
-__retval__ = ('integer', ord(item_val[1]))
-"
-end
 
-------------------------------------------------------------------
-function achar
-------------------------------------------------------------------
--- given a decimal ASCII code return the corresponding character symbol
-with item:%integer do return escape
-"
-global __retval__
-item_val = state.symbol_table.lookup_sym('item')
-__retval__ = ('string', str(chr(item_val[1])))
+list1_val = state.symbol_table.lookup_sym('list1')
+list2_val = state.symbol_table.lookup_sym('list2')
+
+# zip it with Python's zip
+l = list(zip(list1_val[1], list2_val[1]))
+
+# turn Python tuples into Asteroid tuples and
+# put them onto an output list
+out_list = []
+for (i,t) in l:
+  out_list.append(('tuple',[i,t]))
+
+__retval__ = ('list', out_list)
 "
 end
 
diff --git a/asteroid/modules/vector.ast b/asteroid/modules/vector.ast
index 2f8716cd..4d00802a 100644
--- a/asteroid/modules/vector.ast
+++ b/asteroid/modules/vector.ast
@@ -12,6 +12,28 @@ load system type.
 ------------------------------------------------------------------
 structure __VECTOR_MODULE__ with
 
+------------------------------------------------------------------
+function add
+------------------------------------------------------------------
+with (a,b) do
+  return this @op(lambda with (x,y) do return x+y,a,b).
+end
+
+------------------------------------------------------------------
+function dot
+-- computes the dot product of two lists
+------------------------------------------------------------------
+with (a:%list,b:%list) do
+  return this @mult(a,b) @reduce(lambda with (x,y) do return x+y).
+end
+
+------------------------------------------------------------------
+function mult
+------------------------------------------------------------------
+with (a,b) do
+  return this @op(lambda with (x,y) do return x*y,a,b).
+end
+
 ------------------------------------------------------------------
 function op
 ------------------------------------------------------------------
@@ -35,13 +57,6 @@ with (f:%function,a if type @isscalar(a),b:%list) do
   return v @map(f).
 end
 
-------------------------------------------------------------------
-function add
-------------------------------------------------------------------
-with (a,b) do
-  return this @op(lambda with (x,y) do return x+y,a,b).
-end
-
 ------------------------------------------------------------------
 function sub
 ------------------------------------------------------------------
@@ -49,20 +64,6 @@ with (a,b) do
   return this @op(lambda with (x,y) do return x-y,a,b).
 end
 
-------------------------------------------------------------------
-function mult
-------------------------------------------------------------------
-with (a,b) do
-  return this @op(lambda with (x,y) do return x*y,a,b).
-end
-
-------------------------------------------------------------------
-function dot
--- computes the dot product of two lists
-------------------------------------------------------------------
-with (a:%list,b:%list) do
-  return this @mult(a,b) @reduce(lambda with (x,y) do return x+y).
-end
 
 end -- __VECTOR_MODULE__
 
diff --git a/docs/ADB.rst b/docs/ADB.rst
index a2a31f08..ec99053a 100644
--- a/docs/ADB.rst
+++ b/docs/ADB.rst
@@ -1,14 +1,15 @@
-/******************************************************************
-  This is the source file from which the action doc is generated.
-  We use cpp to insert live code snippets into the document.
-  In order to generate the action doc run the following command
-  on a Unix-like system:
-
-  cpp -w -P "ADB.txt" > "ADB.rst"
+..
+    /******************************************************************
+    This is the source file from which the action doc is generated.
+    We use cpp to insert live code snippets into the document.
+    In order to generate the action doc run the following command
+    on a Unix-like system:
 
- ******************************************************************/
-/* header for generated .rst files */
+    cpp -w -P "ADB.txt" > "ADB.rst"
 
+    ******************************************************************/
+..
+   /* header for generated .rst files */
 ..
    *** DO NOT EDIT; MACHINE GENERATED ***
 ===================
diff --git a/docs/ADB.txt b/docs/ADB.txt
index 5318b9e4..2153a9e7 100644
--- a/docs/ADB.txt
+++ b/docs/ADB.txt
@@ -1,12 +1,14 @@
-/******************************************************************
-  This is the source file from which the action doc is generated.
-  We use cpp to insert live code snippets into the document.
-  In order to generate the action doc run the following command
-  on a Unix-like system:
+..
+    /******************************************************************
+    This is the source file from which the action doc is generated.
+    We use cpp to insert live code snippets into the document.
+    In order to generate the action doc run the following command
+    on a Unix-like system:
 
-  cpp -w -P "ADB.txt" > "ADB.rst"
+    cpp -w -P "ADB.txt" > "ADB.rst"
+
+    ******************************************************************/
 
- ******************************************************************/
 #include "header.txt"
 
 ===================
diff --git a/docs/Asteroid in Action.rst b/docs/Asteroid in Action.rst
index 2a3ad468..54cfd0e1 100644
--- a/docs/Asteroid in Action.rst
+++ b/docs/Asteroid in Action.rst
@@ -1,13 +1,15 @@
-/******************************************************************
-  This is the source file from which the action doc is generated.
-  We use cpp to insert live code snippets into the document.
-  In order to generate the action doc run the following command
-  on a Unix-like system:
+..
+    /******************************************************************
+    This is the source file from which the action doc is generated.
+    We use cpp to insert live code snippets into the document.
+    In order to generate the action doc run the following command
+    on a Unix-like system:
 
-  cpp -w -P "Asteroid in Action.txt" > "Asteroid in Action.rst"
+    cpp -w -P "Asteroid in Action.txt" > "Asteroid in Action.rst"
 
- ******************************************************************/
-/* header for generated .rst files */
+    ******************************************************************/
+..
+   /* header for generated .rst files */
 
 ..
    *** DO NOT EDIT; MACHINE GENERATED ***
diff --git a/docs/Asteroid in Action.txt b/docs/Asteroid in Action.txt
index 10f419db..266082e9 100644
--- a/docs/Asteroid in Action.txt
+++ b/docs/Asteroid in Action.txt
@@ -1,12 +1,13 @@
-/******************************************************************
-  This is the source file from which the action doc is generated.
-  We use cpp to insert live code snippets into the document.
-  In order to generate the action doc run the following command
-  on a Unix-like system:
+..
+    /******************************************************************
+    This is the source file from which the action doc is generated.
+    We use cpp to insert live code snippets into the document.
+    In order to generate the action doc run the following command
+    on a Unix-like system:
 
-  cpp -w -P "Asteroid in Action.txt" > "Asteroid in Action.rst"
+    cpp -w -P "Asteroid in Action.txt" > "Asteroid in Action.rst"
 
- ******************************************************************/
+    ******************************************************************/
 #include "header.txt"
 
 .. highlight:: none
diff --git a/docs/Quickstart Tutorial.rst b/docs/Quickstart Tutorial.rst
index 379ef8de..b0e17dbe 100644
--- a/docs/Quickstart Tutorial.rst
+++ b/docs/Quickstart Tutorial.rst
@@ -1,14 +1,16 @@
-/******************************************************************
-  This is the source file from which the reference guide is
-  generated.  We use cpp to insert live code snippets into the
-  document. In order to generate the reference guide run the
-  following command on a Unix-like system in the directory of
-  this doc:
+..
+   /******************************************************************
+   This is the source file from which the reference guide is
+   generated.  We use cpp to insert live code snippets into the
+   document. In order to generate the reference guide run the
+   following command on a Unix-like system in the directory of
+   this doc:
 
-  bash generate_docs
+   bash generate_docs
 
- ******************************************************************/
-/* header for generated .rst files */
+   ******************************************************************/
+..
+   /* header for generated .rst files */
 
 ..
    *** DO NOT EDIT; MACHINE GENERATED ***
diff --git a/docs/Quickstart Tutorial.txt b/docs/Quickstart Tutorial.txt
index 1f689d41..7a653250 100644
--- a/docs/Quickstart Tutorial.txt
+++ b/docs/Quickstart Tutorial.txt
@@ -1,13 +1,15 @@
-/******************************************************************
-  This is the source file from which the reference guide is
-  generated.  We use cpp to insert live code snippets into the
-  document. In order to generate the reference guide run the
-  following command on a Unix-like system in the directory of
-  this doc:
+..
+   /******************************************************************
+   This is the source file from which the reference guide is
+   generated.  We use cpp to insert live code snippets into the
+   document. In order to generate the reference guide run the
+   following command on a Unix-like system in the directory of
+   this doc:
 
-  bash generate_docs
+   bash generate_docs
+
+   ******************************************************************/
 
- ******************************************************************/
 #include "header.txt"
 
 .. highlight:: none
diff --git a/docs/Reference Guide.rst b/docs/Reference Guide.rst
index a65874a4..4781890b 100644
--- a/docs/Reference Guide.rst
+++ b/docs/Reference Guide.rst
@@ -1,14 +1,16 @@
-/******************************************************************
-  This is the source file from which the reference guide is
-  generated.  We use cpp to insert live code snippets into the
-  document. In order to generate the reference guide run the
-  following command on a Unix-like system in the directory of
-  this doc:
+..
+      /******************************************************************
+      This is the source file from which the reference guide is
+      generated.  We use cpp to insert live code snippets into the
+      document. In order to generate the reference guide run the
+      following command on a Unix-like system in the directory of
+      this doc:
 
-  bash generate_docs
+      bash generate_docs
 
- ******************************************************************/
-/* header for generated .rst files */
+      ******************************************************************/
+..
+   /* header for generated .rst files */
 
 ..
    *** DO NOT EDIT; MACHINE GENERATED ***
@@ -641,7 +643,7 @@ Here ``k`` only matches the value of ``val`` if that value is an even number.
 Pure Constraint Patterns
 %%%%%%%%%%%%%%%%%%%%%%%%
 
-Syntax: ``%[ pattern ]%``
+Syntax: ``%[ pattern ]% (BIND '[' ID (AS ID)? (',' ID (AS ID)?)*']')?``
 
 A pure constraint pattern is a pattern that does not create any bindings
 in the current scope.  Any pattern can be turned into a pure constraint pattern
@@ -727,7 +729,7 @@ are written in quotes.
 
   pattern
     : PATTERN WITH? exp
-    | '%[' exp ']%' binding_list?
+    | '%[' exp ']%' 
     | head_tail
 
   head_tail
@@ -788,7 +790,7 @@ are written in quotes.
     | function_const
     | TYPEMATCH           // TYPEMATCH == '%'<typename>
 
-// Note: binding lists are only supported for constraint patterns
+
 
   binding_list
     : BIND binding_list_suffix
@@ -813,30 +815,37 @@ are written in quotes.
 Builtin Functions
 -----------------
 
-* Function ``len``, when given an input value, returns the length of that input. The
-  function can only be applied to lists, strings, tuples, or structures.
+**getid** x
+      Returns a unique id of any Asteroid object as an integer.
 
-* Function ``hd``, when given a list as input returns the first element of that list.
-  It is an error to apply this function to an empty list.
+**hd** x:%list
+      Returns the first element of a list. It is an error to apply this
+      function to an empty list.
 
-* Function ``tl``, when given a list as input returns the rest of the list without the first element.
-  It is an error to apply this function to an empty list.
+**isdefined** x:%string
+      Returns true if a variable or type name is defined in the
+      current environment otherwise it returns false. The variable or type name must be given as a string.
+**len** x
+      Returns the length of x. The
+      function can only be applied to lists, strings, tuples, or structures.
 
-* Function ``range`` will compute a list of values depending on the input values:
+**range**  stop:%integer | (start:%integer, stop:%integer) | (start:%integer, stop:%integer, inc:%integer)
+      Compute a list of values depending on the input values:
 
-  1. ``(start:%integer,stop:%integer)`` returns list ``[start to stop-1]``.
-  2. ``(start:%integer,stop:%integer,inc:%integer)`` returns list ``[start to stop-1 step inc]``.
-  3. ``(stop:%integer)`` returns list ``[0 to stop-1]``.
+      1. If only the stop value is given then the list [0 to stop-1] is returned.
+      2. If the start and stop values are given then the list [start to stop-1] is returned.
+      3. If in addition to the start and stop values the inc values is given then the list [start to stop-1 step inc] is returned.
+
+**tl** x:%list
+      Returns the rest of the list without the first element.  It is an
+      error to apply this function to an empty list.
 
-* Function ``getid`` returns the id (physical memory address) of any Asteroid object as an Asteroid integer.
 
-* Function ``isdefined`` returns true if a variable or type name is defined in the
-  current environment otherwise it returns false. The variable or type name must be given as a string.
 
 List and String Objects
 -----------------------
 
-In Asteroid, both ``lists`` and ``strings,`` are treated like objects. Due to this, they have member functions that can manipulate the contents of those objects.
+In Asteroid, both ``lists`` and ``strings,`` are treated like objects in the OO sense. Due to this, they have member functions that can manipulate the contents of those objects.
 
 Lists
 ^^^^^
@@ -845,85 +854,155 @@ A **list** is a structured data type that consists of square brackets enclosing
 comma-separated values.
 Member functions on lists can be called on the data structure directly, e.g.::
 
-   [1,2,3] @length()
+   [1,2,3] @length ()
+
+Member Functions
+%%%%%%%%%%%%%%%%
+
+list **@append** item
+      Adds the item to the end of the list.
+
+list **@clear** ()
+      Removes all items from the list.
+
+list **@copy** ()
+      Returns a shallow copy of the list.
+
+list **@count** item
+      Returns the number of times item appears in the list.
 
-* Function ``length`` returns the number of elements within that list.
-* Function ``append``, given ``(item)``, adds that item to the end of a list.
-* Function ``extend``, given ``(item)``, will extend the list by adding all the items from the item where ``item`` is either a list, a string or a tuple.
-* Function ``insert``, given ``(ix:%integer,item)``, will insert an item at a given position. The first argument is the index of the element before which to insert, so ``a@insert(0, x)`` inserts at the front of the list, and ``a@insert(a@length(), x)`` is equivalent to ``a@append(x)``.
-* Function ``remove``, given ``(item)``, removes the first element from the list whose value is equal to ``(item)``. It raises a ValueError if there is no such item.
-* Function ``pop``, given ``(ix:%integer)``, removes the item at the given position in the list and returns it. If no index is specified,``a@pop()`` removes and returns the last item in the list.
-* Function ``clear``, given ``(none)``, removes all items from the list.
-* Function ``index`` returns a zero-based index in the list of the first element whose value is equal to ``(item)``. It raises a ValueError exception if there is no such item. The optional argument ``loc`` allows you to specify ``(startix)`` and ``(endix)`` and are used to limit the search to a particular subsequence of the list. The returned index is computed relative to the beginning of the full sequence rather than the ``(startix)`` argument.   This function can be called with several input configurations:
+list **@extend** item
+      Extend the list by adding all the elements from the item to the list where the item is either a list or a tuple.
 
-  1. ``(item,loc(startix:%integer,endix:%integer))``
-  2. ``(item,loc(startix:%integer))``
-  3. ``item``
+list **@filter** f:%function
+      Returns a list constructed from those elements for which function f returns true.
 
-* Function ``count``, given ``(item)``, returns the number of times ``(item)`` appears in the list.
-* Function ``sort`` sorts the items of the list in place. It can be called with several different inputs:
+list **@index** item | (item, loc(startix:%integer) | (item, loc(startix:%integer, endix:%integer))
+      Returns a zero-based index of the first element whose value is equal to item.
+      It throws an exception if there is no such item. The argument loc allows you to specify
+      startix and endix and are used to limit the search to a particular subsequence of the list.
+      The returned index is computed relative to the beginning of the list rather than the startix argument.
 
-  1. ``(reverse:%boolean)`` if the boolean is set to true then the sorted list is reversed.
-  2. ``none`` returns the reverse list.
+list **@insert** (ix:%integer, item)
+      Insert the item into the list at the position i.
+      This means that ``a@insert(0, x)`` inserts x at the front of the list, and ``a@insert(a@length(), x)`` is equivalent to ``a@append(x)``.
 
-* Function ``reverse``, reverses the elements of the list in place.
-* Function ``copy``, makes a shallow copy of the list.
-* Function ``shuffle``, returns a random permutation of a given list - in place!
-* Function ``map``, given ``(f:%function)``, applies ``f`` to each element of the list in place. The modified list is returned.
-* Function ``reduce`` reduces the value of elements in a list. This
-  function can be called with several different inputs:
+list **@join** join_str:%string
+      Turns the list into a string using join_str between the elements.  The string is returned
+      as the return value from this function.
 
-  1. Input ``(f:%function)`` returns ``value``, such that ``value = f(value,this@i)``.
-  2. Input ``(f:%function,init)`` returns the same format but uses ``init`` as an initial value.
+list **@length** ()
+      Returns the number of elements within the list.
 
-  The first argument to ``f`` is the accumulator.
+list **@map** f:%function
+      Applies the function f to each element of the list in place. The modified list is returned.
 
-* Function ``filter``, given ``(f:%function)``, constructs an output list from those elements of the list for which ``f`` returns true. If ``f`` is none, the identity function is assumed, that is, all elements of the input list that are false are removed.
-* Function ``member``, given ``(item)``, returns true only if ``item`` exists on the list.
-* Function ``join``, given ``(join:%string)``, turns the list into a string using ``join`` between the elements.  The string is returned
-  as the return value from this function.
+list **@member** item
+      Returns true only if item exists on the list.
 
+list **@pop** () | ix:%integer
+      Removes the item at the given position in the list and returns it. If no index is specified
+      removes and returns the last item in the list.
 
-See the `Prologue module <https://github.com/asteroid-lang/asteroid/blob/master/asteroid/modules/prologue.ast>`_ for more on all the functions above.
+list **@reduce** f:%function | (f:%function, init)
+      Reduce the list to a value by applying the function f to all the members of the list. The function f has to be
+      a function with two arguments where the first argument is the accumulator.  If no initial
+      value is given then the first element of the list is assumed to be the first accumulator value.
+      In order to illustrate, we have::
+
+            let value = [1,2] @reduce (lambda with (x,y) do x+y, 0).
+            assert(value == 3).
+
+      is equivalent to ::
+
+            let l = [1,2].
+            let value = 0.
+            for i in range(l@length()) do
+                  let value = (lambda with (x,y) do x+y) (value,l@i).
+            end
+            assert(value == 3).
+
+list **@remove** item
+      Removes the first element from the list whose value is equal to item.
+      It throws an exception if there is no such item.
+
+list **@reverse** ()
+      Reverses the elements of the list in place and returns the reversed list.
+
+list **@shuffle** ()
+      Creates a random permutation of the list in place and returns the randomized list.
+
+list **@sort** () | reverse:%boolean
+      Sorts the items of the list in place and returns the sorted list.
+      If the boolean reverse is set to true then the sorted list is reversed.
 
 
 Strings
 ^^^^^^^
 
-A string is a sequence of characters that can be used as a variable or a literal constant.
+A string is a sequence of characters surrounded by double quotes.
+In Asteroid, single characters are represented as single character strings.
 Similar to lists the member functions of strings can be called directly on the
 data structure itself, e.g.::
 
-   "Hello there" @length()
+   "Hello there" @length ()
+
+Member Functions
+%%%%%%%%%%%%%%%%
 
-* Function ``length`` returns the number of characters within that string.
-* Function ``explode``, turns a string into a list of characters.
-* Function ``trim``, given the input ``(what:%string)``, returns a copy of the string with the leading and trailing characters removed. The ``what`` argument is a string specifying the set of characters to be removed. If omitted or none, the ``what`` argument defaults to removing whitespace. The ``what`` argument is not a prefix or suffix; rather, all combinations of its values are stripped.
-* Function ``replace`` will return a copy of the string with all occurrences of regular expression pattern ``old`` replaced by the string ``new``. If the optional argument count is given, only the first count occurrences are replaced. It can be called with several different inputs:
+string **@explode** ()
+      Returns the string as a list of characters.
 
-  * ``(old:%string,new:%string,count:%integer)``
-  * ``(old:%string,new:%string)``
+string **@flip** ()
+      Returns a copy of the string with its characters in the reverse order.
 
-* Function ``split`` will return a list of the words in a given string, using ``sep`` as the delimiter string. If ``maxsplit`` is given: at most maxsplit splits are done (thus, the list will have at most maxsplit+1 elements). If maxsplit is not specified or -1, then there is no limit on the number of splits (all possible splits are made).
-  If ``sep`` is given, consecutive delimiters are not grouped together and are deemed to delimit empty strings (for example, ``"1,,2"@split(",")`` returns ``["1", "", "2"]``). The ``sep`` argument may consist of multiple characters (for example, ``"1<>2<>3"@split("<>")`` returns ``["1", "2", "3"]``). Splitting an empty string with a specified separator returns ``[""]``.
-  If ``sep`` is not specified or is None, a different splitting algorithm is applied: runs of consecutive whitespace are regarded as a single separator, and the result will contain no empty strings at the start or end if the string has leading or trailing whitespace. Consequently, splitting an empty string or a string consisting of just whitespace with a None separator returns ``[]``.
-  Function ``split`` can be called with several different inputs:
+string **@index** item:%string | (item:%string, loc(startix:%integer)) | (item:%string, loc(startix:%integer, endix:%integer))
+      Returns an integer index of the item in the string or none if item was not found.
+      The  argument loc allows you to specify startix and endix and are used to limit the search
+      to a particular substring of the string. The returned index is computed relative to the beginning
+      of the full string rather than the startix.
 
-  1. Input ``(sep:%string,count:%integer)``
-  2. Input ``(sep:%string)``
-  3. Input ``(none)``
+string **@length** ()
+      Returns the number of characters within the string.
 
-* Function ``toupper``, converts all the lowercase letters in a string to uppercase.
-* Function ``tolower``, converts all the uppercase letters in a string to lowercase.
-* Function ``index`` allows the user to search for a given ``item`` in a list. It returns an integer index into the string or ``none`` if ``item`` was not found.  The optional argument ``loc`` allows you to specify ``(startix)`` and ``(endix)`` and are used to limit the search to a particular substring of the string. The returned index is computed relative to the beginning of the full string rather than the ``(startix)`` argument.The function can be called with several different inputs:
+string **@replace** (old:%string, new:%string) | (old:%string, new:%string, count:%integer)
+      Return a copy of the string with all occurrences of regular expression old replaced by the
+      string new. If the argument count is given, only the first count occurrences are replaced.
 
-  1. Input ``(item:%string,loc(startix:%integer,endix:%integer))``
-  2. Input ``(item:%string,loc(startix:%integer))``
-  3. Input ``(item:%string)``
+string **@split** () | sep:%string | (sep:%string, count:%integer)
+      Return a list of the words in the string, using sep as the delimiter. If count is given then
+      at most count splits are done (thus, the list will have at most count+1 elements). If count is
+      not specified or -1, then there is no limit on the number of splits (all possible splits are made).
+      Consecutive delimiters are not grouped together and are deemed to delimit empty strings.
+      For example,::
 
-* Function ``flip`` reverses a string.
+            let s = "1,,2" @split ",".
+            assert (s == ["1", "", "2"]).
+
+      The sep argument may consist of multiple characters.
+      For example,::
+
+            let s = "1<>2<>3" @split "<>".
+            assert (s == ["1", "2", "3"]).
+
+      Splitting an empty string with a specified separator returns ``[""]``.
+      If sep is not specified or is None, a different splitting algorithm is applied:
+      consecutive whitespace is regarded as a single separator, and the result will contain no empty strings at
+      the start or end if the string has leading or trailing whitespace. Consequently, splitting an empty string
+      or a string consisting of just whitespace with a none separator returns ``[]``.
+
+string **@tolower** ()
+      Returns a copy of the string in all lower case letters.
+
+string **@toupper** ()
+      Returns a copy of the string in all upper case letters.
+
+string **@trim** () | what:%string
+      Returns a copy of the string with the leading and trailing characters removed.
+      The what argument specifies the set of characters to be removed.
+      If omitted trim defaults to removing whitespace.
+      The what argument is not a prefix or suffix; rather, all combinations of its characters are stripped.
 
-See the `Prologue module <https://github.com/asteroid-lang/asteroid/blob/master/asteroid/modules/prologue.ast>`_  for more on all the functions above.
 
 
 Asteroid Modules
@@ -937,99 +1016,115 @@ we have ``println`` as one of the member functions.  To call that function::
    load system io.
    io @println "Hello there!".  -- println is a member function of the io module
 
-Bitwise
+bitwise
 ^^^^^^^
 
-The `bitwise <https://github.com/asteroid-lang/asteroid/blob/master/asteroid/modules/bitwise.ast>`_ module defines Bitwise operations. It supports the following functions,
-
-* Function ``band`` can be called with the input ``(x:%integer, y:%integer)``, and performs the Bitwise AND operation.
-* Function ``bor`` can be called with the input ``(x:%integer, y:%integer)``, and performs the Bitwise OR operation.
-* Function ``bnot`` can be called with the input ``(x:%integer)``, and performs the Bitwise NOT operation.
-* Function ``bxor`` can be called with the input ``(x:%integer, y:%integer)``, and performs the Bitwise XOR operation.
-* Function ``blshift`` can be called with the input ``(x:%integer, y:%integer)``, and performs the Bitwise left shift operation.
-* Function ``brshift`` can be called with the input ``(x:%integer, y:%integer)``, and performs the Bitwise right shift operation.
-* Function ``blrotate`` can be called with the input ``(x:%integer, i:%integer)``, and performs the Bitwise left rotate operation.
-* Function ``brrotate`` can be called with the input ``(x:%integer, i:%integer)``, and performs the Bitwise right rotate operation.
-* Function ``bsetbit`` can be called with the input ``(x:%integer, i:%integer)``, and sets the ith bit.
-* Function ``bclearbit`` can be called with the input ``(x:%integer, i:%integer)``, and clears the ith bit.
-* Function ``bsize``can be called with the input ``(x:%integer)``, and returns the bit size.
-
-Hash
+This module defines bitwise operations on integers. It supports the following functions,
+
+bitwise **@band** (x:%integer, y:%integer)
+      Performs the bitwise AND operation and returns the result as an integer.
+
+bitwise **@bclearbit** (x:%integer, i:%integer)
+      Clear the ith bit in x and returns the result as an integer.
+
+bitwise **@blrotate** (x:%integer, i:%integer)
+      Performs the bitwise left rotate operation by i bits and returns the result as an integer.
+
+bitwise **@blshift** (x:%integer, y:%integer)
+      Performs the bitwise left shift operation where x is shifted by y bits and returns the result as an integer.
+
+bitwise **@bnot** x:%integer
+      Performs the bitwise NOT operation and returns the result as an integer.
+
+bitwise **@bor** (x:%integer, y:%integer)
+      Performs the bitwise OR operation and returns the result as an integer.
+
+bitwise **@brrotate** (x:%integer, i:%integer)
+      Performs the bitwise right rotate operation by i bits and returns the result as an integer.
+
+bitwise **@brshift** (x:%integer, y:%integer)
+      Performs the bitwise right shift operation where x is shifted by y bits and returns the result as an integer.
+
+bitwise **@bsetbit** (x:%integer, i:%integer)
+      Sets the ith bit in x and returns the result as an integer.
+
+bitwise **@bsize** x:%integer
+      Returns the bit size of x.
+
+bitwise **@bxor** (x:%integer, y:%integer)
+      Performs the bitwise XOR operation and returns the result as an integer.
+
+
+hash
 ^^^^
 
-The `hash <https://github.com/asteroid-lang/asteroid/blob/master/asteroid/modules/hash.ast>`_ module implements a hash for name-values pairs. It supports the following functions,
+This module implements a hash for key-value pairs. It supports the following functions,
+
+hash **@hash** ()
+      Returns a new hash object of type __HASH__.
+
+__HASH__ **@aslist** ()
+      Returns the hash as a list of key-value pairs.
+
+__HASH__ **@get** key
+      Return the value associated with the given key as long as it can be found otherwise an exception will be thrown.
+
+__HASH__ **@insert** (key, value) | pairs:%list
+      Given a pair of the format (key, value) insert it into the table.  Given a list
+      of the format,::
+
+            [(key1, val1), (key2, val2), ...]
 
-* Function ``insert``, given the input ``(name,value)``, will insert a given name-value pair into the table.
-* Function ``get``, given ``name``, will return the ``value`` associated with the given ``name`` as long as it can be found otherwise an exception will be thrown.
-* Function ``aslist`` returns the hash as a list of name-value pairs.
+      insert all the key-value pairs on the list into the hash.
 
-IO
+io
 ^^
 
-The `io <https://github.com/asteroid-lang/asteroid/blob/master/asteroid/modules/io.ast>`_ module implements Asteroid's I/O system. The module defines three default streams,
+This module implements Asteroid's I/O system. The module defines three I/O streams,
 
-1. ``__STDIN__`` - the standard input stream.
-2. ``__STDOUT__`` - the standard output stream.
-3. ``__STDERR__`` - the standard error stream.
+1. __STDIN__ - the standard input stream.
+2. __STDOUT__ - the standard output stream.
+3. __STDERR__ - the standard error stream.
 
 Furthermore, the module supports the following functions,
 
-* Function ``println`` can be called with ``item``, and prints a given argument to the terminal (``__STDOUT__``) with an implicit newline character.
-* Function ``print`` can be called with ``item``, and prints a given argument. No implicit newline is appended to the output.
-* Function ``input`` can be called with a string ``prompt``.  If ``prompt`` is given it is printed and then input is read from the terminal (``__STDIN__``) and returned as a string.
-* Function ``open`` opens a file. Given ``(name:%string, mode:%string)``, it returns a file descriptor of type ``FILE``. The ``mode`` string can be ``"r"`` when the file will only be read, ``"w"`` for only writing (an existing file with the same name will be erased), and ``"a"`` opens the file for appending; any data written to the file is automatically added to the end. The ``"r+"`` opens the file for both reading and writing.
-* Function ``close``, given ``file:%FILE``, closes that file.
-* Function ``read``, given ``file:%FILE``, reads a file. If no file is given the ``__STDIN__`` stream is read.
-* Function ``readln``, given ``file:%FILE``, reads a given line of input from the file. If no file is given the ``__STDIN__`` stream is read.
-* Function ``write``, given ``(file:%FILE, what:%string)``, will write ``what`` to the given ``file``.  If ``file`` is not given then it writes to the ``__STDOUT__`` stream.
-* Function ``writeln``, works the same way as ``write`` except that it appends a newline character to the output.
-
-Math
-^^^^
-
-The `math <https://github.com/asteroid-lang/asteroid/blob/master/asteroid/modules/math.ast>`_ module implements mathematical constants and functions. It supports the following functions,
+io **@close** file:%\_\_FILE\_\_
+      Closes the file where file is a file descriptor of type \_\_FILE\_\_.
 
-*Power and logarithmic functions*
+io **@input** () | prompt:%string
+      Ask the user for input from __STDIN__.  The input is returned as a string. If prompt is given it is printed and then input is read from terminal.
 
-* Function ``exp``, given ``x:%integer``, returns e raised to the power ``x``, where e = 2.718281… is the base of natural logarithms.
-* Function ``log`` can be called with two different argument setups,
+io **@open** (name:%string, mode:%string)
+      Returns a file descriptor of type \_\_FILE\_\_.
+      The mode string can be "r" when the file will only be read,
+      "w" for only writing (an existing file with the same name will be erased),
+      and "a" opens the file for appending; any data written to the file is
+      automatically added to the end.
+      Finally,  "r+" opens the file for both reading and writing.
 
-  1. If only one argument, ``(x)``, is input, this returns the natural logarithm of x (to base e).
-  2. If two arguments, ``(x,base)``, are input, this returns the logarithm of x to the given base, calculated as log(x)/log(base).
+io **@print** item
+      Prints item to the terminal (__STDOUT__). No implicit newline is appended to the output.
 
-* Function ``pow``, given ``(b,p:%integer)``, returns "b <sup>p</sup>" as long as b is either ``real`` or ``integer``.
-* Function ``sqrt``, given ``a``, returns its square root as long as ``a`` is either ``real`` or ``integer``.
+io **@println** item
+      Prints item to the terminal (__STDOUT__) with an implicit newline character.
 
-*Number-theoretic and representation functions*
+io **@read** () | file:%\_\_FILE\_\_
+      Read a file and return the contents as a string. If no file is given the __STDIN__ stream is read.
 
-* Function ``abs``, given ``x``, returns its absolute value.
-* Function ``ceil``, given ``x:%real``, returns the ceiling of x: the smallest integer greater than or equal to x.
-* Function ``floor``, given ``x:%real``, returns the floor of x: the largest integer less than or equal to x.
-* Function ``gcd``, given ``(a:%integer,b:%integer)``, returns the greatest common denominator that both integers share.
-* Function ``isclose`` can be called with two different argument setups,
+io **@readln** () | file:%\_\_FILE\_\_
+      Reads a line of input from a file and returns it as a string. If no file is given the __STDIN__ stream is read.
 
-  1. With input values ``(a,b)``, it returns returns ``true`` if the two values are close to each other and ``False`` otherwise. Default tolerance 1e-09.
-  2. With input values ``(a,b,t)``, it compares ``a`` and ``b`` with tolerance ``t``.
+io **@write** what:%string | (file:%\_\_FILE\_\_, what:%string)
+      Write what to a file.  If file is not given then it writes to the __STDOUT__ stream.
 
-* Function ``mod``, given ``(v,d)``, will return the remainder of the operation ``v/d``, as long as ``v`` and ``d`` are either ``real`` or ``integer`` values.
+io **@writeln** what:%string | (file:%\_\_FILE\_\_, what:%string)
+      Write what to a file and append a newline charater.  If file is not given then it writes to  __STDOUT__.
 
-*Trigonometric functions*
 
-* Function ``acos``, given ``x``, returns the arc cosine of x in radians. The result is between 0 and pi.
-* Function ``asin``, given ``x``, returns the arc sine of x in radians. The result is between -pi/2 and pi/2.
-* Function ``atan``, ,given ``x``, returns the arc tangent of x in radians. The result is between -pi/2 and pi/2.
-* Function ``cos``, given ``x``, returns the cosine of x radians.
-* Function ``sin``, given ``x``, returns the sine of x radians.
-* Function ``tan``, given ``x``, returns the tangent of x radians.
-* Function ``acosh``, given ``x``, returns the inverse hyperbolic cosine of x.
-* Function ``asinh``, given ``x``, returns the inverse hyperbolic sine of x.
-* Function ``atanh``, given ``x``, returns the inverse hyperbolic tangent of x.
-* Function ``cosh``, given ``x``, returns the hyperbolic cosine of x.
-* Function ``sinh``, given ``x``, returns the hyperbolic sine of x.
-* Function ``tanh``, given ``x``, returns the hyperbolic tangent of x.
-* Function ``degrees``, given ``x``, converts angle ``x`` from radians to degrees.
-* Function ``radians``,  given ``x``, converts angle ``x`` from degrees to radians.
+math
+^^^^
 
+The math module implements mathematical constants and functions.
 An example,
 ::
     load system io.
@@ -1037,117 +1132,413 @@ An example,
 
     let x = math @sin( math @pi / 2 ).
     io @println("The sine of pi / 2 is " + x + ".").
-Pick
+
+Constants
+%%%%%%%%%
+
+math **@pi**
+      The mathematical constant π = 3.141592…, to available precision.
+
+math **@e**
+      The mathematical constant e = 2.718281…, to available precision.
+
+
+Power and logarithmic functions
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+math **@exp** x:%integer
+      Returns e raised to the power x, where e = 2.718281… is the base of the natural logarithm.
+
+math **@log** x | (x, base:%integer)
+      If only argument x is the input, return the natural logarithm of x (to base e).
+      If two arguments, (x, base:%integer), are given as input, return the logarithm
+      of x to the given base, calculated as log(x)/log(base).
+
+math **@pow** (b, p:%integer)
+      Return b raised to the power p.  The return type depends on the type
+      of the base.
+
+math **@sqrt** x
+      Return the square root of x as a real.
+
+
+Number-theoretic and representation functions
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+math **@abs** x
+      Return that absolute value of x.  The return type depends on the type of x.
+
+math **@ceil** x:%real
+      Returns the ceiling of x: the smallest integer greater than or equal to x.
+
+math **@floor** x:%real
+      Returns the floor of x: the largest integer less than or equal to x.
+
+math **@gcd** (a:%integer, b:%integer)
+      Returns the greatest common denominator that both integers share.
+
+math **@isclose** (a:%real, b:%real) | (a:%real, b:%real, t:%real)
+      Return true if the values a and b are close to each other and false otherwise.
+      Default tolerance is 1e-09.  An alternative tolerance can be specified with
+      the t argument.
+
+math **@mod** (v,d)
+      Implements the modulus operation. Returns the remainder of the quotient v/d.
+
+
+Trigonometric functions
+%%%%%%%%%%%%%%%%%%%%%%%
+
+math **@acos** x
+      Returns the arc cosine of x in radians. The result is between 0 and pi.
+
+math **@asin** x
+      Returns the arc sine of x in radians. The result is between -pi/2 and pi/2.
+
+math **@atan** x
+      Returns the arc tangent of x in radians. The result is between -pi/2 and pi/2.
+
+math **@cos** x
+      Returns the cosine of x radians.
+
+math **@sin** x
+      Returns the sine of x radians.
+
+math **@tan** x
+      Returns the tangent of x radians.
+
+Hyperbolic functions
+%%%%%%%%%%%%%%%%%%%%
+
+math **@acosh** x
+      Returns the inverse hyperbolic cosine of x.
+
+math **@asinh** x
+      Returns the inverse hyperbolic sine of x.
+
+math **@atanh** x
+      Returns the inverse hyperbolic tangent of x.
+
+math **@cosh** x
+      Returns the hyperbolic cosine of x.
+
+math **@sinh** x
+      Returns the hyperbolic sine of x.
+
+math **@tanh** x
+      Returns the hyperbolic tangent of x.
+
+Angular conversion
+%%%%%%%%%%%%%%%%%%
+
+math **@degrees** x
+      Converts angle x from radians to degrees.
+
+math **@radians** x
+      Converts angle x from degrees to radians.
+
+
+os
+^^
+
+This module provides a portable way of using operating system dependent functionality.
+
+Process Parameters
+%%%%%%%%%%%%%%%%%%
+
+os **@argv**
+      The list of command line arguments passed to an Asteroid script.
+      argv[0] is the name of the Asteroid script (it is operating
+      system dependent whether this is a full pathname or not).
+      In interactive mode argv[0] will be the empty string.
+
+os **@env**
+      A hash table where keys and values are strings that represent
+      the process environment. For example,
+            os @env @get "HOME"
+      is the pathname of your home directory (on some platforms),
+      and is equivalent to getenv("HOME") in C.
+
+os **@platform**
+      This string contains a platform identifier.
+
+
+Functions
+%%%%%%%%%
+
+os **@basename** path:%string
+      Return the base name of pathname path. This is the second element of the pair
+      returned by passing path to the function split. Note that the result of this
+      function is different from the Unix basename program; where basename for '/foo/bar/'
+      returns 'bar', the basename function returns an empty string ("").
+
+os **@chdir** path:%string
+      Change the current working directory to path.
+
+os **@dirname** path:%string
+      Return the directory name of pathname path. This is the first element of the
+      pair returned by passing path to the function split.
+
+os **@exists** path:%string
+      Return true if path refers to an existing path or an open file descriptor.
+      Returns false for broken symbolic links. On some platforms, this function
+      may return False if permission is not granted to execute stat on
+      the requested file, even if the path physically exists.
+
+os **@exit** () | v:%integer | msg:%string
+      Signaling an intention to exit the interpreter.
+      When an argument value other than none is provided
+      it is considered a status value. If it is
+      an integer, zero is considered “successful termination” and any
+      nonzero value is considered “abnormal termination” by shells and
+      the like. Most systems require it to be in the range 0–127, and
+      produce undefined results otherwise. Some systems have a
+      convention for assigning specific meanings to specific exit codes,
+      but these are generally underdeveloped; Unix programs generally
+      use 2 for command line syntax errors and 1 for all other kind
+      of errors. If none is given as an argument value then is it
+      is considered to be a successful exit equivalent to passing a zero.
+      If a string is passed then it is printed printed to
+      __STDERR__ and results in an exit code of 1. In particular,
+      sys.exit("some error message") is a quick way to exit a program
+      when an error occurs.
+
+os **@getdir** ()
+      Return a string representing the current working directory.
+
+os **@getpathtime** path:%string | (path:%string,flag:%boolean)
+      Returns a triple with (creation, access, modification) times.
+      By default the return value is a triple of real numbers
+      giving the number of seconds since 1/1/1970.  If the flag is set
+      to true then a triple of strings is returned where each string
+      represents the respective local time. Throws an exception if the file
+      does not exist or is inaccessible.
+
+os **@getsize** path:%string
+      Return the size, in bytes, of path. Throws exception if the file
+      does not exist or is inaccessible.
+
+os **@isfile** path:%string
+      Return true if path is an existing regular file. This follows
+      symbolic links.
+
+os **@isdir** path:%string
+      Return true if path is an existing directory. This follows
+      symbolic links.
+
+os **@join** (path1:%string,path2:%string)
+      Join path1 and path2 components intelligently. The return value
+      is the concatenation of path and any members of *paths with
+      exactly one directory separator following each non-empty part
+      except the last, meaning that the result will only end in a
+      separator if the last part is empty. If the second component is an
+      absolute path, the first component is thrown away.
+
+      On Windows, the drive letter is not reset when an absolute
+      path component (e.g., r'\foo') is encountered. If a component
+      contains a drive letter, all previous components are thrown away
+      and the drive letter is reset. Note that since there is a current
+      directory for each drive, os.path.join("c:", "foo") represents a
+      path relative to the current directory on drive C: (c:foo), not c:\foo.
+
+os **@split** path:%string
+      Split the pathname path into a pair, (head, tail) where tail is
+      the last pathname component and head is everything leading up to
+      that. The tail part will never contain a slash; if path ends in
+      a slash, tail will be empty. If there is no slash in path, head
+      will be empty. If path is empty, both head and tail are empty.
+      Trailing slashes are stripped from head unless it is the root
+      (one or more slashes only). Also see the functions dirname and
+      basename.
+
+os **@splitdrive** path:%string
+      Split the pathname path into a pair (drive, tail) where drive is
+      either a mount point or the empty string. On systems which do not
+      use drive specifications, drive will always be the empty string.
+      In all cases, drive + tail will be the same as path.
+
+      On Windows, splits a pathname into drive/UNC sharepoint and
+      relative path.
+
+      If the path contains a drive letter, drive will contain everything
+      up to and including the colon.
+
+os **@splitext** path:%string
+      Split the pathname path into a pair (root, ext) such that
+      root + ext == path, and the extension, ext, is empty or begins
+      with a period and contains at most one period. If the path contains
+      no extension, ext will be the empty string.
+
+os **@syscmd** cmd:%string
+      Execute a command in a subshell. This is implemented
+      by calling the Standard C function system, and has the same
+      limitations. If command generates any output, it will be
+      sent to the interpreter standard output stream.
+      The C standard does not specify the meaning of the return value of
+      the C function, so the return value of this function is
+      system-dependent.
+
+
+
+
+pick
 ^^^^
 
-The `pick <https://github.com/asteroid-lang/asteroid/blob/master/asteroid/modules/pick.ast>`_ module implements
-pick objects that allow a user to randomly pick items from a list using the ``pick`` function.
-The ``pick`` function can be called with ``n:%integer`` and returns a list of ``n`` randomly picked objects from the object list.
-Here is a simple use case
-::
+The pick module implements
+pick objects that allow a user to randomly pick items from a list of items using the pickitems function.
+
+pick **@pick** l:%list
+      Construct a pick object of type __PICK__.
+
+__PICK__ **@pickitems** () | n:%integer
+      Return items randomly picked from the list l.  If no input is provided
+      then pickitems will return a single, randomly picked item from the list.
+      If an integer value n is given then a list of n randomly picked items from
+      the list l is returned.  The picked item list is constructed by sampling the
+      list l with replacement.
+
+An example::
    load system io.
    load system pick.
 
    let po = pick @pick([1 to 10]).
-   let objects = po @pick(3).
+   let objects = po @pickitems 3.
    io @println objects.
-Random
+random
 ^^^^^^
 
-The `random <https://github.com/lutzhamel/asteroid/blob/master/asteroid/modules/random.ast>`_ module implements the ``random`` numbers. Using the functions included in this module will return a random value within a given range or interval. It supports the following functions,
+The random module implements random number generation.
 
-* Function ``random``, given the input ``none``, returns a random floating point number in the range ``[0.0, 1.0)``.
-* Function ``randint`` returns a random value N in the interval lo <= N <= hi. The exact random value output depends on the types of the values specifying the interval. It can be called with two different number interval inputs:
+random **@randint** (lo:%integer,hi:%integer) | (lo:%real,hi:%real)
+      Return a random value N in the interval lo <= N <= hi.
+      The type of the random value depends on the types of the
+      values specifying the interval.  If the interval is specified
+      with integers then a random integer value is returned.
+      If the interval is specified with real numbers then a real value is
+      is returned, and for everything else an exception is thrown.
 
-  1. ``(lo:%integer,hi:%integer)``
-  2. ``(lo:%real,hi:%real)``
-  3. Note: any other interval specification will instead output an error message for "unsupported interval specification in randint."
+random **@random** ()
+      Return a random real number in the range [0.0, 1.0).
 
-* Function ``seed``, given ``(sd:%integer)``, provides a seed value for the random number generator.
+random **@seed** x:%integer
+      Provide the seed value x for the random number generator.
 
-Set
+set
 ^^^
 
-The `set <https://github.com/asteroid-lang/asteroid/blob/master/asteroid/modules/set.ast>`_ module implements Asteroid sets as lists. Unlike lists, sets do not have repeated members. It supports the following functions,
+The set module implements Asteroid sets as lists.
+Unlike lists, sets do not have repeated elements.
+Use the set member function toset to turn any list
+into a list that represents a set (remove repeated items).
+
+set **@diff** (a:%list,b:%list)
+      Return the difference set between sets a and b.
+
+set **@intersection** (a:%list,b:%list)
+      Return the intersection of sets a and b.
+
+set **@toset** l:%list
+      Return list l as a set by removing repeated elements.
 
-* Function ``toset``, given ``(lst:%list)``, converts the input list into a set.
-* Function ``diff``, given ``(a:%list,b:%list)``, computes the difference set between the two set ``a`` and ``b``.
-* Function ``intersection``, given ``(a:%list,b:%list)``, finds the intersection between  sets ``a`` and ``b``.
-* Function ``union``, given ``(a:%list,b:%list)``, computes the union of sets ``a`` and ``b``.
-* Function ``xunion``, given ``(a:%list,b:%list)``, returns all elements in ``a`` or ``b``, but not in both.
+set **@union** (a:%list,b:%list)
+      Return the union of sets a and b.
 
-Sort
+set **@xunion** (a:%list,b:%list)
+      Return the elements in a or b but not both.
+
+
+sort
 ^^^^
 
-The `sort <https://github.com/asteroid-lang/asteroid/blob/master/asteroid/modules/sort.ast>`_ module
-defines a parameterized ``sort`` function over a list.
-The ``sort`` function makes use of a user-defined order predicate on the list's elements to
-perform the sort. The ``Quicksort`` is the underlying sort algorithm.
+The sort  module
+defines a parameterized sort function over a list.
+The sort function makes use of a user-defined order predicate on the list's elements to
+perform the sort. The QuickSort is the underlying sort algorithm.
+
+sort **@sort** (p:%function,l:%list)
+      Returns the sorted list l using the predicate p.
+
 The following is a simple example,
 ::
    load system io.
    load system sort.
-   let sl = sort @sort((lambda with (x,y) do return true if x<y else false),
+   let sl = sort @sort((lambda with (x,y) do true if x<y else false),
                        [10,5,110,50]).
-    io @println sl.
+   io @println sl.
+
 prints the sorted list::
 
   [5,10,50,110]
 
-Stream
+stream
 ^^^^^^
 
-The `stream <https://github.com/asteroid-lang/asteroid/blob/master/asteroid/modules/stream.ast>`_ module implements streams that allow
-the developer to turn any list into a stream supporting interface functions like ``peeking`` ahead or ``rewinding`` the stream.
-The following stream interface functions are available,
+The stream module implements streams that allow
+the developer to turn any list into a stream supporting interface functions like peeking ahead or rewinding
+the stream.
 
-* Function ``eof`` returns ``true`` if the stream does not contain any further elements for processing. Otherwise it returns ``false``.
-* Function ``peek`` returns the current element available on the stream otherwise it returns ``none``.
-* Function ``get`` returns the current element and moves the stream pointer one ahead.
-* Function ``rewind`` resets the stream pointer to the first element of the stream.
-* Function ``map`` applies a given function to each element in the stream.
-* Function ``append``, given ``item``, adds item to the end of the stream.
-* Function ``__string__`` maps a the stream to a string representation.
+stream **@stream** l:%list
+      Returns a stream object of type __STREAM__.
 
-A simple use case.
-::
+__STREAM__ **@append** x
+      Adds x to the end of the stream.
+
+__STREAM__ **@eof** ()
+      Returns true if the stream does not contain any further elements for processing.
+      Otherwise it returns false.
+
+__STREAM__ **@get** ()
+      Returns the current element and moves
+      the stream pointer one ahead.  Returns none if no elements left in stream.
+
+__STREAM__ **@map** f:%function
+      Applies function f to each element in the stream.
+
+__STREAM__ **@peek** ()
+      Returns the current element available on the stream otherwise it returns none.
+
+__STREAM__ **@rewind** ()
+      Resets the stream pointer to the first element of the stream.
+
+A simple use case::
    load system io.
    load system stream.
 
-   let s = stream @stream([1 to 10]).
-   while not s @ eof() do
-      io @ print (s @get()+" ").
+   let s = stream @stream [1 to 10].
+   while not s @eof() do
+      io @print (s @get() + " ").
    end
-   io @println ("").
+   io @println "".
+
 which outputs::
 
    1 2 3 4 5 6 7 8 9 10
 
 
-Type
+type
 ^^^^
 
-The `type <https://github.com/asteroid-lang/asteroid/blob/master/asteroid/modules/type.ast>`_ module defines type related functions and structures.
-
-*Type Conversion*
+The type module defines type related functions and structures.
 
-* Function ``tointeger`` converts a given input to an integer. It can be called with two different arguments,
+Type Conversion
+%%%%%%%%%%%%%%%
 
-  1. ``(item:%string,base:%integer)`` where ``base`` is a valid base for integer conversion
-  2. ``item`` where ``item`` is converted to a base 10 integer.
+type **@tobase** (x:%integer,base:%integer)
+      Represents the given integer x as a numeral string in different bases.
 
+type **@toboolean** x
+      Interpret x as a Boolean value.
 
-* Function ``toreal``, given ``item``, returns the input as a real number data type.
-* Function ``toboolean``, given ``item``, returns the input as a Boolean value of either true or false.
-* Function ``tostring`` converts an Asteroid object to a string. If format values are given, it applies the formatting to the object. It can be called with several different inputs where ``*TP`` indicates a``boolean``, ``integer``, or ``string`` type and ``w`` is the width specification, ``p`` is the precision specification and ``s`` is the scientific notation flag.  When no formatting information is provided a default string conversion occurs,
+type **@tointeger** (x:%string,base:%integer) | x
+      Converts a given input to an integer. If a base value is specified then
+      the resulting integer is in the corresponding base.
 
-  1. ``(v:*TP,type @stringformat(w:%integer))``
-  2. ``(v:%real,type @stringformat(w:%integer))``
-  3. ``(v:%real,type @stringformat(w:%integer,p:%integer))``
-  4. ``(v:%real,type @stringformat(w:%integer,p:%integer,s:%boolean))``
-  5. ``item`` - default conversion
+type **@toreal** x
+      Returns the input as a real number.
 
-* Function ``tobase`` represents the given integer ``x`` (*specifically* within the given input ``(x:%integer,base:%integer)``) as a string in the given base.
+type  **@tostring** x | (x,type @stringformat(width:%integer,precision:%integer,scientific:%boolean))
+      Converts an Asteroid object to a string. If format values are given,
+      it applies the formatting to the string object.
 
 Here is a program that exercises some of the string formatting options,
 ::
@@ -1182,12 +1573,20 @@ The output of the program is,
 Notice the right justification of the various values within the given string length.
 
 
-*Type Query Functions*
+Type Query Functions
+%%%%%%%%%%%%%%%%%%%%
+
+type **@islist** x
+      Returns true if x is a list otherwise it will return false.
+
+type **@isnone** x
+      Returns true if x is equal to the value none.
+
+type **@isscalar** x
+      Returns true if x is either an integer or a real value.
 
-* Function ``islist`` returns ``true`` if given ``item`` is a list otherwise it will return ``false``.
-* Function ``isscalar`` returns ``true`` if given ``item`` is either an integer or a real value.
-* Function ``isnone`` returns ``true`` if given ``item`` is equal to the value ``none``.
-* Function ``gettype`` returns the type of a given ``item`` as an Asteroid string.
+type **@gettype** x
+      Returns the type of x as a string.
 
 A simple example program using the ``gettype`` function,
 ::
@@ -1195,38 +1594,64 @@ A simple example program using the ``gettype`` function,
 
    let i = 1.
    assert(type @gettype(i) == "integer").
-Util
+
+util
 ^^^^
 
-The `util <https://github.com/asteroid-lang/asteroid/blob/master/asteroid/modules/util.ast>`_ module defines utility functions and structures that don't really fit into any omodules. It supports the following functions,
+The util module defines utility functions and structures that don't really
+fit into any other modules.
+
+util **@achar** x
+      Given a decimal ASCII code x, return the corresponding character symbol.
 
-* Function ``exit`` exits the program. It can be called with two inputs,
+util **@ascii** x:%string
+      Given a character x, return the corresponding ASCII code of the first character of the input.
 
-  1. ``none``
-  2. ``msg:%string``
+util **@cls** ()
+      Clears the terminal screen.
 
-* Function ``copy``, given Asteroid object ``obj``, makes a deep copy of it.
-* Function ``cls`` clears the terminal screen.
-* Function ``sleep``,  programs sleep for ``secs`` seconds where the argument ``secs`` is either an integer or real value.
-* Function ``zip``, given ``(list1:%list,list2:%list)``, will return a list where element ``i`` of the list is the tuple ``(list1@i,list2@i)``.
-* Function ``unzip``, given a list of pairs will return a pair of lists where the first component of the pair is the list of all the first components of the pairs of the input list and the second component of the return list is a list of all the second components of the input list.
-* Function ``ascii``, given a character ``item:%string``, returns the corresponding ASCII code of the first character of the input string.
-* Function ``achar``, given a decimal ASCII code ``item:%integer``, returns the corresponding character symbol.
+util **@copy** x
+      Given the object x, make a deep copy of it.
 
-Vector
+util **@ctime** x:%real
+      Given a real value representing seconds since 1/1/1970 this function
+      converts it to a suitable string representation of the date.
+
+type **@sleep** x
+      Sleep for x seconds where the x is either an integer or real value.
+
+type **@time** ()
+      Returns the local time as a real value in secs since 1/1/1970.
+
+type **@unzip** x:%list
+      Given a list of pairs x this function will return a pair of lists
+      where the first component of the pair is the list of all the first
+      components of the pairs of the input list and the second component
+      of the return list is a list of all the second components of the input list.
+
+type **@zip** (list1:%list,list2:%list)
+      Returns a list where element i of the list is the tuple (list1@i,list2@i).
+
+vector
 ^^^^^^
 
-The `vector <https://github.com/asteroid-lang/asteroid/blob/master/asteroid/modules/vector.ast>`_ defines functions useful for vector arithmetic. It supports the following functions.  Here ``a`` and ``b`` are vectors implemented as lists,
+The vector defines functions useful for vector arithmetic. Vectors are implemented as lists.
+
+vector **@add** (a:%list,b:%list)
+      Returns a vector that contains the element by element sum of the input vectors a and b.
+
+vector **@dot** (a:%list,b:%list)
+      Computes the dot product of the two vectors a and b.
+
+vector **@mult** (a:%list,b:%list)
+      Returns the element by element vector multiplication of vectors a and b.
 
-* Function ``add``, given the input ``(a,b)``, returns a vector that contains the element by element sum of the input vectors.
-* Function ``sub``, given the input ``(a,b)``, returns the element by element difference vector.
-* Function ``mult``, given the input ``(a,b)``, returns the element by element vector multiplication.
-* Function ``dot``, given ``(a,b)``, computes the dot product of the two vectors.
-* Function ``op``  allows the developer to vectorize any function. It can be called with three different inputs:
+vector **@op** (f:%function,a:%list,b:%list) | (f:%function,a:%list,b if type @isscalar(b)) | (f:%function,a if type @isscalar(a),b:%list)
+      Allows the developer to vectorize any function f. Applying scalar values
+      to vectors is also supported by this function.
 
-  1. ``(f:%function,a:%list,b:%list)``
-  2. ``(f:%function,a:%list,b if type @isscalar(b))``
-  3. ``(f:%function,a if type @isscalar(a),b:%list)``
+vector **@sub** (a:%list,b:%list)
+      Returns the element by element difference vector.
 
 Here is a simple example program for the ``vector`` module,
 ::
diff --git a/docs/Reference Guide.txt b/docs/Reference Guide.txt
index b94fb3d6..5e1a6b96 100644
--- a/docs/Reference Guide.txt
+++ b/docs/Reference Guide.txt
@@ -1,13 +1,14 @@
-/******************************************************************
-  This is the source file from which the reference guide is
-  generated.  We use cpp to insert live code snippets into the
-  document. In order to generate the reference guide run the
-  following command on a Unix-like system in the directory of
-  this doc:
+..
+      /******************************************************************
+      This is the source file from which the reference guide is
+      generated.  We use cpp to insert live code snippets into the
+      document. In order to generate the reference guide run the
+      following command on a Unix-like system in the directory of
+      this doc:
 
-  bash generate_docs
+      bash generate_docs
 
- ******************************************************************/
+      ******************************************************************/
 #include "header.txt"
 
 .. highlight:: none
@@ -639,7 +640,7 @@ Here ``k`` only matches the value of ``val`` if that value is an even number.
 Pure Constraint Patterns
 %%%%%%%%%%%%%%%%%%%%%%%%
 
-Syntax: ``%[ pattern ]%``
+Syntax: ``%[ pattern ]% (BIND '[' ID (AS ID)? (',' ID (AS ID)?)*']')?``
 
 A pure constraint pattern is a pattern that does not create any bindings
 in the current scope.  Any pattern can be turned into a pure constraint pattern
@@ -675,30 +676,37 @@ are written in quotes.
 Builtin Functions
 -----------------
 
-* Function ``len``, when given an input value, returns the length of that input. The
-  function can only be applied to lists, strings, tuples, or structures.
+**getid** x
+      Returns a unique id of any Asteroid object as an integer.
 
-* Function ``hd``, when given a list as input returns the first element of that list.
-  It is an error to apply this function to an empty list.
+**hd** x:%list
+      Returns the first element of a list. It is an error to apply this 
+      function to an empty list.
 
-* Function ``tl``, when given a list as input returns the rest of the list without the first element.
-  It is an error to apply this function to an empty list.
+**isdefined** x:%string
+      Returns true if a variable or type name is defined in the
+      current environment otherwise it returns false. The variable or type name must be given as a string.
+**len** x
+      Returns the length of x. The
+      function can only be applied to lists, strings, tuples, or structures.
 
-* Function ``range`` will compute a list of values depending on the input values:
+**range**  stop:%integer | (start:%integer, stop:%integer) | (start:%integer, stop:%integer, inc:%integer)
+      Compute a list of values depending on the input values:
 
-  1. ``(start:%integer,stop:%integer)`` returns list ``[start to stop-1]``.
-  2. ``(start:%integer,stop:%integer,inc:%integer)`` returns list ``[start to stop-1 step inc]``.
-  3. ``(stop:%integer)`` returns list ``[0 to stop-1]``.
+      1. If only the stop value is given then the list [0 to stop-1] is returned.
+      2. If the start and stop values are given then the list [start to stop-1] is returned.
+      3. If in addition to the start and stop values the inc values is given then the list [start to stop-1 step inc] is returned.
+
+**tl** x:%list
+      Returns the rest of the list without the first element.  It is an 
+      error to apply this function to an empty list.
 
-* Function ``getid`` returns the id (physical memory address) of any Asteroid object as an Asteroid integer.
 
-* Function ``isdefined`` returns true if a variable or type name is defined in the
-  current environment otherwise it returns false. The variable or type name must be given as a string.
 
 List and String Objects
 -----------------------
 
-In Asteroid, both ``lists`` and ``strings,`` are treated like objects. Due to this, they have member functions that can manipulate the contents of those objects.
+In Asteroid, both ``lists`` and ``strings,`` are treated like objects in the OO sense. Due to this, they have member functions that can manipulate the contents of those objects.
 
 Lists
 ^^^^^
@@ -707,85 +715,155 @@ A **list** is a structured data type that consists of square brackets enclosing
 comma-separated values.
 Member functions on lists can be called on the data structure directly, e.g.::
 
-   [1,2,3] @length()
+   [1,2,3] @length ()
 
-* Function ``length`` returns the number of elements within that list.
-* Function ``append``, given ``(item)``, adds that item to the end of a list.
-* Function ``extend``, given ``(item)``, will extend the list by adding all the items from the item where ``item`` is either a list, a string or a tuple.
-* Function ``insert``, given ``(ix:%integer,item)``, will insert an item at a given position. The first argument is the index of the element before which to insert, so ``a@insert(0, x)`` inserts at the front of the list, and ``a@insert(a@length(), x)`` is equivalent to ``a@append(x)``.
-* Function ``remove``, given ``(item)``, removes the first element from the list whose value is equal to ``(item)``. It raises a ValueError if there is no such item.
-* Function ``pop``, given ``(ix:%integer)``, removes the item at the given position in the list and returns it. If no index is specified,``a@pop()`` removes and returns the last item in the list.
-* Function ``clear``, given ``(none)``, removes all items from the list.
-* Function ``index`` returns a zero-based index in the list of the first element whose value is equal to ``(item)``. It raises a ValueError exception if there is no such item. The optional argument ``loc`` allows you to specify ``(startix)`` and ``(endix)`` and are used to limit the search to a particular subsequence of the list. The returned index is computed relative to the beginning of the full sequence rather than the ``(startix)`` argument.   This function can be called with several input configurations:
+Member Functions
+%%%%%%%%%%%%%%%%
 
-  1. ``(item,loc(startix:%integer,endix:%integer))``
-  2. ``(item,loc(startix:%integer))``
-  3. ``item``
+list **@append** item
+      Adds the item to the end of the list.
 
-* Function ``count``, given ``(item)``, returns the number of times ``(item)`` appears in the list.
-* Function ``sort`` sorts the items of the list in place. It can be called with several different inputs:
+list **@clear** ()
+      Removes all items from the list.
 
-  1. ``(reverse:%boolean)`` if the boolean is set to true then the sorted list is reversed.
-  2. ``none`` returns the reverse list.
+list **@copy** ()
+      Returns a shallow copy of the list.
 
-* Function ``reverse``, reverses the elements of the list in place.
-* Function ``copy``, makes a shallow copy of the list.
-* Function ``shuffle``, returns a random permutation of a given list - in place!
-* Function ``map``, given ``(f:%function)``, applies ``f`` to each element of the list in place. The modified list is returned.
-* Function ``reduce`` reduces the value of elements in a list. This
-  function can be called with several different inputs:
+list **@count** item
+      Returns the number of times item appears in the list.
 
-  1. Input ``(f:%function)`` returns ``value``, such that ``value = f(value,this@i)``.
-  2. Input ``(f:%function,init)`` returns the same format but uses ``init`` as an initial value.
+list **@extend** item
+      Extend the list by adding all the elements from the item to the list where the item is either a list or a tuple.
 
-  The first argument to ``f`` is the accumulator.
+list **@filter** f:%function
+      Returns a list constructed from those elements for which function f returns true. 
 
-* Function ``filter``, given ``(f:%function)``, constructs an output list from those elements of the list for which ``f`` returns true. If ``f`` is none, the identity function is assumed, that is, all elements of the input list that are false are removed.
-* Function ``member``, given ``(item)``, returns true only if ``item`` exists on the list.
-* Function ``join``, given ``(join:%string)``, turns the list into a string using ``join`` between the elements.  The string is returned
-  as the return value from this function.
+list **@index** item | (item, loc(startix:%integer) | (item, loc(startix:%integer, endix:%integer))
+      Returns a zero-based index of the first element whose value is equal to item. 
+      It throws an exception if there is no such item. The argument loc allows you to specify 
+      startix and endix and are used to limit the search to a particular subsequence of the list. 
+      The returned index is computed relative to the beginning of the list rather than the startix argument.   
 
+list **@insert** (ix:%integer, item)
+      Insert the item into the list at the position i.
+      This means that ``a@insert(0, x)`` inserts x at the front of the list, and ``a@insert(a@length(), x)`` is equivalent to ``a@append(x)``.
 
-See the `Prologue module <https://github.com/asteroid-lang/asteroid/blob/master/asteroid/modules/prologue.ast>`_ for more on all the functions above.
+list **@join** join_str:%string
+      Turns the list into a string using join_str between the elements.  The string is returned
+      as the return value from this function.
 
+list **@length** ()
+      Returns the number of elements within the list.
 
-Strings
-^^^^^^^
+list **@map** f:%function
+      Applies the function f to each element of the list in place. The modified list is returned.
 
-A string is a sequence of characters that can be used as a variable or a literal constant.
-Similar to lists the member functions of strings can be called directly on the
-data structure itself, e.g.::
+list **@member** item
+      Returns true only if item exists on the list.
+
+list **@pop** () | ix:%integer
+      Removes the item at the given position in the list and returns it. If no index is specified
+      removes and returns the last item in the list.
 
-   "Hello there" @length()
+list **@reduce** f:%function | (f:%function, init)
+      Reduce the list to a value by applying the function f to all the members of the list. The function f has to be
+      a function with two arguments where the first argument is the accumulator.  If no initial
+      value is given then the first element of the list is assumed to be the first accumulator value.
+      In order to illustrate, we have::
 
-* Function ``length`` returns the number of characters within that string.
-* Function ``explode``, turns a string into a list of characters.
-* Function ``trim``, given the input ``(what:%string)``, returns a copy of the string with the leading and trailing characters removed. The ``what`` argument is a string specifying the set of characters to be removed. If omitted or none, the ``what`` argument defaults to removing whitespace. The ``what`` argument is not a prefix or suffix; rather, all combinations of its values are stripped.
-* Function ``replace`` will return a copy of the string with all occurrences of regular expression pattern ``old`` replaced by the string ``new``. If the optional argument count is given, only the first count occurrences are replaced. It can be called with several different inputs:
+            let value = [1,2] @reduce (lambda with (x,y) do x+y, 0).
+            assert(value == 3).
 
-  * ``(old:%string,new:%string,count:%integer)``
-  * ``(old:%string,new:%string)``
+      is equivalent to ::
 
-* Function ``split`` will return a list of the words in a given string, using ``sep`` as the delimiter string. If ``maxsplit`` is given: at most maxsplit splits are done (thus, the list will have at most maxsplit+1 elements). If maxsplit is not specified or -1, then there is no limit on the number of splits (all possible splits are made).
-  If ``sep`` is given, consecutive delimiters are not grouped together and are deemed to delimit empty strings (for example, ``"1,,2"@split(",")`` returns ``["1", "", "2"]``). The ``sep`` argument may consist of multiple characters (for example, ``"1<>2<>3"@split("<>")`` returns ``["1", "2", "3"]``). Splitting an empty string with a specified separator returns ``[""]``.
-  If ``sep`` is not specified or is None, a different splitting algorithm is applied: runs of consecutive whitespace are regarded as a single separator, and the result will contain no empty strings at the start or end if the string has leading or trailing whitespace. Consequently, splitting an empty string or a string consisting of just whitespace with a None separator returns ``[]``.
-  Function ``split`` can be called with several different inputs:
+            let l = [1,2].
+            let value = 0.
+            for i in range(l@length()) do
+                  let value = (lambda with (x,y) do x+y) (value,l@i).
+            end
+            assert(value == 3).
 
-  1. Input ``(sep:%string,count:%integer)``
-  2. Input ``(sep:%string)``
-  3. Input ``(none)``
+list **@remove** item
+      Removes the first element from the list whose value is equal to item. 
+      It throws an exception if there is no such item.
 
-* Function ``toupper``, converts all the lowercase letters in a string to uppercase.
-* Function ``tolower``, converts all the uppercase letters in a string to lowercase.
-* Function ``index`` allows the user to search for a given ``item`` in a list. It returns an integer index into the string or ``none`` if ``item`` was not found.  The optional argument ``loc`` allows you to specify ``(startix)`` and ``(endix)`` and are used to limit the search to a particular substring of the string. The returned index is computed relative to the beginning of the full string rather than the ``(startix)`` argument.The function can be called with several different inputs:
+list **@reverse** ()
+      Reverses the elements of the list in place and returns the reversed list.
 
-  1. Input ``(item:%string,loc(startix:%integer,endix:%integer))``
-  2. Input ``(item:%string,loc(startix:%integer))``
-  3. Input ``(item:%string)``
+list **@shuffle** ()
+      Creates a random permutation of the list in place and returns the randomized list.
 
-* Function ``flip`` reverses a string.
+list **@sort** () | reverse:%boolean
+      Sorts the items of the list in place and returns the sorted list. 
+      If the boolean reverse is set to true then the sorted list is reversed.
+
+
+Strings
+^^^^^^^
+
+A string is a sequence of characters surrounded by double quotes.
+In Asteroid, single characters are represented as single character strings.
+Similar to lists the member functions of strings can be called directly on the
+data structure itself, e.g.::
+
+   "Hello there" @length ()
+
+Member Functions
+%%%%%%%%%%%%%%%%
+
+string **@explode** ()
+      Returns the string as a list of characters.
+
+string **@flip** ()
+      Returns a copy of the string with its characters in the reverse order.
+
+string **@index** item:%string | (item:%string, loc(startix:%integer)) | (item:%string, loc(startix:%integer, endix:%integer))
+      Returns an integer index of the item in the string or none if item was not found.  
+      The  argument loc allows you to specify startix and endix and are used to limit the search 
+      to a particular substring of the string. The returned index is computed relative to the beginning 
+      of the full string rather than the startix.  
+
+string **@length** ()
+      Returns the number of characters within the string.
+
+string **@replace** (old:%string, new:%string) | (old:%string, new:%string, count:%integer)
+      Return a copy of the string with all occurrences of regular expression old replaced by the 
+      string new. If the argument count is given, only the first count occurrences are replaced. 
+
+string **@split** () | sep:%string | (sep:%string, count:%integer)
+      Return a list of the words in the string, using sep as the delimiter. If count is given then
+      at most count splits are done (thus, the list will have at most count+1 elements). If count is 
+      not specified or -1, then there is no limit on the number of splits (all possible splits are made).
+      Consecutive delimiters are not grouped together and are deemed to delimit empty strings. 
+      For example,::
+      
+            let s = "1,,2" @split ",".
+            assert (s == ["1", "", "2"]). 
+            
+      The sep argument may consist of multiple characters. 
+      For example,:: 
+      
+            let s = "1<>2<>3" @split "<>". 
+            assert (s == ["1", "2", "3"]).
+            
+      Splitting an empty string with a specified separator returns ``[""]``.
+      If sep is not specified or is None, a different splitting algorithm is applied: 
+      consecutive whitespace is regarded as a single separator, and the result will contain no empty strings at 
+      the start or end if the string has leading or trailing whitespace. Consequently, splitting an empty string 
+      or a string consisting of just whitespace with a none separator returns ``[]``.
+ 
+string **@tolower** ()
+      Returns a copy of the string in all lower case letters.
+
+string **@toupper** ()
+      Returns a copy of the string in all upper case letters.
+
+string **@trim** () | what:%string
+      Returns a copy of the string with the leading and trailing characters removed. 
+      The what argument specifies the set of characters to be removed. 
+      If omitted trim defaults to removing whitespace. 
+      The what argument is not a prefix or suffix; rather, all combinations of its characters are stripped.
 
-See the `Prologue module <https://github.com/asteroid-lang/asteroid/blob/master/asteroid/modules/prologue.ast>`_  for more on all the functions above.
 
 
 Asteroid Modules
@@ -799,146 +877,441 @@ we have ``println`` as one of the member functions.  To call that function::
    load system io.
    io @println "Hello there!".  -- println is a member function of the io module
 
-Bitwise
+bitwise
 ^^^^^^^
 
-The `bitwise <https://github.com/asteroid-lang/asteroid/blob/master/asteroid/modules/bitwise.ast>`_ module defines Bitwise operations. It supports the following functions,
-
-* Function ``band`` can be called with the input ``(x:%integer, y:%integer)``, and performs the Bitwise AND operation.
-* Function ``bor`` can be called with the input ``(x:%integer, y:%integer)``, and performs the Bitwise OR operation.
-* Function ``bnot`` can be called with the input ``(x:%integer)``, and performs the Bitwise NOT operation.
-* Function ``bxor`` can be called with the input ``(x:%integer, y:%integer)``, and performs the Bitwise XOR operation.
-* Function ``blshift`` can be called with the input ``(x:%integer, y:%integer)``, and performs the Bitwise left shift operation.
-* Function ``brshift`` can be called with the input ``(x:%integer, y:%integer)``, and performs the Bitwise right shift operation.
-* Function ``blrotate`` can be called with the input ``(x:%integer, i:%integer)``, and performs the Bitwise left rotate operation.
-* Function ``brrotate`` can be called with the input ``(x:%integer, i:%integer)``, and performs the Bitwise right rotate operation.
-* Function ``bsetbit`` can be called with the input ``(x:%integer, i:%integer)``, and sets the ith bit.
-* Function ``bclearbit`` can be called with the input ``(x:%integer, i:%integer)``, and clears the ith bit.
-* Function ``bsize``can be called with the input ``(x:%integer)``, and returns the bit size.
-
-Hash
+This module defines bitwise operations on integers. It supports the following functions,
+
+bitwise **@band** (x:%integer, y:%integer)
+      Performs the bitwise AND operation and returns the result as an integer.
+
+bitwise **@bclearbit** (x:%integer, i:%integer)
+      Clear the ith bit in x and returns the result as an integer.
+
+bitwise **@blrotate** (x:%integer, i:%integer)
+      Performs the bitwise left rotate operation by i bits and returns the result as an integer.
+
+bitwise **@blshift** (x:%integer, y:%integer)
+      Performs the bitwise left shift operation where x is shifted by y bits and returns the result as an integer.
+
+bitwise **@bnot** x:%integer
+      Performs the bitwise NOT operation and returns the result as an integer.
+
+bitwise **@bor** (x:%integer, y:%integer)
+      Performs the bitwise OR operation and returns the result as an integer.
+
+bitwise **@brrotate** (x:%integer, i:%integer)
+      Performs the bitwise right rotate operation by i bits and returns the result as an integer.
+
+bitwise **@brshift** (x:%integer, y:%integer)
+      Performs the bitwise right shift operation where x is shifted by y bits and returns the result as an integer.
+
+bitwise **@bsetbit** (x:%integer, i:%integer)
+      Sets the ith bit in x and returns the result as an integer.
+
+bitwise **@bsize** x:%integer
+      Returns the bit size of x.
+
+bitwise **@bxor** (x:%integer, y:%integer)
+      Performs the bitwise XOR operation and returns the result as an integer.
+
+
+hash
 ^^^^
 
-The `hash <https://github.com/asteroid-lang/asteroid/blob/master/asteroid/modules/hash.ast>`_ module implements a hash for name-values pairs. It supports the following functions,
+This module implements a hash for key-value pairs. It supports the following functions,
+
+hash **@hash** ()
+      Returns a new hash object of type __HASH__.
+
+__HASH__ **@aslist** ()
+      Returns the hash as a list of key-value pairs.
+
+__HASH__ **@get** key
+      Return the value associated with the given key as long as it can be found otherwise an exception will be thrown.
 
-* Function ``insert``, given the input ``(name,value)``, will insert a given name-value pair into the table.
-* Function ``get``, given ``name``, will return the ``value`` associated with the given ``name`` as long as it can be found otherwise an exception will be thrown.
-* Function ``aslist`` returns the hash as a list of name-value pairs.
+__HASH__ **@insert** (key, value) | pairs:%list
+      Given a pair of the format (key, value) insert it into the table.  Given a list
+      of the format,::
 
-IO
+            [(key1, val1), (key2, val2), ...]
+
+      insert all the key-value pairs on the list into the hash.
+
+io
 ^^
 
-The `io <https://github.com/asteroid-lang/asteroid/blob/master/asteroid/modules/io.ast>`_ module implements Asteroid's I/O system. The module defines three default streams,
+This module implements Asteroid's I/O system. The module defines three I/O streams,
 
-1. ``__STDIN__`` - the standard input stream.
-2. ``__STDOUT__`` - the standard output stream.
-3. ``__STDERR__`` - the standard error stream.
+1. __STDIN__ - the standard input stream.
+2. __STDOUT__ - the standard output stream.
+3. __STDERR__ - the standard error stream.
 
 Furthermore, the module supports the following functions,
 
-* Function ``println`` can be called with ``item``, and prints a given argument to the terminal (``__STDOUT__``) with an implicit newline character.
-* Function ``print`` can be called with ``item``, and prints a given argument. No implicit newline is appended to the output.
-* Function ``input`` can be called with a string ``prompt``.  If ``prompt`` is given it is printed and then input is read from the terminal (``__STDIN__``) and returned as a string.
-* Function ``open`` opens a file. Given ``(name:%string, mode:%string)``, it returns a file descriptor of type ``FILE``. The ``mode`` string can be ``"r"`` when the file will only be read, ``"w"`` for only writing (an existing file with the same name will be erased), and ``"a"`` opens the file for appending; any data written to the file is automatically added to the end. The ``"r+"`` opens the file for both reading and writing.
-* Function ``close``, given ``file:%FILE``, closes that file.
-* Function ``read``, given ``file:%FILE``, reads a file. If no file is given the ``__STDIN__`` stream is read.
-* Function ``readln``, given ``file:%FILE``, reads a given line of input from the file. If no file is given the ``__STDIN__`` stream is read.
-* Function ``write``, given ``(file:%FILE, what:%string)``, will write ``what`` to the given ``file``.  If ``file`` is not given then it writes to the ``__STDOUT__`` stream.
-* Function ``writeln``, works the same way as ``write`` except that it appends a newline character to the output.
-
-Math
-^^^^
-
-The `math <https://github.com/asteroid-lang/asteroid/blob/master/asteroid/modules/math.ast>`_ module implements mathematical constants and functions. It supports the following functions,
+io **@close** file:%\_\_FILE\_\_
+      Closes the file where file is a file descriptor of type \_\_FILE\_\_.
 
-*Power and logarithmic functions*
+io **@input** () | prompt:%string
+      Ask the user for input from __STDIN__.  The input is returned as a string. If prompt is given it is printed and then input is read from terminal.
 
-* Function ``exp``, given ``x:%integer``, returns e raised to the power ``x``, where e = 2.718281… is the base of natural logarithms.
-* Function ``log`` can be called with two different argument setups,
+io **@open** (name:%string, mode:%string)
+      Returns a file descriptor of type \_\_FILE\_\_. 
+      The mode string can be "r" when the file will only be read, 
+      "w" for only writing (an existing file with the same name will be erased), 
+      and "a" opens the file for appending; any data written to the file is 
+      automatically added to the end. 
+      Finally,  "r+" opens the file for both reading and writing.
 
-  1. If only one argument, ``(x)``, is input, this returns the natural logarithm of x (to base e).
-  2. If two arguments, ``(x,base)``, are input, this returns the logarithm of x to the given base, calculated as log(x)/log(base).
+io **@print** item
+      Prints item to the terminal (__STDOUT__). No implicit newline is appended to the output.
 
-* Function ``pow``, given ``(b,p:%integer)``, returns "b <sup>p</sup>" as long as b is either ``real`` or ``integer``.
-* Function ``sqrt``, given ``a``, returns its square root as long as ``a`` is either ``real`` or ``integer``.
+io **@println** item
+      Prints item to the terminal (__STDOUT__) with an implicit newline character.
 
-*Number-theoretic and representation functions*
+io **@read** () | file:%\_\_FILE\_\_
+      Read a file and return the contents as a string. If no file is given the __STDIN__ stream is read.
 
-* Function ``abs``, given ``x``, returns its absolute value.
-* Function ``ceil``, given ``x:%real``, returns the ceiling of x: the smallest integer greater than or equal to x.
-* Function ``floor``, given ``x:%real``, returns the floor of x: the largest integer less than or equal to x.
-* Function ``gcd``, given ``(a:%integer,b:%integer)``, returns the greatest common denominator that both integers share.
-* Function ``isclose`` can be called with two different argument setups,
+io **@readln** () | file:%\_\_FILE\_\_
+      Reads a line of input from a file and returns it as a string. If no file is given the __STDIN__ stream is read.
 
-  1. With input values ``(a,b)``, it returns returns ``true`` if the two values are close to each other and ``False`` otherwise. Default tolerance 1e-09.
-  2. With input values ``(a,b,t)``, it compares ``a`` and ``b`` with tolerance ``t``.
+io **@write** what:%string | (file:%\_\_FILE\_\_, what:%string)
+      Write what to a file.  If file is not given then it writes to the __STDOUT__ stream.
 
-* Function ``mod``, given ``(v,d)``, will return the remainder of the operation ``v/d``, as long as ``v`` and ``d`` are either ``real`` or ``integer`` values.
+io **@writeln** what:%string | (file:%\_\_FILE\_\_, what:%string)
+      Write what to a file and append a newline charater.  If file is not given then it writes to  __STDOUT__.
 
-*Trigonometric functions*
 
-* Function ``acos``, given ``x``, returns the arc cosine of x in radians. The result is between 0 and pi.
-* Function ``asin``, given ``x``, returns the arc sine of x in radians. The result is between -pi/2 and pi/2.
-* Function ``atan``, ,given ``x``, returns the arc tangent of x in radians. The result is between -pi/2 and pi/2.
-* Function ``cos``, given ``x``, returns the cosine of x radians.
-* Function ``sin``, given ``x``, returns the sine of x radians.
-* Function ``tan``, given ``x``, returns the tangent of x radians.
-* Function ``acosh``, given ``x``, returns the inverse hyperbolic cosine of x.
-* Function ``asinh``, given ``x``, returns the inverse hyperbolic sine of x.
-* Function ``atanh``, given ``x``, returns the inverse hyperbolic tangent of x.
-* Function ``cosh``, given ``x``, returns the hyperbolic cosine of x.
-* Function ``sinh``, given ``x``, returns the hyperbolic sine of x.
-* Function ``tanh``, given ``x``, returns the hyperbolic tangent of x.
-* Function ``degrees``, given ``x``, converts angle ``x`` from radians to degrees.
-* Function ``radians``,  given ``x``, converts angle ``x`` from degrees to radians.
+math
+^^^^
 
+The math module implements mathematical constants and functions.
 An example,
 ::
 #include "../asteroid/test-suites/ref-programs/math.ast"
 
-Pick
+Constants
+%%%%%%%%%
+
+math **@pi**
+      The mathematical constant π = 3.141592…, to available precision.
+
+math **@e**
+      The mathematical constant e = 2.718281…, to available precision.
+
+
+Power and logarithmic functions
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+math **@exp** x:%integer
+      Returns e raised to the power x, where e = 2.718281… is the base of the natural logarithm.
+
+math **@log** x | (x, base:%integer)
+      If only argument x is the input, return the natural logarithm of x (to base e).
+      If two arguments, (x, base:%integer), are given as input, return the logarithm 
+      of x to the given base, calculated as log(x)/log(base).
+
+math **@pow** (b, p:%integer)
+      Return b raised to the power p.  The return type depends on the type
+      of the base.
+
+math **@sqrt** x 
+      Return the square root of x as a real.
+
+
+Number-theoretic and representation functions
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+math **@abs** x
+      Return that absolute value of x.  The return type depends on the type of x.
+
+math **@ceil** x:%real
+      Returns the ceiling of x: the smallest integer greater than or equal to x.
+
+math **@floor** x:%real
+      Returns the floor of x: the largest integer less than or equal to x.
+
+math **@gcd** (a:%integer, b:%integer)
+      Returns the greatest common denominator that both integers share.
+
+math **@isclose** (a:%real, b:%real) | (a:%real, b:%real, t:%real)
+      Return true if the values a and b are close to each other and false otherwise.
+      Default tolerance is 1e-09.  An alternative tolerance can be specified with 
+      the t argument.
+
+math **@mod** (v,d)
+      Implements the modulus operation. Returns the remainder of the quotient v/d.
+
+
+Trigonometric functions
+%%%%%%%%%%%%%%%%%%%%%%%
+
+math **@acos** x
+      Returns the arc cosine of x in radians. The result is between 0 and pi.
+
+math **@asin** x
+      Returns the arc sine of x in radians. The result is between -pi/2 and pi/2.
+
+math **@atan** x
+      Returns the arc tangent of x in radians. The result is between -pi/2 and pi/2.
+
+math **@cos** x
+      Returns the cosine of x radians.
+
+math **@sin** x
+      Returns the sine of x radians.
+
+math **@tan** x
+      Returns the tangent of x radians.
+
+Hyperbolic functions
+%%%%%%%%%%%%%%%%%%%%
+
+math **@acosh** x
+      Returns the inverse hyperbolic cosine of x.
+
+math **@asinh** x
+      Returns the inverse hyperbolic sine of x.
+
+math **@atanh** x
+      Returns the inverse hyperbolic tangent of x.
+
+math **@cosh** x
+      Returns the hyperbolic cosine of x.
+
+math **@sinh** x
+      Returns the hyperbolic sine of x.
+
+math **@tanh** x
+      Returns the hyperbolic tangent of x.
+
+Angular conversion
+%%%%%%%%%%%%%%%%%%
+
+math **@degrees** x
+      Converts angle x from radians to degrees.
+
+math **@radians** x
+      Converts angle x from degrees to radians.
+
+
+os
+^^
+
+This module provides a portable way of using operating system dependent functionality. 
+
+Process Parameters
+%%%%%%%%%%%%%%%%%%
+
+os **@argv**
+      The list of command line arguments passed to an Asteroid script. 
+      argv[0] is the name of the Asteroid script (it is operating 
+      system dependent whether this is a full pathname or not).
+      In interactive mode argv[0] will be the empty string.
+
+os **@env**
+      A hash table where keys and values are strings that represent 
+      the process environment. For example, 
+            os @env @get "HOME"
+      is the pathname of your home directory (on some platforms), 
+      and is equivalent to getenv("HOME") in C.
+
+os **@platform**
+      This string contains a platform identifier.
+
+
+Functions
+%%%%%%%%%
+
+os **@basename** path:%string
+      Return the base name of pathname path. This is the second element of the pair
+      returned by passing path to the function split. Note that the result of this
+      function is different from the Unix basename program; where basename for '/foo/bar/'
+      returns 'bar', the basename function returns an empty string ("").
+
+os **@chdir** path:%string
+      Change the current working directory to path.
+
+os **@dirname** path:%string
+      Return the directory name of pathname path. This is the first element of the 
+      pair returned by passing path to the function split.
+
+os **@exists** path:%string
+      Return true if path refers to an existing path or an open file descriptor. 
+      Returns false for broken symbolic links. On some platforms, this function 
+      may return False if permission is not granted to execute stat on 
+      the requested file, even if the path physically exists.
+
+os **@exit** () | v:%integer | msg:%string
+      Signaling an intention to exit the interpreter.
+      When an argument value other than none is provided
+      it is considered a status value. If it is 
+      an integer, zero is considered “successful termination” and any 
+      nonzero value is considered “abnormal termination” by shells and 
+      the like. Most systems require it to be in the range 0–127, and 
+      produce undefined results otherwise. Some systems have a 
+      convention for assigning specific meanings to specific exit codes, 
+      but these are generally underdeveloped; Unix programs generally 
+      use 2 for command line syntax errors and 1 for all other kind 
+      of errors. If none is given as an argument value then is it
+      is considered to be a successful exit equivalent to passing a zero. 
+      If a string is passed then it is printed printed to 
+      __STDERR__ and results in an exit code of 1. In particular, 
+      sys.exit("some error message") is a quick way to exit a program 
+      when an error occurs.
+
+os **@getdir** ()
+      Return a string representing the current working directory.
+
+os **@getpathtime** path:%string | (path:%string,flag:%boolean)
+      Returns a triple with (creation, access, modification) times.
+      By default the return value is a triple of real numbers
+      giving the number of seconds since 1/1/1970.  If the flag is set
+      to true then a triple of strings is returned where each string
+      represents the respective local time. Throws an exception if the file 
+      does not exist or is inaccessible.
+
+os **@getsize** path:%string
+      Return the size, in bytes, of path. Throws exception if the file 
+      does not exist or is inaccessible.
+
+os **@isfile** path:%string
+      Return true if path is an existing regular file. This follows 
+      symbolic links.
+
+os **@isdir** path:%string
+      Return true if path is an existing directory. This follows 
+      symbolic links.
+
+os **@join** (path1:%string,path2:%string)
+      Join path1 and path2 components intelligently. The return value 
+      is the concatenation of path and any members of *paths with 
+      exactly one directory separator following each non-empty part 
+      except the last, meaning that the result will only end in a 
+      separator if the last part is empty. If the second component is an 
+      absolute path, the first component is thrown away. 
+
+      On Windows, the drive letter is not reset when an absolute 
+      path component (e.g., r'\foo') is encountered. If a component 
+      contains a drive letter, all previous components are thrown away 
+      and the drive letter is reset. Note that since there is a current 
+      directory for each drive, os.path.join("c:", "foo") represents a 
+      path relative to the current directory on drive C: (c:foo), not c:\foo.
+
+os **@split** path:%string
+      Split the pathname path into a pair, (head, tail) where tail is 
+      the last pathname component and head is everything leading up to 
+      that. The tail part will never contain a slash; if path ends in 
+      a slash, tail will be empty. If there is no slash in path, head 
+      will be empty. If path is empty, both head and tail are empty. 
+      Trailing slashes are stripped from head unless it is the root 
+      (one or more slashes only). Also see the functions dirname and 
+      basename.
+
+os **@splitdrive** path:%string
+      Split the pathname path into a pair (drive, tail) where drive is 
+      either a mount point or the empty string. On systems which do not 
+      use drive specifications, drive will always be the empty string. 
+      In all cases, drive + tail will be the same as path.
+
+      On Windows, splits a pathname into drive/UNC sharepoint and 
+      relative path.
+
+      If the path contains a drive letter, drive will contain everything 
+      up to and including the colon.
+
+os **@splitext** path:%string
+      Split the pathname path into a pair (root, ext) such that 
+      root + ext == path, and the extension, ext, is empty or begins 
+      with a period and contains at most one period. If the path contains 
+      no extension, ext will be the empty string.
+
+os **@syscmd** cmd:%string
+      Execute a command in a subshell. This is implemented 
+      by calling the Standard C function system, and has the same 
+      limitations. If command generates any output, it will be 
+      sent to the interpreter standard output stream. 
+      The C standard does not specify the meaning of the return value of 
+      the C function, so the return value of this function is 
+      system-dependent.
+
+
+
+
+pick
 ^^^^
 
-The `pick <https://github.com/asteroid-lang/asteroid/blob/master/asteroid/modules/pick.ast>`_ module implements
-pick objects that allow a user to randomly pick items from a list using the ``pick`` function.
-The ``pick`` function can be called with ``n:%integer`` and returns a list of ``n`` randomly picked objects from the object list.
-Here is a simple use case
-::
+The pick module implements
+pick objects that allow a user to randomly pick items from a list of items using the pickitems function.
+
+pick **@pick** l:%list
+      Construct a pick object of type __PICK__.
+
+__PICK__ **@pickitems** () | n:%integer
+      Return items randomly picked from the list l.  If no input is provided 
+      then pickitems will return a single, randomly picked item from the list.
+      If an integer value n is given then a list of n randomly picked items from 
+      the list l is returned.  The picked item list is constructed by sampling the 
+      list l with replacement.
+
+An example::
 #include "../asteroid/test-suites/ref-programs/pick.ast"
 
 
-Random
+random
 ^^^^^^
 
-The `random <https://github.com/lutzhamel/asteroid/blob/master/asteroid/modules/random.ast>`_ module implements the ``random`` numbers. Using the functions included in this module will return a random value within a given range or interval. It supports the following functions,
+The random module implements random number generation. 
 
-* Function ``random``, given the input ``none``, returns a random floating point number in the range ``[0.0, 1.0)``.
-* Function ``randint`` returns a random value N in the interval lo <= N <= hi. The exact random value output depends on the types of the values specifying the interval. It can be called with two different number interval inputs:
+random **@randint** (lo:%integer,hi:%integer) | (lo:%real,hi:%real)
+      Return a random value N in the interval lo <= N <= hi.
+      The type of the random value depends on the types of the
+      values specifying the interval.  If the interval is specified 
+      with integers then a random integer value is returned. 
+      If the interval is specified with real numbers then a real value is
+      is returned, and for everything else an exception is thrown.
 
-  1. ``(lo:%integer,hi:%integer)``
-  2. ``(lo:%real,hi:%real)``
-  3. Note: any other interval specification will instead output an error message for "unsupported interval specification in randint."
+random **@random** ()
+      Return a random real number in the range [0.0, 1.0).
 
-* Function ``seed``, given ``(sd:%integer)``, provides a seed value for the random number generator.
+random **@seed** x:%integer
+      Provide the seed value x for the random number generator.
 
-Set
+set
 ^^^
 
-The `set <https://github.com/asteroid-lang/asteroid/blob/master/asteroid/modules/set.ast>`_ module implements Asteroid sets as lists. Unlike lists, sets do not have repeated members. It supports the following functions,
+The set module implements Asteroid sets as lists. 
+Unlike lists, sets do not have repeated elements.
+Use the set member function toset to turn any list 
+into a list that represents a set (remove repeated items).
 
-* Function ``toset``, given ``(lst:%list)``, converts the input list into a set.
-* Function ``diff``, given ``(a:%list,b:%list)``, computes the difference set between the two set ``a`` and ``b``.
-* Function ``intersection``, given ``(a:%list,b:%list)``, finds the intersection between  sets ``a`` and ``b``.
-* Function ``union``, given ``(a:%list,b:%list)``, computes the union of sets ``a`` and ``b``.
-* Function ``xunion``, given ``(a:%list,b:%list)``, returns all elements in ``a`` or ``b``, but not in both.
+set **@diff** (a:%list,b:%list)
+      Return the difference set between sets a and b.
 
-Sort
+set **@intersection** (a:%list,b:%list)
+      Return the intersection of sets a and b.
+
+set **@toset** l:%list
+      Return list l as a set by removing repeated elements.
+
+set **@union** (a:%list,b:%list)
+      Return the union of sets a and b.
+
+set **@xunion** (a:%list,b:%list)
+      Return the elements in a or b but not both.
+
+
+sort
 ^^^^
 
-The `sort <https://github.com/asteroid-lang/asteroid/blob/master/asteroid/modules/sort.ast>`_ module
-defines a parameterized ``sort`` function over a list.
-The ``sort`` function makes use of a user-defined order predicate on the list's elements to
-perform the sort. The ``Quicksort`` is the underlying sort algorithm.
+The sort  module
+defines a parameterized sort function over a list.
+The sort function makes use of a user-defined order predicate on the list's elements to
+perform the sort. The QuickSort is the underlying sort algorithm.
+
+sort **@sort** (p:%function,l:%list)
+      Returns the sorted list l using the predicate p.
+
 The following is a simple example,
 ::
 #include "../asteroid/test-suites/ref-programs/sort.ast"
@@ -947,23 +1320,37 @@ prints the sorted list::
 
   [5,10,50,110]
 
-Stream
+stream
 ^^^^^^
 
-The `stream <https://github.com/asteroid-lang/asteroid/blob/master/asteroid/modules/stream.ast>`_ module implements streams that allow
-the developer to turn any list into a stream supporting interface functions like ``peeking`` ahead or ``rewinding`` the stream.
-The following stream interface functions are available,
+The stream module implements streams that allow
+the developer to turn any list into a stream supporting interface functions like peeking ahead or rewinding
+the stream.
 
-* Function ``eof`` returns ``true`` if the stream does not contain any further elements for processing. Otherwise it returns ``false``.
-* Function ``peek`` returns the current element available on the stream otherwise it returns ``none``.
-* Function ``get`` returns the current element and moves the stream pointer one ahead.
-* Function ``rewind`` resets the stream pointer to the first element of the stream.
-* Function ``map`` applies a given function to each element in the stream.
-* Function ``append``, given ``item``, adds item to the end of the stream.
-* Function ``__string__`` maps a the stream to a string representation.
+stream **@stream** l:%list
+      Returns a stream object of type __STREAM__.
 
-A simple use case.
-::
+__STREAM__ **@append** x
+      Adds x to the end of the stream.
+
+__STREAM__ **@eof** ()
+      Returns true if the stream does not contain any further elements for processing.
+      Otherwise it returns false.
+
+__STREAM__ **@get** ()
+      Returns the current element and moves 
+      the stream pointer one ahead.  Returns none if no elements left in stream.
+
+__STREAM__ **@map** f:%function
+      Applies function f to each element in the stream.
+
+__STREAM__ **@peek** () 
+      Returns the current element available on the stream otherwise it returns none.
+
+__STREAM__ **@rewind** ()
+      Resets the stream pointer to the first element of the stream.
+
+A simple use case::
 #include "../asteroid/test-suites/ref-programs/stream.ast"
 
 which outputs::
@@ -971,31 +1358,31 @@ which outputs::
    1 2 3 4 5 6 7 8 9 10
 
 
-Type
+type
 ^^^^
 
-The `type <https://github.com/asteroid-lang/asteroid/blob/master/asteroid/modules/type.ast>`_ module defines type related functions and structures.
-
-*Type Conversion*
+The type module defines type related functions and structures.
 
-* Function ``tointeger`` converts a given input to an integer. It can be called with two different arguments,
+Type Conversion
+%%%%%%%%%%%%%%%
 
-  1. ``(item:%string,base:%integer)`` where ``base`` is a valid base for integer conversion
-  2. ``item`` where ``item`` is converted to a base 10 integer.
+type **@tobase** (x:%integer,base:%integer)
+      Represents the given integer x as a numeral string in different bases.
 
+type **@toboolean** x
+      Interpret x as a Boolean value.
 
-* Function ``toreal``, given ``item``, returns the input as a real number data type.
-* Function ``toboolean``, given ``item``, returns the input as a Boolean value of either true or false.
-* Function ``tostring`` converts an Asteroid object to a string. If format values are given, it applies the formatting to the object. It can be called with several different inputs where ``*TP`` indicates a``boolean``, ``integer``, or ``string`` type and ``w`` is the width specification, ``p`` is the precision specification and ``s`` is the scientific notation flag.  When no formatting information is provided a default string conversion occurs,
+type **@tointeger** (x:%string,base:%integer) | x 
+      Converts a given input to an integer. If a base value is specified then 
+      the resulting integer is in the corresponding base.
 
-  1. ``(v:*TP,type @stringformat(w:%integer))``
-  2. ``(v:%real,type @stringformat(w:%integer))``
-  3. ``(v:%real,type @stringformat(w:%integer,p:%integer))``
-  4. ``(v:%real,type @stringformat(w:%integer,p:%integer,s:%boolean))``
-  5. ``item`` - default conversion
-
-* Function ``tobase`` represents the given integer ``x`` (*specifically* within the given input ``(x:%integer,base:%integer)``) as a string in the given base.
+type **@toreal** x
+      Returns the input as a real number.
 
+type  **@tostring** x | (x,type @stringformat(width:%integer,precision:%integer,scientific:%boolean)) 
+      Converts an Asteroid object to a string. If format values are given, 
+      it applies the formatting to the string object. 
+      
 Here is a program that exercises some of the string formatting options,
 ::
 #include "../asteroid/test-suites/ref-programs/format.ast"
@@ -1011,49 +1398,82 @@ The output of the program is,
 Notice the right justification of the various values within the given string length.
 
 
-*Type Query Functions*
+Type Query Functions
+%%%%%%%%%%%%%%%%%%%%
+
+type **@islist** x 
+      Returns true if x is a list otherwise it will return false.
+
+type **@isnone** x
+      Returns true if x is equal to the value none.
 
-* Function ``islist`` returns ``true`` if given ``item`` is a list otherwise it will return ``false``.
-* Function ``isscalar`` returns ``true`` if given ``item`` is either an integer or a real value.
-* Function ``isnone`` returns ``true`` if given ``item`` is equal to the value ``none``.
-* Function ``gettype`` returns the type of a given ``item`` as an Asteroid string.
+type **@isscalar** x
+      Returns true if x is either an integer or a real value.
+
+type **@gettype** x
+      Returns the type of x as a string.
 
 A simple example program using the ``gettype`` function,
 ::
 #include "../asteroid/test-suites/ref-programs/type.ast"
 
-Util
+util
 ^^^^
 
-The `util <https://github.com/asteroid-lang/asteroid/blob/master/asteroid/modules/util.ast>`_ module defines utility functions and structures that don't really fit into any omodules. It supports the following functions,
+The util module defines utility functions and structures that don't really 
+fit into any other modules. 
+
+util **@achar** x
+      Given a decimal ASCII code x, return the corresponding character symbol.
+
+util **@ascii** x:%string
+      Given a character x, return the corresponding ASCII code of the first character of the input.
 
-* Function ``exit`` exits the program. It can be called with two inputs,
+util **@cls** ()
+      Clears the terminal screen.
 
-  1. ``none``
-  2. ``msg:%string``
+util **@copy** x
+      Given the object x, make a deep copy of it.
 
-* Function ``copy``, given Asteroid object ``obj``, makes a deep copy of it.
-* Function ``cls`` clears the terminal screen.
-* Function ``sleep``,  programs sleep for ``secs`` seconds where the argument ``secs`` is either an integer or real value.
-* Function ``zip``, given ``(list1:%list,list2:%list)``, will return a list where element ``i`` of the list is the tuple ``(list1@i,list2@i)``.
-* Function ``unzip``, given a list of pairs will return a pair of lists where the first component of the pair is the list of all the first components of the pairs of the input list and the second component of the return list is a list of all the second components of the input list.
-* Function ``ascii``, given a character ``item:%string``, returns the corresponding ASCII code of the first character of the input string.
-* Function ``achar``, given a decimal ASCII code ``item:%integer``, returns the corresponding character symbol.
+util **@ctime** x:%real
+      Given a real value representing seconds since 1/1/1970 this function 
+      converts it to a suitable string representation of the date.
 
-Vector
+type **@sleep** x 
+      Sleep for x seconds where the x is either an integer or real value.
+
+type **@time** ()
+      Returns the local time as a real value in secs since 1/1/1970.
+
+type **@unzip** x:%list
+      Given a list of pairs x this function will return a pair of lists 
+      where the first component of the pair is the list of all the first 
+      components of the pairs of the input list and the second component 
+      of the return list is a list of all the second components of the input list.
+
+type **@zip** (list1:%list,list2:%list)
+      Returns a list where element i of the list is the tuple (list1@i,list2@i).
+
+vector
 ^^^^^^
 
-The `vector <https://github.com/asteroid-lang/asteroid/blob/master/asteroid/modules/vector.ast>`_ defines functions useful for vector arithmetic. It supports the following functions.  Here ``a`` and ``b`` are vectors implemented as lists,
+The vector defines functions useful for vector arithmetic. Vectors are implemented as lists.
+
+vector **@add** (a:%list,b:%list) 
+      Returns a vector that contains the element by element sum of the input vectors a and b.
+
+vector **@dot** (a:%list,b:%list) 
+      Computes the dot product of the two vectors a and b.
+
+vector **@mult** (a:%list,b:%list)
+      Returns the element by element vector multiplication of vectors a and b.
 
-* Function ``add``, given the input ``(a,b)``, returns a vector that contains the element by element sum of the input vectors.
-* Function ``sub``, given the input ``(a,b)``, returns the element by element difference vector.
-* Function ``mult``, given the input ``(a,b)``, returns the element by element vector multiplication.
-* Function ``dot``, given ``(a,b)``, computes the dot product of the two vectors.
-* Function ``op``  allows the developer to vectorize any function. It can be called with three different inputs:
+vector **@op** (f:%function,a:%list,b:%list) | (f:%function,a:%list,b if type @isscalar(b)) | (f:%function,a if type @isscalar(a),b:%list)
+      Allows the developer to vectorize any function f. Applying scalar values 
+      to vectors is also supported by this function.
 
-  1. ``(f:%function,a:%list,b:%list)``
-  2. ``(f:%function,a:%list,b if type @isscalar(b))``
-  3. ``(f:%function,a if type @isscalar(a),b:%list)``
+vector **@sub** (a:%list,b:%list)
+      Returns the element by element difference vector.
 
 Here is a simple example program for the ``vector`` module,
 ::
diff --git a/docs/User Guide.rst b/docs/User Guide.rst
index 9a94492c..99b3fa2a 100644
--- a/docs/User Guide.rst
+++ b/docs/User Guide.rst
@@ -1,13 +1,15 @@
-/******************************************************************
-  This is the source file from which the user guide is generated.
-  We use cpp to insert live code snippets into the document.
-  In order to generate the user guide run the following command
-  on a Unix-like system in the directory of this doc:
+..
+    /******************************************************************
+    This is the source file from which the user guide is generated.
+    We use cpp to insert live code snippets into the document.
+    In order to generate the user guide run the following command
+    on a Unix-like system in the directory of this doc:
 
-  bash generate_docs
+    bash generate_docs
 
- ******************************************************************/
-/* header for generated .rst files */
+    ******************************************************************/
+..
+   /* header for generated .rst files */
 
 ..
    *** DO NOT EDIT; MACHINE GENERATED ***
diff --git a/docs/User Guide.txt b/docs/User Guide.txt
index 42c837bc..e0d0fe08 100644
--- a/docs/User Guide.txt
+++ b/docs/User Guide.txt
@@ -1,12 +1,14 @@
-/******************************************************************
-  This is the source file from which the user guide is generated.
-  We use cpp to insert live code snippets into the document.
-  In order to generate the user guide run the following command
-  on a Unix-like system in the directory of this doc:
+..
+    /******************************************************************
+    This is the source file from which the user guide is generated.
+    We use cpp to insert live code snippets into the document.
+    In order to generate the user guide run the following command
+    on a Unix-like system in the directory of this doc:
 
-  bash generate_docs
+    bash generate_docs
+
+    ******************************************************************/
 
- ******************************************************************/
 #include "header.txt"
 
 .. highlight:: none
diff --git a/docs/header.txt b/docs/header.txt
index eb548f7b..ffc3e15c 100644
--- a/docs/header.txt
+++ b/docs/header.txt
@@ -1,4 +1,5 @@
-/* header for generated .rst files */
+..
+   /* header for generated .rst files */
 
 ..
    *** DO NOT EDIT; MACHINE GENERATED ***


Test patch:
diff --git a/asteroid/test-suites/action-tests/test013.ast b/asteroid/test-suites/action-tests/test013.ast
index a0211b23..3cea1353 100644
--- a/asteroid/test-suites/action-tests/test013.ast
+++ b/asteroid/test-suites/action-tests/test013.ast
@@ -15,8 +15,7 @@
   let pick_list = int_list+lc_list+uc_list+sp_list.
 
   -- generate the password and print it.
-  let pwd = pick @pick pick_list @pick(15)
-                           @join("").
+  let pwd = pick @pick pick_list @pickitems 15 @join("").
   io @println pwd.
 
   assert (pwd == "e3zvshdbS43brt#")
diff --git a/asteroid/test-suites/action-tests/test024.ast b/asteroid/test-suites/action-tests/test024.ast
index d2d1e37b..f8e3dbfe 100644
--- a/asteroid/test-suites/action-tests/test024.ast
+++ b/asteroid/test-suites/action-tests/test024.ast
@@ -1,7 +1,8 @@
   load system io.
   load system math.
 
+  let tau = 2 * math @pi.
+
   io @println (math @e).
-  io @println (math @tau). -- tau=2*pi
+  io @println tau.
 
-  assert (math @tau == 2 * math @pi)
diff --git a/asteroid/test-suites/ref-programs/pick.ast b/asteroid/test-suites/ref-programs/pick.ast
index 6378639c..1ba8821b 100644
--- a/asteroid/test-suites/ref-programs/pick.ast
+++ b/asteroid/test-suites/ref-programs/pick.ast
@@ -2,6 +2,6 @@
    load system pick.
 
    let po = pick @pick([1 to 10]).
-   let objects = po @pick(3).
+   let objects = po @pickitems 3.
    io @println objects.
    
\ No newline at end of file
diff --git a/asteroid/test-suites/ref-programs/sort.ast b/asteroid/test-suites/ref-programs/sort.ast
index 34ac21f7..f5b65dc7 100644
--- a/asteroid/test-suites/ref-programs/sort.ast
+++ b/asteroid/test-suites/ref-programs/sort.ast
@@ -1,5 +1,5 @@
    load system io.
    load system sort.
-   let sl = sort @sort((lambda with (x,y) do return true if x<y else false),
+   let sl = sort @sort((lambda with (x,y) do true if x<y else false),
                        [10,5,110,50]).
-    io @println sl.
+   io @println sl.
diff --git a/asteroid/test-suites/ref-programs/stream.ast b/asteroid/test-suites/ref-programs/stream.ast
index b4d85cd0..41971f97 100644
--- a/asteroid/test-suites/ref-programs/stream.ast
+++ b/asteroid/test-suites/ref-programs/stream.ast
@@ -1,9 +1,9 @@
    load system io.
    load system stream.
 
-   let s = stream @stream([1 to 10]).
-   while not s @ eof() do
-      io @ print (s @get()+" ").
+   let s = stream @stream [1 to 10].
+   while not s @eof() do
+      io @print (s @get() + " ").
    end
-   io @println ("").
+   io @println "".
    
\ No newline at end of file