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.
[mac] (%braces . body)
The function invoked on curly-bracket calls.
For example, {a 1 b 2} => (%braces a 1 b 2) => (obj a 1 b 2)[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)
[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
[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'.
[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
[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.
[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.
[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] (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)[fn] (break-thread th)
Politely tries to interrupt a thread of concurrently running expressions when it's ready to be interrupted.
[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] (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] (check x test (o alt))
Returns `x' if it satisfies `test', otherwise returns 'alt' (nil if it's not provided).
[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] (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] (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] (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"))[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.
[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'.
[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] (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)[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.2. For Arc 3.2'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)'.
[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)[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.
[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] (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] (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)[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] (lastcons xs)
Returns the absolute last link of list 'xs'. Save this value to efficiently append to 'xs'.
[fn] (len tem)
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
[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] (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-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] (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] (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
[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] (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] (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[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
[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] (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] (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] (prrn . args)
Like prn, but prints both carriage return and newline, usually because the HTTP protocol requires them.
[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)))
[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] (readfile name)
Slurps the entire contents of file 'name' using read and returns the expressions as a list.
[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] (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"[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] (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] (set-coercer to from fun)
Makes 'fun the coercion function from 'from to 'to.
See also: defcoerce[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] (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] (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] (sref self val . args)
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] (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[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))
[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] (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] (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] (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 " "))
[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/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
[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] (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
[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 teardown 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), (age 31 height 70), or (backup-important-global (copy important-global)). Teardown is a list of s-expressions to run after the tests finish, like ((= important-global backup-important-global)). Don't quote FULL-SUITE-NAME.
[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] (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.
[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[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))[fn] (count-passes suite-results)
Count the total number of passed tests in SUITE-RESULTS, a list of suite-results templates.
[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.
[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'.
[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] (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
[mac] (dol parms (test result) . body)
Like the standard lisp/scheme do loop, but with redundant inner parens
removed.[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] (enq-limit val q (o limit 1000))
Like enq, but never let the queue 'q' grow larger than 'limit'.
[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] (flip f)
Flips the order of the first two arguments of `f'.
For example: ((flip cons) 1 2) => (2 . 1)[mac] (gentag . args)
An opening tag. For example, (gentag html lang "en") results in printing out: <html lang="en"> .
[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-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] (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.[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-core str)
Returns a list of symbols whose documentation matches or partly matches
`str'.[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] (inst tem-type . args)
Instantiates a table with the given 'args', setting defaults for missing keys from template 'tem-type'.
[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] (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] (lazy-map f xs)
lazily maps f over the stream xs invariant: (as cons (lazy-map f lazy-stream)) == (map f lazy-stream)
[fn] (len-dotted x)
len for dotted lists Examples: arc> (len-dotted '(1 2 3)) 3 arc> (len-dotted '(1 2 . 3)) 3
[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[fn] (lines s)
Breaks up a multi-line string into lines, respecting either newlines or CRLF sequences.
[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.[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 teardown . body)
Make a test for SUITE-NAME named TEST-NAME. Quote both of these. The test should have SETUP, TEARDOWN, and BODY. SETUP is a list of variable-value pairs, like (x 3 y (+ x 2)). TEARDOWN is a list of s-expressions to run after the test, like ((wipe test-storage)).
[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] (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] (mtime path)
Returns the modification time of the file or directory `path' in
seconds since the epoch.[fn] (multisubst pairs seq)
For each (old new) pair in 'pairs', substitute 'old' with 'new' in 'seq'.
[fn] (norf . fns)
Creates a function which returns `t' iff none of `fns' return `t'
on its arguments.
See also orf andf nor[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-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] (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] (partition test seq)
Equivalent to but more efficient than `(list (keep test seq) (rem test seq))'. See also keep rem
[fn] (posmatch pat seq (o start 0))
Returns the first index after 'start' where substring 'pat' is found in 'seq'.
[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] (ppr . l)
Pretty print. This function displays arc code with proper
indenting and representation of syntax.[fn] (ppr-source name)
Pretty-prints the source code of the function `name'.
Is a function, so `name' is evaluated.
See also: src[fn] (print x)
Print an expression on one line, replacing quote, unquote,
quasiquote, unquote-splicing, %brackets, and %braces with their respective symbols.[mac] (pull1 test place)
Removes the first element that passes `test' from `place'.
See also pull rem1 rem keep[fn] (queue . contents)
A queue is like a list but with efficient insertion in one end and deletion in the other.
[fn] (rem1 test seq)
Returns a copy of `seq' with the first element that passes `test' removed.
See also rem keep pull1 pull[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] (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.[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.[mac] (sctag spec)
A self-closed tag. For example, (sctag (img src "http://example.com/favicon.ico")) renders as: <img src="http://example.com/favicon.ico" />
[fn] (slices s test)
Like tokens but creates a new string at every character matching 'test', creating empty strings as necessary.
[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
[mac] (src name)
Pretty prints the source code of the function `name'.
Is a macro, so `name' is not evaluated.
See also: ppr-source[fn] (start-tag spec (o self-close nil))
Render an opening tag with the given SPEC. SELF-CLOSE, if given, means that the tag ends in a space, a slash. See https://html.spec.whatwg.org/multipage/syntax.html#start-tags
[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)[fn] (summarize-run names starting-time)
Summarize a given test run.
That is, print out information about the overall status
of a set of suites.[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[mac] (tag spec . body)
Print a full html tag with opening and closing tags, plus a body. For example, (tag (a href "https://arclanguage.org/") (pr "check it out")) renders as: <a href="https://arclanguage.org/">check it out</a>
[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] (total-tests suite-results)
Count the total number of tests in SUITE-RESULTS, a list of suite-results templates.
[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.
[mac] (uform user req after . body)
Like aform but also authenticates that the form is submitted by 'user'.[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] (urform user req after . body)
Like arform but also authenticates that the form is submitted by 'user'.[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.
[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'.[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] (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.[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] (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] (would-shadow cur-suite thing-name)
Returns t iff CUR-SUITE has a test or suite named THING-NAME.
[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