Anarki Reference Documentation

All this functionality is subject to change! You're welcome to edit it with us on GitHub, or you can open a GitHub issue or an Arc Forum thread for some help! We count on contributions like yours to make Anarki better.

Since others are welcome to do the same thing, watch out for changes in this space.

Documented in arc.arc

[sym] ($ expr)
Evaluates 'expr' using the underlying Racket implementation.
[mac] (++ place (o i 1))
Increments 'place' by 'i' (1 by default).
[mac] (-- place (o i 1))
Decrements 'place' by 'i' (1 by default).
[fn]  (<= . args)
Is each element of 'args' lesser than or equal to all following elements?
[mac] (= . args)
(= var val) saves 'val' in 'var'.
(= var1 val1 var2 val2) saves 'val's in corresponding 'var's.
'var's can be complex expressions like (car x), and so on. See defset.
When you run multiple threads at once, only one will ever be modifying a variable at once.
See atomic.

Examples:
  arc> (= x 1)
  arc> (= x 2 y 4)
[fn]  (>= . args)
Is each element of 'args' greater than or equal to all following elements?
[mac] (aand . args)
Like and, but each expression in 'args' can access the result of the
previous one in variable 'it'.

Examples:
  arc> (aand 
         1
         (+ it 2)
         (* it 10))
  30
[fn]  (abs n)
Returns the absolute value of 'n'.
[mac] (accum accfn . body)
Runs 'body' (usually containing a loop) and then returns in order all the
values that were called with 'accfn' in the process.
Can be cleaner than map for complex anonymous functions.

Examples:
  arc> (accum accfn
         (each x '(1 2 3)
           (accfn (* x 10))))
  (10 20 30)
  arc> (accum yield
         (each x "abcd"
           (yield x)))
  (a b c d)
[mac] (acheck x test (o alt))
Like check, but 'alt' can refer to the value of expr 'x' as 'it.
Pronounced 'anaphoric check'.
[fn]  (acons x)
Is 'x' a non-nil list?
[mac] (afn parms . body)
Like fn and rfn but the created function can call itself as 'self'

Examples:
  arc> ((afn (x)
          (if (is x 0)
            1
            (* 2
               (self (- x 1)))))
        5)
  32
[mac] (after x . ys)
Runs all 'ys' after 'x', even if 'x' throws an error.
Returns result of 'x' on success, and nothing on error.
[mac] (aif expr . branches)
Like if, but also puts the value of 'expr' in variable 'it'.

Examples:
  arc> (aif (> 1 2)
              (+ it 1)
            42
              (+ it 2))
  44
  arc> (let h (obj a 1)
         (aif h!a (+ it 1)))
  2
