# Introduction [CLHS-1]

## Special Symbols [CLHS-1.4.1.3]

The final delimiter of an interactive stream: On &unix;, the user has to type &ctrl;D at the beginning of a line. On &dos; or &win32;, the user has to type &ctrl;Z, followed by Return. This final delimiter is never actually seen by programs; no need to test for #\^D or #\^Z - 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.

A newline character can be entered by the user by pressing the Newline key or, on the numeric keypad, the Enter key.

## Error Terminology [CLHS-1.4.2]

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

## Class Precedence Lists [CLHS-1.4.4.5]

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

## Symbols in the Package &cl-pac; [CLHS-1.9]

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

- &call-method;
- &change-class;
- &define-method-combination;
- &ensure-generic-function;
- &invalid-method-error;
- &make-instances-obsolete;
- &make-method;
- &method-combination-error;
- &method-combination-class;
- &update-instance-for-different-class;
- &update-instance-for-redefined-class;

# Syntax [CLHS-2]

## Symbols as Tokens [CLHS-2.3.4]

A "reserved token", i.e., a token that has potential number syntax but cannot be interpreted as a number, is interpreted as symbol when being read.

When creating a symbol from a token, no character attributes are removed.

## Valid Patterns for Tokens [CLHS-2.3.5]

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 USER:: or :1 or LISP::4711 or 21:3 as symbols.

## Double-Quote [CLHS-2.4.5]

When a string is read, no character attributes are removed.

## Backquote [CLHS-2.4.6]

