ref/foundation-doc.html

<html dir="ltr">
<head>
<meta content="text/html; charset=UTF-8" http-equiv="Content-Type"/>
<title>Arc: The Foundation</title>
<link rel="shortcut icon" href="/assets/favicon.png">
<link rel="stylesheet" type="text/css" href="code.css">
<link href="/assets/bootstrap.css" rel="stylesheet">
</head>
<body style='margin:12px 50px 0'>
  <div class="navbar navbar-inverse">
    <div class="navbar-inner">
      <ul class="nav navbar-nav">
        <li><a href="/ref/">Arc 3.1</a>
        <li><a href="http://tryarc.org">Try it</a></li>
        <li><a href="http://github.com/arclanguage/anarki">Get it</a></li>
        <li><a href="http://ycombinator.com/arc/tut.txt">Tutorial</a></li>
        <li><a href="http://arclanguage.org/forum">Forum</a></li>
      </ul>
    </div>
  </div> <!-- end of navbar -->

<h1 class="links">The Foundation</h1>
The Arc language is implemented by a "foundation" of functionality
implemented in Scheme in <code>ac.scm</code>. On top of this the <a
href="http://paulgraham.com/core.html">core</a> of the language is implemented
in the Arc language itself in <code>arc.arc</code>. Finally, various libraries
are implemented on top of the core. This page provides some documentation
of the functionality in the foundation. For more information on how the
foundation is implemented, see the article
<a href="http://arcfn.com/2008/02/arc-internals-part-1.html">Arc Internals</a>.

<br/><br/>
This reference was created using
<a href='https://github.com/arclanguage/arclanguage.github.io/blob/master/_ref/generate.sh'>an Arc program</a>
The examples on the right, for
the most part, show actual output from running the embedded code while
generating the page. (A few commands, such as quit and the socket operations,
are not suitable for execution in this way and their output was "faked".)
Please inform <a href='http://arclanguage.org/forum'>the forum</a> if you find
anything unclear or anomalous.
<h2>Data Types</h2>

  Arc inherits a surprisingly complex system of data types
  from <a
  href='http://download.plt-scheme.org/doc/mzscheme/mzscheme-Z-H-3.html#node_chap_3'>MzScheme</a>.
  <p/>
  Arc defines Boolean values somewhat differently from Scheme, using nil
  for falsity and t for truth.  Note that anything except nil and the empty
  list will evaluate as true, including 0 and an empty table.
<p><table class='arc'>
  <tr>
    <td class='arc'><a name='numbers'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>numbers</span> <span class='args'></span>
    <div class='desc'>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.</div>
    </td>
    <td class='arc'><pre>
