<?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 &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-t; is &signal;ed.</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-t; contain the class &structure-object-t;
 instead of the class &standard-object-t;.</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>All 978 symbols in the &cl-pac; package specified by the
 &ansi-cl; are implemented.</para>

</section>

</chapter>

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

<section id="reader-alg"><title>Reader Algorithm
   <ulink url="&clhs;/Body/sec_2-2.html">[CLHS-2.2]</ulink></title>

<para>The requirement of step 4 that a
 <quote><ulink url="&clhs;/Body/glo_r.html#reader_macro_function">reader
  macro function</ulink> may return zero values or one value</quote>
 <emphasis role="strong">is</emphasis> enforced.
 You can use the function &values; to control the number of values
 returned.</para>

</section>

<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
 <ulink url="&clhs;/Body/glo_p.html#potential_number">potential number</ulink>
 syntax but cannot be interpreted as a &number-t;, is interpreted as
 &symbol-t; 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 id="bq-nested"><programlisting>
   (&eval; ``(,#'(&lambda-m; () ',a) ,#'(&lambda-m; () ',b)))
 = (&eval; `(list #'(&lambda-m; () ',a) #'(&lambda-m; () ',b)))
 = (&eval; (list 'list (list 'function (list 'lambda nil (list 'quote a)))
                     (list 'function (list 'lambda nil (list 'quote b)))))
</programlisting></informalexample></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:
<variablelist id="extra-read-macro-table">
 <title>Additional reader macros</title>
 <varlistentry><term>#,</term>
  <listitem><simpara>load-time evaluation, kept despite the &ansi-cl; issue
    <ulink url="&clhs;/Issues/iss315.html">SHARP-COMMA-CONFUSION:REMOVE</ulink>
 </simpara></listitem></varlistentry>
 <varlistentry><term>#Y</term>
  <listitem><simpara>function objects and file &encoding;s
 </simpara></listitem></varlistentry>
 <varlistentry><term>#&quot;&quot;</term>
  <listitem><simpara>&pathname-t;</simpara></listitem></varlistentry>
</variablelist></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-t;) and interpreted
 functions (of type &function-t;).</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>Macro &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>Function <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_the_evalu_n_dictionary.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 cannot 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>&constant;s may not be bound dynamically or lexically.</para>

<formalpara id="spe-var-p"><title>Function &spe-var-p;</title>
<para>You can use the function <literal role="sexp">(&spe-var-p;
  &symbol-r; &optional-amp; &env-r;)</literal> to check whether the
 symbol is a special variable.  &env-r; of &nil; or omitted means use
 the global environment, &t; means use current lexical environment.
 You can also obtain the current lexical environment using the macro
 &the-env; (interpreted code only).
 This function will always return &t; for global special
 variables and constants.
 Note that this function will not work in compiled code as you expect:
 when called with &nil; &env-r;, it will be called at <emphasis>run
  time</emphasis> and check for globally special variables,
 but when &env-r; is &t;, it will be called at <emphasis>compile
  time</emphasis> and the value will be used as a constant in the
 code.</para></formalpara>

</section>

<section id="constantp"><title>Function &constantp;.</title>

<para>Function &constantp; fully complies with &ansi-cl;.
Additionally, some non-trivial forms are identified as constants, e.g.,
<literal role="sexp">(&constantp; '(&plus; 1 2 3))</literal> returns
&t;.</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>

<warning><para>Note that the situations <constant>EVAL</constant>,
 <constant>LOAD</constant> and <constant>COMPILE</constant> are
 deprecated by the spec, and they are &not-e; equivalent to the new
 standard situations <constant>:EXECUTE</constant>,
 <constant>:LOAD-TOPLEVEL</constant>
 and <constant>:COMPILE-TOPLEVEL</constant> in that they ignore the
 top-level versus non-top-level distinction.</para></warning>

</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-t; type specifier is <literal
 role="type">(&complex-t; <replaceable>type-of-real-part</replaceable>
 <replaceable>type-of-imaginary-part</replaceable>)</literal>.  The type
 specifier <literal role="type">(&complex-t; &type-r;)</literal> is
 equivalent to <literal role="type">(&complex-t; &type-r;
 &type-r;)</literal>.</para>

<para>The &ansi-cl; type specifier <literal role="type">(&real-t;
 <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>Function
  <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-t;</simpara></listitem>
 <listitem><simpara>&symbol-t;, &null-t;, &boolean-t;,
  &keyword-t;</simpara></listitem>
 <listitem><simpara><literal role="type">(&integer-t; 0
  #.&most-positive-fixnum;)</literal>, <literal role="type">(&integer-t;
  #.&most-negative-fixnum; (0))</literal>, <literal role="type">(&integer-t;
  (#.&most-positive-fixnum;))</literal>, <literal role="type">(&integer-t; *
  (#.&most-negative-fixnum;))</literal></simpara></listitem>
 <listitem><simpara>&rational-t;, &short-float-t;, &single-float-t;,
  &double-float-t;, &long-float-t;, &complex-t;</simpara></listitem>
 <listitem><simpara>&character-t;, &base-char-t;</simpara></listitem>
 <listitem><simpara><literal role="type">(&array-t; &eltype-r;
  &dimensions-r;)</literal>, <literal role="type">(&simple-array-t;
  &eltype-r; &dimensions-r;)</literal></simpara></listitem>
 <listitem><simpara><literal role="type">(&vector-t; &t;
  &size-r;)</literal>, <literal role="type">(&simple-vector-t;
  &size-r;)</literal></simpara></listitem>
 <listitem><simpara><literal role="type">(&string-t;
  &size-r;)</literal>, <literal role="type">(&simple-string-t;
  &size-r;)</literal></simpara></listitem>
 <listitem><simpara><literal role="type">(&base-string-t;
  &size-r;)</literal>, <literal role="type">(&simple-base-string-t;
  &size-r;)</literal></simpara></listitem>
 <listitem><simpara><literal role="type">(&bit-vector-t;
  &size-r;)</literal>, <literal role="type">(&simple-bit-vector-t;
  &size-r;)</literal></simpara></listitem>
 <listitem><simpara>&function-t;, &compiled-function-t;</simpara></listitem>
 <listitem><simpara>&stream-t;, &file-stream-t;, &synonym-stream-t;,
  &broadcast-stream-t;, &concatenated-stream-t;, &two-way-stream-t;,
  &echo-stream-t;, &string-stream-t;</simpara></listitem>
 <listitem><simpara>&package-t;, &hash-table-t;, &readtable-t;, &pathname-t;,
  &logical-pathname-t;, &random-state-t;, &byte-t;</simpara></listitem>
 <listitem><simpara><classname>SPECIAL-OPERATOR</classname>,
  <classname>LOAD-TIME-EVAL</classname>, &symbol-macro;, &encoding;,
  &foreign-pointer-t;, &foreign-address-t;,
  &foreign-variable;;, &foreign-function;</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-t; (structure types or &clos;
  classes)</simpara></listitem>
 <listitem><simpara>a class object (&clos; classes without a 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 the
 &ansi-cl; standard exported symbols (the &clisp; extensions, e.g.,
 &class-proto;, are &not-e; &re-export;ed).
 Since <link linkend="make-pack">the default &use-k; argument</link>
 to &make-package; is &cl-pac;, the standard &clos; symbols are normally
 visible in all user-defined packages.
 If you do not want them (for example, if you want to use the
 <ulink url="ftp://cvs2.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>

<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><firstterm>&gen-flet;<indexterm id="gen-flet" significance="preferred">
   <primary id="gen-flet-i"><function>GENERIC-FLET</function>
 </primary></indexterm></firstterm>
 and
 <firstterm>&gen-labels;<indexterm id="gen-labels" significance="preferred">
   <primary id="gen-labels-i"><function>GENERIC-LABELS</function>
 </primary></indexterm></firstterm>
 are implemented as macros, not as special operators (as permitted by
 <ulink url="&clhs;/Body/sec_3-1-2-1-2-2.html">Section 3.1.2.1.2.2</ulink>).
 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>&print-object; is only called on objects of type
 &standard-object-t; and &structure-object-t;.
 It is not called on other objects, like &cons-t;es
 and &number-t;s, due to the performance concerns.</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-t;</simpara></listitem>
 <listitem><simpara>&character-t;</simpara></listitem>
 <listitem><simpara>&number-t;, &complex-t;, &real-t;, &float-t;,
   &rational-t;, &ratio-t;, &integer-t;</simpara></listitem>
 <listitem><simpara>&sequence-t;</simpara></listitem>
 <listitem><simpara>&array-t;, &vector-t;, &bit-vector-t;
   &string-t;</simpara></listitem>
 <listitem><simpara>&list-t;, &cons-t;</simpara></listitem>
 <listitem><simpara>&symbol-t;, &null-t;</simpara></listitem>
 <listitem><simpara>&function-t;, &generic-function-t;,
   &standard-generic-function-t;</simpara></listitem>
 <listitem><simpara>&hash-table-t;</simpara></listitem>
 <listitem><simpara>&package-t;</simpara></listitem>
 <listitem><simpara>&pathname-t;, &logical-pathname-t;
  </simpara></listitem>
 <listitem><simpara>&random-state-t;</simpara></listitem>
 <listitem><simpara>&readtable-t;</simpara></listitem>
 <listitem><simpara>&stream-t;, &broadcast-stream-t;,
   &concatenated-stream-t;, &echo-stream-t;, &string-stream-t;,
   &file-stream-t;, &synonym-stream-t;,
   &two-way-stream-t;</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>

<para>It is &not-e; required that the superclasses of a class are
 defined before the &defclass; form for the class is evaluated.
 Use &amop; generic functions
 <firstterm>&class-fin-p;<indexterm id="class-fin-p" significance="preferred">
   <primary id="class-fin-p-i"><function>CLASS-FINALIZED-P</function>
 </primary></indexterm></firstterm>
 to check whether the class has been finalized and thus its instances
 can be created, and
 <firstterm>&fin-inher;<indexterm id="fin-inher" significance="preferred">
   <primary id="fin-inher-i"><function>FINALIZE-INHERITANCE</function>
 </primary></indexterm></firstterm>
 to force class finalization.</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>Trivial changes, e.g., those that can occur when doubly loading
 the same code, do not require updating the instances.
 These are the changes that do not modify the set of local slots
 accessible in instances, e.g., changes to slot options
 <constant>:INITFORM</constant>, <constant>:DOCUMENTATION</constant>,
 and changes to class options <constant>:DEFAULT-INITARGS</constant>,
 <constant>:DOCUMENTATION</constant>.</para>

<para>The instances are updated when they are first accessed, &not-e; at
 the time when the class is redefined or &make-instances-obsolete; is
 called.  When the class has been redefined several times since the
 instance was last accessed, &update-instance-for-redefined-class; is
 still called just once.</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-t; 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-t; to a &character-t;.
  When &fixnum-char-ansi; is &nil;, &clisp; &coerce;s &fixnum-t;s to
  &character-t;s via &code-char;.
  When &fixnum-char-ansi; is non-&nil;, &fixnum-t;s cannot be
  &coerce;d to &character-t;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 id="fle"><title>Function &function-lambda-expression;</title>
<para>The &name-r; of a &foreign-function; is a <emphasis>string</emphasis>
(the name of the underlying &c-lang; function), not a lisp
<ulink url="&clhs;/Body/glo_f.html#function_name">function name</ulink>.
</para></formalpara>

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

<formalpara><title>Macros &prog1;, &prog2;, &and-m;, &or-m;, &psetq;,
 &when;, &unless;, &cond;, &case;, &multiple-value-list;,
 &multiple-value-bind;, &multiple-value-setq;</title>
<para>These macros are implemented as special operators (as permitted by
 <ulink url="&clhs;/Body/sec_3-1-2-1-2-2.html">Section 3.1.2.1.2.2</ulink>)
 and, as such, are rather efficient.</para></formalpara>

<formalpara><title>Macro &defconstant;</title>
<para>The initial value is &not-e; evaluated at compile time,
 just like with &defvar; and &defparameter;.
 Use &eval-when; if you need the value at compile time.</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="xor"><title>Function <function>EXT:XOR</function></title>
<para>This function checks that exactly one of its arguments is non-&nil;
 and, if this is the case, returns its value and index in the argument
 list as &mul-val;, otherwise returns &nil;.</para></section>

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

<para>&eq; compares &character-t;s and &fixnum-t;s as &eql; does.
 No unnecessary copies are made of &character-t;s and &number-t;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>

<para>Note that <literal role="sexp">(eq x x)</literal> might not be
 &t; for a &foreign-variable; &x-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-t;.</para>

</section>

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

<para>Additional &place;s:
<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>place&sub-1;</replaceable>
                                  <replaceable>place&sub-2;</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-t;.
 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
 <firstterm>&symbol-mex;<indexterm id="symbol-mex" significance="preferred">
   <primary id="symbol-mex-i"><function>SYMBOL-MACRO-EXPAND</function>
 </primary></indexterm></firstterm>
 tests for a &symbol-macro;: If &symbol-r; is defined as a &symbol-macro;,
 <literal role="sexp">(&symbol-mex; &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-m;</title>

<formalpara><title>Constant &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>Function call limits</title>
 <tgroup cols="2" colsep="1" rowsep="1" align="center">
 <tbody>
  <row><entry>&call-arguments-limit;</entry>
   <entry>2<superscript>12</superscript>=4096</entry></row>
  <row><entry>&multiple-values-limit;</entry>
   <entry>2<superscript>7</superscript>=128</entry></row>
  <row><entry>&lambda-parameters-limit;</entry>
   <entry>2<superscript>12</superscript>=4096</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>

<formalpara id="suppress-check-redef">
 <title>Variable &suppress-check-redef;</title>
<para>When <firstterm>&suppress-check-redef;</firstterm> is &nil;,
 &clisp; issues a &warning-t; when a function (macro, variable, class,
 etc) is redefined in a different file than its original definition.
 It is &not-e; a good idea to set this variable to &t;.
</para></formalpara>

</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>

<section id="std-meth-combo"><title>Standard Method Combination
  <ulink url="&clhs;/Body/sec_7-6-6-2.html">[CLHS-7.6.6.2]</ulink></title>

<para>Generic function
 <firstterm>&no-prim;<indexterm id="no-prim" significance="preferred">
   <primary id="no-prim-i"><function>NO-PRIMARY-METHOD</function>
 </primary></indexterm></firstterm>
 (similar to &no-applicable-method;) is called when there is an
 applicable method but no applicable <emphasis>primary</emphasis>
 method.</para>

<para>The default methods for &no-prim;, &no-applicable-method; and
 &no-next-method; &signal; an &error-t; of type
 <firstterm>&meth-call-err;
  <indexterm id="meth-call-err" significance="preferred">
   <primary id="meth-call-err-i"><classname>METHOD-CALL-ERROR</classname>
 </primary></indexterm></firstterm>.
 You can find out more information about the error using functions
 <function>CLOS:METHOD-CALL-ERROR-GENERIC-FUNCTION</function>,
 <function>CLOS:METHOD-CALL-ERROR-ARGUMENT-LIST</function>, and
 (only for &no-next-method;)
 <function>CLOS:METHOD-CALL-ERROR-METHOD</function>.
 Moreover, when the generic function has only one <emphasis>dispatching
 argument</emphasis>, (i.e., such an argument that not all the
 corresponding parameter specializers are &t-t;), an &error-t; of type
 <firstterm>&meth-call-type-err;
  <indexterm id="meth-call-type-err" significance="preferred">
   <primary id="meth-call-type-err-i">
    <classname>METHOD-CALL-TYPE-ERROR</classname>
 </primary></indexterm></firstterm>
  is &signal;ed, additinally making &type-error-datum; and
  &type-error-expected-type; available.</para>

</section>

<section id="obj-dict"><title>The Objects Dictionary
  <ulink url="&clhs;/Body/sec_7-7.html">[CLHS-7.7]</ulink></title>

<section id="class-proto"><title>Generic function &class-proto;.</title>
<para>The &amop; generic function &class-proto; is implemented.
 This allows non-consing access to slots with
 allocation <constant>:CLASS</constant>:
 <programlisting>
  (defclass counter ()
    ((count :allocation :class :initform 0 :reader how-many)))
  (defmethod initialize-instance :after ((obj counter) &amp;rest args)
    (incf (slot-value obj 'count)))
  (defclass counted-object (counter) ((name :initarg :name)))
 </programlisting>
 Now you can find out how many <classname>COUNTED-OBJECT</classname>s
 have been created by using
 <literal role="sexp">(HOW-MANY (&class-proto; 'COUNTER))</literal>:
 <programlisting>
  (make-instance 'counted-object :name 'foo)
    <returnvalue>#&lt;COUNTED-OBJECT #x203028C9&gt;</returnvalue>
  (how-many (clos:class-prototype 'counter))
    <returnvalue>1</returnvalue>
  (make-instance 'counted-object :name 'bar)
    <returnvalue>#&lt;COUNTED-OBJECT #x20306CB1&gt;</returnvalue>
  (how-many (clos:class-prototype 'counter))
    <returnvalue>2</returnvalue>
</programlisting></para></section>

</section>

</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-m; (object stream depth) (declare
 (ignore depth)) ...)</literal>
 This &lambda-expr; names a &function-t; whose task is to output the
 external representation of the &structure-object-t; &object-r; onto the
 &stream-t; &stream-r;. 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 treatment of &print-pretty-var; is up to you.
 </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 the 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 (this is a
 &clisp; extension).</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 id="muffle-cerrors"><title>Macro &muffle-cerrors;</title>
<para>The macro <literal role="sexp">(&muffle-cerrors; {&form-r;}*)</literal>
 executes the &form-r;s.  When a continuable error occurs, no message is
 printed, instead, the &continue; &restart-t; is invoked.</para></formalpara>

<formalpara id="appease-cerrors"><title>Macro &appease-cerrors;</title>
<para>The macro <literal role="sexp">(&appease-cerrors; {&form-r;}*)</literal>
 executes the &form-r;s.  Continuable errors are reported as warnings
 and the &continue; &restart-t; is invoked.</para></formalpara>

<formalpara id="exit-on-error"><title>Macro &exit-on-error;</title>
<para>The macro <literal role="sexp">(&exit-on-error; {&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 message is printed and &clisp; terminates with an error
 status.</para></formalpara>

<formalpara id="with-restarts"><title>Macro &with-restarts;</title>
<para>The macro &with-restarts; 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 with any &condition-t;.
 <literal role="sexp">(&with-restarts; ({<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-t;
 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>Macro &restart-case;</title>
 <para>In <literal role="sexp">(&restart-case; &form-r;
   {<replaceable>restart-clause</replaceable>}*)</literal>,
  the argument list can also be specified after the keyword/value pairs
  instead of before them, i.e., each
  <replaceable>restart-clause</replaceable> can be either
  <literal role="sexp">(<varname>restart-name</varname>
   <replaceable>arglist</replaceable>
   {<replaceable>keyword-value-pair</replaceable>}* {&form-r;}*)</literal>
  or <literal role="sexp">(<replaceable>restart-name</replaceable>
   {<replaceable>keyword-value-pair</replaceable>}*
   <replaceable>arglist</replaceable> {&form-r;}*)</literal>.
</para></formalpara>

<formalpara><title>Function &compute-restarts;</title>
<para>&compute-restarts; and &find-restart; behave as specified in
 &ansi-cl;: If the optional <replaceable>condition</replaceable>
 argument is non-&nil;, only restarts associated with that condition and
 restarts associated with 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 <quote role="package">CL</quote>
    and <quote role="package">LISP</quote></simpara></listitem></varlistentry>
 <varlistentry><term>&clu-pac;</term>
  <listitem><simpara>with the nicknames <quote role="package">CL-USER</quote>
    and <quote role="package">USER</quote></simpara></listitem></varlistentry>
 <varlistentry><term>&kwd-pac;</term>
  <listitem><simpara>with the nickname <quote role="package"></quote>
  </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 &cl-pac; 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>Function &package-lock;</title>
<para><indexterm id="pack-lock-f" significance="preferred">
  <primary id="pack-lock-i"><function>PACKAGE-LOCK</function>
 </primary></indexterm>
 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-t; (continuing overrides locking for this operation).
When &suppress-check-redef; is &t; (&not-e; a good idea!), the &error-t;
is not &signal;ed for redefine operations.
Function <literal role="sexp" >(&package-lock; &pack-r;)</literal>
returns the generalized boolean indicating whether the &pack-r; is locked.
A package (or a 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;).</para></formalpara>

<formalpara><title>Macro &without-package-lock;</title>
<para>If you want to evaluate some forms with certain packages unlocked,
 you can use
 <firstterm>&without-package-lock;
  <indexterm id="without-pack-lock" significance="preferred">
   <primary id="without-pack-lock-i"><function>WITHOUT-PACKAGE-LOCK</function>
 </primary></indexterm></firstterm>:
<programlisting>
(&without-package-lock; ("LISP" "EXT" "CLOS")
  (defun restart () ...))
</programlisting>
or
<programlisting>
(&without-package-lock; ("LISP") (trace read-line))
</programlisting>
<literal role="sexp" >(&without-package-lock; () ...)</literal>
temporarily unlocks all packages in &sys-pack-list;.</para></formalpara>

<formalpara><title>Discussion - see also
  <ulink url="http://groups.google.com/groups?hl=en&amp;lr=&amp;ie=UTF-8&amp;selm=3C3E7F57.7F80395%40pacbell.net">the USENET posting</ulink> by
  <author><firstname>Steven M.</firstname> <surname>Haflich</surname>
   <email>haflich@pacbell.net</email></author></title>
<para>This should prevent you from accidentally hosing yourself with
<programlisting>
 (&defstruct; instance ...)
</programlisting>
and allow enforcing modularity.
Note that you will also get the continuable error when you try to
assign (with &setq;, &psetq;, etc.) a value to an internal special
variable living in a locked package and not accessible in your current
&package-var;, but only in the interpreted code and during compilation.
There is no check for package locks in compiled code because of the
performance considerations.
</para></formalpara>

</section>

<section id="clupack"><title>The
  <quote role="package">COMMON-LISP-USER</quote> 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 <quote role="package">SYS</quote>
    and <quote role="package">COMPILER</quote>, and has no
    &export;ed symbols.  It defines many system internals.
 </simpara></listitem></varlistentry>
 <varlistentry id="ext-pac"><term>&ext-pac;</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</ulink>
 ("Constraints on the &cl-pac; Package for Conforming Programs")
 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>

<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-&export;s all external &symbol-t;s from
 <replaceable>FROM-PACK</replaceable> also from
 <replaceable>TO-PACK</replaceable>, provided it already uses
 <replaceable>FROM-PACK</replaceable>; and &signal;s an &error-t; otherwise.
</para></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-t; is the disjoint union of the types
 &real-t; and &complex-t; (<ulink
 url="&clhs;/Body/glo_e.html#exhaustive_partition"><quote>exhaustive
 partition</quote></ulink>)</para>

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

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

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

<para>The type &float-t; is the disjoint union of the types
 &short-float-t;, &single-float-t;, &double-float-t; and
 &long-float-t;.</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-t;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-t;) or
 inexact (&float-t;) 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-t;,
 &single-float-t;, &double-float-t; and &long-float-t;:
<informaltable id="floating-types-table" frame="all">
<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-t;</entry><entry>1 bit</entry>
 <entry>16+1 bits</entry><entry>8 bits</entry><entry>immediate</entry></row>
       <row><entry>&single-float-t;</entry><entry>1 bit</entry>
 <entry>23+1 bits</entry><entry>8 bits</entry><entry>&ieee-bfp;</entry></row>
       <row><entry>&double-float-t;</entry><entry>1 bit</entry>
 <entry>52+1 bits</entry><entry>11 bits</entry><entry>&ieee-bfp;</entry></row>
       <row><entry>&long-float-t;</entry><entry>1 bit</entry>
 <entry>&gt;=64 bits</entry><entry>32 bits</entry><entry>variable
 length</entry></row></tbody></tgroup></informaltable></para>

<para>The single and double float formats are those of the &ieee-bfp;
 <quote>Standard for Binary Floating-Point Arithmetic</quote>,
 except that &clisp; does not support features like
 <literal>&plusmn;0</literal>, <literal>&plusmn;inf</literal>,
 <literal>NaN</literal>, gradual underflow, etc.
 &cl; does not make use of these features, so, to reduce portability
 problems, &clisp; by design returns the same floating point results on
 all platforms (&clisp; has a floating-point emulation built in for
 platforms that do not support &ieee-bfp;).  Note that
 <itemizedlist><listitem><simpara>When you got a <literal>NaN</literal>
    in your program, your program is broken, so you will spend time
    determining where the <literal>NaN</literal> came from.
    It is better to &signal; an &error-t; in this case.</simpara></listitem>
  <listitem><simpara>When you got unnormalized floats in your program,
    your results will have a greatly reduced accuracy anyway.
    Since &clisp; has the means to cope with this - &long-float-t;s of
    <link linkend="lfd">variable precision</link> - it does not
    need unnormalized floats.</simpara></listitem></itemizedlist>
 This is why &features-var; does not contain the
 <constant>:IEEE-FLOATING-POINT</constant> keyword.</para>

<formalpara id="lfd"><title>Arbitrary Precision Floats</title>
<para>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 about 1000 decimal digits.
</para></formalpara>


<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-t; &rarr; &single-float-t; &rarr;
 &double-float-t; &rarr; &long-float-t;.</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 computer 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&plusmn;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&plusmn;0.005</literal> and <literal>3.3&plusmn;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-t; &rarr;
 &long-float-t; &rarr; &double-float-t; &rarr; &single-float-t;
 &rarr; &short-float-t; (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-v;) &pi-v;)</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-float-t;s,
  a &long-float-t; (like &pi-v;) 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-t;; furthermore much computation time
  would be lost by calculating with &long-float-t;s when only
  &short-float-t;s would be needed.
  </simpara></listitem></varlistentry>
</variablelist>

<formalpara id="warn-fpc"><title>Variable &warn-fpc;</title>
<para>If the variable &warn-fpc; is non-&nil;, a warning is emitted for
 every coercion involving different floating-point types.
 As explained above, float precision contagion is not a good idea,
 this is why &warn-fpc; is set to &t; initially.
 You can avoid the contagion by doing all your computations with the
 same floating-point type (and using &float; to convert all constants,
 e.g., &pi-v;, to your preferred type).
 Set it to &error; to have &clisp; &signal; an &error-t; on float
 precision contagion.</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 &zero;, not only
 <literal>0.0</literal> (which would mean "approximately 0").</para>

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

<para>The type specifier <literal role="type">(&complex-t;
 &type-r;)</literal> is equivalent to <literal
 role="type">(&complex-t; &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 &zero;,
 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>Function &upgraded-complex-part-type;</title>
<para>When the argument is not a &recog-subt; or &real-t;,
 &upgraded-complex-part-type; &signal;s an &error-t;,
 otherwise it returns &real-t;, since a &complex-t; number in
 &clisp; can always have &realpart; and &imagpart; of any type.
</para></formalpara>

<formalpara id="default-float-format">
 <title>Variable &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>Macro &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-t; inhibited.  Floating point operations
 will silently return zero instead of &signal;ing an &error-t; of type
 &floating-point-underflow-t;.</para></formalpara>

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

<formalpara><title>Function <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-t;.</para></formalpara>

<formalpara><title>Function <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 &signal;s an &error-t; when the quotient
 is not integer.  (This is more efficient than &slash;.)</para></formalpara>

<formalpara><title>Function <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>

<formalpara><title>Function <function>EXT:MOD-EXPT</function></title>
<para><literal role="sexp">(<function>EXT:MOD-EXPT</function>
 &k-r; &l-r; &m-r;)</literal> is equivalent to
 <literal role="sexp">(&mod; (&expt; &k-r; &l-r;) &m-r;)</literal>
 except it is more efficient for very large arguments.
</para></formalpara>

</section>

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

<formalpara id="expt"><title>Function &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 id="log"><title>Function &log;</title>
<para><literal role="sexp">(&log; &number-r; &base-r;)</literal> &signal;s
 an &error-t; if <literal>&base-r; = 1</literal>.</para></formalpara>

<formalpara id="pi"><title>Constant &pi-v;</title>
 <para>The value of &pi-v; is a &long-float-t; with the precision given
  by &lfd-l;.  When this precision is changed, the value of &pi-v; is
  automatically recomputed.  Therefore &pi-v; is &not-e; 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-t; number) to a
  floating point number with at least &digits-r; mantissa digits.
  The following always evaluates to &t;:
  <programlisting>
   (&geq; (&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>Fixnum limits</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-v;, 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 &not-e; &constant;s.</para>

</section>

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

<section id="float-inexact">
  <title>Condition &floating-point-inexact-t;</title>
<para>This &condition-t; is never &signal;ed 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
 &charset-ascii;.</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 21-bit &unicode; 3.2
 character set (ISO 10646, also known as UCS-4).
</simpara></listitem></varlistentry></variablelist>
<!-- #endif -->

<!-- #if defined(ISOLATIN_CHS) && !defined(UNICODE) -->
<variablelist>
<varlistentry><term>Platform dependent: &unix; (except &nextstep;),
   &win32; 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:
<informaltable id="latin-1-table" frame="all">
  <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></informaltable>
&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:
<informaltable id="next-charset-table" frame="all">
  <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></informaltable>
&char-table-legend;
</para></listitem></varlistentry></variablelist>
<!-- #endif -->

<table id="standard-char-table" frame="all">
  <title>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-s;</entry><entry><keycode>#x0A</keycode></entry></row>
</tbody></tgroup></table>

<table id="semi-standard-char-table" frame="all">
  <title>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>&lf-s;</entry><entry><keycode>#x0A</keycode></entry></row>
 <row><entry><keysym>#\Page</keysym></entry>
              <entry><keycode>#x0C</keycode></entry></row>
 <row><entry>&cr-s;</entry><entry><keycode>#x0D</keycode></entry></row>
</tbody></tgroup></table>

<para>&nl-s; 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 <xref linkend="chario"/>.</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-t;
 and &input-char;.
 Note that &eql; or &equal; are equivalent to &eq; on 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><para>Character bits:
    <informaltable id="bit-table" frame="all">
     <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></informaltable></para></listitem></varlistentry>
 <varlistentry><term><literal role="sexp">(<function>ext:char-font</function>
  &object-r;)</literal> </term>
 <listitem><simpara>returns the font of a &character-t; 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-t; 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;, &win32;
   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-t;
 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(WIN32) || (defined(UNIX) && (O_BINARY != 0)) -->
<variablelist>
<varlistentry><term>Platform dependent: &win32;
   platforms only.</term>
<listitem><simpara>When writing to a file, &nl-s; is converted to
 &cr-c;/&lf-c;. (This is the usual convention on &dos;.)
 For example, &cr-s;+&nl-s; 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-s;
 (the usual convention on &dos;), and &cr-c; not followed by &lf-c; is
 converted to &nl-s; as well (the usual conversion on MacOS, also used
 by some programs on &win32;).
 If you do not want this, i.e., if you really want to distinguish
 &lf-c;, &cr-c; and &cr-c;/&lf-c;, you have to resort to
 binary input (function &read-byte;).</para>

<formalpara><title>Rationale</title>
<para>In &clisp;, &nl-s; is identical to &lf-s;
 (which is specifically permitted by &ansi-cl; in section
 <ulink url="http://www.lisp.org/HyperSpec/Body/sec_13-1-7.html">Character
  Names</ulink>).
 Consider a file containing exactly this string:
 <literal role="sexp">(&concatenate; 'string "foo" (string &lf-s;)
  "bar" (string &cr-s;) (string &lf-s;))</literal>
 Suppose we open it with
 <literal role="sexp">(&open; "foo" &extfmt; &dos-k;)</literal>.
 What should &read-line; return?
 Right now, it returns <literal>"foo"</literal> (the second &read-line;
 returns <literal>"bar"</literal> and reaches &eos;).
 If our i/o were "faithful", &read-line; would have returned the string
 <literal role="sexp">(&concatenate; 'string "foo" (string &lf-s;)
  "bar")</literal>, i.e., a string with an embedded &nl-s;
 between <literal>"foo"</literal> and <literal>"bar"</literal> (because
 a single &lf-s; is not a &nl-s; in the specified &extfmt;, it will not
 make &read-line; return, but it <emphasis>is</emphasis> a CLISP &nl-s;!)
 Even though the specification for &read-line; does not explicitly
 forbids newlines inside the returned string, such behavior would be
 quite surprising, to say the least.
 Moreover, this line (with an embedded &nl-s;) would be written as two
 lines (when writing to a &stream-t; with &extfmt; of &dos-k;), because
 the embedded &nl-s; would be written as &cr-c;+&lf-c;.
</para></formalpara>

</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 <xref linkend="encoding"/>.</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 &zero; (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>Number of characters</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>17 * 2<superscript>16</superscript> = 1114112</entry></row>
</tbody></tgroup></table>

<para>The types <classname>EXT:STRING-CHAR</classname> and
 &base-char-t; are equivalent to &character-t;.</para>

<para>The graphic characters have been described
 <link linkend="graph-char">above</link>.</para>

<para>The standard characters are &nl-s; 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>Function
  <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 WIN32_CHARNAMES -->
<table id="dos-win32-chars-table" frame="all">
 <title>Platform dependent characters: &win32; platforms.</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-s;</entry><entry>&lf-s;</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>&cr-s;</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 characters: &unix; platforms.</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-s;</entry>
          <entry><keysym>#\Nl</keysym></entry><entry>&lf-s;</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>&cr-s;</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>Character bit constants (obsolete)</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>

<formalpara 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;:
 <programlisting><literal role="sexp">(&mapcap; &func-r; &x1-r; ... &xn-r;)</literal> &equiv;
<literal role="sexp">(&apply; #'&append; (&mapcar; &func-r; &x1-r; ... &xn-r;))</literal></programlisting>
(Actually a bit more efficient that this would have been.)</para></formalpara>

<formalpara 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;:
 <programlisting><literal role="sexp">(&maplap; &func-r; &x1-r; ... &xn-r;)</literal> &equiv;
<literal role="sexp">(&apply; #'&append; (&maplist; &func-r; &x1-r; ... &xn-r;))</literal></programlisting>
 (Actually a bit more efficient that this would have been.)</para></formalpara>

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


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

<formalpara><title>Function &make-array;</title>
<para>&make-array; can return specialized arrays for the
 &array-element-type;s
 <literal role="type">(&unsigned-byte-t; 2)</literal>,
 <literal role="type">(&unsigned-byte-t; 4)</literal>,
 &unsigned-byte-8;, &unsigned-byte-16;, &unsigned-byte-32;,
 and, of course, the required specializations &nil-t;, &bit-t; and
 &character-t;.</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>Array limits</title>
 <tgroup cols="4" colsep="1" rowsep="1" align="center">&cpu-type-header;
 <tbody>
 <row><entry>&array-rank-limit;</entry>
      <entry namest="b16" nameend="b64" align="center"
            >2<superscript>12</superscript> = 4096</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>

<note><para>Note that &array-dimension-limit; and &array-total-size-limit;
 are not &fixnum-t;s (they are equal to
 <literal role="sexp">(&pl1; &most-positive-fixnum;)</literal>),
 contrary to the &ansi-cl; Issue <ulink url="&clhs;/Issues/iss014.html"
 >ARRAY-DIMENSION-LIMIT-IMPLICATIONS:ALL-FIXNUM</ulink>.</para></note>

</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>Function &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>Function &string-width;</title>
 <para><literal role="sexp">(&string-width; &string-r;
   &key-amp; &start-r; &end-r;)</literal>
  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-f;:</para>

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

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

</section>
</section>

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

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

<formalpara><title>Function &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-t;,
 the &cdr; parts are modified.  If the argument is a &vector-t; 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>Variable &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 which 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 <constant>:WEAK</constant> can take the following values:
 <simplelist columns="1">
 <member>&nil; (default)</member>
 <member>&key-k;</member>
 <member><constant>:VALUE</constant></member>
 <member><constant>:EITHER</constant></member>
 <member><constant>:BOTH</constant></member>
</simplelist>
and specifies whether the &hash-table-t; is <emphasis>weak</emphasis>:
if the key, value, either or both are not accessible for the &gc;ion
purposes, i.e., if they are only accessible via weak &hash-table-t;s
and &weak-pointer;s, it is &gc;ed and removed from the weak
&hash-table-t;.</para>

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

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

</section>

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

<para>You can define a new hash table test using the macro
 &defhash;: <literal role="sexp">(&defhash; test-name &test-f;
  &hash-f;)</literal>, after which <replaceable>test-name</replaceable>
 can be passed as the <constant>:TEST</constant> argument to
 &make-hash-table;.  E.g.: <programlisting>
 (&defhash; string &string-eq; &sxhash;)
 (&make-hash-table; :test 'string)
</programlisting>
(which is not too useful because it is equivalent to an &equal;
&hash-table-t; but less efficient).</para>

<para>The fundamental requirement is that the &test-f; and &hash-f; are
 consistent: <programlisting>
  (&funcall; &test-f; &x-r; &y-r;) &rArr;
  (&areq; (&funcall; &hash-f; &x-r;) (&funcall; &hash-f; &y-r;))
 </programlisting>
 This means that the following definition: <programlisting>
  (&defhash; number &areq; &sxhash;) ; <emphasis role="strong">BAD!</emphasis>
 </programlisting>
 is &not-e; correct because <literal role="sexp">(&areq; 1 1d0)</literal> is
 &t; but <literal role="sexp">(&areq; (&sxhash; 1) (&sxhash; 1d0))</literal>
 is &nil;.  The correct way is, e.g.: <programlisting>
  (&defhash; number &areq; (&lambda-m; (x) (&sxhash; (&coerce; x '&short-float-t;))))
 </programlisting>
 (note that
 <literal role="sexp">(&coerce; &x-r; &short-float-t;)</literal>
 does &not-e; cons up &fresh; objects while
 <literal role="sexp">(&coerce; &x-r; &double-float-t;)</literal>
 does).</para>

</section>

<section id="ht-test"><title>Function &hash-table-test;</title>
<para>Function &hash-table-test; returns either one of the four standard
 symbols &eq;, &eql;, &equal;, &equalp;, or, for &hash-table-t;s
 created with a user-defined &hash-table-test; (see macro &defhash;),
 a &cons-t; cell <literal role="sexp">(&test-f; . &hash-f;)</literal>.</para>
</section>

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

<para>For iteration through a &hash-table-t;, 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-form;s.</para>

</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) -->
<varlistentry><term>Platform dependent: &unix; platforms only.</term>
<listitem><simpara>For example, <filename>#P"foo/bar"</filename> denotes
 the file &bar-f; in the directory &foo-f;,
 while <filename>#P"foo/bar/"</filename> denotes the subdirectory
 &bar-f; of the directory &foo-f;.
</simpara></listitem></varlistentry>
<!-- #endif -->

<!-- #ifdef PATHNAME_WIN32 -->
<varlistentry><term>Platform dependent: &win32;  platforms only.</term>
<listitem><simpara>For example, <filename>#P"foo\\bar"</filename>
 denotes the file &bar-f; in the directory &foo-f;,
 while <filename>#P"foo\\bar\\"</filename> denotes the subdirectory
 &bar-f; of the directory &foo-f;.
</simpara></listitem></varlistentry>
<!-- #endif -->

<!-- #if defined(PATHNAME_WIN32) || defined(UNIX_CYGWIN32) -->
<varlistentry id="device-prefix"><term>Platform dependent: &win32; and
  &cygwin; platforms only.</term>
 <listitem><simpara>User variable <firstterm>&dev-prefix;</firstterm>
  controls translation between &cygwin; pathnames
  (e.g., <filename>#P"/cygdrive/c/gnu/clisp/"</filename>) and native
  &win32; pathnames (e.g., <filename>#P"C:\\gnu\\clisp\\"</filename>)
  When it is set to &nil;, no translations occur and the &cygwin; port
  will not understand the native paths and the native &win32; port will
  not understand the &cygwin; paths.
  When its value is a string, it is used by &parse-namestring; to
  translate into the appropriate platform-specific representation,
  so that on &cygwin;,
  <literal role="sexp">(&parse-namestring; "c:/gnu/clisp/")</literal>
  returns <literal role="sexp">#P"/cygdrive/c/gnu/clisp/"</literal>,
  while on &win32;
  <literal role="sexp">(&parse-namestring; "/cygdrive/c/gnu/clisp/")</literal>
  returns <literal role="sexp">#P"C:/gnu/clisp/"</literal>.
  The initial value is <literal>"cygdrive"</literal>, you should edit
  &config-file; to change it.</simpara></listitem></varlistentry>
<!-- #endif -->
</variablelist>

<para>This is especially important for the
 <link linkend="dir">directory-handling functions</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 or with name <replaceable>.yy</replaceable> and no type,
    depending on the value of &parsedot;.</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>

<section id="path-dir-canon"><title>Directory canonicalization.</title>
<para>As permitted by the &make-pathname; secification, the &pathname-t;
 directory component is canonicalized when the pathname is constructed:
 <orderedlist>
  <listitem><simpara><filename>""</filename> and
    <filename>"."</filename> are removed</simpara></listitem>
  <listitem><simpara><filename>".."</filename>,
    <filename>"*"</filename>, and <filename>"**"</filename> are converted
    to <constant>:UP</constant>, &wild-k; and &wild-inferiors-k;,
    respectively</simpara></listitem>
  <listitem><simpara>patterns <filename>foo/../</filename> are
    collapsed</simpara></listitem>
 </orderedlist>
</para>
</section>

<section id="path-platform-specific"><title>Platform-specific issues.</title>

<!-- #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>&dir-term;
 <listitem><informaltable id="unix-dir-table" frame="all">
 <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></informaltable></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>

<informaltable id="unix-filename-table" frame="all">
 <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></informaltable>
</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-t;, wildcard characters may
   occur but do not 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>&dir-term;
 <listitem><informaltable id="win32-dir-table" frame="all">
   <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></informaltable></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>

<informaltable id="win32-filename-table" frame="all">
 <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></informaltable>

<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;, &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 -->
<formalpara id="name-type-split"><title>Name/type namestring split.</title>
<para><variablelist>
<varlistentry><term>Platform dependent:  &unix;, &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>
  <listitem><para>if the only &file-dot; is the first character, then
   the behavior depends on the value of the user variable
    <firstterm>&parsedot;</firstterm>
   which can be either
   <variablelist><varlistentry><term>&type-k;</term>
    <listitem><simpara>&nil; &name-r;, everything after the &file-dot;
     is the &type-r;; or</simpara></listitem></varlistentry>
   <varlistentry><term>&name-k;</term>
    <listitem><simpara>&nil; &type-r;, everything is the
     &name-r;</simpara></listitem></varlistentry></variablelist>
   </para></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-k; "foo.bar")</literal>.
 </simpara></listitem></varlistentry>
</variablelist></para></formalpara>
<!-- #endif -->
</section>

</section>

<section id="unspecific"><title>:UNSPECIFIC as a Component Value
 <ulink url="&clhs;/Body/sec_19-2-2-2-3.html">[CLHS-19.2.2.2.3]</ulink></title>

<para>The symbol <constant>:UNSPECIFIC</constant> is not permitted as a
 pathname component for any slot of any pathname.
 It is also illegal to pass it as an argument to &make-pathname;.</para>

<para>The only use for <constant>:UNSPECIFIC</constant> is that it is
 returned by &pathname-device; for &logical-pathname-t;s, as required by
 <ulink url="&clhs;/Body/sec_19-3-2-1.html">[CLHS-19.3.2.1] Unspecific
  Components of a Logical Pathname</ulink>.</para>
</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_UNIX -->
<varlistentry><term>Platform dependent: &unix; platforms only.</term>
<listitem><informaltable id="unix-path-external-table" frame="all">
 <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></informaltable>

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

<!-- #ifdef PATHNAME_WIN32 -->
<varlistentry><term>Platform dependent: &win32; platforms only.</term>
<listitem><informaltable id="win32-path-external-table" frame="all">
 <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></informaltable>

<para>Name and type may be &string-t;s of any &length;
 (consisting of printing &ascii; characters, except &file-slash;,
 &file-bsla;, &file-colon;).</para></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: unknown platforms only.</term>
<listitem><simpara>The function &user-homedir-pathname; is not implemented.
</simpara></listitem></varlistentry>
</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>

<formalpara id="path-des"><title>Pathname Designators</title>
 <para>When &parsename; is &nil;, &symbol-t; is also treated as a
  <ulink url="&clhs;/Body/glo_p.html#pathname_designator">pathname
   designator</ulink>, namely its &symbol-name; is converted to the
  operating system's preferred pathname case.</para></formalpara>

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

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

<section id="translate-pathname"><title>Function &translate-pathname;</title>

<para>&translate-pathname; has two additional keywords: <literal
 role="sexp">(&translate-pathname; &source-r;
 <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; &source-r;
 <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 &source-r;.</para>

</section>

<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-t;.
 To construct a logical pathname from a string, the function
 &logical-pathname; can be used.</para>

<para>The &ansi-cl; behavior of recognizing logical pathnames when
 the &string-r; begins with some alphanumeric characters followed by a
 colon (<keysym>#\:</keysym>) can be very confusing
 (cf. <filename>"c:/autoexec.bat"</filename>,
 <filename>"home:.clisprc"</filename> and
 <filename>"prep:/pub/gnu"</filename>)
 and therefore is disabled by default.
 To enable the &ansi-cl; 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>

<formalpara><title>Rationale</title>
<para>&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-m; 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-m; a b b)</literal> is the same as
 <literal role="sexp">(&or-m; 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></formalpara>

<para>(This question actually does matter 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>Reversely, 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>

<formalpara><title>Rationale</title>
<para><quote>merge</quote> is <emphasis>merge</emphasis> and
 not <emphasis>or</emphasis>.</para></formalpara>
</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 &env-var;s
  <envar>LOGICAL_HOST_&host-r;_FROM</envar> and
  <envar>LOGICAL_HOST_&host-r;_TO</envar> exist, then their values
  define the map of the &host-r;.</simpara></listitem>
 <listitem><simpara>If the &env-var;
  <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>Function &rename-file;</title>
<para>&rename-file; always returns a non-logical pathname as
 its first value.</para></formalpara>

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

<formalpara><title>Function &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>Function &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-t;
 if the parent directory of &path-r; does not exist.</para></formalpara>

<formalpara id="del-file"><title>Function &delete-file;</title>
<para><literal role="sexp">(&delete-file; &path-r;)</literal> deletes
 the pathname &path-r;, not its &truename;, and returns the absolute
 pathname it actually removed or &nil; if &path-r; did not exist.
 When &path-r; points to a file which is currently open in &clisp;, an
 &error-t; is &signal;ed.</para></formalpara>

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

<para><literal role="sexp">(&directory; &optional-amp; &path-r; &key-amp;
  :FULL :CIRCLE &if-does-not-exist;)</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.
  E.g., <literal role="sexp">(&directory; "/etc/*/")</literal> lists
  all subdirectories in the directory
  <filename>#P"/etc/"</filename>.</simpara></listitem>
 <listitem><simpara>Otherwise a list of all matching files is returned.
  E.g., <literal role="sexp">(&directory; "/etc/*")</literal> lists all
  regular files in the directory <filename>#P"/etc/"</filename>.
  If the <constant>:FULL</constant> argument is non-&nil;,
  additional information is returned: 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>

If you want <emphasis>all</emphasis> the files <emphasis>and</emphasis>
subdirectories in the current directory, you should use
<literal role="sexp">(&nconc; (&directory; "*/") (&directory; "*"))</literal>.
If you want all the files and subdirectories in all the subdirectories
under the current directory
(similar to the &ls; <option>-R</option> &unix; command),
use <literal role="sexp">(&nconc; (&directory; "**/")
 (&directory; "**/*"))</literal>.

<!-- #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 -->

The argument &if-does-not-exist; controls the treatment of links
pointing to non-existent files and can take the following values:
<variablelist>
<varlistentry><term><constant>:DISCARD</constant> (default)</term>
 <listitem><simpara>discard the bad directory entries
</simpara></listitem></varlistentry>
<varlistentry><term>&error-k;</term>
 <listitem><simpara>&signal; an &error-t; on bad directory entries
   (this corresponds to the default behavior of &directory; in &cmucl;)
</simpara></listitem></varlistentry>
<varlistentry><term><constant>:KEEP</constant></term>
 <listitem><simpara>keep bad directory entries in the returned list
   (this roughly corresponds to the <literal role="sexp">(&directory;
    ... <constant>:TRUNAMEP</constant> &nil;)</literal> call in &cmucl;)
</simpara></listitem></varlistentry>
<varlistentry><term><constant>:IGNORE</constant></term>
 <listitem><simpara>Similar to <constant>:DISCARD</constant>, but also
   do not signal an error when a directory is unaccessible (contrary to
   the &ansi-cl; specification).</simpara></listitem></varlistentry>
</variablelist>

</para>

<formalpara><title>Function <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>

<formalpara id="cd"><title>Function &cd;</title>
<para><literal role="sexp">(&cd; &path-r;)</literal> sets it,
 <literal role="sexp">(&cd;)</literal> returns it.
<variablelist>
<!-- #if defined(PATHNAME_UNIX) -->
<varlistentry><term>Platform dependent: &unix; platforms only.</term>
 <listitem><simpara><literal role="sexp">(&cd; [&path-r;])</literal>
   manages the current directory.</simpara></listitem></varlistentry>
<!-- #else -->
<varlistentry><term>Platform dependent: &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></para></formalpara>

<formalpara><title>Function <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 <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 <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 id="readline"><title>&readline;</title>
 <varlistentry><term>Platform dependent: &unix; platforms
    only, and only in &clisp; built &without; compile-time flag &noreadline;
    (and when &readline; is installed on your machine already).</term>
 <listitem><simpara>Input through &terminal-io-var; uses the &readline;
  library.  Arrow keys can be used to move within the input history.
  The <keysym>#\Tab</keysym> key completes the &symbol-t; name or
  &pathname-t; that is being typed.
  See <ulink url="http://cnswww.cns.cwru.edu/~chet/readline/rluserman.html"
  >readline user manual</ulink> for general details and
  <olink targetdoc="man" targetptr="clisp"/> for &clisp;-specific
  extensions.</simpara>
  <warning><simpara>The &readline; library is &not-e; used if standard
    input and standard output do not both refer to the same terminal.
    In some exotic cases, e.g., when running under &gdb; in
    an <command>rxvt</command> window under &cygwin;, this may be
    determined incorrectly.</simpara></warning></listitem>
 </varlistentry></variablelist>
<!-- #endif -->

<!-- #if defined(KEYBOARD) -->
<variablelist><title>Macro &with-kbd;</title>
<varlistentry><term>Platform dependent: &unix;, &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,
 <firstterm>&kbd-in;</firstterm> is the stream that reads the
 keystrokes from the keyboard.
 It returns every keystroke in detail, as &character-t; or
 &input-char; with the following bits:
<variablelist>
<!-- #ifdef WIN32 -->
 <varlistentry><term><constant>:hyper</constant></term>
  <listitem><simpara><emphasis>(Platform dependent:
   &win32; platforms only.)</emphasis>
   if a non-standard key.  These keys are:
<!-- #ifdef WIN32 -->
   <emphasis>[&win32;]:</emphasis>
   Function keys, cursor keypads, numeric keypad.
<!-- #endif -->
   </simpara></listitem></varlistentry>
<!-- #endif -->
  <varlistentry><term>slot <replaceable>key</replaceable></term>
    <listitem><para>the key name, for non-standard keys:
      <variablelist>
<!-- #if defined(UNIX) || defined(WIN32) -->
      <varlistentry><term>Platform dependent: &unix;, &win32;
         platforms only.</term>
      <listitem><informaltable id="unix-kbd-keys" frame="all">
       <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></informaltable></listitem></varlistentry>
<!-- #endif -->
      </variablelist></para></listitem></varlistentry>

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

<!-- #ifdef WIN32 -->
  <varlistentry><term><constant>:super</constant></term>
   <listitem><simpara><emphasis>(Platform dependent:
     &win32; 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>
<!-- #ifdef WIN32 -->
  <varlistentry><term><constant>:meta</constant></term>
  <listitem><simpara><emphasis>(Platform dependent: &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 <xref linkend="screen"/>.</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-t;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-t; 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>Functions &stream-element-type; and <literal role="sexp">(&setf;
 &stream-element-type;)</literal> are &generic-function-t;s, see
 <xref linkend="gray"/>.</para>

<section id="bin-stdio"><title>Binary input from &standard-input-var;</title>

<para>Note that you cannot change &stream-element-type; for some
 built-in streams, such as <link linkend="terminal">terminal streams</link>,
 which is normally the value of &terminal-io-var;.
 Since &standard-input-var; normally is a &synonym-stream-t; pointing
 to &terminal-io-var;, you cannot use &read-byte; in the it.</para>

<para>Since <ulink url="http://hoohoo.ncsa.uiuc.edu/cgi/">CGI</ulink>
 (Common Gateway Interface) provides the form data for
 <command>METHOD="POST"</command> on the stdin,
 and the server will &not-e; send you an &eos; on the end of the data,
 you will need to use
 <literal role="sexp">(&getenv; <envar>"CONTENT_LENGTH"</envar>)</literal>
 to determine how much data you should read from stdin.
 &clisp; will detect that stdin is not a terminal and create a regular
 &file-stream-t; which can be passed to <literal role="sexp">(&setf;
 &stream-element-type;)</literal>.
 To test this functionality interactively,
 you will need to open the standard input in the binary mode:
<programlisting>
(let ((buf (&make-array; (&parse-integer; (&getenv; "CONTENT_LENGTH"))
                       :element-type &unsigned-byte-8;)))
  (&with-open-stream; (in (&make-stream; &input-k; &eltype; &unsigned-byte-8;))
    (&read-sequence; buf in))
  buf)
</programlisting></para>
</section>
</section>

<section id="make-stream"><title>Function &make-stream;</title>
<para>Function &make-stream; creates a Lisp stream out of an OS file
 handle: <literal role="sexp">(&make-stream; &object-r; &direction-k;
  &eltype; &extfmt; &buffered;)</literal></para>
<para>&object-r; designates an OS handle (a &file-des;),
 and should be one of the following:
 <variablelist>
  <varlistentry><term>number</term>
   <listitem><simpara>denotes the &file-des; of this value
  </simpara></listitem></varlistentry>
  <varlistentry><term>&input-k;</term>
   <listitem><simpara>denotes &clisp; process standard input
  </simpara></listitem></varlistentry>
  <varlistentry><term>&output-k;</term>
  <listitem><simpara>denotes &clisp; process standard output
  </simpara></listitem></varlistentry>
  <varlistentry><term>&error-k;</term>
  <listitem><simpara>denotes &clisp; process standard error
  </simpara></listitem></varlistentry>
  <varlistentry><term>&stream-t;</term>
  <listitem><simpara>denotes the handle of this stream, which should be
    a &file-stream-t; or a &socket-stream;
  </simpara></listitem></varlistentry>
</variablelist></para>

<para>The handle is duplicated (with &dup;), so it is safe to &close;
 a &stream-t; returned by &make-stream;.</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-t; from &stream-r;.
 &stream-r; should be a stream with &stream-element-type;
 &unsigned-byte-8;.
 &eltype-r; should be &type-eq; 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>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-bfp;
 binary representation from &stream-r;.
 &stream-r; should be a &stream-t; with &stream-element-type;
 &unsigned-byte-8;.
 &eltype-r; should be &type-eq; to
 &single-float-t; or &double-float-t;.</para>

<formalpara id="endianness"><title>Endianness</title>
<para>&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></formalpara>

</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-t; with &stream-element-type;
 &unsigned-byte-8;.
 &eltype-r; should be &type-eq; 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-t;.</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-bfp;
 binary representation to &stream-r;.
 &stream-r; should be a &stream-t; with &stream-element-type;
 &unsigned-byte-8;.
 &eltype-r; should be &type-eq; to
 &single-float-t; or &double-float-t;.</para>

</section>

<section id="bulk-io"><title>Bulk Input and Output</title>

<formalpara id="read-seq"><title>Function &read-sequence;</title>
<para>In addition to &read-sequence;, the following two
 functions are provided:
<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; :NO-HANG)</literal> fills the
   subsequence of &sequence-r; specified by &start-k; and &end-k; with
   &integer-t;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).
   When <constant>:NO-HANG</constant> is non-&nil;, does not block:
   treat input unavailability as &eos;.</simpara>
 <simpara>This function is especially efficient if &sequence-r; is a
   &unsigned-byte-vec; and &stream-r; is a &file-pipe-socket;
   &stream-t; 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-t; and &stream-k; is a &file-pipe-socket; stream with
  &stream-element-type; &character-t; or an &input-s; &string-stream-t;.
  </simpara></listitem></varlistentry>
</variablelist></para></formalpara>

<formalpara id="write-seq"><title>Function &write-sequence;</title>
<para>In addition to &write-sequence;, the following two
functions are provided:
<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-r; &key-amp; &start-k; &end-k;)</literal> outputs the
  &integer-t;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-t; 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-r; &key-amp; &start-k; &end-k;  :NO-HANG)</literal> outputs the
  characters of the subsequence of &sequence-r; specified by &start-k;
  and &end-k; to &stream-k;.
  When <constant>:NO-HANG</constant> is non-&nil;, does not block.
  Returns two values: &sequence-r; and the index of the first byte that
  was not output.</simpara>
 <simpara>This function is especially efficient if &sequence-r; is a
  &string-t; and &stream-k; is a &file-pipe-socket; &stream-t;
  with &stream-element-type; &character-t;.
  </simpara></listitem></varlistentry>
</variablelist></para></formalpara>

<formalpara id="bulk-io-rationale"><title>Rationale</title>
<para>The rationale for &rd-ch-seq;, &rd-by-seq;, &wr-ch-seq; and
 &wr-by-seq; is that some &stream-t;s support both character and binary
 i/o, and when you read into a &sequence-t; that can hold both (e.g.,
 &list-t; or &simple-vector-t;) you cannot determine which kind of
 input to use.  In such situation &read-sequence; and &write-sequence;
 &signal; an &error-t;, while &rd-ch-seq;, &rd-by-seq;, &wr-ch-seq; and
 &wr-by-seq; work just fine.</para></formalpara>

</section>

<section id="non-block-io"><title>Non-Blocking Input and Output</title>

<para>In addition to the standard functions &listen; and
 &read-char-no-hang;, &clisp; provides the following functionality
 facilitating non-blocking input and output, both binary and
 character.</para>

<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-f;
  (&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 way 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>
 <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-t; 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 id="rbwhp"><term><literal role="sexp">(&rbwhp;
    &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 id="rbnh"><term><literal role="sexp">(&rbnh;
    &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-t; 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>

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

<variablelist>
 <varlistentry><term>Platform dependent: &win32;
    platforms only.</term>
<listitem><simpara>&file-position; works on any &buffered; &file-stream-t;.
  When a &nl-s; is output to (respectively input from) a file stream,
  its file position is increased by 2 since &nl-s; 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 an additional keyword &buffered;.</para>

<variablelist><title>The acceptable values for the arguments to the
   &file-pipe-socket; functions</title>
 <varlistentry id="eltype"><term>&eltype;</term>
  <listitem><simpara>types equivalent to &character-t; or
    &unsigned-byte-n;, &signed-byte-n;; if the stream is to be
    un&buffered;, &n-r; must be a multiple of 8.</simpara>
   <simpara>If &n-r; is not a multiple of 8, &clisp; will use the
    specified number of bits for i/o, and write the file length
    (as a number of &n-r;-bit bytes) in the preamble.</simpara>
   <simpara>This is done to ensure the input/output consistency:
    suppose you open a file with &eltype; of <literal
    role="type">(&unsigned-byte-t; 3)</literal> and write 7 bytes
    (i.e., 21 bit) there.
    The underlying OS can do input/output only in whole 8-bit bytes.
    Thus the OS will report the size of the file as 3 (8-bit) bytes.
    Without the preamble &clisp; will have no way to know how many
    3-bit bytes to read from this file - 6, 7 or 8.
   </simpara></listitem></varlistentry>
 <varlistentry id="extfmt"><term>&extfmt;</term>
  <listitem><simpara>&encoding;s, (constant) &symbol-t;s in the
   &charset-pac; package, &string-t;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;.
    This argument determines how the lisp &character-t; data is
   converted to/from the 8-bit bytes that the underlying OS uses.
  </simpara></listitem></varlistentry>
 <varlistentry id="buffered"><term>&buffered;</term>
  <listitem><para>&nil;, &t;, or &default-k;.
    Have &clisp; manage an internal buffer for input or output (in
    addition to the buffering that might be used by the underlying OS).
    Buffering is a known general technique to significantly speed up i/o.
  <itemizedlist>
   <listitem><simpara>for functions that create &socket-stream;s and
    <link linkend="pipe">pipes</link>, &default-k; is equivalent to
    &nil;; it you are transmitting a lot of data then using buffering
    will significantly speed up your i/o;</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>
  Note that some files, notably those on the <filename>/proc</filename>
  filesystem (on &unix; systems), are actually, despite their innocuous
  appearance, special files, so you might need to supply an explicit
  &buffered; &nil; argument for them.  Actually, &clisp; detects that
  the file is a <filename>/proc</filename> file, so that one is covered,
  but there are probably more strange beasts there!
</para></listitem></varlistentry>
</variablelist>

</section>

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

<para>Function &close; is a &generic-function-t;, see
 <xref linkend="gray"/>.</para>

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

<para>&get-output-stream-string; returns the same value after
 &close; as it would before it.</para>

<para>&close; on an already closed &stream-t; does nothing and returns
 &t;.</para>

<para>If you do not &close; your &stream-t; explicitly, it will be
 closed at &gc;ion time automatically.
 This is not recommended though because &gc;ion is not deterministic.
 Please use &with-open-stream; etc.</para>

</section>

<section id="open-stream-p"><title>Function &open-stream-p;</title>
<para>Function &open-stream-p; is a &generic-function-t;, see
 <xref linkend="gray"/>.</para>
</section>

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

<para>&input-stream-p; and &interactive-stream-p; return false for
 &broadcast-stream-t;s.</para>

</section>

<section id="stream-buffer"><title>Functions
  <function>EXT:MAKE-BUFFERED-INPUT-STREAM</function> and
  <function>EXT:MAKE-BUFFERED-OUTPUT-STREAM</function></title>

<para><literal role="sexp">(EXT:MAKE-BUFFERED-OUTPUT-STREAM &func-r;)</literal>
 returns a buffered &out-s;.
 &func-r; is a &function-t; expecting one argument, a &simple-string-t;.
 &write-char; collects the &character-t;s in a &string-t;, until a
 newline character is written or &force-output;/&finish-output; is called.
 Then &func-r; is called with a &simple-string-t; as argument,
 that contains the characters collected so far.
 &clear-output; dicards the characters collected so far.</para>

<para><literal role="sexp">(EXT:MAKE-BUFFERED-INPUT-STREAM &func-r;
  <replaceable>mode</replaceable>)</literal> returns a buffered &in-s;.
 &func-r; is a &function-t; of 0 arguments that returns
 either &nil; (stands for &eos;) or up to three values
 &string-r;, &start-r;, &end-r;.
 &read-char; returns the &character-t;s of the current &string-r; one
 after another, as delimited by &start-r; and &end-r;, which default to
 &zero; and &nil;, respectively.
 When the &string-r; is consumed, &func-r; is called again.
 The &string-r; returned by &func-r; should not be changed,
 otherwise &func-r; should copy the &string-r; with &copy-seq;
 or &subseq; beforehand.
 <replaceable>mode</replaceable> determines the behavior of &listen;
 when the current &string-r; buffer is empty:
 <variablelist>
  <varlistentry><term>&nil;</term>
   <listitem><simpara>the stream acts like a &file-stream-t;,
     i.e. &func-r; is called</simpara></listitem></varlistentry>
  <varlistentry><term>&t;</term>
   <listitem><simpara>the stream acts like an interactive stream without
     &eos;, i.e. one can assume that further characters will always
     arrive, without calling &func-r;</simpara></listitem></varlistentry>
  <varlistentry><term>&function-t;</term>
   <listitem><simpara>this &function-t; tells, upon call, if further
     non-empty &string-r;s are to be expected.</simpara></listitem>
 </varlistentry></variablelist>
 &clear-input; discards the rest of the current &string-r;,
 so &func-r; will be called upon the next &read-char; operation.
</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>Variable &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>Variable &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>Variable &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>Variable &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-s;,
 then a &nl-s; 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-t;, 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-t;, 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 &not-e; 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>Functions &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 additional &format; instruction
 <firstterm>~!<indexterm id="format-bang" significance="preferred">
   <primary>&format;</primary>
   <secondary id="format-bang-i">~!</secondary></indexterm></firstterm>
 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 explicitly.
 <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 the
 <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-1.html">1.5.1.4.1 Resolution of Apparent
 Conflicts in Exceptional Situations</ulink>.</para>

<warning><simpara>When both &print-readably-var; and &pathprint; are
  non-&nil; and the namestring will be parsed to a dissimilar object
  (with the current value of &parsedot;), an &error-t; of type
  &print-not-readable-t; is &signal;ed.</simpara></warning>

</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
 <firstterm><ulink url="&clhs;/Body/sec_22-1-3-1-3.html"
                   ><function>SYS::WRITE-FLOAT-DECIMAL</function></ulink>
  <indexterm id="write-float-decimal" significance="preferred">
   <primary id="write-float-decimal-i"><function>WRITE-FLOAT-DECIMAL</function>
 </primary></indexterm></firstterm>,
 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>
<varlistentry><term>Platform dependent: &unix;, &win32;
   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>
</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 &structure-object-t;s lacking a keyword constructor</entry></row>
 <row><entry><literal>#&lt;ARRAY &type-r; &dimensions-r;&gt;</literal></entry>
  <entry>all &array-t;s except &string-t;s, 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-t;</entry></row>
 <row><entry><literal>#&lt;PACKAGE &name-r;&gt;</literal></entry>
  <entry>&package-t;</entry></row>
 <row><entry><literal>#&lt;HASH-TABLE #x...&gt;</literal></entry>
  <entry>&hash-table-t;, if &print-array-var; is &nil;</entry></row>
 <row><entry><literal>#&lt;READTABLE #x...&gt;</literal></entry>
  <entry>&readtable-t;</entry></row>
 <row><entry><literal>#&lt;SYMBOL-MACRO &form-r;&gt;</literal></entry>
  <entry>&symbol-macro; handler</entry></row>
 <row><entry><literal>#&lt;MACRO &func-r;&gt;</literal></entry>
  <entry>macro expander (defined by &defmacro; and friends)</entry></row>
 <!-- #ifdef FOREIGN -->
 <row><entry><literal>#&lt;&foreign-pointer-t; #x...&gt;</literal></entry>
  <entry>foreign pointer <emphasis>(Platform dependent: &unix;,
    &win32; platforms only.)</emphasis>
 </entry></row>
<!-- #endif -->
<!-- #ifdef DYNAMIC_FFI -->
 <row><entry><literal>#&lt;&foreign-address-t; #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 &in-s;'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(WIN32) -->
<varlistentry><term>Platform dependent: &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 -->
</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
 <link linkend="make-pack">&case-sensitive-k;</link> option of
 &make-package; and &defpackage;.</para>

</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; &outfile-k;
  :LISTING &warnings-k; &verbose-k; &print-k; &extfmt;)</literal>
compiles a file to platform-independent bytecode.</para>

<variablelist id="compile-file-arguments">
 <title>Options for &compile-file;</title>
<varlistentry><term><replaceable>input-file</replaceable></term>
 <listitem><simpara>should be a &path-des;.
 </simpara></listitem></varlistentry>
<varlistentry><term>&outfile-k;</term>
 <listitem><simpara>should be &nil; or &t; or a &path-des; or an
   &out-s;.  The default is &t;.</simpara></listitem></varlistentry>
<varlistentry><term><constant>:LISTING</constant></term>
 <listitem><simpara>should be &nil; or &t; or a &path-des; or an
   &out-s;.  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 <firstterm>&compile-warn;</firstterm>,
 &compile-verbose-var;, &compile-print-var; provide defaults for the
 &warnings-k;, &verbose-k;, &print-k; keyword arguments, respectively,
 and are bound by &compile-file; to the values of the arguments, i.e.,
 these arguments are recursive.</para>

<para>For each input file (default file type: &lisp-file;)
 the following files are generated:
<informaltable id="compile-file-new-files-table" frame="all">
 <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 &outfile-k; 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 &outfile-k; 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 &outfile-k; 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></informaltable></para>

<warning id="c-file-overwrite"><para>If you have two files in the same
directory - &foolisp-f; and <filename>#P"foo.c"</filename>, and you
compile the first file with &clisp;, the second file will be
<emphasis>clobbered</emphasis> if you have any &ffi-pac; forms in
the first one!</para></warning>

</section>

<section id="compile-file-path">
 <title>Function &compile-file-pathname;</title>
<para>The default for the &outfile-k; 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-t; or a &list-t; of &pathname-t;s: files to be &load;ed
 if the required module is not already present.</para>

<para>At compile time, <literal role="sexp">(&require; &foo-f;)</literal>
forms are treated specially: &load-paths; is searched for
&foolisp-f; <emphasis>and</emphasis> <filename>#P"foo.lib"</filename>.
If the latest such file is a &lisp-file;, it is compiled;
otherwise the &lib-file; is loaded.</para>

<para>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 &not-e; necessary to either enclose &require; forms in
&eval-when; or to load the required files in the makefiles: if you have
two files, &foolisp-f; and <filename>#P"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 <literal role="sexp">(&load; &foo-f;)</literal>
in order to <literal role="sexp">(&compile-file;
 <filename>#P"bar.lisp"</filename>)</literal>.
If memory is tight, and if &foolisp-f; contains
only a few inline functions, macros, constants or variables,
this is a space and time saver.
If &foolisp-f; 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 four additional keywords &echo-k;, &compiling-k;,
 &extra-file-types-k;, and &obsolete-action-k;.</para>

<para><literal role="sexp">(&load; &filename-r; &key-amp; &verbose-k;
 &print-k; &echo-k; &if-does-not-exist; &compiling-k;
 &extra-file-types-k; &obsolete-action-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 <firstterm>&load-echo;</firstterm>, 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 <firstterm>&load-comp;</firstterm>,
  which is initially &nil;.</simpara></listitem></varlistentry>
 <varlistentry><term>&extra-file-types-k; &list-t;</term>
  <listitem><simpara>Specifies the additional file types considered for
  loading, in addition to <firstterm>&source-types;</firstterm>
  (which is initially <literal role="sexp">("lisp" "lsp" "cl")</literal>)
  and <firstterm>&compiled-types;</firstterm>
  (which is initially <literal role="sexp">("fas")</literal>).
  </simpara><simpara>When &filename-r; does not spefify a unique file
  (e.g., &filename-r; is &foo-f; and both &foolisp-f;
  and <filename>#P&quot;foo.fas&quot;</filename> are found in the
  &load-paths;), then the <emphasis>newest</emphasis> file is loaded.
 </simpara></listitem></varlistentry>
 <varlistentry><term>&obsolete-action-k; &nil;</term>
  <listitem><simpara>Specifies the action to take when loading a
   &fasl-file; with a different <link linkend="bytecode">bytecode</link>
   version from the one supported by this &clisp; version.
   The possible actions are <constant>:DELETE</constant> to delete the
   &fasl-file; and &error-k; to &signal; an &error-t;.
   The default action is to &warn; and <link linkend="load-paths">look
   for another matching file</link>.
   If no file can be loaded and &if-does-not-exist; is non-&nil;,
   an &error-t; is &signal;ed.
   The default is <firstterm>&load-obs;</firstterm>,
   which is initially &nil;.</simpara></listitem></varlistentry>
</variablelist>

<para>The variables &load-verbose-var;, &load-print-var;,
&load-obs;, &load-comp;, and &load-echo; are bound by &load; when it
receives a corresponding keyword argument (&verbose-k;, &print-k;,
&obsolete-action-k;, &compiling-k;, and &echo-k;), i.e., these arguments
are recursive, just like the arguments &warnings-k;, &verbose-k;, and
&print-k; for &compile-file;.</para>

<formalpara id="load-paths"><title>Variable &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 following symbols
<variablelist id="features-table"><title>Default &features-var;</title>
<varlistentry><term><constant>:CLISP</constant></term>
  <listitem><simpara>the name of this implementation
</simpara></listitem></varlistentry>
<varlistentry><term><constant>:ANSI-CL</constant></term>
 <listitem><simpara>&clisp;
   <ulink url="&clhs;/Body/glo_p.html#purports_to_conform">purports to
    conform</ulink> to &ansi-cl;</simpara></listitem></varlistentry>
<varlistentry><term><constant>:COMMON-LISP</constant></term>
 <listitem><simpara>required by &ansi-cl;</simpara></listitem></varlistentry>
<varlistentry><term><constant>:INTERPRETER</constant></term>
 <listitem><simpara>&eval; is implemented</simpara></listitem></varlistentry>
<varlistentry><term><constant>:COMPILER</constant></term>
 <listitem><simpara>&compile; and &compile-file; are implemented
</simpara></listitem></varlistentry>
<!-- #ifdef SOCKET_STREAMS -->
<varlistentry><term><constant>:SOCKETS</constant></term>
 <listitem><simpara>see <xref linkend="socket"/>
</simpara></listitem></varlistentry>
<!-- #endif -->
<!-- #ifdef GENERIC_STREAMS -->
<varlistentry><term><constant>:GENERIC-STREAMS</constant></term>
 <listitem><simpara>see <xref linkend="clos-stream"/>
</simpara></listitem></varlistentry>
<!-- #endif -->
<!-- #ifdef LOGICAL_PATHNAMES -->
<varlistentry><term><constant>:LOGICAL-PATHNAMES</constant></term>
 <listitem><simpara><link linkend="log-path">Logical Pathnames</link>
   are implemented</simpara></listitem></varlistentry>
<!-- #endif -->
<!-- #ifdef DYNAMIC_FFI -->
<varlistentry><term><constant>:FFI</constant></term>
 <listitem><simpara>if a foreign function interface
   (see <xref linkend="dffi"/>) is supported
   <emphasis>(Platform dependent: many &unix;, &win32;
    platforms only)</emphasis></simpara></listitem></varlistentry>
<!-- #endif -->
<!-- #ifdef GNU_GETTEXT -->
<varlistentry><term><constant>:GETTEXT</constant></term>
 <listitem><simpara>if internationalization (see <xref linkend="i18n"/>)
   using the &ggettext; package is supported
   <emphasis>(Platform dependent: most &unix; platforms
    only)</emphasis></simpara></listitem></varlistentry>
<!-- #endif -->
<!-- #ifdef UNICODE -->
<varlistentry><term><constant>:UNICODE</constant></term>
 <listitem><simpara>if &unicode; (ISO 10646) characters are supported
   (see &charset-pac;)</simpara></listitem></varlistentry>
<!-- #endif -->
<varlistentry><term><constant>:LOOP</constant></term>
 <listitem><simpara>&loop; is implemented</simpara></listitem></varlistentry>
<varlistentry><term><constant>:CLOS</constant></term>
 <listitem><simpara>&clos; is implemented</simpara></listitem></varlistentry>
<varlistentry><term><constant>:WIN32</constant></term>
 <listitem><simpara>if &hw; = PC (clone) and &os; = Win32
  (Windows 95/98/NT/Me/2000/XP)</simpara></listitem></varlistentry>
<varlistentry><term><constant>:PC386</constant></term>
 <listitem><simpara>if &hw; = PC (clone) with a 386/486/586/686/786 CPU
</simpara></listitem></varlistentry>
<varlistentry><term>&unix-k;</term>
 <listitem><simpara>if &os; = Unix (in this case the &hw; is irrelevant!)
</simpara></listitem></varlistentry>
<varlistentry><term><constant>:CYGWIN</constant></term>
 <listitem><simpara>if &clisp; is using the &cygwin; &unix;
   compatibility layer on top of &win32;
   (in that case &unix-k; is also present)
</simpara></listitem></varlistentry></variablelist></para>

<para>Each &module; should add the appropriate keyword, e.g.,
 <link linkend="syscalls"><constant>:SYSCALLS</constant></link>,
 <link linkend="dir-key"><constant>:DIR-KEY</constant></link>,
 <link linkend="regexp"><constant>:REGEXP</constant></link>,
 <link linkend="pcre"><constant>:PCRE</constant></link>, etc.</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
 <link linkend="prompt">prompt</link> and the set of available commands.
 Commands must be typed literally, in any case,
 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>
 <row><entry><command>Quit</command></entry>
   <entry><command>:q</command></entry>
   <entry>quit to the top &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>Inspect</command></entry>
   <entry><command>:i</command></entry>
   <entry>inspect 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>Commands specific to &eval;/&apply;</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>EXT:SYSTEM-FUNCTION</classname>, a
   &foreign-function;, 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).</para>

<formalpara id="browser"><title>Function <function>EXT:CLHS</function></title>
<para>&hyperspec; access is provided via <literal
  role="sexp">(<function>EXT:CLHS</function> &symbol-r; &key-amp;
  &browser-k;)</literal> function, which uses your web browser.
  <replaceable>browser</replaceable> (defaults to &browser;) should be a
  valid keyword in the &browsers; &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>

<formalpara id="trace-indent"><title>Variable &trace-indent;</title>
<para>If you want the &trace; level to be indicated by the indentation
in addition to the printed numbers, set &trace-indent; to non-&nil;.
Initially it is &nil; since many nested traced calls will easily
exhaust the available line length.</para></formalpara>

</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-k; 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="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
 <firstterm><link linkend="gc"><function>EXT:GC</function></link>
  <indexterm id="gc-func" significance="preferred">
   <primary id="gc-func-i"><function>GC</function>
 </primary></indexterm></firstterm>
 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:
 <simplelist columns="1">
 <member>the real time ("wall" time),</member>
 <member>the run time (processor time for this process),</member>
 <member>the number of bytes allocated, and</member>
 <member>the number of &gc;ions performed, if any.</member>
</simplelist></para>

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

</section>

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

<para>The function &ed; calls the external editor specified by the value
 of <literal role="sexp">(&getenv; "EDITOR")</literal>
 or, failing that, the value of the variable
 <firstterm>&editor;</firstterm> (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 id="default-tz"><title>Default Time Zone</title>
<varlistentry><term>Platform dependent: unknown platforms only.</term>
 <listitem><simpara>The variable <firstterm>&default-tz;</firstterm>
   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-t;, but (as &float-t; or &rational-t; number)
 it should be a multiple of <literal>1/3600</literal>.</para>

<table id="internal-time-units-table" frame="all">
 <title>Time granularity</title>
 <tgroup cols="5" colsep="1" rowsep="1" align="center">
 <thead><row><entry>platform</entry>
        <entry>&unix;</entry><entry>&win32;</entry></row></thead><tbody>
 <row><entry>&internal-time-units-per-second;</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; platform only.</term>
 <listitem><simpara>The functions &short-site-name;, &long-site-name;
   should be defined in a site-specific &config-file; file.
   The default implementations try to read the value of the &env-var;
   <envar>ORGANIZATION</envar>, and, failing that, call &uname;.
</simpara></listitem></varlistentry>
<varlistentry><term>Platform dependent: &win32; platform only.</term>
 <listitem><simpara>The functions &short-site-name;, &long-site-name;
   should be defined in a site-specific &config-file; file.
   The default implementations try to read the registry.
</simpara></listitem></varlistentry>
<!-- #else -->
<varlistentry><term>Platform dependent: unknown 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>

<formalpara><title>Variable &apropos-do-more;</title>
<para>You can make &apropos; print more information about the symbols it
 found by setting &apropos-do-more; to a list containing some of
<constant>:FUNCTION</constant>, <constant>:VARIABLE</constant>,
&type-k;, and <constant>:CLASS</constant> or just set it to &t; to get
all of the values.</para></formalpara>

<formalpara><title>Variable &apropos-matcher;</title>
<para>You can make &apropos; and &apropos-list; be more flexible in
 their search by setting &apropos-matcher; to a &function-t; of one
 argument, a pattern (a &string-t;), returning a new &function-t; of one
 argument, a &symbol-t; name (also a &string-t;),
 which returns non-&nil; when the symbol name matches the pattern
 for the purposes of &apropos;.
 When &apropos-matcher; is &nil;, &search; is used.
 Some &module;s come with functions which can be used for
 &apropos-matcher;, e.g., &re-matcher;,
 <function>WILDCARD:WILDCARD-MATCHER</function>,
 <link linkend="pcre-matcher"><function>PCRE:PCRE-MATCHER</function></link>.
</para></formalpara>

</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>

<para>Dribbling is implemented via a kind (but &not-e; &recog-subt;) of
 &two-way-stream-t;, named &ds-t;.
 If you have a &source-r; &bidi-s; &x-r; and you want all transactions
 (input and output) on &x-r; to be copied to the &target-r; &out-s; &y-r;,
 you can do
 <programlisting id="dribble-example">
  (&defvar; *loggable* &x-r;)
  (&setq; &x-r; (&make-synonym-stream; '*loggable*))
  (&defun; toggle-logging (&optional-amp; s)
    (&multiple-value-bind; (so ta) (dribble-toggle *loggable* s)
      (&when; (&streamp; so) (&setq; *loggable* so))
      ta))
  (toggle-logging &y-r;)     ; start logging
  ...
  (toggle-logging)       ; finish logging
  ...
  (toggle-logging &y-r;)     ; restart logging
  ...
  (toggle-logging)       ; finish logging
  (&close; &y-r;)
 </programlisting></para>

<variablelist>
 <varlistentry id="drist"><term><literal role="sexp"
   >(<function>EXT:DRIBBLE-STREAM</function> &stream-r;)</literal></term>
  <listitem><simpara>When &stream-r; is a &ds-t;, returns two values:
    the &source-r; and the &target-r; streams.  Otherwise returns &nil;.
 </simpara></listitem></varlistentry>
 <varlistentry id="drist-p"><term><literal role="sexp"
   >(<function>EXT:DRIBBLE-STREAM-P</function> &stream-r;)</literal></term>
  <listitem><simpara>When &stream-r; is a &ds-t;, returns &t;, otherwise
    returns &nil;.</simpara></listitem></varlistentry>
 <varlistentry id="drist-so"><term><literal role="sexp"
   >(<function>EXT:DRIBBLE-STREAM-SOURCE</function>
     &stream-r;)</literal></term>
  <listitem><simpara>When &stream-r; is a &ds-t;, returns its
    &source-r; stream, otherwise signals a &type-error-t;.
 </simpara></listitem></varlistentry>
 <varlistentry id="drist-ta"><term><literal role="sexp"
   >(<function>EXT:DRIBBLE-STREAM-TARGET</function>
     &stream-r;)</literal></term>
  <listitem><simpara>When &stream-r; is a &ds-t;, returns its
    &target-r; stream, otherwise signals a &type-error-t;.
 </simpara></listitem></varlistentry>
  <varlistentry id="mk-drist"><term><literal role="sexp"
   >(<function>EXT:MAKE-DRIBBLE-STREAM</function>
     &source-r; &target-r;)</literal></term>
   <listitem><simpara>Create a new &ds-t;.
 </simpara></listitem></varlistentry>
 <varlistentry id="dri-toggle"><term><literal role="sexp"
   >(<function>EXT:DRIBBLE-TOGGLE</function> &stream-r;
     &optional-amp; &path-r;)</literal></term>
  <listitem><simpara>When &stream-r; is a &ds-t; and &path-r; is &nil;,
    writes a dribble termination note to the &stream-r;'s &target-r;
    &stream-t; and returns &stream-r;'s &source-r; and &target-r;
    &stream-t;s;
    when &stream-r; is not a &ds-t; and &path-r; is non-&nil;,
    creates a new &ds-t;, dribbling from &stream-r; to &path-r;,
    writes a dribble initialization note to &path-r;,
    and return the &ds-t; (the second value is the &target-r; &stream-t;);
    otherwise &warn; that no appropriate action may be taken.
    &path-r; may be an open &out-s; or a &path-des;.
    See <link linkend="dribble-example">above</link> for the sample usage.
    See also <filename>#P"src/dribble.lisp"</filename> in the &clisp;
    source tree.
</simpara></listitem></varlistentry></variablelist></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 id="argv"><title>Function <function>EXT:ARGV</function></title>
<para>This function will return a &fresh; &simple-vector-t; of
 &string-t; command line arguments passed to the runtime, including
 those already processed by &clisp;.
 Use &args; instead of this function to get the arguments for your program.
</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>