The backquote read macro also works when nested. Example:

       (&eval; ``(,#'(λ () ',a) ,#'(λ () ',b)))
     = (&eval; `(list #'(λ () ',a) #'(λ () ',b)))
     = (&eval; (list 'list (list 'function (list 'lambda nil (list 'quote a)))
                         (list 'function (list 'lambda nil (list 'quote b)))))

Multiple backquote combinations like `,,@` or `,@,@` are not implemented. Their use would be confusing anyway.

## Sharpsign [CLHS-2.4.8]

Reader macros are also defined for the following:

Additional reader macros

Macro | Meaning
--- | ---
#, | load-time evaluation
#Y | function objects and file &encoding;s
#"" | pathname

# Evaluation and Compilation [CLHS-3]

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

## Evaluation [CLHS-3.1]

### Introduction to Environments [CLHS-3.1.1]

&the-env;

As in Scheme, the macro `(&the-env;)` returns the current lexical environment. This works only in interpreted code and is not compilable!

`(EXT:EVAL-ENV &form-r; &optional-amp; &env-r;)`

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.

## Compilation [CLHS-3.2]

### Compiler Terminology [CLHS-3.2.1]

&clisp; compiles to platform-independent byte-code.

### Compiler Macros [CLHS-3.2.2.1]

Compiler macros are expanded in the compiled code only, and ignored by the interpreter.

### Definition of Similarity [CLHS-3.2.4.2.2]

Hash tables are externalizable objects.

## Declarations [CLHS-3.3]

The declarations `(&type-dec; &type-r; &var-r; ...)`, `(&ftype-dec; &type-r; &func-r; ...)`, `(&optimize-dec; (quality &value-r;) ...)` are ignored by the interpreter and the compiler.

The &ansi-cl; declaration `(&optimize-dec; (debug ...))` is legal.

The &ansi-cl; declaration `(&ignorable-dec; &var-r; ...)` affects the variable binding for the variable &var-r;. The compiler will not warn about the variable, regardless whether it is used or not.

### Additional declarations

The declaration `(compile)` has the effect that the current form is compiled prior to execution. Examples:

     (&locally; (&declare; (compile)) &form-r;)

executes a compiled version of form.

    (&let; ((x 0))
      (&flet; ((inc () (&declare; (compile)) (&incf; x))
             (dec () (&decf; x)))
        (&values; #'inc #'dec)))

returns two functions. The first is compiled and increments &x-r;, the second is interpreted (slower) and decrements the same &x-r;.

The type assertion `(&the; &val-type-r; &form-r;)` enforces a type check in interpreted code. No type check is done in compiled code. See also the ðe; macro.

## Lambda Lists [CLHS-3.4]

### Boa Lambda Lists [CLHS-3.4.6]

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

## The Evaluation and Compilation Dictionary [CLHS-3.8]

### Declaration &special-dec;

`(&proclaim; '(&special-dec; &var-r;))` declarations may not be undone. The same holds for &defvar;, &defparameter; and &defconstant; declarations.

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

Constants may not be bound dynamically or lexically.

### Macro &eval-when;

&eval-when; also accepts the situations `(not eval)` and `(not compile)`.

# Types and Classes [CLHS-4]

## Types [CLHS-4.2]

### Type Specifiers [CLHS-4.2.3]

The general form of the &complex-class; type specifier is `(&complex-class; type-of-real-part type-of-imaginary-part)`. The type specifier `(&complex-class; &type-r;)` is equivalent to `(&complex-class; &type-r; &type-r;)`.

The &ansi-cl; type specifier `(&real-class; low high)` denotes the real numbers between low and high.

&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.

`(`ext:type-expand` typespec &optional-amp; once-p)`

If typespec is a user-defined type, this will expand it recursively until it is no longer a user-defined type (unless once-p is supplied and non-&nil;). Two values are returned - the expansion and an indicator (&t; or &nil;) of whether the original typespec was a user-defined type.

The possible results of &type-of;

- &cons-class;

- &symbol-class;, &null-class;, &boolean-type;

- &fixnum-type;, &bignum-type;, &rational-class;, &short-float-type;, &single-float-type;, &double-float-type;, &long-float-type;, &complex-class;

- &character-class;, &base-char-type;

- `(&array-class; &eltype-r; &dimensions-r;)`, `(&simple-array-type; &eltype-r; &dimensions-r;)`

- `(&vector-class; &t; &size-r;)`, `(&simple-vector-type; &size-r;)`

- `(&string-class; &size-r;)`, `(&simple-string-type; &size-r;)`

- `(&base-string-type; &size-r;)`, `(&simple-base-string-type; &size-r;)`

- `(&bit-vector-class; &size-r;)`, `(&simple-bit-vector-type; &size-r;)`

- &function-class;, &compiled-function-type;

- &stream-class;, &file-stream-class;, &synonym-stream-class;, &broadcast-stream-class;, &concatenated-stream-class;, &two-way-stream-class;, &echo-stream-class;, &string-stream-class;

- &package-class;, &hash-table-class;, &readtable-class;, &pathname-class;, &logical-pathname-class;, &random-state-class;, &byte-t;

- special-operator, load-time-eval, &symbol-macro;, &encoding;, &foreign-pointer;, foreign-address, foreign-variable, foreign-function

- &weak-pointer;, read-label, frame-pointer, system-internal

- address (should not occur)

- any other symbol (structure types or &clos; classes)

- a class (&clos; classes without proper name)

## Classes [CLHS-4.3]

The &clos; symbols are &export;ed from the package &clos-pac;. &cl-pac; uses (as in &use-package;) &clos-pac; and &re-export;s all its exported symbols. Since the default &use-k; argument to &make-package; is &cl-pac; (see here), the &clos; symbols are normally visible in all user packages. If you do not want them (for example, if you want to use the PCL implementation of &clos; instead of the native one), do the following:

    (&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

.

## Deviations from &ansi-cl;

&defclass;

It is required that the superclasses of a class be defined before the &defclass; form for the class is evaluated.

&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;.

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.

There is a generic function `CLOS:NO-PRIMARY-METHOD` (similar to &no-applicable-method;) which is called when a generic function of the class &standard-generic-function-class; is invoked and no primary method on that generic function is applicable.

`clos:generic-flet` and `clos:generic-labels` are implemented as macros, not as special operators. They are not imported into the packages &clu-pac; and &cl-pac; because of the &ansi-cl; issue GENERIC-FLET-POORLY-DESIGNED:DELETE.

The function &ensure-generic-function; is not implemented.

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

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

&documentation; still has the &cltl1; implementation.

## Standard Metaclasses [CLHS-4.3.1.1]

Among those classes listed in Figure 4-8, only the following are instances of &built-in-class;:

- &t-class;

- &character-class;

- &number-class;, &complex-class;, &real-class;, &float-class;, &rational-class;, &ratio-class;, &integer-class;

- &sequence-class;

- &array-class;, &vector-class;, &bit-vector-class; &string-class;

- &list-class;, &cons-class;

- &symbol-class;, &null-class;

- &function-class;, &generic-function-class;, &standard-generic-function-class;

- &hash-table-class;

- &package-class;

- &pathname-class;, &logical-pathname-class;

- &random-state-class;

- &readtable-class;

- &stream-class;, &broadcast-stream-class;, &concatenated-stream-class;, &echo-stream-class;, &string-stream-class;, &file-stream-class;, &synonym-stream-class;, &two-way-stream-class;

## Defining Classes [CLHS-4.3.2]

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

## Redefining Classes [CLHS-4.3.6]

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

## Integrating Types and Classes [CLHS-4.3.7]

The class &method-combination-class; is not implemented.

## The Types and Classes Dictionary [CLHS-4.4]

### Function &coerce;

&fixnum-type; is not a character designator in &ansi-cl;, although &code-char; provides an obvious venue to &coerce; a &fixnum-type; to a &character-class;. When &fixnum-char-ansi; is &nil;, &clisp; &coerce;s &fixnum-type;s to &character-class;s via &code-char;. When &fixnum-char-ansi; is non-&nil;, &fixnum-type;s cannot be &coerce;d to &character-class;s.

# Data and Control Flow [CLHS-5]

## The Data and Control Flow Dictionary [CLHS-5.3]

&destructuring-bind;

does not perform full error checking.

&prog1;, &prog2;, ∧, ∨, &psetq;, &when;, &unless;, &cond;, &case;, &multiple-value-list;, &multiple-value-bind;, &multiple-value-setq;

are implemented as special operators and, as such, are rather efficient.

### Macro `EXT:FCASE`

This macro allows specifying the test for &case;, e.g.,

    (fcase string= (subseq foo 0 (position #\Space foo))
      ("first" 1)
      (("second" "two") 2)
      (("true" "yes") t)
      (otherwise nil))

is the same as

    (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)))

### Function &eq;

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

`(let ((x y)) (eq x x))` always returns &t;, regardless of &y-r;.

### Function &symbol-function;

`(&setf; (&symbol-function; &symbol-r;) &object-r;)` requires &object-r; to be either a function, a &symbol-function; return value or a &lambda-expr;. The &lambda-expr; is thereby immediately converted to a &function-class;.

### Macro &setf;

Additional places:

&funcall;

  `(&setf; (&funcall; #'&symbol-r; ...) &object-r;)` and `(&setf; (&funcall; '&symbol-r; ...) &object-r;)` are equivalent to `(&setf; (&symbol-r; ...) &object-r;)`.

&progn;

  `(&setf; (&progn; &form-r; ... &place-r;) &object-r;)`

&locally;

  `(&setf; (&locally; &declaration-r; ... &form-r; ... &place-r;) &object-r;)`

&if;

  `(&setf; (&if; condition place1 place2) &object-r;)`

&get-dispatch-macro-character;

  `(&setf; (&get-dispatch-macro-character; ...) ...)` calls &set-dispatch-macro-character;.

&lfd;:

  `(&setf; (&lfd;) &digits-r;)` sets the default mantissa length of long floats to &digits-r; bits.

&values-list;

  `(&setf; (&values-list; list) &form-r;)` is equivalent to `(&values-list; (&setf; list (&multiple-value-list; &form-r;)))`

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

`(&get-setf-expansion; &form-r; &optional-amp; &env-r;)`, `(EXT:GET-SETF-METHOD &form-r; &optional-amp; &env-r;)`, and `(EXT:GET-SETF-METHOD-MULTIPLE-VALUE &form-r; &optional-amp; &env-r;)` receive as optional argument &env-r; the environment necessary for macro expansions. In &define-setf-expander; and `EXT:DEFINE-SETF-METHOD` &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;, `EXT:GET-SETF-METHOD` and `EXT:GET-SETF-METHOD-MULTIPLE-VALUE`. If this is done, even local macros will be interpreted as places correctly.

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

See also the &letf; and &letf-star; macros.

### Special Operator &function;

`(&function; &symbol-r;)` returns the local function definition established by &flet; or &labels;, if it exists, otherwise the global function definition.

`(&special-operator-p; &symbol-r;)` returns &nil; or &t;. If it returns &t;, then `(&symbol-function; &symbol-r;)` returns the (useless) special operator handler.

### Macro &define-symbol-macro;

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): `(&define-symbol-macro; &symbol-r; expansion)`.

The function `EXT:SYMBOL-MACRO-EXPAND` tests for a &symbol-macro;: If &symbol-r; is defined as a &symbol-macro;, `(EXT:SYMBOL-MACRO-EXPAND &symbol-r;)` returns two values, &t; and the expansion, otherwise it returns &nil;.

Calling &boundp; on a symbol defined as a &symbol-macro; returns &t;.

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.

Calling &makunbound; on a symbol defined as a &symbol-macro; removes the &symbol-macro; definition.

### Macro λ

&lambda-list-keywords;

`(&optional-amp; &rest-amp; &key-amp; &allow-other-keys-amp; &aux-amp; &body-amp; &whole-amp; &environment-amp;)`

Platform dependent

&cpu-type-header;
&call-arguments-limit; | 216=65536 | 232=4294967296
&multiple-values-limit; | 27=128
&lambda-parameters-limit; | 216=65536 | 232=4294967296

### Macros &defun; & &defmacro;

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

    (let ((gensym-prefix "G")
          (gensym-count 1))
      (defun gensym (&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))))

# Iteration [CLHS-6]

No notes.

# Objects [CLHS-7]

Changing the class of a given instance is not supported. The functions &change-class;, &update-instance-for-different-class;, &make-instances-obsolete; are not implemented.

Only the &standard; method combination is implemented.

User-defined method combination is not supported. The macros &define-method-combination;, &call-method; and the functions &invalid-method-error;, &method-combination-error; are not implemented.

# Structures [CLHS-8]

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

- The value of &print-escape-var; must be respected.

- The value of &print-pretty-var; should not and cannot be respected, since the pretty-print mechanism is not accessible from outside.

- The value of &print-circle-var; need not be respected. This is managed by the system. (But the print-circle mechanism handles only those objects that are (direct or indirect) components of structure.)

- 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 > 1. (The print-level mechanism does not recognize how many parentheses you have output. It only counts how many times it was called recursively.)

- The value of &print-length-var; must be respected, especially if you are outputting an arbitrary number of components.

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

- 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;.

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

# Conditions [CLHS-9]

When an error occurred, you are in a break loop. You can evaluate forms as usual. The `help` command (or help key if there is one) lists the available debugging commands.

`EXT:MUFFLE-CERRORS`

The macro `(`EXT:MUFFLE-CERRORS` {&form-r;}*)` executes the &form-r;s. When a continuable error occurs, no message is printed. Instead, the &continue; restart is invoked.

`EXT:APPEASE-CERRORS`

The macro `(`EXT:APPEASE-CERRORS` {&form-r;}*)` executes the &form-r;s. When a continuable error occurs, the error is printed as a warning and the &continue; restart is invoked.

`EXT:EXIT-ON-ERROR`

The macro `(`EXT:EXIT-ON-ERROR` {&form-r;}*)` executes the &form-r;s. When a non-continuable error or a &ctrl;C interrupt occurs, the error is printed and &clisp; terminates with an error status.

`EXT:WITH-RESTARTS`

The macro `EXT: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 to any condition. `(`EXT:WITH-RESTARTS` ({`restart-clause`}*) {&form-r;}*)` is therefore equivalent to `(&restart-case; (&progn; {&form-r;}*) {`restart-clause`}*)`.

## Embedded Newlines in Condition Reports [CLHS-9.1.3.1.3]

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

## The Conditions Dictionary [CLHS-9.2.]

&restart-case;

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

`(&restart-case; &form-r; {`restart-clause`}*)`

`restart-clause` ::==

         (restart-name arglist
          {keyword-value}* {&form-r;}*) |
         (restart-name {keyword-value}*
          arglist {&form-r;}*)

&compute-restarts;

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

# Symbols [CLHS-10]

No notes.

# Packages [CLHS-11]

The &ansi-cl; packages present in &clisp;

&cl-pac;

  with the nicknames `"CL"` and `"LISP"`

&clu-pac;

  with the nicknames `"CL-USER"` and `"USER"`

&kwd-pac;

  with the nickname `""`

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

## Constraints on the COMMON-LISP Package for Conforming Programs - package locking [CLHS-11.1.2.1.2]

&package-lock;

Packages can be locked. When a package is locked, attempts to change its symbol table or redefine functions which its symbols name result in a continuable error (continuing overrides locking for this operation). Function `(&package-lock; package)` returns the generalized boolean indicating whether the package is locked. A package (or list thereof) can be locked using `(&setf; (&package-lock; package-or-list) &t;)`. &clisp; locks its system packages (specified in the variable &sys-pack-list;). If you want to evaluate some forms with certain packages unlocked, you can use `EXT:WITHOUT-PACKAGE-LOCK`:

    (without-package-lock ("LISP" "EXT" "CLOS")
      (defun restart () ...))

`(without-package-lock () ...)` unlocks all packages in &sys-pack-list;.

## The COMMON-LISP-USER Package [CLHS-11.1.2.2]

The &clu-pac; package uses the &cl-pac; and &ext-pac; packages.

## Implementation-Defined Packages [CLHS-11.1.2.4]

The following additional packages exist:

Implementation-Defined Packages

&clos-pac;

  &export;s all &clos; specific symbols, including some additional symbols.

&sys-pac;

  has the nicknames SYS and COMPILER, and has no &export;ed symbols. It defines many system internals.

EXT

  is the umbrella package for all extensions: it imports and &re-export;s all the external symbols in all &clisp; extensions, so a simple `(&use-package; "EXT")` 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;.

&charset-pac;

  defines and &export;s some character sets, for use with &make-encoding; and as &extfmt; argument.

&ffi-pac;

  implements the foreign function interface. Some platforms only.

&screen-pac;

  defines an API for random screen access. Some platforms only.

All pre-existing packages except &clu-pac; belong to the implementation, in the sense that the programs that do not follow Section 11.1.2.1.2 Constraints on the COMMON-LISP Package for Conforming Programs cause undefined behavior.

## The Packages Dictionary [CLHS-11.2.]

### Function &make-package;

For &make-package;, the default value of the &use-k; argument is `(&cl-pac;)`.

&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 `(&readtable-case; &readtable-var;)`, though.

#### Function &re-export;

The function `(&re-export; FROM-PACK TO-PACK)` re-exports all external symbols from FROM-PACK also from TO-PACK, provided it already uses FROM-PACK; and signals an error otherwise.

# Numbers [CLHS-12]

## Numeric Types

The type &number-class; is the disjoint union of the types &real-class; and &complex-class; (exhaustive partition)

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

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

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

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

## Number Concepts [CLHS-12.1]

### Byte Operations on Integers [CLHS-12.1.1.3.2]

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

### Rule of Float Substitutability [CLHS-12.1.3.3]

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

### Floating-point Computations [CLHS-12.1.4]

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

floating point types

type | sign | mantissa | exponent | comment
--- | --- | --- | --- | ---
&short-float-type; | 1 bit | 16+1 bits | 8 bits | immediate
&single-float-type; | 1 bit | 23+1 bits | 8 bits | IEEE format
&double-float-type; | 1 bit | 52+1 bits | 11 bits | IEEE format
&long-float-type; | 1 bit | >=64 bits | 32 bits | variable length

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

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 `(&setf; (&lfd;) &n-r;)`, where &n-r; is a positive integer. E.g., `(&setf; (&lfd;) 3322)` sets the default precision of long floats to 1000 decimal digits.

#### Rule of Float Precision Contagion [CLHS-12.1.4.4]

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

Rationale:

  See it pragmatically: save what you can and let others worry about the rest.

Brief:

  &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.

Detailed:

  A float is an approximation of a real number. One can think of it as a random variable with the mean equal to itself and standard deviation equal to half the last significant digit. E.g., `1.5` is actually `1.5+-0.05`. Consider adding `1.5` and `1.75`. &ansi-cl; requires that `(+ 1.5 1.75)` return `3.25`, while traditional &clisp; would return `3.3`. The implied random variables are: `3.25+-0.005` and `3.3+-0.05`. Note that the traditional &clisp; way does lie about the mean: the mean is `3.25` and nothing else, while the standard way could be lying about the deviation (accuracy): if the implied accuracy of `1.5 (0.05)` 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.

Experience:

  Rounding errors accumulate, and if a computation is conducted with insufficient precision, an outright incorrect result can be returned. (E.g., `E(x2) - E(x)2` 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.

When &flocont; is &nil;, the traditional &clisp; method is used, namely the result of an arithmetic operation whose arguments are of different float types is rounded to the float format of the shortest (least precise) of the arguments: &rational-class; → &long-float-type; → &double-float-type; → &single-float-type; → &short-float-type; (in contrast to 12.1.4.4 Rule of Float Precision Contagion!)

Rationale:

  See it mathematically. Add intervals: `{1.0 ± 1e-8} + {1.0 ± 1e-16} = {2.0 ± 1e-8}`. So, if we add `1.0s0` and `1.0d0`, we should get `2.0s0`.

Brief:

  Do not suggest accuracy of a result by giving it a precision that is greater than its accuracy.

Example:

  `(- (+ 1.7 π) π)` should not return `1.700000726342836417234L0`, it should return `1.7f0` (or `1.700001f0` if there were rounding errors).

Experience:

  If in a computation using thousands of short floats, a long float (like π) happens to be used, the long precision should not propagate throughout all the intermediate values. Otherwise, the long result would look precise, but its accuracy is only that of a short float; furthermore much computation time would be lost by calculating with long floats when only short floats would be needed.

&warn-fpc;

If the variable &warn-fpc; is non-&nil;, a warning is emitted for every coercion involving different floating-point types.

### Complex Computations [CLHS-12.1.5]

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

The type specifier for this is `(&complex-class; &integer-class; &single-float-type;)`, and `(&complex-class; `type-of-real-part` `type-of-imaginary-part`)` in general.

The type specifier `(&complex-class; &type-r;)` is equivalent to `(&complex-class; &type-r; &type-r;)`.

### Rule of Canonical Representation for Complex Rationals [CLHS-12.1.5.3]

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

This has the advantage that `(let ((x (sqrt -9.0))) (* x x))` - instead of evaluating to `#C(-9.0 0.0)`, with &x-r; = `#C(0.0 3.0)` - evaluates to `#C(-9.0 0)` = `-9.0`, with &x-r; = `#C(0 3.0)`.

## The Numbers Dictionary [CLHS-12.2]

&upgraded-complex-part-type;

&upgraded-complex-part-type; always returns &t;, since a &complex-class; number in &clisp; can always have ℜ and ℑ of any type.

&default-float-format;

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;.

&no-underflow;

The macro `(&no-underflow; {&form-r;}*)` executes the &form-r;s, with errors of type &floating-point-underflow-type; inhibited. Floating point operations will silently return zero instead of signalling an error of type &floating-point-underflow-type;.

### Additional Integer Functions

`ext:!`

`(`ext:!` &n-r;)` returns the factorial of &n-r;, &n-r; being a nonnegative &integer-class;.

`ext:exquo`

`(`ext:exquo` &x-r; &y-r;)` returns the integer quotient `x/y` of two integers &x-r;,&y-r;, and signals an error when the quotient is not integer. (This is more efficient than &slash;.)

`ext:xgcd`

`(`ext:xgcd` &x1-r; ... &xn-r;)` 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

     &l-r; = (&gcd; &x1-r; ... &xn-r;)
       = (+ (* &k1-r; &x1-r;) ... (* &kn-r; &xn-r;))

### Floating Point

&expt;

`(&expt; &base-r; exponent)` is not very precise if exponent has a large absolute value.

&log;

`(&log; &number-r; &base-r;)` signals an error if `&base-r; = 1`.

π

The value of π is a &long-float-type; with the precision given by &lfd-l;. When this precision is changed, the value of π is automatically recomputed. Therefore π is a variable, not a constant.

### Float Decoding [CLHS]

&float-radix; always returns `2`.

`(&float-digits; &number-r; &digits-r;)` coerces &number-r; (a real number) to a floating point number with at least &digits-r; mantissa digits. The following holds:

     (>= (&float-digits; (&float-digits; &number-r; &digits-r;)) &digits-r;)

### Boolean Operations [CLHS]

Boolean Operations

constant | value
--- | ---
&boole-clr; | 0
&boole-set; | 15
&boole-1; | 10
&boole-2; | 12
&boole-c1; | 5
&boole-c2; | 3
&boole-and; | 8
&boole-ior; | 14
&boole-xor; | 6
&boole-eqv; | 9
&boole-nand; | 7
&boole-nor; | 1
&boole-andc1; | 4
&boole-andc2; | 2
&boole-orc1; | 13
&boole-orc2; | 11

### Fixnum Limits [CLHS]

Platform dependent

&cpu-type-header;
&most-positive-fixnum; | 224-1 = 16777215 | 232-1 = 4294967295
&most-negative-fixnum; | -224 = -16777216 | -232 = -4294967296

### Float Limits [CLHS]

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

### Condition &floating-point-invalid-operation-type;

This condition is never signaled by &clisp;.

### Condition &floating-point-inexact-type;

This condition is never signaled by &clisp;.

# Characters [CLHS-13]

The characters are ordered according to a superset of the ASCII encoding.

Platform dependent: only in &clisp; built &with; the compile-time flag &unicode;.

  More precisely, &clisp; uses the 16-bit &unicode; character set (ISO 10646, also known as UCS-2).

Platform dependent: &dos;, &os2; platforms only, and only in &clisp; built &without; compile-time flag &unicode;.

  More precisely, &clisp; uses the IBM PC character set (code page 437):

  the IBM PC character set (code page 437)

  &char-table-header;
  #x00&cc; |  |  |  |  |  | &cc;&cc;&cc;&cc;&cc;&cc;&cc; | ¶ | §
  #x10 |  |  |  |  |  |  |  |  |  | &cc;&cc; |  |  |  |
  &ascii-printable;
  #x80 | Ç | ü | é | â | ä | à | å | ç | ê | ë | è | ï | î | ì | Ä | Å
  #x90 | É | æ | Æ | ô | ö | ò | û | ù | ÿ | Ö | Ü | ¢ | £ | ¥ | ₧ | ƒ
  #xA0 | á | í | ó | ú | ñ | Ñ | ª | º | ¿ | ⌐ | ¬ | ½ | ¼ | ¡ | « | »
  #xB0 | ░ | ▒ | ▓ | │ | ┤ | ╡ | ╢ | ╖ | ╕ | ╣ | ║ | ╗ | ╝ | ╜ | ╛ | ┐
  #xC0 | └ | ┴ | ┬ | ├ | ─ | ┼ | ╞ | ╟ | ╚ | ╔ | ╩ | ╦ | ╠ | ═ | ╬ | ╧
  #xD0 | ╨ | ╤ | ╥ | ╙ | ╘ | ╒ | ╓ | ╛ | ╚ | ┘ | ┌ | █ | ▄ | ▌ | ▐ | ▀
  #xE0 | α | ß | Γ | π | Σ | σ | µ | τ | Φ | Θ | Ω | δ | ∞ | &phgr; | ε | ∩
  #xF0 | ≡ | ± | ≥ | ≤ | ⌠ | ⌡ | ÷ | ≈ | ° | ∙ | · | √ | ⁿ | ² | ■ |

  &char-table-legend;

Platform dependent: &unix; (except &nextstep;), &win32;, &amiga;, &acorn; platforms only, and only in &clisp; built &without; compile-time flag &unicode;.

  More precisely, &clisp; uses the ISO Latin-1 (ISO 8859-1) character set:

  the ISO Latin-1 (ISO 8859-1) character set

  &char-table-header;
  #x00&cc;&cc;&cc;&cc;&cc;&cc;&cc;&cc;&cc;&cc;&cc; &cc;&cc;&cc;&cc;&cc;
  #x10&cc;&cc;&cc;&cc;&cc;&cc;&cc;&cc;&cc;&cc;&cc; &cc;&cc;&cc;&cc;&cc;
  &ascii-printable;
  #x80 |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
  #x90 |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
  #xA0 |  | ¡ | ¢ | £ | ¤ | ¥ | ¦ | § | ¨ | © | ª | « | ¬ |  | ® | ¯
  #xB0 | ° | ± | ² | ³ | ´ | µ | ¶ | · | ¸ | ¹ | º | » | ¼ | ½ | ¾ | ¿
  #xC0 | À | Á | Â | Ã | Ä | Å | Æ | Ç | È | É | Ê | Ë | Ì | Í | Î | Ï
  #xD0 | Ð | Ñ | Ò | Ó | Ô | Õ | Ö | × | Ø | Ù | Ú | Û | Ü | Ý | Þ | ß
  #xE0 | à | á | â | ã | ä | å | æ | ç | è | é | ê | ë | ì | í | î | ï
  #xF0 | ð | ñ | ò | ó | ô | õ | ö | ÷ | ø | ù | ú | û | ü | ý | þ | ÿ

  &char-table-legend;

Platform dependent: &nextstep; platforms only, and only in &clisp; built &without; compile-time flag &unicode;.

  More precisely, &clisp; uses the &nextstep; character set:

  the &nextstep; character set

  &char-table-header;
  #x00&cc;&cc;&cc;&cc;&cc;&cc;&cc;&cc;&cc;&cc;&cc; &cc;&cc;&cc;&cc;&cc;
  #x10&cc;&cc;&cc;&cc;&cc;&cc;&cc;&cc;&cc;&cc;&cc; &cc;&cc;&cc;&cc;&cc;
  &ascii-printable;
  #x80 |  | À | Á | Â | Ã | Ä | Å | Ç | È | É | Ê | Ë | Ì | Í | Î | Ï
  #x90 | Ð | Ñ | Ò | Ó | Ô | Õ | Ö | Ù | Ú | Û | Ü | Ý | Þ | µ | × | ÷
  #xA0 | © | ¡ | ¢ | £ | ⁄ | ¥ | ƒ | § | ¤ | ’ | “ | « | ‹ | › | ﬁ | ﬂ
  #xB0 | ® | – | † | ‡ | · | ¦ | ¶ | • | ‚ | „ | ” | » | … | ‰ | ¬ | ¿
  #xC0 | ¹ | ˋ | ´ | ˆ | ˜ | ¯ | ˘ | ˙ | ¨ | ² | ˚ | ¸ | ³ | ˝ | ˛ | ˇ
  #xD0 | — | ± | ¼ | ½ | ¾ | à | á | â | ã | ä | å | ç | è | é | ê | ë
  #xE0 | ì | Æ | í | ª | î | ï | ð | ñ | Ł | Ø | Œ | º | ò | ó | ô | õ
  #xF0 | ö | æ | ù | ú | û | ı | ü | ý | ł | ø | œ | ß | þ | ÿ |  |

  &char-table-legend;

The following are standard characters:

&char-code-header;
#\Space | #x20
&nl-c; | #x0A

The following are semi-standard characters:

&char-code-header;
#\Backspace | #x08
#\Tab | #x09
#\Linefeed | #x0A
#\Page | #x0C
&ret-c; | #x0D

&nl-c; is the &line-term;.

Additional Named Characters

&char-code-header;
#\Null | #x00
#\Bell | #x07
#\Escape | #x1B

Additional syntax for characters with code from #x00 to #x1F:

&char-code-header;
#\^@ | #x00
#\^A … #\^Z | #x01 … #x1A
#\^[ | #x1B
#\^\ | #x1C
#\^] | #x1D
#\^^ | #x1E
#\^_ | #x1F

See also the section Character I/O.

## Attributes

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

`ext:char-font-limit` = 16

  The system uses only font 0.

`ext:char-bits-limit` = 16

  The following bits are defined:

  &key-value-header;
  &control-k; | &ch-ctrl;
  &meta-k; | &ch-meta;
  &super-k; | &ch-super;
  &hyper-k; | &ch-hyper;

`(`ext:char-font` &object-r;)`

  returns the font of a &character-class; or &input-char;.

`(`ext:char-bits` &object-r;)`

  returns the bits of a &character-class; or &input-char;.

`(`ext:make-char` &ch-r; [bits [font]])`

  returns a new &input-char;, or &nil; if such a character cannot be created.

`(`ext:char-bit` &object-r; &name-r;)`

  returns &t; if the named bit is set in &object-r;, else &nil;.

`(`ext:set-char-bit` &object-r; &name-r; newvalue)`

  returns a new &input-char; with the named bit set or unset, depending on the boolean newvalue.

Platform dependent: &unix;, &dos;, &os2;, &win32;, &acorn; platforms only.

  The system itself uses this &input-char; type only to mention special keys and &ctrl;/&alt;/&shift; key status on return from `(&read-char; &kbd-in;)`.

## Character Scripts [CLHS-13.1.2.1]

The only defined character script is the type &character-class; itself.

## Character Attributes [CLHS-13.1.3]

Characters have no implementation-defined attributes. All characters are simple characters.

## Graphic Characters [CLHS-13.1.4.1]

The graphic characters are those &unicode; characters which are defined by the &unicode; standard, excluding the ranges U0000 … U001F and U007F … U009F.

## Alphabetic Characters [CLHS-13.1.4.2]

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

## Case of Implementation-Defined Characters [CLHS-13.1.4.3.4]

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:

- &uc-r; and &lc-r; are different

- &c-r; is one of &uc-r; and &lc-r;

- the upper case mapping of &uc-r; and of &lc-r; is &uc-r;

- the lower case mapping of &uc-r; and of &lc-r; is &lc-r;

The titlecase property of &unicode; characters has no equivalent in &cl;.

## Numeric Characters [CLHS-13.1.4.4]

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

## Ordering of Characters [CLHS-13.1.6]

The characters are ordered according to their &unicode; code.

## Treatment of Newline during Input and Output [CLHS-13.1.8]

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:

Platform dependent: &dos;, &os2;, &win32; platforms only.

  When writing to a file, &nl-c; is converted to &cr-c;/&lf-c;. (This is the usual convention on &dos;.) For example, &ret-c;+&nl-c; is written as &cr-c;/&cr-c;/&lf-c;.

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

## Character Encodings [CLHS-13.1.9]

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

## Documentation of Implementation-Defined Scripts [CLHS-13.1.10]

See the description of &encoding;s.

## The Characters Dictionary [CLHS-13.2]

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

Platform dependent

binaries built | &without; &unicode; support | &with; &unicode; support
--- | --- | ---
&char-code-limit; | 28 = 256 | 216 = 65536

The types ext:string-char and &base-char-type; are equivalent to &character-class;.

The graphic characters have been described above.

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

The alphabetic characters are these characters:

                 ABCDEFGHIJKLMNOPQRSTUVWXYZ
                 abcdefghijklmnopqrstuvwxyz

and the international alphabetic characters from the character set:

                 ÇüéâäàåçêëèïîìÄÅÉæÆôöòûùÿÖÜßáíóúñÑªºãõØøÀÃÕ etc.

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.

## Functions on characters

`(&char-width; &ch-r;)`

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;.

## platform-dependent characters

The characters that are not graphic chars and the space character have names:

Platform dependent: &amiga; platforms only.

&code-char-header;
`(&code-char; #x00)` | #\Null
`(&code-char; #x01)` | #\Code1
`(&code-char; #x02)` | #\Code2
`(&code-char; #x03)` | #\Code3
`(&code-char; #x04)` | #\Code4
`(&code-char; #x05)` | #\Code5
`(&code-char; #x06)` | #\Code6
`(&code-char; #x07)` | #\Bell | #\Bel
`(&code-char; #x08)` | #\Backspace | #\Bs
`(&code-char; #x09)` | #\Tab | #\Ht
`(&code-char; #x0A)` | &nl-c; | #\Linefeed | #\Lf
`(&code-char; #x0B)` | #\Vt
`(&code-char; #x0C)` | #\Page | #\Ff
`(&code-char; #x0D)` | &ret-c; | #\Cr
`(&code-char; #x0E)` | #\So
`(&code-char; #x0F)` | #\Si
`(&code-char; #x10)` | #\Code16
`(&code-char; #x11)` | #\Code17
`(&code-char; #x12)` | #\Code18
`(&code-char; #x13)` | #\Code19
`(&code-char; #x14)` | #\Code20
`(&code-char; #x15)` | #\Code21
`(&code-char; #x16)` | #\Code22
`(&code-char; #x17)` | #\Code23
`(&code-char; #x18)` | #\Code24
`(&code-char; #x19)` | #\Code25
`(&code-char; #x1A)` | #\Code26
`(&code-char; #x1B)` | #\Escape | #\Esc
`(&code-char; #x1C)` | #\Code28
`(&code-char; #x1D)` | #\Code29
`(&code-char; #x1E)` | #\Code30
`(&code-char; #x1F)` | #\Code31
`(&code-char; #x20)` | #\Space
`(&code-char; #x7F)` | #\Rubout
`(&code-char; #x9B)` | #\Csi

Platform dependent: &dos;, &os2;, &win32; platforms only.

&code-char-header;
`(&code-char; #x00)` | #\Null
`(&code-char; #x07)` | #\Bell
`(&code-char; #x08)` | #\Backspace | #\Rubout
`(&code-char; #x09)` | #\Tab
`(&code-char; #x0A)` | &nl-c; | #\Linefeed
`(&code-char; #x0B)` | #\Code11
`(&code-char; #x0C)` | #\Page
`(&code-char; #x0D)` | &ret-c;
`(&code-char; #x1A)` | #\Code26
`(&code-char; #x1B)` | #\Escape
`(&code-char; #x20)` | #\Space

Platform dependent: &unix;, &acorn;, platforms only.

&code-char-header;
`(&code-char; #x00)` | #\Null | #\Nul
`(&code-char; #x01)` | #\Soh
`(&code-char; #x02)` | #\Stx
`(&code-char; #x03)` | #\Etx
`(&code-char; #x04)` | #\Eot
`(&code-char; #x05)` | #\Enq
`(&code-char; #x06)` | #\Ack
`(&code-char; #x07)` | #\Bell | #\Bel
`(&code-char; #x08)` | #\Backspace | #\Bs
`(&code-char; #x09)` | #\Tab | #\Ht
`(&code-char; #x0A)` | &nl-c; | #\Nl | #\Linefeed
`(&code-char; #x0B)` | #\Vt
`(&code-char; #x0C)` | #\Page | #\Np
`(&code-char; #x0D)` | &ret-c; | #\Cr
`(&code-char; #x0E)` | #\So
`(&code-char; #x0F)` | #\Si
`(&code-char; #x10)` | #\Dle
`(&code-char; #x11)` | #\Dc1
`(&code-char; #x12)` | #\Dc2
`(&code-char; #x13)` | #\Dc3
`(&code-char; #x14)` | #\Dc4
`(&code-char; #x15)` | #\Nak
`(&code-char; #x16)` | #\Syn
`(&code-char; #x17)` | #\Etb
`(&code-char; #x18)` | #\Can
`(&code-char; #x19)` | #\Em
`(&code-char; #x1A)` | #\Sub
`(&code-char; #x1B)` | #\Escape | #\Esc
`(&code-char; #x1C)` | #\Fs
`(&code-char; #x1D)` | #\Gs
`(&code-char; #x1E)` | #\Rs
`(&code-char; #x1F)` | #\Us
`(&code-char; #x20)` | #\Space | #\Sp
`(&code-char; #x7F)` | #\Rubout | #\Delete | #\Del

## Obsolete Constants

obsolete constants

constant | value
--- | ---
&ch-ctrl; | 1
&ch-meta; | 2
&ch-super; | 4
&ch-hyper; | 8

# Conses [CLHS-14]

## The Conses Dictionary [CLHS-14.2]

### Functions &mapcar;, &mapcan;, &maplist;, &mapcon;, ...

#### Function &mapcap;

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

`(&mapcap; &func-r; &x1-r; ... &xn-r;)` == `(&apply; #'&append; (&mapcar; &func-r; &x1-r; ... &xn-r;))`

(Actually a bit more efficient that this would have been.)

#### Function &maplap;

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

`(&maplap; &func-r; &x1-r; ... &xn-r;)` == `(&apply; #'&append; (&maplist; &func-r; &x1-r; ... &xn-r;))`

(Actually a bit more efficient that this would have been.)

# Arrays [CLHS-15]

&make-array;

&make-array; can return specialized arrays for the &array-element-type;s `(&unsigned-byte-type; 2)`, `(&unsigned-byte-type; 4)`, &unsigned-byte-8;, &unsigned-byte-16;, &unsigned-byte-32;, and, of course, &bit-type; and &character-class;.

## Array Elements [CLHS-15.1.1]

Platform dependent

&cpu-type-header;
&array-rank-limit; | 216 = 65536 | 232 = 4294967296
&array-dimension-limit; | 224 = 16777216 | 232 = 4294967296
&array-total-size-limit; | 224 = 16777216 | 232 = 4294967296

Note that these constants are not fixnums, contrary to the &ansi-cl; Issue ARRAY-DIMENSION-LIMIT-IMPLICATIONS:ALL-FIXNUM.

## The Arrays Dictionary [CLHS-15.2]

&adjust-array; for displaced arrays

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!

# Strings [CLHS-16]

String comparison is based on the function &char-leq;. Therefore diphthongs do not obey the usual national rules. Example: `o` < `oe` < `z` < `ö`.

## The Strings Dictionary [CLHS-16.2]

### Functions on strings

`(&string-width; &string-r;)`

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.

# Sequences [CLHS-17]

## The Sequences Dictionary [CLHS-17.3.]

### Additional Macros

#### Macro &doseq;

For iteration through a sequence, a macro &doseq;, similar to &dolist;, may be used instead of ↦:

    (&doseq; (&var-r; seqform [resultform])
      {&declaration-r;}*
      {&tag-r;|&form-r;}*)

&doseq; forms are &iter-forms;.

### Functions &nreverse; & &nreconc;

&nreverse;

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

&nreconc;

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.

### Functions &remove; & &delete;

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

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

&count-ansi;

Contrary to the &ansi-cl; issue 283 RANGE-OF-COUNT-KEYWORD:NIL-OR-INTEGER, negative &count-k; keyword arguments are not allowed unless you set &count-ansi; to a non-&nil; value, in hich case using a negative integer value is functionally equivalent to using a value of zero, as per the &ansi-cl; issue.

### Functions &sort; & &stable-sort;

&sort; and &stable-sort; have two additional keywords &start-k; and &end-k;:

    (&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;)

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

# Hash Tables [CLHS-18]

## The Hash Tables Dictionary [CLHS-18.2.]

### Function &make-hash-table;

&make-hash-table; supports additional keywords `:initial-contents` and `:weak`:

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

The `:initial-contents` argument is an &alist; that is used to initialize the new hash table. The `:rehash-threshold` argument is ignored.

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

The &setf;able predicate `EXT:HASH-TABLE-WEAK-P` checks whether the &hash-table-class; is weak.

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

### Additional Macros

#### Macro &dohash;

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

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

&dohash; forms are &iter-forms;.

# Filenames [CLHS-19]

For most operations, pathnames denoting files and pathnames denoting directories cannot be used interchangeably.

Platform dependent: &unix;, &amiga; platforms only.

  For example, `#p"FOO/BAR"` denotes the file `BAR` in the directory `FOO`, while `#p"FOO/BAR/"` denotes the subdirectory `BAR` of the directory `FOO`.

Platform dependent: &dos;, &os2;, &win32; platforms only.

  For example, `#p"FOO\\BAR"` denotes the file `BAR` in the directory `FOO`, while `#p"FOO\\BAR\\"` denotes the subdirectory `BAR` of the directory `FOO`.

Platform dependent: &acorn; platforms only.

  For example, `#p"FOO.BAR"` denotes the file `FOO` in the directory `BAR`, while `#p"FOO.BAR."` denotes the subdirectory `BAR` of the directory `FOO`.

This is especially important for the functions `directory`, `ext:dir`, `ext:cd`, `ext:make-dir`, `ext:delete-dir`.

The minimum filename syntax that may be used portably

pathname | meaning
--- | ---
`xxx` | for a file with name xxx
`xxx.yy` | for a file with name xxx and type yy
`.yy` | for a pathname with type yy and no name specified

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

## Pathname Components [CLHS-19.2.1]

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.

Platform dependent: &amiga; platforms only.
  &path-comps;
  &host-r;
  &always-nil;
  &device-r;
  &string-or-nil;
  &directory-r;

    &dir-title; &elt-val-meaning-header;
    &startp-rel-abs; &subdirs-def; &subdir-string-or-wild;
    &subdir-r; | &parent-k; | &file-slash; instead of `subdir/`

  &name-r;
  &wild-string-or-nil;
  &type-r;
  &wild-string-or-nil; &version-nil;

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

  An &amiga; &name-type-split;

  Case is ignored in the strings on comparison. No case conversions are performed.

  filename notations

  External notation: | `dev:sub1.typ/sub2.typ/name.typ`
  using defaults: | `sub1.typ/sub2.typ/name.typ`
  or | `name.typ`
  or | `sub1.typ/**/sub3.typ/x*.lisp`
  or similar. |

  Formal specification of the external notation

  ch ::==

    any character except ':','/' and '*','?'

  name ::==

    {ch}+

  device ::==

    [ <empty> | ':' | name ':' ]

    empty | current device, relative to current directory
    ':' | current device, absolute (relative to root for disks)
    name ':' | specified device, absolute (relative to root for disks)

  subdir ::==

    [ <empty> | name ]

    empty | parent directory

  pathname ::==

    device { subdir '/' }* name

  Examples

  String | Device | Directory | our pathname
  --- | --- | --- | ---
  `'c:foo'` | 'C' | `device->foo` | `"c"` (&absolute-k; `"foo"`)
  `'c:foo/'` | 'C' | `device->foo` | `"c"` (&absolute-k; `"foo"`)
  `'c:foo/bar'` | 'C' | `device->foo->bar` | `"c"` (&absolute-k; `"foo" "bar"`)
  `'c:/foo'` | 'C' | `device->up->foo` | `"c"` (&absolute-k; &parent-k; `"foo"`)
  `'c:'` | 'C' | `device` | `"c"` (&absolute-k;)
  `:foo` | current | `device->root->foo` | &nil; (&absolute-k; `"foo"`)
  `foo` | current | `device->foo` | &nil; (&relative-k; `"foo"`)
  `'/foo'` | current | `device->up->foo` | &nil; (&relative-k; &parent-k; `"foo"`)
  `'//foo/bar'` | current | `device->up->up->foo->bar` | &nil; (&relative-k; &parent-k; &parent-k; `"foo" "bar"`)
  &file-bsla; | current | `device` | &nil; (&relative-k;)

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

  We interpret any path string that is empty or ends with &file-colon; or &file-slash; as pathname of a directory (with both &name-r; and &type-r; being &nil;).

Platform dependent: &unix; platforms only.
  &path-comps;
  &host-r;
  &always-nil;
  &device-r;
  &always-nil;
  &directory-r;

    &dir-title; &elt-val-meaning-header;
    &startp-rel-abs; &subdirs-def; &subdir-string-or-wild;

  &name-r;
  &wild-string-or-nil;
  &type-r;
  &wild-string-or-nil; &version-nil;

  A &unix; &name-type-split;

  filename notations

  External notation: | `server:sub1.typ/sub2.typ/name.typ`
  using defaults: | `sub1.typ/sub2.typ/name.typ`
  or | `name.typ`
  or | `sub1.typ/**/sub3.typ/x*.lisp`
  or similar. |

Platform dependent: &os2; platforms only.
  &path-comps;
  &host-r;
  &always-nil;
  &device-r;

    &nil; or &wild-k; or &file-letter-uc;

  &directory-r;

    &dir-title; &elt-val-meaning-header;
    &startp-rel-abs; &subdirs-def; &subdir-string-or-wild;

  &name-r;
  &wild-string-or-nil;
  &type-r;
  &wild-string-or-nil; &version-nil;

  An &os2; &name-type-split;

  filename notations

  External notation: | `A:\sub1.typ\sub2.typ\name.typ`
  using defaults: | `\sub1.typ\sub2.typ\name.typ`
  or | `name.typ`
  or | `*:\sub1.typ\**\sub3.typ\x*.lisp`
  or similar. |

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

Platform dependent: &win32; platforms only.
  &path-comps;
  &host-r;

    &nil; or &simple-string-type;, wildcard characters may occur but don't act as wildcards

  &device-r;

    &nil; or &wild-k; or &file-letter-uc;

  &directory-r;

    &dir-title; &elt-val-meaning-header;
    &startp-rel-abs; &subdirs-def; &subdir-string-or-wild;

  &name-r;
  &wild-string-or-nil;
  &type-r;
  &wild-string-or-nil; &version-nil;

  If &host-r; is non-&nil;, &device-r; must be &nil;.

  A &win32; &name-type-split;

  filename notations

  External notation: | `A:\sub1.typ\sub2.typ\name.typ`
  using defaults: | `\sub1.typ\sub2.typ\name.typ`
  or | `name.typ`
  or | `*:\sub1.typ\**\sub3.typ\x*.lisp`
  or similar. |

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

  If &host-r; is non-&nil; and the &directory-r;'s &startpoint-r; is not &absolute-k;, `(&parse-namestring; (&namestring; &path-r;))` will not be the same as &path-r;.

Platform dependent: &unix;, &amiga;, &os2;, &win32; platforms only.

  The wildcard characters: &file-star; matches any sequence of characters, &file-ques; matches any one character.

Platform dependent: &unix;, &amiga;, &os2;, &win32; platforms only.

  A filename is split into name and type according to the following rule:

  - if there is no &file-dot; in the filename, then the &name-r; is everything, &type-r; is &nil;;

  - if there is a &file-dot;, then &name-r; is the part before and &type-r; the part after the last dot.

  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: `(&make-pathname; :name ".profile")`.

Platform dependent: &acorn; platforms only.

  RISC OS provides several file systems as standard (ADFS, IDEFS, NetFS, RamFS, NetPrint) and support for extra file systems (DOSFS, ResourceFS and DeviceFS).

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

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

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

  Terminology

    A pathname may include a file system name, a special field, a media name (e.g., a disc name), directory name(s), and the name of the object itself; each of these parts of a pathname is known as an `element' of the pathname.

  Filenames

    Filename `elements' may be up to ten characters in length on FileCore-based file systems and on NetFS. These characters may be digits or letters. FileSwitch makes no distinction between upper and lower case, although file systems can do so. As a general rule, you should not use top-bit-set characters in filenames, although some file systems (such as FileCore-based ones) support them. Other characters may be used provided they do not have a special significance. Those that do are listed below:

    &file-dot;

      Separates directory specifications, e.g., `$.fred`

    &file-colon;

      Introduces a drive or disc specification, e.g., `:0`, `:bigdisc`. It also marks the end of a file system name, e.g., `adfs:`

    &file-star;

      Acts as a `wildcard' to match zero or more characters.

    `#`

      Acts as a `wildcard' to match any single character.

    `$`

      is the name of the root directory of the disc.

    `&`

      is the user root directory (URD)

    `@`

      is the currently selected directory (CSD)

    `^`

      is the `parent' directory

    `%`

      is the currently selected library (CSL)

    &file-bsla;

      is the previously selected directory (PSD)

  Directories

    The root directory, `$`, forms the top of the directory hierarchy of the media which contains the CSD. `$` does not have a parent directory, trying to access its parent will just access `$`. Each directory name is separated by a &file-dot; character. For example:

    - `$.Documents.Memos`

    - `%.cc`

  File Systems

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

    - `-net-$.SystemMesg`

    - `adfs:%.aasm`

  Special Fields

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

    - `net#MJHardy::disc1.mike`

    - `#MJHardy::disc1.mike`

    - `-net#MJHardy-:disc1.mike`

    - `-#MJHardy-:disc1.mike`

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

  `File$Path` and `Run$Path`

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

    name | purpose
    --- | ---
    File$Path | for read operations
    Run$Path | for execute operations

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

  Other path variables

    You can set up other path variables and use them as pseudo file systems. For example if you typed:

        *Set Source$Path adfs:$.src.,adfs:$.public.src.

    , you could then refer to the pseudo file system as `Source:` or (less preferable) as `-Source-`. These path variables work in the same was as `File$Path` and `Run$Path`.

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

  from Lisp-string notation to internal representation

    No swapping. `foo.lisp` means file type &lisp-file; and file name `foo`. This is pseudo-BNF:

    legal character ::==

      any ISO latin-1 graphic character ≥ ' ' except '.' ':' '*' '#' '$' '&' '@' '^' '%' '\' '?'

    extended legal character ::==

      any ISO latin-1 graphic character ≥ ' ' except ':' '"' '|'

    legal-wild char ::==

      legal char | '*' | '#' | '?'

    host ::==

      '-' { extended legal char except '-' }+ '-' | { extended legal char except '-' } { extended legal char }* ':' | empty

    device ::==

      ':' { legal char }+ '.' | empty

    directory ::==

      { '$' | '&' | '@' | '%' | '\' } '.' { subdirectory }* | { subdirectory }+ | empty

      '$' -> | &absolute-k; &root-k;
      '&' -> | &absolute-k; &home-k;
      '@' -> | &absolute-k; ¤t-k;
      '%' -> | &absolute-k; &library-k;
      '\' -> | &absolute-k; &previous-k;
      else | &relative-k;

    subdirectory ::==

      { '^' | { legal-wild char }+ } '.'

      '^' -> | &parent-k;

    filename ::==

      { { legal-wild char }+ | empty }

    filetype ::==

      { '.' { legal-wild char }+ | empty }

    pathname ::==

      host device directory filename filetype

    Examples

    String | Hostname | Device | Directory | Name | Type
    --- | --- | --- | --- | --- | ---
    `-net-$.SystemMesg` | `net` | &nil; | `(&absolute-k; &root-k;)` | `SystemMesg` | &nil;
    `net#MJHardy::disc1.mike` | `net#MJHardy` | `disc1` | `(&absolute-k; &root-k;)` | `mike` | &nil;
    `#MJHardy::disc1.mike` | `#MJHardy` | `disc1` | `(&absolute-k; &root-k;)` | `mike` | &nil;
    `-net#MJHardy-:disc1.mike` | `net#MJHardy` | `disc1` | `(&absolute-k; &root-k;)` | `mike` | &nil;
    `-#MJHardy-:disc1.mike` | `#MJHardy` | `disc1` | `(&absolute-k; &root-k;)` | `mike` | &nil;
    `@.foo` | &nil; | &nil; | `(&absolute-k; ¤t-k;)` | `foo` | &nil;
    `foo` | &nil; | &nil; | `(&relative-k;)` | `foo` | &nil;
    `^.` | &nil; | &nil; | `(&relative-k; &parent-k;)` | &nil; | &nil;
    `@.^.` | &nil; | &nil; | `(&absolute-k; ¤t-k; &parent-k;)` | &nil; | &nil;
    `foo.bar` | &nil; | &nil; | `(&relative-k;)` | `foo` | `bar`
    `foo.bar.baz` | &nil; | &nil; | `(&relative-k; "foo")` | `bar` | `baz`
    `foo.bar.` | &nil; | &nil; | `(&relative-k; "foo" "bar")` | &nil; | &nil;
    `foo.@.` | illegal |  |  |  |

  From internal representation to RISCOS string

    with swapping only of name/type components.

    Hostname | Device | Directory | Name | Type | RISCOS String
    --- | --- | --- | --- | --- | ---
    `net` | `disc1` | `(&absolute-k; &root-k;)` | `foo` | &nil; | `net::disc1.$.foo`
    `net#MJ` | `disc1` | `(&absolute-k; &root-k; "foo")` | `bar` | `baz` | `net#MJ::disc1.$.foo.baz.bar`
    `adfs` | `4` | `(&absolute-k; &root-k; "foo" "bar")` | &nil; | &nil; | `adfs::4.$.foo.bar`
    &nil; | `disc1` | `(&absolute-k; &root-k; "foo")` | `bar` | &nil; | `:disc1.$.foo.bar`
    &nil; | `disc1` | `(&absolute-k; ¤t-k;)` | &nil; | &nil; | illegal here
    &nil; | `disc1` | `(&relative-k;)` | &nil; | &nil; | `:disc1.`
    &nil; | `disc1` | &nil; | &nil; | &nil; | `:disc1.`
    &nil; | &nil; | `(&absolute-k; &root-k;)` | `foo` | &nil; | `$.foo`
    &nil; | &nil; | `(&absolute-k; ¤t-k;)` | `foo` | &nil; | `@.foo`
    &nil; | &nil; | `(&relative-k;)` | `foo` | `bar` | `bar.foo`
    &nil; | &nil; | `(&relative-k; "foo")` | `bar` | `baz` | `foo.baz.bar`
    &nil; | &nil; | `(&absolute-k; &library-k;)` | `bar` | &nil; | `%.bar`
    &nil; | &nil; | `(&absolute-k; &library-k; "foo")` | `bar` | &nil; | `%.foo.bar`
    &nil; | &nil; | `(&relative-k;)` | `foo` | `bar` | `bar.foo`
    &nil; | &nil; | `(&relative-k; "foo")` | `bar` | &nil; | `foo.bar`
    &nil; | &nil; | `(&relative-k; "foo")` | &nil; | `bar` | illegal here

    That is, the RISCOS string is the flattening-concatenation of

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

  internal representation
    &path-comps;
    &host-r;
    &string-or-nil;
    &device-r;
    &string-or-nil;
    &directory-r;

      &dir-title;
      element | values
      --- | ---
      &startpoint-r; | &relative-k; | &absolute-k; anchor
      anchor | &root-k; | &home-k; | ¤t-k; | &library-k; | &previous-k;
      &subdirs-def;
      &subdir-r; | &parent-k;
      &subdir-r; | &simple-string-type;, may contain wildcard characters &file-ques;,`#` and &file-star;

    &name-r;

      &simple-string-type; or &nil;, may contain wildcard characters &file-ques;,`#` and &file-star; (may also be specified as &wild-k;)

    &type-r;

      &nil; or &simple-string-type;, may contain wildcard characters &file-ques;,`#` and &file-star; (may also be specified as &wild-k;)

    &version-nil;

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

    The wildcard characters: &file-star; matches any sequence of characters, `'#'` or &file-ques; matches any one character.

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

## External notation.

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

Platform dependent: &dos; platforms only.

  [ [drivespec] : ] | a letter &file-star;|&file-letter-lc;|&file-letter-uc;
  { name [. type] \ } | each one a subdirectory, &file-bsla; may be replaced by &file-slash;
  [ name [. type] ] | filename with type (extension)

  Name and type may be character sequences of any &length; (consisting of alphanumeric characters and `-`, `_`). They are shortened to 8 (respectively 3) characters and converted to upper case. A single &file-star; is allowed for &wild-k;.

Platform dependent: &amiga; platforms only.

  see above.

Platform dependent: &unix; platforms only.

  [ &file-slash; ] | &file-slash; denotes absolute pathnames
  { &name-r; &file-slash; } | each one a subdirectory
  [ &name-r; [&file-dot; &type-r;] ] | filename with type (extension)

  Name and type may be character sequences of any &length; (consisting of printing ASCII characters, except &file-slash;).

Platform dependent: &os2;, &win32; platforms only.

  [ [drivespec] : ] | a letter &file-star;|&file-letter-lc;|&file-letter-uc;
  { &name-r; [. &type-r;] \ } | each one a subdirectory, &file-bsla; may be replaced by &file-slash;
  [ &name-r; [. &type-r;] ] | filename with type (extension)

  Name and type may be character sequences of any &length; (consisting of printing ASCII characters, except &file-slash;, &file-bsla;, &file-colon;).

Platform dependent: &acorn; platforms only.

  see above.

&namestring; has an optional flag argument: `(&namestring; &path-r; &t;)` returns an external notation suitable for passing to the operating system or other programs.

Platform dependent: &dos;, &os2;, &amiga; platforms only.

  The function &user-homedir-pathname; is not implemented.

Platform dependent: &dos;, &os2; platforms only.

  If you really need that function, you might define it like this:

      (defun user-homedir-pathname (&optional host)
        (declare (ignore host))
        (or (system::getenv "HOME") "\\"))

## Logical Pathnames [CLHS-19.3]

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

## The Filenames Dictionary [CLHS-19.4]

&pathname; always returns a physical pathname.

&pathname-match-p; does not interpret missing components as wild.

&translate-pathname; has two additional keywords: `(&translate-pathname; source from-wildname to-wildname &key-amp; &all-k; &merge-k;)`

If &all-k; is specified and non-&nil;, a list of all resulting pathnames, corresponding to all matches of `(&pathname-match-p; source from-wildname)`, is returned. If &merge-k; is specified and &nil;, unspecified pieces of to-pathname are not replaced by corresponding pieces of source.

### Function &parse-namestring;

`(&parse-namestring; &string-r; &optional-amp; &host-r; &defaults-r; &key-amp; &start-r; &end-r; junk-allowed)` returns a logical pathname only if &host-r; is a logical host or &host-r; is &nil; and &defaults-r; is a &logical-pathname-class;. To construct a logical pathname from a string, the function &logical-pathname; can be used.

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

### Function &merge-pathnames;

`(&merge-pathnames; &path-r; [default-pathname])` returns a logical pathname only if default-pathname is a logical pathname. To construct a logical pathname from a string, the function &logical-pathname; can be used.

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

Rationale: &merge-pathnames; is used to specify default components for pathnames, so there is some analogy between `(&merge-pathnames; a b)` and `(or a b)`. Obviously putting in the same default a second time should do the same as putting it in once: `(or a b b)` is the same as `(or a b)`, so `(&merge-pathnames; (&merge-pathnames; a b) b)` should be the same as `(&merge-pathnames; a b)`.

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

Now, `(&merge-pathnames; (&merge-pathnames; '#p"x/" '#p"y/") '#p"y/")` and `(&merge-pathnames; '#p"x/" '#p"y/")` 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;.

When &pathmerge; is non-&nil;, the normal &ansi-cl; behavior is exhibited: `(&merge-pathnames; #p"x/" #p"y/")` evaluates to `#p"y/x/"`

The rationale is that merge is merge and not or.

### Function &load-logical-pathname-translations;

When the &host-r; argument to &load-logical-pathname-translations; is not a defined logical host yet, we proceed as follows:

1. If both environment variables `LOGICAL_HOST_&host-r;_FROM` and `LOGICAL_HOST_&host-r;_TO` exist, then they define the map of the &host-r;.

2. If the environment variable `LOGICAL_HOST_&host-r;` exists, its value is read from, and the result is passed to `(&setf; &logical-pathname-translations;)`.

3. 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, Allegro CL-style, odd objects being host names and even object being their &logical-pathname-translations;. When the element is a directory, a file, named `&host-r;` or `&host-r;.host`, in that directory, is &read; from once, CMUCL-style, the object read being the &logical-pathname-translations; of the &host-r;.

# Files [CLHS-20]

## The Files Dictionary [CLHS-20.2]

&rename-file;

&rename-file; always returns a non-logical pathname as its first value.

&probe-file;

&probe-file; cannot be used to check whether a directory exists. Use the function &probe-dir; or the function &directory; for this purpose.

&file-author;

&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 owner and author are not the same; in particular, authorship is preserved by copying, while ownership is not.

&probe-dir;

`(&probe-dir; &path-r;)` tests whether &path-r; exists and is a directory. It will, unlike &probe-file; or &truename;, not signal an error if the parent directory of &path-r; does not exist.

### Function &directory;

`(&directory; &optional-amp; &path-r; &key-amp; :full :circle)` can run in two modes:

- If &path-r; contains no name or type component, a list of all matching directories is produced.

- Otherwise a list of all matching files is returned. If the `:full` argument is non-&nil;, this contains additional information: for each matching file you get a list of at least four elements `(file-pathname file-truename file-write-date-as-decoded-time file-length)`.

Platform dependent: &unix; platforms only.

  If the `:circle` argument is non-&nil;, the function avoids endless loops that may result from symbolic links.

`ext:dir`

`(`ext:dir` &optional-amp; &path-r;)` is like &directory;, but displays the pathnames instead of returning them. `(ext:dir)` shows the contents of the current directory.

&cd;

Platform dependent: &unix;, &amiga; platforms only.

  `(&cd; [&path-r;])` manages the current directory.

Platform dependent: &acorn; platforms only.

  `(&cd; [&path-r;])` manages the current host, current device and the current directory.

Platform dependent: &dos;, &os2;, &win32; platforms only.

  `(&cd; [&path-r;])` manages the current device and the current directory.

&cd;

`(&cd; &path-r;)` sets it, `(&cd;)` returns it.

`ext:default-directory`

`(`ext:default-directory`)` is equivalent to `(&cd;)`. `(&setf; (`ext:default-directory`) &path-r;)` is equivalent to `(&cd; &path-r;)`, except for the return value.

`ext:make-dir`

`(`ext:make-dir` directory-pathname)` creates a new subdirectory.

`ext:delete-dir`

`(`ext:delete-dir` directory-pathname)` removes an (empty) subdirectory.

# Streams [CLHS-21]

## Interactive Streams [CLHS-21.1.1.1.3]

Interactive streams are those whose next input might depend on a prompt one might output.

## Terminal interaction.

&readline;

Platform dependent: &unix;, &dos;, &os2; platforms only, and only in &clisp; built &without; compile-time flag &noreadline;.

  Input through &terminal-io-var; uses the &readline; library. Arrow keys can be used to move within the input history. The Tab key completes the symbol's name that is being typed. See clreadline.html or clreadline.dvi for a complete description of the key bindings. The &readline; library is not used if standard input and standard output do not both refer to the same terminal.

&with-kbd;

Platform dependent: &unix;, &amiga;, &acorn;, &dos;, &os2;, &win32; platforms only.

  &terminal-io-var; is not the only stream that communicates directly with the user: During execution of the body of a `(&with-kbd; . &body-r;)` form, &kbd-in; is the stream that reads the keystrokes from the keyboard. It returns every keystroke in detail, as &character-class; or &input-char; with the following bits:

  `:hyper`

    (Platform dependent: &dos;, &os2;, &win32;, &amiga; platforms only.) if a non-standard key. These keys are: Function keys, cursor keypads, numeric keypad (Platform dependent: &dos;, &os2;, &win32; platforms only). Function keys, cursor keypad (Platform dependent: &amiga; platforms only).

  slot key

    the key name, for non-standard keys:

    Platform dependent: &dos;, &os2; platforms only.

      &key-value-header;
      F1..F12 | `:F1`..`:F12`
      Insert | `:Insert`
      Delete | `:Delete`
      Home | `:Home`
      End | `:End`
      PgUp | `:PgUp`
      PgDn | `:PgDn`
      Arrow keys | `:Left``:Right` `:Up``:Down`

    Platform dependent: &unix;, &win32; platforms only.

      &key-value-header;
      F1..F12 | `:F1`..`:F12`
      Insert | `:Insert`
      Delete | `:Delete`
      Home | `:Home`
      End | `:End`
      Center | `:Center`
      PgUp | `:PgUp`
      PgDn | `:PgDn`
      Arrow keys | `:Left``:Right` `:Up``:Down`

    Platform dependent: &amiga; platforms only.

      &key-value-header;
      F1..F10 | `:F1`..`:F10`
      Help | `:Help`
      Arrow keys | `:Left``:Right` `:Up``:Down`

  slot &ch-r;

    the ASCII code for standard keys

  `:super`

    (Platform dependent: &dos;, &os2;, &win32;, &amiga; platforms only.) if pressed together with &shift; key(s) and if the keystroke would have been an other without &shift;.

  `:control`

    if pressed together with the &ctrl; key.

  `:meta`

    (Platform dependent: &dos;, &os2;, &win32; platforms only.) if pressed together with the &alt; key.

  This keyboard input is not echoed on the screen. During execution of a `(&with-kbd; . &body-r;)` form, no input from &terminal-io-var; or any synonymous stream should be requested.

See also Random Screen Access.

## The Streams Dictionary [CLHS-21.2.]

### Function &stream-element-type;

&stream-element-type; is &setf;able. The &stream-element-type; of &stream-class;s created by the functions &open;, &mk-pipe-in; &mk-pipe-out;, &mk-pipe-io;, &so-accept;, &so-connect; can be modified, if the old and the new &stream-element-type;s are either

- both equivalent to &character-class; or &unsigned-byte-8; or &signed-byte-8;; or

- both equivalent to &unsigned-byte-n; or &signed-byte-n;, with the same &n-r;.

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

### Binary input, &read-byte;, &rd-integer; & &rd-float;

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

`(&rd-integer; &stream-r; &eltype-r;)` is like `(&read-byte; &stream-r;)` if &stream-r;'s &stream-element-type; were set to &eltype-r;, except that &stream-r;'s &file-position; will increase by &n-r;/8 instead of 1.

&endianness; can be `:little` or `:big`. The default is `:little`, which corresponds to the &read-byte; behavior in &clisp;.

Together with `(&setf; &stream-element-type;)`, this function permits mixed character/binary input from a stream.

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

### Binary output, &write-byte;, &wr-integer; & &wr-float;

The function `(&wr-integer; &int-r; &stream-r; &eltype-r; &optional-amp; &endianness;)` writes a multi-byte integer to &stream-r;. &stream-r; should be a &stream-class; with &stream-element-type; &unsigned-byte-8;. &eltype-r; should be a type equivalent to &unsigned-byte-n;, where &n-r; is a multiple of 8.

`(&wr-integer; &int-r; &stream-r; &eltype-r;)` is like `(&write-byte; &int-r; &stream-r;)` if &stream-r;'s &stream-element-type; were set to &eltype-r;, except that &stream-r;'s &file-position; will increase by &n-r;/8 instead of 1.

Together with `(&setf; &stream-element-type;)`, this function permits mixed character/binary output to a &stream-class;.

The function `(&wr-float; float &stream-r; &eltype-r; &optional-amp; &endianness;)` writes a floating-point number in IEEE binary representation to &stream-r;. &stream-r; should be a &stream-class; with &stream-element-type; &unsigned-byte-8;. &eltype-r; should be a type equivalent to &single-float-type; or &double-float-type;.

### Function &read-sequence;

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

&rd-by-seq; performs multiple &read-byte; operations:

  `(&rd-by-seq; &sequence-r; &stream-r; &key-amp; &start-k; &end-k;)` fills the subsequence of &sequence-r; specified by &start-k; and &end-k; with &integer-class;s consecutively read from &stream-r;. It returns the index of the first element of &sequence-r; that was not updated (= &end-r; or < &end-r; if the &stream-r; reached its end).

  This function is especially efficient if &sequence-r; is a &unsigned-byte-vec; and &stream-r; is a &file-pipe-socket; &stream-class; with &stream-element-type; &unsigned-byte-8;.

&rd-ch-seq; performs multiple &read-char; operations:

  `(&rd-ch-seq; &sequence-r; &stream-r; &key-amp; &start-k; &end-k;)` 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 < &end-r; if the &stream-r; reached its end).

  This function is especially efficient if &sequence-r; is a &string-class; and &stream-k; is a &file-pipe-socket; stream with &stream-element-type; &character-class; or an input string stream.

### Function &write-sequence;

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

&wr-by-seq; performs multiple &write-byte; operations:

  `(&wr-by-seq; &sequence-r; &stream-k; &key-amp; &start-k; &end-k;)` outputs the &integer-class;s of the subsequence of &sequence-r; specified by &start-k; and &end-k; to &stream-k;. It returns &sequence-r;.

  This function is especially efficient if &sequence-r; is a &unsigned-byte-vec; and &stream-r; is a &file-pipe-socket; &stream-class; with &stream-element-type; &unsigned-byte-8;.

&wr-ch-seq; performs multiple &write-char; operations:

  `(&wr-ch-seq; &sequence-r; &stream-k; &key-amp; &start-k; &end-k;)` outputs the characters of the subsequence of &sequence-r; specified by &start-k; and &end-k; to &stream-k;. It returns &sequence-r;.

  This function is especially efficient if &sequence-r; is a &string-class; and &stream-k; is a &file-pipe-socket; &stream-class; with &stream-element-type; &character-class;.

### Function &file-position;

Platform dependent: &dos;, &os2;, &win32; platforms only.

  &file-position; works on any buffered file stream. When a &nl-c; is output to (respectively input from) a file stream, its file position is increased by 2 since &nl-c; is encoded as &cr-c;/&lf-c; in the file.

### Function &open;

&open; cannot handle files of size ≥ 4 GB.

&open; accepts three additional keywords: &eltype;, &extfmt;, &buffered;.

The acceptable values for the &file-pipe-socket; functions

&eltype;

  types equivalent to &character-class; or &unsigned-byte-n;, &signed-byte-n;; if the stream is to be unbuffered, &n-r; must be a multiple of 8.

&extfmt;

  &encoding;s, (constant) &symbol-class;s in the &charset-pac; package, &string-class;s (denoting &iconv;-based encodings), the symbol &default-k;, and the &line-term; keywords &unix-k;, &mac-k;, &dos-k;. The default encoding is &def-file-enc;.

&buffered;

  &nil;, &t;, or &default-k;.

  - for functions that create &socket-stream;s and pipes, &default-k; is equivalent to &nil;;

  - for functions that open 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.

### Function &close;

&close; ignores its &abort-k; argument.

### Class &broadcast-stream-class;

&input-stream-p; and &interactive-stream-p; return false for broadcast streams.

# Printer [CLHS-22]

## Multiple Possible Textual Representations [CLHS-22.1.1.1]

&pr-closure;

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 #Y syntax which the reader understands. &pr-closure; is initially set to &nil;.

&pr-rpars;

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;.

&pr-indent;

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 `1`.

&ppr-first-newline;

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

## Printing Other Vectors [CLHS-22.1.3.7]

When &print-readably-var; is true, other vectors are written as follows: if the &array-element-type; is &t-class;, the syntax `#(x0 ... xn-1)` is used. Otherwise, the syntax `#A(&eltype-r; &dimensions-r; &cont-r;)` is used.

## Printing Other Arrays [CLHS-22.1.3.8]

When &print-readably-var; is true, other arrays are written as follows: if the &array-element-type; is &t-class;, the syntax `#rankA &cont-r;` is used. Otherwise, the syntax `#A(&eltype-r; &dimensions-r; &cont-r;)` is used.

## The Lisp Pretty Printer [CLHS-22.2]

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

### Pretty Print Dispatch Table [CLHS-22.2.1.4]

A pprint dispatch table 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).

## The Printer Dictionary [CLHS-22.4]

&write; & &write-to-string;

The functions &write; and &write-to-string; have an additional keyword argument `:closure` which is used to bind &pr-closure;.

### Function &format;

The &format; instruction &format-w; is similar to &format-a; and &format-s;, but avoids binding of &print-escape-var;. `(&format; &stream-r; "~W" &object-r;)` is equivalent to `(&write; &object-r; &stream-k; &stream-r;)`.

The &format; instruction `~!` 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.

`(&format; &stream-r; "~args!" &func-r; &object-r;)` is equivalent to `(&funcall; &func-r; &stream-r; &object-r; colon-modifier-p atsign-modifier-p args)`.

&format; &format-r; and &format; &format-rs; can output only integers in the range `|n| < 1066`. The output is in English, according to the American conventions, and these conventions are identical to the British conventions only in the range `|n| < 109`.

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

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.

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

### pathnames

Pathnames are printed as follows: If &print-escape-var; is &nil;, only the namestring is printed; otherwise it is printed with `#P""` syntax, as per &ansi-cl; Issue PRINT-READABLY-BEHAVIOR:CLARIFY. But, if &print-readably-var; is true, we are in trouble as `#P""` 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: `#-CLISP #P"" #+CLISP #S(PATHNAME ...)`. Otherwise, when the variable &pathprint; is non-&nil;, the `#P""` notation is used as per 1.5.1.4.1 Resolution of Apparent Conflicts in Exceptional Situations.

### Miscellaneous Issues

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

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

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

Platform dependent: &unix;, &dos;, &os2;, &win32;, &acorn; platforms only.

  &print-pretty-var; is initially &nil; but set to &t; in &config-file;. This makes screen output prettier.

Platform dependent: &amiga; platforms only.

  &print-pretty-var; is initially &nil; but set to &t; in &config-file;. This makes unbuffered screen output both much faster and prettier.

&print-array-var; is initially set to &t;.

# Reader [CLHS-23]

This is the list of objects whose external representation cannot be meaningfully read in:

unreadable objects

format | meaning
--- | ---
`#<&type-r; ...>` | all structures lacking a keyword constructor
`#<ARRAY &type-r; &dimensions-r;>` | all arrays except strings, if &print-array-var; is &nil;
`#<SYSTEM-FUNCTION &name-r;>` | built-in function written in &c-lang;
`#<ADD-ON-SYSTEM-FUNCTION &name-r;>` | other function written in &c-lang;
`#<SPECIAL-OPERATOR &name-r;>` | special operator handler
`#<COMPILED-CLOSURE &name-r;>` | compiled function, if &pr-closure; is &nil;
`#<CLOSURE &name-r; ...>` | interpreted function
`#<FRAME-POINTER #x...>` | pointer to a stack frame
`#<DISABLED POINTER>` | frame pointer which has become invalid on exit from the corresponding █ or &tagbody;
`#<...-STREAM ...>` | stream
`#<PACKAGE &name-r;>` | package
`#<HASH-TABLE #x...>` | hash table, if &print-array-var; is &nil;
`#<READTABLE #x...>` | readtable
`#<SYMBOL-MACRO &form-r;>` | &symbol-macro; handler
`#<FOREIGN-POINTER #x...>` | foreign pointer (Platform dependent: &unix;, &win32;, &amiga; platforms only.)
`#<FOREIGN-ADDRESS #x...>` | foreign address (Platform dependent: &unix;, &win32; platforms only.)
`#<FOREIGN-VARIABLE &name-r; #x...>` | foreign variable (Platform dependent: &unix;, &win32; platforms only.)
`#<FOREIGN-FUNCTION &name-r; #x...>` | foreign function (Platform dependent: &unix;, &win32; platforms only.)
`#<UNBOUND>` | "value" of a symbol without value, "value" of an unsupplied optional or keyword argument
`#<SPECIAL REFERENCE>` | environment marker for variables declared &special-dec;
`#<DOT>` | internal &read; result for "."
`#<END OF FILE>` | internal &read; result, when the end of file is reached
`#<READ-LABEL ...>` | intermediate &read; result for `#n#`
`#<ADDRESS #x...>` | machine address, should not occur
`#<SYSTEM-POINTER #x...>` | should not occur

## characters

#\Code allows input of characters of arbitrary code: e.g., #\Code231 reads as the character `(&code-char; 231.)`.

## Additional read dispatch macros

- #Y is used to read compiled functions and to set the current input stream's &encoding;.

- `#""` is used to read pathnames: `#"test.lisp"` is the value of `(&pathname; "test.lisp")`

  Platform dependent: &dos;, &os2;, &win32; platforms only.

    As in all strings, backslashes must be written twice here: `#"A:\\programs\\test.lisp"`

  Platform dependent: &acorn; platforms only.

    As in all strings, backslashes must be written twice here: `#"\\.test.lisp"`

## Function &readtable-case;

When the value of `(&readtable-case; readtable)` is `:invert`, it applies to the package name and the symbol name of a symbol separately (not to the entire token at once). An alternative to the use of &readtable-case; is the use of the &case-sensitive-k; option to &make-package;, &in-package; and &defpackage;.

## Functions &listen;, &read-char-no-hang;

`(&rcwhp; &stream-r;)`

  &rcwhp; queries the stream's input status. It returns &nil; if &read-char; and &peek-char; with a peek-type of &nil; will return immediately. Otherwise it returns &t;. (In the latter case the standard &listen; function would return &nil;.)

  Note the difference with `(¬ (&listen; &stream-r;))`: When the &eos; is reached, &listen; returns &nil;, whereas &rcwhp; returns &nil;.

  Note also that &rcwhp; is not a good mean to test for &eos;: If &rcwhp; returns &t;, this does not mean that the &stream-r; will deliver more characters. It only means that it is not known at this moment whether the &stream-r; is already at &eos;, or will deliver more characters.

## Function &read-byte;

`(&rbla; &stream-r;)`

  To be called only if &stream-r;'s &stream-element-type; is &unsigned-byte-8; or &signed-byte-8;. Returns &t; if &read-byte; would return immediately with an &integer-class; result. Returns &eof-k; if the &eos; is already known to be reached. If &read-byte;'s value is not available immediately, returns &nil; instead of waiting.

`(`EXT:READ-BYTE-WILL-HANG-P` &stream-r;)`

  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.

`(`EXT:READ-BYTE-NO-HANG` &stream-r; &optional-amp; &eof-ep; &eof-v;)`

  To be called only if &stream-r;'s &stream-element-type; is &unsigned-byte-8; or &signed-byte-8;. Returns an &integer-class; or does &eos; handling, like &read-byte;, if that would return immediately. If &read-byte;'s value is not available immediately, returns &nil; instead of waiting.

# System Construction [CLHS-24]

## The System Construction Dictionary [CLHS-24.2]

The compiler can be called not only by the functions &compile;, &compile-file; and &disassemble;, but also by the declaration `(compile)`.

### Function &compile-file;

`(&compile-file; input-file &key-amp; :output-file :listing &warnings-k; &verbose-k; &print-k;)` compiles a file to platform-independent bytecode.

input-file

  should be a pathname/string/symbol.

`:output-file`

  should be &nil; or &t; or a pathname/string/symbol or an output-stream. The default is &t;.

`:listing`

  should be &nil; or &t; or a pathname/string/symbol or an output-stream. The default is &nil;.

&warnings-k;

  specifies whether warnings should also appear on the screen.

&verbose-k;

  specifies whether error messages should also appear on the screen.

&print-k;

  specifies whether an indication which forms are being compiled should appear on the screen.

The variables `custom:*compile-warnings*`, &compile-verbose-var;, &compile-print-var; provide defaults for the &warnings-k;, &verbose-k;, &print-k; keyword arguments, respectively. For each input file (default file type: &lisp-file;) the following files are generated:

File | When | Default file type | Contents
--- | --- | --- | ---
output file | only if `:output-file` is not &nil; | &fasl-file; | can be loaded using the &load; function
auxiliary output file | only if `:output-file` is not &nil; | &lib-file; | used by &compile-file; when compiling a &require; form referring to the input file
listing file | only if `:listing` is not &nil; | `#p".lis"` | disassembly of the output file
&c-lang; output file | only if `:output-file` is not &nil; | `#p".c"` | foreign function interface; this file is deleted if it is empty

### Function &compile-file-pathname;

The default for the `:output-file` argument is &t;, which means &fasl-file;.

### Function &require;

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

At compile time, `(&require; "foo")` forms are treated specially: &load-paths; is searched for `"foo.lisp"` and `"foo.lib"`. If the latest such file is a &lisp-file;, it is compiled; otherwise the &lib-file; is loaded. The &lib-file; is a header 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 necessary to either enclose &require; forms in &eval-when; or to load the required files in the makefiles: if you have two files, `"foo.lisp"` and `"bar.lisp"`, and the latter requires the former, you can write in your &make-file;:

    all: foo.fas bar.fas

    foo.fas: foo.lisp
    	clisp -c foo

    bar.fas: bar.lisp foo.fas
            clisp -c bar

instead of the more cumbersome (and slower, since &lib-file;s are usually smaller and load faster that &fasl-file;s):

    bar.fas: bar.lisp foo.fas
            clisp -i foo -c bar

Thus, you do not need to &load; `"foo"` in order to &compile-file; `"bar.lisp"`. If memory is tight, and if `"foo.lisp"` contains only a few inline functions, macros, constants or variables, this is a space and time saver. If `"foo.lisp"` does a lot of initializations or side effects when being loaded, this is important as well.

### Function &load;

&load; has two additional keywords &echo-k; and &compiling-k;.

`(&load; &filename-r; &key-amp; &verbose-k; &print-k; &echo-k; &if-does-not-exist; &compiling-k;)`

&verbose-k; &t;

  causes &load; to emit a short message that a file is being loaded. The default is &load-verbose-var;, which is initially &t;.

&print-k; &t;

  causes &load; to print the value of each form. The default is &load-print-var;, which is initially &nil;.

&echo-k; &t;

  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 `custom:*load-echo*`, which is initially &nil;.

&compiling-k; &t;

  causes each form read to be compiled on the fly. The compiled code is executed at once and - in contrast to `compile-file` - not written to a file. The default is `custom:*load-compiling*`, which is initially &nil;.

&load-paths;

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;.

### Variable &features-var;

The variable &features-var; initially contains the symbols

keyword | meaning
--- | ---
`:CLISP` | the name of this implementation
`:ANSI-CL` |
`:COMMON-LISP` |
`:INTERPRETER` |
`:COMPILER` |
`:SOCKETS` | see &socket-stream;s
`:GENERIC-STREAMS` | see Defining new kinds of Streams
`:SYSCALLS` | see System Calls
`:DIR-KEY` | see Directory Access
`:LOGICAL-PATHNAMES` |
`:FFI` | if a foreign function interface (see &ffi-pac;) is supported (Platform dependent: many &unix;, &win32; platforms only)
`:GETTEXT` | if internationalization (see &i18n-pac;) using the &ggettext; package is supported (Platform dependent: most &unix; platforms only)
`:UNICODE` | if Unicode (ISO 10646) characters are supported (see &charset-pac;)
`:LOOP` |
`:CLOS` |
`:AMIGA` | if &hw; = Amiga and &os; = Exec/AmigaDOS
`:DOS` | if &hw; = PC (clone) and &os; = DOS
`:OS/2` | if &hw; = PC (clone) and &os; = OS/2
`:WIN32` | if &hw; = PC (clone) and &os; = Win32 (Windows 95/98/NT/Me/2000)
`:PC386` | if &hw; = PC (clone) with a 386/486/586/686 CPU
&unix-k; | if &os; = Unix (in this case the &hw; is irrelevant!)

# Environment [CLHS-25]

## Debugging Utilities [CLHS-25.1.2]

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

Commands common to the main loop, the debugger and the stepper

&cmd-abbrev-oper-header;
`Help` | `:h` | prints a list of available commands

Commands common to the debugger and the stepper

&cmd-abbrev-oper-header;
`Abort` | `:a` | abort to the next most recent &repl;
`Unwind` | `:uw` | abort to the next most recent &repl;

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.

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 `Up` and `Down`.

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.

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

Commands common to the debugger and the stepper

&cmd-abbrev-oper-header;
`Error` | `:e` | print the last error message.
`Mode-1` | `:m1` | sets the current mode to 1: all the stack elements are considered. This mode works fine for debugging compiled functions.
`Mode-2` | `:m2` | sets the current mode to 2: all the frames are considered.
`Mode-3` | `:m3` | sets the current mode to 3: only lexical frames (frames that correspond to special forms that modify the lexical environment) are considered.
`Mode-4` | `:m4` | 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.
`Mode-5` | `:m5` | sets the current mode to 5: only &apply; frames are considered. Every invocation of an interpreted function corresponds to one &apply; frame.
`Where` | `:w` | shows the current stack frame.
`Up` | `:u` | goes up one frame, i.e., to the caller if in mode-5
`Down` | `:d` | does down one frame, i.e., to the callee if in mode-5
`Top` | `:t` | goes to top frame, i.e., to the top-level form if in mode-4
`Bottom` | `:b` | goes to bottom (most recent) frame, i.e., most probably to the form or function that caused the debugger to be entered.
`Backtrace` | `:bt` | lists the stack in current mode, bottom frame first, top frame last.
`Backtrace-1` | `:bt1` | lists the stack in mode 1.
`Backtrace-2` | `:bt2` | lists the stack in mode 2.
`Backtrace-3` | `:bt3` | lists the stack in mode 3.
`Backtrace-4` | `:bt4` | lists the stack in mode 4.
`Backtrace-5` | `:bt5` | lists the stack in mode 5.
`Frame-limit` | `:fl` | set the frame-limit: this many frames will be printed in a backtrace at most.
`Backtrace-l` | `:bl` | limit of frames to print will be prompted for.

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

&eval;/&apply;-specific commands

&cmd-abbrev-oper-header;
`Break+` | `:br+` | 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.
`Break-` | `:br-` | removes a breakpoint from the current frame.
`Redo` | `:rd` | re-evaluates the corresponding form or function call. This command can be used to restart parts of a computation without aborting it entirely.
`Return` | `:rt` | leaves the current frame. You will be prompted for the return values.

Commands specific to the debugger

&cmd-abbrev-oper-header;
`Continue` | `:c` | continues evaluation of the program.

Commands specific to the stepper

&cmd-abbrev-oper-header;
`Step` | `:s` | step into a form: evaluate this form in single step mode
`Next` | `:n` | step over a form: evaluate this form at once
`Over` | `:o` | step over this level: evaluate at once up to the next return
`Continue` | `:c` | switch off single step mode, continue evaluation

The stepper is usually used like this: If some form returns a strange value or results in an error, call `(&step; &form-r;)` and navigate using the commands `Step` and `Next` until you reach the form you regard as responsible. If you are too fast (execute `Next` 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 `Next` commands or one `Over` command will help.

## The Environment Dictionary [CLHS-25.2]

### Function &disassemble;

Platform dependent: &unix; platforms only.

  &disassemble; can disassemble to machine code, provided that &gnu; gdb is present. In that case the argument may be a system-function, a foreign-function, a special operator indicator, a symbol denoting one of these, a number, or a string.

### Function &uncompile;

The function &uncompile; does the converse of &compile;: `(&uncompile; &func-r;)` reverts a compiled &func-r; (name), that has been entered or loaded in the same session and then compiled, back to its interpreted form.

### Function &documentation;

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

`ext:clhs`

&hyperspec; access is provided via `(`ext:clhs` &symbol-r; &key-amp; `:browser`)` function, which uses your web browser. browser should be a valid keyword in the `custom:*browsers*` &alist;.

### Macro &trace;

`(&trace; &func-r; ...)` makes the functions &func-r;, ... traced. &func-r; should be either a symbol or a list `(&symbol-r; &key-amp; `:suppress-if` `:step-if` `:pre` `:post` `:pre-break-if` `:post-break-if` `:pre-print` `:post-print` &print-k;)`, where

`:suppress-if` &form-r;

  no trace output as long as &form-r; is true

`:step-if` &form-r;

  invokes the stepper as soon as &form-r; is true

`:pre` &form-r;

  evaluates &form-r; before calling the function

`:post` &form-r;

  evaluates &form-r; after return from the function

`:pre-break-if` &form-r;

  goes into the break loop before calling the function if &form-r; is true

`:post-break-if` &form-r;

  goes into the break loop after return from the function if &form-r; is true

`:pre-print` &form-r;

  prints the values of &form-r; before calling the function

`:post-print` &form-r;

  prints the values of &form-r; after return from the function

&print-k; &form-r;

  prints the values of &form-r; both before calling and after return from the function

In all these forms you can access the following variables:

`EXT:*TRACE-FUNCTION*`

  the function itself

`EXT:*TRACE-ARGS*`

  the arguments to the function

`EXT:*TRACE-FORM*`

  the function/macro call as form

&trace-val;

  after return from the function: the list of return values from the function call

and you can leave the function call with specified values by using &return;.

&trace; and &untrace; are also applicable to functions `(&setf; &symbol-r;)` and to macros, but not to locally defined functions and macros.

### Function &inspect;

The function &inspect; takes a keyword argument `:frontend`, which specifies the way &clisp; will interact with the user.

Available `:frontend`s for &inspect; in &clisp;

`:tty`

  The interaction is conducted via the &terminal-io-var; stream. Please use the `:h` command to get the list of all available commands.

`:http`

  A window in your Web browser (specified by the &browser; keyword argument) is opened and it is controlled by &clisp; via a &socket-stream;, using the HTTP protocol. You should be able to use all the standard browser features.

  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 `quit` link to terminate the session.

  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.

### Macro &space;

The macro &space; is like the macro &time;: `(&space; &form-r;)` evaluates the &form-r;, and, as a side effect, outputs information about the memory allocations caused by this evaluation. It also prints everything printed by `TIME`.

### Function &room;

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.

The function `EXT:GC` starts a global &gc;ion and its return value has the same meaning as the second value of &room;.

### Macro &time;

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

### Function &ed;

The function &ed; calls the external editor specified by the variable `CUSTOM:*EDITOR*` (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.

### Clock Time

Platform dependent: &amiga;, &acorn;, &dos;, &os2; platforms only.

  The variable `CUSTOM:*DEFAULT-TIME-ZONE*` 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).

The time zone in a decoded time must not necessarily be an integer, but (as float or rational number) it should be a multiple of `1/3600`.

Platform dependent

platform | &acorn;, &dos;, &os2; | &amiga; | &unix; | &win32;
--- | --- | --- | --- | ---
&internal-time-units-per-second; | 100 | 50 | 1,000,000 | 10,000,000

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

### Machine

Platform dependent: &unix;, &win32; platforms only.

  The functions &short-site-name;, &long-site-name; should be defined in a site-specific &config-file; file.

Platform dependent: &amiga;, &acorn;, &dos;, &os2; platforms only.

  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.

### Functions &apropos; & &apropos-list;

The search performed by &apropos; and &apropos-list; is case-insensitive.

### Function &dribble;

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

### Function &lisp-implementation-version;

&lisp-implementation-version; returns the numeric version (like `3.14`), and the release date (like `"1999-07-21"`). 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 `3141592654`). When running on a different machine, it appends the &machine-instance; of the machine on which it was built.

# Glossary [CLHS-26]

No notes.

# Appendix [CLHS-a]

No notes.