ac.scm
. On top of this the core of the language is implemented
in the Arc language itself in arc.arc
. Finally, various libraries
are implemented on top of the core. This page provides some documentation
of the functionality in the foundation.
In one sense, the foundation can be considered the "axioms", and the full language is created out of these axioms. However, in my view, the current foundation both contains too much and too little to be considered an axiomatic base. For example, it contains enough networking functionality to implement a web server, but not enough to fetch a web page. The math functions include square root and exponentiation, but not trigonometry. Nonetheless, the foundation provides the basis for a very interesting language. For more information on how the foundation is implemented, see my article Arc Internals.
Arc was used to generate this document. I created a large Arc data structure holding the functions, arguments, description, headings, and test examples. I wrote a program in Arc that processes this data structure to generate the HTML file for this page. The functions are linked to the Arc Cross Reference website. The examples on the right, for the most part, show actual output from running the embedded code while generating the page. This ensures that the examples show actual behavior of the arc2 release. (A few commands, such as quit and the socket operations, are not suitable for execution in this way and their output was "faked".)
The documentation below is based on my exploration of the language. Undoubtedly this document contains many errors. In addition, the language is undergoing active modification. This documentation is based on the "arc1" release.
![]() Arc includes integers (fixed size and arbitrarily large),
floats, fractions, and complex numbers. It also has positive and negative infinities
and "Not a Number". Arc supports escapes for hex, decimal, octal, or
binary numbers: #x, #d, #o, and #b. Numbers are of type 'int or 'num.
|
>42 42 >5.0 5.0 >2.0-3.0i 2.0-3.0i >+inf.0 +inf.0 >(+ #x10 #d10 #o10 #b10) 36 >1/2+3/4i 1/2+3/4i >1e3 1000.0 >1/2e3 500.0 >(type 5.0) int >(type 1+2i) num |
![]() Arc supports Unicode characters, and a variety of
escapes.
|
>(prn #\a #\102 #\newline #\null #\u5a #\u4e9c #\U12031 #\日) aB Z亜𒀱日 #\a >(type #\a) char |
![]() Arc supports Unicode strings, and a variety of escapes. The
escape sequences are not the same as the character escape sequences.
|
>(prn "a \102 \n \x00 \x5a \U4e9c 日") a B Z 亜 日 "a B \n \u0000 Z 亜 日" >(type "a") string |
![]() By quoting a symbol, it will not be evaluated.
|
>'a a >'b b >(type 'c) sym |
![]() Lists are built up of cons cells. They are terminated with nil,
in contrast to Scheme, where they are terminated with '().
|
>'(1 2 3) (1 2 3) >(type '(1)) cons |
![]() Procedures are created by fn or def.
|
>(fn (x) (+ x 1)) #<procedure> >(def foo (x) (+ x 1)) #<procedure: foo> >(type (fn (x) (+ x 1))) fn |
![]() Macros are created by mac.
|
>(mac bar (x) `(+ ,x 1)) #3(tagged mac #<procedure>) >(type (mac baz (x) `(+ ,x 1))) mac |
![]() Arc supports arbitrary tagged types.
|
>(annotate 'mytype 'x) #3(tagged mytype x) >(type (annotate 'mytype 'x)) mytype |
![]() Arc supports hash tables. Tables can be used as
functions; they look up the key.
|
>(table) #hash() >(let x (table) (= (x 'key) 'value) (x 'key)) value >(type (table)) table |
![]() Input ports can be from files, sockets, or strings.
|
>(type (stdin)) input |
![]() Output ports can be from files, sockets, or strings.
|
>(type (outfile "/tmp/junk")) output |
![]() A thread can throw an exception if an error occurs, or
generate an exception with err.
|
>(on-err (fn (ex) (prn ex) (prn (details ex)) (type ex)) (fn () (car 1))) #<struct:exn:fail> Can't take car of 1 exception |
![]() A TCP socket is created with open-socket. Arc's socket
support is limited to incoming TCP connections.
|
>(type (open-socket 8080)) Error: tcp-listen: listen on 8080 failed (Address already in use; errno=98) |
![]() Threads are created with new-thread.
|
>(type (new-thread (fn x))) thread |
![]() ![]() nil represents false. it is equivalent to '()
|
>(is nil '()) t >(type nil) sym |
![]() ![]() t represents true. Any non-nil value will evaluate as true in a
conditional, including 0 and the empty string.
|
>(no t) nil >(type t) sym |
![]() ![]() Coerces object to a new type. A char can be
coerced to int, string, or sym. A number can be coerced to int, char, or string
(of specified base). A string can be coerced to sym, cons (char list), or int (of
specified base). A list of characters can be coerced to a string. A symbol
can be coerced to a string.
|
>(coerce "a" 'sym) a >(coerce 65 'char) #\A >(coerce 65 'int 2) 65 >(coerce "abc" 'cons) (#\a #\b #\c) |
![]() ![]() Returns the type of an object (as a symbol).
Possibilities are cons, sym, fn, char, string, int, num, table, output,
input, socket, exception, or mac.
|
>(type 1) int >(type car) fn |
![]() ![]() fn is used to create lambda functions. The args can be a variable (which
will pick up all the arguments as a list), a list of variables, or a dotted list of
variables (the last will pick up the remainder as a list ).
|
>((fn (x y) (+ x y)) 1 2) 3 >((fn all (len all)) 1 2 3) 3 >((fn (arg1 arg2 . rest) rest) 1 2 3 4) (3 4) |
![]() ![]() Arc is the basic conditional operation.
It takes a sequence of tests and expressions. The expression corresponding
to the first true test is returned. Other expressions are not evaluated.
|
>(if nil "Nil is true" 0 "0 is true" "What is true?") "0 is true" |
![]() ![]() The backquote ` is shorthand for quasiquote, e.g. `(+
1 2) is the same as (quasiquote (1 2)). Inside quasiquote, the unquote
operator will cause the contents to be evaluated instead of quoated. The
unquote-splicing operator will cause contents to be evaluated and spliced
into the result. , is shorthand for unquote, and ,@ is shorthand for
unquote-splicing.
|
>`((+ 1 2) ,(+ 3 4) ,@(list 5 6)) ((+ 1 2) 7 5 6) |
![]() ![]() The single quote ' is shorthand for quote, e.g. 'x is the same as (quote x)
|
>'(1 2 3) (1 2 3) |
![]() ![]() ![]() set is used to set a variable to a value.
|
>(set x 10) 10 |
![]() ![]() ![]() Less than comparison. Applies to numbers, strings, symbols, or
chars. If multiple arguments are given, the sequence must be monotonically
increasing.
|
>(< 1 2) t >(< 1 2 3) t >(< 1 3 2) nil >(< "a" "b") t >(< 'a 'b) t >(< #\a #\b) t |
![]() ![]() ![]() Greater than comparison. Applies to numbers, strings, symbols, or
chars. If multiple arguments are given, the sequence must be monotonically
decreasing.
|
>(> 1 2) nil >(> 3 1 2) nil >(> "a" "b") nil >(> 'a 'b) nil >(> #\a #\b) nil |
![]() ![]() ![]() Tests is a symbol is bound.
|
>(bound 'foobar) nil >(do (set y 1) (bound 'y)) t |
![]() ![]() ![]() Tests if the value is an exact integer.
|
>(exact 3) t >(exact 3.14) nil |
![]() ![]() ![]() Tests equality with eqv?
|
>(is 1 2) nil >(is "a" "a") t >(is '(1) '(1)) nil >(is 1 1 1 1) t >(is nil '()) t |
![]() ![]() First element of list
|
>(car '(1 2 3)) 1 |
![]() ![]() Remainder of list.
|
>(cdr '(1 2 3)) (2 3) |
![]() ![]() Prepends element to list.
|
>(cons 1 '(2 3)) (1 2 3) |
![]() ![]() Creates a string of the given length.
|
>(newstring 5 #\a) "aaaaa" |
![]() ![]() ![]() Sets car of list to new value. If applied to a
string, sets the first character of the string, which must have length at
least one.
|
>(do (= x "abc") (scar x #\d) x) "dbc" >(do (= x '(1 2 3)) (scar x #\d) x) (#\d 2 3) |
![]() ![]() ![]() Sets cdr of a list.
|
>(do (= x '(1 2 3)) (scdr x '(4)) x) (1 4) |
![]() ![]() ![]() Sets indexed entry in a list, string, or hash table to
the given value.
|
>(do (= x "abc") (sref x #\d 1) x) "adc" >(do (= x '(1 2 3)) (sref x #\d 1) x) (1 #\d 3) |
![]() ![]() Computes the length of a list, string, or hash table.
|
>(len "abc") 3 >(len '(1 2 3)) 3 |
![]() ![]() Multiplication.
|
>(* 2 3) 6 |
![]() ![]() Addition. This operator also performs string and list
concatenation.
|
>(+ 1 2 3) 6 >(+ "ab" "c" "de") "abcde" >(+ '(1 2) '(3 4) '(5)) (1 2 3 4 5) |
![]() ![]() Subtraction.
|
>(- 3 2) 1 |
![]() ![]() Division
|
>(/ 1 2) 1/2 >(/ 1.0 2) 0.5 |
![]() ![]() Exponentiation.
|
>(expt 2 3) 8 |
![]() ![]() |
>(mod 10 3) 1 >(mod -10 3) 2 |
![]() ![]() Returns a random number between 0 and 1, or between 0 and
the specified integer (excluding the integer).
|
>(rand 10) 5 >(rand) 0.4255004866291074 |
![]() ![]() Square root operation
|
>(sqrt 2) 1.4142135623730951 >(sqrt -1) 0+1i |
![]() ![]() Truncates to an integer. Was 'truncate' in arc0.
|
>(trunc 1.9) 1 >(trunc -1.1) -1 |
![]() ![]() Applies proc to each element of the table.
|
>(let x (table) (sref x 9 3) (sref x 16 4) (maptable (fn (key val) (prn key " " val)) x)) 4 16 3 9 #hash((3 . 9) (4 . 16)) |
![]() ![]() Creates a hash table.
|
>(table) #hash() |
![]() ![]() Evaluates the expression.
|
>(eval '(+ 1 2)) 3 |
![]() ![]() Applies the function to the arguments.
|
>(apply + '(1 2)) 3 |
![]() ![]() Expands special syntax (: ! . or ~). The :
character indicates composition. The ~ indicates complementing. The .
applies the first value to the remainder. The ! is like . except the
arguments are quoted.
|
>(ssexpand 'x:~y:z) (compose x (complement y) z) >(ssexpand '+.1.2) (+ 1 2) >(ssexpand '+!1!2) (+ (quote 1) (quote 2)) >(ssexpand 'cons!a!b) (cons (quote a) (quote b)) |
![]() ![]() ![]() Tests if the symbol contains special syntax (: ! . or ~).
|
>(ssyntax 'x:y) t |
![]() ![]() Tags the object with the given type. Only used for
macros.
|
>(type (annotate 'mac car)) mac |
![]() ![]() Expands a macro.
|
>(macex '(let a 1 (pr a))) ((fn (a) (pr a)) 1) |
![]() ![]() Expands a macro to one level.
|
>(macex1 '(let a 1 (pr a))) (with (a 1) (pr a)) |
![]() ![]() Returns the underlying object for an annotated object
|
>(rep whilet) #<procedure> |
![]() ![]() Hash table containing function signatures.
|
>(sig 'map) (f . seqs) |
![]() ![]() Generates a unique symbol.
|
>(uniq) gs2503 |
![]() ![]() Calls thunk, setting current-input-port
to the specified port.
|
>(call-w/stdin (instring "Hello") readline) "Hello" |
![]() ![]() Calls thunk, setting current-input-port
to the specified port.
|
>(let sop (outstring) (call-w/stdout sop (fn () (prn '(1 2)))) (inside sop)) "(1 2)\n" |
![]() ![]() Closes a port. In arc0, close took a single argument
only.
|
>(close (outfile "/tmp/junk")) nil |
![]() ![]() Displays the argument on the output-port (or
current-output-port) using Scheme's display procedure.
|
>(disp '(1 2)) (1 2) nil >(disp "abc") abc nil |
![]() ![]() Peeks at the next character from the input port, but
leaves the character for future reads. It
uses current-input-port if the argument is nil. It returns the character, or nil for
end-of-file.
|
>(peekc (pipe-from "echo hello")) #\h |
![]() ![]() Executes command in the underlying OS. Then opens
an input-port to the results.
|
>(readline (pipe-from "echo hello")) "hello" |
![]() ![]() Reads a byte from the input-port (or default of
current-input-port). Returns nil on end-of-file.
|
>(readb (pipe-from "echo hello")) 104 |
![]() ![]() Reads a character from the input-port (or default of
current-input-port). Returns nil on end-of-file.
|
>(readc (pipe-from "echo ©")) #\© |
![]() ![]() Reads a Scheme object from the input port. Returns eof-value
on end-of-file.
|
>(sread (pipe-from "echo '(1 2) (3)'") "junk") (1 2) |
![]() ![]() current-error-port: returns the output-port stderr
|
>(stderr) #<output-port:stderr> |
![]() ![]() current-input-port: returns the input-port stdin
|
>(stdin) #<input-port:stdin> |
![]() ![]() current-output-port: returns the output-port stdout
|
>(stdout) #<output-port:string> |
![]() ![]() Writes the argument to the output-port (or
current-output-port). The write and disp procedures are subtly different.
The output from write is more 'raw' than the output from disp; see the
MzScheme
Default
Printer documentation for details.
|
>(write "abc") "abc" nil |
![]() ![]() Writes the byte to the output-port (or
default of current-output-port).
|
>(writeb 65) A 65 |
![]() ![]() Writes the character to the output-port (or
default of current-output-port).
|
>(writec #\日) 日 #\日 |
![]() ![]() Returns (as a string) the bytes accumulated
in a string-output-port generated by outstring. This is MzScheme's get-output-string.
|
>(let sop (outstring) (write "hello" sop) (inside sop)) "\"hello\"" |
![]() ![]() Creates an input port to read UTF-8 bytes from the
string. This is MzScheme's open-input-string.
|
>(readline (instring "hello")) "hello" |
![]() ![]() Creates an output-port that accumulates the output
into a byte string. The string can be retrieved with inside. This is
MzScheme's open-output-string.
|
>(outstring) #<output-port:string> |
![]() ![]() Returns the IP address of the client
connected to a TCP port. The tcp-output-argument is the second value
returned from socket-accept. The address is returned as a string, the same as
the third result from socket-accept.
|
>(let s (socket-accept (open-socket 8080)) (client-ip (s 1))) "10.2.40.71" |
![]() ![]() Opens a tcp-listener on the given port.
|
>(open-socket 8000) Error: tcp-listen: listen on 8000 failed (Address already in use; errno=98) |
![]() ![]() Accepts a connection on the given tcp-listener.
The thread blocks until a connection is received. It returns a list of
(input-port output-port client-ip-string)
|
>(socket-accept (open-socket 8080)) (#<input-port> #<output-port> "10.2.40.71") |
![]() ![]() Returns the directory contents as a list.
|
>(dir "mydir") ("foo") |
![]() ![]() Tests if a directory exists.
|
>(dir-exists "mydir") "mydir" |
![]() ![]() Tests if a file exists.
|
>(file-exists "mydir") nil |
![]() ![]() Opens the specified path for
reading. By default, the file is opened in binary mode, and bytes are
returned as read from the file. In text mode, return and linefeed bytes are
filtered in a platform-specific way. (On Windows, return followed by
linefeed is filtered to a single linefeed.)
|
>(outfile "/tmp/junk" 'append) #<output-port:/tmp/junk> |
![]() ![]() Opens the specified path for writing. By
default, the file is truncated if it already exists. Returns an
output-port. Arc supports only 'text mode for outfile.
|
>(outfile "/tmp/junk" 'append) #<output-port:/tmp/junk> |
![]() ![]() Removes the specified file.
|
>(rmfile "/tmp/junk") nil |
![]() ![]() Invokes function, making sure that only one
thread at a time invokes something wrapped inside an atomic-invoke.
|
>(atomic-invoke (fn () "critical section" (+ 1 2))) 3 |
![]() ![]() Triggers a break exception on a thread.
|
>(let th (new-thread (fn () (sleep 2))) (break-thread th)) user break |
![]() ![]() ![]() Predicate to test if a thread has terminated.
|
>(let th (new-thread (fn () (sleep 1))) (prn (dead th)) (sleep 2) (prn (dead th))) nil t t |
![]() ![]() Terminates the specified thread immediately.
|
>(let th (new-thread (fn () (sleep 100))) (kill-thread th) (dead th)) t |
![]() ![]() Creates and returns a new thread. Was 'thread'
in arc0.
|
>(new-thread (fn () (+ 1 2))) #<thread> |
![]() ![]() Causes the current thread to sleep for at least the
specified time.
|
>(sleep 0.1) nil |
![]() ![]() Returns the message associated with an exception.
|
>(on-err (fn (ex) (details ex)) (err "boo")) Error: boo |
![]() ![]() Raises an exception with the given text.
|
>(err "Failure" 42) Error: Failure 42 |
![]() ![]() Executes proc. Calls err-proc if an exception
occurs in proc. The exception is passed to err-proc
|
>(on-err (fn (ex) (string "caught " (details ex))) (fn () (/ 1 0))) "caught /: division by zero" |
![]() ![]() Packages up the current continuation into an 'escape
procedure' and passes it to the procedure. Equivalent to Scheme's call/cc or call-with-current-continuation.
|
>(ccc (fn (ep) (ep "bailout value") 42)) "bailout value" |
![]() ![]() Uses Scheme's
dynamic-wind to
ensure that after-procedure is executed whenever during-procedure exits.
|
>(protect (fn () (/ 1 0)) (fn () (prn "after"))) after Error: /: division by zero |
![]() ![]() Returns the amount of time spent in garbage
collection.
See MzScheme
for more details on Arc's time functions.
|
>(current-gc-milliseconds) 5476 |
![]() ![]() Returns the number of milliseconds of
processor time used.
|
>(current-process-milliseconds) 13644 |
![]() ![]() Returns current time in milliseconds. The time is from an
arbitrary starting date, and can wrap or be negative.
|
>(msec) 355667501 |
![]() ![]() Returns current time in seconds, from a platform-specific
starting date.
|
>(seconds) 1205093994 |
![]() ![]() Executes the string in the underlying OS.
|
>(system "date #/t") Sun Mar 9 13:19:54 PDT 2008 nil |
![]() ![]() Exits the interpreter.
|
>(quit) --exits-- |
Copyright 2008 Ken Shirriff.