&gt;42
<span class="return">42
</span></pre>
<pre>
&gt;5.0
<span class="return">5.0
</span></pre>
<pre>
&gt;2.0-3.0i
<span class="return">2.0-3.0i
</span></pre>
<pre>
&gt;+inf.0
<span class="return">+inf.0
</span></pre>
<pre>
&gt;(+ #x10 #d10 #o10 #b10)
<span class="return">36
</span></pre>
<pre>
&gt;1/2+3/4i
<span class="return">1/2+3/4i
</span></pre>
<pre>
&gt;1e3
<span class="return">1000.0
</span></pre>
<pre>
&gt;1/2e3
<span class="return">500.0
</span></pre>
<pre>
&gt;(type 5.0)
<span class="return">num
</span></pre>
<pre>
&gt;(type 1+2i)
<span class="return">num
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='characters'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>characters</span> <span class='args'></span>
    <div class='desc'>Arc supports Unicode characters, and a variety of
  escapes.</div>
    </td>
    <td class='arc'><pre>
&gt;(prn #\a #\102 #\newline #\null #\u5a #\u4e9c #\U12031 #\日)
<span class="stdout">aB
 Z亜𒀱日

</span><span class="return">#\a
</span></pre>
<pre>
&gt;(type #\a)
<span class="return">char
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='strings'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>strings</span> <span class='args'></span>
    <div class='desc'>Arc supports Unicode strings, and a variety of escapes.  The
  escape sequences are not the same as the character escape sequences.</div>
    </td>
    <td class='arc'><pre>
&gt;(prn "a \102 \n \x00 \x5a \U4e9c 日")
<span class="stdout">a B 
   Z 亜 日

</span><span class="return">"a B \n \u0000 Z 亜 日"
</span></pre>
<pre>
&gt;(type "a")
<span class="return">string
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='symbols'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>symbols</span> <span class='args'></span>
    <div class='desc'>By quoting a symbol, it will not be evaluated.</div>
    </td>
    <td class='arc'><pre>
&gt;'a
<span class="return">a
</span></pre>
<pre>
&gt;'b
<span class="return">b
</span></pre>
<pre>
&gt;(type 'c)
<span class="return">sym
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='lists'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>lists</span> <span class='args'></span>
    <div class='desc'>Lists are built up of cons cells.  They are terminated with nil,
  in contrast to Scheme, where they are terminated with '().</div>
    </td>
    <td class='arc'><pre>
&gt;'(1 2 3)
<span class="return">(1 2 3)
</span></pre>
<pre>
&gt;(type '(1))
<span class="return">cons
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='procedures'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>procedures</span> <span class='args'></span>
    <div class='desc'>Procedures are created by fn or def.</div>
    </td>
    <td class='arc'><pre>
&gt;(fn (x) (+ x 1))
<span class="return">#&lt;procedure:...t/private/kw.rkt:592:14&gt;
</span></pre>
<pre>
&gt;(def foo (x) (+ x 1))
<span class="return">#&lt;procedure: foo&gt;
</span></pre>
<pre>
&gt;(type (fn (x) (+ x 1)))
<span class="return">fn
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='macros'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>macros</span> <span class='args'></span>
    <div class='desc'>Macros are created by mac.</div>
    </td>
    <td class='arc'><pre>
&gt;(mac bar (x) `(+ ,x 1))
<span class="return">#(tagged mac #&lt;procedure: bar&gt;)
</span></pre>
<pre>
&gt;(type (mac baz (x) `(+ ,x 1)))
<span class="return">mac
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='tagged'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>tagged</span> <span class='args'></span>
    <div class='desc'>Arc supports arbitrary tagged types.</div>
    </td>
    <td class='arc'><pre>
&gt;(annotate 'mytype 'x)
<span class="return">#(tagged mytype x)
</span></pre>
<pre>
&gt;(type (annotate 'mytype 'x))
<span class="return">mytype
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='table'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>table</span> <span class='args'></span>
    <div class='desc'>Arc supports hash tables.  Tables can be used as
  functions; they look up the key.</div>
    </td>
    <td class='arc'><pre>
&gt;(table)
<span class="return">#hash()
</span></pre>
<pre>
&gt;(let x (table)
    (= (x 'key) 'value)
    (prn (x 'key) (x 'foo 'default)))
<span class="stdout">valuedefault

</span><span class="return">value
</span></pre>
<pre>
&gt;(type (table))
<span class="return">table
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='input'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>input</span> <span class='args'></span>
    <div class='desc'>Input ports can be from files, sockets, or strings.</div>
    </td>
    <td class='arc'><pre>
&gt;(type (stdin))
<span class="return">input
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='output'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>output</span> <span class='args'></span>
    <div class='desc'>Output ports can be from files, sockets, or strings.</div>
    </td>
    <td class='arc'><pre>
&gt;(type (outfile "/tmp/junk"))
<span class="return">output
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='exception'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>exception</span> <span class='args'></span>
    <div class='desc'>A thread can throw an exception if an error occurs, or
  generate an exception with err.</div>
    </td>
    <td class='arc'><pre>
&gt;(on-err (fn (ex) (prn ex) (prn (details ex)) (type ex))
    (fn () (car 1)))
<span class="stdout">#(struct:exn:fail Can't take car of 1 #
&lt;continuation-mark-set&gt;)
Can't take car of 1

</span><span class="return">exception
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='socket'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>socket</span> <span class='args'></span>
    <div class='desc'>A TCP socket is created with open-socket.  Arc's socket
  support is limited to incoming TCP connections.</div>
    </td>
    <td class='arc'><pre>
&gt;(type (open-socket 8080))
<span class="return">socket
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='threads'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>threads</span> <span class='args'></span>
    <div class='desc'>Threads are created with new-thread.</div>
    </td>
    <td class='arc'><pre>
&gt;(type (new-thread (fn x)))
<span class="return">thread
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name=''></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>nil</span> <span class='args'></span>
    <div class='desc'>nil represents false.  it is equivalent to '()</div>
    </td>
    <td class='arc'><pre>
&gt;(is nil '())
<span class="return">t
</span></pre>
<pre>
&gt;(type nil)
<span class="return">sym
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='t'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>t</span> <span class='args'></span>
    <div class='desc'>t represents true.  Any non-nil value will evaluate as true in a
  conditional, including 0 and the empty string.</div>
    </td>
    <td class='arc'><pre>
&gt;(no t)
<span class="return">nil
</span></pre>
<pre>
&gt;(type t)
<span class="return">sym
</span></pre>
  </td></tr>
</table>
<h2>Type handling</h2>
Arc has functions to convert types and to determine the type of an
object.
<p><table class='arc'>
  <tr>
    <td class='arc'><a name='coerce'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>coerce</span> <span class='args'>obj type [args]</span>
    <div class='desc'>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.</div>
    </td>
    <td class='arc'><pre>
&gt;(coerce "a" 'sym)
<span class="return">a
</span></pre>
<pre>
&gt;(coerce 65 'char)
<span class="return">#\A
</span></pre>
<pre>
&gt;(coerce 65 'int 2)
<span class="return">65
</span></pre>
<pre>
&gt;(coerce "abc" 'cons)
<span class="return">(#\a #\b #\c)
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='type'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>type</span> <span class='args'>object</span>
    <div class='desc'>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.</div>
    </td>
    <td class='arc'><pre>
&gt;(type 1)
<span class="return">int
</span></pre>
<pre>
&gt;(type car)
<span class="return">fn
</span></pre>
  </td></tr>
</table>
<h2>Special forms</h2>
Arc defines a small number of special forms, which are evaluated
  specially.
<p><table class='arc'>
  <tr>
    <td class='arc'><a name='fn'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>fn</span> <span class='args'>args [body ...]</span>
    <div class='desc'>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 ).</div>
    </td>
    <td class='arc'><pre>
&gt;((fn (x y) (+ x y)) 1 2)
<span class="return">3
</span></pre>
<pre>
&gt;((fn all (len all)) 1 2 3)
<span class="return">3
</span></pre>
<pre>
&gt;((fn (arg1 arg2 . rest) rest) 1 2 3 4)
<span class="return">(3 4)
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='if'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>if</span> <span class='args'>[test expr] ... [else-expr]</span>
    <div class='desc'>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.</div>
    </td>
    <td class='arc'><pre>
&gt;(if nil "Nil is true"
    0   "0 is true"
    "What is true?")
<span class="return">"0 is true"
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='quasiquote'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>quasiquote</span> <span class='args'>arg</span>
    <div class='desc'> 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.</div>
    </td>
    <td class='arc'><pre>
&gt;`((+ 1 2) ,(+ 3 4) ,@(list 5 6))
<span class="return">((+ 1 2) 7 5 6)
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='quote'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>quote</span> <span class='args'>arg</span>
    <div class='desc'> The single quote ' is shorthand for quote, e.g. 'x is the same as (quote x) </div>
    </td>
    <td class='arc'><pre>
&gt;'(1 2 3)
<span class="return">(1 2 3)
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='assign'></a>
<img src='foundation.gif' title='Foundation'/>
<img src='destructive.gif' title='Destructive'/>
<span class='op'>assign</span> <span class='args'>variable val</span>
    <div class='desc'>assign is used to assign a value to a variable.</div>
    </td>
    <td class='arc'><pre>
&gt;(assign x 10)
<span class="return">10
</span></pre>
  </td></tr>
</table>
<h2>Invoking a type</h2>
Arc permits lists, tables, and strings to be used as functions.
<p><table class='arc'>
  <tr>
    <td class='arc'><a name='procedure'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>procedure</span> <span class='args'>[arg ...]</span>
    <div class='desc'>Invokes the procedure or macro.</div>
    </td>
    <td class='arc'><pre>
&gt;(sqrt 2)
<span class="return">1.4142135623730951
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='list'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>list</span> <span class='args'>n</span>
    <div class='desc'>Returns the nth element of the list.</div>
    </td>
    <td class='arc'><pre>
&gt;('(a b c) 1)
<span class="return">b
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='table'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>table</span> <span class='args'>value [default]</span>
    <div class='desc'>Looks up the value in the table.  Returns nil (or default) if the
  element is not present in the table.</div>
    </td>
    <td class='arc'><pre>
&gt;(let tbl (table)
  (= (tbl 3) 9)
  (= (tbl 4) 16)
  (tbl 3))
<span class="return">9
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='string'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>string</span> <span class='args'>n</span>
    <div class='desc'>Returns the nth character of the string.</div>
    </td>
    <td class='arc'><pre>
&gt;("abc" 1)
<span class="return">#\b
</span></pre>
  </td></tr>
</table>
<h2>  Predicates </h2>
Arc includes multiple predicates.  The dead and ssyntax predicates are
  listed elsewhere.
<p><table class='arc'>
  <tr>
    <td class='arc'><a name='<'></a>
<img src='foundation.gif' title='Foundation'/>
<img src='predicate.gif' title='Predicate'/>
<span class='op'><</span> <span class='args'>arg arg [...]</span>
    <div class='desc'>Less than comparison.  Applies to numbers, strings, symbols, or
  chars.  If multiple arguments are given, the sequence must be monotonically
  increasing.</div>
    </td>
    <td class='arc'><pre>
&gt;(&lt; 1 2)
<span class="return">t
</span></pre>
<pre>
&gt;(&lt; 1 2 3)
<span class="return">t
</span></pre>
<pre>
&gt;(&lt; 1 3 2)
<span class="return">nil
</span></pre>
<pre>
&gt;(&lt; "a" "b")
<span class="return">t
</span></pre>
<pre>
&gt;(&lt; 'a 'b)
<span class="return">t
</span></pre>
<pre>
&gt;(&lt; #\a #\b)
<span class="return">t
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='>'></a>
<img src='foundation.gif' title='Foundation'/>
<img src='predicate.gif' title='Predicate'/>
<span class='op'>></span> <span class='args'>arg arg [...]</span>
    <div class='desc'>Greater than comparison.  Applies to numbers, strings, symbols, or
  chars.  If multiple arguments are given, the sequence must be monotonically
  decreasing.</div>
    </td>
    <td class='arc'><pre>
&gt;(&gt; 1 2)
<span class="return">nil
</span></pre>
<pre>
&gt;(&gt; 3 1 2)
<span class="return">nil
</span></pre>
<pre>
&gt;(&gt; "a" "b")
<span class="return">nil
</span></pre>
<pre>
&gt;(> 'a 'b)
<span class="return">nil
</span></pre>
<pre>
&gt;(&gt; #\a #\b)
<span class="return">nil
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='bound'></a>
<img src='foundation.gif' title='Foundation'/>
<img src='predicate.gif' title='Predicate'/>
<span class='op'>bound</span> <span class='args'>symbol</span>
    <div class='desc'>Tests if a symbol is bound.</div>
    </td>
    <td class='arc'><pre>
&gt;(bound 'foobar)
<span class="return">nil
</span></pre>
<pre>
&gt;(do
       (assign y 1)
       (bound 'y))
<span class="return">t
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='exact'></a>
<img src='foundation.gif' title='Foundation'/>
<img src='predicate.gif' title='Predicate'/>
<span class='op'>exact</span> <span class='args'>value</span>
    <div class='desc'>Tests if the value is an exact integer.</div>
    </td>
    <td class='arc'><pre>
&gt;(exact 3)
<span class="return">t
</span></pre>
<pre>
&gt;(exact 3.14)
<span class="return">nil
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='is'></a>
<img src='foundation.gif' title='Foundation'/>
<img src='predicate.gif' title='Predicate'/>
<span class='op'>is</span> <span class='args'>val [val ...] </span>
    <div class='desc'>Tests equality with eqv?</div>
    </td>
    <td class='arc'><pre>
&gt;(is 1 2)
<span class="return">nil
</span></pre>
<pre>
&gt;(is "a" "a")
<span class="return">t
</span></pre>
<pre>
&gt;(is '(1) '(1))
<span class="return">nil
</span></pre>
<pre>
&gt;(is 1 1 1 1)
<span class="return">t
</span></pre>
<pre>
&gt;(is nil '())
<span class="return">t
</span></pre>
  </td></tr>
</table>
<h2>  List operations </h2>
The traditional list operations are supported.  Some of the operations
  also apply to strings.
<p><table class='arc'>
  <tr>
    <td class='arc'><a name='car'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>car</span> <span class='args'>list</span>
    <div class='desc'>First element of list</div>
    </td>
    <td class='arc'><pre>
&gt;(car '(1 2 3))
<span class="return">1
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='cdr'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>cdr</span> <span class='args'>list</span>
    <div class='desc'>Remainder of list.</div>
    </td>
    <td class='arc'><pre>
&gt;(cdr '(1 2 3))
<span class="return">(2 3)
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='cons'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>cons</span> <span class='args'>element list</span>
    <div class='desc'>Prepends element to list.</div>
    </td>
    <td class='arc'><pre>
&gt;(cons 1 '(2 3))
<span class="return">(1 2 3)
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='newstring'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>newstring</span> <span class='args'>length [char]</span>
    <div class='desc'>Creates a string of the given length.</div>
    </td>
    <td class='arc'><pre>
&gt;(newstring 5 #\a)
<span class="return">"aaaaa"
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='scar'></a>
<img src='foundation.gif' title='Foundation'/>
<img src='destructive.gif' title='Destructive'/>
<span class='op'>scar</span> <span class='args'>list value</span>
    <div class='desc'>Sets car of list to new value.  If applied to a
  string, assigns to the first character of the string, which must have length at
  least one.</div>
    </td>
    <td class='arc'><pre>
&gt;(do
    (= x "abc")
    (scar x #\d)
    x)
<span class="return">"dbc"
</span></pre>
<pre>
&gt;(do
    (= x '(1 2 3))
    (scar x #\d)
    x)
<span class="return">(#\d 2 3)
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='scdr'></a>
<img src='foundation.gif' title='Foundation'/>
<img src='destructive.gif' title='Destructive'/>
<span class='op'>scdr</span> <span class='args'>list value</span>
    <div class='desc'>Sets cdr of a list.</div>
    </td>
    <td class='arc'><pre>
&gt;(do
    (= x '(1 2 3))
    (scdr x '(4))
    x)
<span class="return">(1 4)
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='sref'></a>
<img src='foundation.gif' title='Foundation'/>
<img src='destructive.gif' title='Destructive'/>
<span class='op'>sref</span> <span class='args'>object value index</span>
    <div class='desc'>Sets indexed entry in a list, string, or hash table to
  the given value.</div>
    </td>
    <td class='arc'><pre>
&gt;(do
    (= x "abc")
    (sref x #\d 1) x)
<span class="return">"adc"
</span></pre>
<pre>
&gt;(do
    (= x '(1 2 3))
    (sref x #\d 1) x)
<span class="return">(1 #\d 3)
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='len'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>len</span> <span class='args'>obj</span>
    <div class='desc'>Computes the length of a list, string, or hash table.</div>
    </td>
    <td class='arc'><pre>
&gt;(len "abc")
<span class="return">3
</span></pre>
<pre>
&gt;(len '(1 2 3))
<span class="return">3
</span></pre>
  </td></tr>
</table>
<h2> Math operations </h2>
The math operations of Arc are fairly limited.  Many expected
  operations, such as trigonometry, are missing.
<p><table class='arc'>
  <tr>
    <td class='arc'><a name='*'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>*</span> <span class='args'>args</span>
    <div class='desc'>Multiplication.</div>
    </td>
    <td class='arc'><pre>
&gt;(* 2 3)
<span class="return">6
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='%2b'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>+</span> <span class='args'>args</span>
    <div class='desc'>Addition.  This operator also performs string and list
  concatenation.</div>
    </td>
    <td class='arc'><pre>
&gt;(+ 1 2 3)
<span class="return">6
</span></pre>
<pre>
&gt;(+ "ab" "c" "de")
<span class="return">"abcde"
</span></pre>
<pre>
&gt;(+ '(1 2) '(3 4) '(5))
<span class="return">(1 2 3 4 5)
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='-'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>-</span> <span class='args'>args</span>
    <div class='desc'>Subtraction.</div>
    </td>
    <td class='arc'><pre>
&gt;(- 3 2)
<span class="return">1
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='/'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>/</span> <span class='args'>args</span>
    <div class='desc'>Division</div>
    </td>
    <td class='arc'><pre>
&gt;(/ 1 2)
<span class="return">1/2
</span></pre>
<pre>
&gt;(/ 1.0 2)
<span class="return">0.5
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='cos'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>cos</span> <span class='args'>arg</span>
    <div class='desc'>Cosine function.  New in arc3.</div>
    </td>
    <td class='arc'><pre>
&gt;(cos 3.14)
<span class="return">-0.9999987317275395
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='expt'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>expt</span> <span class='args'>base exponent</span>
    <div class='desc'>Exponentiation.</div>
    </td>
    <td class='arc'><pre>
&gt;(expt 2 3)
<span class="return">8
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='log'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>log</span> <span class='args'>arg</span>
    <div class='desc'>Natuarl logarithm function.  New in arc3.</div>
    </td>
    <td class='arc'><pre>
&gt;(log 100)
<span class="return">4.605170185988092
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='mod'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>mod</span> <span class='args'>dividend divisor</span>
    <div class='desc'>  </div>
    </td>
    <td class='arc'><pre>
&gt;(mod 10 3)
<span class="return">1
</span></pre>
<pre>
&gt;(mod -10 3)
<span class="return">2
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='rand'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>rand</span> <span class='args'>[max] </span>
    <div class='desc'>Returns a random number between 0 and 1, or between 0 and
  the specified integer (excluding the integer).</div>
    </td>
    <td class='arc'><pre>
&gt;(rand 10)
<span class="return">2
</span></pre>
<pre>
&gt;(rand)
<span class="return">0.8056925860196488
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='sin'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>sin</span> <span class='args'>arg</span>
    <div class='desc'>Sine function.  New in arc3.</div>
    </td>
    <td class='arc'><pre>
&gt;(sin 3.14)
<span class="return">0.0015926529164868282
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='sqrt'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>sqrt</span> <span class='args'>number</span>
    <div class='desc'>Square root operation</div>
    </td>
    <td class='arc'><pre>
&gt;(sqrt 2)
<span class="return">1.4142135623730951
</span></pre>
<pre>
&gt;(sqrt -1)
<span class="return">0+1i
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='tan'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>tan</span> <span class='args'>arg</span>
    <div class='desc'>Tangent function.  New in arc3.</div>
    </td>
    <td class='arc'><pre>
&gt;(tan 3.14)
<span class="return">-0.001592654936407223
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='trunc'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>trunc</span> <span class='args'>number</span>
    <div class='desc'>Truncates to an integer.  Was 'truncate' in arc0.</div>
    </td>
    <td class='arc'><pre>
&gt;(trunc 1.9)
<span class="return">1
</span></pre>
<pre>
&gt;(trunc -1.1)
<span class="return">-1
</span></pre>
  </td></tr>
</table>
<h2> Table operations </h2>
Arc provides support for hash tables.
<p><table class='arc'>
  <tr>
    <td class='arc'><a name='maptable'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>maptable</span> <span class='args'>proc table </span>
    <div class='desc'>Applies proc to each element of the table.</div>
    </td>
    <td class='arc'><pre>
&gt;(let x (table)
    (sref x 9 3)
    (sref x 16 4)
    (maptable (fn (key val) (prn key " " val)) x))
<span class="stdout">4 16
3 9

</span><span class="return">#hash((3 . 9) (4 . 16))
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='table'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>table</span> <span class='args'></span>
    <div class='desc'>Creates a hash table.</div>
    </td>
    <td class='arc'><pre>
&gt;(table)
<span class="return">#hash()
</span></pre>
  </td></tr>
</table>
<h2>Evaluation</h2>
Arc introduces several special syntax forms of expression, using the
  symbolx : ! . or ~.
<p><table class='arc'>
  <tr>
    <td class='arc'><a name='eval'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>eval</span> <span class='args'>expression</span>
    <div class='desc'>Evaluates the expression.</div>
    </td>
    <td class='arc'><pre>
&gt;(eval '(+ 1 2))
<span class="return">3
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='apply'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>apply</span> <span class='args'>fn arglist</span>
    <div class='desc'>Applies the function to the arguments.</div>
    </td>
    <td class='arc'><pre>
&gt;(apply + '(1 2))
<span class="return">3
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='ssexpand'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>ssexpand</span> <span class='args'>symbol</span>
    <div class='desc'>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.</div>
    </td>
    <td class='arc'><pre>
&gt;(ssexpand 'x:~y:z)
<span class="return">(compose x (complement y) z)
</span></pre>
<pre>
&gt;(ssexpand '+.1.2)
<span class="return">((+ 1) 2)
</span></pre>
<pre>
&gt;(ssexpand '+!1!2)
<span class="return">((+ (quote 1)) (quote 2))
</span></pre>
<pre>
&gt;(ssexpand 'cons!a!b)
<span class="return">((cons (quote a)) (quote b))
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='ssyntax'></a>
<img src='foundation.gif' title='Foundation'/>
<img src='predicate.gif' title='Predicate'/>
<span class='op'>ssyntax</span> <span class='args'>symbol</span>
    <div class='desc'>Tests if the symbol contains special syntax (: ! . or ~).</div>
    </td>
    <td class='arc'><pre>
&gt;(ssyntax 'x:y)
<span class="return">t
</span></pre>
  </td></tr>
</table>
<h2>Macros</h2>
Arc's macro system is more similar to Lisp than to Scheme.  Note that
  the 'mac' function is not part of the core, but is implemented on top of the
  core functions described below.
<p><table class='arc'>
  <tr>
    <td class='arc'><a name='annotate'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>annotate</span> <span class='args'>type obj</span>
    <div class='desc'>Tags the object with the given type.  Only used for
  macros.</div>
    </td>
    <td class='arc'><pre>
&gt;(type (annotate 'mac car))
<span class="return">mac
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='macex'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>macex</span> <span class='args'>macro</span>
    <div class='desc'>Expands a macro.</div>
    </td>
    <td class='arc'><pre>
&gt;(macex '(let a 1 (pr a)))
<span class="return">((fn (a) (pr a)) 1)
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='macex1'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>macex1</span> <span class='args'> macro</span>
    <div class='desc'>Expands a macro to one level.</div>
    </td>
    <td class='arc'><pre>
&gt;(macex1 '(let a 1 (pr a)))
<span class="return">(with (a 1) (pr a))
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='rep'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>rep</span> <span class='args'>obj</span>
    <div class='desc'>Returns the underlying object for an annotated object</div>
    </td>
    <td class='arc'><pre>
&gt;(rep whilet)
<span class="return">#&lt;procedure: whilet&gt;
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='sig'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>sig</span> <span class='args'> </span>
    <div class='desc'>Hash table containing function signatures.</div>
    </td>
    <td class='arc'><pre>
&gt;(sig 'map)
<span class="return">(f . seqs)
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='uniq'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>uniq</span> <span class='args'> </span>
    <div class='desc'>Generates a unique symbol.</div>
    </td>
    <td class='arc'><pre>
&gt;(uniq)
<span class="return">gs2482
</span></pre>
  </td></tr>
</table>
<h2>I/O</h2>
Arc has a large variety of I/O operations.  They can be used for file I/O,
  string I/O, or network I/O.
<p><table class='arc'>
  <tr>
    <td class='arc'><a name='call-w/stdin'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>call-w/stdin</span> <span class='args'>input-port thunk</span>
    <div class='desc'>Calls thunk, setting current-input-port
  to the specified port.</div>
    </td>
    <td class='arc'><pre>
&gt;(call-w/stdin (instring "Hello") readline)
<span class="return">"Hello"
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='call-w/stdout'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>call-w/stdout</span> <span class='args'>output-port thunk</span>
    <div class='desc'>Calls thunk, setting current-input-port
  to the specified port.</div>
    </td>
    <td class='arc'><pre>
&gt;(let sop (outstring)
  (call-w/stdout sop (fn () (prn '(1 2))))
  (inside sop))
<span class="return">"(1 2)\n"
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='close'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>close</span> <span class='args'>port [...]</span>
    <div class='desc'>Closes an input-port, output-port or tcp-listener.  Will wait for a TCP output port to drain.</div>
    </td>
    <td class='arc'><pre>
&gt;(close (outfile "/tmp/junk"))
<span class="return">nil
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='force-close'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>force-close</span> <span class='args'>port [...]</span>
    <div class='desc'>Closes an input-port, output-port or tcp-listener.  Will discard any buffered output.  New in arc3.</div>
    </td>
    <td class='arc'><pre>
&gt;(close (outfile "/tmp/junk"))
<span class="return">nil
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='disp'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>disp</span> <span class='args'>[arg [output-port]]</span>
    <div class='desc'>Displays the argument on the output-port (or
  current-output-port) using Scheme's display procedure.</div>
    </td>
    <td class='arc'><pre>
&gt;(disp '(1 2))
<span class="stdout">(1 2)
</span><span class="return">nil
</span></pre>
<pre>
&gt;(disp "abc")
<span class="stdout">abc
</span><span class="return">nil
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='peekc'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>peekc</span> <span class='args'>input-port</span>
    <div class='desc'>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.</div>
    </td>
    <td class='arc'><pre>
&gt;(peekc (pipe-from "echo hello"))
<span class="return">#\h
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='flushout'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>flushout</span> <span class='args'></span>
    <div class='desc'>Flushes output.  New in arc3.</div>
    </td>
    <td class='arc'><pre>
&gt;(flushout)
<span class="return">t
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='pipe-from'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>pipe-from</span> <span class='args'>command</span>
    <div class='desc'>Executes command in the underlying OS.  Then opens
  an input-port to the results.</div>
    </td>
    <td class='arc'><pre>
&gt;(readline (pipe-from "echo hello"))
<span class="return">"hello"
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='readb'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>readb</span> <span class='args'>[input-port]</span>
    <div class='desc'>Reads a byte from the input-port (or default of
  current-input-port).  Returns nil on end-of-file.</div>
    </td>
    <td class='arc'><pre>
&gt;(readb (pipe-from "echo hello"))
<span class="return">104
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='readc'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>readc</span> <span class='args'>[input-port]</span>
    <div class='desc'>Reads a character from the input-port (or default of
  current-input-port).  Returns nil on end-of-file.</div>
    </td>
    <td class='arc'><pre>
&gt;(readc (pipe-from "echo ©"))
<span class="return">#\©
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='sread'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>sread</span> <span class='args'>input-port eof-value</span>
    <div class='desc'>Reads a Scheme object from the input port.  Returns eof-value
  on end-of-file.</div>
    </td>
    <td class='arc'><pre>
&gt;(sread (pipe-from "echo '(1 2) (3)'") "junk")
<span class="return">(1 2)
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='stderr'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>stderr</span> <span class='args'></span>
    <div class='desc'>current-error-port: returns the output-port stderr</div>
    </td>
    <td class='arc'><pre>
&gt;(stderr)
<span class="return">#&lt;output-port:stderr&gt;
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='stdin'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>stdin</span> <span class='args'></span>
    <div class='desc'>current-input-port: returns the input-port stdin</div>
    </td>
    <td class='arc'><pre>
&gt;(stdin)
<span class="return">#&lt;input-port:stdin&gt;
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='stdout'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>stdout</span> <span class='args'></span>
    <div class='desc'>current-output-port: returns the output-port stdout</div>
    </td>
    <td class='arc'><pre>
&gt;(stdout)
<span class="return">#&lt;output-port:string&gt;
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='write'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>write</span> <span class='args'>[arg [output-port]]</span>
    <div class='desc'>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
  <a
  href='http://download.plt-scheme.org/doc/372/html/mzscheme/mzscheme.html#node_toc_node_sec_11.2.5'>Default
  Printer</a> documentation for details.</div>
    </td>
    <td class='arc'><pre>
&gt;(write "abc")
<span class="stdout">"abc"
</span><span class="return">nil
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='writeb'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>writeb</span> <span class='args'>int [output-port]</span>
    <div class='desc'>Writes the byte to the output-port (or
  default of current-output-port).</div>
    </td>
    <td class='arc'><pre>
&gt;(writeb 65)
<span class="stdout">A
</span><span class="return">65
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='writec'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>writec</span> <span class='args'>char [output-port]</span>
    <div class='desc'>Writes the character to the output-port (or
  default of current-output-port).</div>
    </td>
    <td class='arc'><pre>
&gt;(writec #\日)
<span class="stdout">日
</span><span class="return">#\日
</span></pre>
  </td></tr>
</table>
<h2>String Port I/O</h2>

See <a
href='http://download.plt-scheme.org/doc/372/html/mzscheme/mzscheme-Z-H-11.html#node_sec_11.1.5'>String
Ports</a> for background on String Port I/O.  
<p><table class='arc'>
  <tr>
    <td class='arc'><a name='inside'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>inside</span> <span class='args'>string-output-port</span>
    <div class='desc'>Returns (as a string) the bytes accumulated
  in a string-output-port generated by outstring.  This is MzScheme's get-output-string.</div>
    </td>
    <td class='arc'><pre>
&gt;(let sop (outstring) (write "hello" sop) (inside sop))
<span class="return">"\"hello\""
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='instring'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>instring</span> <span class='args'>string [name]</span>
    <div class='desc'>Creates an input port to read UTF-8 bytes from the
  string.  This is MzScheme's open-input-string.</div>
    </td>
    <td class='arc'><pre>
&gt;(readline (instring "hello"))
<span class="return">"hello"
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='outstring'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>outstring</span> <span class='args'>[name]</span>
    <div class='desc'>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.</div>
    </td>
    <td class='arc'><pre>
&gt;(outstring)
<span class="return">#&lt;output-port:string&gt;
</span></pre>
  </td></tr>
</table>
<h2>Networking</h2>
Arc's networking functions are limited to those necessary to support a
  web server.  In particular, there is no support for outgoing network
  connections.
<p><table class='arc'>
  <tr>
    <td class='arc'><a name='client-ip'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>client-ip</span> <span class='args'>tcp-output-port </span>
    <div class='desc'>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.</div>
    </td>
    <td class='arc'><pre>
&gt;(let s (socket-accept (open-socket 8080))
    (client-ip (s 1)))
"10.2.40.71"
</pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='open-socket'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>open-socket</span> <span class='args'>port</span>
    <div class='desc'>Opens a tcp-listener on the given port.</div>
    </td>
    <td class='arc'><pre>
&gt;(open-socket 8000)
<span class="stdout">Error: tcp-listen: listen failed
  port number: 8000
  syste
m error: Address already in use; errno=98

</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='socket-accept'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>socket-accept</span> <span class='args'>tcp-port</span>
    <div class='desc'>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)</div>
    </td>
    <td class='arc'><pre>
&gt;(socket-accept (open-socket 8080))
(#&lt;input-port&gt; #&lt;output-port&gt; "10.2.40.71")
</pre>
  </td></tr>
</table>
<h2>File system operations</h2>
The I/O operations are closely related to MzScheme's <a
href='http://download.plt-scheme.org/doc/mzscheme/mzscheme-Z-H-11.html#node_chap_11'>I/O
operations</a>.
<p><table class='arc'>
  <tr>
    <td class='arc'><a name='dir'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>dir</span> <span class='args'>path</span>
    <div class='desc'>Returns the directory contents as a list.</div>
    </td>
    <td class='arc'><pre>
&gt;(dir "mydir")
<span class="return">("foo")
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='dir-exists'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>dir-exists</span> <span class='args'>path</span>
    <div class='desc'>Tests if a directory exists.</div>
    </td>
    <td class='arc'><pre>
&gt;(dir-exists "mydir")
<span class="return">"mydir"
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='file-exists'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>file-exists</span> <span class='args'>path</span>
    <div class='desc'>Tests if a file exists.</div>
    </td>
    <td class='arc'><pre>
&gt;(file-exists "mydir")
<span class="return">nil
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='infile'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>infile</span> <span class='args'>filename ['binary | 'text]</span>
    <div class='desc'>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.)</div>
    </td>
    <td class='arc'><pre>
&gt;(outfile "/tmp/junk" 'append)
<span class="return">#&lt;output-port:/tmp/junk&gt;
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='outfile'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>outfile</span> <span class='args'>filename ['append]</span>
    <div class='desc'>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.</div>
    </td>
    <td class='arc'><pre>
&gt;(outfile "/tmp/junk" 'append)
<span class="return">#&lt;output-port:/tmp/junk&gt;
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='mvfile'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>mvfile</span> <span class='args'>path</span>
    <div class='desc'>Moves the specified file. New in arc3.</div>
    </td>
    <td class='arc'><pre>
&gt;(mvfile "/tmp/junk" "/tmp/newjunk")
<span class="return">nil
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='rmfile'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>rmfile</span> <span class='args'>path</span>
    <div class='desc'>Removes the specified file.</div>
    </td>
    <td class='arc'><pre>
&gt;(rmfile "/tmp/newjunk")
<span class="return">nil
</span></pre>
  </td></tr>
</table>
<h2>Threading</h2>
See <a
  href='http://download.plt-scheme.org/doc/372/html/mzscheme/mzscheme-Z-H-7.html#node_chap_7'>MzScheme's
  Threads</a> for details of the threading model.
<p><table class='arc'>
  <tr>
    <td class='arc'><a name='atomic-invoke'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>atomic-invoke</span> <span class='args'>function</span>
    <div class='desc'>Invokes function, making sure that only one
  thread at a time invokes something wrapped inside an atomic-invoke.</div>
    </td>
    <td class='arc'><pre>
&gt;(atomic-invoke (fn () "critical section" (+ 1 2)))
<span class="return">3
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='break-thread'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>break-thread</span> <span class='args'>thread</span>
    <div class='desc'>Triggers a break exception on a thread.</div>
    </td>
    <td class='arc'><pre>
&gt;(let th (new-thread (fn () (sleep 2)))
  (break-thread th))
user break
</pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='dead'></a>
<img src='foundation.gif' title='Foundation'/>
<img src='predicate.gif' title='Predicate'/>
<span class='op'>dead</span> <span class='args'>thread</span>
    <div class='desc'>Predicate to test if a thread has terminated.</div>
    </td>
    <td class='arc'><pre>
&gt;(let th (new-thread (fn () (sleep 1)))
  (prn (dead th)) (sleep 2) (prn (dead th)))
<span class="stdout">nil
t

</span><span class="return">t
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='kill-thread'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>kill-thread</span> <span class='args'>thread</span>
    <div class='desc'>Terminates the specified thread immediately.</div>
    </td>
    <td class='arc'><pre>
&gt;(let th (new-thread (fn () (sleep 100)))
    (kill-thread th)
    (dead th))
<span class="return">t
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='new-thread'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>new-thread</span> <span class='args'>procedure</span>
    <div class='desc'>Creates and returns a new thread.  Was 'thread'
  in arc0.</div>
    </td>
    <td class='arc'><pre>
&gt;(new-thread (fn () (+ 1 2)))
<span class="return">#&lt;thread:...t/private/kw.rkt:592:14&gt;
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='sleep'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>sleep</span> <span class='args'>secs</span>
    <div class='desc'>Causes the current thread to sleep for at least the
  specified time.</div>
    </td>
    <td class='arc'><pre>
&gt;(sleep 0.1)
<span class="return">nil
</span></pre>
  </td></tr>
</table>
<h2>Error handling and continuations</h2>
The control flow operations of Arc are somewhat complex.
  See the MzScheme manual on <a
  href='http://download.plt-scheme.org/doc/mzscheme/mzscheme-Z-H-6.html#node_chap_6'>exceptions
  and control flow</a> for details.
<p><table class='arc'>
  <tr>
    <td class='arc'><a name='details'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>details</span> <span class='args'>exception</span>
    <div class='desc'>Returns the message associated with an exception.</div>
    </td>
    <td class='arc'><pre>
&gt;(on-err (fn (ex) (details ex)) (err "boo"))
<span class="stdout">Error: boo

</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='err'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>err</span> <span class='args'>string ...</span>
    <div class='desc'>Raises an exception with the given text.</div>
    </td>
    <td class='arc'><pre>
&gt;(err "Failure" 42)
<span class="stdout">Error: Failure 42

</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='on-err'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>on-err</span> <span class='args'>err-proc proc</span>
    <div class='desc'>Executes proc.  Calls err-proc if an exception
  occurs in proc.  The exception is passed to err-proc</div>
    </td>
    <td class='arc'><pre>
&gt;(on-err (fn (ex) (string "caught " (details ex)))
          (fn () (/ 1 0)))
<span class="return">"caught /: division by zero"
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='ccc'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>ccc</span> <span class='args'>procedure</span>
    <div class='desc'>Packages up the current continuation into an 'escape
  procedure' and passes it to the procedure.  Equivalent to Scheme's call/cc or <a
  href='http://www.schemers.org/Documents/Standards/R5RS/HTML/r5rs-Z-H-9.html#%_idx_566'>call-with-current-continuation</a>.</div>
    </td>
    <td class='arc'><pre>
&gt;(ccc (fn (ep) (ep "bailout value") 42))
<span class="return">"bailout value"
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='protect'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>protect</span> <span class='args'>during-procedure after-procedure</span>
    <div class='desc'>Uses Scheme's
  <a
  href='http://www.schemers.org/Documents/Standards/R5RS/HTML/r5rs-Z-H-9.html#%_idx_576'>dynamic-wind</a> to
  ensure that after-procedure is executed whenever during-procedure exits.</div>
    </td>
    <td class='arc'><pre>
&gt;(protect (fn () (/ 1 0))
    (fn () (prn "after")))
<span class="stdout">after
Error: /: division by zero

</span></pre>
  </td></tr>
</table>
<h2>Time</h2>
Arc includes several functions related to time.
<p><table class='arc'>
  <tr>
    <td class='arc'><a name='current-gc-milliseconds'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>current-gc-milliseconds</span> <span class='args'> </span>
    <div class='desc'>Returns the amount of time spent in garbage
  collection.
  See <a
  href='http://download.plt-scheme.org/doc/372/html/mzscheme/mzscheme-Z-H-15.html#node_sec_15.1'>MzScheme</a>
  for more details on Arc's time functions.</div>
    </td>
    <td class='arc'><pre>
&gt;(current-gc-milliseconds)
<span class="return">363
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='current-process-milliseconds'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>current-process-milliseconds</span> <span class='args'></span>
    <div class='desc'>Returns the number of milliseconds of
  processor time used.</div>
    </td>
    <td class='arc'><pre>
&gt;(current-process-milliseconds)
<span class="return">9278
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='msec'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>msec</span> <span class='args'></span>
    <div class='desc'>Returns current time in milliseconds.  The time is from an
  arbitrary starting date, and can wrap or be negative.</div>
    </td>
    <td class='arc'><pre>
&gt;(msec)
<span class="return">1535272016448
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='seconds'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>seconds</span> <span class='args'> </span>
    <div class='desc'>Returns current time in seconds, from a platform-specific
  starting date.</div>
    </td>
    <td class='arc'><pre>
&gt;(seconds)
<span class="return">1535272016
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='timedate'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>timedate</span> <span class='args'>[secs]</span>
    <div class='desc'>Converts time to string; default is current time.  New in arc3.</div>
    </td>
    <td class='arc'><pre>
&gt;(timedate)
<span class="return">(56 26 8 26 8 2018)
</span></pre>
<pre>
&gt;(timedate 0)
<span class="return">(0 0 0 1 1 1970)
</span></pre>
  </td></tr>
</table>
<h2>Other OS Operations</h2>
The following are miscellaneous operating system operations.
<p><table class='arc'>
  <tr>
    <td class='arc'><a name='declare'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>declare</span> <span class='args'>key value</span>
    <div class='desc'>Sets an interpreter option.  The key <code>direct-calls</code>, when set to t, optimizes function calls on the assumption they will not be redefined as table.  The key <code>explicit-flush</code>, when set to t, disables automatic flushing of output, requiring explicit flushout calls.  Both are initializes to nil.  New in arc3.</div>
    </td>
    <td class='arc'><pre>
&gt;(declare direct-calls t)
<span class="stdout">Error: _direct-calls: undefined;
 cannot reference an identi
fier before its definition
  in module: top-level
  internal
 name: _direct-calls

</span></pre>
<pre>
&gt;(declare explicit-flush t)
<span class="stdout">Error: _explicit-flush: undefined;
 cannot reference an iden
tifier before its definition
  in module: top-level
  intern
al name: _explicit-flush

</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='memory'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>memory</span> <span class='args'></span>
    <div class='desc'>Returns the current memory usage.  New in arc3.</div>
    </td>
    <td class='arc'><pre>
&gt;(memory)
<span class="return">59382768
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='system'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>system</span> <span class='args'>string</span>
    <div class='desc'>Executes the string in the underlying OS.</div>
    </td>
    <td class='arc'><pre>
&gt;(system "date #/t")
<span class="stdout">Sun Aug 26 08:26:56 GMT 2018

</span><span class="return">nil
</span></pre>
  </td></tr>
  <tr>
    <td class='arc'><a name='quit'></a>
<img src='foundation.gif' title='Foundation'/>
<span class='op'>quit</span> <span class='args'></span>
    <div class='desc'>Exits the interpreter.</div>
    </td>
    <td class='arc'><pre>
&gt;(quit)
--exits--
</pre>
  </td></tr>
</table>
<h3>Legend</h3>
<img src='/doc/foundation.gif' title='Foundation'/>: Foundation operation.
<br><img src='/doc/macro.gif' title='Macro'/>: Macro.
<br><img src='/doc/proc.gif' title='Procedure'/>: Procedure.
<br><img src='/doc/var.gif' title='Variable'/>: Variable.
<br><img src='/doc/destructive.gif' title='Destructive'/>: Destructive; arguments may be modified.
<br><img src='/doc/predicate.gif' title='Predicate'/>: Predicate.
<br><img src='/doc/code.gif' title='View code'/>: View code.
<p>
Copyright 2008 Ken Shirriff.
</body>
</html>