<?xml version="1.0" encoding="UTF-8"?>

<chapter id="intro"><title>Introduction
  <ulink url="&clhs;/Body/chap-1.html">[CLHS-1]</ulink></title>

<section id="spec-symb"><title>Special Symbols
  <ulink url="&clhs;/Body/sec_1-4-1-3.html">[CLHS-1.4.1.3]</ulink></title>

<para>The final delimiter of an interactive stream: On &unix;, the user
 has to type <keycombo>&ctrl;<keysym>D</keysym></keycombo> at the
 beginning of a line. On &dos; or &win32;, the user has to type
 <keycombo>&ctrl;<keysym>Z</keysym></keycombo>, followed
 by <keycap>Return</keycap>.  This final delimiter is never actually
 seen by programs; no need to test for <keysym>#\^D</keysym> or
 <keysym>#\^Z</keysym> - use &read-char-no-hang; to check for end of
 stream.  Calling &clear-input; on the stream removes the &eos; state,
 thus making it available for further input.</para>

<para>A newline character can be entered by the user by pressing the
 <keycap>Newline</keycap> key or, on the numeric keypad, the
 <keycap>Enter</keycap> key.</para>

</section>


<section id="error-terms"><title>Error Terminology
  <ulink url="&clhs;/Body/sec_1-4-2.html">[CLHS-1.4.2]</ulink></title>

<para>Safety settings are ignored; therefore where the standard uses the
 phrase <quote>should signal an error</quote>, an &error; is signaled.</para>

</section>

<section id="class-prec"><title>Class Precedence Lists
  <ulink url="&clhs;/Body/sec_1-4-4-5.html">[CLHS-1.4.4.5]</ulink></title>

<para>The class precedence lists of the system classes &class;
 &built-in-class;, &structure-class;, &standard-class;,
 &standard-method-class; contain the class &structure-object-class;
 instead of the class &standard-object-class;.</para>

</section>

<section id="cl-symb"><title>Symbols in the Package &cl-pac;
  <ulink url="&clhs;/Body/sec_1-9.html">[CLHS-1.9]</ulink></title>

<para>The 11 symbols missing from the &cl-pac; package
 (out of 978 specified by the &ansi-cl;):</para>

<simplelist type="horiz" columns="3">
 <member>&call-method;</member>
 <member>&change-class;</member>
 <member>&define-method-combination;</member>
 <member>&ensure-generic-function;</member>
 <member>&invalid-method-error;</member>
 <member>&make-instances-obsolete;</member>
 <member>&make-method;</member>
 <member>&method-combination-error;</member>
 <member>&method-combination-class;</member>
 <member>&update-instance-for-different-class;</member>
 <member>&update-instance-for-redefined-class;</member>
</simplelist>

</section>

</chapter>

<chapter id="syntax"><title>Syntax
   <ulink url="&clhs;/Body/chap-2.html">[CLHS-2]</ulink></title>

<section id="tokens"><title>Symbols as Tokens
  <ulink url="&clhs;/Body/sec_2-3-4.html">[CLHS-2.3.4]</ulink></title>

<para>A "reserved token", i.e., a <ulink
 url="&clhs;/Body/glo_t.html#token">token</ulink> that has potential number
 syntax but cannot be interpreted as a number, is interpreted as symbol
 when being read.</para>

<para>When creating a symbol from a token, no character attributes are
 removed.</para>

</section>

<section id="valid-patterns"><title>Valid Patterns for Tokens
  <ulink url="&clhs;/Body/sec_2-3-5.html">[CLHS-2.3.5]</ulink></title>