[fn]  (alist x)
Is 'x' a (possibly empty) list?
[fn]  (all test seq)
Does every element of 'seq' satisfy 'test'?
[fn]  (allchars str)
Outputs all characters in a stream.
[fn]  (alphadig c)
Is 'c' a latter or a digit?
[fn]  (alref al key)
Returns the value of 'key' in an association list 'al' of (key value) pairs
[mac] (and . args)
Stops at the first argument to fail (return nil). Returns the last argument before stopping.
[fn]  (andf . fns)
Returns a function which calls all the functions in 'fns' on its args, and
ands the results. For example, ((andf f g) x y) <=> (and (f x y) (g x y)).
Simple syntax: f&g <=> (andf f g)
[fn]  (annotate tag . val)
Creates a user-defined tagged type containing 'val'. See also type and rep.
[fn]  (apply f . args)
(apply f '(1 2 3)) <=> (f 1 2 3)
(apply f x y '(z w)) <=> (f x y z w)
[mac] (as type expr)
Tries to convert 'expr' into a different 'type'.
More convenient form of coerce with arguments reversed; doesn't need
'type' to be quoted.
[sym] (assign x y)
Set variable 'x' to value 'y'.

Examples:
  arc> (assign x 10)
[fn]  (assoc key al)
Finds a (key value) pair in an association list 'al' of such pairs.
[fn]  (atend i s)
Is index 'i' at or past the end of sequence 's'?
[mac] (atlet . args)
Like let, but atomic.
[fn]  (atom x)
Is 'x' a simple type? (i.e. not list, table or user-defined)
[mac] (atomic . body)
Runs expressions in 'body' with exclusive access to system resources.
Currently invoked for you anytime you modify a variable. This can slow things down, but
prevents multiple threads of execution from stepping on each other's toes by, say,
writing to a variable at the same time.
[mac] (atwith . args)
Like with, but atomic.
[mac] (atwiths . args)
Like withs, but atomic.
[fn]  (avg ns)
Returns the arithmetic mean of a list of numbers 'ns'.
[mac] (awhen expr . body)
Like when, but also puts the value of 'expr' in variable 'it'.

Examples:
  arc> (awhen (* 2 3)
         (+ it 1))
  7
[fn]  (before x y seq (o i 0))
Does 'x' lie before 'y' in 'seq' (optionally starting from index 'i')?

Examples:
  arc> (before 2
               3
               '(1 2 3 4))
  t
  arc> (before 2
               1
               '(1 2 3 4))
  nil
  arc> (before 1
               even
               '(1 2 3 4))
  t
  arc> (before #\a #\n "banana")
  t
  arc> (before #\a #\n "banana" 2)
  nil
[fn]  (best f seq)
Maximizes comparator function 'f' throughout seq.

Examples:
  arc> (best >
             '(3 1 4 5 9 6))
  9
[fn]  (bestn n f seq)
Returns a list of the top 'n' elements of 'seq' ordered by 'f'.

Examples:
  arc> (bestn 3
              >
              '(3 1 4 5 9 6))
  (9 6 5)
  arc> (bestn 3
              <
              '(3 1 4 5 9 6))
  (1 3 4)
[mac] (between var expr within . body)
Like each but run 'within' between iterations.
[fn]  (bound x)
Does variable 'x' currently have a value?

Examples:
  arc> (do (= y 10)
           (bound 'y))
  t
[fn]  (break-thread th)
Politely tries to interrupt a thread of concurrently running expressions
when it's ready to be interrupted.
[fn]  (butlast x)
Returns all elements of 'x' except the last.
[fn]  (caar xs)
Equivalent to (car (car xs))
[fn]  (cache timef valf)
Converts a function 'valf' into a version that saves and reuses the results
of calls for a certain time. For greater configurability the caching time is
determined by calling 'timef' rather than directly passing in a number.
[fn]  (cadar xs)
Equivalent to (car (cdar xs)).
[fn]  (cadr xs)
Equivalent to (car (cdr xs)). Returns the second element of the list 'xs'
[fn]  (car xs)
Returns the first element of list 'xs'
[fn]  (carif x)
Returns the first element of the given list 'x', or just 'x' if it isn't a list.

Examples:
  arc> (carif '(1 2))
  1
  arc> (carif 3)
  3
[mac] (case expr . args)
Usage: (case expr test1 then1 test2 then2 ...)
Matches 'expr' to the first satisfying 'test' and runs the corresponding 'then' branch.
[mac] (caselet var expr . args)
Like case, but 'expr' is also bound to 'var' and available inside the 'args'.
[mac] (catch . body)
Runs 'body', but any call to (throw x) immediately returns x.
[fn]  (cdar xs)
Equivalent to (cdr (car xs)).
[fn]  (cddr xs)
Equivalent to (cdr (cdr xs)). Returns all elements of list 'xs' but the first two.
[fn]  (cdr xs)
Returns all elements of list 'xs' but the first
[mac] (check x test (o alt))
Returns `x' if it satisfies `test', otherwise returns 'alt' (nil if it's not provided).
[fn]  (coerce x totype . args)
Try to turn 'x' into a value of a different 'type'.
[fn]  (commonest seq)
Returns the most common element of 'seq' and the number of times it occurred
in 'seq'.

Examples:
  arc> (commonest '(b a n a n a))
  a
  arc> (commonest nil)
  nil
[fn]  (compare comparer scorer)
Creates a function to score two args using 'scorer' and compare them using
'comparer'. Often passed to sort.

Examples:
  arc> ((compare < len)
        "yz"
        "abc")
  t
  arc> ((compare < len)
        '(1 2 3)
        '(4 5))
  nil
[fn]  (complement f)
Returns a function that behaves as if the result of calling 'f' was negated.
For example, this is always true:
  ((complement f) a b) <=> (no (f a b))
[mac] (compose . args)
Takes a list of functions and returns a function that behaves as if all its
'args' were called in sequence.
For example, this is always true:
  ((compose f g h) a b c) <=> (f (g (h a b c))).
Be wary of passing macros to compose.
[fn]  (cons x xs)
Returns a new list with element 'x' added to the start of list 'xs'.
[fn]  (consif x xs)
Like cons on 'x' and 'xs' unless 'x' is nil.

Examples:
  arc> (consif 1 '(2 3))
  (1 2 3)
  arc> (consif nil '(2 3))
  (2 3)
[mac] (conswhen f x y)
Adds 'x' to the front of 'y' if 'x' satisfies test 'f'.

Examples:
  arc> (conswhen 
         [< _ 3]
         2
         '(3 4))
  (2 3 4)
  arc> (conswhen 
         [< _ 3]
         4
         '(5 6))
  (5 6)
[fn]  (copy x . args)
Creates a deep copy of 'x'. Future changes to any part of 'x' are guaranteed
to be isolated from the copy.
[fn]  (count test x)
Returns the number of elements of 'x' that pass 'test'.

Examples:
  arc> (count #\a "banana")
  3
  arc> (count odd
              '(1 2 3 4))
  2
  arc> (count odd:cadr
              (obj a 1 b 2))
  1
[fn]  (counts seq)
Returns a table with counts of each unique element in 'seq'.

Examples:
  arc> (counts '(b a n a n a))
  #hash((a . 3) (b . 1) (n . 2))
[fn]  (cut seq start (o end))
Extract a chunk of 'seq' from index 'start' (inclusive) to 'end' (exclusive). 'end'
can be left out or nil to indicate everything from 'start', and can be
negative to count backwards from the end.

Examples:
  arc> (cut '(a b c d e)
            2)
  (c d e)
  arc> (cut '(a b c d e)
            2
            -1)
  (c d)
  arc> (cut "abcde" 2 4)
  "cd"
[fn]  (date (o s (seconds)))
Converts time in seconds-since-epoch (now by default) into a list '(year month date).
[fn]  (datestring (o s (seconds)))
Converts time in seconds-since-epoch (now by default) into a string "YYYY-MM-DD".
[fn]  (dedup xs)
Returns list of elements in 'xs' with duplicates dropped.

Examples:
  arc> (dedup '(1 2 3 2 1))
  (1 2 3)
  arc> (dedup "abcba")
  (a b c)
[mac] (def name parms . body)
Defines a new function called 'name'. When called, the function runs
'body', parameterizing 'parms' with call arguments.
For more information see the tutorial: http://ycombinator.com/arc/tut.txt
Or come ask questions at http://arclanguage.org/forum
[mac] (def-isa name . body)
Declares a new predicate-based type that can be checked with 'isa'.
[mac] (defcall type-name parms . body)
Defines the calling function for type 'type-name.
    See also: defcoerce
[mac] (defcoerce to from parms . body)
Defines the coercion function from 'from to 'to.
    See also: set-coercer defcall
[mac] (defextend name args pred . body)
Extends an existing function to trigger only if 'pred' is non-nil.
[mac] (defmemo name parms . body)
Like def but defines a memoized function. See memo.
[fn]  (digit c)
Is 'c' a digit?
[mac] (do . args)
Evaluates each expression in sequence and returns the result of the
last expression.

Examples:
  arc> (do (prn "line 1")
           (prn "line 2")
           (prn "line 3"))
[mac] (do1 . args)
Like do, but returns the value of the first arg rather than the last.
[fn]  (dotted x)
Is 'x' an _improper_ list terminating in something other than nil?
Name comes from (cons 1 2) being printed with a dot: (1 . 1).
[mac] (down v init min . body)
Counts 'v' down from 'init' (inclusive) to 'min' (also inclusive), running
'body' with each value. Can also (break) and (continue) inside 'body'; see
for.
[fn]  (downcase s)
Converts 'x' to lowercase.
[mac] (drain expr (o eos nil))
Repeatedly evaluates 'expr' until it returns 'eos' (nil by default). Returns
a list of the results.
[mac] (each var expr . body)
Loops through expressions in 'body' with 'var' bound to each successive
element of 'expr'.
[fn]  (ellipsize str (o limit 80))
Trim string 'str' and append ellipses '...' if its length exceeds 'limit'.
[fn]  (empty x)
Is 'seq' an empty container? Usually checks 'seq's len.
[fn]  (ensure-dir path)
Creates the directory 'path' if it doesn't exist.
[fn]  (ero . args)
Like prn but prints to stderr rather than stdout.
[mac] (errsafe expr)
Runs 'expr' and returns the result, or nil if there were any errors.
[fn]  (even n)
Is n even?
[mac] (examples name . tests-and-expected-results)
Shows some example calls of a function as an enhancement of its docstring.
Usually provided immediately after a function docstring+definition, so it
isn't underfoot when it isn't needed.

Usage: (examples name-being-tested
          expr1
          expected-result1
          expr2
          expected-result2
          ...)

Expected results are optional. When provided, they can remind you when
documentation goes out of date. To avoid printing and checking them, use an _
wildcard. For example:

  (examples foo
    (foo x)
    _
    (foo y z)
    _)

Expected results are compared directly, without evaluation. For example:

  (def foo (a b c)
    (list a b c))

  (examples foo
    (foo 1 2 3)
    (1 2 3))            <-- no quote

If the result is an object that read can't handle, use valueof. For example:

  (examples foo
    (foo x)
    (valueof (obj a x)))
[fn]  (filechars name)
Outputs all characters in a file.
[fn]  (fill-table table data)
Populates 'table' with alternating keys and values in 'data'.
[fn]  (find test seq)
Returns the first element of 'seq' that satisfies `test'.

Examples:
  arc> (find 3 '(1 2 3 4))
  3
  arc> (find odd
             '(1 2 3 4))
  1
  arc> (find odd '(2 4 6))
  nil
[fn]  (firstn n xs)
Returns the first 'n' elements of 'xs'.

Examples:
  arc> (firstn 3 '(1 2))
  (1 2)
  arc> (firstn 3
               '(a b c d e))
  (a b c)
[fn]  (flat . x)
Flattens a list of lists.

Examples:
  arc> (flat '(1 2 nil 3 (4 (5))))
  (1 2 3 4 5)
[sym] (fn params . body)
Creates an anonymous function. See the tutorial: http://ycombinator.com/arc/tut.txt
[mac] (for var init test update . body)
Loops through expressions in 'body' as long as 'test' passes, first binding 'var' to 'init'. At the end of each iteration it runs 'update', which usually will modify 'var'.
Can also be terminated from inside 'body' by calling '(break)', or interrupt a single iteration by calling '(continue)'.
If you nest multiple loops with different 'var's like i and j, you can break out of either of them by calling (break-i), (break-j), etc.
Always returns nil.

Incompatibility alert: 'for' is different in Anarki from Arc 3.1. For Arc
3.1's behavior, use up. For more information, see CHANGES/for.

Examples:
  arc> (for i 1 (<= i 10) ++.i
         (pr i " "))
[mac] (forever . body)
Loops through the expressions in 'body' forever.
May still terminate by calling '(break)'.
[mac] (forlen var s . body)
Loops through the length of sequence 's', binding each element to 'var'.
[mac] (fromfile f . body)
Redirects standard input from the file 'f' within 'body'.
[mac] (fromstring str . body)
Runs 'body', reading from 'str' as stdin.
[fn]  (get i)
Returns a function to pass 'i' to its input.
Useful in higher-order functions, or to index into lists, strings, tables, etc.

Examples:
  arc> (get.2 '(1 2 3 4))
  3
  arc> (get!b (obj a 10 b 20))
  20
  arc> (get.9 sqrt)
  3
  arc> (map get.2
            '((a b c)
              (1 2 3)
              (p q r)))
  (c 3 r)
[fn]  (idfn x)
The identity function. Returns whatever is passed in.
[sym] (if test1 then1 test2 then2 ... else)
Version 1: (if test then) runs 'then' if 'test' passes.
Version 2: (if test then else) runs 'then' or 'else' depending on whether
'test' passes or fails.
Version 3: takes arbitrary numbers of alternating tests and expressions,
running the first expression whose test passes. Optionally might take an
'else' branch to run if none of the tests pass.
[mac] (iflet var expr . branches)
If 'expr' is not nil, binds 'var' to it before running the first branch.
Can be given multiple alternating test expressions and branches. The first
passing test expression is bound to 'var' before running its corresponding branch.

For examples, see aif.
[mac] (in x . choices)
Does 'x' match one of the given 'choices'?
[fn]  (insert-sorted test elt seq)
Inserts 'elt' into a sequence 'seq' that is assumed to be sorted by 'test'.

Examples:
  arc> (insert-sorted >
                      5
                      '(10 3 1))
  (10 5 3 1)
  arc> (insert-sorted >
                      5
                      '(10 5 1))
  (10 5 5 1)
[mac] (insort test elt seq)
Like insert-sorted but modifies 'seq' in place'.
[mac] (insortnew test elt seq)
Like insort, but only inserts 'elt' if it doesn't exist.

Examples:
  arc> (ret x '(10 3 1)
         (insortnew > 5 x))
  (10 5 3 1)
  arc> (ret x '(10 5 1)
         (insortnew > 5 x))
  (10 5 1)
[fn]  (int x (o b 10))
Converts 'x' into an integer, optionally in the given base 'b' (decimal by default).
[fn]  (intersperse x ys)
Inserts 'x' between the elements of 'ys'.

Examples:
  arc> (intersperse 1
                    '(a b (c d) e))
  (a 1 b 1 (c d) 1 e)
  arc> (intersperse nil
                    '(1 2 3))
  (1 nil 2 nil 3)
[fn]  (is x y)
Are 'x' and 'y' identical?
[fn]  (isa x y)
Is 'x' of type 'y'?
[fn]  (iso a b)
Are 'x' and 'y' equal-looking to each other? Non-atoms like lists and tables can contain
the same elements (be *isomorphic*) without being identical.
[fn]  (join . args)
Concatenates/appends its arguments into a new list.

Examples:
  arc> (join '(1 2)
             nil
             '(3 4))
  (1 2 3 4)
[mac] (jtime expr)
Like time but always returns 'ok'.
[fn]  (keep test seq)
Returns all elements of 'seq' for which 'test' passes.

Examples:
  arc> (keep odd
             '(1 2 3 4 5))
  (1 3 5)
  arc> (keep 3
             '(1 2 3 4 5))
  (3)
  arc> (keep 3
             '(1 3 1 3 1))
  (3 3)
  arc> (keep [in _ #\a #\b]
             "banana")
  "baaa"
[fn]  (keys h)
Returns list of keys in table 'h'.
[fn]  (kill-thread th)
Abruptly interrupt a thread of concurrently running expressions given its id.
[fn]  (last xs)
Returns the last element of 'xs'.

Examples:
  arc> (last '(1 2 3))
  3
[fn]  (lastcons xs)
Returns the absolute last link of list 'xs'. Save this value to efficiently
append to 'xs'.
[fn]  (lastn n xs)
Returns the last 'n' elements of 'xs'.
[fn]  (len q)
Computes the size of a list, string, hash table or other user-defined type.

Examples:
  arc> (len '(1 2 3))
  3
  arc> (len "abcd")
  4
  arc> (len (obj a 1 b 2))
  2
[fn]  (len< x n)
Is len of 'x' less than 'n'?

Examples:
  arc> (len> '(1 2 3) 2)
  t
  arc> (len> (obj a 1 b 2)
             3)
  nil
[fn]  (len> x n)
Is len of 'x' greater than 'n'?
[mac] (let var val . body)
Like with but with just one binding.
For example, (let x 1
               (+ x 1))
             => (with (x 1)
                  (+ x 1))
             => 2
[mac] (let-or var expr else . body)
Like iflet but provides an immediate escape hatch first if 'expr' is nil.
Use let-or for iflet forms with just one test, many things to do if it
passes, and a simple expression or error if it fails.

Examples:
  arc> (let-or x (+ 3 4) (err "Error in adding 3 and 4")
         ++.x
         (+ x 3))
  11
[fn]  (letter c)
Is 'c' a letter?
[fn]  (listtab al)
Converts association list 'al' of (key value) pairs into a table. Reverse of
tablist.

Examples:
  arc> (listtab '((a 1) (b 2)))
  #hash((a . 1) (b . 2))
[fn]  (load file)
Successively reads and runs all expressions in 'file'.
[fn]  (load-table file)
Reads an association list from 'file' and turns it into a table.
[fn]  (load-tables file)
Reads multiple association lists from 'file' and returns a corresponding list
of tables.
[mac] (loop withses . body)
Like 'with', but the body can also be rerun with new bindings by calling 'recur'.
Often a more readable alternative to rfn or afn.
For example, this prints numbers ad infinitum:
  (loop (x 1)
    (prn x)
    (recur (+ x 1)))
[fn]  (map f . seqs)
Successively applies corresponding elements of 'seqs' to function 'f'.
Generalizes map1 to functions with more than one argument.

Examples:
  arc> (map cdr
            '((1) (2 3) (4 5)))
  (nil (3) (5))
  arc> (map [list _ (* _ 10)]
            '(1 2 3))
  ((1 10) (2 20) (3 30))
  arc> (map +
            '(1 2 3)
            '(4 5 6))
  (5 7 9)
  arc> (map (fn (c n)
              (coerce (+ n
                         (coerce c 'int))
                      'char))
            "abc"
            '(0 2 4))
  "adg"
  arc> (map min "bird" "elephant")
  "bied"
[fn]  (map1 f xs)
Returns a list containing the result of function 'f' applied to every element of 'xs'.

Examples:
  arc> (map1 cdr
             '((1) (2 3) (4 5)))
  (nil (3) (5))
  arc> (map1 [list _ (* _ 10)]
             '(1 2 3))
  ((1 10) (2 20) (3 30))
[fn]  (mappend f . args)
Like map followed by append.

Examples:
  arc> (mappend cdr
                '((1) (2 3) (4 5)))
  (3 5)
  arc> (mappend [list _ (* _ 10)]
                '(1 2 3))
  (1 10 2 20 3 30)
[fn]  (max . args)
Returns the greatest of 'args'.
[fn]  (med ns (o test >))
Returns the median of a list of numbers 'ns' according to the comparison 'test'.
[fn]  (mem test seq)
Returns suffix of 'seq' after the first element to satisfy 'test'.
This is the most reliable way to check for presence, even when searching for nil.

Examples:
  arc> (mem odd
            '(2 4 5 6 7))
  (5 6 7)
  arc> (mem 6
            '(2 4 5 6 7))
  (6 7)
[fn]  (memo f)
Turns function 'f' into a _memoized_ version that also stores results returned
by args passed in, so that future calls with the same inputs can save work.
[fn]  (memtable (o keys nil) (o val t))
Turns a list into a table indicating membership of all elements.
[fn]  (min . args)
Returns the least of 'args'.
[fn]  (mismatch s1 s2)
Returns the first index where 's1' and 's2' do not match.

Examples:
  arc> (mismatch '(1 2 3)
                 '(1 2 4))
  2
  arc> (mismatch "abc" "acc")
  1
  arc> (mismatch "abc" "abc")
  nil
[fn]  (most f seq)
Like best, but function 'f' is a scorer for each element rather than a
comparator between elements.

Examples:
  arc> (most len
             '("cat" "bird" "dog"))
  "bird"
  arc> (most abs
             '(3 -10 5))
  -10
[fn]  (multiple x y)
Is 'x' a multiple of 'y'?
[mac] (n-of n expr)
Runs 'expr' 'n' times, and returns a list of the results.

Examples:
  arc> (n-of 5 "a")
  (a a a a a)
  arc> (w/instring ins "abcdefg"
         (n-of 5 readc.ins))
  (a b c d e)
[mac] (nand . args)
Computes args until one of them fails, then returns t.
Returns nil if none of the args fails.
[fn]  (nappend l item)
Appends item to list, then returns list.
[fn]  (nearest n quantum)
Like round but generalized to arbitrary units.
[fn]  (njoin a b)
Concatenates/appends second list to first, then returns entire result.
[fn]  (no x)
Is 'x' nil? Sometimes we say A passes if it's non-nil, in which case no.A is said to fail.
[mac] (noisy-each n var val . body)
Like each but print a progress indicator every 'n' iterations.
[fn]  (nonwhite c)
Is 'c' a non-whitespace char?
[mac] (nor . args)
Computes args until one of them passes, then returns nil.
Returns t if none of the args passes.
[fn]  (nthcdr n xs)
Returns all but the first 'n' elements of 'xs'.

Examples:
  arc> (nthcdr 0 '(1 2 3))
  (1 2 3)
  arc> (nthcdr 1 '(1 2 3))
  (2 3)
  arc> (nthcdr 2 '(1 2 3))
  (3)
  arc> (nthcdr 10
               '(1 2 3))
  nil
[fn]  (number n)
Is 'n' a number?
[mac] (obj . args)
Creates a table out of a list of alternating keys and values.
[fn]  (odd n)
Is n odd?
[mac] (on var s . body)
Like each, but also maintains a variable calles 'index' counting the iterations.
[fn]  (only f)
Transforms a function 'f' info a variant that runs only if its first arg is
non-nil.

Examples:
  arc> (only.+ 1 2 3)
  6
  arc> (only.+ nil 1 2 3)
  nil
  arc> (only.+)
  nil
[mac] (or . args)
Stops at the first argument to pass, and returns its result.
[fn]  (orf . fns)
Returns a function which calls all the functions in 'fns' on its args, and
ors the results. ((orf f g) x y) <=> (or (f x y) (g x y))
[fn]  (pair xs (o f list))
Splits the elements of 'xs' into buckets of two, and optionally applies the
function 'f' to them.

Examples:
  arc> (pair '(a b c d))
  ((a b) (c d))
  arc> (pair '(a b c d e))
  ((a b) (c d) (e))
  arc> (pair '(1 2 3 4) +)
  (3 7)
  arc> (pair '(10 2 3 40 50 6)
             max)
  (10 40 50)
[mac] (pipe-to dest . body)
Redirects stdout for 'body' into stdin of 'dest'.
[mac] (point name . body)
Like do, but may be exited by calling 'name' from within 'body'.
[mac] (pop place)
Opposite of push: removes the first element of the sequence at 'place' and returns it.
[fn]  (pos test seq (o start 0))
Returns the index of the first element of 'seq' matching 'test', starting
from index 'start' (0 by default).

Examples:
  arc> (pos 'c '(a b c d))
  2
  arc> (pos 'x '(a b c d))
  nil
  arc> (pos #\b "abcba")
  1
  arc> (pos #\b "abcba" 2)
  3
  arc> (pos odd
            '(2 4 5 6 7))
  2
[fn]  (pr . args)
Prints all its 'args' to screen. Returns the first arg.
[fn]  (prall elts (o init "") (o sep ", "))
Prints elements of list 'elts' prefixed with 'init' and separated by 'sep'.
Returns 'elts'.
[mac] (prf str . args)
Prints 'str' interpolating #exprs and replacing instances of ~ with
successive elements of 'args'.

Examples:
  arc> (let x 3
         (prf "the square of #x is ~."
           9))
[fn]  (prn . args)
Prints all its 'args' to screen followed by a newline. Returns the first arg.
[fn]  (prrn . args)
Like prn, but prints both carriage return and newline, usually because the HTTP
protocol requires them.
[fn]  (prs . args)
Prints elements of list 'args' separated by spaces.
[fn]  (prt . args)
Like pr, but doesn't print nils.
[mac] (pull test place)
Removes all elements from 'place' that satisfy 'test'.
[fn]  (punc c)
Is 'c' a punctuation char?
[mac] (push x place)
Adds 'x' to the start of the sequence at 'place'.
[mac] (pushnew x place)
Like push but first checks if 'x' is already present in 'place'.
[mac] (q-with . args)
Returns an Arc expression which will hygienically run a given piece
of Arc code with the results of some given Arc expressions.

For example, n-of usually generates code that looks up the caller's local variables rev, <, +, and cons. This alternative definition always uses the global bindings regardless of whether local bindings exist at the call site:

  (mac n-of (n expr)
    (q-with n `(fn (break recur) ,n)
            expr `(fn (break recur continue) ,expr)
      (let a nil
        (repeat (n break recur) (push (expr break recur continue) a))
        rev.a)))
[mac] (rand-choice . exprs)
Runs one of the given 'exprs' at random and returns the result.
[fn]  (rand-elt seq)
Returns a random element of 'seq'. See also rand-choice.
[fn]  (rand-string n)
Generates a random string of letters and numbers.
[fn]  (range start end)
Returns the list of integers from 'start' to 'end' (both inclusive).

Examples:
  arc> (range 0 10)
  (0 1 2 3 4 5 6 7 8 9 10)
[fn]  (range-bounce i max)
Munges index 'i' in slices of a sequence of length 'max'. First element starts
 at index 0. Negative indices count from the end. A nil index denotes the end.
[fn]  (read (o x (stdin)))
Reads a single expression from string or stream 'x'. Returns the uninterned
symbol stored as the global value of 'eof' if there's nothing left to read.
[fn]  (read-table (o i (stdin)))
Reads an association list from a stream 'i' (stdin by default) and turns it
into a table.
[fn]  (readall src)
Like readfile, but can also accept a string 'src'.
[fn]  (readfile name)
Slurps the entire contents of file 'name' using read and returns the
expressions  as a list.
[fn]  (readfile1 name)
Returns the first expression read from file 'name'.
[fn]  (readline (o str (stdin)))
Reads a string terminated by a newline from the stream 'str'.
[fn]  (readlines (o str (stdin)))
Slurps contents of stream 'str' as a list of lines.
[fn]  (readstring1 s)
Reads a single expression from string 's'. Returns the uninterned symbol
stored as the global value of 'eof' if there's nothing left to read.
[fn]  (real x)
Converts 'x' into a real number.
[fn]  (reclist f xs)
Calls function 'f' with successive cdrs of 'xs' until one of the calls passes.

Examples:
  arc> (reclist [caris _ 'b]
                '(a b c))
  t
  arc> (reclist [caris _ 'd]
                '(a b c))
  nil
  arc> (reclist [if (is 2 len._) _]
                '(a b c d))
  (c d)
[fn]  (recstring test s (o start 0))
Calls function 'test' with successive characters in string 's' until one of the calls passes.
[mac] (redef name parms . body)
Defines a new function like def, but doesn't warn if 'name' already exists.
[fn]  (reduce f xs)
Accumulates elements of 'xs' using binary function 'f'.

Examples:
  arc> (reduce +
               '(1 2 3 4 5))
  15
  arc> (reduce +
               '("a" "b" "c"))
  "abc"
  arc> (reduce / '(1 2 3))
  1/6
[fn]  (rem test seq)
Returns all elements of 'seq' except those satisfying 'test'.

Examples:
  arc> (rem odd
            '(1 2 3 4 5))
  (2 4)
  arc> (rem 3
            '(1 2 3 4 5))
  (1 2 4 5)
  arc> (rem #\d "abcde")
  "abce"
  arc> (rem [in _ #\a #\b]
            "abcde")
  "cde"
[fn]  (rep x)
Returns the contents of a user-defined tagged type object.
[mac] (repeat n . body)
Runs 'body' expression by expression 'n' times.
[mac] (ret var val . body)
Like let, but returns 'val' rather than the value of the final form in 'body'.
[fn]  (retrieve n f xs)
Returns the first 'n' elements of 'xs' that satisfy 'f'.

Examples:
  arc> (retrieve 3
                 odd
                 '(1 2 3 4 5 6 7 8))
  (1 3 5)
  arc> (retrieve 3
                 odd
                 '(2 4 6 8))
  nil
[fn]  (rev x)
Returns a list containing the elements of 'xs' back to front.

Examples:
  arc> (rev '(1 (2 3) 4))
  (4 (2 3) 1)
[mac] (rfn name parms . body)
Like fn but permits the created function to call itself recursively as the given 'name'.
[mac] (rotate . places)
Like swap but for more than two places.
For example, after (rotate place1 place2 place3), place3 is moved to place2,
place2 to place1, and place1 to place3.
[fn]  (round n)
Approximates a fractional value to the nearest integer.
Exact halves are rounded down to the lower integer.
Negative numbers are always treated exactly like their positive variants
barring the sign.
[fn]  (roundup n)
Like round but halves are rounded up rather than down.
[fn]  (rreduce f xs)
Like reduce but accumulates elements of 'xs' in reverse order.

Examples:
  arc> (rreduce +
                '(1 2 3 4 5))
  15
  arc> (rreduce /
                '(1 2 3))
  3/2
[fn]  (safe-load-table filename)
Loads a table from 'filename', or an empty table on any errors.
[fn]  (save-table h file)
Writes table 'h' to 'file'.
[mac] (set . args)
Sets each place in 'args' to t.
[fn]  (set-coercer to from fun)
Makes 'fun the coercion function from 'from to 'to.
    See also: defcoerce
[fn]  (shl n m)
Shifts the binary twos-complement representation of 'n' left by 'm' bits.
[fn]  (shr n m)
Shifts the binary twos-complement representation of 'n' right by 'm' bits.
[fn]  (single x)
Is 'x' a list with just one element?

Examples:
  arc> (single 1)
  nil
  arc> (single 'nil)
  nil
  arc> (single '(1))
  t
  arc> (single '(1 2))
  nil
[fn]  (some test seq)
Does at least one element of 'seq' satisfy 'test'?
[fn]  (sort test seq)
Orders a list 'seq' by comparing its elements using 'test'.

Examples:
  arc> (sort <
             '(3 0 10 -7))
  (-7 0 3 10)
  arc> (sort (fn (a b)
               (< len.a len.b))
             '("horse" "dog" "elephant" "cat"))
  (dog cat horse elephant)
  arc> (sort > "Test word")
  "wtsroedT "
[fn]  (sort-by-commonest seq (o f idfn))
Reorders 'seq' with most common elements first.
[fn]  (split seq pos)
Partitions 'seq' at index 'pos'.

Examples:
  arc> (split '(a b c) 0)
  (nil (a b c))
  arc> (split '(a b c) 1)
  ((a) (b c))
  arc> (split '(a b c) 2)
  ((a b) (c))
  arc> (split '(a b c) 3)
  ((a b c) nil)
  arc> (split '(a b c) 4)
  ((a b c) nil)
[fn]  (split-at s delim)
Partitions string s at first instance of delimiter, dropping delimiter.
[fn]  (sref tem v k)
Sets position 'indices' in 'aggregate' (which might be a list, string, hash
table, or other user-defined type) to 'value'.

Examples:
  arc> (ret x '(1 2 3)
         (sref x 4 1))
  (1 4 3)
  arc> (ret x "abc"
         (sref x #\d 0))
  "dbc"
  arc> (ret x (obj a 1 b 2)
         (sref x 3 'd))
  #hash((a . 1) (b . 2) (d . 3))
[fn]  (string . args)
Converts all 'args' into strings and concatenates the results.
[fn]  (subst old new seq)
Returns a copy of 'seq' with all values of 'old' replaced with 'new'.
[fn]  (sum f xs)
Returns total of all elements in (map f xs).

Examples:
  arc> (sum idfn
            '(1 2 3 4))
  10
  arc> (sum len
            '("this" "is" "a" "sentence"))
  15
  arc> (sum cadr
            (obj a 1 b 2 c 3))
  6
  arc> (sum int "abc")
  294
[mac] (swap place1 place2)
Exchanges the values of 'place1' and 'place2'.
[fn]  (sym x)
Converts 'x' into a symbol.
[fn]  (tablist h)
Converts table 'h' into an association list of (key value) pairs. Reverse of
listtab.

Examples:
  arc> (listtab (map rev
                     (tablist (obj a 1 b 2))))
  #hash((1 . a) (2 . b))
[fn]  (testify x)
Turns an arbitrary value 'x' into a predicate function to compare with 'x'.
[mac] (thread . body)
Concurrently run expressions in 'body', returning an id that can be used to
check their progress, interrupt them, etc.

Creating multiple threads doesn't currently cause arc to use more than one
processor. See http://docs.racket-lang.org/guide/concurrency.html. Programs
will still speed up while waiting for keyboard input, reading/writing files,
or communicating over the network.
[mac] (time expr)
Runs 'expr', then prints the amount of time it took to do so.
[mac] (time10 expr)
Like time but runs 'expr' 10 times.
[mac] (tofile f . body)
Redirects stdout to the file 'f' within 'body'.
[mac] (tostring . body)
Runs 'body' then collect all output to (stdout) and return it as a string.
[mac] (trav x . fs)
Applies each function in 'fs' to 'x', letting the functions recurse on parts
of 'x' by calling 'self'.

Examples:
  arc> (accum acc
         (trav '(1 2 3 4)
           [acc _]
           [self cdr._]))
  ((1 2 3 4) (2 3 4) (3 4) (4))
[fn]  (trues f xs)
Returns (map f xs) dropping any nils.

Examples:
  arc> (trues cdr
              '((1 2) (3) (4 5)))
  ((2) (5))
[fn]  (tuples xs (o n 2))
Splits 'xs' up into lists of size 'n'. Generalization of pair.

Examples:
  arc> (tuples '(1 2 3 4 5)
               1)
  ((1) (2) (3) (4) (5))
  arc> (tuples '(1 2 3 4 5)
               2)
  ((1 2) (3 4) (5))
  arc> (tuples '(1 2 3 4 5)
               3)
  ((1 2 3) (4 5))
[fn]  (type x)
Returns the type of 'x', even if 'x' is a user-defined tagged-type.
[fn]  (union f xs ys)
Merges 'xs' and 'ys', while filtering out duplicates using 'f'. Ordering is
not preserved.

Examples:
  arc> (union is
              '(1 2 3)
              '(2 3 4))
  (1 2 3 4)
  arc> (union is "ab" "banana")
  "abnn"
  arc> (union (fn (a b)
                (is (mod a 10)
                    (mod b 10)))
              '(1 2 3)
              '(13 24 35))
  (1 2 3 24 35)
[mac] (unless test . body)
Opposite of when; runs multiple expressions when 'test' is nil.
[mac] (until test . body)
Like while, but negates 'test'; loops through 'body' as long as 'test' fails.
[mac] (up v init max . body)
Counts 'v' up from 'init' (inclusive) to 'max' (also inclusive), running
'body' with each value. Can also (break) and (continue) inside 'body'; see
for.

Examples:
  arc> (up i 1 10
         (pr i " "))
[fn]  (upcase s)
Converts 'x' to uppercase.
[fn]  (vals h)
Returns list of values in table 'h'.
[mac] (w/appendfile var name . body)
Opens file 'name' into stream 'var' to write to it in 'body'.
Unlike w/outfile, appends to existing contents of the file.
Reliably closes the file when it's done.
[mac] (w/bars . body)
Assumes each expression in 'body' will print something, and intersperses them
with '|'s.
[mac] (w/infile var name . body)
Opens file 'name' into stream 'var' to read from it in 'body'.
Reliably closes the file when it's done.
See also read.
[mac] (w/instring var str . body)
Creates a stream 'var' to read from 'str' in 'body'.
Reliably closes the stream when it's done.
[mac] (w/outfile var name . body)
Opens file 'name' into stream 'var' to write to it in 'body'.
Reliably closes the file when it's done.
[mac] (w/outstring var . body)
Create an in-memory string and write to it in 'body'.
The contents of the string can be accessed by calling 'inside'.
[mac] (w/socket var port . body)
Creates a stream 'var' to listen to and read from 'port'.
Reliably closes the stream when it's done.
[mac] (w/stdin str . body)
Redirects reads from (stdin) inside 'body' using calls to read, etc. to
read from the stream 'str'.
[mac] (w/stdout str . body)
Redirects writes to (stdout) inside 'body' using calls to write, prn,
etc. to write to the stream 'str'.
[mac] (w/table var . body)
Runs 'body' to add to table 'var' and finally return it.
[mac] (w/uniq names . body)
Assigns a set of variables to unique symbols.
Useful for avoiding name capture in macros; see the tutorial: http://ycombinator.com/arc/tut.txt
[fn]  (walk seq f)
Calls function 'f' on each element of 'seq'. See also map.
[fn]  (warn msg . args)
Displays args to screen as a warning.
[mac] (when test . body)
Like if, but can take multiple expressions to run when 'test' is not nil.
Can't take an 'else' branch.
[mac] (whenlet var expr . body)
Like when but also puts the value of 'expr' in 'var' so 'body' can access it.
[mac] (while test . body)
Loops through the expressions in 'body' as long as 'test' passes.
Can also terminate by calling '(break)', or terminate just one iteration by calling
'(continue)'.
[mac] (whiler var expr end . body)
Repeatedly binds 'var' to 'expr' and runs 'body' until 'var' matches 'end'.
[mac] (whilet var test . body)
Like while, but successive values of 'test' are bound to 'var'.
[fn]  (whitec c)
Is 'c' a whitespace char?
[mac] (wipe . args)
Sets each place in 'args' to nil.
[mac] (with parms . body)
Evaluates all expressions in 'body' under the bindings provided in 'parms'.
Returns value of last expression in 'body'.
For example, (with (x 1 y 2)
               (+ x y))
             => 3
[mac] (withs parms . body)
Like with, but binding for a variable can refer to earlier variables.
For example, (withs (x 1 y (+ x 1))
               (+ x y))
             => 3
[fn]  (write-table h (o o (stdout)))
Writes table as an association list to stream 'o' (stdout by default).
[fn]  (writefile val name)
Outputs 'val' to file 'name' using write.
[mac] (zap op place . args)
Replaces 'place' with (apply op place args)

Documented in lib/app.arc

[fn]  (admin u)
Does user 'u' possess administrator privileges for the site?
[mac] (defopl name parm . body)
Like defop, but requires a logged in user.
[fn]  (get-user req)
Gets the user id string associated with 'req'.
Returns nil if no logged-in user.
[fn]  (goodname str (o min 1) (o max nil))
Is 'str' a valid username?
[fn]  (set-pw user pw)
Updates password for 'user'.
[mac] (uform user req after . body)
Like aform but also authenticates that the form is submitted by 'user'.
[mac] (urform user req after . body)
Like arform but also authenticates that the form is submitted by 'user'.

Documented in lib/client.arc

[mac] (defreq name url (o fields) (o method "GET") (o cookies))
Defines a function 'name' that performs a HTTP request to 'url', whose query string is 'fields' with the 'values' passed 'name'.
[fn]  (get-url url)
Submit a HTTP GET request to 'url' and return the body of the response.
[fn]  (mkreq url (o querylist) (o method "GET") (o cookies) (o headers))
Submit a HTTP request with 'url'. 'querylist' contains field-value pairs, hence its length must be even.
[fn]  (post-url url (o querylist))
Submit a HTTP POST request to 'url' and return the body of the response. 'querylist' contains field-value pairs, hence its length must be even.
[fn]  (slurp-body (o s (stdin)))
Read remaining lines from port.
[fn]  (slurp-header (o s (stdin)))
Read each line from port until a blank line is reached.

Documented in lib/collect.arc

[mac] (collect expr . guards)
Creates a list of data based on a sort of 'set builder' notation.
https://en.wikipedia.org/wiki/List_comprehension

Examples:
  arc> (collect i
         (for i from 1 to 3))
  (1 2 3)
  arc> (collect (* i 2)
         (for i from 1 to 3))
  (2 4 6)
  arc> (collect (list i j)
         (for i from 1 to 3)
         (for j from 1 to 3)
         (if (< i j)))
  ((1 2) (1 3) (2 3))

Documented in lib/files.arc

[fn]  (canonical-path path)
builds an absolute file path from the root anarki directory
[fn]  (canonical-path-ts path)
builds a canonical path with a trailing separator
[fn]  (cd path)
Changes the current directory.
[fn]  (cp src dst)
Copies the file `src' to `dst'.
[fn]  (dir-tree path)
Returns a directory tree from the given path.
[fn]  (file-join . parts)
Joins `parts' into a path string.
[fn]  (file-perms path)
Returns a list of the effective file permssions of `path'.
[fn]  (file-size path)
Returns the size, in bytes, of a file `path'.
[fn]  (mtime path)
Returns the modification time of the file or directory `path' in
    seconds since the epoch.
[fn]  (mv src dst)
Moves the file or directory `src' to `dst'.
[fn]  (pwd)
Returns the current directory.
[fn]  (qualified-path path)
Returns the fully-qualified path of a possibly relative `path'.

Documented in lib/help.arc

[mac] (help (o name (quote help)))
Prints the documentation of the given symbol. To use, type
    (help symbol) ; you may also use (help "string") to search
    all documentation for that string.
[fn]  (helpsearch str)
Prints all symbols whose documentation matches or partly matches `str'.
[fn]  (helpsearch-core str)
Returns a list of symbols whose documentation matches or partly matches 
    `str'.
[fn]  (helpstr name (o verbose t))
Returns a help string for the symbol `name'.
[fn]  (ppr-source name)
Pretty-prints the source code of the function `name'.
    Is a function, so `name' is evaluated.
    See also: src
[mac] (src name)
Pretty prints the source code of the function `name'. 
    Is a macro, so `name' is not evaluated.
    See also: ppr-source

Documented in lib/html.arc

[fn]  (blank-url)
s.gif

Documented in lib/ns.arc

[fn]  (embed-ns/bare-bones result)
Makes a `"lib/ns.rkt"` expression out of the literal value
    `result' by embedding it inside a procedure call. This is
    necessary so that Racket doesn't translate it into immutable
    syntax and back.
[fn]  (global-arcracket global)
Converts an Arc global variable name (a symbol) into the
    corresponding Racket top-level variable name.
[fn]  (global-racketarc global)
Converts a Racket top-level variable name (a symbol) into the name
    the variable is visible as from Arc.
[fn]  (instantiate-rmodule rmodule)
Instantiates a Racket module by first delving into its internal
    Arc representation (a combination of a module path and an example
    namespace which has the module attached on that path), and then
    requiring that path in that namespace.
[fn]  (make-bare-bones-rmodule racket-module-body)
Makes a Racket module based on `"lib/ns.rkt"` and the given
    Racket list of top-level module expressions. We create the module
    by evaluating a Racket `(module ...) form in the main namespace of
    Arc. The resulting module will have a gensym for a name (even if
    Racket's `current-module-declare-name' would have overridden
    that), and Racket's `compile-enforce-module-constants' parameter
    will be `#f' while the module is being compiled, so that its
    module-level variables can be redefined or assigned to later on.
[fn]  (ns-get var (o ns current-ns))
Gets a variable from a namespace by evaluating it in Racket.
      Actually, it's sent through Racket's 'expand-to-top-form so that
      we can use the core #%top form if necessary rather than relying
      on the namespace itself to have one.
[fn]  (ns-ownspace-set var val (o ns current-ns))
Sets a top-level variable in a namespace without changing the
      corresponding identifier mapping to point to that variable.
[fn]  (ns-set var val (o ns current-ns))
Sets a variable in a namespace using Racket's 'set!.
[fn]  (ns-set-own var val (o ns current-ns))
Sets a top-level variable in a namespace and changes the
      corresponding identifier mapping to point to that variable.
[fn]  (ns-set-renamer observing-var canonical-var (o canonical-ns current-ns))
Changes an identifier mapping in a namespace to point to a
      rename transformer.
[fn]  (rns-get var (o rns current-rns))
Gets a variable from a Racket namespace by evaluating it in
      Racket. Actually, it's sent through Racket's 'expand-to-top-form
      so that we can use the core #%top form if necessary rather than
      relying on the namespace itself to have one.
[fn]  (rns-ownspace-set var val (o rns current-rns))
Sets a top-level variable in a Racket namespace without changing
      the corresponding identifier mapping to point to that
      variable.
[fn]  (rns-set var val (o rns current-rns))
Sets a variable in a Racket namespace using Racket's 'set!.
[fn]  (rns-set-own var val (o rns current-rns))
Sets a top-level variable in a Racket namespace and changes the
      corresponding identifier mapping to point to that variable.
[fn]  (rns-set-renamer observing-var canonical-var (o canonical-rns current-rns))
Changes an identifier mapping in a Racket namespace to point to
      a rename transformer.
[mac] (w/module module . body)
Evaluates `module' at expansion time and uses Racket's
    `local-require' to require the Arc variables of the resulting
    module in a local scope for `body'.
[mac] (w/rmodule rmodule . body)
Evaluates `rmodule' at expansion time and uses Racket's
    `local-require' to require the resulting module in a local
    scope for `body'.

Documented in lib/ppr.arc

[fn]  (len-dotted x)
len for dotted lists

Examples:
  arc> (len-dotted '(1 2 3))
  3
  arc> (len-dotted '(1 2 . 3))
  3
[fn]  (ppr . l)
Pretty print. This function displays arc code with proper
    indenting and representation of syntax.
[fn]  (ppr-main x (o col 0) (o noindent nil))
Recursive main body of the ppr function.
[fn]  (print x)
Print an expression on one line, replacing quote, unquote,
    quasiquote, unquote-splicing, and make-br-fn with their respective symbols.
[fn]  (print-spaced xs)
Print the expressions in the list separated by spaces.
[fn]  (sp (o n 1))
Print a number of spaces.

Documented in lib/queue.arc

[fn]  (deq qq)
Delete last element from queue 'qq' and return it.
[fn]  (enq obj qq)
Insert 'obj' into queue 'qq'.
[fn]  (enq-limit val q (o limit 1000))
Like enq, but never let the queue 'q' grow larger than 'limit'.
[fn]  (queue)
A queue is like a list but with efficient insertion in one end and deletion
in the other.

Documented in lib/re.arc

[fn]  (pre s)
Compiles 's' to a regular expression using a Perl-like syntax. See also re.
[fn]  (re s)
Compiles 's' to a regular expression. See also pre.
[fn]  (re-match pat i)
Returns the first match of 'pat' in 'i'.
[fn]  (re-match* pat i)
Returns each match of 'pat' in 'i'.
[fn]  (re-pos pat i)
Returns the start and end position of the first match of 'pat' in 'i'.
[fn]  (re-subst pat i sub)
Returns 'i' where first match of 'pat' has been replaced with 'sub'.

Documented in lib/require.arc

[fn]  (require files)
Loads `file(s)' if it/they has not yet been `require'd.  (Can be fooled by changing
    the name ((require "foo.arc") as opposed to (require "./foo.arc")), but
    this should not be a problem.)
    See also load.

Documented in lib/spliceable-list.arc

[fn]  (splice l)
Clears up to the last n items of a spliceable-list defined with a suffix
length of n, and returns everything else.

Examples:
  arc> (splice (spliceable-list 3))
  nil
  arc> (splice (spliceable-list 3
                                '(1)))
  nil
  arc> (splice (spliceable-list 3
                                '(1 2)))
  nil
  arc> (splice (spliceable-list 3
                                '(1 2 3)))
  nil
  arc> (splice (spliceable-list 3
                                '(1 2 3 4)))
  (1)
[fn]  (spliceable-list n (o init))
Create a spliceable list with a constant suffix length of n. A spliceable
list is a special data structure that efficiently supports the following
operations:

1. Destructively appending items using nappend.
2. Returning the last n items appended using suffix if there are at least
n items to return.
3. Dropping the last n items appended, and returning everything else. splice
[fn]  (suffix l)
Computes the last n elements of l -- as long as there are at least that many.

Examples:
  arc> (suffix 3 '(1))
  nil
  arc> (suffix 3 '(1 2))
  nil
  arc> (suffix 3 '(1 2 3))
  (1 2 3)
  arc> (suffix 3
               '(1 2 3 4))
  (2 3 4)

Documented in lib/srv.arc

[mac] (defop name parm . body)
Handles url /'name', giving 'body' access to the request in the variable
named by 'parm'. 'body' should output the response to stdout.
For example, to respond to a url called /hello,
  (defop hello req
    (prn "hello")
[mac] (defopr name parm . body)
Like defop, handles url /'name' but instead of printing response to
stdout, returns a url to redirect requests to after processing.

Documented in lib/streams.arc

[mac] (delay expr)
delays the evaluation of expr
[fn]  (force delayed-fn)
evaluates a delayed expression
[fn]  (integers-from n)
creates the infinite stream of integers starting from n
[mac] (lazy-cons first second-expr)
create a lazy stream that delays evaluation of second-expr
[fn]  (lazy-gen f)
turn a generator function f into a lazy stream
[fn]  (lazy-keep test xs)
lazily keep elements of xs satisfying test
[fn]  (lazy-map f xs)
lazily maps f over the stream xs
   invariant: (as cons (lazy-map f lazy-stream)) == (map f lazy-stream)
[fn]  (lazy-range a b)
generates a stream of the range [a,b]
[fn]  (lazy-rem test xs)
lazily rem elements of xs satisfying test

Documented in lib/strings.arc

[fn]  (begins seq pat (o start 0))
Like headmatch but with 'seq' and 'pat' reversed.
[fn]  (blank s)
Is 's' empty or all whitespace?
[fn]  (endmatch pat seq)
Does 'seq' end with 'pat'?
[fn]  (headmatch pat seq (o start 0))
Does 'seq' contain 'pat' at index 'start'?
[fn]  (lines s)
Breaks up a multi-line string into lines, respecting either newlines or CRLF
sequences.
[fn]  (multisubst pairs seq)
For each (old new) pair in 'pairs', substitute 'old' with 'new' in 'seq'.
[fn]  (nonblank s)
Returns string 's' unless it's blank.
[fn]  (num n (o digits 2) (o trail-zeros nil) (o init-zero nil))
Formats 'n' as a string with the appropriate 'digits' of precision, padding
trailing zeros and an initial zero before the decimal as desired.
[fn]  (plural n x (o plural-form))
Returns a phrase like "3 apples", pluralizeing depending on 'n'.
[fn]  (pluralize n str (o plural-form))
Returns plural form of 'str' if 'n' is not 1.
[fn]  (positions test seq)
Returns all the indices in 'seq' at which 'test' passes.
[fn]  (posmatch pat seq (o start 0))
Returns the first index after 'start' where substring 'pat' is found in 'seq'.
[fn]  (slices s test)
Like tokens but creates a new string at every character matching 'test',
creating empty strings as necessary.
[fn]  (tokens s (o sep whitec))
Breaks up the string 's' at characters matching the predicate 'sep'
(whitespace by default). Continuous runs of such characters count as a single
separation; no empty strings are returned.
[fn]  (trim s (o where (quote both)) (o test whitec))
Strips out characters matching 'test' from front/start/begin of 's',
back/finish/end, or both.
[fn]  (urldecode s)
Reverse urlencode, replacing runs of encoded %sequences with
corresponding (potentially multibyte) characters.
[fn]  (urlencode s)
Encode string 's' using only characters permitted in urls according to the http spec.
Should behave just like javascript's encodeURIComponent.

Documented in lib/tem.arc

[mac] (deftem tem . fields)
Defines a _template_, a table with defaults defined for various keys.

Templates can be read from or written to file. See https://arclanguage.github.io/ref/template.html.

When you read back a template that you wrote to a file, the results can be
subtly different from (and hopefully better than) arc3.1. For a summary of the
differences, compare lib/tem-report.arc3.1 and lib/tem-report.curr.
[fn]  (inst tem-type . args)
Instantiates a table with the given 'args', setting defaults for missing keys
from template 'tem-type'.

Documented in lib/util.arc

[mac] (ado . body)
Anaphoric do. Each expr in the body is available to the next.
    See also aif awhen aand ado1
[mac] (ado1 . args)
Anaphoric ado1. First expr is available to the rest and also returned.
    See also aif awhen aand ado
[fn]  (aint x)
`t' iff `x' is an int.
[fn]  (anum x)
`t' iff `x' is a num. Note that ints are not nums.
[fn]  (applied f)
Returns a fn that calls `f' on the list of its arguments.
    For example, 'max is equivalent to `(applied [best > _])'.
[mac] (assert exp (o msg (+ "Assertion failed: " (tostring:ppr-main exp (len "Assertion failed: ") t))))
Errors with `msg' if `exp' evaluates to nil.
[mac] (asserts . args)
Asserts each expr in `args', with the default error message.
[fn]  (astring x)
`t' iff `x' is a string.
[fn]  (asym x)
`t' iff `x' is a symbol.
[fn]  (atable x)
`t' iff `x' is a table.
[fn]  (auto exp)
Tests whether an expression should be autogensymed
[fn]  (bool x)
Returns `t' if x is not nil, and `nil' otherwise.
[fn]  (classify classifier seq)
Groups the elements of `seq' by `classifier', returning back a table,
    whose keys are the results of `classifier' and whose values are lists
    of the corresponding elements of `seq'. For example:

      arc> (classify type '(1 "foo" a 2 (b)))
      #hash((cons . ((b))) (int . (2 1)) (string . ("foo")) (sym . (a)))

    See also partition keep rem
[fn]  (const x)
Creates a fn that takes any number of arguments and returns `x'.
[fn]  (curry f . xs)
Partially applies ("curries") `f' to `xs'.
[mac] (dol parms (test result) . body)
Like the standard lisp/scheme do loop, but with redundant inner parens
    removed.
[fn]  (flip f)
Flips the order of the first two arguments of `f'.
    For example: ((flip cons) 1 2) => (2 . 1)
[fn]  (foot l)
Gets the last cons in a proper list. (Fails on dotted lists.)
[fn]  (fst a . _)
Returns its first argument. See also snd
[fn]  (iff . funs)
Put simply: iff is to if as andf is to and. Specifically:

    (iff) => idfn
    (iff fun) => fun
    (iff test fun rest ...) => a fn that applies `fun' to its arguments if they
    pass `test', otherwise applies `(iff rest...)' to them.

    Examples:

      arc> ((iff alist car) '(x))
      x
      arc> ((iff alist car) 2)
      2
      arc> ((iff < (fn (x y) x) (fn (x y) y)) 1 2)
      1

    See also andf orf check idfn
[fn]  (join/d . ls)
Destructive join.
    See also join
[mac] (letf name args expr . body)
Defines a (possibly recursive) local fn `(fn ,args ,expr)' named `name'
    within `body'. Example:

      arc> (letf last (x) (aif cdr.x last.it car.x)
             (last '(x y z)))
      z

    See also withf withr
[mac] (mappendeach var lst . body)
As 'mapeach, but using 'mappend instead of 'map.
    See also mapeach mappend each
[fn]  (mklist x)
Wraps atoms in a list; does nothing if `x' is already a list.
    See also atom alist list
[fn]  (nilfn . _)
Ignores its arguments and returns nil.
[fn]  (norf . fns)
Creates a function which returns `t' iff none of `fns' return `t'
    on its arguments.
    See also orf andf nor
[fn]  (partition test seq)
Equivalent to but more efficient than
   `(list (keep test seq) (rem test seq))'. See also keep rem
[mac] (pull1 test place)
Removes the first element that passes `test' from `place'.
    See also pull rem1 rem keep
[fn]  (rem1 test seq)
Returns a copy of `seq' with the first element that passes `test' removed.
    See also rem keep pull1 pull
[fn]  (snd a b . _)
Returns its second argument. See also fst
[mac] (switch expr . cases)
'switch is to 'switchlet as 'case is to 'caselet.
    See also switchlet case caselet
[mac] (switchlet var expr . cases)
Like 'caselet, except it (lazily) evals the expressions compared against.
    See also switch caselet case
[fn]  (tfn . _)
Ignores its arguments and returns t.
[fn]  (uniqs lst)
Returns a list of gensyms, one for each element of `lst'. Elements
    of `lst' that are symbols are used as the base names for their
    corresponding gensyms.
    See also uniq
[fn]  (unzip xs)
Precisely as `zip', except that zip's `ls' is unzip's `xs'; so it takes one
    list of lists rather than any number of lists as arguments. Can be thought
    of as performing the inverse operation.
    See also zip
[mac] (where expr . parms)
Binds `parms' and evaluates `expr'. Examples:

      arc> (where (square x)
              square [* _ _]
              x 2)
      4

    Note that binding is recursive, but that actual assignment of values is done
    in the reverse of the order given, so any variables which are both bound and
    used in `parms' must be used in reverse dependency order:

      arc> (where x x (+ y y) y 0)    ; this works as expected
      y
      arc> (where x y 0 x (+ y y))    ; this doesn't
      nil

    Essentially, this is a reversed form of Scheme's 'letrec,
    with many fewer parentheses. Inspired by Haskell's "where".
    See also withr withr/p withf
[mac] (with/p vars-vals . body)
Scheme/Common Lisp's `let' - ie: 'with with the parens added back.
    Easier to use in macro expansions than 'with.
    See also with withs/p
[mac] (withf fns . body)
Defines a set `fns' of mutually recursive local fns within `body'. Each
    three elements of `fn' correspond to a fn name, argument list, and body,
    so you'll need to use 'do if you want a multi-expression fn body.
    Example:

      arc> (withf (is-even (x) (case x 0 t (is-odd (- x 1)))
                   is-odd (x) (case x 0 nil (is-even (- x 1))))
             (keep is-odd (range 0 5)))
      (1 3 5)

    See also letf withr
[mac] (withf/p fns . body)
Like 'withf, only with extra parens, as in 'with/p compared to 'with.
    See also withf with/p withr withr/p
[mac] (withr bindings . body)
Scheme's 'letrec, with the redundant inner parens removed.
    See also withf letf where withr/p
[mac] (withr/p bindings . body)
Scheme's 'letrec.
    See also withr where
[mac] (withs/p vars-vals . body)
Like Scheme/Common Lisp's `let*' - ie: 'withs with the parens added back.
    Easier to use in macro expansions than 'withs.
    See also withs with/p
[fn]  (zip . ls)
Returns a list of lists; the n-th element of the result is a list of the
    n-th elements of the lists in `ls'. The length of the result is the length
    of the shortest list in `ls'; extra elements in other lists are discarded.
    See also unzip

Documented in unit-test.arc/unit-test.arc

[mac] (add-suites-to-suite full-suite-name cur-suite-sexp suites-sexps)
Add the first suite from SUITES-SEXPS to CUR-SUITE-SEXP.
FULL-SUITE-NAME is the unquoted name of the suite.
[mac] (add-tests-to-suite cur-suite-sexp full-suite-name setup tests-sexps)
Add tests to CUR-SUITE-SEXP, with setup SETUP. Tests come from TESTS-SEXPS.

SETUP is a list of var val pairs, like (x 1) or (age 31 height 70).
Don't quote FULL-SUITE-NAME.
[fn]  (count-passes suite-results)
Count the total number of passed tests in SUITE-RESULTS, a list of suite-results templates.
[fn]  (do-test-and-error-on-failure names)
Run the tests in NAMES, as in do-test.

However, if there are any test failures, throw an error.
This is intended for use in scripts, where the exit code
from racket is needed to tell if all tests passed or not
[fn]  (filter-unique-names names)
Gets the unique names from NAMES.

      If one name is a full prefix of another (only counting period-separated fragments),
      only include the prefix. So if the input is '(whatever.thing whatever), the output
      should be '(whatever).
[fn]  (get-all-top-level-suite-names)
Get the names of all the top-level suites.

      A top-level suite is a suite that doesn't have a parent.
[fn]  (get-name-fragments name)
Take a full suite name NAME, and return the fragments of it as a list of symbols.
      For example, (get-name-fragments 'math.integers.subtracting)
      returns '(math integers subtracting).
      This function will also work for test names
[fn]  (get-nesting-level name)
Return how nested NAME is, where a top-level suite is level 0.
      Each period in the name increases the level by one.
[fn]  (get-suite name)
Get the suite with full name NAME out of *unit-tests*
      This method looks at nested suites; that is, for a NAME of math.adding,
      it gets the 'math suite out of *unit-tests*, then looks for a nested
      suite 'adding inside it, rather than looking for a suite named math.adding
      at the top level of *unit-tests*.
[fn]  (get-suite-and-test-name test-full-name)
Return (suite-name test-name), as a list.
[fn]  (get-suite-structure-problems suite-sexp)
Return the problems with the structure of SUITE-SEXP, as a string.

For example, a SUITE-SEXP of (suitex name (test a b)) should have an error about
beginning with the symbol 'suitex .
[fn]  (get-test name)
Get the test obj referred to by NAME, or nil if it isn't found.
[fn]  (is-valid-name name)
Return t if NAME, a symbol, is a valid name for a suite or test.

      Valid names contain any characters but periods.
[fn]  (keep-by-car sexp identifier)
Gets each element of SEXP where that element is a list, and the car of that element is IDENTIFIER.
[fn]  (list-suites)
Prints out all suites that can be run.
[mac] (make-suite parent-suite-full-name suite-sexp)
Makes a suite.

      PARENT-SUITE-FULL-NAME is the full name of the parent suite, or nil. Don't quote it.
      FULL-SUITE is the full s-exp for the suite; something like (suite my-name (test...) ...).
[mac] (make-test suite-name test-name setup . body)
Make a test for SUITE-NAME named TEST-NAME. Quote both of these.

The test should have SETUP and BODY.
[fn]  (pretty-results test-result)
Print out a pretty summary of TEST-RESULT.
[fn]  (print-run-summary name)
This should work on both suite and test names
[fn]  (remove-thing name-fragments suites-obj)
Delete the thing referred to by NAME-FRAGMENTS from SUITES-OBJ.

      To do this, take each non-terminal element of NAME-FRAGMENTS,
      treat that symbol as a suite name, and look up that suite.

      Then it takes the last element, and deletes any suites or tests with that name. Finally,
      it will go back up the path and delete any empty suites.

      For example, it might get called as (remove-thing '(top nested1 nested2 last-thing)).
      It will remove a suite called top.nested1.nested2.last-thing, or a test named last-thing
      inside top.nested1.nested2.
[fn]  (result-is-pass test-result)
Return t if TEST-RESULT, a test-result template instance, represents a passed test.
[fn]  (retest)
Rerun the last group of tests run.
[fn]  (run-all-tests)
Run all tests. Return t if any were found, nil if none were.
[fn]  (run-specific-things names (o store-result nil))
Run the things in names, then if there were any, store that in *last-things-run*.
      Return t if at least one of the names is found, nil otherwise.
[fn]  (run-these-things names (o store-result nil))
Each name in NAMES can either be a suite or a test.
      If STORE-RESULT is t, store the result of each function in *test-results* or *suite-results*
      Return t if at least one of the names is found, nil otherwise.
[fn]  (run-this-thing name (o store-result nil))
If NAME is a test or a suite, run it and return the template result.
      If NAME is not either, return nil.
[fn]  (suite-has-content the-suite)
Return t if SUITE has either tests or nested suites.
[fn]  (summarize-run names)
Summarize a given test run.
      That is, print out information about the overall status
      of a set of suites.
[fn]  (summarize-run-of-all-tests)
Summarise the run of all tests.
[fn]  (to-readable-string val)
Return a readable version of VAL.
[fn]  (total-tests suite-results)
Count the total number of tests in SUITE-RESULTS, a list of suite-results templates.
[fn]  (wipe-all-tests)
Delete all tests and suites.
[mac] (wipe-tests . names)
Delete the tests or suites from *unit-tests*, causing them to not exist anymore.

      If this deletion results in a suite with no tests and no nested suites, that suite
      will be removed also.
[fn]  (wipe-tests-helper name-list)
For each thing named in NAME-LIST, delete it from *unit-tests*.
[fn]  (would-shadow cur-suite thing-name)
Returns t iff CUR-SUITE has a test or suite named THING-NAME.