<para>When a token with package markers is read, then no checking is
 done whether the package part and the symbol-name part do not have
 number syntax. (What's the purpose of this check?) So we consider
 tokens like <token>USER::</token> or <token>:1</token> or
 <token>LISP::4711</token> or <token>21:3</token> as symbols.</para>

</section>

<section id="double-quote"><title>Double-Quote
  <ulink url="&clhs;/Body/sec_2-4-5.html">[CLHS-2.4.5]</ulink></title>

<para>When a string is read, no character attributes are removed.</para>

</section>

<section id="backquote"><title>Backquote
  <ulink url="&clhs;/Body/sec_2-4-6.html">[CLHS-2.4.6]</ulink></title>

<para>The backquote read macro also works when nested. Example:
<informalexample><programlisting>
   (&eval; ``(,#'(&lambda; () ',a) ,#'(&lambda; () ',b)))
 = (&eval; `(list #'(&lambda; () ',a) #'(&lambda; () ',b)))
 = (&eval; (list 'list (list 'function (list 'lambda nil (list 'quote a)))
                     (list 'function (list 'lambda nil (list 'quote b)))))
</programlisting></informalexample></para>

<para>Multiple backquote combinations like <literal>,,@</literal> or
 <literal>,@,@</literal> are not implemented.  Their use would be
 confusing anyway.</para>

</section>

<section id="sharpsign"><title>Sharpsign
  <ulink url="&clhs;/Body/sec_2-4-8.html">[CLHS-2.4.8]</ulink></title>

<para>Reader macros are also defined for the following:

<table id="extra-read-macro-table" frame="all">
  <title>Additional reader macros</title>
 <tgroup cols="2" colsep="1" rowsep="1" align="center">
 <thead><row><entry>Macro</entry><entry>Meaning</entry></row></thead><tbody>
 <row><entry>#,</entry><entry>load-time evaluation</entry></row>
 <row><entry>#Y</entry><entry>function objects and file
  &encoding;s</entry></row>
 <row><entry>#&quot;&quot;</entry><entry>pathname</entry></row>
</tbody></tgroup></table>
</para>

</section>
</chapter>


<chapter id="eval"><title>Evaluation and Compilation
   <ulink url="&clhs;/Body/chap-3.html">[CLHS-3]</ulink></title>

<para>All the functions built by &function;, &compile; and the like are
 atoms.  There are built-in functions written in &c-lang;, compiled
 functions (both of type &compiled-function-type;) and interpreted
 functions (of type &function-class;).</para>

<section id="evaluation"><title>Evaluation
  <ulink url="&clhs;/Body/sec_3-1.html">[CLHS-3.1]</ulink></title>

<section id="eval-environ"><title>Introduction to Environments
  <ulink url="&clhs;/Body/sec_3-1-1.html">[CLHS-3.1.1]</ulink></title>

<formalpara id="the-env"><title>&the-env;</title>
<para>As in Scheme, the macro <literal role="sexp">(&the-env;)</literal>
 returns the current lexical environment.  This works only in
 interpreted code and is not compilable!</para></formalpara>

<formalpara id="eval-env"><title><literal role="sexp">(EXT:EVAL-ENV
 &form-r; &optional-amp; &env-r;)</literal></title>
<para>evaluates a form in a given lexical environment, just as if the
 form had been a part of the program that the environment came from.
</para></formalpara>

</section>
</section>

<section id="compilation"><title>Compilation
  <ulink url="&clhs;/Body/sec_3-2.html">[CLHS-3.2]</ulink></title>

<section id="compiler-terms"><title>Compiler Terminology
  <ulink url="&clhs;/Body/sec_3-2-1.html">[CLHS-3.2.1]</ulink></title>

<para>&clisp; compiles to platform-independent
 <link linkend="bytecode">byte-code</link>.</para>

</section>

<section id="compiler-macros"><title>Compiler Macros
  <ulink url="&clhs;/Body/sec_3-2-2-1.html">[CLHS-3.2.2.1]</ulink></title>

<para>Compiler macros are expanded in the compiled code only, and
ignored by the interpreter.</para>

</section>

<section id="similarity"><title>Definition of Similarity
  <ulink url="&clhs;/Body/sec_3-2-4-2-2.html">[CLHS-3.2.4.2.2]</ulink></title>

<para>Hash tables are <ulink
 url="&clhs;/Body/glo_e.html#externalizable_object">externalizable
 object</ulink>s.</para>

</section>
</section>

<section id="declarations"><title>Declarations
  <ulink url="&clhs;/Body/sec_3-3.html">[CLHS-3.3]</ulink></title>

<para>The declarations
 <literal role="sexp">(&type-dec; &type-r; &var-r; ...)</literal>,
 <literal role="sexp">(&ftype-dec; &type-r;
        &func-r; ...)</literal>,
 <literal role="sexp">(&optimize-dec; (<replaceable>quality</replaceable>
        &value-r;) ...)</literal>
   are ignored by the interpreter and the compiler.</para>

<para>The &ansi-cl; declaration <literal role="sexp">(&optimize-dec;
 (debug ...))</literal> is legal.</para>

<para>The &ansi-cl; declaration <literal role="sexp">(&ignorable-dec;
 &var-r; ...)</literal> affects the variable
 binding for the variable &var-r;.  The compiler
 will not warn about the variable, regardless whether it is used or
 not.</para>

<section id="compile-decl"><title>Additional declarations</title>

<para>The declaration <literal role="sexp">(compile)</literal> has the
 effect that the current form is compiled prior to execution.
 Examples:
<programlisting>
 (&locally; (&declare; (compile)) &form-r;)
</programlisting>
executes a compiled version of form.</para>

<para><programlisting>
(&let; ((x 0))
  (&flet; ((inc () (&declare; (compile)) (&incf; x))
         (dec () (&decf; x)))
    (&values; #'inc #'dec)))
</programlisting>
 returns two functions.  The first is compiled and increments &x-r;, the
 second is interpreted (slower) and decrements the same &x-r;.</para>

<para>The type assertion <literal role="sexp">(&the; &val-type-r;
 &form-r;)</literal> enforces a type check in interpreted code.
 No type check is done in compiled code.  See also the &ethe; macro.</para>

</section>
</section>

<section id="lalist"><title>Lambda Lists
   <ulink url="&clhs;/Body/sec_3-4.html">[CLHS-3.4]</ulink></title>

<section id="boa-lalist"><title>Boa Lambda Lists
  <ulink url="&clhs;/Body/sec_3-4-6.html">[CLHS-3.4.6]</ulink></title>

<para>The initial value of an &aux-amp; variable in a boa &lalist; is
 the value of the corresponding slot's initial form.</para>

</section>
</section>

<section id="eval-comp"><title>The Evaluation and Compilation Dictionary
  <ulink url="&clhs;/Body/sec_3-8.html">[CLHS-3.8]</ulink></title>

<section id="spec-decl"><title>Declaration &special-dec;</title>

<para><literal role="sexp">(&proclaim; '(&special-dec;
 &var-r;))</literal> declarations may not be undone.  The same holds for
 &defvar;, &defparameter; and &defconstant; declarations.</para>

<para>It is an error if a &defconstant; variable is bound at the moment
 the &defconstant; is executed, but &defconstant; does not check
 this.</para>

<para>Constants may not be bound dynamically or lexically.</para>

</section>

<section id="eval-when"><title>Macro &eval-when;</title>

<para>&eval-when; also accepts the situations <literal role="sexp">(not
 eval)</literal> and <literal role="sexp">(not
 compile)</literal>.</para>

</section>

</section>
</chapter>


<chapter id="types-classes"><title>Types and Classes
   <ulink url="&clhs;/Body/chap-4.html">[CLHS-4]</ulink></title>

<section id="types"><title>Types
  <ulink url="&clhs;/Body/sec_4-2.html">[CLHS-4.2]</ulink></title>

<section id="type-spec"><title>Type Specifiers
  <ulink url="&clhs;/Body/sec_4-2-3.html">[CLHS-4.2.3]</ulink></title>

<para>The general form of the &complex-class; type specifier is <literal
 role="sexp">(&complex-class; <replaceable>type-of-real-part</replaceable>
 <replaceable>type-of-imaginary-part</replaceable>)</literal>.  The type
 specifier <literal role="sexp">(&complex-class; &type-r;)</literal> is
 equivalent to <literal role="sexp">(&complex-class; &type-r;
 &type-r;)</literal>.</para>

<para>The &ansi-cl; type specifier <literal role="sexp">(&real-class;
 <replaceable>low</replaceable> <replaceable>high</replaceable>)</literal>
 denotes the real numbers between <replaceable>low</replaceable> and
 <replaceable>high</replaceable>.</para>

<para>&deftype; &lalist;s are subject to destructuring (nested &lalist;s
 are allowed, as in &defmacro;) and may contain a &whole-amp; marker,
 but not an &environment-amp; marker.</para>

<formalpara><title><literal role="sexp">(<function>ext:type-expand</function>
 <replaceable>typespec</replaceable> &optional-amp;
 <replaceable>once-p</replaceable>)</literal></title>
<para>If <replaceable>typespec</replaceable> is a user-defined type,
 this will expand it recursively until it is no longer a user-defined
 type (unless <replaceable>once-p</replaceable> is supplied and
 non-&nil;).  Two values are returned - the expansion and an indicator
 (&t; or &nil;) of whether the original
 <replaceable>typespec</replaceable> was a user-defined type.
</para></formalpara>

<itemizedlist><title>The possible results of &type-of;</title>
 <listitem><simpara>&cons-class;</simpara></listitem>
 <listitem><simpara>&symbol-class;, &null-class;,
  &boolean-type;</simpara></listitem>
 <listitem><simpara>&fixnum-type;, &bignum-type;, &rational-class;,
  &short-float-type;, &single-float-type;, &double-float-type;,
  &long-float-type;, &complex-class;</simpara></listitem>
 <listitem><simpara>&character-class;, &base-char-type;</simpara></listitem>
 <listitem><simpara><literal role="type">(&array-class; &eltype-r;
  &dimensions-r;)</literal>, <literal role="type">(&simple-array-type;
  &eltype-r; &dimensions-r;)</literal></simpara></listitem>
 <listitem><simpara><literal role="type">(&vector-class; &t;
  &size-r;)</literal>, <literal role="type">(&simple-vector-type;
  &size-r;)</literal></simpara></listitem>
 <listitem><simpara><literal role="type">(&string-class;
  &size-r;)</literal>, <literal role="type">(&simple-string-type;
  &size-r;)</literal></simpara></listitem>
 <listitem><simpara><literal role="type">(&base-string-type;
  &size-r;)</literal>, <literal role="type">(&simple-base-string-type;
  &size-r;)</literal></simpara></listitem>
 <listitem><simpara><literal role="type">(&bit-vector-class;
  &size-r;)</literal>, <literal role="type">(&simple-bit-vector-type;
  &size-r;)</literal></simpara></listitem>
 <listitem><simpara>&function-class;,
  &compiled-function-type;</simpara></listitem>
 <listitem><simpara>&stream-class;, &file-stream-class;,
  &synonym-stream-class;, &broadcast-stream-class;,
  &concatenated-stream-class;, &two-way-stream-class;,
  &echo-stream-class;, &string-stream-class;</simpara></listitem>
 <listitem><simpara>&package-class;, &hash-table-class;, &readtable-class;,
  &pathname-class;, &logical-pathname-class;, &random-state-class;,
  &byte-t;</simpara></listitem>
 <listitem><simpara><classname>special-operator</classname>,
  <classname>load-time-eval</classname>, &symbol-macro;, &encoding;,
  &foreign-pointer;, <classname>foreign-address</classname>,
  <classname>foreign-variable</classname>,
  <classname>foreign-function</classname></simpara></listitem>
 <listitem><simpara>&weak-pointer;,
          <link linkend="reader"><classname>read-label</classname></link>,
          <link linkend="reader"><classname>frame-pointer</classname></link>,
      <classname>system-internal</classname></simpara></listitem>
 <listitem><simpara><classname>address</classname> (should not
  occur)</simpara></listitem>
 <listitem><simpara>any other symbol (structure types or &clos;
  classes)</simpara></listitem>
 <listitem><simpara>a class (&clos; classes without proper
  name)</simpara></listitem>
</itemizedlist>

</section>
</section>

<section id="classes"><title>Classes
  <ulink url="&clhs;/Body/sec_4-3.html">[CLHS-4.3]</ulink></title>

<para>The &clos; symbols are &export;ed from the package &clos-pac;.
 &cl-pac; uses (as in &use-package;) &clos-pac; and &re-export;s all its
 exported symbols.
 Since the default &use-k; argument to &make-package; is &cl-pac;
 (see <link linkend="make-pack">here</link>),
 the &clos; symbols are normally visible in all user packages.
 If you do not want them (for example, if you want to use the
 <ulink url="ftp://clisp.cons.org/pub/lisp/clisp/packages/pcl.sept92f.clisp.tar.gz">PCL</ulink>
 implementation of &clos; instead of the native one), do the following:
<programlisting>
(&defpackage; "CL-NO-CLOS" (:use "CL"))
(&do-external-symbols; (&symbol-r; &cl-pac;)
  (&shadow; &symbol-r; "CL-NO-CLOS"))
(&do-symbols; (&symbol-r; "CL-NO-CLOS")
  (&export; &symbol-r; "CL-NO-CLOS"))
(&in-package; "CL-NO-CLOS")
(&load; "pcl") ; or whatever
(&defpackage; "MY-USER" (:use "CL-NO-CLOS"))
(&in-package; "MY-USER")
;; your code which uses PCL goes here
</programlisting>.</para>

</section>

<section id="clos-diff"><title>Deviations from &ansi-cl;</title>

<formalpara><title>&defclass;</title>
<para>It <emphasis>is</emphasis> required that the superclasses of a
 class be defined before the &defclass; form for the class is evaluated.
 </para></formalpara>

<para>&defclass; supports the option &metaclass-k; &structure-class;.
 This option is necessary in order to define a subclass of a
 &defstruct;-defined structure type using &defclass; instead of
 &defstruct;.</para>

<para>When &call-next-method; is called with arguments, the rule that
 the ordered set of applicable methods must be the same as for the
 original arguments is enforced by the implementation only in
 interpreted code.</para>

<para>There is a generic function <emphasis
 role="strong"><function>CLOS:NO-PRIMARY-METHOD</function></emphasis>
 (similar to &no-applicable-method;) which is called when a generic
 function of the class &standard-generic-function-class; is invoked and
 no primary method on that generic function is applicable.</para>

<para><emphasis
 role="strong"><function>clos:generic-flet</function></emphasis> and
 <emphasis
 role="strong"><function>clos:generic-labels</function></emphasis> are
 implemented as macros, not as special operators.  They are not imported
 into the packages &clu-pac; and &cl-pac; because of the &ansi-cl; issue
 <ulink
 url="&clhs;/Issues/iss181.html">GENERIC-FLET-POORLY-DESIGNED:DELETE</ulink>.
 </para>

<para>The function &ensure-generic-function; is not implemented.</para>

<para>&add-method; can put methods into other generic functions
 than the one the method came from.</para>

<para>&print-object; is only called on objects of type
 &standard-object-class; and &structure-object-class;.
 It is not called on other objects, like &cons-class;es
 and &number-class;s, due to the performance concerns.</para>

<para>&documentation; still has the &cltl1; implementation.</para>

</section>

<section id="metaclasses"><title>Standard Metaclasses
  <ulink url="&clhs;/Body/sec_4-3-1-1.html">[CLHS-4.3.1.1]</ulink></title>

<para>Among those classes listed in <ulink
 url="&clhs;/Body/sec_4-3-7.html#classtypecorrespondence">Figure
 4-8</ulink>, only the following are instances of &built-in-class;:

<itemizedlist>
 <listitem><simpara>&t-class;</simpara></listitem>
 <listitem><simpara>&character-class;</simpara></listitem>
 <listitem><simpara>&number-class;, &complex-class;, &real-class;,
    &float-class;, &rational-class;, &ratio-class;, &integer-class;
  </simpara></listitem>
 <listitem><simpara>&sequence-class;</simpara></listitem>
 <listitem><simpara>&array-class;, &vector-class;, &bit-vector-class;
      &string-class;</simpara></listitem>
 <listitem><simpara>&list-class;, &cons-class;</simpara></listitem>
 <listitem><simpara>&symbol-class;, &null-class;</simpara></listitem>
 <listitem><simpara>&function-class;, &generic-function-class;,
      &standard-generic-function-class;</simpara></listitem>
 <listitem><simpara>&hash-table-class;</simpara></listitem>
 <listitem><simpara>&package-class;</simpara></listitem>
 <listitem><simpara>&pathname-class;, &logical-pathname-class;
  </simpara></listitem>
 <listitem><simpara>&random-state-class;</simpara></listitem>
 <listitem><simpara>&readtable-class;</simpara></listitem>
 <listitem><simpara>&stream-class;, &broadcast-stream-class;,
    &concatenated-stream-class;, &echo-stream-class;,
    &string-stream-class;, &file-stream-class;,
    &synonym-stream-class;, &two-way-stream-class;</simpara></listitem>
</itemizedlist></para>

</section>

<section id="def-class"><title>Defining Classes
  <ulink url="&clhs;/Body/sec_4-3-2.html">[CLHS-4.3.2]</ulink></title>

<para>&defclass; supports the &metaclass-k; option.  Possible values are
 &standard-class; (the default) and &structure-class; (which creates
 structure classes, like &defstruct; does).</para>

</section>

<section id="redef-class"><title>Redefining Classes
  <ulink url="&clhs;/Body/sec_4-3-6.html">[CLHS-4.3.6]</ulink></title>

<para>Redefining classes is not supported.  The function
 &update-instance-for-redefined-class; is not implemented.</para>

</section>

<section id="type-class-int"><title>Integrating Types and Classes
  <ulink url="&clhs;/Body/sec_4-3-7.html">[CLHS-4.3.7]</ulink></title>

<para>The class &method-combination-class; is not implemented.</para>

</section>

<section id="type-class-dict"><title>The Types and Classes Dictionary
  <ulink url="&clhs;/Body/sec_the_types_s_dictionary.html">[CLHS-4.4]</ulink></title>

<section id="fixnum-char-ansi"><title>Function &coerce;</title>

<para>&fixnum-type; is not a <ulink
  url="&clhs;/Body/glo_c.html#character_designator">character
  designator</ulink> in &ansi-cl;, although &code-char; provides an
  obvious venue to &coerce; a &fixnum-type; to a &character-class;.
  When &fixnum-char-ansi; is &nil;, &clisp; &coerce;s &fixnum-type;s to
  &character-class;s via &code-char;.
  When &fixnum-char-ansi; is non-&nil;, &fixnum-type;s cannot be
  &coerce;d to &character-class;s.
</para>
</section>
</section>
</chapter>


<chapter id="data"><title>Data and Control Flow
   <ulink url="&clhs;/Body/chap-5.html">[CLHS-5]</ulink></title>

<section id="flow-dict"><title>The Data and Control Flow Dictionary
   <ulink url="&clhs;/Body/sec_the_data__w_dictionary.html">[CLHS-5.3]</ulink></title>

<formalpara><title>&destructuring-bind;</title>
<para>does not perform full error checking.</para></formalpara>

<formalpara><title>&prog1;, &prog2;, &and;, &or;, &psetq;, &when;,
 &unless;, &cond;, &case;, &multiple-value-list;, &multiple-value-bind;,
 &multiple-value-setq;</title>
<para>are implemented as special operators and, as
 such, are rather efficient.</para></formalpara>

<section id="fcase"><title>Macro <function>EXT:FCASE</function></title>

<para>This macro allows specifying the test for &case;, e.g.,
<programlisting>
(fcase string= (subseq foo 0 (position #\Space foo))
  ("first" 1)
  (("second" "two") 2)
  (("true" "yes") t)
  (otherwise nil))
</programlisting>
is the same as
<programlisting>
(let ((var (subseq foo 0 (position #\Space foo))))
  (cond ((string= var "first") 1)
        ((or (string= var "second") (string= var "two")) 2)
        ((or (string= var "true") (string= var "yes")) t)
        (t nil)))
</programlisting>
</para>
</section>

<section id="eq"><title>Function &eq;</title>

<para>&eq; compares &character-class;s and &fixnum-type;s as &eql; does.
 No unnecessary copies are made of &character-class;s and &number-class;s.
 Nevertheless, one should use &eql; as it is more portable across &cl;
 implementations.</para>

<para><literal role="sexp">(let ((x y)) (eq x x))</literal> always
 returns &t;, regardless of &y-r;.</para>

</section>

<section id="sym-fun"><title>Function &symbol-function;</title>

<para><literal role="sexp">(&setf; (&symbol-function; &symbol-r;)
 &object-r;)</literal> requires &object-r; to be either a function, a
 &symbol-function; return value or a &lambda-expr;.  The &lambda-expr;
 is thereby immediately converted to a &function-class;.</para>

</section>

<section id="setf"><title>Macro &setf;</title>

<para>Additional places:
<variablelist>
 <varlistentry><term>&funcall;</term>
  <listitem><simpara><literal role="sexp">(&setf; (&funcall; #'&symbol-r; ...)
     &object-r;)</literal>
    and
   <literal role="sexp">(&setf; (&funcall; '&symbol-r; ...)
     &object-r;)</literal>
   are equivalent to
   <literal role="sexp">(&setf; (&symbol-r; ...) &object-r;)</literal>.
  </simpara></listitem></varlistentry>

 <varlistentry><term>&progn;</term>
  <listitem><simpara>
   <literal role="sexp">(&setf; (&progn; &form-r; ... &place-r;)
                                &object-r;)</literal>
  </simpara></listitem></varlistentry>

 <varlistentry><term>&locally;</term>
  <listitem><simpara>
   <literal role="sexp">(&setf; (&locally; &declaration-r; ... &form-r; ...
                                 &place-r;) &object-r;)</literal>
  </simpara></listitem></varlistentry>

 <varlistentry><term>&if;</term>
  <listitem><simpara>
   <literal role="sexp">(&setf; (&if; <replaceable>condition</replaceable>
                                  <replaceable>place1</replaceable>
                                  <replaceable>place2</replaceable>)
                                &object-r;)</literal>
  </simpara></listitem></varlistentry>

 <varlistentry><term>&get-dispatch-macro-character;</term>
  <listitem><simpara>
   <literal role="sexp">(&setf; (&get-dispatch-macro-character; ...)
     ...)</literal> calls &set-dispatch-macro-character;.
  </simpara></listitem></varlistentry>

 <varlistentry><term>&lfd;:</term>
  <listitem><simpara>
   <literal role="sexp">(&setf; (&lfd;) &digits-r;)</literal> sets the
    default mantissa length of long floats to &digits-r; bits.
   </simpara></listitem></varlistentry>

 <varlistentry><term>&values-list;</term>
  <listitem><simpara>
   <literal role="sexp">(&setf; (&values-list;
       <replaceable>list</replaceable>) &form-r;)</literal>
    is equivalent to
   <literal role="sexp">(&values-list; (&setf; <replaceable>list</replaceable>
    (&multiple-value-list; &form-r;)))</literal>
  </simpara></listitem></varlistentry>
</variablelist></para>

<para>&key-amp; markers in &defsetf; &lalist;s are supported, but the
 corresponding keywords must appear literally in the program text.</para>

<para><literal role="sexp">(&get-setf-expansion; &form-r; &optional-amp;
 &env-r;)</literal>, <literal
 role="sexp">(EXT:GET-SETF-METHOD &form-r; &optional-amp;
 &env-r;)</literal>, and <literal
 role="sexp">(EXT:GET-SETF-METHOD-MULTIPLE-VALUE &form-r; &optional-amp;
 &env-r;)</literal> receive as optional argument &env-r;
 the environment necessary for macro expansions.  In
 &define-setf-expander; and <function>EXT:DEFINE-SETF-METHOD</function>
 &lalist;s, one can specify &environment-amp; and a variable, which will
 be bound to the environment.  This environment should be passed to all
 calls of &get-setf-expansion;,
 <function>EXT:GET-SETF-METHOD</function> and
 <function>EXT:GET-SETF-METHOD-MULTIPLE-VALUE</function>.  If this is
 done, even local macros will be interpreted as places correctly.</para>

<para>Attempts to modify read-only data will signal an error.  Program
 text and quoted constants loaded from files are considered read-only
 data.  This check is only performed for strings, not for conses, other
 kinds of arrays, and user-defined data types.</para>

<para>See also the &letf; and &letf-star; macros.</para>

</section>

<section id="func"><title>Special Operator &function;</title>

<para><literal role="sexp">(&function; &symbol-r;)</literal> returns the
 local function definition established by &flet; or &labels;, if it
 exists, otherwise the global function definition.</para>

<para><literal role="sexp">(&special-operator-p; &symbol-r;)</literal>
 returns &nil; or &t;.  If it returns &t;, then <literal
 role="sexp">(&symbol-function; &symbol-r;)</literal> returns the
 (useless) special operator handler.</para>

</section>

<section id="def-sym-mac"><title>Macro &define-symbol-macro;</title>

<para>The macro &define-symbol-macro; establishes &symbol-macro;s with
 global scope (as opposed to &symbol-macro;s defined with
 &symbol-macrolet;, which have local scope):
 <literal role="sexp">(&define-symbol-macro; &symbol-r;
 <replaceable>expansion</replaceable>)</literal>.</para>

<para>The function <emphasis
 role="strong"><function>EXT:SYMBOL-MACRO-EXPAND</function></emphasis>
 tests for a &symbol-macro;: If &symbol-r; is defined as
 a &symbol-macro;, <literal role="sexp">(EXT:SYMBOL-MACRO-EXPAND
 &symbol-r;)</literal> returns two values, &t; and the
 expansion, otherwise it returns &nil;.</para>

<para>Calling &boundp; on a symbol defined as a &symbol-macro; returns
 &t;.</para>

<para>Calling &symbol-value; on a symbol defined as a &symbol-macro;
 returns the value of the expansion.  Calling &set; on a symbol defined
 as a &symbol-macro; calls &setf; on the expansion.</para>

<para>Calling &makunbound; on a symbol defined as a &symbol-macro;
 removes the &symbol-macro; definition.</para>

</section>

<section id="lambda"><title>Macro &lambda;</title>

<formalpara><title>&lambda-list-keywords;</title>
<para><literal role="sexp">(&optional-amp; &rest-amp; &key-amp;
 &allow-other-keys-amp; &aux-amp; &body-amp; &whole-amp; &environment-amp;)
</literal></para></formalpara>

<table id="values-limits-table" frame="all">
  <title>Platform dependent</title>
 <tgroup cols="4" colsep="1" rowsep="1" align="center">&cpu-type-header;
 <tbody>
  <row><entry>&call-arguments-limit;</entry>
       <entry>2<superscript>16</superscript>=65536</entry>
       <entry namest="b32" nameend="b64" align="center"
             >2<superscript>32</superscript>=4294967296</entry></row>
  <row><entry>&multiple-values-limit;</entry>
       <entry namest="b16" nameend="b64" align="center"
             >2<superscript>7</superscript>=128</entry></row>
  <row><entry>&lambda-parameters-limit;</entry>
       <entry>2<superscript>16</superscript>=65536</entry>
       <entry namest="b32" nameend="b64" align="center"
             >2<superscript>32</superscript>=4294967296</entry></row>
</tbody></tgroup></table>

</section>

<section id="defun"><title>Macros &defun; &amp; &defmacro;</title>

<para>&defun; and &defmacro; are allowed in non-toplevel positions. As
 an example, consider the old (&cltl1;) definition of &gensym;:</para>

<programlisting>
(let ((gensym-prefix "G")
      (gensym-count 1))
  (defun gensym (&amp;optional (x nil s))
    (when s
      (cond ((stringp x) (setq gensym-prefix x))
            ((integerp x)
             (if (minusp x)
               (error "~S: index ~S is negative" 'gensym x)
               (setq gensym-count x)))
            (t (error "~S: argument ~S of wrong type" 'gensym x))))
    (prog1
      (make-symbol
        (concatenate 'string
          gensym-prefix
          (write-to-string gensym-count :base 10 :radix nil)))
      (incf gensym-count))))
</programlisting>

</section>

</section>
</chapter>


<chapter id="iteration"><title>Iteration
   <ulink url="&clhs;/Body/chap-6.html">[CLHS-6]</ulink></title>
<para>No notes.</para>
</chapter>

<chapter id="objects"><title>Objects
   <ulink url="&clhs;/Body/chap-7.html">[CLHS-7]</ulink></title>

<para><ulink url="&clhs;/Body/sec_7-2.html">Changing the class of a given
 instance</ulink> is not supported.  The functions &change-class;,
 &update-instance-for-different-class;, &make-instances-obsolete; are
 not implemented.</para>

<para>Only the &standard; method combination is implemented.</para>

<para><ulink url="&clhs;/Body/sec_7-6-6-3.html">User-defined method
 combination</ulink> is not supported.  The macros
 &define-method-combination;, &call-method; and the functions
 &invalid-method-error;, &method-combination-error; are not
 implemented.</para>

</chapter>

<chapter id="structures"><title>Structures
   <ulink url="&clhs;/Body/chap-8.html">[CLHS-8]</ulink></title>

<para>The &print-function-k; option should contain a &lambda-expr;
 <literal role="sexp">(&lambda; (structure stream depth) (declare
 (ignore depth)) ...)</literal> This &lambda-expr; names a function
 whose task is to output the external representation of structure onto
 the stream. This may be done by outputting text onto the stream using
 &write-char;, &write-string;, &write;, &prin1;, &princ;, &print;,
 &pprint;, &format; and the like. The following rules must be
 obeyed:</para>

<itemizedlist>
 <listitem><simpara>The value of &print-escape-var; must be
  respected.</simpara></listitem>
 <listitem><simpara>The value of &print-pretty-var; should not and
  cannot be respected, since the pretty-print mechanism is not
  accessible from outside.</simpara></listitem>
 <listitem><simpara>The value of &print-circle-var; need not be
  respected.  This is managed by the system.  (But the print-circle
  mechanism handles only those objects that are (direct or indirect)
  components of structure.)</simpara></listitem>
 <listitem><simpara>The value of &print-level-var; is respected by
  &write;, &prin1;, &princ;, &print;, &pprint;, &format; instructions
  &format-a;, &format-s;, &format-w;, and &format; instructions
  &format-r;, &format-d;, &format-b;, &format-o;, &format-x;, &format-f;,
  &format-e;, &format-g;, &format-dollar; with not-numerical arguments.
  Therefore the print-level mechanism works automatically if only these
  functions are used for outputting objects and if they are not called
  on objects with nesting level &gt; 1. (The print-level mechanism does
  not recognize how many parentheses you have output. It only counts how
  many times it was called recursively.)</simpara></listitem>
 <listitem><simpara>The value of &print-length-var; must be respected,
  especially if you are outputting an arbitrary number of components.
  </simpara></listitem>
 <listitem><simpara>The value of &print-readably-var; must be
  respected. Remember that the values of &print-escape-var;,
  &print-level-var;, &print-length-var; are ignored if
  &print-readably-var; is true.  The value of &print-readably-var; is
  respected by &print-unreadable-object;, &write;, &prin1;, &princ;,
  &print;, &pprint;, &format; instructions &format-a;, &format-s;,
  &format-w;, and &format; instructions &format-r;, &format-d;,
  &format-b;, &format-o;, &format-x;, &format-f;, &format-e;,
  &format-g;, &format-dollar; with not-numerical arguments.  Therefore
  &print-readably-var; will be respected automatically if only these
  functions are used for printing objects.</simpara></listitem>
 <listitem><simpara>You need not worry about the values of
  &print-base-var;, &print-radix-var;, &print-case-var;,
  &print-gensym-var;, &print-array-var;, &pr-closure;,
  &pr-rpars;, &pr-indent;.</simpara></listitem>
</itemizedlist>

<para>The &inherit-k; option is exactly like &include-k; except that it
 does not create new accessors for the inherited slots.</para>

</chapter>


<chapter id="conditions"><title>Conditions
   <ulink url="&clhs;/Body/chap-9.html">[CLHS-9]</ulink></title>

<para>When an error occurred, you are in a break loop. You can evaluate
 forms as usual. The <command>help</command> command (or help key if
 there is one) lists the available <link linkend="debugger">debugging
 commands</link>.</para>

<formalpara><title><function>EXT:MUFFLE-CERRORS</function></title>
<para>The macro <literal
 role="sexp">(<function>EXT:MUFFLE-CERRORS</function>
 {&form-r;}*)</literal> executes the &form-r;s.  When a continuable
 error occurs, no message is printed.  Instead, the &continue; restart
 is invoked.</para></formalpara>

<formalpara><title><function>EXT:APPEASE-CERRORS</function></title>
<para>The macro <literal
 role="sexp">(<function>EXT:APPEASE-CERRORS</function>
 {&form-r;}*)</literal> executes the &form-r;s.  When a continuable
 error occurs, the error is printed as a warning and the &continue;
 restart is invoked.</para></formalpara>

<formalpara><title><function>EXT:EXIT-ON-ERROR</function></title>
<para>The macro <literal
 role="sexp">(<function>EXT:EXIT-ON-ERROR</function>
 {&form-r;}*)</literal> executes the &form-r;s.  When a non-continuable
 error or a <keycombo>&ctrl;<keysym>C</keysym></keycombo>
 interrupt occurs, the error is printed and &clisp; terminates with an
 error status.</para></formalpara>

<formalpara><title><function>EXT:WITH-RESTARTS</function></title>
<para>The macro <function>EXT:WITH-RESTARTS</function> is like
 &restart-case;, except that the forms are specified after the restart
 clauses instead of before them, and the restarts created are not
 implicitly associated to any condition.
 <literal role="sexp">(<function>EXT:WITH-RESTARTS</function>
 ({<varname>restart-clause</varname>}*) {&form-r;}*)</literal> is
 therefore equivalent to <literal role="sexp">(&restart-case; (&progn;
 {&form-r;}*) {<varname>restart-clause</varname>}*)</literal>.
</para></formalpara>

<section id="cond-nl"><title>Embedded Newlines in Condition Reports
   <ulink url="&clhs;/Body/sec_9-1-3-1-3.html">[CLHS-9.1.3.1.3]</ulink></title>

<para>The error message prefix for the first line is "*** - ". There is
 no prefix for subsequent error lines. The aesthetics of condition
 reports containing an object, which requires newlines when pretty
 printing is enabled, is undefined.</para>

</section>

<section id="cond-dict"><title>The Conditions Dictionary
   <ulink url="&clhs;/Body/sec_the_condi_s_dictionary.html">[CLHS-9.2.]</ulink></title>

<formalpara><title>&restart-case;</title>
<para>In &restart-case; clauses the argument list can also be specified
 after the keyword/value pairs instead of before them.  The syntax
 therefore is

<variablelist><title><literal role="sexp">(&restart-case; &form-r;
 {<varname>restart-clause</varname>}*)</literal></title>
 <varlistentry><term><varname>restart-clause</varname> ::==</term><listitem>
  <programlisting>
   (<varname>restart-name</varname> <replaceable>arglist</replaceable>
    {<varname>keyword-value</varname>}* {&form-r;}*) |
   (<varname>restart-name</varname> {<varname>keyword-value</varname>}*
    <replaceable>arglist</replaceable> {&form-r;}*)
</programlisting></listitem></varlistentry></variablelist>
</para></formalpara>

<formalpara><title>&compute-restarts;</title>
<para>&compute-restarts; and &find-restart; behave as specified in
 &ansi-cl;: If the optional condition argument is non-&nil;, only
 restarts associated with that condition and restarts associated to no
 condition at all are considered.  Therefore the effect of associating a
 restart to a condition is not to activate it, but to hide it from other
 conditions.  This makes the syntax dependent implicit association
 performed by &restart-case; nearly obsolete.</para></formalpara>

</section>
</chapter>


<chapter id="symbols"><title>Symbols
   <ulink url="&clhs;/Body/chap-10.html">[CLHS-10]</ulink></title>
<para>No notes.</para>
</chapter>

<chapter id="packages"><title>Packages
   <ulink url="&clhs;/Body/chap-11.html">[CLHS-11]</ulink></title>

<variablelist><title>The &ansi-cl; packages present in &clisp;</title>
 <varlistentry><term>&cl-pac;</term>
  <listitem><simpara>with the nicknames
   <emphasis role="strong"><constant>"CL"</constant></emphasis> and
   <emphasis role="strong"><constant>"LISP"</constant></emphasis>
  </simpara></listitem></varlistentry>
 <varlistentry><term>&clu-pac;</term>
  <listitem><simpara>with the nicknames
   <emphasis role="strong"><constant>"CL-USER"</constant></emphasis> and
   <emphasis role="strong"><constant>"USER"</constant></emphasis>
  </simpara></listitem></varlistentry>
 <varlistentry><term>&kwd-pac;</term>
  <listitem><simpara>with the nickname
   <emphasis role="strong"><constant>""</constant></emphasis>
  </simpara></listitem></varlistentry>
</variablelist>

<para>The package &cl-pac; &export;s only those symbols
 from the &ansi-cl; that are actually implemented.</para>

<section id="pack-lock"><title>Constraints on the COMMON-LISP Package for
 Conforming Programs - package locking
 <ulink url="&clhs;/Body/sec_11-1-2-1-2.html">[CLHS-11.1.2.1.2]</ulink></title>

<formalpara><title>&package-lock;</title>
<para>Packages can be <quote>locked</quote>.
When a package is locked, attempts to change its symbol table or
redefine functions which its symbols name result in a continuable error
(continuing overrides locking for this operation).
Function <literal role="sexp" >(&package-lock;
 <replaceable>package</replaceable>)</literal> returns the
generalized boolean indicating whether the package is locked.
A package (or list thereof) can be locked using <literal role="sexp"
>(&setf; (&package-lock; <replaceable>package-or-list</replaceable>)
&t;)</literal>.
&clisp; locks its system packages (specified in the variable
&sys-pack-list;).
If you want to evaluate some forms with certain packages unlocked, you
can use <function>EXT:WITHOUT-PACKAGE-LOCK</function>:
<programlisting>
(without-package-lock ("LISP" "EXT" "CLOS")
  (defun restart () ...))
</programlisting>
<literal role="sexp" >(without-package-lock () ...)</literal> unlocks
all packages in &sys-pack-list;.</para></formalpara>

</section>

<section id="clupack"><title>The COMMON-LISP-USER Package
   <ulink url="&clhs;/Body/sec_11-1-2-2.html">[CLHS-11.1.2.2]</ulink></title>

<para>The &clu-pac; package uses the &cl-pac; and &ext-pac; packages.</para>

</section>

<section id="imppack"><title>Implementation-Defined Packages
   <ulink url="&clhs;/Body/sec_11-1-2-4.html">[CLHS-11.1.2.4]</ulink></title>

<para>The following additional packages exist:</para>
<variablelist><title>Implementation-Defined Packages</title>
  <varlistentry><term>&clos-pac;</term><listitem>
   <simpara>&export;s all &clos; specific symbols, including some
   <link linkend="clos-diff">additional symbols</link>.
   </simpara></listitem></varlistentry>
  <varlistentry id="sys-pac"><term>&sys-pac;</term><listitem>
   <simpara>has the nicknames <emphasis
   role="strong"><quote>SYS</quote></emphasis> and <emphasis
   role="strong"><quote>COMPILER</quote></emphasis>, and has no
   &export;ed symbols.  It defines many system internals.
   </simpara></listitem></varlistentry>
  <varlistentry id="ext-pac"><term><quote>EXT</quote></term><listitem><simpara>
   is the umbrella package for all extensions: it imports and &re-export;s
   all the external symbols in all &clisp; extensions, so a simple
   <literal role="sexp">(&use-package; "EXT")</literal> is enough to
   make all the extensions available in the current package.
   This package uses packages (in addition to &cl-pac;):
   &ldap-pac; &posix-pac; &socket-pac; &gstream-pac; &gray-pac;
   &i18n-pac; &custom-pac;.</simpara></listitem></varlistentry>
  <varlistentry><term>&charset-pac;</term><listitem>
   <simpara>defines and &export;s some character sets, for use with
   &make-encoding; and as &extfmt; argument.
   </simpara></listitem></varlistentry>
  <varlistentry><term>&ffi-pac;</term><listitem>
   <simpara>implements the <link linkend="dffi">foreign function
   interface</link>.  Some platforms only.
   </simpara></listitem></varlistentry>
  <varlistentry><term>&screen-pac;</term><listitem>
   <simpara>defines an API for <link linkend="screen">random screen
   access</link>.  Some platforms only.
   </simpara></listitem></varlistentry>
</variablelist>

<para>All pre-existing packages except &clu-pac; belong to the
 implementation, in the sense that the programs that do not follow
 <ulink url="&clhs;/Body/sec_11-1-2-1-2.html">Section 11.1.2.1.2
 Constraints on the COMMON-LISP Package for Conforming Programs</ulink>
 cause undefined behavior.</para>

</section>

<section id="pack-dict"><title>The Packages Dictionary
   <ulink url="&clhs;/Body/sec_the_packa_s_dictionary.html">[CLHS-11.2.]</ulink></title>

<section id="make-pack"><title>Function &make-package;</title>

<para>For &make-package;, the default value of the &use-k; argument is
 <literal role="sexp">(&cl-pac;)</literal>.
</para>

<para>&make-package; accepts a keyword argument &case-sensitive-k;.
 Similarly, &defpackage; accepts an option &case-sensitive-k;.
 When its value is non-&nil;, the package will be case sensitive, i.e.,
 the reader will not case-convert symbol names before looking them up or
 creating them in this package.
 The package names are still subject to
 <literal role="sexp">(&readtable-case; &readtable-var;)</literal>,
 though.</para>

<section id="re-export"><title>Function &re-export;</title>

<para>The function <literal role="sexp"
 >(&re-export; <replaceable>FROM-PACK</replaceable>
               <replaceable>TO-PACK</replaceable>)</literal>
 re-exports all external symbols from
 <replaceable>FROM-PACK</replaceable> also from
 <replaceable>TO-PACK</replaceable>, provided it already uses
 <replaceable>FROM-PACK</replaceable>; and signals an error otherwise.
</para></section>

</section>
</section>
</chapter>

<chapter id="numbers"><title>Numbers
   <ulink url="&clhs;/Body/chap-12.html">[CLHS-12]</ulink></title>

<section id="num-types"><title>Numeric Types</title>

<para>The type &number-class; is the disjoint union of the types
 &real-class; and &complex-class; (<ulink
 url="&clhs;/Body/glo_e.html#exhaustive_partition"><quote>exhaustive
 partition</quote></ulink>)</para>

<para>The type &real-class; is the disjoint union of the types
 &rational-class; and &float-class;.</para>

<para>The type &rational-class; is the disjoint union of the types
 &integer-class; and &ratio-class;.</para>

<para>The type &integer-class; is the disjoint union of the types
 &fixnum-type; and &bignum-type;.</para>

<para>The type &float-class; is the disjoint union of the types
 &short-float-type;, &single-float-type;, &double-float-type; and
 &long-float-type;.</para>

</section>

<section id="num-concepts"><title>Number Concepts
   <ulink url="&clhs;/Body/sec_12-1.html">[CLHS-12.1]</ulink></title>

<section id="byte-type"><title>Byte Operations on Integers
   <ulink url="&clhs;/Body/sec_12-1-1-3-2.html">[CLHS-12.1.1.3.2]</ulink></title>

<para>Byte specifiers are objects of built-in type &byte-t;,
 not &integer-class;s.</para>

</section>

<section id="float-subst"><title>Rule of Float Substitutability
   <ulink url="&clhs;/Body/sec_12-1-3-3.html">[CLHS-12.1.3.3]</ulink></title>

<para>When a mathematical function may return an exact (rational) or
 inexact (floating-point) result, it always returns the exact result.</para>

</section>

<section id="float-comp"><title>Floating-point Computations
   <ulink url="&clhs;/Body/sec_12-1-4.html">[CLHS-12.1.4]</ulink></title>

<para>There are four floating point types: &short-float-type;,
 &single-float-type;, &double-float-type; and &long-float-type;:</para>

<table id="floating-types-table" frame="all">
  <title>floating point types</title>
<tgroup cols="5" colsep="1" rowsep="1" align="center">
<thead><row><entry>type</entry><entry>sign</entry><entry>mantissa</entry>
       <entry>exponent</entry><entry>comment</entry></row></thead>
<tbody><row><entry>&short-float-type;</entry><entry>1 bit</entry>
 <entry>16+1 bits</entry><entry>8 bits</entry><entry>immediate</entry></row>
       <row><entry>&single-float-type;</entry><entry>1 bit</entry>
 <entry>23+1 bits</entry><entry>8 bits</entry><entry>IEEE format</entry></row>
       <row><entry>&double-float-type;</entry><entry>1 bit</entry>
 <entry>52+1 bits</entry><entry>11 bits</entry><entry>IEEE format</entry></row>
       <row><entry>&long-float-type;</entry><entry>1 bit</entry>
 <entry>&gt;=64 bits</entry><entry>32 bits</entry><entry>variable
 length</entry></row></tbody></tgroup></table>

<para>The single and double float formats are those of the IEEE standard
 (1981), except that &clisp; does not support features like
 <literal>+0</literal>, <literal>-0</literal>, <literal>+inf</literal>,
 <literal>-inf</literal>, gradual underflow, <literal>NaN</literal>,
 etc. (&cl; does not make use of these features.)
 This is why &features-var; does not contain the
 <constant>:IEEE-FLOATING-POINT</constant> keyword.</para>

<para id="lfd">Long floats have variable mantissa length, which is a
 multiple of 16 (or 32, depending on the word size of the processor).
 The default length used when long floats are read is given by the place
 &lfd-l;.  It can be set by <literal role="sexp">(&setf; (&lfd;)
 &n-r;)</literal>, where &n-r; is a positive integer.  E.g., <literal
 role="sexp">(&setf; (&lfd;) 3322)</literal> sets the default precision
 of long floats to 1000 decimal digits.</para>


<section id="flocont"><title>Rule of Float Precision Contagion
   <ulink url="&clhs;/Body/sec_12-1-4-4.html">[CLHS-12.1.4.4]</ulink></title>

<para>The floating point contagion is controlled by the variable
 &flocont;.  When it is non-&nil;, contagion is done as per the
 &ansi-cl;: &short-float-type; &rarr; &single-float-type; &rarr;
 &double-float-type; &rarr; &long-float-type;.</para>

<variablelist>
<varlistentry><term>Rationale:</term>
 <listitem><simpara>See it pragmatically: save what you can and let
  others worry about the rest.</simpara></listitem></varlistentry>
<varlistentry><term>Brief:</term>
 <listitem><simpara>&cl; knows the number's precision, not accuracy, so
  preserving the precision can be accomplished reliably, while anything
  relating to the accuracy is just a speculation - only the user
  (programmer) knows what it is in each case.
 </simpara></listitem></varlistentry>
<varlistentry><term>Detailed:</term>
 <listitem><simpara>A float is an approximation of a real number.  One
  can think of it as a random variable with the mean equal to itself and
  standard deviation equal to half the last significant digit.  E.g.,
  <literal>1.5</literal> is actually <literal>1.5+-0.05</literal>.
  Consider adding <literal>1.5</literal> and <literal>1.75</literal>.
  &ansi-cl; requires that <literal role="sexp">(+ 1.5 1.75)</literal>
  return <literal>3.25</literal>, while traditional &clisp; would return
  <literal>3.3</literal>.  The implied random variables are:
  <literal>3.25+-0.005</literal> and <literal>3.3+-0.05</literal>.  Note
  that the traditional &clisp; way <emphasis role="strong">does</emphasis>
  lie about the mean: the mean <emphasis role="strong">is</emphasis>
  <literal>3.25</literal> and nothing else, while the standard way
  <emphasis role="strong">could</emphasis> be lying about the deviation
  (accuracy): if the implied accuracy of <literal>1.5 (0.05)</literal>
  is its actual accuracy, then the accuracy of the result cannot be
  smaller that that.  Therefore, since &cl; has no way of knowing the
  actual accuracy, &ansi-cl; (and all the other standard engineering
  programming languages, like &c-lang;, FORTRAN etc) decides that
  keeping the accuracy correct is the business of the programmer, while
  the language should preserve what it can - the precision.
  </simpara></listitem></varlistentry>
<varlistentry><term>Experience:</term>
  <listitem><simpara> Rounding errors accumulate, and if a computation
  is conducted with insufficient precision, an outright incorrect
  result can be returned.  (E.g.,
  <literal>E(x<superscript>2</superscript>) -
  E(x)<superscript>2</superscript></literal> can be negative!)  The user
  should not mix floats of different precision (that's what &warn-fpc; is
  for), but one should not be penalized for this too harshly.
  </simpara></listitem></varlistentry>
</variablelist>

<para>When &flocont; is &nil;, the traditional &clisp; method is used,
 namely the result of an arithmetic operation whose arguments are of
 different float types is rounded to the float format of the shortest
 (least precise) of the arguments: &rational-class; &rarr;
 &long-float-type; &rarr; &double-float-type; &rarr; &single-float-type;
 &rarr; &short-float-type; (in contrast to <ulink
 url="&clhs;/Body/sec_12-1-4-4.html">12.1.4.4 Rule of Float Precision
 Contagion</ulink>!)</para>

<variablelist>
<varlistentry><term>Rationale:</term>
 <listitem><simpara> See it mathematically.  Add intervals:
  <literal>{1.0 &plusmn; 1e-8} + {1.0 &plusmn; 1e-16} = {2.0 &plusmn;
  1e-8}</literal>.  So, if we add <literal>1.0s0</literal> and
  <literal>1.0d0</literal>, we should get <literal>2.0s0</literal>.
  </simpara></listitem></varlistentry>
<varlistentry><term>Brief:</term>
 <listitem><simpara>Do not suggest accuracy of a result by giving it a
  precision that is greater than its accuracy.
  </simpara></listitem></varlistentry>
<varlistentry><term>Example:</term>
 <listitem><simpara><literal role="sexp">(- (+ 1.7 &pi;) &pi;)</literal>
  should not return <literal>1.700000726342836417234L0</literal>, it
  should return <literal>1.7f0</literal> (or
  <literal>1.700001f0</literal> if there were rounding errors).
  </simpara></listitem></varlistentry>
<varlistentry><term>Experience:</term>
 <listitem><simpara>If in a computation using thousands of short floats,
  a long float (like &pi;) happens to be used, the long precision should
  not propagate throughout all the intermediate values. Otherwise, the
  long result would look precise, but its accuracy is only that of a
  short float; furthermore much computation time would be lost by
  calculating with long floats when only short floats would be needed.
  </simpara></listitem></varlistentry>
</variablelist>

<formalpara id="warn-fpc"><title>&warn-fpc;</title>
<para>If the variable &warn-fpc; is non-&nil;, a warning is emitted for
 every coercion involving different floating-point types.
</para></formalpara>

</section>
</section>

<section id="complex-comp"><title>Complex Computations
   <ulink url="&clhs;/Body/sec_12-1-5.html">[CLHS-12.1.5]</ulink></title>

<para>Complex numbers can have a real part and an imaginary part of
 different types. For example, <literal role="sexp">(sqrt
 -9.0)</literal> evaluates to the number <literal>#C(0 3.0)</literal>,
 which has a real part of exactly <literal>0</literal>, not only
 <literal>0.0</literal> (which would mean "approximately 0").</para>

<para>The type specifier for this is <literal
 role="sexp">(&complex-class; &integer-class;
 &single-float-type;)</literal>, and <literal
 role="sexp">(&complex-class; <varname>type-of-real-part</varname>
 <varname>type-of-imaginary-part</varname>)</literal> in general.</para>

<para>The type specifier <literal role="sexp">(&complex-class;
 &type-r;)</literal> is equivalent to <literal
 role="sexp">(&complex-class; &type-r; &type-r;)</literal>.</para>

</section>

<section id="complex-rational"><title>Rule of
   Canonical Representation for Complex Rationals
   <ulink url="&clhs;/Body/sec_12-1-5-3.html">[CLHS-12.1.5.3]</ulink></title>

<para>Complex numbers can have a real part and an imaginary part of
 different types.  If the imaginary part is &eql; to
 <literal>0</literal>, the number is automatically converted to a real
 number.</para>

<para>This has the advantage that
   <literal role="sexp">(let ((x (sqrt -9.0))) (* x x))</literal>
 - instead of evaluating to <literal>#C(-9.0 0.0)</literal>,
 with &x-r; = <literal>#C(0.0 3.0)</literal> - evaluates to
 <literal>#C(-9.0 0)</literal> = <literal>-9.0</literal>,
 with &x-r; = <literal>#C(0 3.0)</literal>.</para>

</section>
</section>

<section id="num-dict"><title>The Numbers Dictionary
   <ulink url="&clhs;/Body/sec_the_numbers_dictionary.html">[CLHS-12.2]</ulink></title>

<formalpara><title>&upgraded-complex-part-type;</title>
<para>&upgraded-complex-part-type; always returns &t;, since a
 &complex-class; number in &clisp; can always have &realpart; and
 &imagpart; of any type.</para></formalpara>

<formalpara id="default-float-format"><title>&default-float-format;</title>
<para>When rational numbers are to be converted to floats (due to
 &float;, &coerce;, &sqrt; or a transcendental function), the result
 type is given by the variable &default-float-format;.</para></formalpara>

<formalpara id="no-underflow"><title>&no-underflow;</title>
<para>The macro <literal role="sexp">(&no-underflow;
 {&form-r;}*)</literal> executes the &form-r;s, with errors of type
 &floating-point-underflow-type; inhibited.  Floating point operations
 will silently return zero instead of signalling an error of type
 &floating-point-underflow-type;.</para></formalpara>

<section id="int-func-ext"><title>Additional Integer Functions</title>

<formalpara><title><function>ext:!</function></title>
<para><literal role="sexp">(<function>ext:!</function> &n-r;)</literal>
 returns the factorial of &n-r;, &n-r; being a nonnegative
 &integer-class;.</para></formalpara>

<formalpara><title><function>ext:exquo</function></title>
<para><literal role="sexp">(<function>ext:exquo</function> &x-r;
 &y-r;)</literal> returns the integer quotient <varname>x/y</varname> of
 two integers &x-r;,&y-r;, and signals an error when the quotient is not
 integer.  (This is more efficient than &slash;.)</para></formalpara>

<formalpara><title><function>ext:xgcd</function></title>
<para><literal role="sexp">(<function>ext:xgcd</function>
 &x1-r; ... &xn-r;)</literal>
 returns the values &l-r;, &k1-r;, ..., &kn-r;, where &l-r; is the
 greatest common divisor of the integers &x1-r;, ..., &xn-r;, and
 &k1-r;, ..., &kn-r; are the integer coefficients such that
<programlisting>
 &l-r; = (&gcd; &x1-r; ... &xn-r;)
   = (+ (* &k1-r; &x1-r;) ... (* &kn-r; &xn-r;))
</programlisting></para></formalpara>

</section>

<section id="float-notes"><title>Floating Point</title>

<formalpara><title>&expt;</title>
<para><literal role="sexp">(&expt; &base-r;
 <replaceable>exponent</replaceable>)</literal> is not very precise if
 <replaceable>exponent</replaceable> has a large absolute
 value.</para></formalpara>

<formalpara><title>&log;</title>
<para><literal role="sexp">(&log; &number-r; &base-r;)</literal> signals
 an error if <literal>&base-r; = 1</literal>.</para></formalpara>

<formalpara><title>&pi;</title>
<para>The value of &pi; is a &long-float-type; with the precision given
 by &lfd-l;.  When this precision is changed, the value of &pi; is
 automatically recomputed.  Therefore &pi; is a variable, not a
 constant.</para></formalpara>

</section>

<section id="float-decode"><title>Float Decoding
   <ulink url="&clhs;/Body/fun_decode-fl_decode-float.html">[CLHS]</ulink></title>

<para>&float-radix; always returns <literal>2</literal>.</para>

<para><literal role="sexp">(&float-digits; &number-r;
 &digits-r;)</literal> coerces &number-r; (a real number) to a floating
 point number with at least &digits-r; mantissa digits.
 The following holds:
<programlisting>
 (&gt;= (&float-digits; (&float-digits; &number-r; &digits-r;)) &digits-r;)
</programlisting></para>

</section>

<section id="bool-ops"><title>Boolean Operations
   <ulink url="&clhs;/Body/convar_boole-_cm_boole-xor.html">[CLHS]</ulink></title>

<table id="bool-op-table" frame="all">
 <title>Boolean Operations</title>
<tgroup cols="2" colsep="1" rowsep="1" align="left">
<thead><row><entry>constant</entry><entry>value</entry></row></thead><tbody>
 <row><entry>&boole-clr;</entry><entry>0</entry></row>
 <row><entry>&boole-set;</entry><entry>15</entry></row>
 <row><entry>&boole-1;</entry><entry>10</entry></row>
 <row><entry>&boole-2;</entry><entry>12</entry></row>
 <row><entry>&boole-c1;</entry><entry>5</entry></row>
 <row><entry>&boole-c2;</entry><entry>3</entry></row>
 <row><entry>&boole-and;</entry><entry>8</entry></row>
 <row><entry>&boole-ior;</entry><entry>14</entry></row>
 <row><entry>&boole-xor;</entry><entry>6</entry></row>
 <row><entry>&boole-eqv;</entry><entry>9</entry></row>
 <row><entry>&boole-nand;</entry><entry>7</entry></row>
 <row><entry>&boole-nor;</entry><entry>1</entry></row>
 <row><entry>&boole-andc1;</entry><entry>4</entry></row>
 <row><entry>&boole-andc2;</entry><entry>2</entry></row>
 <row><entry>&boole-orc1;</entry><entry>13</entry></row>
 <row><entry>&boole-orc2;</entry><entry>11</entry></row>
</tbody></tgroup></table>

</section>

<section id="fixnum-lim"><title>Fixnum Limits
<ulink url="&clhs;/Body/convar_most-p_ative-fixnum.html">[CLHS]</ulink></title>

<table id="fixnum-lim-table" frame="all">
  <title>Platform dependent</title>
 <tgroup cols="4" colsep="1" rowsep="1" align="center">&cpu-type-header;
 <tbody>
 <row><entry>&most-positive-fixnum;</entry>
      <entry namest="b16" nameend="b32" align="center"
            >2<superscript>24</superscript>-1 = 16777215</entry>
      <entry>2<superscript>32</superscript>-1 = 4294967295</entry></row>
 <row><entry>&most-negative-fixnum;</entry>
      <entry namest="b16" nameend="b32" align="center"
            >-2<superscript>24</superscript> = -16777216</entry>
      <entry>-2<superscript>32</superscript> = -4294967296</entry></row>
</tbody></tgroup></table>

</section>

<section id="float-lim"><title>Float Limits
<ulink url="&clhs;/Body/convar_most-p_d-long-float.html">[CLHS]</ulink></title>

<para>Together with &pi;, the other long float constants
 &least-negative-long-float; &least-negative-normalized-long-float;
 &least-positive-long-float; &least-positive-normalized-long-float;
 &long-float-epsilon; &long-float-negative-epsilon;
 &most-negative-long-float; &most-positive-long-float; are recomputed
 whenever &lfd-l; is &setf;ed.  They are variables, not constants.</para>

</section>

<section id="float-invalid-op">
  <title>Condition &floating-point-invalid-operation-type;</title>
<para>This condition is never signaled by &clisp;.</para>
</section>

<section id="float-inexact">
  <title>Condition &floating-point-inexact-type;</title>
<para>This condition is never signaled by &clisp;.</para>
</section>
</section>
</chapter>

<chapter id="characters"><title>Characters
   <ulink url="&clhs;/Body/chap-13.html">[CLHS-13]</ulink></title>

<para>The characters are ordered according to a superset of the ASCII
encoding.</para>

<!-- #ifdef UNICODE -->
<variablelist>
<varlistentry><term>Platform dependent: only in &clisp; built
  &with; the compile-time flag &unicode;.</term>
<listitem><simpara>More precisely, &clisp; uses the 16-bit &unicode;
 character set (ISO 10646, also known as UCS-2).
</simpara></listitem></varlistentry></variablelist>
<!-- #endif -->

<!-- #if defined(IBMPC_CHS) && !defined(UNICODE) -->
<variablelist>
<varlistentry><term>Platform dependent: &dos;, &os2; platforms only, and
   only in &clisp; built &without; compile-time flag &unicode;.</term>
<listitem><para>More precisely, &clisp; uses the IBM PC character set
 (code page 437):
<table id="ibmpc-charset-table" frame="all">
  <title>the IBM PC character set (code page 437)</title>
 <tgroup cols="17" colsep="1" rowsep="1" align="center">
  &char-table-header;<tbody>
  <row><entry>#x00</entry>&cc;<entry/><entry/><entry/><entry/><entry/><entry/>
   &cc;&cc;&cc;&cc;&cc;&cc;&cc;<entry>&para;</entry><entry>&sect;</entry></row>
  <row><entry>#x10</entry><entry/><entry/><entry/>
   <entry/><entry/><entry/><entry/><entry/>
   <entry/><entry/>&cc;&cc;<entry/><entry/><entry/><entry/></row>
  &ascii-printable;
  <row><entry>#x80</entry><entry>&Ccedil;</entry><entry>&uuml;</entry>
   <entry>&eacute;</entry><entry>&acirc;</entry><entry>&auml;</entry>
   <entry>&agrave;</entry><entry>&aring;</entry><entry>&ccedil;</entry>
   <entry>&ecirc;</entry><entry>&euml;</entry><entry>&egrave;</entry>
   <entry>&iuml;</entry><entry>&icirc;</entry><entry>&igrave;</entry>
   <entry>&Auml;</entry><entry>&Aring;</entry></row>
  <row><entry>#x90</entry><entry>&Eacute;</entry><entry>&aelig;</entry>
   <entry>&AElig;</entry><entry>&ocirc;</entry><entry>&ouml;</entry>
   <entry>&ograve;</entry><entry>&ucirc;</entry><entry>&ugrave;</entry>
   <entry>&yuml;</entry><entry>&Ouml;</entry><entry>&Uuml;</entry>
   <entry>&cent;</entry><entry>&pound;</entry><entry>&yen;</entry>
   <entry>&#8359;</entry><entry>&#402;</entry></row>
  <row><entry>#xA0</entry><entry>&aacute;</entry><entry>&iacute;</entry>
   <entry>&oacute;</entry><entry>&uacute;</entry><entry>&ntilde;</entry>
   <entry>&Ntilde;</entry><entry>&ordf;</entry><entry>&ordm;</entry>
   <entry>&iquest;</entry><entry>&#8976;</entry><entry>&not;</entry>
   <entry>&frac12;</entry><entry>&frac14;</entry><entry>&iexcl;</entry>
   <entry>&laquo;</entry><entry>&raquo;</entry></row>
  <row><entry>#xB0</entry><entry>&#9617;</entry><entry>&#9618;</entry>
   <entry>&#9619;</entry><entry>&#9474;</entry><entry>&#9508;</entry>
   <entry>&#9569;</entry><entry>&#9570;</entry><entry>&#9558;</entry>
   <entry>&#9557;</entry><entry>&#9571;</entry><entry>&#9553;</entry>
   <entry>&#9559;</entry><entry>&#9565;</entry><entry>&#9564;</entry>
   <entry>&#9563;</entry><entry>&#9488;</entry></row>
  <row><entry>#xC0</entry><entry>&#9492;</entry><entry>&#9524;</entry>
   <entry>&#9516;</entry><entry>&#9500;</entry><entry>&#9472;</entry>
   <entry>&#9532;</entry><entry>&#9566;</entry><entry>&#9567;</entry>
   <entry>&#9562;</entry><entry>&#9556;</entry><entry>&#9577;</entry>
   <entry>&#9574;</entry><entry>&#9568;</entry><entry>&#9552;</entry>
   <entry>&#9580;</entry><entry>&#9575;</entry></row>
  <row><entry>#xD0</entry><entry>&#9576;</entry><entry>&#9572;</entry>
   <entry>&#9573;</entry><entry>&#9561;</entry><entry>&#9560;</entry>
   <entry>&#9554;</entry><entry>&#9555;</entry><entry>&#9563;</entry>
   <entry>&#9562;</entry><entry>&#9496;</entry><entry>&#9484;</entry>
   <entry>&#9608;</entry><entry>&#9604;</entry><entry>&#9612;</entry>
   <entry>&#9616;</entry><entry>&#9600;</entry></row>
  <row><entry>#xE0</entry><entry>&alpha;</entry><entry>&szlig;</entry>
   <entry>&Gamma;</entry><entry>&pi;</entry><entry>&Sigma;</entry>
   <entry>&sigma;</entry><entry>&micro;</entry><entry>&tau;</entry>
   <entry>&Phi;</entry><entry>&Theta;</entry><entry>&Omega;</entry>
   <entry>&delta;</entry><entry>&infin;</entry><entry>&phgr;</entry>
   <entry>&epsi;</entry><entry>&cap;</entry></row>
  <row><entry>#xF0</entry><entry>&equiv;</entry><entry>&plusmn;</entry>
   <entry>&ge;</entry><entry>&le;</entry><entry>&#8992;</entry>
   <entry>&#8993;</entry><entry>&divide;</entry><entry>&asymp;</entry>
   <entry>&deg;</entry><entry>&#8729;</entry><entry>&middot;</entry>
   <entry>&radic;</entry><entry>&#8319;</entry><entry>&sup2;</entry>
   <entry>&#9632;</entry><entry>&nbsp;</entry></row>
</tbody></tgroup></table>
 &char-table-legend;
</para></listitem></varlistentry></variablelist>
<!-- #endif -->

<!-- #if defined(ISOLATIN_CHS) && !defined(UNICODE) -->
<variablelist>
<varlistentry><term>Platform dependent: &unix; (except &nextstep;),
   &win32;, &amiga;, &acorn; platforms only, and only in
   &clisp; built &without; compile-time flag &unicode;.</term>
<listitem><para>More precisely, &clisp; uses the ISO Latin-1 (ISO
 8859-1) character set:
<table id="latin-1-table" frame="all">
   <title>the ISO Latin-1 (ISO 8859-1) character set</title>
  <tgroup cols="17" colsep="1" rowsep="1" align="center">
  &char-table-header;<tbody>
  <row><entry>#x00</entry>&cc;&cc;&cc;&cc;&cc;&cc;&cc;&cc;&cc;&cc;&cc;
   &cc;&cc;&cc;&cc;&cc;</row>
  <row><entry>#x10</entry>&cc;&cc;&cc;&cc;&cc;&cc;&cc;&cc;&cc;&cc;&cc;
   &cc;&cc;&cc;&cc;&cc;</row>
  &ascii-printable;
  <row><entry>#x80</entry><entry/><entry/><entry/>
   <entry/><entry/><entry/><entry/><entry>
   </entry><entry/><entry/><entry/><entry/>
   <entry/><entry/><entry/><entry/></row>
  <row><entry>#x90</entry><entry/><entry/><entry/>
   <entry/><entry/><entry/><entry/><entry>
   </entry><entry/><entry/><entry/><entry/>
   <entry/><entry/><entry/><entry/></row>
  <row><entry>#xA0</entry><entry>&nbsp;</entry><entry>&iexcl;</entry>
   <entry>&cent;</entry><entry>&pound;</entry><entry>&curren;</entry>
   <entry>&yen;</entry><entry>&brvbar;</entry><entry>&sect;</entry>
   <entry>&uml;</entry><entry>&copy;</entry><entry>&ordf;</entry>
   <entry>&laquo;</entry><entry>&not;</entry><entry>&shy;</entry>
   <entry>&reg;</entry><entry>&macr;</entry></row>
  <row><entry>#xB0</entry><entry>&deg;</entry><entry>&plusmn;</entry>
   <entry>&sup2;</entry><entry>&sup3;</entry><entry>&acute;</entry>
   <entry>&micro;</entry><entry>&para;</entry><entry>&middot;</entry>
   <entry>&cedil;</entry><entry>&sup1;</entry><entry>&ordm;</entry>
   <entry>&raquo;</entry><entry>&frac14;</entry><entry>&frac12;</entry>
   <entry>&frac34;</entry><entry>&iquest;</entry></row>
  <row><entry>#xC0</entry><entry>&Agrave;</entry><entry>&Aacute;</entry>
   <entry>&Acirc;</entry><entry>&Atilde;</entry><entry>&Auml;</entry>
   <entry>&Aring;</entry><entry>&AElig;</entry><entry>&Ccedil;</entry>
   <entry>&Egrave;</entry><entry>&Eacute;</entry><entry>&Ecirc;</entry>
   <entry>&Euml;</entry><entry>&Igrave;</entry><entry>&Iacute;</entry>
   <entry>&Icirc;</entry><entry>&Iuml;</entry></row>
  <row><entry>#xD0</entry><entry>&ETH;</entry><entry>&Ntilde;</entry>
   <entry>&Ograve;</entry><entry>&Oacute;</entry><entry>&Ocirc;</entry>
   <entry>&Otilde;</entry><entry>&Ouml;</entry><entry>&times;</entry>
   <entry>&Oslash;</entry><entry>&Ugrave;</entry><entry>&Uacute;</entry>
   <entry>&Ucirc;</entry><entry>&Uuml;</entry><entry>&Yacute;</entry>
   <entry>&THORN;</entry><entry>&szlig;</entry></row>
  <row><entry>#xE0</entry><entry>&agrave;</entry><entry>&aacute;</entry>
   <entry>&acirc;</entry><entry>&atilde;</entry><entry>&auml;</entry>
   <entry>&aring;</entry><entry>&aelig;</entry><entry>&ccedil;</entry>
   <entry>&egrave;</entry><entry>&eacute;</entry><entry>&ecirc;</entry>
   <entry>&euml;</entry><entry>&igrave;</entry><entry>&iacute;</entry>
   <entry>&icirc;</entry><entry>&iuml;</entry></row>
  <row><entry>#xF0</entry><entry>&eth;</entry><entry>&ntilde;</entry>
   <entry>&ograve;</entry><entry>&oacute;</entry><entry>&ocirc;</entry>
   <entry>&otilde;</entry><entry>&ouml;</entry><entry>&divide;</entry>
   <entry>&oslash;</entry><entry>&ugrave;</entry><entry>&uacute;</entry>
   <entry>&ucirc;</entry><entry>&uuml;</entry><entry>&yacute;</entry>
   <entry>&thorn;</entry><entry>&yuml;</entry></row>
</tbody></tgroup></table>
&char-table-legend;
</para></listitem></varlistentry></variablelist>
<!-- #endif -->

<!-- #if defined(NEXTSTEP_CHS) && !defined(UNICODE) -->
<variablelist>
<varlistentry><term>Platform dependent: &nextstep; platforms only, and
 only in &clisp; built &without; compile-time flag &unicode;.</term>
<listitem><para>More precisely, &clisp; uses the &nextstep; character set:
<table id="next-charset-table" frame="all">
   <title>the &nextstep; character set</title>
  <tgroup cols="17" colsep="1" rowsep="1" align="center">
  &char-table-header;<tbody>
  <row><entry>#x00</entry>&cc;&cc;&cc;&cc;&cc;&cc;&cc;&cc;&cc;&cc;&cc;
   &cc;&cc;&cc;&cc;&cc;</row>
  <row><entry>#x10</entry>&cc;&cc;&cc;&cc;&cc;&cc;&cc;&cc;&cc;&cc;&cc;
   &cc;&cc;&cc;&cc;&cc;</row>
  &ascii-printable;
  <row><entry>#x80</entry><entry>&nbsp;</entry><entry>&Agrave;</entry>
   <entry>&Aacute;</entry><entry>&Acirc;</entry><entry>&Atilde;</entry>
   <entry>&Auml;</entry><entry>&Aring;</entry><entry>&Ccedil;</entry>
   <entry>&Egrave;</entry><entry>&Eacute;</entry><entry>&Ecirc;</entry>
   <entry>&Euml;</entry><entry>&Igrave;</entry><entry>&Iacute;</entry>
   <entry>&Icirc;</entry><entry>&Iuml;</entry></row>
  <row><entry>#x90</entry><entry>&ETH;</entry><entry>&Ntilde;</entry>
   <entry>&Ograve;</entry><entry>&Oacute;</entry><entry>&Ocirc;</entry>
   <entry>&Otilde;</entry><entry>&Ouml;</entry><entry>&Ugrave;</entry>
   <entry>&Uacute;</entry><entry>&Ucirc;</entry><entry>&Uuml;</entry>
   <entry>&Yacute;</entry><entry>&THORN;</entry><entry>&micro;</entry>
   <entry>&times;</entry><entry>&divide;</entry></row>
  <row><entry>#xA0</entry><entry>&copy;</entry><entry>&iexcl;</entry>
   <entry>&cent;</entry><entry>&pound;</entry><entry>&#8260;</entry>
   <entry>&yen;</entry><entry>&fnof;</entry><entry>&sect;</entry>
   <entry>&curren;</entry><entry>&#8217;</entry><entry>&ldquo;</entry>
   <entry>&laquo;</entry><entry>&#8249;</entry><entry>&#8250;</entry>
   <entry>&#64257;</entry><entry>&#64258;</entry></row>
  <row><entry>#xB0</entry><entry>&reg;</entry><entry>&ndash;</entry>
   <entry>&dagger;</entry><entry>&Dagger;</entry><entry>&middot;</entry>
   <entry>&brvbar;</entry><entry>&para;</entry><entry>&bull;</entry>
   <entry>&#8218;</entry><entry>&#8222;</entry><entry>&rdquo;</entry>
   <entry>&raquo;</entry><entry>&hellip;</entry><entry>&permil;</entry>
   <entry>&not;</entry><entry>&iquest;</entry></row>
  <row><entry>#xC0</entry><entry>&sup1;</entry><entry>&#715;</entry>
   <entry>&acute;</entry><entry>&circ;</entry><entry>&tilde;</entry>
   <entry>&macr;</entry><entry>&#728;</entry><entry>&#729;</entry>
   <entry>&uml;</entry><entry>&sup2;</entry><entry>&#730;</entry>
   <entry>&cedil;</entry><entry>&sup3;</entry><entry>&#733;</entry>
   <entry>&#731;</entry><entry>&#711;</entry></row>
  <row><entry>#xD0</entry><entry>&mdash;</entry><entry>&plusmn;</entry>
   <entry>&frac14;</entry><entry>&frac12;</entry><entry>&frac34;</entry>
   <entry>&agrave;</entry><entry>&aacute;</entry><entry>&acirc;</entry>
   <entry>&atilde;</entry><entry>&auml;</entry><entry>&aring;</entry>
   <entry>&ccedil;</entry><entry>&egrave;</entry><entry>&eacute;</entry>
   <entry>&ecirc;</entry><entry>&euml;</entry></row>
  <row><entry>#xE0</entry><entry>&igrave;</entry><entry>&AElig;</entry>
   <entry>&iacute;</entry><entry>&ordf;</entry><entry>&icirc;</entry>
   <entry>&iuml;</entry><entry>&eth;</entry><entry>&ntilde;</entry>
   <entry>&#321;</entry><entry>&Oslash;</entry><entry>&OElig;</entry>
   <entry>&ordm;</entry><entry>&ograve;</entry><entry>&oacute;</entry>
   <entry>&ocirc;</entry><entry>&otilde;</entry></row>
  <row><entry>#xF0</entry><entry>&ouml;</entry><entry>&aelig;</entry>
   <entry>&ugrave;</entry><entry>&uacute;</entry><entry>&ucirc;</entry>
   <entry>&#305;</entry><entry>&uuml;</entry><entry>&yacute;</entry>
   <entry>&#322;</entry><entry>&oslash;</entry><entry>&oelig;</entry>
   <entry>&szlig;</entry><entry>&thorn;</entry><entry>&yuml;</entry>
   <entry/><entry/></row>
  </tbody></tgroup></table>
&char-table-legend;
</para></listitem></varlistentry></variablelist>
<!-- #endif -->

<table id="standard-char-table" frame="all">
  <title>The following are standard characters:</title>
 <tgroup cols="2" colsep="1" rowsep="1" align="center">
  &char-code-header;<tbody>
 <row><entry><keysym>#\Space</keysym></entry>
              <entry><keycode>#x20</keycode></entry></row>
 <row><entry>&nl-c;</entry>
              <entry><keycode>#x0A</keycode></entry></row>
</tbody></tgroup></table>

<table id="semi-standard-char-table" frame="all">
  <title>The following are semi-standard characters:</title>
 <tgroup cols="2" colsep="1" rowsep="1" align="center">
  &char-code-header;<tbody>
 <row><entry><keysym>#\Backspace</keysym></entry>
              <entry><keycode>#x08</keycode></entry></row>
 <row><entry><keysym>#\Tab</keysym></entry>
              <entry><keycode>#x09</keycode></entry></row>
 <row><entry><keysym>#\Linefeed</keysym></entry>
              <entry><keycode>#x0A</keycode></entry></row>
 <row><entry><keysym>#\Page</keysym></entry>
              <entry><keycode>#x0C</keycode></entry></row>
 <row><entry>&ret-c;</entry>
              <entry><keycode>#x0D</keycode></entry></row>
</tbody></tgroup></table>

<para>&nl-c; is the &line-term;.</para>


<table id="extra-named-chars-table" frame="all">
  <title>Additional Named Characters</title>
 <tgroup cols="2" colsep="1" rowsep="1" align="center">
  &char-code-header;<tbody>
 <row><entry><keysym>#\Null</keysym></entry>
              <entry><keycode>#x00</keycode></entry></row>
 <row><entry><keysym>#\Bell</keysym></entry>
              <entry><keycode>#x07</keycode></entry></row>
 <row><entry><keysym>#\Escape</keysym></entry>
              <entry><keycode>#x1B</keycode></entry></row>
</tbody></tgroup></table>

<table id="ctrl-char-table" frame="all">
  <title>Additional syntax for characters with code from
   <keycode>#x00</keycode> to <keycode>#x1F</keycode>:</title>
 <tgroup cols="2" colsep="1" rowsep="1" align="center">
  &char-code-header;<tbody>
 <row><entry><keysym>#\^@</keysym></entry>
              <entry><keycode>#x00</keycode></entry></row>
 <row><entry><keysym>#\^A</keysym> &hellip; <keysym>#\^Z</keysym></entry>
              <entry><keycode>#x01</keycode> &hellip;
                   <keycode>#x1A</keycode></entry></row>
 <row><entry><keysym>#\^[</keysym></entry>
              <entry><keycode>#x1B</keycode></entry></row>
 <row><entry><keysym>#\^\</keysym></entry>
              <entry><keycode>#x1C</keycode></entry></row>
 <row><entry><keysym>#\^]</keysym></entry>
              <entry><keycode>#x1D</keycode></entry></row>
 <row><entry><keysym>#\^^</keysym></entry>
              <entry><keycode>#x1E</keycode></entry></row>
 <row><entry><keysym>#\^_</keysym></entry>
              <entry><keycode>#x1F</keycode></entry></row>
</tbody></tgroup></table>

<para>See also the section <link linkend="chario">Character
 I/O</link>.</para>


<section id="input-char"><title>Attributes</title>

<para>Characters do not have the &cltl1; font and bits attributes.
 For backward compatibility, there is a class &input-char; representing
 either a character with font and bits, or a keystroke.
 The following functions work with objects of types &character-class;
 and &input-char;.
 Note that &eql; or &equal; cannot be used to compare objects of type
 &input-char;.</para>

<variablelist>
 <varlistentry><term><constant>ext:char-font-limit</constant> = 16</term>
  <listitem><simpara>The system uses only font 0.
  </simpara></listitem></varlistentry>
 <varlistentry><term><constant>ext:char-bits-limit</constant> = 16</term>
  <listitem><table id="bit-table" frame="all">
    <title>The following bits are defined:</title>
   <tgroup cols="2" colsep="1" rowsep="1" align="center">
    &key-value-header;<tbody>
   <row><entry>&control-k;</entry><entry>&ch-ctrl;</entry></row>
   <row><entry>&meta-k;</entry><entry>&ch-meta;</entry></row>
   <row><entry>&super-k;</entry><entry>&ch-super;</entry></row>
   <row><entry>&hyper-k;</entry><entry>&ch-hyper;</entry></row>
  </tbody></tgroup></table></listitem></varlistentry>
 <varlistentry><term><literal role="sexp">(<function>ext:char-font</function>
  &object-r;)</literal> </term>
 <listitem><simpara>returns the font of a &character-class; or &input-char;.
  </simpara></listitem></varlistentry>
 <varlistentry><term><literal role="sexp">(<function>ext:char-bits</function>
  &object-r;)</literal> </term>
 <listitem><simpara>returns the bits of a &character-class; or &input-char;.
  </simpara></listitem></varlistentry>
 <varlistentry><term><literal role="sexp">(<function>ext:make-char</function>
  &ch-r; [<replaceable>bits</replaceable>
            [<replaceable>font</replaceable>]])</literal></term>
 <listitem><simpara>returns a new &input-char;, or &nil; if such a
 character cannot be created.</simpara></listitem></varlistentry>
 <varlistentry><term><literal role="sexp">(<function>ext:char-bit</function>
  &object-r; &name-r;)</literal></term>
 <listitem><simpara>returns &t; if the named bit is set in &object-r;,
  else &nil;.</simpara></listitem></varlistentry>
 <varlistentry><term><literal
   role="sexp">(<function>ext:set-char-bit</function>
  &object-r; &name-r; <replaceable>newvalue</replaceable>)</literal></term>
 <listitem><simpara>returns a new &input-char; with the named bit set or
  unset, depending on the boolean <replaceable>newvalue</replaceable>.
  </simpara></listitem></varlistentry>
</variablelist>

<!-- #ifdef KEYBOARD -->
<variablelist>
<varlistentry><term>Platform dependent: &unix;, &dos;, &os2;, &win32;, &acorn;
   platforms only.</term>
<listitem><simpara>The system itself uses this &input-char; type only to
 mention special keys and &ctrl;/&alt;/&shift; key status on return from
 <literal role="sexp">(&read-char; &kbd-in;)</literal>.
 </simpara></listitem></varlistentry>
</variablelist>
<!-- #endif -->

</section>

<section id="char-script"><title>Character Scripts
   <ulink url="&clhs;/Body/sec_13-1-2-1.html">[CLHS-13.1.2.1]</ulink></title>

<para>The only defined character script is the type &character-class;
 itself.</para>

</section>

<section id="char-attrib"><title>Character Attributes
   <ulink url="&clhs;/Body/sec_13-1-3.html">[CLHS-13.1.3]</ulink></title>

<para>Characters have no implementation-defined attributes.  All characters
are simple characters.</para>

</section>

<section id="graph-char"><title>Graphic Characters
   <ulink url="&clhs;/Body/sec_13-1-4-1.html">[CLHS-13.1.4.1]</ulink></title>

<para>The graphic characters are those &unicode; characters which are
 defined by the &unicode; standard, excluding the ranges
 <keycode>U0000</keycode> &hellip; <keycode>U001F</keycode> and
 <keycode>U007F</keycode> &hellip; <keycode>U009F</keycode>.</para>

</section>

<section id="alpha-char"><title>Alphabetic Characters
   <ulink url="&clhs;/Body/sec_13-1-4-2.html">[CLHS-13.1.4.2]</ulink></title>

<para>The alphabetic characters are those &unicode; characters which are
 defined as letters by the &unicode; standard.</para>

</section>

<section id="char-ext"><title>Case of Implementation-Defined Characters
   <ulink url="&clhs;/Body/sec_13-1-4-3-4.html">[CLHS-13.1.4.3.4]</ulink></title>

<para>The characters with case are those &unicode; characters &c-r;, for
 which the upper case mapping &uc-r; and the lower case mapping &lc-r;
 have the following properties:
<itemizedlist>
  <listitem><simpara>&uc-r; and &lc-r; are different</simpara></listitem>
  <listitem><simpara>&c-r; is one of &uc-r; and &lc-r;</simpara></listitem>
  <listitem><simpara>the upper case mapping of &uc-r; and of &lc-r;
   is &uc-r;</simpara></listitem>
  <listitem><simpara>the lower case mapping of &uc-r; and of &lc-r;
   is &lc-r;</simpara></listitem>
</itemizedlist></para>

<para>The titlecase property of &unicode; characters has no equivalent in
 &cl;.</para>

</section>

<section id="num-char"><title>Numeric Characters
   <ulink url="&clhs;/Body/sec_13-1-4-4.html">[CLHS-13.1.4.4]</ulink></title>

<para>The numeric characters are those &unicode; characters which are
 defined as digits by the &unicode; standard.</para>

</section>

<section id="char-ord"><title>Ordering of Characters
   <ulink url="&clhs;/Body/sec_13-1-6.html">[CLHS-13.1.6]</ulink></title>

<para>The characters are ordered according to their &unicode; code.</para>

</section>

<section id="clhs-newline"><title>Treatment of Newline during Input and Output
   <ulink url="&clhs;/Body/sec_13-1-8.html">[CLHS-13.1.8]</ulink></title>

<para>Newlines are written according to the stream's &encoding;, see the
 function &stream-external-format; and the description of &encoding;s,
 in particular, &line-term;s.
 The default behavior is as follows:</para>

<!-- #if defined(MSDOS) || defined(WIN32) || (defined(UNIX) && (O_BINARY != 0)) -->
<variablelist>
<varlistentry><term>Platform dependent: &dos;, &os2;, &win32;
   platforms only.</term>
<listitem><simpara>When writing to a file, &nl-c; is converted to
 &cr-c;/&lf-c;. (This is the usual convention on &dos;.)
 For example, &ret-c;+&nl-c; is written as &cr-c;/&cr-c;/&lf-c;.
</simpara></listitem></varlistentry></variablelist>
<!-- #endif -->

<para>When reading from a file, &cr-c;/&lf-c; is converted to &nl-c;
 (the usual convention on &dos;), and &cr-c; not followed by &lf-c; is
 converted to &nl-c; as well (the usual conversion on MacOS, also used
 by some programs on &win32;).</para>

</section>

<section id="char-int"><title>Character Encodings
   <ulink url="&clhs;/Body/sec_13-1-9.html">[CLHS-13.1.9]</ulink></title>

<para>The integer returned by &char-int; is the same as the character's
 code.</para>

</section>

<section id="script-ext"><title>Documentation
   of Implementation-Defined Scripts
   <ulink url="&clhs;/Body/sec_13-1-10.html">[CLHS-13.1.10]</ulink></title>

<para>See the description of &encoding;s.</para>

</section>

<section id="char-dict"><title>The Characters Dictionary
   <ulink url="&clhs;/Body/sec_the_chara_s_dictionary.html">[CLHS-13.2]</ulink></title>

<para>&char-code; takes values from 0 (inclusive) to
 &char-code-limit; (exclusive), i.e., the implementation
 supports exactly &char-code-limit; characters.</para>

<table id="char-code-limit-table" frame="all">
  <title>Platform dependent</title>
 <tgroup cols="3" colsep="1" rowsep="1" align="center">
 <thead><row><entry>binaries built</entry>
             <entry>&without; &unicode; support</entry>
             <entry>&with; &unicode; support</entry></row></thead>
 <tbody><row><entry>&char-code-limit;</entry>
             <entry>2<superscript>8</superscript> = 256</entry>
             <entry>2<superscript>16</superscript> = 65536</entry></row>
</tbody></tgroup></table>

<para>The types <classname>ext:string-char</classname> and
 &base-char-type; are equivalent to &character-class;.</para>

<para>The graphic characters have been described above.</para>

<para>The standard characters are &nl-c; and the graphic characters with
 a code between 32 and 126 (inclusive).</para>

<para>The alphabetic characters are these characters:
<literallayout>
             ABCDEFGHIJKLMNOPQRSTUVWXYZ
             abcdefghijklmnopqrstuvwxyz
</literallayout>
and the international alphabetic characters from the character set:
<literallayout>
             &Ccedil;&uuml;&eacute;&acirc;&auml;&agrave;&aring;&ccedil;&ecirc;&euml;&egrave;&iuml;&icirc;&igrave;&Auml;&Aring;&Eacute;&aelig;&AElig;&ocirc;&ouml;&ograve;&ucirc;&ugrave;&yuml;&Ouml;&Uuml;&szlig;&aacute;&iacute;&oacute;&uacute;&ntilde;&Ntilde;&ordf;&ordm;&atilde;&otilde;&Oslash;&oslash;&Agrave;&Atilde;&Otilde; etc.
</literallayout></para>

<para>The functions &char-equal; &char-not-equal;, &char-lessp;,
 &char-greaterp;, &char-not-greaterp;, &char-not-lessp; ignore bits and
 font attributes of their arguments.</para>

</section>

<section id="char-width"><title>Functions on characters</title>

<formalpara><title><literal role="sexp">(&char-width; &ch-r;)</literal></title>
<para>returns the number of screen columns occupied by &ch-r;.
 This is 0 for non-spacing characters
  (such as control characters and many combining characters),
 2 for double-width East Asian characters,
 and 1 for all other characters.
 See also function &string-width;.
</para></formalpara>

</section>

<section id="char-platform-dep"><title>platform-dependent characters</title>

<para>The characters that are not graphic chars and the space character
 have names:</para>

<!-- #ifdef AMIGA_CHARNAMES -->
<table id="amiga-chars-table" frame="all">
  <title>Platform dependent: &amiga; platforms only.</title>
 <tgroup cols="2" colsep="1" rowsep="1" align="center">
  &code-char-header;<tbody>
 <row><entry><literal role="sexp">(&code-char; #x00)</literal></entry>
          <entry><keysym>#\Null</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x01)</literal></entry>
          <entry><keysym>#\Code1</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x02)</literal></entry>
          <entry><keysym>#\Code2</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x03)</literal></entry>
          <entry><keysym>#\Code3</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x04)</literal></entry>
          <entry><keysym>#\Code4</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x05)</literal></entry>
          <entry><keysym>#\Code5</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x06)</literal></entry>
          <entry><keysym>#\Code6</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x07)</literal></entry>
          <entry><keysym>#\Bell</keysym></entry>
          <entry><keysym>#\Bel</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x08)</literal></entry>
          <entry><keysym>#\Backspace</keysym></entry>
          <entry><keysym>#\Bs</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x09)</literal></entry>
          <entry><keysym>#\Tab</keysym></entry>
          <entry><keysym>#\Ht</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x0A)</literal></entry>
          <entry>&nl-c;</entry>
          <entry><keysym>#\Linefeed</keysym></entry>
          <entry><keysym>#\Lf</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x0B)</literal></entry>
          <entry><keysym>#\Vt</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x0C)</literal></entry>
          <entry><keysym>#\Page</keysym></entry>
          <entry><keysym>#\Ff</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x0D)</literal></entry>
          <entry>&ret-c;</entry>
          <entry><keysym>#\Cr</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x0E)</literal></entry>
          <entry><keysym>#\So</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x0F)</literal></entry>
          <entry><keysym>#\Si</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x10)</literal></entry>
          <entry><keysym>#\Code16</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x11)</literal></entry>
          <entry><keysym>#\Code17</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x12)</literal></entry>
          <entry><keysym>#\Code18</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x13)</literal></entry>
          <entry><keysym>#\Code19</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x14)</literal></entry>
          <entry><keysym>#\Code20</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x15)</literal></entry>
          <entry><keysym>#\Code21</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x16)</literal></entry>
          <entry><keysym>#\Code22</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x17)</literal></entry>
          <entry><keysym>#\Code23</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x18)</literal></entry>
          <entry><keysym>#\Code24</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x19)</literal></entry>
          <entry><keysym>#\Code25</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x1A)</literal></entry>
          <entry><keysym>#\Code26</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x1B)</literal></entry>
          <entry><keysym>#\Escape</keysym></entry>
          <entry><keysym>#\Esc</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x1C)</literal></entry>
          <entry><keysym>#\Code28</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x1D)</literal></entry>
          <entry><keysym>#\Code29</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x1E)</literal></entry>
          <entry><keysym>#\Code30</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x1F)</literal></entry>
          <entry><keysym>#\Code31</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x20)</literal></entry>
          <entry><keysym>#\Space</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x7F)</literal></entry>
          <entry><keysym>#\Rubout</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x9B)</literal></entry>
          <entry><keysym>#\Csi</keysym></entry></row>
</tbody></tgroup></table>
<!-- #endif -->

<!-- #if defined(MSDOS_CHARNAMES) || defined(WIN32_CHARNAMES) -->
<table id="dos-win32-chars-table" frame="all">
  <title>Platform dependent: &dos;, &os2;, &win32; platforms only.</title>
 <tgroup cols="2" colsep="1" rowsep="1" align="center">
  &code-char-header;<tbody>
 <row><entry><literal role="sexp">(&code-char; #x00)</literal></entry>
          <entry><keysym>#\Null</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x07)</literal></entry>
          <entry><keysym>#\Bell</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x08)</literal></entry>
          <entry><keysym>#\Backspace</keysym></entry>
          <entry><keysym>#\Rubout</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x09)</literal></entry>
          <entry><keysym>#\Tab</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x0A)</literal></entry>
          <entry>&nl-c;</entry>
          <entry><keysym>#\Linefeed</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x0B)</literal></entry>
          <entry><keysym>#\Code11</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x0C)</literal></entry>
          <entry><keysym>#\Page</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x0D)</literal></entry>
          <entry>&ret-c;</entry></row>
 <row><entry><literal role="sexp">(&code-char; #x1A)</literal></entry>
          <entry><keysym>#\Code26</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x1B)</literal></entry>
          <entry><keysym>#\Escape</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x20)</literal></entry>
          <entry><keysym>#\Space</keysym></entry></row>
</tbody></tgroup></table>
<!-- #endif -->

<!-- #ifdef UNIX_CHARNAMES -->
<table id="unix-chars-table" frame="all">
  <title>Platform dependent: &unix;, &acorn;, platforms only.</title>
 <tgroup cols="2" colsep="1" rowsep="1" align="center">
  &code-char-header;<tbody>
 <row><entry><literal role="sexp">(&code-char; #x00)</literal></entry>
          <entry><keysym>#\Null</keysym></entry>
          <entry><keysym>#\Nul</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x01)</literal></entry>
          <entry><keysym>#\Soh</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x02)</literal></entry>
          <entry><keysym>#\Stx</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x03)</literal></entry>
          <entry><keysym>#\Etx</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x04)</literal></entry>
          <entry><keysym>#\Eot</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x05)</literal></entry>
          <entry><keysym>#\Enq</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x06)</literal></entry>
          <entry><keysym>#\Ack</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x07)</literal></entry>
          <entry><keysym>#\Bell</keysym></entry>
          <entry><keysym>#\Bel</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x08)</literal></entry>
          <entry><keysym>#\Backspace</keysym></entry>
          <entry><keysym>#\Bs</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x09)</literal></entry>
          <entry><keysym>#\Tab</keysym></entry>
          <entry><keysym>#\Ht</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x0A)</literal></entry>
          <entry>&nl-c;</entry>
          <entry><keysym>#\Nl</keysym></entry>
          <entry><keysym>#\Linefeed</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x0B)</literal></entry>
          <entry><keysym>#\Vt</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x0C)</literal></entry>
          <entry><keysym>#\Page</keysym></entry>
          <entry><keysym>#\Np</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x0D)</literal></entry>
          <entry>&ret-c;</entry>
          <entry><keysym>#\Cr</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x0E)</literal></entry>
          <entry><keysym>#\So</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x0F)</literal></entry>
          <entry><keysym>#\Si</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x10)</literal></entry>
          <entry><keysym>#\Dle</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x11)</literal></entry>
          <entry><keysym>#\Dc1</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x12)</literal></entry>
          <entry><keysym>#\Dc2</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x13)</literal></entry>
          <entry><keysym>#\Dc3</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x14)</literal></entry>
          <entry><keysym>#\Dc4</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x15)</literal></entry>
          <entry><keysym>#\Nak</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x16)</literal></entry>
          <entry><keysym>#\Syn</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x17)</literal></entry>
          <entry><keysym>#\Etb</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x18)</literal></entry>
          <entry><keysym>#\Can</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x19)</literal></entry>
          <entry><keysym>#\Em</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x1A)</literal></entry>
          <entry><keysym>#\Sub</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x1B)</literal></entry>
          <entry><keysym>#\Escape</keysym></entry>
          <entry><keysym>#\Esc</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x1C)</literal></entry>
          <entry><keysym>#\Fs</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x1D)</literal></entry>
          <entry><keysym>#\Gs</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x1E)</literal></entry>
          <entry><keysym>#\Rs</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x1F)</literal></entry>
          <entry><keysym>#\Us</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x20)</literal></entry>
          <entry><keysym>#\Space</keysym></entry>
          <entry><keysym>#\Sp</keysym></entry></row>
 <row><entry><literal role="sexp">(&code-char; #x7F)</literal></entry>
          <entry><keysym>#\Rubout</keysym></entry>
          <entry><keysym>#\Delete</keysym></entry>
          <entry><keysym>#\Del</keysym></entry></row>
</tbody></tgroup></table>
<!-- #endif -->

</section>

<section id="char-bits"><title>Obsolete Constants</title>

<table id="char-bits-table" frame="all">
  <title>obsolete constants</title>
 <tgroup cols="2" colsep="1" rowsep="1" align="center">
 <thead><row><entry>constant</entry><entry>value</entry></row></thead><tbody>
 <row><entry>&ch-ctrl;</entry><entry>1</entry></row>
 <row><entry>&ch-meta;</entry><entry>2</entry></row>
 <row><entry>&ch-super;</entry><entry>4</entry></row>
 <row><entry>&ch-hyper;</entry><entry>8</entry></row>
</tbody></tgroup></table>
</section>


</chapter>


<chapter id="conses"><title>Conses
   <ulink url="&clhs;/Body/chap-14.html">[CLHS-14]</ulink></title>

<section id="cons-dict"><title>The Conses Dictionary
   <ulink url="&clhs;/Body/sec_the_conses_dictionary.html">[CLHS-14.2]</ulink></title>

<section id="map-func">
   <title>Functions &mapcar;, &mapcan;, &maplist;, &mapcon;, ...</title>

<section id="mapcap"><title>Function &mapcap;</title>

<para>The function &mapcap; is like &mapcan;, except that it
 concatenates the resulting lists with &append; instead of &nconc;:</para>

<para><literal role="sexp">(&mapcap; &func-r; &x1-r; ... &xn-r;)</literal> ==
 <literal role="sexp">(&apply; #'&append; (&mapcar; &func-r; &x1-r;
 ... &xn-r;))</literal></para>

<para>(Actually a bit more efficient that this would have been.)</para>

</section>

<section id="maplap"><title>Function &maplap;</title>

<para>The function &maplap; is like &mapcon;, except that it
 concatenates the resulting lists with &append; instead of &nconc;:</para>

<para><literal role="sexp">(&maplap; &func-r; &x1-r; ... &xn-r;)</literal> ==
 <literal role="sexp">(&apply; #'&append; (&maplist; &func-r; &x1-r;
 ... &xn-r;))</literal></para>

<para>(Actually a bit more efficient that this would have been.)</para>

</section>
</section>
</section>
</chapter>


<chapter id="arrays"><title>Arrays
   <ulink url="&clhs;/Body/chap-15.html">[CLHS-15]</ulink></title>

<formalpara><title>&make-array;</title>
<para>&make-array; can return specialized arrays for the
 &array-element-type;s
 <literal role="type">(&unsigned-byte-type; 2)</literal>,
 <literal role="type">(&unsigned-byte-type; 4)</literal>,
 &unsigned-byte-8;, &unsigned-byte-16;, &unsigned-byte-32;,
 and, of course, &bit-type; and &character-class;.</para></formalpara>

<section id="array-elts"><title>Array Elements
   <ulink url="&clhs;/Body/sec_15-1-1.html">[CLHS-15.1.1]</ulink></title>

<table id="array-limit-table" frame="all">
  <title>Platform dependent</title>
 <tgroup cols="4" colsep="1" rowsep="1" align="center">&cpu-type-header;
 <tbody>
 <row><entry>&array-rank-limit;</entry>
      <entry namest="b16" nameend="b32" align="center"
            >2<superscript>16</superscript> = 65536</entry>
      <entry>2<superscript>32</superscript> = 4294967296</entry></row>
 <row><entry>&array-dimension-limit;</entry>
      <entry namest="b16" nameend="b32" align="center"
            >2<superscript>24</superscript> = 16777216</entry>
      <entry>2<superscript>32</superscript> = 4294967296</entry></row>
 <row><entry>&array-total-size-limit;</entry>
      <entry namest="b16" nameend="b32" align="center"
            >2<superscript>24</superscript> = 16777216</entry>
      <entry>2<superscript>32</superscript> = 4294967296</entry></row>
</tbody></tgroup></table>

<para>Note that these constants are not fixnums, contrary to the &ansi-cl;
 Issue <ulink url="&clhs;/Issues/iss014.html"
 >ARRAY-DIMENSION-LIMIT-IMPLICATIONS:ALL-FIXNUM</ulink>.</para>

</section>

<section id="array-dict"><title>The Arrays Dictionary
   <ulink url="&clhs;/Body/sec_the_arrays_dictionary.html">[CLHS-15.2]</ulink></title>

<formalpara><title>&adjust-array; for displaced arrays</title>
<para>An array to which another array is displaced should not be shrunk
 (using &adjust-array;) in such a way that the other array points into
 void space.  This is not checked at the time &adjust-array; is
 called!</para></formalpara>

</section>
</chapter>


<chapter id="strings"><title>Strings
   <ulink url="&clhs;/Body/chap-16.html">[CLHS-16]</ulink></title>

<para>String comparison is based on the function &char-leq;.  Therefore
 diphthongs do not obey the usual national rules.  Example:
 <literal>o</literal> &lt; <literal>oe</literal> &lt;
 <literal>z</literal> &lt; <literal>&ouml;</literal>.</para>

<section id="string-dict"><title>The Strings Dictionary
   <ulink url="&clhs;/Body/sec_the_strings_dictionary.html">[CLHS-16.2]</ulink></title>

<section id="string-width"><title>Functions on strings</title>

<formalpara><title><literal role="sexp">(&string-width;
 &string-r;)</literal></title>
 <para>returns the number of screen columns occupied by &string-r;.
 This is computed as the sum of all &char-width;s
 of all of the &string-r;'s characters.</para></formalpara></section>

</section>
</chapter>


<chapter id="sequences"><title>Sequences
   <ulink url="&clhs;/Body/chap-17.html">[CLHS-17]</ulink></title>

<section id="seq-dict"><title>The Sequences Dictionary
   <ulink url="&clhs;/Body/sec_the_seque_s_dictionary.html">[CLHS-17.3.]</ulink></title>

<section id="seq-macro-ext"><title>Additional Macros</title>

<section id="doseq"><title>Macro &doseq;</title>

<para>For iteration through a sequence, a macro &doseq;,
 similar to &dolist;, may be used instead of &map;:</para>

<programlisting>
(&doseq; (&var-r; <replaceable>seqform</replaceable> [<replaceable>resultform</replaceable>])
  {&declaration-r;}*
  {&tag-r;|&form-r;}*)
</programlisting>

<para>&doseq; forms are &iter-forms;.</para>

</section>
</section>

<section id="nreverse-nreconc">
   <title>Functions &nreverse; &amp; &nreconc;</title>

<formalpara><title>&nreverse;</title>
<para>The result of &nreverse; is always &eq; to the argument.
 &nreverse; on a &vector-class; swaps pairs of elements.
 &nreverse; on a &list-class; swaps the first and the last
 element and reverses the list chaining between them.</para></formalpara>

<formalpara><title>&nreconc;</title>
<para>The result of &nreconc; is &eq; to the first argument unless it is
 &nil;, in which case the result is &eq; to the second argument.</para>
</formalpara>
</section>

<section id="rem-del"><title>Functions &remove; &amp; &delete;</title>

<para>&remove;, &remove-if;, &remove-if-not;, &remove-duplicates; return
 their argument unchanged, if no element has to be removed.</para>

<para>&delete;, &delete-if;, &delete-if-not;, &delete-duplicates;
 destructively modify their argument: If the argument is a &list-class;,
 the &cdr; parts are modified.  If the argument is a &vector-class; with
 fill pointer, the fill pointer is lowered and the remaining elements are
 compacted below the new fill pointer.</para>

<formalpara id="count-ansi"><title>&count-ansi;</title>
<para>Contrary to the &ansi-cl; issue 283 <ulink
 url="&clhs;/Issues/iss283.html">RANGE-OF-COUNT-KEYWORD:NIL-OR-INTEGER</ulink>,
 negative &count-k; keyword arguments are not allowed unless you set
 &count-ansi; to a non-&nil; value, in hich case <quote>using a negative
 integer value is functionally equivalent to using a value of
 zero</quote>, as per the &ansi-cl; issue.</para></formalpara>

</section>

<section id="sorting"><title>Functions &sort; &amp; &stable-sort;</title>

<para>&sort; and &stable-sort; have two additional keywords &start-k;
and &end-k;:</para>

<programlisting>
(&sort; &sequence-r; &pred-r; &key-amp; &key-k; &start-k; &end-k;)
(&stable-sort; &sequence-r; &pred-r; &key-amp; &key-k; &start-k; &end-k;)
</programlisting>

<para>&sort; and &stable-sort; are identical.
 They implement the mergesort algorithm.
 Worst case complexity: <varname>O(n*log(n))</varname> comparisons,
 where &n-r; is the &length; of the subsequence bounded
 by the &start-k; and &end-k; arguments.</para>

</section>
</section>
</chapter>


<chapter id="hash"><title>Hash Tables
   <ulink url="&clhs;/Body/chap-18.html">[CLHS-18]</ulink></title>

<section id="hash-dict"><title>The Hash Tables Dictionary
   <ulink url="&clhs;/Body/sec_the_hash__s_dictionary.html">[CLHS-18.2.]</ulink></title>

<section id="make-hash"><title>Function &make-hash-table;</title>

<para>&make-hash-table; supports additional keywords
 <constant>:initial-contents</constant>
 and <constant>:weak</constant>:</para>

<programlisting>
(&make-hash-table; &key-amp; :test :initial-contents :size
                 :rehash-size :rehash-threshold :weak)
</programlisting>

<para>The <constant>:initial-contents</constant> argument is an
 &alist; that is used to initialize the new hash table.
 The <constant>:rehash-threshold</constant> argument is ignored.</para>

<para>The boolean <constant>:weak</constant> argument defaults to &nil;
and specifies whether the &hash-table-class; is <emphasis>weak</emphasis>:
the key is not considered accessible for the &gc;ion purposes, i.e., if
is is only accessible in the weak &hash-table-class;, it is &gc;ed and
removed from the weak &hash-table-class;.</para>

<para>The &setf;able predicate <function>EXT:HASH-TABLE-WEAK-P</function>
checks whether the &hash-table-class; is weak.</para>

<para>Just like &weak-pointer;s, weak &hash-table-class;s cannot be
printed readably.</para>

</section>

<section id="hash-ext"><title>Additional Macros</title>

<section id="dohash"><title>Macro &dohash;</title>

<para>For iteration through a hash table, a macro &dohash;
 similar to &dolist;, can be used instead of &maphash;:</para>

<programlisting>
(&dohash; (<replaceable>key-var</replaceable> <replaceable>value-var</replaceable> <replaceable>hash-table-form</replaceable> [<replaceable>resultform</replaceable>])
  {&declaration-r;}*
  {&tag-r;|&form-r;}*)
</programlisting>

<para>&dohash; forms are &iter-forms;.</para>

</section>
</section>
</section>
</chapter>

<chapter id="filenames"><title>Filenames
   <ulink url="&clhs;/Body/chap-19.html">[CLHS-19]</ulink></title>

<para>For most operations, pathnames denoting files and pathnames
 denoting directories cannot be used interchangeably.</para>

<variablelist>
<!-- #if defined(PATHNAME_UNIX) || defined(PATHNAME_AMIGAOS) -->
<varlistentry><term>Platform dependent: &unix;, &amiga; platforms only.</term>
<listitem><simpara>For example, <filename>#p"FOO/BAR"</filename> denotes
 the file <filename>BAR</filename> in the directory
 <filename>FOO</filename>, while <filename>#p"FOO/BAR/"</filename>
 denotes the subdirectory <filename>BAR</filename> of the directory
 <filename>FOO</filename>.
</simpara></listitem></varlistentry>
<!-- #endif -->

<!-- #if defined(PATHNAME_MSDOS) || defined(PATHNAME_OS2) || defined(PATHNAME_WIN32) -->
<varlistentry><term>Platform dependent: &dos;, &os2;, &win32;
   platforms only.</term>
<listitem><simpara>For example, <filename>#p"FOO\\BAR"</filename>
 denotes the file <filename>BAR</filename> in the directory
 <filename>FOO</filename>, while <filename>#p"FOO\\BAR\\"</filename>
 denotes the subdirectory <filename>BAR</filename> of the directory
 <filename>FOO</filename>.
</simpara></listitem></varlistentry>
<!-- #endif -->

<!-- #ifdef PATHNAME_RISCOS -->
<varlistentry><term>Platform dependent: &acorn; platforms only.</term>
<listitem><simpara>For example, <filename>#p"FOO.BAR"</filename> denotes
 the file <filename>FOO</filename> in the directory
 <filename>BAR</filename>, while <filename>#p"FOO.BAR."</filename>
 denotes the subdirectory <filename>BAR</filename> of the directory
 <filename>FOO</filename>.
</simpara></listitem></varlistentry>
<!-- #endif -->

</variablelist>

<para>This is especially important for the functions <link
 linkend="dir"><function>directory</function>,
 <function>ext:dir</function>, <function>ext:cd</function>,
 <function>ext:make-dir</function>,
 <function>ext:delete-dir</function></link>.</para>

<table id="min-filename-syntax-table" frame="all">
  <title>The minimum filename syntax that may be used portably</title>
 <tgroup cols="2" colsep="1" rowsep="1" align="center">
 <thead><row><entry>pathname</entry><entry>meaning</entry></row></thead><tbody>
 <row><entry><filename>xxx</filename></entry>
   <entry>for a file with name <replaceable>xxx</replaceable></entry></row>
 <row><entry><filename>xxx.yy</filename></entry>
   <entry>for a file with name <replaceable>xxx</replaceable> and type
   <replaceable>yy</replaceable></entry></row>
 <row><entry><filename>.yy</filename></entry>
   <entry>for a pathname with type <replaceable>yy</replaceable> and no
   name specified</entry></row>
</tbody></tgroup></table>

<para>Hereby <replaceable>xxx</replaceable> denotes 1 to 8 characters,
 and <replaceable>yy</replaceable> denotes 1 to 3 characters, each of
 which being either an alphanumeric character or the underscore
 <keysym>#\_</keysym>.  Other properties of pathname syntax vary between
 operating systems.</para>

<section id="path-components"><title>Pathname Components
   <ulink url="&clhs;/Body/sec_19-2-1.html">[CLHS-19.2.1]</ulink></title>

<para>When a pathname is to be fully specified (no wildcards), that
 means that no &wild-k;, &wild-inferiors-k; is allowed, no wildcard
 characters are allowed in the strings, and &name-r; &eq; &nil; may not
 be allowed either.</para>

<!-- #ifdef PATHNAME_AMIGAOS -->
<variablelist>
<varlistentry><term>Platform dependent: &amiga; platforms only.</term>
<listitem><variablelist>&path-comps;
<varlistentry><term>&host-r;</term>&always-nil;</varlistentry>
<varlistentry><term>&device-r;</term>&string-or-nil;</varlistentry>
<varlistentry><term>&directory-r;</term>
 <listitem><table id="amiga-dir-table" frame="all">&dir-title;
 <tgroup cols="2" colsep="1" rowsep="1" align="center">
   &elt-val-meaning-header;<tbody>
 &startp-rel-abs; &subdirs-def; &subdir-string-or-wild;
 <row><entry>&subdir-r;</entry><entry>&parent-k;</entry>
  <entry>&file-slash; instead of <filename>subdir/</filename></entry></row>
 </tbody></tgroup></table></listitem></varlistentry>
<varlistentry><term>&name-r;</term>&wild-string-or-nil;</varlistentry>
<varlistentry><term>&type-r;</term>&wild-string-or-nil;</varlistentry>
&version-nil;
</variablelist>

<para>Constraint: &startpoint-r; = &relative-k; only if &device-r; is
 &nil;.  If the device is specified, the pathname must be absolute!</para>

<para>An &amiga; &name-type-split;</para>

<para>Case is ignored in the strings on comparison.  No case conversions
 are performed.</para>

<table frame="all" id="pathnames-externally-amiga">
 <title>filename notations</title>
 <tgroup cols="2" colsep="1" rowsep="1" align="center"><tbody>
 <row><entry>External notation:</entry>
  <entry><filename>dev:sub1.typ/sub2.typ/name.typ</filename></entry></row>
 <row><entry>using defaults:</entry>
  <entry><filename>    sub1.typ/sub2.typ/name.typ</filename></entry></row>
 <row><entry>or</entry>
  <entry><filename>                      name.typ</filename></entry></row>
 <row><entry>or</entry>
  <entry><filename>    sub1.typ/**/sub3.typ/x*.lisp</filename></entry></row>
 <row><entry>or similar.</entry><entry/></row>
</tbody></tgroup></table>

<variablelist><title>Formal specification of the external notation</title>
  <varlistentry><term>ch ::==</term>
   <listitem><simpara>any character except ':','/' and '*','?'
   </simpara></listitem></varlistentry>
  <varlistentry><term>name ::==</term>
   <listitem><simpara>{ch}+</simpara></listitem></varlistentry>
  <varlistentry><term>device ::==</term>
   <listitem><para>[ &lt;empty&gt; | ':' | name ':' ]
    <table frame="all"><title/>
    <tgroup cols="2" colsep="1" rowsep="1" align="center"><tbody>
    <row><entry>empty</entry><entry>current device, relative to
     current directory</entry></row>
    <row><entry>':'</entry><entry>current device, absolute (relative
     to root for disks)</entry></row>
    <row><entry>name ':'</entry><entry>specified device, absolute
     (relative to root for disks)</entry></row>
   </tbody></tgroup></table></para></listitem></varlistentry>
  <varlistentry><term>subdir ::==</term>
   <listitem><para>[ &lt;empty&gt; | name ]
    <table frame="all"><title/>
    <tgroup cols="2" colsep="1" rowsep="1" align="center"><tbody>
    <row><entry>empty</entry><entry>parent directory</entry></row>
   </tbody></tgroup></table></para></listitem></varlistentry>
  <varlistentry><term>pathname ::==</term>
   <listitem><simpara>device { subdir '/' }* name
   </simpara></listitem></varlistentry>
</variablelist>

<table id="amiga-path-examples-table" frame="all"><title>Examples</title>
 <tgroup cols="4" colsep="1" rowsep="1" align="center">
  <thead><row><entry>String</entry><entry>Device</entry>
  <entry>Directory</entry><entry>our pathname</entry></row></thead><tbody>
 <row><entry><filename>'c:foo'</filename></entry><entry>'C'</entry>
   <entry><filename>device-&gt;foo</filename></entry>
   <entry><filename>"c"</filename>
        (&absolute-k; <filename>"foo"</filename>)</entry></row>
 <row><entry><filename>'c:foo/'</filename></entry><entry>'C'</entry>
   <entry><filename>device-&gt;foo</filename></entry>
   <entry><filename>"c"</filename>
        (&absolute-k; <filename>"foo"</filename>)</entry></row>
 <row><entry><filename>'c:foo/bar'</filename></entry><entry>'C'</entry>
   <entry><filename>device-&gt;foo-&gt;bar</filename></entry>
   <entry><filename>"c"</filename>
        (&absolute-k; <filename>"foo" "bar"</filename>)</entry></row>
 <row><entry><filename>'c:/foo'</filename></entry><entry>'C'</entry>
   <entry><filename>device-&gt;up-&gt;foo</filename></entry>
   <entry><filename>"c"</filename>
        (&absolute-k; &parent-k; <filename>"foo"</filename>)
        </entry></row>
 <row><entry><filename>'c:'</filename></entry><entry>'C'</entry>
   <entry><filename>device</filename></entry>
   <entry><filename>"c"</filename> (&absolute-k;)</entry></row>
 <row><entry><filename>:foo</filename></entry><entry>current</entry>
   <entry><filename>device-&gt;root-&gt;foo</filename></entry>
   <entry>&nil; (&absolute-k; <filename>"foo"</filename>)</entry></row>
 <row><entry><filename>foo</filename></entry><entry>current</entry>
   <entry><filename>device-&gt;foo</filename></entry>
   <entry>&nil; (&relative-k; <filename>"foo"</filename>)</entry></row>
 <row><entry><filename>'/foo'</filename></entry><entry>current</entry>
   <entry><filename>device-&gt;up-&gt;foo</filename></entry>
   <entry>&nil; (&relative-k; &parent-k; <filename>"foo"</filename>)
   </entry></row>
 <row><entry><filename>'//foo/bar'</filename></entry><entry>current</entry>
   <entry><filename>device-&gt;up-&gt;up-&gt;foo-&gt;bar</filename></entry>
   <entry>&nil; (&relative-k; &parent-k; &parent-k; <filename>"foo"
               "bar"</filename>)</entry></row>
 <row><entry>&file-bsla;</entry><entry>current</entry>
   <entry><filename>device</filename></entry>
   <entry>&nil; (&relative-k;)</entry></row>
</tbody></tgroup></table>

<para>Appending a &file-slash; to a path string that is non-empty and
 does not end with &file-colon; or &file-slash; does not change its
 meaning.  This &file-slash; must be appended before another non-empty
 component can be appended.  But appending a &file-slash; to a path
 string that is empty or ends with &file-colon; or &file-slash; means
 going up to the parent directory!</para>

<para>We interpret any path string that is empty or ends with
 &file-colon; or &file-slash; as pathname of a directory (with both
 &name-r; and &type-r; being &nil;).</para>
</listitem></varlistentry></variablelist>
<!-- #endif -->

<!-- #ifdef PATHNAME_UNIX -->
<variablelist>
<varlistentry><term>Platform dependent: &unix; platforms only.</term>
<listitem><variablelist>&path-comps;
<varlistentry><term>&host-r;</term>&always-nil;</varlistentry>
<varlistentry><term>&device-r;</term>&always-nil;</varlistentry>
<varlistentry><term>&directory-r;</term>
 <listitem><table id="unix-dir-table" frame="all">&dir-title;
 <tgroup cols="2" colsep="1" rowsep="1" align="center">
   &elt-val-meaning-header;<tbody>
 &startp-rel-abs; &subdirs-def; &subdir-string-or-wild;
 </tbody></tgroup></table></listitem></varlistentry>
<varlistentry><term>&name-r;</term>&wild-string-or-nil;</varlistentry>
<varlistentry><term>&type-r;</term>&wild-string-or-nil;</varlistentry>
&version-nil;
</variablelist>

<para>A &unix; &name-type-split;</para>

<table id="unix-filename-table" frame="all"><title>filename notations</title>
 <tgroup cols="2" colsep="1" rowsep="1" align="center"><tbody>
 <row><entry>External notation:</entry><entry>
  <filename>server:sub1.typ/sub2.typ/name.typ</filename></entry></row>
 <row><entry>using defaults:</entry><entry>
  <filename>       sub1.typ/sub2.typ/name.typ</filename></entry></row>
 <row><entry>or</entry><entry>
  <filename>                         name.typ</filename></entry></row>
 <row><entry>or</entry><entry>
  <filename>       sub1.typ/**/sub3.typ/x*.lisp</filename></entry></row>
 <row><entry>or similar.</entry><entry/></row>
</tbody></tgroup></table>
</listitem></varlistentry></variablelist>
<!-- #endif -->

<!-- #if defined(PATHNAME_OS2) -->
<variablelist>
<varlistentry><term>Platform dependent: &os2; platforms only.</term>
<listitem><variablelist>&path-comps;
<varlistentry><term>&host-r;</term>&always-nil;</varlistentry>
<varlistentry><term>&device-r;</term>
 <listitem><simpara>&nil; or &wild-k; or &file-letter-uc;
 </simpara></listitem></varlistentry>
<varlistentry><term>&directory-r;</term>
 <listitem><table id="os2-dir-table" frame="all">&dir-title;
 <tgroup cols="2" colsep="1" rowsep="1" align="center">
  &elt-val-meaning-header;<tbody>
 &startp-rel-abs; &subdirs-def; &subdir-string-or-wild;
 </tbody></tgroup></table></listitem></varlistentry>
<varlistentry><term>&name-r;</term>&wild-string-or-nil;</varlistentry>
<varlistentry><term>&type-r;</term>&wild-string-or-nil;</varlistentry>
&version-nil;
</variablelist>

<para>An &os2; &name-type-split;</para>

<table id="os2-filename-table" frame="all"><title>filename notations</title>
 <tgroup cols="2" colsep="1" rowsep="1" align="center"><tbody>
 <row><entry>External notation:</entry>
  <entry><filename>A:\sub1.typ\sub2.typ\name.typ</filename></entry></row>
 <row><entry>using defaults:</entry>
  <entry><filename>  \sub1.typ\sub2.typ\name.typ</filename></entry></row>
 <row><entry>or</entry>
  <entry><filename>                     name.typ</filename></entry></row>
 <row><entry>or</entry>
  <entry><filename>*:\sub1.typ\**\sub3.typ\x*.lisp</filename></entry></row>
 <row><entry>or similar.</entry><entry/></row>
</tbody></tgroup></table>

<para>Instead of &file-bsla; one may use &file-slash;, as usual for DOS
 calls.</para></listitem></varlistentry></variablelist>
<!-- #endif -->

<!-- #if defined(PATHNAME_WIN32) -->
<variablelist>
<varlistentry><term>Platform dependent: &win32; platforms only.</term>
<listitem><variablelist>&path-comps;
<varlistentry><term>&host-r;</term>
 <listitem><simpara>&nil; or &simple-string-type;, wildcard characters may
   occur but don't act as wildcards</simpara></listitem></varlistentry>
<varlistentry><term>&device-r;</term>
 <listitem><simpara>&nil; or &wild-k; or &file-letter-uc;
 </simpara></listitem></varlistentry>
<varlistentry><term>&directory-r;</term>
 <listitem><table id="win32-dir-table" frame="all">&dir-title;
   <tgroup cols="2" colsep="1" rowsep="1" align="center">
    &elt-val-meaning-header;<tbody>
 &startp-rel-abs; &subdirs-def; &subdir-string-or-wild;
 </tbody></tgroup></table></listitem></varlistentry>
<varlistentry><term>&name-r;</term>&wild-string-or-nil;</varlistentry>
<varlistentry><term>&type-r;</term>&wild-string-or-nil;</varlistentry>
&version-nil;
</variablelist>

<para>If &host-r; is non-&nil;, &device-r; must be &nil;.</para>

<para>A &win32; &name-type-split;</para>

<table id="win32-filename-table" frame="all"><title>filename notations</title>
 <tgroup cols="2" colsep="1" rowsep="1" align="center"><tbody>
 <row><entry>External notation:</entry>
  <entry><filename>A:\sub1.typ\sub2.typ\name.typ</filename></entry></row>
 <row><entry>using defaults:</entry>
  <entry><filename>  \sub1.typ\sub2.typ\name.typ</filename></entry></row>
 <row><entry>or</entry>
  <entry><filename>                     name.typ</filename></entry></row>
 <row><entry>or</entry>
  <entry><filename>*:\sub1.typ\**\sub3.typ\x*.lisp</filename></entry></row>
 <row><entry>or similar.</entry><entry/></row>
</tbody></tgroup></table>

<para>Instead of &file-bsla; one may use &file-slash;, as usual for DOS
 calls.</para>

<para>If &host-r; is non-&nil; and the &directory-r;'s &startpoint-r;
 is not &absolute-k;, <literal role="sexp">(&parse-namestring; (&namestring;
 &path-r;))</literal> will not be the same as &path-r;.</para>

</listitem></varlistentry></variablelist>
<!-- #endif -->

<!-- #ifdef PATHNAME_NOEXT -->
<variablelist>
<varlistentry><term>Platform dependent: &unix;, &amiga;, &os2;, &win32;
    platforms only.</term>
<listitem><simpara>The wildcard characters: &file-star; matches any
 sequence of characters, &file-ques; matches any one character.
 </simpara></listitem></varlistentry>
</variablelist>
<!-- #endif -->

<!-- #ifdef PATHNAME_NOEXT -->
<variablelist id="name-type-split">
<varlistentry><term>Platform dependent:  &unix;, &amiga;, &os2;, &win32;
   platforms only.</term>
<listitem><para>A filename is split into name and type according to the
 following rule: <itemizedlist>
  <listitem><simpara>if there is no &file-dot; in the filename, then the
   &name-r; is everything, &type-r; is &nil;;</simpara></listitem>
  <listitem><simpara>if there is a &file-dot;, then &name-r; is the part
   before and &type-r; the part after the last dot.</simpara></listitem>
  </itemizedlist></para>
<simpara>Due to this name/type splitting rule, there are pathnames that
 cannot result from &parse-namestring;.
 To get a pathname whose type contains a dot or whose name contains a
 dot and whose type is &nil;, &make-pathname; must be used.  Example:
 <literal role="sexp">(&make-pathname; :name ".profile")</literal>.
 </simpara></listitem></varlistentry>
</variablelist>
<!-- #endif -->

<!-- #ifdef PATHNAME_RISCOS -->
<variablelist>
<varlistentry><term>Platform dependent: &acorn; platforms only.</term>
<listitem><simpara>RISC OS provides several file systems as standard
  (ADFS, IDEFS, NetFS, RamFS, NetPrint) and support for extra file
  systems (DOSFS, ResourceFS and DeviceFS).</simpara>

<simpara>A module called FileSwitch is at the center of all file system
 operation in RISC OS.  FileSwitch provides a common core of functions
 used by all file systems.  It only provides the parts of these services
 that are device independent.  The device dependent services that
 control the hardware are provided by separate modules, which are the
 actual file systems.  FileSwitch keeps track of active file systems and
 switches between them as necessary.</simpara>

<simpara>One of the file system modules that RISC OS provides is
 FileCore.  It takes the normal calls that FileSwitch sends to a file
 system module, and converts them to a simpler set of calls to modules
 that control the hardware.  Unlike FileSwitch it creates a fresh
 instantiation of itself for each module that it supports.  Using
 FileCore to build file system modules imposes a more rigid structure on
 it, as more of the file system is predefined.</simpara>

<simpara>As well as standard file systems, FileSwitch supports image
 file systems.  These provide facilities for RISC OS to handle media in
 foreign formats, and to support `image files' (or partitions) in those
 formats.  Rather than accessing the hardware directly they rely on
 standard RISC OS file systems to do so.  DOSFS is an example of an
 image file system used to handle DOS format discs.</simpara>

<variablelist>
<varlistentry><term>Terminology</term>
 <listitem><simpara>A pathname may include a file system name, a special
  field, a media name (e.g., a disc name), directory name(s), and the
  name of the object itself; each of these parts of a pathname is known
  as an `element' of the pathname.</simpara></listitem></varlistentry>
<varlistentry><term>Filenames</term>
 <listitem><simpara>Filename `elements' may be up to ten characters in
  length on FileCore-based file systems and on NetFS.  These characters
  may be digits or letters.  FileSwitch makes no distinction between
  upper and lower case, although file systems can do so.  As a general
  rule, you should not use top-bit-set characters in filenames, although
  some file systems (such as FileCore-based ones) support them.  Other
  characters may be used provided they do not have a special
  significance.  Those that do are listed below:</simpara>

 <variablelist>
  <varlistentry><term>&file-dot;</term>
   <listitem><simpara>Separates directory specifications, e.g.,
   <filename>$.fred</filename></simpara></listitem></varlistentry>
  <varlistentry><term>&file-colon;</term>
   <listitem><simpara>Introduces a drive or disc specification, e.g.,
   <filename>:0</filename>, <filename>:bigdisc</filename>.  It also
   marks the end of a file system name, e.g.,
   <filename>adfs:</filename></simpara></listitem></varlistentry>
  <varlistentry><term>&file-star;</term>
   <listitem><simpara>Acts as a `wildcard' to match zero or more
   characters.</simpara></listitem></varlistentry>
  <varlistentry><term><filename>#</filename></term>
   <listitem><simpara>Acts as a `wildcard' to match any single
   character.</simpara></listitem></varlistentry>
  <varlistentry><term><filename>$</filename></term>
   <listitem><simpara>is the name of the root directory of the disc.
   </simpara></listitem></varlistentry>
  <varlistentry><term><filename>&amp;</filename></term>
   <listitem><simpara>is the user root directory (URD)
   </simpara></listitem></varlistentry>
  <varlistentry><term><filename>@</filename></term>
   <listitem><simpara>is the currently selected directory (CSD)
   </simpara></listitem></varlistentry>
  <varlistentry><term><filename>^</filename></term>
   <listitem><simpara>is the `parent' directory
   </simpara></listitem></varlistentry>
  <varlistentry><term><filename>%</filename></term>
   <listitem><simpara>is the currently selected library (CSL)
   </simpara></listitem></varlistentry>
  <varlistentry><term>&file-bsla;</term>
   <listitem><simpara>is the previously selected directory (PSD)
   </simpara></listitem></varlistentry>
  </variablelist></listitem></varlistentry>

<varlistentry><term>Directories</term>
 <listitem><simpara>The root directory, <filename>$</filename>, forms
  the top of the directory hierarchy of the media which contains the
  CSD.  <filename>$</filename> does not have a parent directory, trying
  to access its parent will just access <filename>$</filename>.  Each
  directory name is separated by a &file-dot; character.
  For example:</simpara>
 <itemizedlist>
  <listitem><simpara><filename>$.Documents.Memos</filename>
   </simpara></listitem>
  <listitem><simpara><filename>%.cc</filename></simpara></listitem>
 </itemizedlist></listitem></varlistentry>

<varlistentry><term>File Systems</term>

 <listitem><simpara>Files may also be accessed on file systems other
  than the current one by prefixing the filename with a file system
  specification.  A file system name may appear between
  <filename>-</filename> characters, or suffixed by a
  &file-colon;, though the latter is advised since
  <filename>-</filename> can also be used to introduce a parameter on a
  command line, or as part of a file name.  For example:</simpara>

 <itemizedlist>
  <listitem><simpara><filename>-net-$.SystemMesg</filename>
   </simpara></listitem>
  <listitem><simpara><filename>adfs:%.aasm</filename></simpara></listitem>
 </itemizedlist></listitem></varlistentry>

<varlistentry><term>Special Fields</term>

 <listitem><simpara>Special fields are used to supply more information
  to the file system than you can using standard path names; for example
  NetFS and NetPrint use them to specify server addresses or names. They
  are introduced by a <filename>#</filename> character; a variety of
  syntaxes are possible:</simpara>

<itemizedlist>
  <listitem><simpara><filename>  net#MJHardy::disc1.mike</filename>
   </simpara></listitem>
  <listitem><simpara><filename>     #MJHardy::disc1.mike</filename>
   </simpara></listitem>
  <listitem><simpara><filename> -net#MJHardy-:disc1.mike</filename>
   </simpara></listitem>
  <listitem><simpara><filename>    -#MJHardy-:disc1.mike</filename>
   </simpara></listitem>
</itemizedlist>

 <simpara>The special fields here are all MJHardy, and give the name of
  the fileserver to use.  Special fields may use any character except for
  control characters, double quote '&quot;', solidus '|' and space.  If
  a special field contains a hyphen you may only use the first two
  syntaxes given above.</simpara></listitem></varlistentry>

<varlistentry><term><filename>File$Path</filename> and
  <filename>Run$Path</filename></term>

 <listitem><simpara>These two special variables control exactly where a
  file will be looked for, according to the operation being performed on
  it.</simpara>

<table frame="all"><title/>
 <tgroup cols="2" colsep="1" rowsep="1" align="center">
 <thead><row><entry>name</entry><entry>purpose</entry></row></thead><tbody>
 <row><entry>File$Path</entry>
    <entry>for read operations</entry></row>
 <row><entry>Run$Path</entry>
    <entry>for execute operations</entry></row>
</tbody></tgroup></table>

 <simpara>The contents of each variable should expand to a list or
  prefixes, separated by commas.  When a read operation is performed
  then the prefixes in <filename>File$Path</filename> are used in the
  order in which they are listed. The first object that matches is used,
  whether it be a file or directory.  Similarly any execute operation
  uses the prefixes in Run$Path.  These search paths are only used when
  the pathname does not contain an explicit file system reference, e.g.,
  executing <filename>adfs:file</filename> will not use
  <filename>Run$Path</filename>.</simpara></listitem></varlistentry>

<varlistentry><term>Other path variables</term>
 <listitem><para>You can set up other path variables and use them as
  pseudo file systems.  For example if you typed:
  <literallayout><userinput>*Set Source$Path adfs:$.src.,adfs:$.public.src.</userinput></literallayout>,
  you could then refer to the pseudo file system as
  <filename>Source:</filename> or (less preferable) as
  <filename>-Source-</filename>.  These path variables work in the same
  was as <filename>File$Path</filename> and
  <filename>Run$Path</filename>.</para>

 <simpara>NOTE: Path variables are not implemented in this version of
 &clisp;.  A workaround for this is to use "&lt;Foo$Path&gt;"
 instead of "Foo:" until they are made available.</simpara>
 </listitem></varlistentry>

<varlistentry id="pathnames-externally-acorn"><term>from Lisp-string
  notation to internal representation</term>

 <listitem><simpara><emphasis>No</emphasis> swapping.
   <filename>foo.lisp</filename> means file type
   &lisp-file; and file name <filename>foo</filename>.
   This is pseudo-BNF:</simpara>
 <variablelist>
  <varlistentry><term>legal character ::==</term>
   <listitem><simpara>any ISO latin-1 graphic character &ge; ' ' except
    '.' ':' '*' '#' '$' '&amp;' '@' '^' '%' '\' '?'
    </simpara></listitem></varlistentry>
  <varlistentry><term>extended legal character ::==</term>
   <listitem><simpara>any ISO latin-1 graphic character &ge; ' ' except
    ':' '&quot;' '|'
    </simpara></listitem></varlistentry>
  <varlistentry><term>legal-wild char ::==</term>
   <listitem><simpara>legal char | '*' | '#' | '?'
    </simpara></listitem></varlistentry>
  <varlistentry><term>host ::==</term>
   <listitem><simpara> '-' { extended legal char except '-' }+ '-'
    | { extended legal char except '-' } { extended legal char }* ':' | empty
    </simpara></listitem></varlistentry>
  <varlistentry><term>device ::==</term>
   <listitem><simpara> ':' { legal char }+ '.' | empty
    </simpara></listitem></varlistentry>
  <varlistentry><term>directory ::==</term>
    <listitem><para> { '$' | '&amp;' | '@' | '%' | '\' } '.'
    { subdirectory }* | { subdirectory }+ | empty
    <table frame="all"><title/>
    <tgroup cols="2" colsep="1" rowsep="1" align="center"><tbody>
     <row><entry>'$' -&gt;</entry>
         <entry>&absolute-k; &root-k;</entry></row>
     <row><entry>'&amp;' -&gt;</entry>
         <entry>&absolute-k; &home-k;</entry></row>
     <row><entry>'@' -&gt;</entry>
         <entry>&absolute-k; &current-k;</entry></row>
     <row><entry>'%' -&gt;</entry>
         <entry>&absolute-k; &library-k;</entry></row>
     <row><entry>'\' -&gt;</entry>
         <entry>&absolute-k; &previous-k;</entry></row>
     <row><entry>else</entry><entry>&relative-k;</entry></row>
    </tbody></tgroup></table></para></listitem></varlistentry>
  <varlistentry><term>subdirectory ::==</term>
   <listitem><para>{ '^' | { legal-wild char }+ } '.'
   <table frame="all"><title/>
    <tgroup cols="2" colsep="1" rowsep="1" align="center"><tbody>
    <row><entry>'^' -&gt;</entry><entry>&parent-k;</entry></row>
   </tbody></tgroup></table></para></listitem></varlistentry>
  <varlistentry><term>filename ::==</term>
   <listitem><simpara>{ { legal-wild char }+ | empty }
   </simpara></listitem></varlistentry>
  <varlistentry><term>filetype ::==</term>
   <listitem><simpara>{ '.' { legal-wild char }+ | empty }
   </simpara></listitem></varlistentry>
  <varlistentry><term>pathname ::==</term>
   <listitem><simpara>host device directory filename filetype
   </simpara></listitem></varlistentry>
 </variablelist>

<table id="acorn-path-example-table" frame="all"><title>Examples</title>
 <tgroup cols="6" colsep="1" rowsep="1" align="center">
   <thead><row><entry>String</entry><entry>Hostname</entry>
   <entry>Device</entry><entry>Directory</entry>
   <entry>Name</entry><entry>Type</entry></row></thead><tbody>
 <row><entry><filename>-net-$.SystemMesg</filename></entry>
   <entry><filename>net</filename></entry>
   <entry>&nil;</entry>
   <entry><literal role="sexp">(&absolute-k; &root-k;)</literal></entry>
   <entry><filename>SystemMesg</filename></entry>
   <entry>&nil;</entry></row>
 <row><entry><filename>net#MJHardy::disc1.mike</filename></entry>
   <entry><filename>net#MJHardy</filename></entry>
   <entry><filename>disc1</filename></entry>
   <entry><literal role="sexp">(&absolute-k; &root-k;)</literal></entry>
   <entry><filename>mike</filename></entry>
   <entry>&nil;</entry></row>
 <row><entry><filename>#MJHardy::disc1.mike</filename></entry>
   <entry><filename>#MJHardy</filename></entry>
   <entry><filename>disc1</filename></entry>
   <entry><literal role="sexp">(&absolute-k; &root-k;)</literal></entry>
   <entry><filename>mike</filename></entry>
   <entry>&nil;</entry></row>
 <row><entry><filename>-net#MJHardy-:disc1.mike</filename></entry>
   <entry><filename>net#MJHardy</filename></entry>
   <entry><filename>disc1</filename></entry>
   <entry><literal role="sexp">(&absolute-k; &root-k;)</literal></entry>
   <entry><filename>mike</filename></entry>
   <entry>&nil;</entry></row>
 <row><entry><filename>-#MJHardy-:disc1.mike</filename></entry>
   <entry><filename>#MJHardy</filename></entry>
   <entry><filename>disc1</filename></entry>
   <entry><literal role="sexp">(&absolute-k; &root-k;)</literal></entry>
   <entry><filename>mike</filename></entry>
   <entry>&nil;</entry></row>
 <row><entry><filename>@.foo</filename></entry>
   <entry>&nil;</entry>
   <entry>&nil;</entry>
   <entry><literal role="sexp">(&absolute-k; &current-k;)</literal></entry>
   <entry><filename>foo</filename></entry>
   <entry>&nil;</entry></row>
 <row><entry><filename>foo</filename></entry>
   <entry>&nil;</entry>
   <entry>&nil;</entry>
   <entry><literal role="sexp">(&relative-k;)</literal></entry>
   <entry><filename>foo</filename></entry>
   <entry>&nil;</entry></row>
 <row><entry><filename>^.</filename></entry>
   <entry>&nil;</entry>
   <entry>&nil;</entry>
   <entry><literal role="sexp">(&relative-k; &parent-k;)</literal></entry>
   <entry>&nil;</entry>
   <entry>&nil;</entry></row>
 <row><entry><filename>@.^.</filename></entry>
   <entry>&nil;</entry>
   <entry>&nil;</entry>
   <entry><literal role="sexp">(&absolute-k; &current-k;
        &parent-k;)</literal></entry>
   <entry>&nil;</entry>
   <entry>&nil;</entry></row>
 <row><entry><filename>foo.bar</filename></entry>
   <entry>&nil;</entry>
   <entry>&nil;</entry>
   <entry><literal role="sexp">(&relative-k;)</literal></entry>
   <entry><filename>foo</filename></entry>
   <entry><filename>bar</filename></entry></row>
 <row><entry><filename>foo.bar.baz</filename></entry>
   <entry>&nil;</entry>
   <entry>&nil;</entry>
   <entry><literal role="sexp">(&relative-k; "foo")</literal></entry>
   <entry><filename>bar</filename></entry>
   <entry><filename>baz</filename></entry></row>
 <row><entry><filename>foo.bar.</filename></entry>
   <entry>&nil;</entry>
   <entry>&nil;</entry>
   <entry><literal role="sexp">(&relative-k; "foo" "bar")</literal></entry>
   <entry>&nil;</entry>
   <entry>&nil;</entry></row>
 <row><entry><filename>foo.@.</filename></entry>
   <entry>illegal</entry>
   <entry/>
   <entry/>
   <entry/>
   <entry/></row>
</tbody></tgroup></table></listitem></varlistentry>

<varlistentry><term>From internal representation to RISCOS string</term>

 <listitem><simpara>with swapping <emphasis>only</emphasis> of name/type
  components.</simpara>

<table frame="all"><title/>
 <tgroup cols="6" colsep="1" rowsep="1" align="center">
  <thead><row><entry>Hostname</entry><entry>Device</entry>
  <entry>Directory</entry><entry>Name</entry>
  <entry>Type</entry><entry>RISCOS String</entry></row></thead><tbody>
 <row><entry><filename>net</filename></entry>
   <entry><filename>disc1</filename></entry>
   <entry><literal role="sexp">(&absolute-k; &root-k;)</literal></entry>
   <entry><filename>foo</filename></entry>
   <entry>&nil;</entry>
   <entry><filename>net::disc1.$.foo</filename></entry></row>
 <row><entry><filename>net#MJ</filename></entry>
   <entry><filename>disc1</filename></entry>
   <entry><literal role="sexp">(&absolute-k; &root-k; "foo")</literal></entry>
   <entry><filename>bar</filename></entry>
   <entry><filename>baz</filename></entry>
   <entry><filename>net#MJ::disc1.$.foo.baz.bar</filename></entry></row>
 <row><entry><filename>adfs</filename></entry>
   <entry><filename>4</filename></entry>
   <entry><literal role="sexp">(&absolute-k; &root-k; "foo"
        "bar")</literal></entry>
   <entry>&nil;</entry>
   <entry>&nil;</entry>
   <entry><filename>adfs::4.$.foo.bar</filename></entry></row>
 <row><entry>&nil;</entry>
   <entry><filename>disc1</filename></entry>
   <entry><literal role="sexp">(&absolute-k; &root-k; "foo")</literal></entry>
   <entry><filename>bar</filename></entry>
   <entry>&nil;</entry>
   <entry><filename>:disc1.$.foo.bar</filename></entry></row>
 <row><entry>&nil;</entry>
   <entry><filename>disc1</filename></entry>
   <entry><literal role="sexp">(&absolute-k; &current-k;)</literal></entry>
   <entry>&nil;</entry>
   <entry>&nil;</entry>
   <entry>illegal here</entry></row>
 <row><entry>&nil;</entry>
   <entry><filename>disc1</filename></entry>
   <entry><literal role="sexp">(&relative-k;)</literal></entry>
   <entry>&nil;</entry>
   <entry>&nil;</entry>
   <entry><filename>:disc1.</filename></entry></row>
 <row><entry>&nil;</entry>
   <entry><filename>disc1</filename></entry>
   <entry>&nil;</entry>
   <entry>&nil;</entry>
   <entry>&nil;</entry>
   <entry><filename>:disc1.</filename></entry></row>
 <row><entry>&nil;</entry>
   <entry>&nil;</entry>
   <entry><literal role="sexp">(&absolute-k; &root-k;)</literal></entry>
   <entry><filename>foo</filename></entry>
   <entry>&nil;</entry>
   <entry><filename>$.foo</filename></entry></row>
 <row><entry>&nil;</entry>
   <entry>&nil;</entry>
   <entry><literal role="sexp">(&absolute-k; &current-k;)</literal></entry>
   <entry><filename>foo</filename></entry>
   <entry>&nil;</entry>
   <entry><filename>@.foo</filename></entry></row>
 <row><entry>&nil;</entry>
   <entry>&nil;</entry>
   <entry><literal role="sexp">(&relative-k;)</literal></entry>
   <entry><filename>foo</filename></entry>
   <entry><filename>bar</filename></entry>
   <entry><filename>bar.foo</filename></entry></row>
 <row><entry>&nil;</entry>
   <entry>&nil;</entry>
   <entry><literal role="sexp">(&relative-k; "foo")</literal></entry>
   <entry><filename>bar</filename></entry>
   <entry><filename>baz</filename></entry>
   <entry><filename>foo.baz.bar</filename></entry></row>
 <row><entry>&nil;</entry>
   <entry>&nil;</entry>
   <entry><literal role="sexp">(&absolute-k; &library-k;)</literal></entry>
   <entry><filename>bar</filename></entry>
   <entry>&nil;</entry>
   <entry><filename>%.bar</filename></entry></row>
 <row><entry>&nil;</entry>
   <entry>&nil;</entry>
   <entry><literal role="sexp">(&absolute-k; &library-k; "foo")</literal></entry>
   <entry><filename>bar</filename></entry>
   <entry>&nil;</entry>
   <entry><filename>%.foo.bar</filename></entry></row>
 <row><entry>&nil;</entry>
   <entry>&nil;</entry>
   <entry><literal role="sexp">(&relative-k;)</literal></entry>
   <entry><filename>foo</filename></entry>
   <entry><filename>bar</filename></entry>
   <entry><filename>bar.foo</filename></entry></row>
 <row><entry>&nil;</entry>
   <entry>&nil;</entry>
   <entry><literal role="sexp">(&relative-k; "foo")</literal></entry>
   <entry><filename>bar</filename></entry>
   <entry>&nil;</entry>
   <entry><filename>foo.bar</filename></entry></row>
 <row><entry>&nil;</entry>
   <entry>&nil;</entry>
   <entry><literal role="sexp">(&relative-k; "foo")</literal></entry>
   <entry>&nil;</entry>
   <entry><filename>bar</filename></entry>
   <entry>illegal here</entry></row>
</tbody></tgroup></table>

<simpara>That is, the RISCOS string is the flattening-concatenation
 of</simpara>

<programlisting>
  (append
    (if (null hostname) "" (append hostname ":"))
    (if (null device) "" (append ":" device "."))
    (case (pop directory)
      (:absolute (case (pop directory)
                         (:root "$.")
                         (:home "&amp;.")
                         (:current "@.")
                         (:library "%.")
                         (:previous "\\.")))
      (:relative ""))
    (mapcar (lambda (subdir) (append subdir ".")) directory)
    (if (null name)
        (if (null type) "" (error "type with name illegal here"))
        (if (null type)
            name
            (append type "." name))))
</programlisting>
</listitem></varlistentry>

<varlistentry><term>internal representation</term>
<listitem><variablelist>&path-comps;
<varlistentry><term>&host-r;</term>&string-or-nil;</varlistentry>
<varlistentry><term>&device-r;</term>&string-or-nil;</varlistentry>
<varlistentry><term>&directory-r;</term>
 <listitem><table id="acorn-dir-table" frame="all">&dir-title;
  <tgroup cols="2" colsep="1" rowsep="1" align="center">
   <thead><row><entry>element</entry><entry>values</entry></row></thead><tbody>
 <row><entry>&startpoint-r;</entry>
   <entry>&relative-k; | &absolute-k;
   <replaceable>anchor</replaceable></entry></row>
 <row><entry><replaceable>anchor</replaceable></entry>
   <entry>&root-k; | &home-k; | &current-k; | &library-k; |
   &previous-k;</entry></row>
 &subdirs-def;
 <row><entry>&subdir-r;</entry><entry>&parent-k;</entry></row>
 <row><entry>&subdir-r;</entry>
   <entry>&simple-string-type;, may contain wildcard characters
   &file-ques;,<filename>#</filename> and &file-star;</entry></row>
 </tbody></tgroup></table></listitem></varlistentry>
<varlistentry><term>&name-r;</term>
 <listitem><simpara>&simple-string-type; or &nil;, may contain wildcard
 characters &file-ques;,<filename>#</filename> and
 &file-star; (may also be specified as &wild-k;)
 </simpara></listitem></varlistentry>
<varlistentry><term>&type-r;</term>
 <listitem><simpara>&nil; or &simple-string-type;, may contain wildcard
 characters &file-ques;,<filename>#</filename> and
 &file-star; (may also be specified as &wild-k;)
 </simpara></listitem></varlistentry>
&version-nil;
</variablelist>

<para>Constraint: &startpoint-r; is not &absolute-k; &root-k; only if device
 is &nil;. If the device is specified, the pathname must be &absolute-k;
 &root-k;.</para>

<para>The wildcard characters: &file-star; matches any
 sequence of characters, <filename>'#'</filename> or
 &file-ques; matches any one character.</para>

<para>Due to the name/type swapping rule, there are pathnames that
 cannot result from &parse-namestring;.  To get a pathname whose type is
 &nil;, &make-pathname; must be used.  Example: <literal
 role="sexp">(&make-pathname; :directory "!Clisp." :name
 "README")</literal>.</para>

</listitem></varlistentry></variablelist>
</listitem></varlistentry></variablelist>
<!-- #endif -->

</section>

<section id="path-external-notation"><title>External notation.</title>

<para>External notation of pathnames (cf. &parse-namestring; and
 &namestring;), of course without spaces, [,],{,}:</para>

<variablelist>
<!-- #ifdef PATHNAME_MSDOS -->
<varlistentry><term>Platform dependent: &dos; platforms only.</term>
<listitem><table id="dos-path-external-table" frame="all"><title/>
 <tgroup cols="2" colsep="1" rowsep="1" align="center"><tbody>
  <row><entry>[ [drivespec] : ]</entry>
   <entry>a letter &file-star;|&file-letter-lc;|&file-letter-uc;</entry></row>
  <row><entry>{ name [. type] \ }</entry>
   <entry>each one a subdirectory, &file-bsla; may be replaced by
    &file-slash;</entry></row>
  <row><entry>[ name [. type] ]</entry>
   <entry>filename with type (extension)</entry></row>
</tbody></tgroup></table>

<para>Name and type may be character sequences of any &length;
 (consisting of alphanumeric characters and <filename>-</filename>,
 <filename>_</filename>).  They are shortened to 8 (respectively 3)
 characters and converted to upper case.  A single &file-star; is
 allowed for &wild-k;.</para>
</listitem></varlistentry>
<!-- #endif -->

<!-- #ifdef PATHNAME_AMIGAOS -->
<varlistentry><term>Platform dependent: &amiga; platforms only.</term>
<listitem><simpara>see <link linkend="pathnames-externally-amiga">above</link>.
</simpara></listitem></varlistentry>
<!-- #endif -->

<!-- #ifdef PATHNAME_UNIX -->
<varlistentry><term>Platform dependent: &unix; platforms only.</term>
<listitem><table id="unix-path-external-table" frame="all"><title/>
 <tgroup cols="2" colsep="1" rowsep="1" align="center"><tbody>
  <row><entry>[ &file-slash; ]</entry>
   <entry>&file-slash; denotes absolute pathnames</entry></row>
  <row><entry>{ &name-r; &file-slash; }</entry>
   <entry>each one a subdirectory</entry></row>
  <row><entry>[ &name-r; [&file-dot; &type-r;] ]</entry>
   <entry>filename with type (extension)</entry></row>
</tbody></tgroup></table>

<para>Name and type may be character sequences of any &length;
 (consisting of printing ASCII characters, except &file-slash;).</para>
</listitem></varlistentry>
<!-- #endif -->

<!-- #if defined(PATHNAME_OS2) || defined(PATHNAME_WIN32) -->
<varlistentry><term>Platform dependent: &os2;, &win32; platforms only.</term>
<listitem><table id="win32-path-external-table" frame="all"><title/>
 <tgroup cols="2" colsep="1" rowsep="1" align="center"><tbody>
  <row><entry>[ [<replaceable>drivespec</replaceable>] : ]</entry>
   <entry>a letter &file-star;|&file-letter-lc;|&file-letter-uc;</entry></row>
  <row><entry>{ &name-r; [. &type-r;] \ }</entry>
   <entry>each one a subdirectory, &file-bsla; may be
     replaced by &file-slash;</entry></row>
  <row><entry>[ &name-r; [. &type-r;] ]</entry>
   <entry>filename with type (extension)</entry></row>
</tbody></tgroup></table>

<para>Name and type may be character sequences of any &length;
 (consisting of printing ASCII characters, except &file-slash;,
 &file-bsla;, &file-colon;).</para></listitem></varlistentry>
<!-- #endif -->

<!-- #ifdef PATHNAME_RISCOS -->
<varlistentry><term>Platform dependent: &acorn; platforms only.</term>
<listitem><simpara>see <link linkend="pathnames-externally-acorn">above</link>.
</simpara></listitem></varlistentry>
<!-- #endif -->

</variablelist>

<para>&namestring; has an optional flag argument: <literal
 role="sexp">(&namestring; &path-r; &t;)</literal> returns an external
 notation suitable for passing to the operating system or other
 programs.</para>

<!-- #if !defined(USER_HOMEDIR) -->
<variablelist>
<varlistentry><term>Platform dependent:  &dos;, &os2;, &amiga;
   platforms only.</term>
<listitem><simpara>The function &user-homedir-pathname; is not implemented.
</simpara></listitem></varlistentry>
<!-- #if defined(MSDOS) -->

<varlistentry><term>Platform dependent: &dos;, &os2; platforms only.</term>
<listitem><para>If you really need that function, you might define it
    like this:
<programlisting>
(defun user-homedir-pathname (&amp;optional host)
  (declare (ignore host))
  (or (system::getenv "HOME") "\\"))
</programlisting></para></listitem></varlistentry>
<!-- #endif -->

</variablelist>
<!-- #endif -->

</section>

<!-- #ifdef LOGICAL_PATHNAMES -->
<section id="log-path"><title>Logical Pathnames
   <ulink url="&clhs;/Body/sec_19-3.html">[CLHS-19.3]</ulink></title>

<para>When the argument of the function &translate-logical-pathname; is
 a string, it is interpreted as a logical pathname string.</para>

</section>
<!-- #endif -->

<section id="filename-dict"><title>The Filenames Dictionary
   <ulink url="&clhs;/Body/sec_the_filen_s_dictionary.html">[CLHS-19.4]</ulink></title>

<para>&pathname; always returns a physical pathname.</para>

<para>&pathname-match-p; does not interpret missing components as
 wild.</para>

<para>&translate-pathname; has two additional keywords: <literal
 role="sexp">(&translate-pathname; <replaceable>source</replaceable>
 <replaceable>from-wildname</replaceable>
 <replaceable>to-wildname</replaceable> &key-amp; &all-k;
 &merge-k;)</literal></para>

<para>If &all-k; is specified and non-&nil;, a list of all resulting
 pathnames, corresponding to all matches of <literal
 role="sexp">(&pathname-match-p; <replaceable>source</replaceable>
 <replaceable>from-wildname</replaceable>)</literal>, is returned.  If
 &merge-k; is specified and &nil;, unspecified pieces of
 <replaceable>to-pathname</replaceable> are not replaced by
 corresponding pieces of <replaceable>source</replaceable>.</para>

<section id="parsename"><title>Function &parse-namestring;</title>

<para><literal role="sexp">(&parse-namestring; &string-r; &optional-amp;
   &host-r; &defaults-r; &key-amp; &start-r; &end-r;
   <replaceable>junk-allowed</replaceable>)</literal>
 returns a logical pathname only if &host-r; is a
 <ulink url="&clhs;/Body/glo_l.html#logical_host">logical host</ulink>
 or &host-r; is &nil; and &defaults-r; is a &logical-pathname-class;.
 To construct a logical pathname from a string, the function
 &logical-pathname; can be used.</para>

<para>The ANSI-mandated behavior of recognizing logical pathnames when
the &string-r; begins with some alphanumeric characters followed by a
colon (<keysym>#\:</keysym>) is very confusing (cf.
<literal>"c:/autoexec.bat"</literal>, <literal>"home:.clisprc"</literal>
and <literal>"prep:/pub/gnu"</literal>) and therefore disabled by default.
To enable the ANSI standard behavior, you should set &parsename; to
non-&nil;.</para>

</section>

<section id="pathmerge"><title>Function &merge-pathnames;</title>

<para><literal role="sexp">(&merge-pathnames; &path-r;
   [<replaceable>default-pathname</replaceable>])</literal> returns a
   logical pathname only if
 <replaceable>default-pathname</replaceable> is a logical pathname.  To
 construct a logical pathname from a string, the function
 &logical-pathname; can be used.</para>

<para>When both &path-r; and <replaceable>default-pathname</replaceable>
 are relative pathnames, the behavior depends on &pathmerge;: when it is
 &nil;, then &clisp; retains its traditional behavior:
 <literal role="sexp">(&merge-pathnames; #p"x/" #p"y/")</literal>
 evaluates to <filename>#p"x/"</filename></para>

<para><emphasis>Rationale</emphasis>: &merge-pathnames; is used to
 specify default components for pathnames, so there is some analogy
 between <literal role="sexp">(&merge-pathnames; a b)</literal> and
 <literal role="sexp">(or a b)</literal>.  Obviously putting in the same
 default a second time should do the same as putting it in once:
 <literal role="sexp">(or a b b)</literal> is the same as <literal
 role="sexp">(or a b)</literal>, so <literal
 role="sexp">(&merge-pathnames; (&merge-pathnames; a b) b)</literal>
 should be the same as <literal role="sexp">(&merge-pathnames; a
 b)</literal>.</para>

<para>(This question actually matters because in &cl; there is no
 distinction between <quote>pathnames with defaults merged-in</quote> and
 <quote>pathnames with defaults not yet applied</quote>.)</para>

<para>Now, <literal role="sexp">(&merge-pathnames; (&merge-pathnames;
 '#p"x/" '#p"y/") '#p"y/")</literal> and <literal
 role="sexp">(&merge-pathnames; '#p"x/" '#p"y/")</literal> are &equal;
 in &clisp; (when &pathmerge; is &nil;), but not in implementations that
 strictly follow the &ansi-cl; spec.  In fact, the above twice-default =
 once-default rule holds for all pathnames in &clisp;.</para>

<para>When &pathmerge; is non-&nil;, the normal
 &ansi-cl; behavior is exhibited:
 <literal role="sexp">(&merge-pathnames; #p"x/" #p"y/")</literal>
  evaluates to <filename>#p"y/x/"</filename></para>

<para>The rationale is that <quote>merge</quote> is
 <emphasis>merge</emphasis> and not <emphasis>or</emphasis>.</para>

</section>

<section id="load-lpt">
   <title>Function &load-logical-pathname-translations;</title>

<para>When the &host-r; argument to &load-logical-pathname-translations;
is not a defined logical host yet, we proceed as follows:
<orderedlist numeration="arabic">
 <listitem><simpara>If both environment variables
  <envar>LOGICAL_HOST_&host-r;_FROM</envar> and
  <envar>LOGICAL_HOST_&host-r;_TO</envar> exist, then they define the
  map of the &host-r;.</simpara></listitem>
 <listitem><simpara>If the environment variable
  <envar>LOGICAL_HOST_&host-r;</envar> exists, its value is read from,
  and the result is passed to <literal role="sexp">(&setf;
  &logical-pathname-translations;)</literal>.</simpara></listitem>
 <listitem><simpara>Variable &load-lpt-db; is consulted.
  Its value should be a list of files and/or directories,
  which are searched for in the &load-paths;, just like for &load;.
  When the element is a file, it is &read; from,
  <ulink url="http://www.franz.com/support/documentation/6.0/doc/pathnames.htm#load-logical-pathname-translations-2">Allegro CL-style</ulink>,
  odd objects being host names and even object being their
  &logical-pathname-translations;.
  When the element is a directory, a file, named <filename>&host-r;</filename>
  or <filename>&host-r;.host</filename>, in that directory, is &read;
  from once, <ulink url="http://cvs2.cons.org/ftp-area/cmucl/doc/cmu-user/extensions.html#logical-pathnames">CMUCL-style</ulink>,
  the object read being the
  &logical-pathname-translations; of the &host-r;.</simpara></listitem>
</orderedlist></para>
</section>

</section>
</chapter>


<chapter id="files"><title>Files
   <ulink url="&clhs;/Body/chap-20.html">[CLHS-20]</ulink></title>

<section id="file-dict"><title>The Files Dictionary
   <ulink url="&clhs;/Body/sec_the_files_dictionary.html">[CLHS-20.2]</ulink></title>

<formalpara><title>&rename-file;</title>
<para>&rename-file; always returns a non-logical pathname as
 its first value.</para></formalpara>

<formalpara><title>&probe-file;</title>
<para>&probe-file; cannot be used to check whether a directory exists.
 Use the function &probe-dir; or the function &directory; for this
 purpose.</para></formalpara>

<formalpara><title>&file-author;</title>
<para>&file-author; always returns &nil;, because the operating systems
 &clisp; is ported to do not store a file's author in the file system.
 Some operating systems, such as Unix, have the notion of a file's
 owner, and some other &cl; implementations return the user name of the
 file owner.  &clisp; does not do this, because
 <emphasis>owner</emphasis> and <emphasis>author</emphasis> are not the
 same; in particular, authorship is preserved by copying, while
 ownership is not.</para></formalpara>

<formalpara id="probe-dir"><title>&probe-dir;</title>
<para><literal role="sexp">(&probe-dir; &path-r;)</literal> tests
 whether &path-r; exists and is a directory.
 It will, unlike &probe-file; or &truename;, not signal an error if the
 parent directory of &path-r; does not exist.</para></formalpara>

<section id="dir"><title>Function &directory;</title>

<para><literal role="sexp">(&directory; &optional-amp; &path-r;
 &key-amp; :full :circle)</literal> can run in two modes:
<itemizedlist>
 <listitem><simpara>If &path-r; contains no name or type component, a
  list of all matching directories is produced.</simpara></listitem>
 <listitem><simpara>Otherwise a list of all matching files is
  returned. If the <constant>:full</constant> argument is non-&nil;,
  this contains additional information: for each matching file you get a
  list of at least four elements <literal
  role="sexp">(<replaceable>file-pathname</replaceable>
  <replaceable>file-truename</replaceable>
  <replaceable>file-write-date-as-decoded-time</replaceable>
  <replaceable>file-length</replaceable>)</literal>.</simpara></listitem>
</itemizedlist>

<!-- #ifdef UNIX -->
<variablelist>
<varlistentry><term>Platform dependent: &unix; platforms only.</term>
<listitem><simpara>If the <constant>:circle</constant> argument is
 non-&nil;, the function avoids endless loops that may result from
 symbolic links.</simpara></listitem></varlistentry>
</variablelist>
<!-- #endif --></para>

<formalpara><title><function>ext:dir</function></title>
<para><literal role="sexp">(<function>ext:dir</function> &optional-amp;
 &path-r;)</literal> is like &directory;, but displays the pathnames
 instead of returning them. <literal role="sexp">(ext:dir)</literal>
 shows the contents of the current directory.</para></formalpara>

<variablelist id="cd"><title>&cd;</title>
<!-- #if defined(PATHNAME_UNIX) || defined(PATHNAME_AMIGAOS) -->
<varlistentry><term>Platform dependent: &unix;, &amiga; platforms only.</term>
 <listitem><simpara><literal role="sexp">(&cd; [&path-r;])</literal>
   manages the current directory.</simpara></listitem></varlistentry>
<!-- #elif defined(PATHNAME_RISCOS) -->
<varlistentry><term>Platform dependent: &acorn; platforms only.</term>
 <listitem><simpara><literal role="sexp">(&cd; [&path-r;])</literal>
   manages the current host, current device and the current directory.
   </simpara></listitem></varlistentry>
<!-- #else -->
<varlistentry><term>Platform dependent: &dos;, &os2;, &win32;
   platforms only.</term>
 <listitem><simpara><literal role="sexp">(&cd; [&path-r;])</literal>
   manages the current device and the current directory.
   </simpara></listitem></varlistentry>
<!-- #endif -->
</variablelist>

<formalpara><title>&cd;</title>
<para><literal role="sexp">(&cd; &path-r;)</literal> sets it, <literal
 role="sexp">(&cd;)</literal> returns it.</para></formalpara>

<formalpara><title><function>ext:default-directory</function></title>
<para><literal
 role="sexp">(<function>ext:default-directory</function>)</literal> is
 equivalent to <literal role="sexp">(&cd;)</literal>.  <literal
 role="sexp">(&setf; (<function>ext:default-directory</function>)
 &path-r;)</literal> is equivalent to <literal role="sexp">(&cd;
 &path-r;)</literal>, except for the return value.</para></formalpara>

<formalpara><title><function>ext:make-dir</function></title>
<para><literal role="sexp">(<function>ext:make-dir</function>
 <replaceable>directory-pathname</replaceable>)</literal> creates a new
 subdirectory.</para></formalpara>

<formalpara><title><function>ext:delete-dir</function></title>
<para><literal role="sexp">(<function>ext:delete-dir</function>
 <replaceable>directory-pathname</replaceable>)</literal> removes an
 (empty) subdirectory.</para></formalpara>

</section>
</section>
</chapter>


<chapter id="streams"><title>Streams
   <ulink url="&clhs;/Body/chap-21.html">[CLHS-21]</ulink></title>

<section id="streams-interactive"><title>Interactive Streams
   <ulink url="&clhs;/Body/sec_21-1-1-1-3.html">[CLHS-21.1.1.1.3]</ulink></title>

<para>Interactive streams are those whose next input might depend on a
 prompt one might output.</para>

</section>

<section id="terminal"><title>Terminal interaction.</title>

<!-- #ifdef GNU_READLINE -->
<variablelist><title>&readline;</title>
 <varlistentry><term>Platform dependent: &unix;, &dos;, &os2;
    platforms only, and only in &clisp; built &without; compile-time
    flag &noreadline;.</term>
 <listitem><simpara>Input through &terminal-io-var; uses the &readline;
  library.  Arrow keys can be used to move within the input history. The
  Tab key completes the symbol's name that is being typed.  See
  <ulink url="clreadline.html">clreadline.html</ulink> or
  <ulink url="clreadline.dvi">clreadline.dvi</ulink> for a complete
  description of the key bindings.  The &readline; library is not used
  if standard input and standard output do not both refer to the same
  terminal.</simpara></listitem></varlistentry>
</variablelist>
<!-- #endif -->

<!-- #if defined(KEYBOARD) || defined(AMIGAOS) -->
<variablelist><title>&with-kbd;</title>
<varlistentry><term>Platform dependent: &unix;, &amiga;, &acorn;, &dos;,
  &os2;, &win32; platforms only.</term>
<listitem><para>&terminal-io-var; is not the only stream that
 communicates directly with the user: During execution of the body of a
 <literal role="sexp">(&with-kbd; . &body-r;)</literal> form, <emphasis
 role="strong">&kbd-in;</emphasis> is the stream that reads the
 keystrokes from the keyboard.
 It returns every keystroke in detail, as &character-class; or
 &input-char; with the following bits:
<variablelist>
<!-- #if defined(MSDOS) || defined(WIN32) || defined(AMIGAOS) -->
 <varlistentry><term><constant>:hyper</constant></term>
  <listitem><simpara><emphasis>(Platform dependent: &dos;, &os2;,
   &win32;, &amiga; platforms only.)</emphasis>
   if a non-standard key.  These keys are:
<!-- #if defined(MSDOS) || defined(WIN32) -->
   Function keys, cursor keypads, numeric keypad <emphasis>(Platform
   dependent: &dos;, &os2;, &win32; platforms only)</emphasis>.
<!-- #endif -->
<!-- #ifdef AMIGAOS -->
     Function keys, cursor keypad <emphasis>(Platform dependent:
     &amiga; platforms only)</emphasis>.
<!-- #endif -->
   </simpara></listitem></varlistentry>
<!-- #endif -->
  <varlistentry><term>slot <replaceable>key</replaceable></term>
    <listitem><para>the key name, for non-standard keys:
      <variablelist>
<!-- #ifdef MSDOS -->
       <varlistentry><term>Platform dependent: &dos;, &os2;
          platforms only.</term>
      <listitem><table frame="all"><title/>
      <tgroup cols="2" colsep="1" rowsep="1" align="center">
       &key-value-header;<tbody>
       <row><entry><keycode>F1</keycode>..<keycode>F12</keycode></entry>
         <entry><constant>:F1</constant>..<constant>:F12</constant>
         </entry></row>
       <row><entry><keycode>Insert</keycode></entry>
         <entry><constant>:Insert</constant></entry></row>
       <row><entry><keycode>Delete</keycode></entry>
         <entry><constant>:Delete</constant></entry></row>
       <row><entry><keycode>Home</keycode></entry>
         <entry><constant>:Home</constant></entry></row>
       <row><entry><keycode>End</keycode></entry>
         <entry><constant>:End</constant></entry></row>
       <row><entry><keycode>PgUp</keycode></entry>
         <entry><constant>:PgUp</constant></entry></row>
       <row><entry><keycode>PgDn</keycode></entry>
         <entry><constant>:PgDn</constant></entry></row>
       <row><entry>Arrow keys</entry>
         <entry><constant>:Left</constant><constant>:Right</constant>
         <constant>:Up</constant><constant>:Down</constant></entry></row>
      </tbody></tgroup></table></listitem></varlistentry>
<!-- #endif -->

<!-- #if defined(UNIX) || defined(WIN32) -->
      <varlistentry><term>Platform dependent: &unix;, &win32;
         platforms only.</term>
      <listitem><table frame="all"><title/>
       <tgroup cols="2" colsep="1" rowsep="1" align="center">
       &key-value-header;<tbody>
       <row><entry><keycode>F1</keycode>..<keycode>F12</keycode></entry>
         <entry><constant>:F1</constant>..<constant>:F12</constant>
         </entry></row>
       <row><entry><keycode>Insert</keycode></entry>
         <entry><constant>:Insert</constant></entry></row>
       <row><entry><keycode>Delete</keycode></entry>
         <entry><constant>:Delete</constant></entry></row>
       <row><entry><keycode>Home</keycode></entry>
         <entry><constant>:Home</constant></entry></row>
       <row><entry><keycode>End</keycode></entry>
         <entry><constant>:End</constant></entry></row>
       <row><entry><keycode>Center</keycode></entry>
         <entry><constant>:Center</constant></entry></row>
       <row><entry><keycode>PgUp</keycode></entry>
         <entry><constant>:PgUp</constant></entry></row>
       <row><entry><keycode>PgDn</keycode></entry>
         <entry><constant>:PgDn</constant></entry></row>
       <row><entry>Arrow keys</entry>
         <entry><constant>:Left</constant><constant>:Right</constant>
         <constant>:Up</constant><constant>:Down</constant></entry></row>
      </tbody></tgroup></table></listitem></varlistentry>
<!-- #endif -->

<!-- #ifdef AMIGAOS -->
    <varlistentry><term>Platform dependent: &amiga; platforms only.</term>
    <listitem><table frame="all"><title/>
     <tgroup cols="2" colsep="1" rowsep="1" align="center">
      &key-value-header;<tbody>
       <row><entry><keycode>F1</keycode>..<keycode>F10</keycode></entry>
         <entry><constant>:F1</constant>..<constant>:F10</constant>
         </entry></row>
       <row><entry><keycode>Help</keycode></entry>
         <entry><constant>:Help</constant></entry></row>
       <row><entry>Arrow keys</entry>
         <entry><constant>:Left</constant><constant>:Right</constant>
         <constant>:Up</constant><constant>:Down</constant></entry></row>
      </tbody></tgroup></table></listitem></varlistentry>
<!-- #endif -->
      </variablelist></para></listitem></varlistentry>

  <varlistentry><term>slot &ch-r;</term>
    <listitem><simpara>the ASCII code for standard keys
    </simpara></listitem></varlistentry>

<!-- #if defined(MSDOS) || defined(WIN32) || defined(AMIGAOS) -->
  <varlistentry><term><constant>:super</constant></term>
   <listitem><simpara><emphasis>(Platform dependent: &dos;, &os2;,
     &win32;, &amiga; platforms only.)</emphasis>
  if pressed together with &shift; key(s) and if the keystroke would
  have been an other without &shift;.</simpara></listitem></varlistentry>
<!-- #endif -->
  <varlistentry><term><constant>:control</constant></term>
   <listitem><simpara>if pressed together with the &ctrl; key.
   </simpara></listitem></varlistentry>
<!-- #if defined(MSDOS) || defined(WIN32) -->
  <varlistentry><term><constant>:meta</constant></term>
  <listitem><simpara><emphasis>(Platform dependent: &dos;, &os2;, &win32;
    platforms only.)</emphasis> if pressed together with the &alt; key.
  </simpara></listitem></varlistentry>
<!-- #endif -->
</variablelist>

 This keyboard input is not echoed on the screen.  During execution of a
 <literal role="sexp">(&with-kbd; . &body-r;)</literal> form, no input from
 &terminal-io-var; or any synonymous stream should be requested.</para>
</listitem></varlistentry>
</variablelist>
<!-- #endif -->

<para>See also <link linkend="screen">Random Screen Access</link>.</para>

</section>

<section id="stream-dict"><title>The Streams Dictionary
   <ulink url="&clhs;/Body/sec_the_streams_dictionary.html">[CLHS-21.2.]</ulink></title>

<section id="stream-eltype"><title>Function &stream-element-type;</title>

<para>&stream-element-type; is &setf;able. The &stream-element-type; of
  &stream-class;s created by the functions &open;, &mk-pipe-in;
  &mk-pipe-out;, &mk-pipe-io;, &so-accept;, &so-connect;
  can be modified, if the old and the new &stream-element-type;s are either
<itemizedlist>
  <listitem><simpara>both equivalent to &character-class; or
      &unsigned-byte-8; or &signed-byte-8;; or</simpara></listitem>
  <listitem><simpara>both equivalent to &unsigned-byte-n; or
      &signed-byte-n;, with the same &n-r;.</simpara></listitem>
</itemizedlist></para>

<para>Note that you cannot change &stream-element-type; for some
built-in streams, such as terminal streams (which is normally the
value of &terminal-io-var;).</para>

</section>

<section id="bin-input"><title>Binary input, &read-byte;,
  &rd-integer; &amp; &rd-float;</title>

<para>The function <literal role="sexp">(&rd-integer; &stream-r;
    &eltype-r; &optional-amp; &endianness; &eof-ep; &eof-v;)</literal>
 reads a multi-byte &integer-class; from &stream-r;.
 &stream-r; should be a stream with &stream-element-type;
 &unsigned-byte-8;.
 &eltype-r; should be a type equivalent to &unsigned-byte-n;, where
 &n-r; is a multiple of 8.</para>

<para><literal role="sexp">(&rd-integer; &stream-r;
 &eltype-r;)</literal> is like <literal role="sexp">(&read-byte;
 &stream-r;)</literal> if &stream-r;'s &stream-element-type; were set to
 &eltype-r;, except that &stream-r;'s &file-position; will increase by
 <superscript>&n-r;</superscript>/<subscript>8</subscript>
 instead of 1.</para>

<para id="endianness">&endianness; can be <constant>:little</constant>
 or <constant>:big</constant>.  The default is
 <constant>:little</constant>, which corresponds to the &read-byte;
 behavior in &clisp;.</para>

<para>Together with <literal role="sexp">(&setf;
 &stream-element-type;)</literal>, this function permits mixed
 character/binary input from a stream.</para>

<para>The function <literal role="sexp">(&rd-float; &stream-r;
    &eltype-r; &optional-amp; &endianness; &eof-ep; &eof-v;)</literal>
 reads a floating-point number in IEEE binary representation from &stream-r;.
 &stream-r; should be a &stream-class; with &stream-element-type;
 &unsigned-byte-8;.
 &eltype-r; should be a type equivalent to
 &single-float-type; or &double-float-type;.</para>

</section>

<section id="bin-output"><title>Binary output, &write-byte;,
  &wr-integer; &amp; &wr-float;</title>

<para>The function <literal role="sexp">(&wr-integer;
    &int-r; &stream-r; &eltype-r; &optional-amp; &endianness;)</literal>
 writes a multi-byte integer to &stream-r;.
 &stream-r; should be a &stream-class; with &stream-element-type;
 &unsigned-byte-8;.
 &eltype-r; should be a type equivalent to &unsigned-byte-n;, where
 &n-r; is a multiple of 8.</para>

<para><literal role="sexp">(&wr-integer; &int-r; &stream-r;
 &eltype-r;)</literal> is like <literal role="sexp">(&write-byte;
 &int-r; &stream-r;)</literal> if &stream-r;'s &stream-element-type;
 were set to &eltype-r;, except that &stream-r;'s &file-position; will
 increase by <superscript>&n-r;</superscript>/<subscript>8</subscript>
 instead of 1.</para>

<para>Together with <literal role="sexp">(&setf;
  &stream-element-type;)</literal>, this function permits mixed
  character/binary output to a &stream-class;.</para>

<para>The function <literal role="sexp">(&wr-float;
    <replaceable>float</replaceable> &stream-r;
    &eltype-r; &optional-amp; &endianness;)</literal>
 writes a floating-point number in IEEE binary representation to &stream-r;.
 &stream-r; should be a &stream-class; with &stream-element-type;
 &unsigned-byte-8;.
 &eltype-r; should be a type equivalent to
 &single-float-type; or &double-float-type;.</para>

</section>

<section id="read-seq"><title>Function &read-sequence;</title>

<para>In addition to &read-sequence;, the following two
 functions are provided:</para>

<variablelist>
 <varlistentry id="rd-by-seq"><term>&rd-by-seq;
   performs multiple &read-byte; operations:</term>
 <listitem><simpara><literal role="sexp">(&rd-by-seq; &sequence-r;
   &stream-r; &key-amp; &start-k; &end-k;)</literal> fills the
   subsequence of &sequence-r; specified by &start-k; and &end-k; with
   &integer-class;s consecutively read from &stream-r;.  It returns the
   index of the first element of &sequence-r; that was not updated (=
   &end-r; or &lt; &end-r; if the &stream-r; reached its end).</simpara>
 <simpara>This function is especially efficient if &sequence-r; is a
   &unsigned-byte-vec; and &stream-r; is a &file-pipe-socket;
   &stream-class; with &stream-element-type; &unsigned-byte-8;.
 </simpara></listitem></varlistentry>
 <varlistentry id="rd-ch-seq"><term>&rd-ch-seq;
   performs multiple &read-char; operations:</term>
 <listitem><simpara><literal role="sexp">(&rd-ch-seq; &sequence-r;
  &stream-r; &key-amp; &start-k; &end-k;)</literal> fills the
  subsequence of &sequence-r; specified by &start-k; and &end-k; with
  characters consecutively read from &stream-r;.  It returns the index
  of the first element of &sequence-r; that was not updated (= &end-r;
  or &lt; &end-r; if the &stream-r; reached its end).</simpara>
 <simpara>This function is especially efficient if &sequence-r; is a
  &string-class; and &stream-k; is a &file-pipe-socket; stream with
  &stream-element-type; &character-class; or an <ulink
  url="&clhs;/Body/glo_i.html#input">input</ulink> <ulink
  url="&clhs;/Body/glo_s.html#string_stream">string stream</ulink>.
  </simpara></listitem></varlistentry>
</variablelist>

</section>

<section id="write-seq"><title>Function &write-sequence;</title>

<para>In addition to &write-sequence;, the following two
functions are provided:</para>

<variablelist>
 <varlistentry id="wr-by-seq"><term>&wr-by-seq;
   performs multiple &write-byte; operations:</term>
 <listitem><simpara><literal role="sexp">(&wr-by-seq; &sequence-r;
  &stream-k; &key-amp; &start-k; &end-k;)</literal> outputs the
  &integer-class;s of the subsequence of &sequence-r; specified by
  &start-k; and &end-k; to &stream-k;. It returns &sequence-r;.</simpara>
 <simpara>This function is especially efficient if &sequence-r; is a
  &unsigned-byte-vec; and &stream-r; is a &file-pipe-socket;
  &stream-class; with &stream-element-type; &unsigned-byte-8;.
 </simpara></listitem></varlistentry>
<varlistentry id="wr-ch-seq"><term>&wr-ch-seq;
  performs multiple &write-char; operations:</term>
 <listitem><simpara><literal role="sexp">(&wr-ch-seq; &sequence-r;
  &stream-k; &key-amp; &start-k; &end-k;)</literal> outputs the
  characters of the subsequence of &sequence-r; specified by &start-k;
  and &end-k; to &stream-k;.  It returns &sequence-r;.</simpara>
 <simpara>This function is especially efficient if &sequence-r; is a
  &string-class; and &stream-k; is a &file-pipe-socket; &stream-class;
  with &stream-element-type; &character-class;.
  </simpara></listitem></varlistentry>
</variablelist>
</section>

<!-- #if defined(MSDOS) || defined(WIN32) || (defined(UNIX) && (O_BINARY
!= 0)) -->
<section id="file-pos"><title>Function &file-position;</title>

<variablelist>
 <varlistentry><term>Platform dependent: &dos;, &os2;, &win32;
    platforms only.</term>
<listitem><simpara>&file-position; works on any buffered file stream.
  When a &nl-c; is output to (respectively input from) a file stream,
  its file position is increased by 2 since &nl-c; is encoded as
  &cr-c;/&lf-c; in the file.
</simpara></listitem></varlistentry></variablelist>
</section>
<!-- #endif -->

<section id="open"><title>Function  &open;</title>

<para>&open; cannot handle files of size &ge; 4 GB.</para>

<para>&open; accepts three additional keywords: &eltype;, &extfmt;,
   &buffered;.</para>

<variablelist><title>The acceptable values for the
   &file-pipe-socket; functions</title>
 <varlistentry id="eltype"><term>&eltype;</term>
  <listitem><simpara>types equivalent to &character-class; or
   &unsigned-byte-n;, &signed-byte-n;; if the
   stream is to be unbuffered, &n-r; must be a multiple of 8.
   </simpara></listitem></varlistentry>
 <varlistentry id="extfmt"><term>&extfmt;</term>
  <listitem><simpara>&encoding;s, (constant) &symbol-class;s in the
   &charset-pac; package, &string-class;s (denoting &iconv;-based
   encodings), the symbol &default-k;, and the &line-term; keywords
   &unix-k;, &mac-k;, &dos-k;.  The default encoding is &def-file-enc;.
  </simpara></listitem></varlistentry>
 <varlistentry id="buffered"><term>&buffered;</term>
  <listitem><para>&nil;, &t;, or &default-k;.
  <itemizedlist>
   <listitem><simpara>for functions that create &socket-stream;s and
    <link linkend="pipe">pipes</link>, &default-k; is
    equivalent to &nil;;</simpara></listitem>
   <listitem><simpara>for functions that <link linkend="open">open</link>
    files, &default-k; means that buffered file streams will be returned
    for regular files and (on Unix) block-devices, and unbuffered file
    streams for special files.</simpara></listitem>
  </itemizedlist>
</para></listitem></varlistentry>
</variablelist>

</section>

<section id="close"><title>Function &close;</title>

<para>&close; ignores its &abort-k; argument.</para>

</section>

<section id="broadcast-stream"><title>Class &broadcast-stream-class;</title>

<para>&input-stream-p; and &interactive-stream-p; return false for
 <ulink url="&clhs;/Body/glo_b.html#broadcast_stream">broadcast
 streams</ulink>.</para>

</section>
</section>
</chapter>


<chapter id="printer"><title>Printer
   <ulink url="&clhs;/Body/chap-22.html">[CLHS-22]</ulink></title>

<section id="multi-rep"><title>Multiple Possible Textual Representations
   <ulink url="&clhs;/Body/sec_22-1-1-1.html">[CLHS-22.1.1.1]</ulink></title>

<formalpara id="pr-closure"><title>&pr-closure;</title>
<para>An additional variable &pr-closure; controls whether compiled and
 interpreted functions (closures) are output in detailed form.
 If &pr-closure; is non-&nil;, compiled closures are output in
 <keysym>#Y</keysym> syntax which the reader understands.
 &pr-closure; is initially set to &nil;.</para></formalpara>

<formalpara id="pr-rpars"><title>&pr-rpars;</title>
<para>An additional variable &pr-rpars; controls
 the output of the right (closing) parentheses.
 If &pr-rpars; is non-&nil;, closing parentheses which do not fit onto
 the same line as the the corresponding opening parenthesis are output
 just below their corresponding opening parenthesis, in the same column.
 &pr-rpars; is initially set to &nil;.</para></formalpara>

<formalpara id="pr-indent"><title>&pr-indent;</title>
<para>An additional variable &pr-indent; controls the indentation of
 lists that span more than one line.
 It specifies by how many characters items within the list will be
 indented relative to the beginning of the list.
 &pr-indent; is initially set to <literal>1</literal>.</para></formalpara>

<formalpara id="ppr-first-newline"><title>&ppr-first-newline;</title>
<para>An additional variable &ppr-first-newline; controls
 pretty-printing of multi-line objects.
 When &ppr-first-newline; is non-&nil;,
 and the current line already has some characters on it,
 and the next object will be printed on several lines,
 and it does not start with a &nl-c;,
 then a &nl-c; is printed before the object.
 &ppr-first-newline; has no effect if &print-pretty-var; is &nil;.
 &ppr-first-newline; is initially set to &t;.</para></formalpara>

</section>

<section id="print-vector"><title>Printing Other Vectors
   <ulink url="&clhs;/Body/sec_22-1-3-7.html">[CLHS-22.1.3.7]</ulink></title>

<para>When &print-readably-var; is true, other vectors are written as
 follows: if the &array-element-type; is &t-class;, the syntax <literal
 role="sexp">#(<replaceable>x<subscript>0</subscript></replaceable>
 ... <replaceable>x<subscript>n-1</subscript></replaceable>)</literal>
 is used.  Otherwise, the syntax <literal role="sexp">#A(&eltype-r;
 &dimensions-r; &cont-r;)</literal> is used.</para>

</section>

<section id="print-array"><title>Printing Other Arrays
   <ulink url="&clhs;/Body/sec_22-1-3-8.html">[CLHS-22.1.3.8]</ulink></title>

<para>When &print-readably-var; is true, other arrays are written as
 follows: if the &array-element-type; is &t-class;, the syntax <literal
 role="sexp">#<replaceable>rank</replaceable>A &cont-r;</literal> is
 used.  Otherwise, the syntax <literal role="sexp">#A(&eltype-r;
 &dimensions-r; &cont-r;)</literal> is used.</para>

</section>

<section id="clpp"><title>The Lisp Pretty Printer
   <ulink url="&clhs;/Body/sec_22-2.html">[CLHS-22.2]</ulink></title>

<para>The Lisp Pretty Printer implementation is
 <emphasis>not</emphasis> perfect yet.
 &pprint-logical-block; does not respect &print-lines-var;.</para>

<section id="pp-dispatch"><title>Pretty Print Dispatch Table
   <ulink url="&clhs;/Body/sec_22-2-1-4.html">[CLHS-22.2.1.4]</ulink></title>

<para>A <ulink url="&clhs;/Body/glo_p.html#pprint_dispatch_table">pprint
 dispatch table</ulink> is a &cons; of a symbol
 &print-pprint-dispatch-var; an &alist; which maps types into priorities
 and print functions.
 Their use is strongly discouraged because of the performance issues:
 when &print-pprint-dispatch-var; is non-trivial and &print-pretty-var;
 is non-&nil;, printing of every object requires a lookup in the table,
 which entails many calls to &typep; (which cannot be made fast
 enough).</para>

</section>

</section>

<section id="print-dict"><title>The Printer Dictionary
   <ulink url="&clhs;/Body/sec_the_printer_dictionary.html">[CLHS-22.4]</ulink></title>

<formalpara><title>&write; &amp; &write-to-string;</title>
<para>The functions &write; and &write-to-string; have an additional
 keyword argument <constant>:closure</constant> which is used to bind
 &pr-closure;.</para></formalpara>

<section id="format"><title>Function &format;</title>

<para>The &format; instruction &format-w; is similar to &format-a; and
 &format-s;, but avoids binding of &print-escape-var;.
 <literal role="sexp">(&format; &stream-r; "~W" &object-r;)</literal> is
 equivalent to <literal role="sexp">(&write; &object-r; &stream-k;
 &stream-r;)</literal>.</para>

<para>The &format; instruction <emphasis
 role="strong"><literal>~!</literal></emphasis> is similar to
 &format-slash;, but avoids putting a function name into a string.
 Thus, even if the function is not interned in the &clu-pac; package,
 you might not need to specify the package.</para>

<para><literal role="sexp">(&format; &stream-r; "~args!" &func-r;
 &object-r;)</literal> is equivalent to <literal role="sexp">(&funcall;
 &func-r; &stream-r; &object-r;
 <replaceable>colon-modifier-p</replaceable>
 <replaceable>atsign-modifier-p</replaceable>
 <replaceable>args</replaceable>)</literal>.</para>

<para>&format; &format-r; and &format; &format-rs; can output only
 integers in the range <varname>|n| &lt;
 <replaceable>10<superscript>66</superscript></replaceable></varname>.
 The output is in English, according to the American conventions, and
 these conventions are identical to the British conventions only in the
 range <varname>|n| &lt;
 <replaceable>10<superscript>9</superscript></replaceable></varname>.</para>

<para>&format; &format-c; does not output the character itself, only the
 instruction how to type the character.</para>

<para>For &format; &format-e; and &format; &format-g;, the value of
 &read-default-float-format-var; does not matter if &print-readably-var;
 is true.</para>

<para>&format; &format-t; can determine the current column of any
 built-in stream.</para>

</section>

<section id="pathprint"><title>pathnames</title>

<para>Pathnames are printed as follows: If &print-escape-var; is &nil;,
 only the namestring is printed; otherwise it is printed with
 <filename>#P""</filename> syntax, as per &ansi-cl; Issue <ulink
 url="&clhs;/Issues/iss276.html">PRINT-READABLY-BEHAVIOR:CLARIFY</ulink>.
 But, if &print-readably-var; is true, we are in trouble as
 <filename>#P""</filename> is ambiguous (which is verboten when
 &print-readably-var; is true), while being mandated by the &ansi-cl;.
 Therefore, in this case, &clisp;'s behavior is determined by the value
 of &pathprint;: when it is &nil;, we print pathnames like this:
<computeroutput>#-CLISP #P"" #+CLISP #S(PATHNAME ...)</computeroutput>.
 Otherwise, when the variable &pathprint; is non-&nil;, the
 <filename>#P""</filename> notation is used as per <ulink
 url="&clhs;/Body/sec_1-5-1-4.html">1.5.1.4.1 Resolution of Apparent
 Conflicts in Exceptional Situations</ulink>.</para>

</section>

<section id="print-misc"><title>Miscellaneous Issues</title>

<para>&print-case-var; controls the output not only of symbols, but also
 of characters and some <computeroutput>#&lt;...&gt;</computeroutput>
 objects.</para>

<para>In the absence of <emphasis
 role="strong"><function>sys::write-float-decimal</function></emphasis>,
 floating point numbers are output in radix 2.  This function is defined
 in <filename>floatpri.lisp</filename> and is not available if you run
 &clisp; without a &mem-image; (which you should never do anyway!)</para>

<para>If &print-readably-var; is true,
 &read-default-float-format-var; has no influence on the way
 floating point numbers are printed.</para>

<variablelist>
<!-- #ifndef AMIGAOS -->
<varlistentry><term>Platform dependent: &unix;, &dos;, &os2;, &win32;,
   &acorn; platforms only.</term>
<listitem><simpara>&print-pretty-var; is initially &nil; but set to &t;
 in &config-file;.  This makes screen output prettier.
 </simpara></listitem></varlistentry>
<!-- #else -->
<varlistentry><term>Platform dependent: &amiga; platforms only.</term>
<listitem><simpara>&print-pretty-var; is initially &nil; but set to &t;
 in &config-file;.  This makes unbuffered screen output both much faster
 and prettier.
 </simpara></listitem></varlistentry>
<!-- #endif -->
</variablelist>

<para>&print-array-var; is initially set to &t;.</para>

</section>
</section>
</chapter>

<chapter id="reader"><title>Reader
   <ulink url="&clhs;/Body/chap-23.html">[CLHS-23]</ulink></title>

<para>This is the list of objects whose external representation cannot
  be meaningfully read in:
<table id="unreadable-objects-table" frame="all">
  <title>unreadable objects</title>
 <tgroup cols="2" colsep="1" rowsep="1" align="center">
  <thead><row><entry>format</entry><entry>meaning</entry></row></thead><tbody>
 <row><entry><literal>#&lt;&type-r; ...&gt;</literal></entry>
    <entry>all structures lacking a keyword constructor</entry></row>
 <row><entry><literal>#&lt;ARRAY &type-r; &dimensions-r;&gt;</literal></entry>
    <entry>all arrays except strings, if &print-array-var; is
       &nil;</entry></row>
 <row><entry><literal>#&lt;SYSTEM-FUNCTION
       &name-r;&gt;</literal></entry>
    <entry>built-in function written in &c-lang;</entry></row>
 <row><entry><literal>#&lt;ADD-ON-SYSTEM-FUNCTION
       &name-r;&gt;</literal></entry>
    <entry>other function written in &c-lang;</entry></row>
 <row><entry><literal>#&lt;SPECIAL-OPERATOR
       &name-r;&gt;</literal></entry>
    <entry>special operator handler</entry></row>
 <row><entry><literal>#&lt;COMPILED-CLOSURE
       &name-r;&gt;</literal></entry>
    <entry>compiled function, if &pr-closure; is &nil;</entry></row>
 <row><entry><literal>#&lt;CLOSURE &name-r;
       ...&gt;</literal></entry>
    <entry>interpreted function</entry></row>
 <row><entry><literal>#&lt;FRAME-POINTER #x...&gt;</literal></entry>
    <entry>pointer to a stack frame</entry></row>
 <row><entry><literal>#&lt;DISABLED POINTER&gt;</literal></entry>
    <entry>frame pointer which has become invalid on exit from the
       corresponding &block; or &tagbody;</entry></row>
 <row><entry><literal>#&lt;...-STREAM ...&gt;</literal></entry>
    <entry>stream</entry></row>
 <row><entry><literal>#&lt;PACKAGE
       &name-r;&gt;</literal></entry>
    <entry>package</entry></row>
 <row><entry><literal>#&lt;HASH-TABLE #x...&gt;</literal></entry>
    <entry>hash table, if &print-array-var; is &nil;</entry></row>
 <row><entry><literal>#&lt;READTABLE #x...&gt;</literal></entry>
    <entry>readtable</entry></row>
 <row><entry><literal>#&lt;SYMBOL-MACRO &form-r;&gt;</literal></entry>
    <entry>&symbol-macro; handler</entry></row>
<!-- #ifdef FOREIGN -->
 <row><entry><literal>#&lt;FOREIGN-POINTER #x...&gt;</literal></entry>
    <entry>foreign pointer
      <emphasis>(Platform dependent: &unix;, &win32;, &amiga;
         platforms only.)</emphasis>
     </entry></row>
<!-- #endif -->
<!-- #ifdef DYNAMIC_FFI -->
 <row><entry><literal>#&lt;FOREIGN-ADDRESS #x...&gt;</literal></entry>
    <entry>foreign address
     <emphasis>(Platform dependent: &unix;, &win32; platforms only.)</emphasis>
    </entry></row>
 <row><entry><literal>#&lt;FOREIGN-VARIABLE
       &name-r; #x...&gt;</literal></entry>
    <entry>foreign variable
     <emphasis>(Platform dependent: &unix;, &win32; platforms only.)</emphasis>
    </entry></row>
 <row><entry><literal>#&lt;FOREIGN-FUNCTION
       &name-r; #x...&gt;</literal></entry>
    <entry>foreign function
     <emphasis>(Platform dependent: &unix;, &win32; platforms only.)</emphasis>
    </entry></row>
<!-- #endif -->
 <row><entry><literal>#&lt;UNBOUND&gt;</literal></entry>
    <entry>"value" of a symbol without value, "value" of an unsupplied
      optional or keyword argument</entry></row>
 <row><entry><literal>#&lt;SPECIAL REFERENCE&gt;</literal></entry>
    <entry>environment marker for variables declared &special-dec;
      </entry></row>
 <row><entry><literal>#&lt;DOT&gt;</literal></entry>
    <entry>internal &read; result for "."</entry></row>
 <row><entry><literal>#&lt;END OF FILE&gt;</literal></entry>
    <entry>internal &read; result, when the end of file is reached
      </entry></row>
 <row><entry><literal>#&lt;READ-LABEL ...&gt;</literal></entry>
    <entry>intermediate &read; result for <literal>#n#</literal>
      </entry></row>
 <row><entry><literal>#&lt;ADDRESS #x...&gt;</literal></entry>
    <entry>machine address, should not occur</entry></row>
 <row><entry><literal>#&lt;SYSTEM-POINTER #x...&gt;</literal></entry>
    <entry>should not occur</entry></row>
</tbody></tgroup></table></para>

<section id="chario"><title>characters</title>

<para><keysym>#\Code</keysym> allows input of characters of arbitrary code:
 e.g., <keysym>#\Code231</keysym> reads as the character
 <literal role="sexp">(&code-char; 231.)</literal>.</para>

</section>

<section id="read-dispatch-ext"><title>Additional read dispatch macros</title>

<itemizedlist>
<listitem><simpara><keysym>#Y</keysym> is used to read compiled
  functions and to set the current input stream's &encoding;.
  </simpara></listitem>
<listitem><simpara><filename>#""</filename> is used to read pathnames:
  <filename>#"test.lisp"</filename> is the value of <literal
  role="sexp">(&pathname; "test.lisp")</literal></simpara>
<variablelist>
<!-- #if defined(MSDOS) -->
<varlistentry><term>Platform dependent: &dos;, &os2;, &win32;
   platforms only.</term>
<listitem><simpara>As in all strings, backslashes must be written twice
  here: <filename>#"A:\\programs\\test.lisp"</filename>
  </simpara></listitem></varlistentry>
<!-- #endif -->

<!-- #ifdef RISCOS -->
<varlistentry><term>Platform dependent: &acorn; platforms only.</term>
<listitem><simpara> As in all strings, backslashes must be written twice
  here: <filename>#"\\.test.lisp"</filename>
  </simpara></listitem></varlistentry>
<!-- #endif -->
</variablelist></listitem>
</itemizedlist>

</section>

<section id="rt-case"><title>Function &readtable-case;</title>

<para>When the value of <literal role="sexp">(&readtable-case;
 <replaceable>readtable</replaceable>)</literal> is
 <constant>:invert</constant>, it applies to the package name and the
 symbol name of a symbol separately (not to the entire token at once).
 An alternative to the use of &readtable-case; is the use of the
 &case-sensitive-k; option to &make-package;,
 &in-package; and &defpackage;.</para>

</section>

<section id="listen"><title>Functions &listen;, &read-char-no-hang;</title>

<variablelist>
 <varlistentry id="rcwhp"><term><literal
  role="sexp">(&rcwhp; &stream-r;)</literal></term>
  <listitem><simpara>&rcwhp; queries the stream's input status.
  It returns &nil; if &read-char; and &peek-char; with a
  <replaceable>peek-type</replaceable> of &nil; will return immediately.
  Otherwise it returns &t;.  (In the latter case the standard
  &listen; function would return &nil;.)</simpara>
  <simpara>Note the difference with <literal role="sexp">(&not;
  (&listen; &stream-r;))</literal>: When the &eos; is reached, &listen;
  returns &nil;, whereas &rcwhp; returns &nil;.</simpara>
  <simpara>Note also that &rcwhp; is not a good mean to test for &eos;:
  If &rcwhp; returns &t;, this does not mean that the &stream-r; will
  deliver more characters.  It only means that it is not known at this
  moment whether the &stream-r; is already at &eos;, or will deliver
  more characters.</simpara></listitem></varlistentry>
</variablelist>

</section>

<section id="read-byte"><title>Function &read-byte;</title>

<variablelist>
 <varlistentry id="rbla"><term><literal
    role="sexp">(&rbla; &stream-r;)</literal></term>
  <listitem><simpara>To be called only if &stream-r;'s
   &stream-element-type; is &unsigned-byte-8; or &signed-byte-8;.
   Returns &t; if &read-byte; would return immediately with an
   &integer-class; result.
   Returns &eof-k; if the &eos; is already known to be reached.
   If &read-byte;'s value is not available immediately, returns &nil;
   instead of waiting.</simpara></listitem></varlistentry>
 <varlistentry><term><literal
  role="sexp">(<function>EXT:READ-BYTE-WILL-HANG-P</function>
              &stream-r;)</literal></term>
  <listitem><simpara>To be called only if &stream-r;'s
   &stream-element-type; is &unsigned-byte-8; or &signed-byte-8;.
   Returns &nil; if &read-byte; will return immediately.
   Otherwise it returns true.</simpara></listitem></varlistentry>
 <varlistentry><term><literal
    role="sexp">(<function>EXT:READ-BYTE-NO-HANG</function>
                 &stream-r; &optional-amp; &eof-ep; &eof-v;)</literal></term>
  <listitem><simpara>To be called only if &stream-r;'s
   &stream-element-type; is &unsigned-byte-8; or &signed-byte-8;.
   Returns an &integer-class; or does &eos; handling, like &read-byte;,
   if that would return immediately.
   If &read-byte;'s value is not available immediately, returns &nil;
   instead of waiting.</simpara></listitem></varlistentry>
</variablelist>

</section>
</chapter>


<chapter id="system"><title>System Construction
   <ulink url="&clhs;/Body/chap-24.html">[CLHS-24]</ulink></title>

<section id="system-dict"><title>The System Construction Dictionary
   <ulink url="&clhs;/Body/sec_the_syste_n_dictionary.html">[CLHS-24.2]</ulink></title>

<para>The compiler can be called not only by the functions &compile;,
 &compile-file; and &disassemble;, but also by the declaration <link
 linkend="compile-decl"><literal
 role="sexp">(compile)</literal></link>.</para>

<section id="compilefile"><title>Function &compile-file;</title>

<para><literal role="sexp">(&compile-file;
          <replaceable>input-file</replaceable> &key-amp; :output-file
          :listing &warnings-k; &verbose-k; &print-k;)</literal>
compiles a file to platform-independent bytecode.</para>

<variablelist id="compile-file-arguments">
<varlistentry><term><replaceable>input-file</replaceable></term>
 <listitem><simpara>should be a pathname/string/symbol.
 </simpara></listitem></varlistentry>
<varlistentry><term><constant>:output-file</constant></term>
 <listitem><simpara>should be &nil; or &t; or a pathname/string/symbol
 or an output-stream.  The default is &t;.
 </simpara></listitem></varlistentry>
<varlistentry><term><constant>:listing</constant></term>
 <listitem><simpara>should be &nil; or &t; or a pathname/string/symbol
 or an output-stream.  The default is &nil;.
 </simpara></listitem></varlistentry>
<varlistentry><term>&warnings-k;</term>
 <listitem><simpara>specifies whether warnings should also appear on the
 screen.</simpara></listitem></varlistentry>
<varlistentry><term>&verbose-k;</term>
 <listitem><simpara>specifies whether error messages should also appear
 on the screen.</simpara></listitem></varlistentry>
<varlistentry><term>&print-k;</term>
 <listitem><simpara>specifies whether an indication which forms are
 being compiled should appear on the screen.
 </simpara></listitem></varlistentry>
</variablelist>

<para>The variables <emphasis
 role="strong"><varname>custom:*compile-warnings*</varname></emphasis>,
 &compile-verbose-var;, &compile-print-var; provide defaults for the
 &warnings-k;, &verbose-k;, &print-k; keyword arguments, respectively.
 For each input file (default file type: &lisp-file;)
 the following files are generated:</para>

<table id="compile-file-new-files-table" frame="all"><title/>
 <tgroup cols="4" colsep="1" rowsep="1" align="center">
  <thead><row><entry>File</entry><entry>When</entry>
  <entry>Default file type</entry><entry>Contents</entry></row></thead><tbody>
 <row><entry>output file</entry>
   <entry>only if <constant>:output-file</constant> is not &nil;</entry>
   <entry>&fasl-file;</entry>
   <entry>can be loaded using the &load; function</entry></row>
 <row><entry>auxiliary output file</entry>
   <entry>only if <constant>:output-file</constant> is not &nil;</entry>
   <entry>&lib-file;</entry>
   <entry>used by &compile-file; when compiling a &require; form referring
    to the input file</entry></row>
 <row><entry>listing file</entry>
   <entry>only if <constant>:listing</constant> is not &nil;</entry>
   <entry><filename>#p".lis"</filename></entry>
   <entry>disassembly of the output file</entry></row>
 <row><entry>&c-lang; output file</entry>
   <entry>only if <constant>:output-file</constant> is not &nil;</entry>
   <entry><filename>#p".c"</filename></entry>
   <entry>foreign function interface; this file is deleted if it is
    empty</entry></row>
</tbody></tgroup></table>

</section>

<section id="compile-file-path">
   <title>Function &compile-file-pathname;</title>
<para>The default for the <constant>:output-file</constant> argument is
 &t;, which means &fasl-file;.</para></section>

<section id="require"><title>Function &require;</title>

<para>The function &require; receives as the optional argument either a
 pathname or a list of pathnames: files to be loaded if the required
 module is not already loaded.</para>

<para>At compile time, <literal role="sexp">(&require; "foo")</literal>
forms are treated specially:  &load-paths; is searched
for <filename>"foo.lisp"</filename> <emphasis>and</emphasis>
<filename>"foo.lib"</filename>.
If the latest such file is a &lisp-file;, it is compiled;
otherwise the &lib-file; is loaded.
The &lib-file; is a <quote>header</quote> file which contains the
constant, variable, inline and macro definitions necessary for
compilation of the files that &require; this file, but not the function
definitions and calls that are not necessary for that.
Thus it is <emphasis>not</emphasis> necessary to either enclose
&require; forms in &eval-when; or to load the required files in the
makefiles: if you have two files, <filename>"foo.lisp"</filename>
and <filename>"bar.lisp"</filename>, and the latter requires the
former, you can write in your &make-file;:
<programlisting>
all: foo.fas bar.fas

foo.fas: foo.lisp
	clisp -c foo

bar.fas: bar.lisp foo.fas
        clisp -c bar
</programlisting>
instead of the more cumbersome (and slower, since &lib-file;s are
usually smaller and load faster that &fasl-file;s):
<programlisting>
bar.fas: bar.lisp foo.fas
        clisp -i foo -c bar
</programlisting>
Thus, you do not need to &load; <filename>"foo"</filename>
in order to &compile-file; <filename>"bar.lisp"</filename>.
If memory is tight, and if <filename>"foo.lisp"</filename> contains
only a few inline functions, macros, constants or variables,
this is a space and time saver.
If <filename>"foo.lisp"</filename> does a lot of initializations or side
effects when being loaded, this is important as well.
</para></section>

<section id="loadfile"><title>Function &load;</title>

<para>&load; has two additional keywords &echo-k; and &compiling-k;.</para>

<para><literal role="sexp">(&load; &filename-r; &key-amp; &verbose-k;
 &print-k; &echo-k; &if-does-not-exist; &compiling-k;)</literal></para>

<variablelist>
 <varlistentry><term>&verbose-k; &t;</term>
  <listitem><simpara>causes &load; to emit a short message that a file is
   being loaded.  The default is &load-verbose-var;, which is initially &t;.
  </simpara></listitem></varlistentry>
 <varlistentry><term>&print-k; &t;</term>
  <listitem><simpara>causes &load; to print the value of each form.  The
  default is &load-print-var;, which is initially &nil;.
  </simpara></listitem></varlistentry>
 <varlistentry><term>&echo-k; &t;</term>
  <listitem><simpara>causes the input from the file to be echoed to
  &standard-output-var; (normally to the screen).  Should
  there be an error in the file, you can see at one glance where it is.
  The default is <emphasis
  role="strong"><varname>custom:*load-echo*</varname></emphasis>, which is
  initially &nil;.</simpara></listitem></varlistentry>
 <varlistentry><term>&compiling-k; &t;</term>
  <listitem><simpara>causes each form read to be compiled on the fly.
  The compiled code is executed at once and - in contrast to <link
  linkend="compilefile"><function>compile-file</function></link> - not
  written to a file.  The default is <emphasis
  role="strong"><varname>custom:*load-compiling*</varname></emphasis>,
  which is initially &nil;.
</simpara></listitem></varlistentry></variablelist>

<formalpara id="load-paths"><title>&load-paths;</title>
<para>The variable &load-paths; contains a list of directories where the
 files are looked for - in addition to the specified or current
 directory - by &load;, &require;, &compile-file; and
 &load-logical-pathname-translations;.</para></formalpara>

</section>

<section id="features"><title>Variable &features-var;</title>

<para>The variable &features-var; initially contains the symbols
<table id="features-table" frame="all"><title/>
 <tgroup cols="2" colsep="1" rowsep="1" align="center">
 <thead><row><entry>keyword</entry><entry>meaning</entry></row></thead><tbody>
<row><entry><constant>:CLISP</constant></entry>
   <entry>the name of this implementation</entry></row>
<row><entry><constant>:ANSI-CL</constant></entry><entry/></row>
<row><entry><constant>:COMMON-LISP</constant></entry><entry/></row>
<row><entry><constant>:INTERPRETER</constant></entry><entry/></row>
<row><entry><constant>:COMPILER</constant></entry><entry/></row>
<!-- #ifdef SOCKET_STREAMS -->
<row><entry><constant>:SOCKETS</constant></entry>
   <entry>see &socket-stream;s</entry></row>
<!-- #endif -->
<!-- #ifdef GENERIC_STREAMS -->
<row><entry><constant>:GENERIC-STREAMS</constant></entry>
   <entry>see <link linkend="clos-stream">Defining new kinds of
    Streams</link></entry></row>
<!-- #endif -->
<!-- #ifdef EXPORT_SYSCALLS -->
<row><entry><constant>:SYSCALLS</constant></entry>
   <entry>see <link linkend="syscalls">System Calls</link></entry></row>
<!-- #endif -->
<!-- #ifdef DIR_KEY -->
<row><entry><constant>:DIR-KEY</constant></entry>
   <entry>see <link linkend="dir-key">Directory Access</link></entry></row>
<!-- #endif -->
<!-- #ifdef LOGICAL_PATHNAMES -->
<row><entry><constant>:LOGICAL-PATHNAMES</constant></entry>
  <entry/></row>
<!-- #endif -->
<!-- #ifdef DYNAMIC_FFI -->
<row><entry><constant>:FFI</constant></entry>
   <entry>if a foreign function interface (see &ffi-pac;) is supported
     <emphasis>(Platform dependent: many &unix;, &win32; platforms
     only)</emphasis>
    </entry></row>
<!-- #endif -->
<!-- #ifdef GNU_GETTEXT -->
<row><entry><constant>:GETTEXT</constant></entry>
   <entry>if internationalization (see &i18n-pac;) using the &ggettext;
     package is supported
     <emphasis>(Platform dependent: most &unix; platforms
     only)</emphasis></entry></row>
<!-- #endif -->
<!-- #ifdef UNICODE -->
<row><entry><constant>:UNICODE</constant></entry>
   <entry>if Unicode (ISO 10646) characters are supported (see
     &charset-pac;)</entry></row>
<!-- #endif -->
<row><entry><constant>:LOOP</constant></entry><entry/></row>
<row><entry><constant>:CLOS</constant></entry><entry/></row>
<row><entry><constant>:AMIGA</constant></entry>
   <entry>if &hw; = Amiga and &os; = Exec/AmigaDOS</entry></row>
<row><entry><constant>:DOS</constant></entry>
   <entry>if &hw; = PC (clone) and &os; = DOS</entry></row>
<row><entry><constant>:OS/2</constant></entry>
   <entry>if &hw; = PC (clone) and &os; = OS/2</entry></row>
<row><entry><constant>:WIN32</constant></entry>
   <entry>if &hw; = PC (clone) and
             &os; = Win32 (Windows 95/98/NT/Me/2000)</entry></row>
<row><entry><constant>:PC386</constant></entry>
   <entry>if &hw; = PC (clone) with a 386/486/586/686 CPU</entry></row>
<row><entry>&unix-k;</entry>
   <entry>if &os; = Unix (in this case the &hw; is irrelevant!)</entry></row>
</tbody></tgroup></table></para>

</section>
</section>
</chapter>


<chapter id="environment"><title>Environment
   <ulink url="&clhs;/Body/chap-25.html">[CLHS-25]</ulink></title>

<section id="debugger"><title>Debugging Utilities
   <ulink url="&clhs;/Body/sec_25-1-2.html">[CLHS-25.1.2]</ulink></title>

<para>The debugger may be invoked through the functions
 &invoke-debugger;, &break;, &signal;, &error;, &cerror;, &warn;. The
 stepper is invoked through the macro &step; .  Debugger and stepper
 execute subordinate &repl; (called "break loops") which are similar to
 the main &repl; except for the prompt and the set of available
 commands.  Commands must be typed literally, without surrounding quotes
 or white space.  Each command has a keyword abbreviation, indicated in
 the second column.</para>

<table id="debugger-main-deb-step" frame="all">
 <title>Commands common to the main loop, the debugger and the stepper</title>
 <tgroup cols="3" colsep="1" rowsep="1" align="center">
  &cmd-abbrev-oper-header;<tbody>
 <row><entry><command>Help</command></entry>
   <entry><command>:h</command></entry>
   <entry>prints a list of available commands</entry></row>
</tbody></tgroup></table>

<table id="debugger-deb-step" frame="all">
 <title>Commands common to the debugger and the stepper</title>
 <tgroup cols="3" colsep="1" rowsep="1" align="center">
  &cmd-abbrev-oper-header;<tbody>
 <row><entry><command>Abort</command></entry>
   <entry><command>:a</command></entry>
   <entry>abort to the next most recent &repl;</entry></row>
 <row><entry><command>Unwind</command></entry>
   <entry><command>:uw</command></entry>
   <entry>abort to the next most recent &repl;</entry></row>
</tbody></tgroup></table>

<para>The stack is organized into frames and other stack elements.
 Usually every invocation of an interpreted function and every
 evaluation of an interpreted form corresponds to one stack frame.
 Special forms such as &let;, &let-star;, &unwind-protect; and &catch;
 produce special kinds of stack frames.</para>

<para>In a break loop there is a current stack frame, which is initially
 the most recent stack frame but can be moved using the debugger commands
 <command>Up</command> and <command>Down</command>.</para>

<para>Evaluation of forms in a break loop occurs in the lexical environment
 of the current stack frame but in the dynamic environment of the
 debugger's caller.  This means that to inspect or modify a lexical
 variable all you have to do is to move to the current stack frame just
 below the frame that corresponds to the form or the function call that
 binds that variable.</para>

<para>There is a current "stack mode" which defines in how much
 detail the stack is shown by the stack related debugger commands.</para>

<table id="debugger-deb-step-1" frame="all">
 <title>Commands common to the debugger and the stepper</title>
 <tgroup cols="3" colsep="1" rowsep="1" align="center">
  &cmd-abbrev-oper-header;<tbody>
 <row><entry><command>Error</command></entry>
   <entry><command>:e</command></entry>
   <entry>print the last error message.</entry></row>
 <row><entry><command>Mode-1</command></entry>
   <entry><command>:m1</command></entry>
   <entry>sets the current mode to 1: all the stack elements are considered.
    This mode works fine for debugging compiled functions.</entry></row>
 <row><entry><command>Mode-2</command></entry>
   <entry><command>:m2</command></entry>
   <entry>sets the current mode to 2: all the frames are considered.
     </entry></row>
 <row><entry><command>Mode-3</command></entry>
   <entry><command>:m3</command></entry>
   <entry>sets the current mode to 3: only lexical frames (frames that
         correspond to special forms that modify the lexical environment)
         are considered.</entry></row>
 <row><entry><command>Mode-4</command></entry>
   <entry><command>:m4</command></entry>
   <entry>sets the current mode to 4 (the default): only &eval;
         and &apply; frames are considered. Every evaluation
         of a form in the interpreter corresponds to an EVAL frame.
     </entry></row>
 <row><entry><command>Mode-5</command></entry>
   <entry><command>:m5</command></entry>
   <entry>sets the current mode to 5: only &apply; frames are
         considered. Every invocation of an interpreted function
         corresponds to one &apply; frame.</entry></row>
 <row><entry><command>Where</command></entry>
   <entry><command>:w</command></entry>
   <entry>shows the current stack frame.</entry></row>
 <row><entry><command>Up</command></entry>
   <entry><command>:u</command></entry>
   <entry>goes up one frame, i.e., to the caller if in mode-5
    </entry></row>
 <row><entry><command>Down</command></entry>
   <entry><command>:d</command></entry>
   <entry>does down one frame, i.e., to the callee if in mode-5
    </entry></row>
 <row><entry><command>Top</command></entry>
   <entry><command>:t</command></entry>
   <entry>goes to top frame, i.e., to the top-level form if in mode-4
    </entry></row>
 <row><entry><command>Bottom</command></entry>
   <entry><command>:b</command></entry>
   <entry>goes to bottom (most recent) frame, i.e., most probably to the
         form or function that caused the debugger to be entered.
    </entry></row>
 <row><entry><command>Backtrace</command></entry>
   <entry><command>:bt</command></entry>
   <entry>lists the stack in current mode, bottom frame first, top frame
     last.</entry></row>
 <row><entry><command>Backtrace-1</command></entry>
   <entry><command>:bt1</command></entry>
   <entry>lists the stack in mode 1.</entry></row>
 <row><entry><command>Backtrace-2</command></entry>
   <entry><command>:bt2</command></entry>
   <entry>lists the stack in mode 2.</entry></row>
 <row><entry><command>Backtrace-3</command></entry>
   <entry><command>:bt3</command></entry>
   <entry>lists the stack in mode 3.</entry></row>
 <row><entry><command>Backtrace-4</command></entry>
   <entry><command>:bt4</command></entry>
   <entry>lists the stack in mode 4.</entry></row>
 <row><entry><command>Backtrace-5</command></entry>
   <entry><command>:bt5</command></entry>
   <entry>lists the stack in mode 5.</entry></row>
 <row><entry><command>Frame-limit</command></entry>
   <entry><command>:fl</command></entry>
   <entry>set the frame-limit: this many frames will be printed in a
     backtrace at most.</entry></row>
 <row><entry><command>Backtrace-l</command></entry>
   <entry><command>:bl</command></entry>
   <entry>limit of frames to print will be prompted for.</entry></row>
</tbody></tgroup></table>

<para>If the current stack frame is an &eval; or &apply; frame, the
  following commands are available as well:</para>

<table id="debugger-eval-apply" frame="all">
 <title>&eval;/&apply;-specific commands</title>
 <tgroup cols="3" colsep="1" rowsep="1" align="center">
  &cmd-abbrev-oper-header;<tbody>
<row><entry><command>Break+</command></entry>
   <entry><command>:br+</command></entry>
   <entry>sets a breakpoint in the current frame.  When the corresponding
     form or function will be left, the debugger will be entered again, with
     the variable &trace-val; containing a list of its values.</entry></row>
<row><entry><command>Break-</command></entry>
   <entry><command>:br-</command></entry>
   <entry>removes a breakpoint from the current frame.</entry></row>
<row><entry><command>Redo</command></entry>
   <entry><command>:rd</command></entry>
   <entry>re-evaluates the corresponding form or function call. This
     command can be used to restart parts of a computation without
     aborting it entirely.</entry></row>
<row><entry><command>Return</command></entry>
   <entry><command>:rt</command></entry>
   <entry>leaves the current frame.  You will be prompted for the return
     values.</entry></row>
</tbody></tgroup></table>

<table id="debugger-deb" frame="all">
 <title>Commands specific to the debugger</title>
 <tgroup cols="3" colsep="1" rowsep="1" align="center">
  &cmd-abbrev-oper-header;<tbody>
<row><entry><command>Continue</command></entry>
   <entry><command>:c</command></entry>
   <entry>continues evaluation of the program.</entry></row>
</tbody></tgroup></table>

<table id="debugger-step" frame="all">
 <title>Commands specific to the stepper</title>
 <tgroup cols="3" colsep="1" rowsep="1" align="center">
  &cmd-abbrev-oper-header;<tbody>
<row><entry><command>Step</command></entry>
   <entry><command>:s</command></entry>
   <entry>step into a form: evaluate this form in single step mode
   </entry></row>
<row><entry><command>Next</command></entry>
   <entry><command>:n</command></entry>
   <entry>step over a form: evaluate this form at once
   </entry></row>
<row><entry><command>Over</command></entry>
   <entry><command>:o</command></entry>
   <entry>step over this level: evaluate at once up to the next return
   </entry></row>
<row><entry><command>Continue</command></entry>
   <entry><command>:c</command></entry>
   <entry>switch off single step mode, continue evaluation
   </entry></row>
</tbody></tgroup></table>

<para>The stepper is usually used like this: If some form returns a
 strange value or results in an error, call <literal role="sexp">(&step;
 &form-r;)</literal> and navigate using the
 commands <command>Step</command> and <command>Next</command> until you
 reach the form you regard as responsible.  If you are too fast (execute
 <command>Next</command> once and get the error), there is no way back;
 you have to restart the entire stepper session.  If you are too slow
 (stepped into a function or a form which certainly is OK), a couple of
 <command>Next</command> commands or one <command>Over</command> command
 will help.</para>

</section>

<section id="environment-dict"><title>The Environment Dictionary
   <ulink url="&clhs;/Body/sec_the_envir_t_dictionary.html">[CLHS-25.2]</ulink></title>

<!-- #ifdef HAVE_DISASSEMBLER -->

<section id="disassemble"><title>Function &disassemble;</title>

<variablelist>
<varlistentry><term>Platform dependent: &unix; platforms only.</term>
<listitem><simpara>&disassemble; can disassemble to machine code,
 provided that &gnu; gdb is present.  In that case the argument may be a
 <classname>system-function</classname>, a
 <classname>foreign-function</classname>, a special operator indicator,
 a symbol denoting one of these, a number, or a string.
 </simpara></listitem></varlistentry>
</variablelist>
</section>

<!-- #endif -->

<section id="uncompile"><title>Function &uncompile;</title>

<para>The function &uncompile; does the converse of &compile;: <literal
 role="sexp">(&uncompile; &func-r;)</literal> reverts a compiled
 &func-r; (name), that has been entered or loaded in the same session
 and then compiled, back to its interpreted form.</para>

</section>

<section id="documentation"><title>Function &documentation;</title>

<para>No on-line documentation is available for the system functions
 (yet).  &documentation; still has the &cltl1; implementation.</para>

<formalpara id="browser"><title><function>ext:clhs</function></title>
<para>&hyperspec; access is provided via <literal
  role="sexp">(<function>ext:clhs</function> &symbol-r; &key-amp;
  <literal>:browser</literal>)</literal>
  function, which uses your web browser.
  <replaceable>browser</replaceable> should be a valid
  keyword in the <varname>custom:*browsers*</varname> &alist;.
</para></formalpara>

</section>

<section id="trace"><title>Macro &trace;</title>

<para><literal role="sexp">(&trace; &func-r; ...)</literal> makes the
 functions &func-r;, ... traced.  &func-r; should be either a symbol or
 a list <literal role="sexp">(&symbol-r; &key-amp;
 <constant>:suppress-if</constant> <constant>:step-if</constant>
 <constant>:pre</constant> <constant>:post</constant>
 <constant>:pre-break-if</constant> <constant>:post-break-if</constant>
 <constant>:pre-print</constant> <constant>:post-print</constant>
 &print-k;)</literal>, where</para>

<variablelist>
 <varlistentry><term><constant>:suppress-if</constant> &form-r;</term>
  <listitem><simpara>no trace output as long as &form-r; is true
  </simpara></listitem></varlistentry>
 <varlistentry><term><constant>:step-if</constant> &form-r;</term>
  <listitem><simpara>invokes the stepper as soon as &form-r; is true
  </simpara></listitem></varlistentry>
 <varlistentry><term><constant>:pre</constant> &form-r;</term>
  <listitem><simpara>evaluates &form-r; before calling the function
  </simpara></listitem></varlistentry>
 <varlistentry><term><constant>:post</constant> &form-r;</term>
  <listitem><simpara>evaluates &form-r; after return from the function
  </simpara></listitem></varlistentry>
 <varlistentry><term><constant>:pre-break-if</constant> &form-r;</term>
  <listitem><simpara>goes into the break loop before calling the
   function if &form-r; is true</simpara></listitem></varlistentry>
 <varlistentry><term><constant>:post-break-if</constant> &form-r;</term>
  <listitem><simpara>goes into the break loop after return from the
   function if &form-r; is true</simpara></listitem></varlistentry>
 <varlistentry><term><constant>:pre-print</constant> &form-r;</term>
  <listitem><simpara>prints the values of &form-r; before calling the
   function</simpara></listitem></varlistentry>
 <varlistentry><term><constant>:post-print</constant> &form-r;</term>
  <listitem><simpara>prints the values of &form-r; after return from the
   function</simpara></listitem></varlistentry>
 <varlistentry><term>&print-k; &form-r;</term>
  <listitem><simpara>prints the values of &form-r; both before calling
   and after return from the function</simpara></listitem></varlistentry>
</variablelist>

<para>In all these forms you can access the following variables:
<variablelist>
 <varlistentry><term><varname>EXT:*TRACE-FUNCTION*</varname></term>
  <listitem><simpara>the function itself
  </simpara></listitem></varlistentry>
 <varlistentry><term><varname>EXT:*TRACE-ARGS*</varname></term>
  <listitem><simpara>the arguments to the function
  </simpara></listitem></varlistentry>
 <varlistentry><term><varname>EXT:*TRACE-FORM*</varname></term>
  <listitem><simpara>the function/macro call as form
  </simpara></listitem></varlistentry>
 <varlistentry id="trace-val"><term>&trace-val;</term>
  <listitem><simpara>after return from the function: the list of return
  values from the function call</simpara></listitem></varlistentry>
</variablelist>
and you can leave the function call with specified values by using
&return;.</para>

<para>&trace; and &untrace; are also applicable to functions <literal
 role="sexp">(&setf; &symbol-r;)</literal> and to macros, but not to
 locally defined functions and macros.</para>

</section>

<section id="inspect"><title>Function &inspect;</title>

<para>The function &inspect; takes a keyword argument
 <constant>:frontend</constant>, which specifies the way &clisp; will
 interact with the user.</para>

<variablelist><title>Available <constant>:frontend</constant>s for
   &inspect; in &clisp;</title>
 <varlistentry><term><constant>:tty</constant></term>
  <listitem><simpara>The interaction is conducted via the &terminal-io-var;
   stream.  Please use the <userinput>:h</userinput> command to get the
   list of all available commands.</simpara></listitem></varlistentry>
 <varlistentry><term><constant>:http</constant></term>
  <listitem><simpara>A window in your Web browser (specified by the
   &browser; keyword argument) is opened and it is controlled by
   &clisp; via a &socket-stream;, using the HTTP protocol.  You should be
   able to use all the standard browser features.</simpara>
   <simpara>Since &clisp; is not multitasking at this time, you will not
   be able to do anything else during an &inspect; session.  Please click on
   the <userinput>quit</userinput> link to terminate the session.</simpara>
   <simpara>Please be aware though, that once you terminate an &inspect;
   session, all links in all &inspect; windows in your browser will become
   obsolete and using them in a new &inspect; session will result in
   unpredictable behavior.</simpara></listitem></varlistentry>
</variablelist>
</section>

<section id="space"><title>Macro &space;</title>

<para>The macro &space; is like the macro &time;: <literal
 role="sexp">(&space; &form-r;)</literal>
 evaluates the &form-r;, and, as a side effect, outputs information
 about the memory allocations caused by this evaluation.
 It also prints everything printed by <link
 linkend="time"><function>TIME</function></link>.</para>

</section>

<section id="room"><title>Function &room;</title>

<para>The function &room; returns two values: the number of bytes
 currently occupied by Lisp objects, and the number of bytes that can be
 allocated before the next regular &gc;ion occurs.</para>

<para>The function <emphasis
 role="strong"><function>EXT:GC</function></emphasis> starts a
 global &gc;ion and its return value has the same meaning as the
 second value of &room;.</para>

</section>

<section id="time"><title>Macro &time;</title>

<para>The timing data printed by the macro &time; includes: The real
 time (elapsed time), the run time (processor time for this process),
 the number of bytes allocated (use the &space; macro for more
 detailed analysis), and the number of &gc;ions performed, if any.</para>

</section>

<section id="ed"><title>Function &ed;</title>

<para>The function &ed; calls the external editor specified by the
 variable <emphasis
 role="strong"><varname>CUSTOM:*EDITOR*</varname></emphasis> (see
 &config-file;).  If the argument is a function name which was defined
 in the current session (not loaded from a file), the program text to be
 edited is a pretty-printed version (without comments) of the text which
 was used to define the function.</para>

</section>

<section id="clock"><title>Clock Time</title>

<!-- #if !(defined(UNIX) || defined(WIN32)) -->
<variablelist>
<varlistentry><term>Platform dependent: &amiga;, &acorn;, &dos;, &os2;
   platforms only.</term>
 <listitem><simpara>The variable <emphasis
   role="strong"><varname>CUSTOM:*DEFAULT-TIME-ZONE*</varname></emphasis>
   contains the default time zone used by &encode-universal-time; and
   &decode-universal-time;.  It is initially set to -1 (which
   means 1 hour east of Greenwich, i.e., Mid European Time).
   </simpara></listitem></varlistentry>
</variablelist>
<!-- #endif -->

<para>The <ulink url="&clhs;/Body/glo_t.html#time_zone">time
 zone</ulink> in a decoded time must not necessarily be an integer,
 but (as float or rational number) it should be a multiple of
 <literal>1/3600</literal>.</para>

<table id="internal-time-units-table" frame="all">
 <title>Platform dependent</title>
 <tgroup cols="5" colsep="1" rowsep="1" align="center">
 <thead><row><entry>platform</entry><entry>&acorn;, &dos;, &os2;</entry>
        <entry>&amiga;</entry><entry>&unix;</entry>
        <entry>&win32;</entry></row></thead><tbody>
 <row><entry>&internal-time-units-per-second;</entry><entry>100</entry>
  <entry>50</entry><entry>1,000,000</entry><entry>10,000,000</entry></row>
</tbody></tgroup></table>

<para>&get-internal-run-time; returns the amount of run time
 consumed by the current &clisp; process since its startup.</para>

</section>

<section id="machine"><title>Machine</title>
<variablelist>
<!-- #ifdef MACHINE_KNOWN -->
<varlistentry><term>Platform dependent: &unix;, &win32; platforms only.</term>
 <listitem><simpara>The functions &short-site-name;, &long-site-name;
  should be defined in a site-specific &config-file; file.
  </simpara></listitem></varlistentry>
<!-- #else -->
 <varlistentry><term>Platform dependent: &amiga;, &acorn;, &dos;, &os2;
    platforms only.</term>
 <listitem><simpara>The functions &machine-type;, &machine-version;,
  &machine-instance; and &short-site-name;, &long-site-name; should be
  defined by every user in his user-specific &config-file; file.
  </simpara></listitem></varlistentry>
<!-- #endif -->
</variablelist>

</section>

<section id="apropos"><title>Functions &apropos; &amp; &apropos-list;</title>

<para>The search performed by &apropos; and &apropos-list; is
 case-insensitive.</para>

</section>

<section id="dribble"><title>Function &dribble;</title>

<para>If &dribble; is called with an argument, and dribbling is already
 enabled, a warning is printed, and the new dribbling request is
 ignored.</para>

</section>

<section id="version"><title>Function &lisp-implementation-version;</title>

<para>&lisp-implementation-version; returns
 the numeric version (like <literal>3.14</literal>), and
 the release date (like <literal>"1999-07-21"</literal>).
 When running on the same machine on which &clisp; was built, it appends
  the binary build and &mem-image; dump date in universal time
  (like <literal>3141592654</literal>).
 When running on a different machine, it appends the &machine-instance;
  of the machine on which it was built.</para>
</section>

</section>
</chapter>


<chapter id="glossary"><title>Glossary
   <ulink url="&clhs;/Body/chap-26.html">[CLHS-26]</ulink></title>
<para>No notes.</para>
</chapter>

<chapter id="appendix"><title>Appendix
   <ulink url="&clhs;/Body/chap-a.html">[CLHS-a]</ulink></title>
<para>No notes.</para>
</chapter>
