Implementation Notes for GNU CLISP.
Dr. Bruno Haible
Dr. Sam Steingold
These notes are covered by the GNU GFDL:
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License (GFDL), Version 1.1 or any later version published by the Free Software Foundation (FSF); with no Invariant Sections, with Front-Cover Text being this section, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License."
- Table of Contents
![[CLISP icon]](clisp.png)
- I. Chapters or the [Common Lisp HyperSpec]
- Introduction [CLHS-1]
- Syntax [CLHS-2]
- Evaluation and Compilation [CLHS-3]
- Types and Classes [CLHS-4]
- Data and Control Flow [CLHS-5]
- Iteration [CLHS-6]
- Objects [CLHS-7]
- Structures [CLHS-8]
- Conditions [CLHS-9]
- Symbols [CLHS-10]
- Packages [CLHS-11]
- Numbers [CLHS-12]
- Characters [CLHS-13]
- Attributes
- Character Scripts [CLHS-13.1.2.1]
- Character Attributes [CLHS-13.1.3]
- Graphic Characters [CLHS-13.1.4.1]
- Alphabetic Characters [CLHS-13.1.4.2]
- Case of Implementation-Defined Characters [CLHS-13.1.4.3.4]
- Numeric Characters [CLHS-13.1.4.4]
- Ordering of Characters [CLHS-13.1.6]
- Treatment of Newline during Input and Output [CLHS-13.1.8]
- Character Encodings [CLHS-13.1.9]
- Documentation of Implementation-Defined Scripts [CLHS-13.1.10]
- The Characters Dictionary [CLHS-13.2]
- Functions on characters
- platform-dependent characters
- Obsolete Constants
- Conses [CLHS-14]
- Arrays [CLHS-15]
- Strings [CLHS-16]
- Sequences [CLHS-17]
- Hash Tables [CLHS-18]
- Filenames [CLHS-19]
- Files [CLHS-20]
- Streams [CLHS-21]
- Printer [CLHS-22]
- Reader [CLHS-23]
- System Construction [CLHS-24]
- Environment [CLHS-25]
- Glossary [CLHS-26]
- Appendix [CLHS-a]
- X3J13 Issue Index [CLHS-ic]
- II. Internals of the CLISP Implementation
- Overview of CLISP's Garbage Collection
- The CLISP bytecode specification
- III. Extensions
- Extensions-1: Platform independent Extensions
- Extensions-1.1. Saving an Image
- Extensions-1.2. Quitting CLISP
- Extensions-1.3. Internationalization
- Extensions-1.4. Encodings
- Extensions-1.5. Defining new kinds of Streams
- Extensions-1.6. Weak Pointers
- Extensions-1.7. Finalization
- Extensions-1.8. The Prompt
- Extensions-1.9. Maximum ANSI CL compliance
- Extensions-1.10. Additional Fancy Macros
- Extensions-1.11. Customizing CLISP behavior.
- Extensions-2: Platform specific Extensions
- Extensions-2.1. Random Screen Access
- Extensions-2.2. External Modules
- Extensions-2.3. The Foreign Function Call Facility
- Extensions-2.4. The Amiga Foreign Function Call Facility
- Extensions-2.5. ARexx
- Extensions-2.6. Socket Streams
- Extensions-2.7. System Calls
- Extensions-2.8. Quickstarting delivery with CLISP
- Extensions-2.9. Application delivery with CLISP
- Extensions-2.10. Shell, Pipes and Printing
- Extensions-2.11. Directory Access
- Extensions-2.12. Other
- GNU Free Documentation License
- References
These notes discuss the CLISP implementation of Common Lisp by
andDr Bruno Haible
Louisenstraße 103
Bad Homburg
D-61348 Germany
http://clisp.cons.org/~haible
The current maintainers areDr Michael Stoll
Westerwaldweg 22
Remagen-Oberwinter
D-53424 Germany
http://www.math.uni-duesseldorf.de/home/stoll
andDr Bruno Haible
Dr Sam Steingold
<sds@clisp.cons.org>
http://clisp.cons.org/~sds
This implementation is mostly conforming to the [ANSI CL standard] available on-line as the [Common Lisp HyperSpec] (but the printed ANSI document remains the authoritative source of information). [ANSI CL standard] supersedes the earlier specifications [CLtL1] and [CLtL2].
The first part of these notes is indexed in parallel to the [Common Lisp HyperSpec] and documents the differences between the CLISP implementation of Common Lisp and the [ANSI CL standard].
The second part documents the CLISP garbage-collection (for developers only) and the bytecodes generated by the compiler (i.e., what is printer by DISASSEMBLE).
The third part documents the CLISP extensions.
I. Chapters or the [Common Lisp HyperSpec]
- Table of Contents
- Introduction [CLHS-1]
- Syntax [CLHS-2]
- Evaluation and Compilation [CLHS-3]
- Types and Classes [CLHS-4]
- Data and Control Flow [CLHS-5]
- Iteration [CLHS-6]
- Objects [CLHS-7]
- Structures [CLHS-8]
- Conditions [CLHS-9]
- Symbols [CLHS-10]
- Packages [CLHS-11]
- Numbers [CLHS-12]
- Characters [CLHS-13]
- Conses [CLHS-14]
- Arrays [CLHS-15]
- Strings [CLHS-16]
- Sequences [CLHS-17]
- Hash Tables [CLHS-18]
- Filenames [CLHS-19]
- Files [CLHS-20]
- Streams [CLHS-21]
- Printer [CLHS-22]
- Reader [CLHS-23]
- System Construction [CLHS-24]
- Environment [CLHS-25]
- Glossary [CLHS-26]
- Appendix [CLHS-a]
- X3J13 Issue Index [CLHS-ic]
Introduction [CLHS-1]
Special Symbols [CLHS-1.4.1.3]
The final delimiter of an interactive stream: On UNIX, the user has to type Control-D at the beginning of a line. On DOS or Win32, the user has to type Control-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 end-of-stream 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 contain the class STRUCTURE-OBJECT instead of the class STANDARD-OBJECT.
Symbols in the Package "COMMON-LISP" [CLHS-1.9]
The 11 symbols missing from the "COMMON-LISP" package (out of 978 specified by the [ANSI CL standard]):
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.
Backquote [CLHS-2.4.6]
The backquote read macro also works when nested. Example:
(EVAL ``(,#'(LAMBDA () ',a) ,#'(LAMBDA () ',b))) = (EVAL `(list #'(LAMBDA () ',a) #'(LAMBDA () ',b))) = (EVAL (list 'list (list 'function (list 'lambda nil (list 'quote a))) (list 'function (list 'lambda nil (list 'quote b))))) |
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:
Table 1. Additional reader macros
| Macro | Meaning |
|---|---|
| #, | load-time evaluation |
| #Y | function objects and file EXT:ENCODINGs |
| #"" | 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, compiled functions (both of type COMPILED-FUNCTION) and interpreted functions (of type FUNCTION).
Evaluation [CLHS-3.1]
Introduction to Environments [CLHS-3.1.1]
EXT:THE-ENVIRONMENT. As in Scheme, the macro (EXT:THE-ENVIRONMENT) returns the current lexical environment. This works only in interpreted code and is not compilable!
(EXT:EVAL-ENV form &OPTIONAL env). 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 Macros [CLHS-3.2.2.1]
Compiler macros are expanded in the compiled code only, and ignored by the interpreter.
Declarations [CLHS-3.3]
The declarations (TYPE type variable ...), (FTYPE type function ...), (OPTIMIZE (quality value) ...) are ignored by the interpreter and the compiler.
The [ANSI CL standard] declaration (OPTIMIZE (debug ...)) is legal.
The [ANSI CL standard] declaration (IGNORABLE variable ...) affects the variable binding for the variable variable. 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) |
(LET ((x 0)) (FLET ((inc () (DECLARE (compile)) (INCF x)) (dec () (DECF x))) (VALUES #'inc #'dec))) |
The type assertion (THE value-type form) enforces a type check in interpreted code. No type check is done in compiled code. See also the EXT:ETHE macro.
Lambda Lists [CLHS-3.4]
Boa Lambda Lists [CLHS-3.4.6]
The initial value of an &AUX variable in a boa lambda list is the value of the corresponding slot's initial form.
The Evaluation and Compilation Dictionary [CLHS-3.8]
Declaration SPECIAL
(PROCLAIM '(SPECIAL variable)) 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.
Types and Classes [CLHS-4]
Types [CLHS-4.2]
Type Specifiers [CLHS-4.2.3]
The general form of the COMPLEX type specifier is (COMPLEX type-of-real-part type-of-imaginary-part). The type specifier (COMPLEX type) is equivalent to (COMPLEX type type).
The [ANSI CL standard] type specifier (REAL low high) denotes the real numbers between low and high.
DEFTYPE lambda lists are subject to destructuring (nested lambda lists are allowed, as in DEFMACRO) and may contain a &WHOLE marker, but not an &ENVIRONMENT marker.
(ext:type-expand typespec &OPTIONAL 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
FIXNUM, BIGNUM, RATIONAL, SHORT-FLOAT, SINGLE-FLOAT, DOUBLE-FLOAT, LONG-FLOAT, COMPLEX
(ARRAY element-type dimensions), (SIMPLE-ARRAY element-type dimensions)
(VECTOR T size), (SIMPLE-VECTOR size)
(STRING size), (SIMPLE-STRING size)
(BASE-STRING size), (SIMPLE-BASE-STRING size)
(BIT-VECTOR size), (SIMPLE-BIT-VECTOR size)
STREAM, FILE-STREAM, SYNONYM-STREAM, BROADCAST-STREAM, CONCATENATED-STREAM, TWO-WAY-STREAM, ECHO-STREAM, STRING-STREAM
PACKAGE, HASH-TABLE, READTABLE, PATHNAME, LOGICAL-PATHNAME, RANDOM-STATE, BYTE
special-operator, load-time-eval, SYMBOL-MACRO, EXT:ENCODING, FFI:FOREIGN-POINTER, foreign-address, foreign-variable, foreign-function
EXT: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 EXPORTed from the package "CLOS". "COMMON-LISP" uses (as in USE-PACKAGE) "CLOS" and EXT:RE-EXPORTs all its exported symbols. Since the default :USE argument to MAKE-PACKAGE is "COMMON-LISP" (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 "COMMON-LISP") (SHADOW symbol "CL-NO-CLOS")) (DO-SYMBOLS (symbol "CL-NO-CLOS") (EXPORT symbol "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 standard]
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 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 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 "COMMON-LISP-USER" and "COMMON-LISP" because of the [ANSI CL standard] 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 and STRUCTURE-OBJECT. It is not called on other objects, like CONSes and NUMBERs, 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:
Defining Classes [CLHS-4.3.2]
DEFCLASS supports the :METACLASS 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.
The Types and Classes Dictionary [CLHS-4.4]
Function COERCE
FIXNUM is not a character designator in [ANSI CL standard], although CODE-CHAR provides an obvious venue to COERCE a FIXNUM to a CHARACTER. When CUSTOM:*COERCE-FIXNUM-CHAR-ANSI* is NIL, CLISP COERCEs FIXNUMs to CHARACTERs via CODE-CHAR. When CUSTOM:*COERCE-FIXNUM-CHAR-ANSI* is non-NIL, FIXNUMs cannot be COERCEd to CHARACTERs.
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, AND, OR, 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))
|
(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 CHARACTERs and FIXNUMs as EQL does. No unnecessary copies are made of CHARACTERs and NUMBERs. Nevertheless, one should use EQL as it is more portable across Common Lisp implementations.
(let ((x y)) (eq x x)) always returns T, regardless of y.
Function SYMBOL-FUNCTION
(SETF (SYMBOL-FUNCTION symbol) object) requires object to be either a function, a SYMBOL-FUNCTION return value or a lambda expression. The lambda expression is thereby immediately converted to a FUNCTION.
Macro SETF
Additional places:
- FUNCALL
(SETF (FUNCALL #'symbol ...) object) and (SETF (FUNCALL 'symbol ...) object) are equivalent to (SETF (symbol ...) object).
- PROGN
- LOCALLY
- IF
- GET-DISPATCH-MACRO-CHARACTER
(SETF (GET-DISPATCH-MACRO-CHARACTER ...) ...) calls SET-DISPATCH-MACRO-CHARACTER.
- EXT:LONG-FLOAT-DIGITS:
(SETF (EXT:LONG-FLOAT-DIGITS) digits) sets the default mantissa length of long floats to digits bits.
- VALUES-LIST
(SETF (VALUES-LIST list) form) is equivalent to (VALUES-LIST (SETF list (MULTIPLE-VALUE-LIST form)))
&KEY markers in DEFSETF lambda lists are supported, but the corresponding keywords must appear literally in the program text.
(GET-SETF-EXPANSION form &OPTIONAL env), (EXT:GET-SETF-METHOD form &OPTIONAL env), and (EXT:GET-SETF-METHOD-MULTIPLE-VALUE form &OPTIONAL env) receive as optional argument env the environment necessary for macro expansions. In DEFINE-SETF-EXPANDER and EXT:DEFINE-SETF-METHOD lambda lists, one can specify &ENVIRONMENT 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.
Special Operator FUNCTION
(FUNCTION symbol) returns the local function definition established by FLET or LABELS, if it exists, otherwise the global function definition.
(SPECIAL-OPERATOR-P symbol) returns NIL or T. If it returns T, then (SYMBOL-FUNCTION symbol) returns the (useless) special operator handler.
Macro DEFINE-SYMBOL-MACRO
The macro DEFINE-SYMBOL-MACRO establishes SYMBOL-MACROs with global scope (as opposed to SYMBOL-MACROs defined with SYMBOL-MACROLET, which have local scope): (DEFINE-SYMBOL-MACRO symbol expansion).
The function EXT:SYMBOL-MACRO-EXPAND tests for a SYMBOL-MACRO: If symbol is defined as a SYMBOL-MACRO, (EXT:SYMBOL-MACRO-EXPAND symbol) 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
Table 1. Platform dependent
| CPU type | 16-bit CPU | 32-bit CPU | 64-bit CPU |
|---|---|---|---|
| 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))))
|
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 option should contain a lambda expression (LAMBDA (structure stream depth) (declare (ignore depth)) ...) This lambda expression 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* must be respected.
The value of *PRINT-PRETTY* should not and cannot be respected, since the pretty-print mechanism is not accessible from outside.
The value of *PRINT-CIRCLE* 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* is respected by WRITE, PRIN1, PRINC, PRINT, PPRINT, FORMAT instructions ~A, ~S, ~W, and FORMAT instructions ~R, ~D, ~B, ~O, ~X, ~F, ~E, ~G, ~$ 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* must be respected, especially if you are outputting an arbitrary number of components.
The value of *PRINT-READABLY* must be respected. Remember that the values of *PRINT-ESCAPE*, *PRINT-LEVEL*, *PRINT-LENGTH* are ignored if *PRINT-READABLY* is true. The value of *PRINT-READABLY* is respected by PRINT-UNREADABLE-OBJECT, WRITE, PRIN1, PRINC, PRINT, PPRINT, FORMAT instructions ~A, ~S, ~W, and FORMAT instructions ~R, ~D, ~B, ~O, ~X, ~F, ~E, ~G, ~$ with not-numerical arguments. Therefore *PRINT-READABLY* will be respected automatically if only these functions are used for printing objects.
You need not worry about the values of *PRINT-BASE*, *PRINT-RADIX*, *PRINT-CASE*, *PRINT-GENSYM*, *PRINT-ARRAY*, CUSTOM:*PRINT-CLOSURE*, CUSTOM:*PRINT-RPARS*, CUSTOM:*PRINT-INDENT-LISTS*.
The :INHERIT option is exactly like :INCLUDE 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}*) executes the forms. When a continuable error occurs, no message is printed. Instead, the CONTINUE restart is invoked.
EXT:APPEASE-CERRORS. The macro (EXT:APPEASE-CERRORS {form}*) executes the forms. 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}*) executes the forms. When a non-continuable error or a Control-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}*) is therefore equivalent to (RESTART-CASE (PROGN {form}*) {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 {restart-clause}*)
- restart-clause ::==
(restart-name arglist {keyword-value}* {form}*) | (restart-name {keyword-value}* arglist {form}*)
COMPUTE-RESTARTS. COMPUTE-RESTARTS and FIND-RESTART behave as specified in [ANSI CL standard]: 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.
Packages [CLHS-11]
The [ANSI CL standard] packages present in CLISP
- "COMMON-LISP"
with the nicknames "CL" and "LISP"
- "COMMON-LISP-USER"
with the nicknames "CL-USER" and "USER"
- "KEYWORD"
with the nickname ""
The package "COMMON-LISP" EXPORTs only those symbols from the [ANSI CL standard] that are actually implemented.
Constraints on the COMMON-LISP Package for Conforming Programs - package locking [CLHS-11.1.2.1.2]
EXT: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 (EXT:PACKAGE-LOCK package) returns the generalized boolean indicating whether the package is locked. A package (or list thereof) can be locked using (SETF (EXT:PACKAGE-LOCK package-or-list) T). CLISP locks its system packages (specified in the variable CUSTOM:*SYSTEM-PACKAGE-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 () ...))
|
The COMMON-LISP-USER Package [CLHS-11.1.2.2]
The "COMMON-LISP-USER" package uses the "COMMON-LISP" and "EXT" packages.
Implementation-Defined Packages [CLHS-11.1.2.4]
The following additional packages exist:
Implementation-Defined Packages
- "CLOS"
EXPORTs all CLOS specific symbols, including some additional symbols.
- "SYSTEM"
has the nicknames "SYS" and "COMPILER", and has no EXPORTed symbols. It defines many system internals.
- "EXT"
is the umbrella package for all extensions: it imports and EXT:RE-EXPORTs 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 "COMMON-LISP"): "LDAP" "POSIX" "SOCKET" "GSTREAM" "GRAY" "I18N" "CUSTOM".
- "CHARSET"
defines and EXPORTs some character sets, for use with EXT:MAKE-ENCODING and as :EXTERNAL-FORMAT argument.
- "FFI"
implements the foreign function interface. Some platforms only.
- "SCREEN"
defines an API for random screen access. Some platforms only.
All pre-existing packages except "COMMON-LISP-USER" 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 argument is ("COMMON-LISP").
MAKE-PACKAGE accepts a keyword argument :CASE-SENSITIVE. Similarly, DEFPACKAGE accepts an option :CASE-SENSITIVE. 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*), though.
Function EXT:RE-EXPORT
The function (EXT: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 is the disjoint union of the types REAL and COMPLEX ("exhaustive partition")
The type REAL is the disjoint union of the types RATIONAL and FLOAT.
The type RATIONAL is the disjoint union of the types INTEGER and RATIO.
The type INTEGER is the disjoint union of the types FIXNUM and BIGNUM.
The type FLOAT is the disjoint union of the types SHORT-FLOAT, SINGLE-FLOAT, DOUBLE-FLOAT and LONG-FLOAT.
Number Concepts [CLHS-12.1]
Byte Operations on Integers [CLHS-12.1.1.3.2]
Byte specifiers are objects of built-in type BYTE, not INTEGERs.
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, SINGLE-FLOAT, DOUBLE-FLOAT and LONG-FLOAT:
Table 1. floating point types
| type | sign | mantissa | exponent | comment |
|---|---|---|---|---|
| SHORT-FLOAT | 1 bit | 16+1 bits | 8 bits | immediate |
| SINGLE-FLOAT | 1 bit | 23+1 bits | 8 bits | IEEE format |
| DOUBLE-FLOAT | 1 bit | 52+1 bits | 11 bits | IEEE format |
| LONG-FLOAT | 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. (Common Lisp does not make use of these features.) This is why *FEATURES* 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 (EXT:LONG-FLOAT-DIGITS). It can be set by (SETF (EXT:LONG-FLOAT-DIGITS) n), where n is a positive integer. E.g., (SETF (EXT:LONG-FLOAT-DIGITS) 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 CUSTOM:*FLOATING-POINT-CONTAGION-ANSI*. When it is non-NIL, contagion is done as per the [ANSI CL standard]: SHORT-FLOAT → SINGLE-FLOAT → DOUBLE-FLOAT → LONG-FLOAT.
- Rationale:
See it pragmatically: save what you can and let others worry about the rest.
- Brief:
Common Lisp 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 standard] 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 Common Lisp has no way of knowing the actual accuracy, [ANSI CL standard] (and all the other standard engineering programming languages, like C, 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 CUSTOM:*WARN-ON-FLOATING-POINT-CONTAGION* is for), but one should not be penalized for this too harshly.
When CUSTOM:*FLOATING-POINT-CONTAGION-ANSI* 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 → LONG-FLOAT → DOUBLE-FLOAT → SINGLE-FLOAT → SHORT-FLOAT (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 PI) PI) 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 PI) happens to be used, the long precision should not propagate throughout all the intermediate values. Otherwise, the long result would look precise, but its accuracy is only that of a short float; furthermore much computation time would be lost by calculating with long floats when only short floats would be needed.
CUSTOM:*WARN-ON-FLOATING-POINT-CONTAGION*. If the variable CUSTOM:*WARN-ON-FLOATING-POINT-CONTAGION* 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 INTEGER SINGLE-FLOAT), and (COMPLEX type-of-real-part type-of-imaginary-part) in general.
The type specifier (COMPLEX type) is equivalent to (COMPLEX type type).
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 = #C(0.0 3.0) - evaluates to #C(-9.0 0) = -9.0, with x = #C(0 3.0).
The Numbers Dictionary [CLHS-12.2]
UPGRADED-COMPLEX-PART-TYPE. UPGRADED-COMPLEX-PART-TYPE always returns T, since a COMPLEX number in CLISP can always have REALPART and IMAGPART of any type.
CUSTOM:*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 CUSTOM:*DEFAULT-FLOAT-FORMAT*.
EXT:WITHOUT-FLOATING-POINT-UNDERFLOW. The macro (EXT:WITHOUT-FLOATING-POINT-UNDERFLOW {form}*) executes the forms, with errors of type FLOATING-POINT-UNDERFLOW inhibited. Floating point operations will silently return zero instead of signalling an error of type FLOATING-POINT-UNDERFLOW.
Additional Integer Functions
ext:! (ext:! n) returns the factorial of n, n being a nonnegative INTEGER.
ext:exquo. (ext:exquo x y) returns the integer quotient x/y of two integers x,y, and signals an error when the quotient is not integer. (This is more efficient than /.)
ext:xgcd. (ext:xgcd x1 ... xn) returns the values l, k1, ..., kn, where l is the greatest common divisor of the integers x1, ..., xn, and k1, ..., kn are the integer coefficients such that
l = (GCD x1 ... xn) = (+ (* k1 x1) ... (* kn xn)) |
Floating Point
PI. The value of PI is a LONG-FLOAT with the precision given by (EXT:LONG-FLOAT-DIGITS). When this precision is changed, the value of PI is automatically recomputed. Therefore PI is a variable, not a constant.
Float Decoding [CLHS]
FLOAT-RADIX always returns 2.
(FLOAT-DIGITS number digits) coerces number (a real number) to a floating point number with at least digits mantissa digits. The following holds:
(>= (FLOAT-DIGITS (FLOAT-DIGITS number digits)) digits) |
Boolean Operations [CLHS]
Table 2. 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]
Table 3. Platform dependent
| CPU type | 16-bit CPU | 32-bit CPU | 64-bit CPU |
|---|---|---|---|
| MOST-POSITIVE-FIXNUM | 224-1 = 16777215 | 232-1 = 4294967295 | |
| MOST-NEGATIVE-FIXNUM | -224 = -16777216 | -232 = -4294967296 | |
Float Limits [CLHS]
Together with PI, the other long float constants LEAST-NEGATIVE-LONG-FLOAT LEAST-NEGATIVE-NORMALIZED-LONG-FLOAT LEAST-POSITIVE-LONG-FLOAT LEAST-POSITIVE-NORMALIZED-LONG-FLOAT LONG-FLOAT-EPSILON LONG-FLOAT-NEGATIVE-EPSILON MOST-NEGATIVE-LONG-FLOAT MOST-POSITIVE-LONG-FLOAT are recomputed whenever (EXT:LONG-FLOAT-DIGITS) is SETFed. They are variables, not constants.
Characters [CLHS-13]
The characters are ordered according to a superset of the ASCII encoding.
- Platform dependent: DOS, OS/2 platforms only, and only in CLISP built without compile-time flag UNICODE.
More precisely, CLISP uses the IBM PC character set (code page 437):
Here ** are control characters, not graphic characters. (The characters left blank here cannot be represented in this character set).Table 1. the IBM PC character set (code page 437)
#x0 #x1 #x2 #x3 #x4 #x5 #x6 #x7 #x8 #x9 #xA #xB #xC #xD #xE #xF #x00 ** ** ** ** ** ** ** ** ¶ § #x10 ** ** #x20 ! " # $ % & ' ( ) * + , - . / #x30 0 1 2 3 4 5 6 7 8 9 : ; < = > ? #x40 @ A B C D E F G H I J K L M N O #x50 P Q R S T U V W X Y Z [ \ ] ^ _ #x60 ` a b c d e f g h i j k l m n o #x70 p q r s t u v w x y z { | } ~ #x80 Ç ü é â ä à å ç ê ë è ï î ì Ä Å #x90 É æ Æ ô ö ò û ù ÿ Ö Ü ¢ £ ¥ ₧ ƒ #xA0 á í ó ú ñ Ñ ª º ¿ ⌐ NOT ½ ¼ ¡ « » #xB0 ░ ▒ ▓ │ ┤ ╡ ╢ ╖ ╕ ╣ ║ ╗ ╝ ╜ ╛ ┐ #xC0 └ ┴ ┬ ├ ─ ┼ ╞ ╟ ╚ ╔ ╩ ╦ ╠ ═ ╬ ╧ #xD0 ╨ ╤ ╥ ╙ ╘ ╒ ╓ ╛ ╚ ┘ ┌ █ ▄ ▌ ▐ ▀ #xE0 α ß Γ PI Σ σ µ τ Φ Θ Ω δ ∞ φ ∊ ∩ #xF0 ≡ ± ≥ ≤ ⌠ ⌡ ÷ ≍ ° ∙ · √ ⁿ ² ■
- 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:
Here ** are control characters, not graphic characters. (The characters left blank here cannot be represented in this character set).Table 2. the ISO Latin-1 (ISO 8859-1) character set
#x0 #x1 #x2 #x3 #x4 #x5 #x6 #x7 #x8 #x9 #xA #xB #xC #xD #xE #xF #x00 ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** #x10 ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** #x20 ! " # $ % & ' ( ) * + , - . / #x30 0 1 2 3 4 5 6 7 8 9 : ; < = > ? #x40 @ A B C D E F G H I J K L M N O #x50 P Q R S T U V W X Y Z [ \ ] ^ _ #x60 ` a b c d e f g h i j k l m n o #x70 p q r s t u v w x y z { | } ~ #x80 #x90 #xA0 ¡ ¢ £ ¤ ¥ ¦ § ¨ © ª « NOT ® ¯ #xB0 ° ± ² ³ ´ µ ¶ · ¸ ¹ º » ¼ ½ ¾ ¿ #xC0 À Á Â Ã Ä Å Æ Ç È É Ê Ë Ì Í Î Ï #xD0 Ð Ñ Ò Ó Ô Õ Ö × Ø Ù Ú Û Ü Ý Þ ß #xE0 à á â ã ä å æ ç è é ê ë ì í î ï #xF0 ð ñ ò ó ô õ ö ÷ ø ù ú û ü ý þ ÿ
- Platform dependent: NeXTstep platforms only, and only in CLISP built without compile-time flag UNICODE.
More precisely, CLISP uses the NeXTstep character set:
Here ** are control characters, not graphic characters. (The characters left blank here cannot be represented in this character set).Table 3. the NeXTstep character set
#x0 #x1 #x2 #x3 #x4 #x5 #x6 #x7 #x8 #x9 #xA #xB #xC #xD #xE #xF #x00 ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** #x10 ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** ** #x20 ! " # $ % & ' ( ) * + , - . / #x30 0 1 2 3 4 5 6 7 8 9 : ; < = > ? #x40 @ A B C D E F G H I J K L M N O #x50 P Q R S T U V W X Y Z [ \ ] ^ _ #x60 ` a b c d e f g h i j k l m n o #x70 p q r s t u v w x y z { | } ~ #x80 À Á Â Ã Ä Å Ç È É Ê Ë Ì Í Î Ï #x90 Ð Ñ Ò Ó Ô Õ Ö Ù Ú Û Ü Ý Þ µ × ÷ #xA0 © ¡ ¢ £ ⁄ ¥ ƒ § ¤ ’ “ « ‹ › fi fl #xB0 ® – † ‡ · ¦ ¶ • ‚ „ ” » … ‰ NOT ¿ #xC0 ¹ ˋ ´ ^ ˜ ¯ ˘ ˙ ¨ ² ˚ ¸ ³ ˝ ˛ ˇ #xD0 — ± ¼ ½ ¾ à á â ã ä å ç è é ê ë #xE0 ì Æ í ª î ï ð ñ Ł Ø Œ º ò ó ô õ #xF0 ö æ ù ú û ı ü ý ł ø œ ß þ ÿ
Table 5. The following are semi-standard characters:
| character | code |
|---|---|
| #\Backspace | #x08 |
| #\Tab | #x09 |
| #\Linefeed | #x0A |
| #\Page | #x0C |
| #\Return | #x0D |
#\Newline is the line terminator.
Table 7. Additional syntax for characters with code from #x00 to #x1F:
| character | code |
|---|---|
| #\^@ | #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 SYS::INPUT-CHARACTER representing either a character with font and bits, or a keystroke. The following functions work with objects of types CHARACTER and SYS::INPUT-CHARACTER. Note that EQL or EQUAL cannot be used to compare objects of type SYS::INPUT-CHARACTER.
- ext:char-font-limit = 16
The system uses only font 0.
- ext:char-bits-limit = 16
Table 8. The following bits are defined:
key value :CONTROL EXT:CHAR-CONTROL-BIT :META EXT:CHAR-META-BIT :SUPER EXT:CHAR-SUPER-BIT :HYPER EXT:CHAR-HYPER-BIT - (ext:char-font object)
returns the font of a CHARACTER or SYS::INPUT-CHARACTER.
- (ext:char-bits object)
returns the bits of a CHARACTER or SYS::INPUT-CHARACTER.
- (ext:make-char char [bits [font]])
returns a new SYS::INPUT-CHARACTER, or NIL if such a character cannot be created.
- (ext:char-bit object name)
- (ext:set-char-bit object name newvalue)
returns a new SYS::INPUT-CHARACTER with the named bit set or unset, depending on the boolean newvalue.
- Platform dependent: UNIX, DOS, OS/2, Win32, Acorn platforms only.
The system itself uses this SYS::INPUT-CHARACTER type only to mention special keys and Control/Alternate/Shift key status on return from (READ-CHAR EXT:*KEYBOARD-INPUT*).
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, for which the upper case mapping uc and the lower case mapping lc have the following properties:
uc and lc are different
c is one of uc and lc
the upper case mapping of uc and of lc is uc
the lower case mapping of uc and of lc is lc
The titlecase property of UNICODE characters has no equivalent in Common Lisp.
Numeric Characters [CLHS-13.1.4.4]
The numeric characters are those UNICODE characters which are defined as digits by the UNICODE standard.
Treatment of Newline during Input and Output [CLHS-13.1.8]
Newlines are written according to the stream's EXT:ENCODING, see the function STREAM-EXTERNAL-FORMAT and the description of EXT:ENCODINGs, in particular, line terminators. The default behavior is as follows:
When reading from a file, CR/LF is converted to #\Newline (the usual convention on DOS), and CR not followed by LF is converted to #\Newline 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.
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.
Table 9. 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 are equivalent to CHARACTER.
The graphic characters have been described above.
The standard characters are #\Newline and the graphic characters with a code between 32 and 126 (inclusive).
The alphabetic characters are these characters:
ABCDEFGHIJKLMNOPQRSTUVWXYZ
abcdefghijklmnopqrstuvwxyz
ÇüéâäàåçêëèïîìÄÅÉæÆôöòûùÿÖÜßáíóúñѪºãõØøÀÃÕ 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
(EXT:CHAR-WIDTH char). returns the number of screen columns occupied by char. 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 EXT:STRING-WIDTH.
platform-dependent characters
The characters that are not graphic chars and the space character have names:
Table 10. Platform dependent: Amiga platforms only.
| code | char | ||
|---|---|---|---|
| (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) | #\Newline | #\Linefeed | #\Lf |
| (CODE-CHAR #x0B) | #\Vt | ||
| (CODE-CHAR #x0C) | #\Page | #\Ff | |
| (CODE-CHAR #x0D) | #\Return | #\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 |
Table 11. Platform dependent: DOS, OS/2, Win32 platforms only.
| code | char | |
|---|---|---|
| (CODE-CHAR #x00) | #\Null | |
| (CODE-CHAR #x07) | #\Bell | |
| (CODE-CHAR #x08) | #\Backspace | #\Rubout |
| (CODE-CHAR #x09) | #\Tab | |
| (CODE-CHAR #x0A) | #\Newline | #\Linefeed |
| (CODE-CHAR #x0B) | #\Code11 | |
| (CODE-CHAR #x0C) | #\Page | |
| (CODE-CHAR #x0D) | #\Return | |
| (CODE-CHAR #x1A) | #\Code26 | |
| (CODE-CHAR #x1B) | #\Escape | |
| (CODE-CHAR #x20) | #\Space |
Table 12. Platform dependent: UNIX, Acorn, platforms only.
| code | char | ||
|---|---|---|---|
| (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) | #\Newline | #\Nl | #\Linefeed |
| (CODE-CHAR #x0B) | #\Vt | ||
| (CODE-CHAR #x0C) | #\Page | #\Np | |
| (CODE-CHAR #x0D) | #\Return | #\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
Table 13. obsolete constants
| constant | value |
|---|---|
| EXT:CHAR-CONTROL-BIT | 1 |
| EXT:CHAR-META-BIT | 2 |
| EXT:CHAR-SUPER-BIT | 4 |
| EXT:CHAR-HYPER-BIT | 8 |
Conses [CLHS-14]
The Conses Dictionary [CLHS-14.2]
Functions MAPCAR, MAPCAN, MAPLIST, MAPCON, ...
Function EXT:MAPCAP
The function EXT:MAPCAP is like MAPCAN, except that it concatenates the resulting lists with APPEND instead of NCONC:
(EXT:MAPCAP function x1 ... xn) == (APPLY #'APPEND (MAPCAR function x1 ... xn))
(Actually a bit more efficient that this would have been.)
Function EXT:MAPLAP
The function EXT:MAPLAP is like MAPCON, except that it concatenates the resulting lists with APPEND instead of NCONC:
(EXT:MAPLAP function x1 ... xn) == (APPLY #'APPEND (MAPLIST function x1 ... xn))
(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-TYPEs (UNSIGNED-BYTE 2), (UNSIGNED-BYTE 4), (UNSIGNED-BYTE 8), (UNSIGNED-BYTE 16), (UNSIGNED-BYTE 32), and, of course, BIT and CHARACTER.
Array Elements [CLHS-15.1.1]
Table 1. Platform dependent
| CPU type | 16-bit CPU | 32-bit CPU | 64-bit CPU |
|---|---|---|---|
| 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 standard] 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<=. Therefore diphthongs do not obey the usual national rules. Example: o < oe < z < ö.
The Strings Dictionary [CLHS-16.2]
Functions on strings
(EXT:STRING-WIDTH string). returns the number of screen columns occupied by string. This is computed as the sum of all EXT:CHAR-WIDTHs of all of the string's characters.
Sequences [CLHS-17]
The Sequences Dictionary [CLHS-17.3.]
Functions NREVERSE & NRECONC
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, the CDR parts are modified. If the argument is a VECTOR with fill pointer, the fill pointer is lowered and the remaining elements are compacted below the new fill pointer.
CUSTOM:*SEQUENCE-COUNT-ANSI*. Contrary to the [ANSI CL standard] issue 283 RANGE-OF-COUNT-KEYWORD:NIL-OR-INTEGER, negative :COUNT keyword arguments are not allowed unless you set CUSTOM:*SEQUENCE-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 standard] issue.
Functions SORT & STABLE-SORT
SORT and STABLE-SORT have two additional keywords :START and :END:
(SORT sequence predicate &KEY :KEY :START :END) (STABLE-SORT sequence predicate &KEY :KEY :START :END) |
SORT and STABLE-SORT are identical. They implement the mergesort algorithm. Worst case complexity: O(n*log(n)) comparisons, where n is the LENGTH of the subsequence bounded by the :START and :END 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 :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 is weak: the key is not considered accessible for the garbage-collection purposes, i.e., if is is only accessible in the weak HASH-TABLE, it is garbage-collected and removed from the weak HASH-TABLE.
The SETFable predicate EXT:HASH-TABLE-WEAK-P checks whether the HASH-TABLE is weak.
Just like EXT:WEAK-POINTERs, weak HASH-TABLEs cannot be printed readably.
Additional Macros
Macro EXT:DOHASH
For iteration through a hash table, a macro EXT:DOHASH similar to DOLIST, can be used instead of MAPHASH:
(EXT:DOHASH (key-var value-var hash-table-form [resultform]) {declaration}* {tag|form}*) |
EXT:DOHASH forms are "iteration 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, OS/2, 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.
Table 1. 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, :WILD-INFERIORS is allowed, no wildcard characters are allowed in the strings, and name EQ NIL may not be allowed either.
- Platform dependent: Amiga platforms only.
Pathname components
- host
always NIL
- device
NIL or a SIMPLE-STRING
- directory
Table 2. (startpoint . subdirs)
element values meaning startpoint :RELATIVE | :ABSOLUTE subdirs () | (subdir . subdirs) subdir :WILD-INFERIORS ** or ..., all subdirectories subdir SIMPLE-STRING, may contain wildcard characters ? and * (may also be specified as :WILD) subdir :PARENT / instead of subdir/ - name
NIL or SIMPLE-STRING, may contain wildcard characters ? and * (may also be specified as :WILD)
- type
NIL or SIMPLE-STRING, may contain wildcard characters ? and * (may also be specified as :WILD)
- version
always NIL (may also be specified as :WILD or :NEWEST)
Constraint: startpoint = :RELATIVE only if device is NIL. If the device is specified, the pathname must be absolute!
An Amiga filename is split into name and type.
Case is ignored in the strings on comparison. No case conversions are performed.
Table 3. 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 ':' ]
- subdir ::==
[ <empty> | name ]
- pathname ::==
device { subdir '/' }* name
Table 6. Examples
String Device Directory our pathname 'c:foo' 'C' device->foo "c" (:ABSOLUTE "foo") 'c:foo/' 'C' device->foo "c" (:ABSOLUTE "foo") 'c:foo/bar' 'C' device->foo->bar "c" (:ABSOLUTE "foo" "bar") 'c:/foo' 'C' device->up->foo "c" (:ABSOLUTE :PARENT "foo") 'c:' 'C' device "c" (:ABSOLUTE) :foo current device->root->foo NIL (:ABSOLUTE "foo") foo current device->foo NIL (:RELATIVE "foo") '/foo' current device->up->foo NIL (:RELATIVE :PARENT "foo") '//foo/bar' current device->up->up->foo->bar NIL (:RELATIVE :PARENT :PARENT "foo" "bar") \ current device NIL (:RELATIVE) Appending a / to a path string that is non-empty and does not end with : or / does not change its meaning. This / must be appended before another non-empty component can be appended. But appending a / to a path string that is empty or ends with : or / means going up to the parent directory!
We interpret any path string that is empty or ends with : or / as pathname of a directory (with both name and type being NIL).
- Platform dependent: UNIX platforms only.
Pathname components
- host
always NIL
- device
always NIL
- directory
Table 7. (startpoint . subdirs)
element values meaning startpoint :RELATIVE | :ABSOLUTE subdirs () | (subdir . subdirs) subdir :WILD-INFERIORS ** or ..., all subdirectories subdir SIMPLE-STRING, may contain wildcard characters ? and * (may also be specified as :WILD) - name
NIL or SIMPLE-STRING, may contain wildcard characters ? and * (may also be specified as :WILD)
- type
NIL or SIMPLE-STRING, may contain wildcard characters ? and * (may also be specified as :WILD)
- version
always NIL (may also be specified as :WILD or :NEWEST)
A UNIX filename is split into name and type.
- Platform dependent: OS/2 platforms only.
Pathname components
- host
always NIL
- device
NIL or :WILD or A|...|Z
- directory
Table 9. (startpoint . subdirs)
element values meaning startpoint :RELATIVE | :ABSOLUTE subdirs () | (subdir . subdirs) subdir :WILD-INFERIORS ** or ..., all subdirectories subdir SIMPLE-STRING, may contain wildcard characters ? and * (may also be specified as :WILD) - name
NIL or SIMPLE-STRING, may contain wildcard characters ? and * (may also be specified as :WILD)
- type
NIL or SIMPLE-STRING, may contain wildcard characters ? and * (may also be specified as :WILD)
- version
always NIL (may also be specified as :WILD or :NEWEST)
An OS/2 filename is split into name and type.
Table 10. 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 \ one may use /, as usual for DOS calls.
- Platform dependent: Win32 platforms only.
Pathname components
- host
NIL or SIMPLE-STRING, wildcard characters may occur but don't act as wildcards
- device
NIL or :WILD or A|...|Z
- directory
Table 11. (startpoint . subdirs)
element values meaning startpoint :RELATIVE | :ABSOLUTE subdirs () | (subdir . subdirs) subdir :WILD-INFERIORS ** or ..., all subdirectories subdir SIMPLE-STRING, may contain wildcard characters ? and * (may also be specified as :WILD) - name
NIL or SIMPLE-STRING, may contain wildcard characters ? and * (may also be specified as :WILD)
- type
NIL or SIMPLE-STRING, may contain wildcard characters ? and * (may also be specified as :WILD)
- version
always NIL (may also be specified as :WILD or :NEWEST)
If host is non-NIL, device must be NIL.
A Win32 filename is split into name and type.
Table 12. 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 \ one may use /, as usual for DOS calls.
If host is non-NIL and the directory's startpoint is not :ABSOLUTE, (PARSE-NAMESTRING (NAMESTRING pathname)) will not be the same as pathname.
- Platform dependent: UNIX, Amiga, OS/2, Win32 platforms only.
A filename is split into name and type according to the following rule:
if there is no . in the filename, then the name is everything, type is NIL;
if there is a ., then name is the part before and type 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:
- .
Separates directory specifications, e.g., $.fred
- :
Introduces a drive or disc specification, e.g., :0, :bigdisc. It also marks the end of a file system name, e.g., adfs:
- *
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)
- \
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 . 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 :, 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.
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 #P".lisp" 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
- subdirectory ::==
{ '^' | { legal-wild char }+ } '.'
- filename ::==
{ { legal-wild char }+ | empty }
- filetype ::==
{ '.' { legal-wild char }+ | empty }
- pathname ::==
host device directory filename filetype
Table 16. Examples
String Hostname Device Directory Name Type -net-$.SystemMesg net NIL (:ABSOLUTE :ROOT) SystemMesg NIL net#MJHardy::disc1.mike net#MJHardy disc1 (:ABSOLUTE :ROOT) mike NIL #MJHardy::disc1.mike #MJHardy disc1 (:ABSOLUTE :ROOT) mike NIL -net#MJHardy-:disc1.mike net#MJHardy disc1 (:ABSOLUTE :ROOT) mike NIL -#MJHardy-:disc1.mike #MJHardy disc1 (:ABSOLUTE :ROOT) mike NIL @.foo NIL NIL (:ABSOLUTE :CURRENT) foo NIL foo NIL NIL (:RELATIVE) foo NIL ^. NIL NIL (:RELATIVE :PARENT) NIL NIL @.^. NIL NIL (:ABSOLUTE :CURRENT :PARENT) NIL NIL foo.bar NIL NIL (:RELATIVE) foo bar foo.bar.baz NIL NIL (:RELATIVE "foo") bar baz foo.bar. NIL NIL (:RELATIVE "foo" "bar") NIL NIL foo.@. illegal - From internal representation to RISCOS string
with swapping only of name/type components.
Table 17.
Hostname Device Directory Name Type RISCOS String net disc1 (:ABSOLUTE :ROOT) foo NIL net::disc1.$.foo net#MJ disc1 (:ABSOLUTE :ROOT "foo") bar baz net#MJ::disc1.$.foo.baz.bar adfs 4 (:ABSOLUTE :ROOT "foo" "bar") NIL NIL adfs::4.$.foo.bar NIL disc1 (:ABSOLUTE :ROOT "foo") bar NIL :disc1.$.foo.bar NIL disc1 (:ABSOLUTE :CURRENT) NIL NIL illegal here NIL disc1 (:RELATIVE) NIL NIL :disc1. NIL disc1 NIL NIL NIL :disc1. NIL NIL (:ABSOLUTE :ROOT) foo NIL $.foo NIL NIL (:ABSOLUTE :CURRENT) foo NIL @.foo NIL NIL (:RELATIVE) foo bar bar.foo NIL NIL (:RELATIVE "foo") bar baz foo.baz.bar NIL NIL (:ABSOLUTE :LIBRARY) bar NIL %.bar NIL NIL (:ABSOLUTE :LIBRARY "foo") bar NIL %.foo.bar NIL NIL (:RELATIVE) foo bar bar.foo NIL NIL (:RELATIVE "foo") bar NIL foo.bar NIL NIL (:RELATIVE "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
Pathname components
- host
NIL or a SIMPLE-STRING
- device
NIL or a SIMPLE-STRING
- directory
Table 18. (startpoint . subdirs)
element values startpoint :RELATIVE | :ABSOLUTE anchor anchor :ROOT | :HOME | :CURRENT | :LIBRARY | :PRECIOUS subdirs () | (subdir . subdirs) subdir :PARENT subdir SIMPLE-STRING, may contain wildcard characters ?,# and * - name
SIMPLE-STRING or NIL, may contain wildcard characters ?,# and * (may also be specified as :WILD)
- type
NIL or SIMPLE-STRING, may contain wildcard characters ?,# and * (may also be specified as :WILD)
- version
always NIL (may also be specified as :WILD or :NEWEST)
Constraint: startpoint is not :ABSOLUTE :ROOT only if device is NIL. If the device is specified, the pathname must be :ABSOLUTE :ROOT.
The wildcard characters: * matches any sequence of characters, '#' or ? 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.
Table 19.
[ [drivespec] : ] a letter *|a|...|z|A|...|Z { name [. type] \ } each one a subdirectory, \ may be replaced by / [ 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 * is allowed for :WILD.
- Platform dependent: Amiga platforms only.
see above.
- Platform dependent: UNIX platforms only.
Table 20.
[ / ] / denotes absolute pathnames { name / } each one a subdirectory [ name [. type] ] filename with type (extension) Name and type may be character sequences of any LENGTH (consisting of printing ASCII characters, except /).
- Platform dependent: OS/2, Win32 platforms only.
Table 21.
[ [drivespec] : ] a letter *|a|...|z|A|...|Z { name [. type] \ } each one a subdirectory, \ may be replaced by / [ name [. type] ] filename with type (extension) Name and type may be character sequences of any LENGTH (consisting of printing ASCII characters, except /, \, :).
- Platform dependent: Acorn platforms only.
see above.
NAMESTRING has an optional flag argument: (NAMESTRING pathname T) returns an external notation suitable for passing to the operating system or other programs.
- Platform dependent: DOS, OS/2, Amiga platforms only.
The function USER-HOMEDIR-PATHNAME is not implemented.
- Platform dependent: DOS, OS/2 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 :ALL :MERGE)
If :ALL 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 is specified and NIL, unspecified pieces of to-pathname are not replaced by corresponding pieces of source.
Function PARSE-NAMESTRING
(PARSE-NAMESTRING string &OPTIONAL host defaults &KEY start end junk-allowed) returns a logical pathname only if host is a logical host or host is NIL and defaults is a LOGICAL-PATHNAME. 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 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 CUSTOM:*PARSE-NAMESTRING-ANSI* to non-NIL.
Function MERGE-PATHNAMES
(MERGE-PATHNAMES pathname [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 pathname and default-pathname are relative pathnames, the behavior depends on CUSTOM:*MERGE-PATHNAMES-ANSI*: 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 Common Lisp 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 CUSTOM:*MERGE-PATHNAMES-ANSI* is NIL), but not in implementations that strictly follow the [ANSI CL standard] spec. In fact, the above twice-default = once-default rule holds for all pathnames in CLISP.
When CUSTOM:*MERGE-PATHNAMES-ANSI* is non-NIL, the normal [ANSI CL standard] 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 argument to LOAD-LOGICAL-PATHNAME-TRANSLATIONS is not a defined logical host yet, we proceed as follows:
If both environment variables LOGICAL_HOST_host_FROM and LOGICAL_HOST_host_TO exist, then they define the map of the host.
If the environment variable LOGICAL_HOST_host exists, its value is read from, and the result is passed to (SETF LOGICAL-PATHNAME-TRANSLATIONS).
Variable CUSTOM:*LOAD-LOGICAL-PATHNAME-TRANSLATIONS-DATABASE* is consulted. Its value should be a list of files and/or directories, which are searched for in the CUSTOM:*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 or host.host, in that directory, is READ from once, CMUCL-style, the object read being the LOGICAL-PATHNAME-TRANSLATIONS of the host.
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 EXT:PROBE-DIRECTORY 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 Common Lisp 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.
EXT:PROBE-DIRECTORY. (EXT:PROBE-DIRECTORY pathname) tests whether pathname exists and is a directory. It will, unlike PROBE-FILE or TRUENAME, not signal an error if the parent directory of pathname does not exist.
Function DIRECTORY
(DIRECTORY &OPTIONAL pathname &KEY :full :circle) can run in two modes:
If pathname 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).
ext:dir. (ext:dir &OPTIONAL pathname) is like DIRECTORY, but displays the pathnames instead of returning them. (ext:dir) shows the contents of the current directory.
- Platform dependent: UNIX, Amiga platforms only.
(EXT:CD [pathname]) manages the current directory.
- Platform dependent: Acorn platforms only.
(EXT:CD [pathname]) manages the current host, current device and the current directory.
- Platform dependent: DOS, OS/2, Win32 platforms only.
(EXT:CD [pathname]) manages the current device and the current directory.
ext:default-directory. (ext:default-directory) is equivalent to (EXT:CD). (SETF (ext:default-directory) pathname) is equivalent to (EXT:CD pathname), 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.
- Platform dependent: UNIX, DOS, OS/2 platforms only, and only in CLISP built without compile-time flag NO_READLINE.
Input through *TERMINAL-IO* uses the GNU 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 GNU readline library is not used if standard input and standard output do not both refer to the same terminal.
- Platform dependent: UNIX, Amiga, Acorn, DOS, OS/2, Win32 platforms only.
*TERMINAL-IO* is not the only stream that communicates directly with the user: During execution of the body of a (EXT:WITH-KEYBOARD . body) form, EXT:*KEYBOARD-INPUT* is the stream that reads the keystrokes from the keyboard. It returns every keystroke in detail, as CHARACTER or SYS::INPUT-CHARACTER with the following bits:
This keyboard input is not echoed on the screen. During execution of a (EXT:WITH-KEYBOARD . body) form, no input from *TERMINAL-IO* or any synonymous stream should be requested.- :hyper
(Platform dependent: DOS, OS/2, Win32, Amiga platforms only.) if a non-standard key. These keys are: Function keys, cursor keypads, numeric keypad (Platform dependent: DOS, OS/2, Win32 platforms only). Function keys, cursor keypad (Platform dependent: Amiga platforms only).
- slot key
the key name, for non-standard keys:
- slot char
the ASCII code for standard keys
- :super
(Platform dependent: DOS, OS/2, 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 Control key.
- :meta
(Platform dependent: DOS, OS/2, Win32 platforms only.) if pressed together with the Alternate key.
See also Random Screen Access.
The Streams Dictionary [CLHS-21.2.]
Function STREAM-ELEMENT-TYPE
STREAM-ELEMENT-TYPE is SETFable. The STREAM-ELEMENT-TYPE of STREAMs created by the functions OPEN, EXT:MAKE-PIPE-INPUT-STREAM EXT:MAKE-PIPE-OUTPUT-STREAM, EXT:MAKE-PIPE-IO-STREAM, SOCKET:SOCKET-ACCEPT, SOCKET:SOCKET-CONNECT can be modified, if the old and the new STREAM-ELEMENT-TYPEs are either
both equivalent to CHARACTER or (UNSIGNED-BYTE 8) or (SIGNED-BYTE 8); or
both equivalent to (UNSIGNED-BYTE n) or (SIGNED-BYTE n), with the same n.
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*).
Binary input, READ-BYTE, EXT:READ-INTEGER & EXT:READ-FLOAT
The function (EXT:READ-INTEGER stream element-type &OPTIONAL ENDIANNESS eof-error-p eof-value) reads a multi-byte INTEGER from stream. stream should be a stream with STREAM-ELEMENT-TYPE (UNSIGNED-BYTE 8). element-type should be a type equivalent to (UNSIGNED-BYTE n), where n is a multiple of 8.
(EXT:READ-INTEGER stream element-type) is like (READ-BYTE stream) if stream's STREAM-ELEMENT-TYPE were set to element-type, except that stream's FILE-POSITION will increase by n/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 (EXT:READ-FLOAT stream element-type &OPTIONAL ENDIANNESS eof-error-p eof-value) reads a floating-point number in IEEE binary representation from stream. stream should be a STREAM with STREAM-ELEMENT-TYPE (UNSIGNED-BYTE 8). element-type should be a type equivalent to SINGLE-FLOAT or DOUBLE-FLOAT.
Binary output, WRITE-BYTE, EXT:WRITE-INTEGER & EXT:WRITE-FLOAT
The function (EXT:WRITE-INTEGER integer stream element-type &OPTIONAL ENDIANNESS) writes a multi-byte integer to stream. stream should be a STREAM with STREAM-ELEMENT-TYPE (UNSIGNED-BYTE 8). element-type should be a type equivalent to (UNSIGNED-BYTE n), where n is a multiple of 8.
(EXT:WRITE-INTEGER integer stream element-type) is like (WRITE-BYTE integer stream) if stream's STREAM-ELEMENT-TYPE were set to element-type, except that stream's FILE-POSITION will increase by n/8 instead of 1.
Together with (SETF STREAM-ELEMENT-TYPE), this function permits mixed character/binary output to a STREAM.
The function (EXT:WRITE-FLOAT float stream element-type &OPTIONAL ENDIANNESS) writes a floating-point number in IEEE binary representation to stream. stream should be a STREAM with STREAM-ELEMENT-TYPE (UNSIGNED-BYTE 8). element-type should be a type equivalent to SINGLE-FLOAT or DOUBLE-FLOAT.
Function READ-SEQUENCE
In addition to READ-SEQUENCE, the following two functions are provided:
- EXT:READ-BYTE-SEQUENCE performs multiple READ-BYTE operations:
(EXT:READ-BYTE-SEQUENCE sequence stream &KEY :START :END) fills the subsequence of sequence specified by :START and :END with INTEGERs consecutively read from stream. It returns the index of the first element of sequence that was not updated (= end or < end if the stream reached its end).
This function is especially efficient if sequence is a (VECTOR (UNSIGNED-BYTE 8)) and stream is a file/pipe/socket STREAM with STREAM-ELEMENT-TYPE (UNSIGNED-BYTE 8).
- EXT:READ-CHAR-SEQUENCE performs multiple READ-CHAR operations:
(EXT:READ-CHAR-SEQUENCE sequence stream &KEY :START :END) fills the subsequence of sequence specified by :START and :END with characters consecutively read from stream. It returns the index of the first element of sequence that was not updated (= end or < end if the stream reached its end).
This function is especially efficient if sequence is a STRING and :STREAM is a file/pipe/socket stream with STREAM-ELEMENT-TYPE CHARACTER or an input string stream.
Function WRITE-SEQUENCE
In addition to WRITE-SEQUENCE, the following two functions are provided:
- EXT:WRITE-BYTE-SEQUENCE performs multiple WRITE-BYTE operations:
(EXT:WRITE-BYTE-SEQUENCE sequence :STREAM &KEY :START :END) outputs the INTEGERs of the subsequence of sequence specified by :START and :END to :STREAM. It returns sequence.
This function is especially efficient if sequence is a (VECTOR (UNSIGNED-BYTE 8)) and stream is a file/pipe/socket STREAM with STREAM-ELEMENT-TYPE (UNSIGNED-BYTE 8).
- EXT:WRITE-CHAR-SEQUENCE performs multiple WRITE-CHAR operations:
(EXT:WRITE-CHAR-SEQUENCE sequence :STREAM &KEY :START :END) outputs the characters of the subsequence of sequence specified by :START and :END to :STREAM. It returns sequence.
This function is especially efficient if sequence is a STRING and :STREAM is a file/pipe/socket STREAM with STREAM-ELEMENT-TYPE CHARACTER.
Function FILE-POSITION
- Platform dependent: DOS, OS/2, Win32 platforms only.
FILE-POSITION works on any buffered file stream. When a #\Newline is output to (respectively input from) a file stream, its file position is increased by 2 since #\Newline is encoded as CR/LF in the file.
Function OPEN
OPEN cannot handle files of size ≥ 4 GB.
OPEN accepts three additional keywords: :ELEMENT-TYPE, :EXTERNAL-FORMAT, :BUFFERED.
The acceptable values for the file/pipe/socket functions
- :ELEMENT-TYPE
types equivalent to CHARACTER or (UNSIGNED-BYTE n), (SIGNED-BYTE n); if the stream is to be unbuffered, n must be a multiple of 8.
- :EXTERNAL-FORMAT
EXT:ENCODINGs, (constant) SYMBOLs in the "CHARSET" package, STRINGs (denoting iconv()-based encodings), the symbol :DEFAULT, and the line terminator keywords :UNIX, :MAC, :DOS. The default encoding is CUSTOM:*DEFAULT-FILE-ENCODING*.
- :BUFFERED
for functions that create SOCKET:SOCKET-STREAMs and pipes, :DEFAULT is equivalent to NIL;
for functions that open files, :DEFAULT means that buffered file streams will be returned for regular files and (on Unix) block-devices, and unbuffered file streams for special files.
Printer [CLHS-22]
Multiple Possible Textual Representations [CLHS-22.1.1.1]
CUSTOM:*PRINT-CLOSURE*. An additional variable CUSTOM:*PRINT-CLOSURE* controls whether compiled and interpreted functions (closures) are output in detailed form. If CUSTOM:*PRINT-CLOSURE* is non-NIL, compiled closures are output in #Y syntax which the reader understands. CUSTOM:*PRINT-CLOSURE* is initially set to NIL.
CUSTOM:*PRINT-RPARS*. An additional variable CUSTOM:*PRINT-RPARS* controls the output of the right (closing) parentheses. If CUSTOM:*PRINT-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. CUSTOM:*PRINT-RPARS* is initially set to NIL.
CUSTOM:*PRINT-INDENT-LISTS*. An additional variable CUSTOM:*PRINT-INDENT-LISTS* 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. CUSTOM:*PRINT-INDENT-LISTS* is initially set to 1.
CUSTOM:*PPRINT-FIRST-NEWLINE*. An additional variable CUSTOM:*PPRINT-FIRST-NEWLINE* controls pretty-printing of multi-line objects. When CUSTOM:*PPRINT-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 #\Newline, then a #\Newline is printed before the object. CUSTOM:*PPRINT-FIRST-NEWLINE* has no effect if *PRINT-PRETTY* is NIL. CUSTOM:*PPRINT-FIRST-NEWLINE* is initially set to T.
Printing Other Vectors [CLHS-22.1.3.7]
When *PRINT-READABLY* is true, other vectors are written as follows: if the ARRAY-ELEMENT-TYPE is T, the syntax #(x0 ... xn-1) is used. Otherwise, the syntax #A(element-type dimensions contents) is used.
Printing Other Arrays [CLHS-22.1.3.8]
When *PRINT-READABLY* is true, other arrays are written as follows: if the ARRAY-ELEMENT-TYPE is T, the syntax #rankA contents is used. Otherwise, the syntax #A(element-type dimensions contents) 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*.
Pretty Print Dispatch Table [CLHS-22.2.1.4]
A pprint dispatch table is a CONS of a symbol *PRINT-PPRINT-DISPATCH* an alist which maps types into priorities and print functions. Their use is strongly discouraged because of the performance issues: when *PRINT-PPRINT-DISPATCH* is non-trivial and *PRINT-PRETTY* 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 CUSTOM:*PRINT-CLOSURE*.
Function FORMAT
The FORMAT instruction ~W is similar to ~A and ~S, but avoids binding of *PRINT-ESCAPE*. (FORMAT stream "~W" object) is equivalent to (WRITE object :STREAM stream).
The FORMAT instruction ~! is similar to ~/, but avoids putting a function name into a string. Thus, even if the function is not interned in the "COMMON-LISP-USER" package, you might not need to specify the package.
(FORMAT stream "~args!" function object) is equivalent to (FUNCALL function stream object colon-modifier-p atsign-modifier-p args).
FORMAT ~R and FORMAT ~:R 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 ~:@C does not output the character itself, only the instruction how to type the character.
For FORMAT ~E and FORMAT ~G, the value of *READ-DEFAULT-FLOAT-FORMAT* does not matter if *PRINT-READABLY* is true.
FORMAT ~T can determine the current column of any built-in stream.
pathnames
Pathnames are printed as follows: If *PRINT-ESCAPE* is NIL, only the namestring is printed; otherwise it is printed with #P"" syntax, as per [ANSI CL standard] Issue PRINT-READABLY-BEHAVIOR:CLARIFY. But, if *PRINT-READABLY* is true, we are in trouble as #P"" is ambiguous (which is verboten when *PRINT-READABLY* is true), while being mandated by the [ANSI CL standard]. Therefore, in this case, CLISP's behavior is determined by the value of CUSTOM:*PRINT-PATHNAMES-ANSI*: when it is NIL, we print pathnames like this: #-CLISP #P"" #+CLISP #S(PATHNAME ...). Otherwise, when the variable CUSTOM:*PRINT-PATHNAMES-ANSI* 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* 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 memory image (which you should never do anyway!)
If *PRINT-READABLY* is true, *READ-DEFAULT-FLOAT-FORMAT* has no influence on the way floating point numbers are printed.
- Platform dependent: UNIX, DOS, OS/2, Win32, Acorn platforms only.
*PRINT-PRETTY* is initially NIL but set to T in #P"config.lisp". This makes screen output prettier.
- Platform dependent: Amiga platforms only.
*PRINT-PRETTY* is initially NIL but set to T in #P"config.lisp". This makes unbuffered screen output both much faster and prettier.
*PRINT-ARRAY* is initially set to T.
Reader [CLHS-23]
This is the list of objects whose external representation cannot be meaningfully read in:
Table 1. unreadable objects
| format | meaning |
|---|---|
| #<type ...> | all structures lacking a keyword constructor |
| #<ARRAY type dimensions> | all arrays except strings, if *PRINT-ARRAY* is NIL |
| #<SYSTEM-FUNCTION name> | built-in function written in C |
| #<ADD-ON-SYSTEM-FUNCTION name> | other function written in C |
| #<SPECIAL-OPERATOR name> | special operator handler |
| #<COMPILED-CLOSURE name> | compiled function, if CUSTOM:*PRINT-CLOSURE* is NIL |
| #<CLOSURE name ...> | interpreted function |
| #<FRAME-POINTER #x...> | pointer to a stack frame |
| #<DISABLED POINTER> | frame pointer which has become invalid on exit from the corresponding BLOCK or TAGBODY |
| #<...-STREAM ...> | stream |
| #<PACKAGE name> | package |
| #<HASH-TABLE #x...> | hash table, if *PRINT-ARRAY* is NIL |
| #<READTABLE #x...> | readtable |
| #<SYMBOL-MACRO form> | 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 #x...> | foreign variable (Platform dependent: UNIX, Win32 platforms only.) |
| #<FOREIGN-FUNCTION name #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 |
| #<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 EXT:ENCODING.
#"" is used to read pathnames: #"test.lisp" is the value of (PATHNAME "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 option to MAKE-PACKAGE, IN-PACKAGE and DEFPACKAGE.
Functions LISTEN, READ-CHAR-NO-HANG
- (EXT:READ-CHAR-WILL-HANG-P stream)
EXT:READ-CHAR-WILL-HANG-P 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 (NOT (LISTEN stream)): When the end-of-stream is reached, LISTEN returns NIL, whereas EXT:READ-CHAR-WILL-HANG-P returns NIL.
Note also that EXT:READ-CHAR-WILL-HANG-P is not a good mean to test for end-of-stream: If EXT:READ-CHAR-WILL-HANG-P returns T, this does not mean that the stream will deliver more characters. It only means that it is not known at this moment whether the stream is already at end-of-stream, or will deliver more characters.
Function READ-BYTE
- (EXT:READ-BYTE-LOOKAHEAD stream)
To be called only if stream's STREAM-ELEMENT-TYPE is (UNSIGNED-BYTE 8) or (SIGNED-BYTE 8). Returns T if READ-BYTE would return immediately with an INTEGER result. Returns :EOF if the end-of-stream 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)
To be called only if stream'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 &OPTIONAL eof-error-p eof-value)
To be called only if stream's STREAM-ELEMENT-TYPE is (UNSIGNED-BYTE 8) or (SIGNED-BYTE 8). Returns an INTEGER or does end-of-stream 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 :output-file :listing :WARNINGS :VERBOSE :PRINT) 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
specifies whether warnings should also appear on the screen.
- :VERBOSE
specifies whether error messages should also appear on the screen.
specifies whether an indication which forms are being compiled should appear on the screen.
The variables custom:*compile-warnings*, *COMPILE-VERBOSE*, *COMPILE-PRINT* provide defaults for the :WARNINGS, :VERBOSE, :PRINT keyword arguments, respectively. For each input file (default file type: #P".lisp") the following files are generated:
Table 1.
| File | When | Default file type | Contents |
|---|---|---|---|
| output file | only if :output-file is not NIL | #P".fas" | can be loaded using the LOAD function |
| auxiliary output file | only if :output-file is not NIL | #P".lib" | 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 output file | only if :output-file is not NIL | #p".c" | foreign function interface; this file is deleted if it is empty |
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: CUSTOM:*LOAD-PATHS* is searched for "foo.lisp" and "foo.lib". If the latest such file is a #P".lisp", it is compiled; otherwise the #P".lib" is loaded. The #P".lib" 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 #P"Makefile":
all: foo.fas bar.fas
foo.fas: foo.lisp
clisp -c foo
bar.fas: bar.lisp foo.fas
clisp -c bar
|
bar.fas: bar.lisp foo.fas
clisp -i foo -c bar
|
Function LOAD
LOAD has two additional keywords :ECHO and :COMPILING.
(LOAD filename &KEY :VERBOSE :PRINT :ECHO :IF-DOES-NOT-EXIST :COMPILING)
- :VERBOSE T
causes LOAD to emit a short message that a file is being loaded. The default is *LOAD-VERBOSE*, which is initially T.
- :PRINT T
causes LOAD to print the value of each form. The default is *LOAD-PRINT*, which is initially NIL.
- :ECHO T
causes the input from the file to be echoed to *STANDARD-OUTPUT* (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 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.
CUSTOM:*LOAD-PATHS*. The variable CUSTOM:*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*
The variable *FEATURES* initially contains the symbols
Table 2.
| keyword | meaning |
|---|---|
| :CLISP | the name of this implementation |
| :ANSI-CL | |
| :COMMON-LISP | |
| :INTERPRETER | |
| :COMPILER | |
| :SOCKETS | see SOCKET:SOCKET-STREAMs |
| :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") is supported (Platform dependent: many UNIX, Win32 platforms only) |
| :GETTEXT | if internationalization (see "I18N") using the GNU gettext package is supported (Platform dependent: most UNIX platforms only) |
| :UNICODE | if Unicode (ISO 10646) characters are supported (see "CHARSET") |
| :LOOP | |
| :CLOS | |
| :AMIGA | if hardware = Amiga and operating system = Exec/AmigaDOS |
| :DOS | if hardware = PC (clone) and operating system = DOS |
| :OS/2 | if hardware = PC (clone) and operating system = OS/2 |
| :WIN32 | if hardware = PC (clone) and operating system = Win32 (Windows 95/98/NT/Me/2000) |
| :PC386 | if hardware = PC (clone) with a 386/486/586/686 CPU |
| :UNIX | if operating system = Unix (in this case the hardware 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 read-eval-print loop (called "break loops") which are similar to the main read-eval-print loop 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.
Table 1. Commands common to the main loop, the debugger and the stepper
| command | abbreviation | operation |
|---|---|---|
| Help | :h | prints a list of available commands |
Table 2. Commands common to the debugger and the stepper
| command | abbreviation | operation |
|---|---|---|
| Abort | :a | abort to the next most recent read-eval-print loop |
| Unwind | :uw | abort to the next most recent read-eval-print loop |
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*, 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.
Table 3. Commands common to the debugger and the stepper
| command | abbreviation | operation |
|---|---|---|
| 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:
Table 4. EVAL/APPLY-specific commands
| command | abbreviation | operation |
|---|---|---|
| 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 EXT:*TRACE-VALUES* 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. |
Table 5. Commands specific to the debugger
| command | abbreviation | operation |
|---|---|---|
| Continue | :c | continues evaluation of the program. |
Table 6. Commands specific to the stepper
| command | abbreviation | operation |
|---|---|---|
| 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) 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 EXT:UNCOMPILE
The function EXT:UNCOMPILE does the converse of COMPILE: (EXT:UNCOMPILE function) reverts a compiled function (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. [Common Lisp HyperSpec] access is provided via (ext:clhs symbol &KEY :browser) function, which uses your web browser. browser should be a valid keyword in the custom:*browsers* alist.
Macro TRACE
(TRACE function ...) makes the functions function, ... traced. function should be either a symbol or a list (symbol &KEY :suppress-if :step-if :pre :post :pre-break-if :post-break-if :pre-print :post-print :PRINT), where
- :suppress-if form
no trace output as long as form is true
- :step-if form
invokes the stepper as soon as form is true
- :pre form
evaluates form before calling the function
- :post form
evaluates form after return from the function
- :pre-break-if form
goes into the break loop before calling the function if form is true
- :post-break-if form
goes into the break loop after return from the function if form is true
- :pre-print form
prints the values of form before calling the function
- :post-print form
prints the values of form after return from the function
- :PRINT form
prints the values of form 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
- EXT:*TRACE-VALUES*
after return from the function: the list of return values from the function call
TRACE and UNTRACE are also applicable to functions (SETF symbol) 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 :frontends for INSPECT in CLISP
- :tty
The interaction is conducted via the *TERMINAL-IO* 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: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 EXT:SPACE
The macro EXT:SPACE is like the macro TIME: (EXT:SPACE form) evaluates the form, 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 garbage-collection occurs.
The function EXT:GC starts a global garbage-collection 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 EXT:SPACE macro for more detailed analysis), and the number of garbage-collections performed, if any.
Function ED
The function ED calls the external editor specified by the variable CUSTOM:*EDITOR* (see #P"config.lisp"). 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, OS/2 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.
Table 7. Platform dependent
| platform | Acorn, DOS, OS/2 | 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 #P"config.lisp" file.
- Platform dependent: Amiga, Acorn, DOS, OS/2 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 #P"config.lisp" 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 memory 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.
X3J13 Issue Index [CLHS-ic]
This is the list of ANSI CL issues and their current status in CLISP, i.e., whether CLISP supports code that makes use of the functionality specified by the vote.
- &ENVIRONMENT-BINDING-ORDER:FIRST
yes
- ACCESS-ERROR-NAME
yes
- ADJUST-ARRAY-DISPLACEMENT
yes
- ADJUST-ARRAY-FILL-POINTER
yes
- ADJUST-ARRAY-NOT-ADJUSTABLE:IMPLICIT-COPY
no
- ALLOCATE-INSTANCE:ADD
yes
- ALLOW-LOCAL-INLINE:INLINE-NOTINLINE
yes
- ALLOW-OTHER-KEYS-NIL:PERMIT
yes
- AREF-1D
yes
- ARGUMENT-MISMATCH-ERROR-AGAIN:CONSISTENT
yes
- ARGUMENT-MISMATCH-ERROR-MOON:FIX
yes
- ARGUMENT-MISMATCH-ERROR:MORE-CLARIFICATIONS
yes, except for argument list checking in CALL-NEXT-METHOD in compiled code (items 11,12)
- ARGUMENTS-UNDERSPECIFIED:SPECIFY
yes
- ARRAY-DIMENSION-LIMIT-IMPLICATIONS:ALL-FIXNUM
no
- ARRAY-TYPE-ELEMENT-TYPE-SEMANTICS:UNIFY-UPGRADING
yes for arrays, no for complex numbers
- ASSERT-ERROR-TYPE:ERROR
yes
- ASSOC-RASSOC-IF-KEY
yes
- ASSOC-RASSOC-IF-KEY:YES
yes
- BOA-AUX-INITIALIZATION:ERROR-ON-READ
yes
- BREAK-ON-WARNINGS-OBSOLETE:REMOVE
no
- BROADCAST-STREAM-RETURN-VALUES:CLARIFY-MINIMALLY
no
- BUTLAST-NEGATIVE:SHOULD-SIGNAL
yes
- CHANGE-CLASS-INITARGS:PERMIT
no
- CHAR-NAME-CASE:X3J13-MAR-91
yes
- CHARACTER-LOOSE-ENDS:FIX
yes
- CHARACTER-PROPOSAL:2
yes
- CHARACTER-PROPOSAL:2-1-1
yes
- CHARACTER-PROPOSAL:2-1-2
yes
- CHARACTER-PROPOSAL:2-2-1
yes
- CHARACTER-PROPOSAL:2-3-1
yes
- CHARACTER-PROPOSAL:2-3-2
yes
- CHARACTER-PROPOSAL:2-3-3
yes
- CHARACTER-PROPOSAL:2-3-4
yes
- CHARACTER-PROPOSAL:2-3-5
yes
- CHARACTER-PROPOSAL:2-3-6
yes
- CHARACTER-PROPOSAL:2-4-1
yes
- CHARACTER-PROPOSAL:2-4-2
yes
- CHARACTER-PROPOSAL:2-4-3
yes
- CHARACTER-PROPOSAL:2-5-2
yes
- CHARACTER-PROPOSAL:2-5-6
yes
- CHARACTER-PROPOSAL:2-5-7
yes
- CHARACTER-PROPOSAL:2-6-1
yes
- CHARACTER-PROPOSAL:2-6-2
yes
- CHARACTER-PROPOSAL:2-6-3
yes
- CHARACTER-PROPOSAL:2-6-5
yes
- CHARACTER-VS-CHAR:LESS-INCONSISTENT-SHORT
yes
- CLASS-OBJECT-SPECIALIZER:AFFIRM
yes
- CLOS-CONDITIONS-AGAIN:ALLOW-SUBSET
yes
- CLOS-CONDITIONS:INTEGRATE
yes
- CLOS-ERROR-CHECKING-ORDER:NO-APPLICABLE-METHOD-FIRST
yes
- CLOS-MACRO-COMPILATION:MINIMAL
yes
- CLOSE-CONSTRUCTED-STREAM:ARGUMENT-STREAM-ONLY
yes
- CLOSED-STREAM-OPERATIONS:ALLOW-INQUIRY
yes
- COERCING-SETF-NAME-TO-FUNCTION:ALL-FUNCTION-NAMES
yes
- COLON-NUMBER
yes
- COMMON-FEATURES:SPECIFY
yes
- COMMON-TYPE:REMOVE
yes
- COMPILE-ARGUMENT-PROBLEMS-AGAIN:FIX
yes
- COMPILE-FILE-HANDLING-OF-TOP-LEVEL-FORMS:CLARIFY
yes
- COMPILE-FILE-OUTPUT-FILE-DEFAULTS:INPUT-FILE
yes
- COMPILE-FILE-PACKAGE
yes
- COMPILE-FILE-PATHNAME-ARGUMENTS:MAKE-CONSISTENT
yes
- COMPILE-FILE-SYMBOL-HANDLING:NEW-REQUIRE-CONSISTENCY
yes
- COMPILED-FUNCTION-REQUIREMENTS:TIGHTEN
yes
- COMPILER-DIAGNOSTICS:USE-HANDLER
no
- COMPILER-LET-CONFUSION:ELIMINATE
yes
- COMPILER-VERBOSITY:LIKE-LOAD
yes
- COMPILER-WARNING-STREAM
yes
- COMPLEX-ATAN-BRANCH-CUT:TWEAK
yes
- COMPLEX-ATANH-BOGUS-FORMULA:TWEAK-MORE
yes
- COMPLEX-RATIONAL-RESULT:EXTEND
yes
- COMPUTE-APPLICABLE-METHODS:GENERIC
yes
- CONCATENATE-SEQUENCE:SIGNAL-ERROR
yes
- CONDITION-ACCESSORS-SETFABLE:NO
yes
- CONDITION-RESTARTS:BUGGY
yes
- CONDITION-RESTARTS:PERMIT-ASSOCIATION
yes, except for (6)
- CONDITION-SLOTS:HIDDEN
yes
- CONS-TYPE-SPECIFIER:ADD
yes
- CONSTANT-CIRCULAR-COMPILATION:YES
yes
- CONSTANT-COLLAPSING:GENERALIZE
yes
- CONSTANT-COMPILABLE-TYPES:SPECIFY
yes
- CONSTANT-FUNCTION-COMPILATION:NO
no
- CONSTANT-MODIFICATION:DISALLOW
yes
- CONSTANTP-DEFINITION:INTENTIONAL
yes
- CONSTANTP-ENVIRONMENT:ADD-ARG
yes
- CONTAGION-ON-NUMERICAL-COMPARISONS:TRANSITIVE
yes
- COPY-SYMBOL-COPY-PLIST:COPY-LIST
yes
- COPY-SYMBOL-PRINT-NAME:EQUAL
yes
- DATA-IO:ADD-SUPPORT
yes for *PRINT-READABLY*, *READ-EVAL* and WITH-STANDARD-IO-SYNTAX, no for everything else
- DATA-TYPES-HIERARCHY-UNDERSPECIFIED
yes
- DEBUGGER-HOOK-VS-BREAK:CLARIFY
no
- DECLARATION-SCOPE:NO-HOISTING
no
- DECLARE-ARRAY-TYPE-ELEMENT-REFERENCES:RESTRICTIVE
yes
- DECLARE-FUNCTION-AMBIGUITY:DELETE-FTYPE-ABBREVIATION
yes
- DECLARE-MACROS:FLUSH
no
- DECLARE-TYPE-FREE:LEXICAL
yes
- DECLS-AND-DOC
??
- DECODE-UNIVERSAL-TIME-DAYLIGHT:LIKE-ENCODE
yes
- DEFCONSTANT-SPECIAL:NO
yes
- DEFGENERIC-DECLARE:ALLOW-MULTIPLE
yes
- DEFINE-COMPILER-MACRO:X3J13-NOV89
yes
- DEFINE-CONDITION-SYNTAX:INCOMPATIBLY-MORE-LIKE-DEFCLASS+EMPHASIZE-READ-ONLY
yes
- DEFINE-METHOD-COMBINATION-BEHAVIOR:CLARIFY
no
- DEFINING-MACROS-NON-TOP-LEVEL:ALLOW
no
- DEFMACRO-BLOCK-SCOPE:EXCLUDES-BINDINGS
yes
- DEFMACRO-LAMBDA-LIST:TIGHTEN-DESCRIPTION
yes
- DEFMETHOD-DECLARATION-SCOPE:CORRESPONDS-TO-BINDINGS
yes
- DEFPACKAGE:ADDITION
yes
- DEFSTRUCT-CONSTRUCTOR-KEY-MIXTURE:ALLOW-KEY
yes
- DEFSTRUCT-CONSTRUCTOR-OPTIONS:EXPLICIT
yes
- DEFSTRUCT-CONSTRUCTOR-SLOT-VARIABLES:NOT-BOUND
no (furthermore it gets hairy when applied to BOA constructors)
- DEFSTRUCT-COPIER-ARGUMENT-TYPE:RESTRICT
yes
- DEFSTRUCT-COPIER:ARGUMENT-TYPE
yes
- DEFSTRUCT-DEFAULT-VALUE-EVALUATION:IFF-NEEDED
yes
- DEFSTRUCT-INCLUDE-DEFTYPE:EXPLICITLY-UNDEFINED
yes
- DEFSTRUCT-PRINT-FUNCTION-AGAIN:X3J13-MAR-93
yes
- DEFSTRUCT-PRINT-FUNCTION-INHERITANCE:YES
yes
- DEFSTRUCT-REDEFINITION:ERROR
yes
- DEFSTRUCT-SLOTS-CONSTRAINTS-NAME:DUPLICATES-ERROR
yes
- DEFSTRUCT-SLOTS-CONSTRAINTS-NUMBER
yes
- DEFTYPE-DESTRUCTURING:YES
yes
- DEFTYPE-KEY:ALLOW
yes
- DEFVAR-DOCUMENTATION:UNEVALUATED
yes
- DEFVAR-INIT-TIME:NOT-DELAYED
yes
- DEFVAR-INITIALIZATION:CONSERVATIVE
yes
- DEPRECATION-POSITION:LIMITED
yes
- DESCRIBE-INTERACTIVE:NO
yes
- DESCRIBE-UNDERSPECIFIED:DESCRIBE-OBJECT
yes
- DESTRUCTIVE-OPERATIONS:SPECIFY
yes
- DESTRUCTURING-BIND:NEW-MACRO
yes
- DISASSEMBLE-SIDE-EFFECT:DO-NOT-INSTALL
yes
- DISPLACED-ARRAY-PREDICATE:ADD
yes
- DO-SYMBOLS-BLOCK-SCOPE:ENTIRE-FORM
yes
- DO-SYMBOLS-DUPLICATES
yes
- DOCUMENTATION-FUNCTION-BUGS:FIX
no
- DOCUMENTATION-FUNCTION-TANGLED:REQUIRE-ARGUMENT
no
- DOTIMES-IGNORE:X3J13-MAR91
yes
- DOTTED-LIST-ARGUMENTS:CLARIFY
yes
- DOTTED-MACRO-FORMS:ALLOW
yes
- DRIBBLE-TECHNIQUE
yes
- DYNAMIC-EXTENT-FUNCTION:EXTEND
yes
- DYNAMIC-EXTENT:NEW-DECLARATION
yes
- EQUAL-STRUCTURE:MAYBE-STATUS-QUO
no for EQUALP on hash tables, yes for everything else
- ERROR-TERMINOLOGY-WARNING:MIGHT
yes
- EVAL-OTHER:SELF-EVALUATE
yes
- EVAL-TOP-LEVEL:LOAD-LIKE-COMPILE-FILE
yes, except maybe if LOAD :COMPILING T
- EVAL-WHEN-NON-TOP-LEVEL:GENERALIZE-EVAL-NEW-KEYWORDS
no
- EVAL-WHEN-OBSOLETE-KEYWORDS:X3J13-MAR-1993
no
- EVALHOOK-STEP-CONFUSION:FIX
yes
- EVALHOOK-STEP-CONFUSION:X3J13-NOV-89
yes
- EXIT-EXTENT-AND-CONDITION-SYSTEM:LIKE-DYNAMIC-BINDINGS
yes
- EXIT-EXTENT:MINIMAL
yes, actually implement MEDIUM
- EXPT-RATIO:P.211
yes
- EXTENSIONS-POSITION:DOCUMENTATION
yes
- EXTERNAL-FORMAT-FOR-EVERY-FILE-CONNECTION:MINIMUM
no
- EXTRA-RETURN-VALUES:NO
yes
- FILE-OPEN-ERROR:SIGNAL-FILE-ERROR
no
- FIXNUM-NON-PORTABLE:TIGHTEN-DEFINITION
no
- FLET-DECLARATIONS
yes
- FLET-DECLARATIONS:ALLOW
yes
- FLET-IMPLICIT-BLOCK:YES
yes
- FLOAT-UNDERFLOW:ADD-VARIABLES
yes
- FLOATING-POINT-CONDITION-NAMES:X3J13-NOV-89
yes
- FORMAT-ATSIGN-COLON
yes
- FORMAT-COLON-UPARROW-SCOPE
yes
- FORMAT-COMMA-INTERVAL
yes
- FORMAT-E-EXPONENT-SIGN:FORCE-SIGN
yes
- FORMAT-OP-C
yes
- FORMAT-PRETTY-PRINT:YES
yes, except that ~F, ~E, ~G, ~$ also bind *PRINT-BASE* to 10 and *PRINT-RADIX* to NIL
- FORMAT-STRING-ARGUMENTS:SPECIFY
yes
- FUNCTION-CALL-EVALUATION-ORDER:MORE-UNSPECIFIED
yes
- FUNCTION-COMPOSITION:JAN89-X3J13
yes
- FUNCTION-DEFINITION:JAN89-X3J13
yes
- FUNCTION-NAME:LARGE
yes
- FUNCTION-TYPE
yes
- FUNCTION-TYPE-ARGUMENT-TYPE-SEMANTICS:RESTRICTIVE
yes
- FUNCTION-TYPE-KEY-NAME:SPECIFY-KEYWORD
yes
- FUNCTION-TYPE-REST-LIST-ELEMENT:USE-ACTUAL-ARGUMENT-TYPE
yes
- FUNCTION-TYPE:X3J13-MARCH-88
yes
- GENERALIZE-PRETTY-PRINTER:UNIFY
no
- GENERIC-FLET-POORLY-DESIGNED:DELETE
yes
- GENSYM-NAME-STICKINESS:LIKE-TEFLON
yes
- GENTEMP-BAD-IDEA:DEPRECATE
yes
- GET-MACRO-CHARACTER-READTABLE:NIL-STANDARD
yes
- GET-SETF-METHOD-ENVIRONMENT:ADD-ARG
yes
- HASH-TABLE-ACCESS:X3J13-MAR-89
yes
- HASH-TABLE-KEY-MODIFICATION:SPECIFY
yes
- HASH-TABLE-PACKAGE-GENERATORS:ADD-WITH-WRAPPER
no
- HASH-TABLE-REHASH-SIZE-INTEGER
yes
- HASH-TABLE-SIZE:INTENDED-ENTRIES
yes
- HASH-TABLE-TESTS:ADD-EQUALP
yes
- IEEE-ATAN-BRANCH-CUT:SPLIT
yes
- IGNORE-USE-TERMINOLOGY:VALUE-ONLY
yes
- IMPORT-SETF-SYMBOL-PACKAGE
no
- IN-PACKAGE-FUNCTIONALITY:MAR89-X3J13
yes
- IN-SYNTAX:MINIMAL
yes
- INITIALIZATION-FUNCTION-KEYWORD-CHECKING
??
- ISO-COMPATIBILITY:ADD-SUBSTRATE
yes
- JUN90-TRIVIAL-ISSUES:11
yes
- JUN90-TRIVIAL-ISSUES:14
yes
- JUN90-TRIVIAL-ISSUES:24
yes
- JUN90-TRIVIAL-ISSUES:25
yes
- JUN90-TRIVIAL-ISSUES:27
- JUN90-TRIVIAL-ISSUES:3
yes
- JUN90-TRIVIAL-ISSUES:4
yes
- JUN90-TRIVIAL-ISSUES:5
yes
- JUN90-TRIVIAL-ISSUES:9
yes
- KEYWORD-ARGUMENT-NAME-PACKAGE:ANY
yes
- LAST-N
yes
- LCM-NO-ARGUMENTS:1
yes
- LEXICAL-CONSTRUCT-GLOBAL-DEFINITION:UNDEFINED
yes
- LISP-PACKAGE-NAME:COMMON-LISP
yes
- LISP-SYMBOL-REDEFINITION-AGAIN:MORE-FIXES
yes
- LISP-SYMBOL-REDEFINITION:MAR89-X3J13
yes
- LOAD-OBJECTS:MAKE-LOAD-FORM
no
- LOAD-TIME-EVAL:R**2-NEW-SPECIAL-FORM
obsolete
- LOAD-TIME-EVAL:R**3-NEW-SPECIAL-FORM
yes, except for macro expansion at compile time
- LOAD-TRUENAME:NEW-PATHNAME-VARIABLES
yes
- LOCALLY-TOP-LEVEL:SPECIAL-FORM
yes
- LOOP-AND-DISCREPANCY:NO-REITERATION
yes
- LOOP-FOR-AS-ON-TYPO:FIX-TYPO
yes
- LOOP-INITFORM-ENVIRONMENT:PARTIAL-INTERLEAVING-VAGUE
no
- LOOP-MISCELLANEOUS-REPAIRS:FIX
yes
- LOOP-NAMED-BLOCK-NIL:OVERRIDE
yes
- LOOP-PRESENT-SYMBOLS-TYPO:FLUSH-WRONG-WORDS
yes
- LOOP-SYNTAX-OVERHAUL:REPAIR
yes
- MACRO-AS-FUNCTION:DISALLOW
yes
- MACRO-DECLARATIONS:MAKE-EXPLICIT
yes
- MACRO-ENVIRONMENT-EXTENT:DYNAMIC
yes
- MACRO-FUNCTION-ENVIRONMENT
obsolete
- MACRO-FUNCTION-ENVIRONMENT:YES
yes
- MACRO-SUBFORMS-TOP-LEVEL-P:ADD-CONSTRAINTS
no
- MACROEXPAND-HOOK-DEFAULT:EXPLICITLY-VAGUE
yes
- MACROEXPAND-HOOK-INITIAL-VALUE:IMPLEMENTATION-DEPENDENT
yes
- MACROEXPAND-RETURN-VALUE:TRUE
yes
- MAKE-LOAD-FORM-CONFUSION:REWRITE
no
- MAKE-LOAD-FORM-SAVING-SLOTS:NO-INITFORMS
no
- MAKE-PACKAGE-USE-DEFAULT:IMPLEMENTATION-DEPENDENT
yes
- MAP-INTO:ADD-FUNCTION
yes
- MAPPING-DESTRUCTIVE-INTERACTION:EXPLICITLY-VAGUE
yes
- METACLASS-OF-SYSTEM-CLASS:UNSPECIFIED
yes
- METHOD-COMBINATION-ARGUMENTS:CLARIFY
no
- METHOD-INITFORM:FORBID-CALL-NEXT-METHOD
no
- MUFFLE-WARNING-CONDITION-ARGUMENT
yes
- MULTIPLE-VALUE-SETQ-ORDER:LIKE-SETF-OF-VALUES
yes
- MULTIPLE-VALUES-LIMIT-ON-VARIABLES:UNDEFINED
yes
- NINTERSECTION-DESTRUCTION
yes
- NINTERSECTION-DESTRUCTION:REVERT
yes
- NOT-AND-NULL-RETURN-VALUE:X3J13-MAR-93
yes
- NTH-VALUE:ADD
yes
- OPTIMIZE-DEBUG-INFO:NEW-QUALITY
yes
- PACKAGE-CLUTTER:REDUCE
no
- PACKAGE-DELETION:NEW-FUNCTION
yes
- PACKAGE-FUNCTION-CONSISTENCY:MORE-PERMISSIVE
yes
- PARSE-ERROR-STREAM:SPLIT-TYPES
yes
- PATHNAME-COMPONENT-CASE:KEYWORD-ARGUMENT
yes
- PATHNAME-COMPONENT-VALUE:SPECIFY
no
- PATHNAME-HOST-PARSING:RECOGNIZE-LOGICAL-HOST-NAMES
yes when CUSTOM:*PARSE-NAMESTRING-ANSI* is non-NIL
- PATHNAME-LOGICAL:ADD
yes
- PATHNAME-PRINT-READ:SHARPSIGN-P
yes
- PATHNAME-STREAM
yes
- PATHNAME-STREAM:FILES-OR-SYNONYM
yes
- PATHNAME-SUBDIRECTORY-LIST:NEW-REPRESENTATION
yes
- PATHNAME-SYMBOL
no
- PATHNAME-SYNTAX-ERROR-TIME:EXPLICITLY-VAGUE
yes
- PATHNAME-UNSPECIFIC-COMPONENT:NEW-TOKEN
no
- PATHNAME-WILD:NEW-FUNCTIONS
yes
- PEEK-CHAR-READ-CHAR-ECHO:FIRST-READ-CHAR
yes
- PLIST-DUPLICATES:ALLOW
yes
- PRETTY-PRINT-INTERFACE
yes
- PRINC-READABLY:X3J13-DEC-91
yes
- PRINT-CASE-BEHAVIOR:CLARIFY
yes
- PRINT-CASE-PRINT-ESCAPE-INTERACTION:VERTICAL-BAR-RULE-NO-UPCASE
no
- PRINT-CIRCLE-SHARED:RESPECT-PRINT-CIRCLE
yes
- PRINT-CIRCLE-STRUCTURE:USER-FUNCTIONS-WORK
yes
- PRINT-READABLY-BEHAVIOR:CLARIFY
yes
- PRINTER-WHITESPACE:JUST-ONE-SPACE
yes
- PROCLAIM-ETC-IN-COMPILE-FILE:NEW-MACRO
yes
- PUSH-EVALUATION-ORDER:FIRST-ITEM
yes
- PUSH-EVALUATION-ORDER:ITEM-FIRST
yes
- PUSHNEW-STORE-REQUIRED:UNSPECIFIED
yes
- QUOTE-SEMANTICS:NO-COPYING
yes
- RANGE-OF-COUNT-KEYWORD:NIL-OR-INTEGER
yes, when CUSTOM:*SEQUENCE-COUNT-ANSI* is non-NIL; otherwise negative :COUNT values are not allowed.
- RANGE-OF-START-AND-END-PARAMETERS:INTEGER-AND-INTEGER-NIL
yes
- READ-AND-WRITE-BYTES:NEW-FUNCTIONS
yes
- READ-CASE-SENSITIVITY:READTABLE-KEYWORDS
yes
- READ-MODIFY-WRITE-EVALUATION-ORDER:DELAYED-ACCESS-STORES
no
- READ-SUPPRESS-CONFUSING:GENERALIZE
yes, except that READ-DELIMITED-LIST still constructs a list
- READER-ERROR:NEW-TYPE
yes
- REAL-NUMBER-TYPE:X3J13-MAR-89
yes
- RECURSIVE-DEFTYPE:EXPLICITLY-VAGUE
yes
- REDUCE-ARGUMENT-EXTRACTION
yes
- REMF-DESTRUCTION-UNSPECIFIED:X3J13-MAR-89
yes
- REQUIRE-PATHNAME-DEFAULTS-AGAIN:X3J13-DEC-91
yes
- REQUIRE-PATHNAME-DEFAULTS-YET-AGAIN:RESTORE-ARGUMENT
yes, except that REQUIRE wants a pathname, not a list of pathnames
- REQUIRE-PATHNAME-DEFAULTS:ELIMINATE
superseded by REQUIRE-PATHNAME-DEFAULTS-AGAIN:X3J13-DEC-91
- REST-LIST-ALLOCATION:MAY-SHARE
yes
- RESULT-LISTS-SHARED:SPECIFY
yes
- RETURN-VALUES-UNSPECIFIED:SPECIFY
yes
- ROOM-DEFAULT-ARGUMENT:NEW-VALUE
yes
- SELF-MODIFYING-CODE:FORBID
yes
- SEQUENCE-TYPE-LENGTH:MUST-MATCH
yes
- SETF-APPLY-EXPANSION:IGNORE-EXPANDER
no
- SETF-FIND-CLASS:ALLOW-NIL
no
- SETF-FUNCTIONS-AGAIN:MINIMAL-CHANGES
yes
- SETF-GET-DEFAULT:EVALUATED-BUT-IGNORED
yes
- SETF-MACRO-EXPANSION:LAST
yes
- SETF-METHOD-VS-SETF-METHOD:RENAME-OLD-TERMS
yes
- SETF-MULTIPLE-STORE-VARIABLES:ALLOW
yes
- SETF-OF-APPLY:ONLY-AREF-AND-FRIENDS
yes
- SETF-OF-VALUES:ADD
yes
- SETF-SUB-METHODS:DELAYED-ACCESS-STORES
yes
- SHADOW-ALREADY-PRESENT
yes
- SHADOW-ALREADY-PRESENT:WORKS
yes
- SHARP-COMMA-CONFUSION:REMOVE
no
- SHARP-O-FOOBAR:CONSEQUENCES-UNDEFINED
yes
- SHARP-STAR-DELIMITER:NORMAL-DELIMITER
yes
- SHARPSIGN-PLUS-MINUS-PACKAGE:KEYWORD
yes
- SLOT-MISSING-VALUES:SPECIFY
yes
- SLOT-VALUE-METACLASSES:LESS-MINIMAL
yes
- SPECIAL-FORM-P-MISNOMER:RENAME
yes
- SPECIAL-TYPE-SHADOWING:CLARIFY
yes
- STANDARD-INPUT-INITIAL-BINDING:DEFINED-CONTRACTS
yes
- STANDARD-REPERTOIRE-GRATUITOUS:RENAME
yes
- STEP-ENVIRONMENT:CURRENT
yes
- STEP-MINIMAL:PERMIT-PROGN
yes
- STREAM-ACCESS:ADD-TYPES-ACCESSORS
yes
- STREAM-CAPABILITIES:INTERACTIVE-STREAM-P
yes
- STRING-COERCION:MAKE-CONSISTENT
yes
- STRING-OUTPUT-STREAM-BASHING:UNDEFINED
yes
- STRUCTURE-READ-PRINT-SYNTAX:KEYWORDS
yes
- SUBSEQ-OUT-OF-BOUNDS
yes
- SUBSEQ-OUT-OF-BOUNDS:IS-AN-ERROR
yes
- SUBSETTING-POSITION:NONE
yes
- SUBTYPEP-ENVIRONMENT:ADD-ARG
no
- SUBTYPEP-TOO-VAGUE:CLARIFY-MORE
yes
- SXHASH-DEFINITION:SIMILAR-FOR-SXHASH
no
- SYMBOL-MACROLET-DECLARE:ALLOW
yes
- SYMBOL-MACROLET-SEMANTICS:SPECIAL-FORM
yes
- SYMBOL-MACROLET-TYPE-DECLARATION:NO
yes
- SYMBOL-MACROS-AND-PROCLAIMED-SPECIALS:SIGNALS-AN-ERROR
yes
- SYMBOL-PRINT-ESCAPE-BEHAVIOR:CLARIFY
yes
- SYNTACTIC-ENVIRONMENT-ACCESS:RETRACTED-MAR91
yes
- TAGBODY-TAG-EXPANSION:NO
yes
- TAILP-NIL:T
yes
- TEST-NOT-IF-NOT:FLUSH-ALL
yes, but no warning
- THE-AMBIGUITY:FOR-DECLARATION
yes
- THE-VALUES:RETURN-NUMBER-RECEIVED
no
- TIME-ZONE-NON-INTEGER:ALLOW
yes
- TYPE-DECLARATION-ABBREVIATION:ALLOW-ALL
no
- TYPE-OF-AND-PREDEFINED-CLASSES:TYPE-OF-HANDLES-FLOATS
yes
- TYPE-OF-AND-PREDEFINED-CLASSES:UNIFY-AND-EXTEND
yes, except for class METHOD-COMBINATION
- TYPE-OF-UNDERCONSTRAINED:ADD-CONSTRAINTS
yes
- TYPE-SPECIFIER-ABBREVIATION:X3J13-JUN90-GUESS
yes
- UNDEFINED-VARIABLES-AND-FUNCTIONS:COMPROMISE
yes
- UNINITIALIZED-ELEMENTS:CONSEQUENCES-UNDEFINED
yes, could add error checking
- UNREAD-CHAR-AFTER-PEEK-CHAR:DONT-ALLOW
yes
- UNSOLICITED-MESSAGES:NOT-TO-SYSTEM-USER-STREAMS
yes
- VARIABLE-LIST-ASYMMETRY:SYMMETRIZE
yes
- WITH-ADDED-METHODS:DELETE
yes
- WITH-COMPILATION-UNIT:NEW-MACRO
yes
- WITH-OPEN-FILE-DOES-NOT-EXIST:STREAM-IS-NIL
yes
- WITH-OPEN-FILE-SETQ:EXPLICITLY-VAGUE
yes
- WITH-OPEN-FILE-STREAM-EXTENT:DYNAMIC-EXTENT
yes
- WITH-OUTPUT-TO-STRING-APPEND-STYLE:VECTOR-PUSH-EXTEND
yes
- WITH-STANDARD-IO-SYNTAX-READTABLE:X3J13-MAR-91
yes
II. Internals of the CLISP Implementation
- Table of Contents
- Overview of CLISP's Garbage Collection
- The CLISP bytecode specification
Overview of CLISP's Garbage Collection
These are internals, which are of interest only to the CLISP developers. If you are not subscribed to <clisp-devel@lists.sourceforge.net>, this chapter is not for you.Introduction
Knowing that most malloc() implementations are buggy and/or slow, and because CLISP needs to perform garbage collection, CLISP has its own memory management subsystem in files spvw*.d.
Lisp objects in CLISP
Three kinds of storage are distinguished:
CLISP data (the "heap"), i.e. storage which contains Lisp objects and is managed by the garbage collector.
C data (including program text, data, malloc()ed memory)
A CLISP object is one word, containing a tag (partial type information) and either immediate data (e.g. fixnums or short floats) or a pointer to storage. Pointers to C data have tag = machine_type = 0, pointers to CLISP stack have tag = system_type, most other pointers point to CLISP data.
Let us turn to these CLISP objects that consume regular CLISP memory. Every CLISP object has a size which is determined when the object is allocated (using one of the allocate_*() routines). The size can be computed from the type tag and - if necessary - the length field of the object's header. The length field always contains the number of elements of the object. The number of bytes is given by the function objsize().
CLISP objects which contain exactly 2 CLISP objects (i.e. CONSes, COMPLEX numbers, RATIOs) are stored in a separate area and occupy 2 words each. All other CLISP objects have "varying length" (more precisely, not a fixed length) and include a word for garbage collection purposes at their beginning.
The garbage collector is invoked when an allocate_*() request cannot be fulfilled. It marks all objects which are "live" (may be reached from the "roots"), compacts these objects and unmarks them. Non-live objects are lost; their storage is reclaimed.
2-pointer objects are compacted by a simple hole-filling algorithm: fill the most-left object into the most-right hole, and so on, until the objects are contiguous at the right and the hole is contiguous at the left.
Variable-length objects are compacted by sliding them down (their address decreases).
Memory Models
There are 6 memory models. Which one is used, depends on the operating system and is determined at build time.
Memory Models
- SPVW_MIXED_BLOCKS_OPPOSITE
The heap consists of one block of fixed length (allocated at startup). The variable-length objects are allocated from the left, the 2-pointer objects are allocated from the right. There is a hole between them. When the hole shrinks to 0, garbage-collect is invoked. garbage-collect slides the variable-length objects to the left and concentrates the 2-pointer objects at the right end of the block again. When no more room is available, some reserve area beyond the right end of the block is halved, and the 2-pointer objects are moved to the right accordingly.
overview
- (+)
Simple management.
- (+)
No fragmentation at all.
- (-)
The total heap size is limited.
- SPVW_MIXED_BLOCKS_OPPOSITE & TRIVIALMAP_MEMORY
The heap consists of two big blocks, one for variable-length objects and one for 2-pointer objects. The former one has a hole to the right and is extensible to the right, the latter one has a hole to the left and is extensible to the left. Similar to the previous model, except that the hole is unmapped.
overview
- (+)
Total heap size grows depending on the application's needs.
- (+)
No fragmentation at all.
- (*)
Works only when SINGLEMAP_MEMORY is possible as well.
- SPVW_MIXED_BLOCKS_STAGGERED & TRIVIALMAP_MEMORY
The heap consists of two big blocks, one for variable-length objects and one for 2-pointer objects. Both have a hole to the right, but are extensible to the right.
overview
- (+)
Total heap size grows depending on the application's needs.
- (+)
No fragmentation at all.
- (*)
Works only when SINGLEMAP_MEMORY is possible as well.
- SPVW_MIXED_PAGES
The heap consists of many small pages (usually around 8 KB). There are two kinds of pages: one for 2-pointer objects, one for variable-length objects. The set of all pages of a fixed kind is called a "Heap". Each page has its hole (free space) at its end. For every heap, the pages are kept sorted according to the size of their hole, using AVL trees. Garbage collection is invoked when the used space has grown by 25% since the last GC; until that point new pages are allocated from the operating system. The GC compacts the data in each page separately: data is moved to the left. Emptied pages are given back to the OS. If the holes then make up more than 25% of the occupied storage, a second GC turn moves objects across pages, from nearly empty ones to nearly full ones, with the aim to free as many pages as possible.
overview
- (-)
every allocation requires AVL tree operations, thus slower
- (+)
Total heap size grows depending on the application's needs.
- (+)
Works on operating systems which do not provide large contiguous areas.
- SPVW_PURE_PAGES
Just like SPVW_MIXED_PAGES, except that every page contains data of only a single type tag, i.e. there is a Heap for every type tag.
overview
- (-)
every allocation requires AVL tree operations, thus slower
- (+)
Total heap size grows depending on the application's needs.
- (+)
Works on operating systems which do not provide large contiguous areas.
- (-)
More fragmentation because objects of different type never fit into the same page.
- SPVW_PURE_BLOCKS
There is a big block of storage for each type tag. Each of these blocks has its data to the left and the hole to the right, but these blocks are extensible to the right (because there is enough room between them). A garbage collection is triggered when the allocation amount since the last GC reaches 50% of the amount of used space at the last GC, but at least 512 KB. The garbage collection cleans up each block separately: data is moved left.
overview
- (+)
Total heap size grows depending on the application's needs.
- (+)
No 16 MB total size limit.
- (*)
Works only in combination with SINGLEMAP_MEMORY.
In page based memory models, an object larger than a page is the only object carried by its pages. There are no small objects in pages belonging to a big object.
The following combinations of memory model and mmap tricks are possible:
Table 1. With TYPECODES (the number indicates the order in which the respective models have been developed:
| no MAP_MEMORY | TRIVIALMAP_MEMORY | SINGLEMAP_MEMORY | MULTIMAP_MEMORY | GENERATIONAL_GC | |
|---|---|---|---|---|---|
| SPVW_MIXED_BLOCKS_OPPOSITE | 1 | 10 | 2 | 9 | |
| SPVW_MIXED_BLOCKS_STAGGERED | 7 | 8 | |||
| SPVW_PURE_BLOCKS | 5 | 6 | |||
| SPVW_MIXED_PAGES | 3 | ||||
| SPVW_PURE_PAGES | 4 |
The burden of garbage-collection upon the rest of CLISP
Every subroutine marked with can trigger GC may invoke garbage-collect. garbage-collect moves all the CLISP objects and updates the pointers. But the garbage-collect looks only on the STACK and not in the C variables. (Anything else would not be portable.) Therefore at every "unsafe" point, i.e. every call to such a subroutine, all the C variables of type object MUST BE ASSUMED TO BECOME GARBAGE. (Except for objects that are known to be unmovable, e.g. immediate data or Subrs.) Pointers inside CLISP data (e.g. to the characters of a STRING or to the elements of a SIMPLE-VECTOR) become INVALID as well.
The workaround is usually to allocate all the needed CLISP data first and do the rest of the computation with C variables, without calling unsafe routines, and without worrying about garbage-collect.
Foreign Pointers
Pointers to C functions and to malloc()ed data can be hidden in CLISP objects of type machine_type; garbage-collect will not modify its value. But one should not dare to assume that a C stack pointer or the address of a C function in a shared library satisfies the same requirements.
If another pointer is to be viewed as a CLISP object, it is best to box it, e.g. in a SIMPLE-BIT-VECTOR or in an Fpointer (using allocate_fpointer().)
The CLISP bytecode specification
Last modified: 19 September 1998.Introduction
The CLISP compiler compiles Common Lisp programs into instruction codes for a virtual processor. This bytecode is optimized for saving space in the most common cases of Common Lisp programs. The main advantages/drawbacks of this approach, compared to native code compilation, are:
Bytecode compiled programs are a lot smaller than when compiled to native code. This results in better use of CPU caches, and in less virtual memory paging. Users perceive this as good responsiveness.
Maximum execution speed (throughput in tight loops) is limited.
Since no bytecode instructions are provided for "unsafe" operations (like unchecked array accesses, or "fast" CAR/CDR), programs run with all safety checks enabled even when compiled.
Execution speed of a program can easily be understood by looking at the output of the DISASSEMBLE function. A rule of thumb is that every elementary instruction costs 1 time unit, whereas a function call costs 3 to 4 time units.
Needing to do no type inference, the compiler is pretty straightforward and fast. As a consequence, the definition of CLOS generic functions, which needs to compile small pieces of generated code, is not perceived to be slow.
The compiler is independent from the hardware CPU. Different backends, one for each hardware CPU, are not needed. As a consequence, the compiler is fairly small (and would have been easily maintainable if it were written in a less kludgey way...), and it is impossible for the compiler writer to introduce CPU dependent bugs.
The virtual machine
The bytecode can be thought of as being interpreted by a virtual processor. The engine which actually interprets the bytecode (the "implementation of the virtual machine") is actually a C function, but it could as well be a just-in-time compiler which translates a function's bytecode into hardware CPU instructions the first time said function is called.
The virtual machine is a stack machine with two stacks:
This two-stack architecture permits to save an unlimited number of CLISP objects on the STACK (needed for handling of Common Lisp multiple values), without consing. Also, in a world with a compacting no-ambiguous-roots garbage collector, STACK must only hold CLISP objects, and SP can hold all the other data belonging to a frame, which would not fit into STACK without tagging/untagging overhead.
The scope of STACK and SP is only valid for a given function invocation. Whereas the amount of STACK space needed for executing a function (excluding other function calls) is unlimited, the amount of SP space needed is known a priori, at compile time. When a function is called, no relation is specified between the caller's STACK and the callee's STACK, and between the caller's SP and the callee's SP. The bytecode is designed so that outgoing arguments on the caller's STACK can be shared by the caller's incoming arguments area (on the callee's STACK), but a virtual machine implementation may also copy outgoing arguments to incoming arguments instead of sharing them.
The virtual machine has a special data structure, values, containing the "top of stack", specially adapted to Common Lisp multiple values:
The contents of values is short-lived. It does not survive a function call, not even a garbage collection.
The interpretation of some bytecode instructions depends on a constant, jmpbufsize. This is a CPU-dependent number, the value of system::*jmpbuf-size*. In C, it is defined as ceiling(sizeof(jmp_buf),sizeof(void*)).
The structure of compiled functions
A compiled function consists of two objects: The function itself, containing the references to all CLISP objects needed for the bytecode, and a byte vector containing only immediate data, including the bytecode proper.
Typically, the byte vector is about twice as large as the function vector. The separation thus helps the garbage collector (since the byte vector does not need to be scanned for pointers).
A function looks like this (cf. the C type Cclosure):
- name
This is the name of the function, normally a symbol or a list of the form (SETF symbol). It is used for printing the function and for error messages. This field is immutable.
- codevec
This is the byte vector. It is a SIMPLE-BIT-VECTOR (because that's the simplest type in CLISP which contains immediate data -- note that (SIMPLE-VECTOR (UNSIGNED-BYTE 8)) is more complex than this). This field is immutable.
- consts[]
The remaining fields in the function object are references to other CLISP objects. These references are immutable, which is why they are called "constants". (The referenced CLISP objects can be mutable objects, such as conses or vectors, however.)
There is actually one exception to the immutability rule: When a generic function's dispatch code is installed, the codevec and consts fields are destructively modified.
Some of the consts can play special roles. A function looks like this, in more detail:
- name
see above
- codevec
see above
- venv-const*
At most one object, representing the closed-up variables, representing the variables of the lexical environment in which this function was defined. It is a SIMPLE-VECTOR, which looks like this: #(next value1 ... valuen) where value1, ..., valuen are the values of the closed-up variables, and next is either NIL or a SIMPLE-VECTOR having the same structure.
- block-const*
Objects representing closed-up BLOCK tags, representing the BLOCK tags of the lexical environment in which this function was defined. Each is a CONS containing in the CDR part: either a frame pointer to the block frame, or #<DISABLED>. The CAR is the block's name, only for error message purposes.
- tagbody-const*
Objects representing closed-up TAGBODY tags, representing the TAGBODY tags of the lexical environment in which this function was defined. Each is a CONS containing in the CDR part: either a frame pointer to the TAGBODY frame, or #<DISABLED> if the TAGBODY has already been left. The CAR is a SIMPLE-VECTOR containing the names of the TAGBODY tags, only for the error message purposes.
- keyword-const*
If the function was defined with a lambda list containing &KEY, here come the symbols ("keywords"), in their correct order. They are used by the interpreter during function call.
- other-const*
Other objects needed by the function's bytecode.
If venv-const, block-const, tagbody-const are all absent, the function is called autonomous. This is the case if the function does not refer to lexical variables, blocks or tags defined in compile code outside of the function. In particular, it is the case if the function is defined in a null lexical environment.
If some venv-const, block-const, or tagbody-const are present, the function (a "closure") is created at runtime. The compiler only generates a prototype, containing NIL values instead of each venv-const, block-const, tagbody-const. At runtime, a function is created by copying this prototype and replacing the NIL values by the definitive ones.
The list (keyword-const* other-const*) normally does not contain duplicates, because the compiler removes duplicates when possible. (Duplicates can occur nevertheless, through the use of LOAD-TIME-VALUE.)
The codevec looks like this (cf. the C type Codevec):
- spdepth_1 (2 bytes)
The 1st part of the maximal SP depth.
- spdepth_jmpbufsize (2 bytes)
The jmpbufsize part of the maximal SP depth. The maximal SP depth (precomputed by the compiler) is given by spdepth_1 + spdepth_jmpbufsize * jmpbufsize.
- numreq (2 bytes)
Number of required parameters.
- numopt (2 bytes)
Number of optional parameters.
- flags (1 byte)
- bit 0
set if the function has an &REST parameter
- bit 7
set if the function has &KEY parameters
- bit 6
set if the function has &ALLOW-OTHER-KEYS
- bit 4
set if the function is a generic function
- bit 3
set if the function is a generic function and its effective method shall be returned (instead of being executed)
- signature (1 byte)
An abbreviation code depending on numreq, numopt, flags. It is used for speeding up the function call.
- numkey (2 bytes, only if the function has &KEY)
The number of &KEY parameters.
- keyconsts (2 bytes, only if the function has &KEY)
The offset of the keyword-const in the function.
- byte* (any number of bytes)
The bytecode instructions.
The general structure of the instructions
All instructions consist of one byte, denoting the opcode, and some number of operands.
The conversion from a byte (in the range 0..255) to the opcode is performed by lookup in the table contained in the file bytecode.d.
There are the following types of operands, denoted by different letters:
- k, n, m, l
A (nonnegative) numeric operand. The next byte is read. If its bit 7 is zero, then the bits 6..0 give the value (7 bits). If its bit 7 is one, then the bits 6..0 and the subsequent byte together form the value (15 bits).
- b
A (nonnegative) 1-byte operand. The next byte is read and is the value.
- label
A label operand. A signed numeric operand is read: The next byte is read. If its bit 7 is zero, then the bits 6..0 give the value (7 bits, sign-extended). If its bit 7 is one, then the bits 6..0 and the subsequent byte together form the value (15 bits, sign-extended). If the latter 15-bit result is zero, then four more bytes are read and put together (32 bits, sign-extended). Finally, the bytecode pointer for the target is computed as the current bytecode pointer (pointing after the operand just read), plus the signed numeric operand.
The instruction set
Instructions for constants
Table 1. Instructions for constants
| mnemonic | description | semantics |
|---|---|---|
| (NIL) | Load NIL into values. | value1 := NIL, mv_count := 1 |
| (PUSH-NIL n) | Push n NILs into the STACK. | n times do: *--STACK := NIL, values undefined |
| (T) | Load T into values. | value1 := T, mv_count := 1 |
| (CONST n) | Load the function's nth constant into values. | value1 := consts[n], mv_count := 1 |
Instructions for lexical variables
Table 2. Instructions for lexical variables
| mnemonic | description | semantics |
|---|---|---|
| (LOAD n) | Load a directly accessible local variable into values. | value1 := *(STACK+n), mv_count := 1 |
| (LOADI k1 k2 n) | Load an indirectly accessible local variable into values. | k := k1 + jmpbufsize * k2, value1 := *(*(SP+k)+ n), mv_count := 1 |
| (LOADC n m) | Load a closed-up variable, defined in the same function and directly accessible, into values. | value1 := SVREF(*(STACK+n),1+m), mv_count := 1 |
| (LOADV k m) | Load a closed-up variable, defined in an outer function, into values. | v := venv-const, m times do: v := SVREF(v,0), value1 := SVREF(v,m), mv_count := 1 |
| (LOADIC k1 k2 n m) | Load a closed-up variable, defined in the same function and indirectly accessible, into values. | k := k1 + jmpbufsize * k2, value1 := SVREF(*(*(SP+k)+n),1+m), mv_count := 1 |
| (STORE n) | Store values into a directly accessible local variable. | *(STACK+n) := value1, mv_count := 1 |
| (STOREI k1 k2 n) | Store values into an indirectly accessible local variable. | k := k1 + jmpbufsize * k2, *(*(SP+k)+ n) := value1, mv_count := 1 |
| (STOREC n m) | Store values into a closed-up variable, defined in the same function and directly accessible. | SVREF(*(STACK+n),1+m) := value1, mv_count := 1 |
| (STOREV k m) | Store values into a closed-up variable, defined in an outer function. | v := venv-const, m times do: v := SVREF(v,0), SVREF(v,m) := value1, mv_count := 1 |
| (STOREIC k1 k2 n m) | Store values into a closed-up variable, defined in the same function and indirectly accessible. | k := k1 + jmpbufsize * k2, SVREF(*(*(SP+k)+n),1+m) := value1, mv_count := 1 |
Instructions for dynamic variables
Table 3. Instructions for dynamic variables
| mnemonic | description | semantics |
|---|---|---|
| (GETVALUE n) | Load a symbol's value into values. | value1 := symbol-value(consts[n]), mv_count := 1 |
| (SETVALUE n) | Store values into a symbol's value. | symbol-value(consts[n]) := value1, mv_count := 1 |
| (BIND n) | Bind a symbol dynamically. | Bind the value of the symbol consts[n] to value1, implicitly STACK -= 3, values undefined |
| (UNBIND1) | Dissolve one binding frame. | Unbind the binding frame STACK is pointing to, implicitly STACK += 3 |
| (UNBIND n) | Dissolve n binding frames. | n times do: Unbind the binding frame STACK is pointing to, thereby incrementing STACK Thus, STACK += 1+2*n |
| (PROGV) | Bind a set of symbols dynamically to a set of values. | symbols := *STACK++, *--SP := STACK, build a single binding frame binding the symbols in symbols to the values in value1, values undefined |
Instructions for stack operations
Table 4. Instructions for stack operations
| mnemonic | description | semantics |
|---|---|---|
| (PUSH) | Push one object onto the STACK. | *--STACK := value1, values undefined |
| (POP) | Pop one object from the STACK, into values. | value1 := *STACK++, mv_count := 1 |
| (SKIP n) | Restore a previous STACK pointer. Remove n objects from the STACK. | STACK := STACK + n |
| (SKIPI k1 k2 n) | Restore a previous STACK pointer. Remove an unknown number of objects from the STACK. | k := k1 + jmpbufsize * k2, STACK := *(SP+k), SP := SP+k+1 |
| (SKIPSP k1 k2) | Restore a previous SP pointer. | k := k1 + jmpbufsize * k2, SP := SP+k |
Instructions for control flow, jumps
Table 5. Instructions for control flow, jumps
| mnemonic | description | semantics |
|---|---|---|
| (SKIP&RET n) | Clean up the STACK, and return from the function. | STACK := STACK+n, return from the function, returning values. |
| (SKIP&RETGF n) | Clean up the STACK, and return from the generic function. | If bit 3 is set in the function's flags, then STACK := STACK+n, mv_count := 1, and return from the function. Otherwise: if the current function has no &REST argument, then STACK := STACK+n-numreq, apply value1 to the numreq arguments still on the STACK, and return from the function. Else STACK := STACK+n-numreq-1, apply value1 to the numreq arguments and the &REST argument, all still on the STACK, and return from the function. |
| (JMP label) | Jump to label. | PC := label. |
| (JMPIF label) | Jump to label, if value1 is true. | If value1 is not NIL, PC := label. |
| (JMPIFNOT label) | Jump to label, if value1 is false. | If value1 is NIL, PC := label. |
| (JMPIF1 label) | Jump to label and forget secondary values, if value1 is true. | If value1 is not NIL, mv_count := 1, PC := label. |
| (JMPIFNOT1 label) | Jump to label and forget secondary values, if value1 is false. | If value1 is NIL, mv_count := 1, PC := label. |
| (JMPIFATOM label) | Jump to label, if value1 is not a cons. | If value1 is not a cons, PC := label. values undefined |
| (JMPIFCONSP label) | Jump to label, if value1 is a cons. | If value1 is a cons, PC := label. values undefined |
| (JMPIFEQ label) | Jump to label, if value1 is EQ to the top-of-stack. | If eq(value1,*STACK++), PC := label. values undefined |
| (JMPIFNOTEQ label) | Jump to label, if value1 is not EQ to the top-of-stack. | If not eq(value1,*STACK++), PC := label. values undefined |
| (JMPIFEQTO n label) | Jump to label, if the top-of-stack is EQ to a constant. | If eq(*STACK++,consts[n]), PC := label. values undefined |
| (JMPIFNOTEQTO n label) | Jump to label, if the top-of-stack is not EQ to a constant. | If not eq(*STACK++,consts[n]), PC := label. values undefined |
| (JMPHASH n label) | Table-driven jump, depending on value1. | Lookup value1 in the hash table consts[n]. (The hash table's test is either EQ or EQL.) If found, the hash table value is a signed FIXNUM, jump to it: PC := PC + value. Else jump to label. values undefined |
| (JMPHASHV n label) | Table-driven jump, depending on value1, inside a generic function. | Lookup value1 in the hash table SVREF(consts[0],n). (The hash table's test is either EQ or EQL.) If found, the hash table value is a signed FIXNUM, jump to it: PC := PC + value. Else jump to label. values undefined |
| (JSR label) | Subroutine call. | *--STACK := function. Then start interpreting the bytecode at label, with values undefined. When a (RET) is encountered, program execution is resumed at the instruction after (JSR label). |
| (JMPTAIL m n label) | Tail subroutine call. | n >= m. The STACK frame of size n is reduced to size m: {*(STACK+n-m), ..., *(STACK+n-1)} := {*STACK, ..., *(STACK+m-1)}. STACK += n-m. *--STACK := function. Then jump to label, with values undefined. |
Instructions for lexical environment, creation of closures
Table 6. Instructions for lexical environment, creation of closures
| mnemonic | description | semantics |
|---|---|---|
| (VENV) | Load the venv-const into values. | value1 := consts[0], mv_count := 1. |
| (MAKE-VECTOR1&PUSH n) | Create a simple-vector used for closed-up variables. | v := new simple-vector of size n+1. SVREF(v,0) := value1. *--STACK := v. values undefined |
| (COPY-CLOSURE m n) | Create a closure by copying the prototype and filling in the lexical environment. | f := copy-function(consts[m]). For i=0,..,n-1: f_consts[i] := *(STACK+n-1-i). STACK += n. value1 := f, mv_count := 1 |
Instructions for function calls
Table 7. Instructions for function calls
| mnemonic | description | semantics |
|---|---|---|
| (CALL k n) | Calls a constant function with k arguments. | The function consts[n] is called with the arguments *(STACK+k-1), ..., *(STACK+0). STACK += k. The returned values go into values. |
| (CALL0 n) | Calls a constant function with 0 arguments. | The function consts[n] is called with 0 arguments. The returned values go into values. |
| (CALL1 n) | Calls a constant function with 1 argument. | The function consts[n] is called with one argument *STACK. STACK += 1. The returned values go into values. |
| (CALL2 n) | Calls a constant function with 2 arguments. | The function consts[n] is called with two arguments *(STACK+1) and *(STACK+0). STACK += 2. The returned values go into values. |
| (CALLS1 b) | Calls a system function with no &REST. | Calls the system function FUNTAB[b]. The right number of arguments is already on the STACK (including #<UNBOUND>s in place of absent &OPTIONAL or &KEY parameters). The arguments are removed from the STACK. The returned values go into values. |
| (CALLS2 b) | Calls a system function with no &REST. | Calls the system function FUNTAB[256+b]. The right number of arguments is already on the STACK (including #<UNBOUND>s in place of absent &OPTIONAL or &KEY parameters). The arguments are removed from the STACK. The returned values go into values. |
| (CALLSR m b) | Calls a system function with &REST. | Calls the system function FUNTABR[b]. The minimum number of arguments is already on the STACK, and m additional arguments as well. The arguments are removed from the STACK. The returned values go into values. |
| (CALLC) | Calls a computed compiled function with no &KEY. | Calls the compiled function value1. The right number of arguments is already on the STACK (including #<UNBOUND>s in place of absent &OPTIONAL parameters). The arguments are removed from the STACK. The returned values go into values. |
| (CALLCKEY) | Calls a computed compiled function with &KEY. | Calls the compiled function value1. The right number of arguments is already on the STACK (including #<UNBOUND>s in place of absent &OPTIONAL or &KEY parameters). The arguments are removed from the STACK. The returned values go into values. |
| (FUNCALL n) | Calls a computed function. | Calls the function *(STACK+n) with the arguments *(STACK+n-1), ..., *(STACK+0). STACK += n+1. The returned values go into values. |
| (APPLY n) | Calls a computed function with an unknown number of arguments. | Calls the function *(STACK+n) with the arguments *(STACK+n-1), ..., *(STACK+0) and a list of additional arguments value1. STACK += n+1. The returned values go into values. |
Instructions for optional and keyword parameters
Table 8. Instructions for optional and keyword parameters
| mnemonic | description | semantics |
|---|---|---|
| (PUSH-UNBOUND n) | Push n #<UNBOUND>s into the STACK. | n times do: *--STACK := #<UNBOUND>. values undefined |
| (UNLIST n m) | Destructure a proper list. | 0 ≤ m ≤ n. n times do: *--STACK := CAR(value1), value1 := CDR(value1). During the last m iterations, the list value1 may already have reached its end; in this case, *--STACK := #<UNBOUND>. At the end, value1 must be NIL. values undefined |
| (UNLIST* n m) | Destructure a proper or dotted list. | 0 ≤ m ≤ n, n > 0. n times do: *--STACK := CAR(value1), value1 := CDR(value1). During the last m iterations, the list value1 may already have reached its end; in this case, *--STACK := #<UNBOUND>. At the end, after n CDRs, *--STACK := value1. values undefined |
| (JMPIFBOUNDP n label) | Jump to label, if a local variable is not unbound. | If *(STACK+n) is not #<UNBOUND>, value1 := *(STACK+n), mv_count := 1, PC := label. Else: values undefined. |
| (BOUNDP n) | Load T or NIL into values, depending on whether a local variable is bound. | If *(STACK+n) is not #<UNBOUND>, value1 := T, mv_count := 1. Else: value1 := NIL, mv_count := 1. |
| (UNBOUND->NIL n) | If a local variable is unbound, assign a default value NIL to it. | If *(STACK+n) is #<UNBOUND>, *(STACK+n) := NIL. |
Instructions for multiple values
Table 9. Instructions for multiple values
| mnemonic | description | semantics |
|---|---|---|
| (VALUES0) | Load no values into values. | value1 := NIL, mv_count := 0 |
| (VALUES1) | Forget secondary values. | mv_count := 1 |
| (STACK-TO-MV n) | Pop the first n objects from STACK into values. | Load values(*(STACK+n-1),...,*(STACK+0)) into values. STACK += n. |
| (MV-TO-STACK) | Save values on STACK. | Push the mv_count values onto the STACK (in order: value1 comes first). STACK -= mv_count. values undefined |
| (NV-TO-STACK n) | Save n values on STACK. | Push the first n values onto the STACK (in order: value1 comes first). STACK -= n. values undefined |
| (MV-TO-LIST) | Convert multiple values into a list. | value1 := list of values, mv_count := 1 |
| (LIST-TO-MV) | Convert a list into multiple values. | Call the function VALUES-LIST with value1 as argument. The returned values go into values. |
| (MVCALLP) | Start a MULTIPLE-VALUE-CALL invocation. | *--SP := STACK. *--STACK := value1. |
| (MVCALL) | Finish a MULTIPLE-VALUE-CALL invocation. | newSTACK := *SP++. Call the function *(newSTACK-1), passing it *(newSTACK-2), ..., *(STACK+0) as arguments. STACK := newSTACK. The returned values go into values. |
Instructions for BLOCK and RETURN-FROM
Table 10. Instructions for BLOCK and RETURN-FROM
| mnemonic | description | semantics |
|---|---|---|
| (BLOCK-OPEN n label) | Create a BLOCK frame. | Create a BLOCK frame, STACK -= 3, SP -= 2+jmpbufsize. The topmost (third) object in the block frame is CONS(consts[n],frame-pointer) (its block-cons). Upon a RETURN-FROM to this frame, execution will continue at label. |
| (BLOCK-CLOSE) | Dissolve a BLOCK frame. | Dissolve the BLOCK frame at STACK, STACK += 3, SP += 2+jmpbufsize. Mark the block-cons as invalid. |
| (RETURN-FROM n) | Leave a BLOCK whose block-cons is given. | block-cons := consts[n]. If CDR(block-cons) = #<DISABLED>, signal an error. Else CDR(block-cons) is a frame-pointer. Unwind the stack up to this frame, pass it values. |
| (RETURN-FROM-I k1 k2 n) | Leave a BLOCK whose block-cons is indirectly accessible. | k := k1 + jmpbufsize * k2, block-cons := *(*(SP+k)+n). If CDR(block-cons) = #<DISABLED>, signal an error. Else CDR(block-cons) is a frame-pointer. Unwind the stack up to this frame, pass it values. |
Instructions for TAGBODY and GO
Table 11. Instructions for TAGBODY and GO
| mnemonic | description | semantics |
|---|---|---|
| (TAGBODY-OPEN n label1 ... labeln) | Create a tagbody frame. | Fetch consts[n], this is a SIMPLE-VECTOR with m elements, then decode m label operands. Create a TAGBODY frame, STACK -= 3+m, SP -= 1+jmpbufsize. The third object in the tagbody frame is CONS(consts[n],frame-pointer) (the tagbody-cons) Upon a GO to tag label of this frame, execution will continue at labell. values undefined |
| (TAGBODY-CLOSE-NIL) | Dissolve a tagbody frame, and load NIL into values. | Dissolve the tagbody frame at STACK, STACK += 3+m, SP += 1+jmpbufsize. Mark the tagbody-cons as invalid. value1 := NIL, mv_count := 1. |
| (TAGBODY-CLOSE) | Dissolve a tagbody frame. | Dissolve the tagbody frame at STACK, STACK += 3+m, SP += 1+jmpbufsize. Mark the tagbody-cons as invalid. |
| (GO n label) | Jump into a tagbody whose tagbody-cons is given. | tagbody-cons := consts[n]. If CDR(tagbody-cons) = #<DISABLED>, signal an error. Else CDR(tagbody-cons) is a frame-pointer. Unwind the stack up to this frame, pass it the number label. |
| (GO-I k1 k2 n label) | Jump into a tagbody whose tagbody-cons is indirectly accessible. | k := k1 + jmpbufsize * k2, tagbody-cons := *(*(SP+k)+n). If CDR(tagbody-cons) = #<DISABLED>, signal an error. Else CDR(tagbody-cons) is a frame-pointer. Unwind the stack up to this frame, pass it the number label. |
Instructions for CATCH and THROW
Table 12. Instructions for CATCH and THROW
| mnemonic | description | semantics |
|---|---|---|
| (CATCH-OPEN label) | Create a CATCH frame. | Create a CATCH frame, with value1 as tag. STACK -= 3, SP -= 2+jmpbufsize. Upon a THROW to this tag execution continues at label. |
| (CATCH-CLOSE) | Dissolve a CATCH frame. | Dissolve the CATCH frame at STACK. STACK += 3, SP += 2+jmpbufsize. |
| (THROW) | Non-local exit to a CATCH frame. | tag := *STACK++. Search the innermost CATCH frame with tag tag on the STACK, unwind the stack up to it, pass it values. |
Instructions for UNWIND-PROTECT
Table 13. Instructions for UNWIND-PROTECT
| mnemonic | description | semantics |
|---|---|---|
| (UNWIND-PROTECT-OPEN label) | Create an UNWIND-PROTECT frame. | Create an UNWIND-PROTECT frame. STACK -= 2, SP -= 2+jmpbufsize. When the stack will be unwound by a non-local exit, values will be saved on STACK, and execution will be transferred to label. |
| (UNWIND-PROTECT-NORMAL-EXIT) | Dissolve an UNWIND-PROTECT frame, and start the cleanup code. | Dissolve the UNWIND-PROTECT frame at STACK. STACK += 2, SP += 2+jmpbufsize. *--SP := 0, *--SP := 0, *--SP := STACK. Save the values on the STACK, STACK -= mv_count. |
| (UNWIND-PROTECT-CLOSE) | Terminate the cleanup code. | newSTACK := *SP++. Load values(*(newSTACK-1), ..., *(STACK+0)) into values. STACK := newSTACK. SPword1 := *SP++, SPword2 := *SP++. Continue depending on SPword1 and SPword2. If both are 0, simply continue execution. If SPword2 is 0 but SPword1 is nonzero, interpret it as a label and jump to it. |
| (UNWIND-PROTECT-CLEANUP) | Dissolve an UNWIND-PROTECT frame, and execute the cleanup code like a subroutine call. | Dissolve the UNWIND-PROTECT frame at STACK, get label out of the frame. STACK += 2, SP += 2+jmpbufsize. *--SP := 0, *--SP := PC, *--SP := STACK. Save the values on the STACK, STACK -= mv_count. PC := label. |
Instructions for HANDLER-BIND
Table 14. Instructions for HANDLER-BIND
| mnemonic | description | semantics |
|---|---|---|
| (HANDLER-OPEN n) | Create a handler frame. | Create a handler frame, using consts[n] which contains the condition types, the corresponding labels and the current SP depth (= function entry SP - current SP). |
| (HANDLER-BEGIN&PUSH) | Start a handler. | Restore the same SP state as after the HANDLER-OPEN. value1 := the condition that was passed to the handler, mv_count := 1. *--STACK := value1. |
Instructions for some inlined functions
Table 15. Instructions for some inlined functions
| mnemonic | description | semantics |
|---|---|---|
| (NOT) | Inlined call to NOT. | value1 := not(value1), mv_count := 1. |
| (EQ) | Inlined call to EQ. | value1 := eq(*STACK++,value1), mv_count := 1. |
| (CAR) | Inlined call to CAR. | value1 := CAR(value1), mv_count := 1. |
| (CDR) | Inlined call to CDR. | value1 := CDR(value1), mv_count := 1. |
| (CONS) | Inlined call to CONS. | value1 := cons(*STACK++,value1), mv_count := 1. |
| (SYMBOL-FUNCTION) | Inlined call to SYMBOL-FUNCTION. | value1 := SYMBOL-FUNCTION(value1), mv_count := 1. |
| (SVREF) | Inlined call to SVREF. | value1 := SVREF(*STACK++,value1), mv_count := 1. |
| (SVSET) | Inlined call to SYSTEM::SVSTORE. | arg1 := *(STACK+1), arg2 := *(STACK+0), STACK += 2. SVREF(arg2,value1) := arg1. value1 := arg1, mv_count := 1. |
| (LIST n) | Inlined call to LIST. | value1 := LIST(*(STACK+n-1),...,*(STACK+0)), mv_count := 1, STACK += n. |
| (LIST* n) | Inlined call to LIST*. | value1 := LIST*(*(STACK+n-1),..., *(STACK+0),value1), mv_count := 1, STACK += n. |
Combined instructions
The most frequent short sequences of instructions have an equivalent combined instruction. They are only present for space and speed optimization. The only exception is FUNCALL&SKIP&RETGF, which is needed for generic functions.
Table 16. Combined instructions
| mnemonic | equivalent |
|---|---|
| (NIL&PUSH) | (NIL) (PUSH) |
| (T&PUSH) | (T) (PUSH) |
| (CONST&PUSH n) | (CONST n) (PUSH) |
| (LOAD&PUSH n) | (LOAD n) (PUSH) |
| (LOADI&PUSH k1 k2 n) | (LOADI k1 k2 n) (PUSH) |
| (LOADC&PUSH n m) | (LOADC n m) (PUSH) |
| (LOADV&PUSH k m) | (LOADV k m) (PUSH) |
| (POP&STORE n) | (POP) (STORE n) |
| (GETVALUE&PUSH n) | (GETVALUE n) (PUSH) |
| (JSR&PUSH label) | (JSR label) (PUSH) |
| (COPY-CLOSURE&PUSH m n) | (COPY-CLOSURE m n) (PUSH) |
| (CALL&PUSH k n) | (CALL k n) (PUSH) |
| (CALL1&PUSH n) | (CALL1 n) (PUSH) |
| (CALL2&PUSH n) | (CALL2 n) (PUSH) |
| (CALLS1&PUSH b) | (CALLS1 b) (PUSH) |
| (CALLS2&PUSH b) | (CALLS2 b) (PUSH) |
| (CALLSR&PUSH m n) | (CALLSR m n) (PUSH) |
| (CALLC&PUSH) | (CALLC) (PUSH) |
| (CALLCKEY&PUSH) | (CALLCKEY) (PUSH) |
| (FUNCALL&PUSH n) | (FUNCALL n) (PUSH) |
| (APPLY&PUSH n) | (APPLY n) (PUSH) |
| (CAR&PUSH) | (CAR) (PUSH) |
| (CDR&PUSH) | (CDR) (PUSH) |
| (CONS&PUSH) | (CONS) (PUSH) |
| (LIST&PUSH n) | (LIST n) (PUSH) |
| (LIST*&PUSH n) | (LIST* n) (PUSH) |
| (NIL&STORE n) | (NIL) (STORE n) |
| (T&STORE n) | (T) (STORE n) |
| (LOAD&STOREC k n m) | (LOAD k) (STOREC n m) |
| (CALLS1&STORE b k) | (CALLS1 b) (STORE k) |
| (CALLS2&STORE b k) | (CALLS2 b) (STORE k) |
| (CALLSR&STORE m n k) | (CALLSR m n) (STORE k) |
| (LOAD&CDR&STORE n) | (LOAD n) (CDR) (STORE n) |
| (LOAD&CONS&STORE n) | (LOAD n+1) (CONS) (STORE n) |
| (LOAD&INC&STORE n) | (LOAD n) (CALL1 #'1+) (STORE n) |
| (LOAD&DEC&STORE n) | (LOAD n) (CALL1 #'1-) (STORE n) |
| (LOAD&CAR&STORE m n) | (LOAD m) (CAR) (STORE n) |
| (CALL1&JMPIF n label) | (CALL1 n) (JMPIF label) |
| (CALL1&JMPIFNOT n label) | (CALL1 n) (JMPIFNOT label) |
| (CALL2&JMPIF n label) | (CALL2 n) (JMPIF label) |
| (CALL2&JMPIFNOT n label) | (CALL2 n) (JMPIFNOT label) |
| (CALLS1&JMPIF b label) | (CALLS1 b) (JMPIF label) |
| (CALLS1&JMPIFNOT b label) | (CALLS1 b) (JMPIFNOT label) |
| (CALLS2&JMPIF b label) | (CALLS2 b) (JMPIF label) |
| (CALLS2&JMPIFNOT b label) | (CALLS2 b) (JMPIFNOT label) |
| (CALLSR&JMPIF m n label) | (CALLSR m n) (JMPIF label) |
| (CALLSR&JMPIFNOT m n label) | (CALLSR m n) (JMPIFNOT label) |
| (LOAD&JMPIF n label) | (LOAD n) (JMPIF label) |
| (LOAD&JMPIFNOT n label) | (LOAD n) (JMPIFNOT label) |
| (LOAD&CAR&PUSH n) | (LOAD n) (CAR) (PUSH) |
| (LOAD&CDR&PUSH n) | (LOAD n) (CDR) (PUSH) |
| (LOAD&INC&PUSH n) | (LOAD n) (CALL1 #'1+) (PUSH) |
| (LOAD&DEC&PUSH n) | (LOAD n) (CALL1 #'1-) (PUSH) |
| (CONST&SYMBOL-FUNCTION n) | (CONST n) (SYMBOL-FUNCTION) |
| (CONST&SYMBOL-FUNCTION&PUSH n) | (CONST n) (SYMBOL-FUNCTION) (PUSH) |
| (CONST&SYMBOL-FUNCTION&STORE n k) | (CONST n) (SYMBOL-FUNCTION) (STORE k) |
| (APPLY&SKIP&RET n k) | (APPLY n) (SKIP&RET k) |
| (FUNCALL&SKIP&RETGF n k) | (FUNCALL n) (SKIP&RETGF k) |
Shortcut instructions
There are special one-byte instructions (without explicit operands) for the following frequent instructions:
III. Extensions
Extensions-1: Platform independent Extensions
Extensions-1.1. Saving an Image
The function (ext:saveinitmem &OPTIONAL (filename "lispinit.mem") &KEY :quiet :init-function :locked-packages) saves the running CLISP's memory to the file filename; extension #P".mem" is recommended. If the :quiet argument is not NIL, the startup banner and the good-bye message will be suppressed. The :init-function argument specifies a function that will be executed at startup of the saved image. When filename does not have an extension, #P".mem" extension is automatically used. The :locked-packages argument specifies the packages to lock before saving the image; this is convenient for application delivery, when you do not want your user to mess up your product. This argument defaults to CUSTOM:*SYSTEM-PACKAGE-LIST*. The starting package of the new image is the one in which you were when you invoked ext:saveinitmem.
Extensions-1.2. Quitting CLISP
The functions (ext:exit [errorp]), (ext:quit [errorp]) and (ext:bye [errorp]) - all synonymous - terminate CLISP. If errorp is non-NIL, CLISP aborts with error status, i.e., the environment is informed that the CLISP session did not succeed.
Extensions-1.3. Internationalization
Internationalization means to prepare a program so that it can use multiple national languages and national cultural conventions without requiring further source code changes. Localization means providing the data - mostly textual translations - necessary for an internationalized program to work in a particular language and with particular cultural conventions.
CLISP is internationalized, and is localized for the languages English, German, French, Spanish and Dutch. CLISP also supports internationalized Lisp programs, through GNU gettext.
The GNU gettext
GNU gettext is a set of functions, included in CLISP or the C library, which permit looking up translations of strings through message catalogs. It is also a set of tools which makes the translation maintenance easy for the translator and the program maintainer.
The GNU gettext functions are available in CLISP in the "I18N" package, which is EXT:RE-EXPORTed from the "EXT" package.
- (I18N:GETTEXT MSGID &OPTIONAL DOMAIN CATEGORY)
returns the translation of the message MSGID, in the given DOMAIN, depending on the given CATEGORY. MSGID should be an ASCII string, and is normally the English message.
- (I18N:NGETTEXT MSGID msgid_plural n &OPTIONAL DOMAIN CATEGORY)
returns the plural form of the translation for of MSGID and n in the given DOMAIN, depending on the given CATEGORY. MSGID and msgid_plural should be ASCII strings, and are normally the English singular and English plural variant of the message, respectively.
Domain
The DOMAIN is a string identifier denoting the program that is requesting the translation. The pathname of the message catalog depends on the DOMAIN: usually it is located at TEXTDOMAINDIR/l/LC_MESSAGES/domain.mo, where l is the ISO 639 code of the language. The notion of DOMAIN allows several Lisp programs running in the same image to request translations independently of each other.
(I18N:TEXTDOMAIN) is a place that returns the default DOMAIN, used when no DOMAIN argument is passed to the I18N:GETTEXT and I18N:NGETTEXT functions. It is SETFable. (SETF I18N:TEXTDOMAIN) is usually used during the startup phase of a program. Note that the default DOMAIN is not saved in a memory image. The use of (SETF I18N:TEXTDOMAIN) is recommended only for programs that are so simple that they will never need more than one DOMAIN.
(I18N:TEXTDOMAINDIR DOMAIN) is a place that returns the base directory, called TEXTDOMAINDIR above, where the message catalogs for the given DOMAIN are assumed to be installed. It is SETFable. (SETF I18N:TEXTDOMAINDIR) is usually used during the startup phase of a program, and should be used because only the program knows where its message catalogs are installed. Note that the TEXTDOMAINDIRs are not saved in a memory image.
Category
The CATEGORY argument of the I18N:GETTEXT and I18N:NGETTEXT functions denotes which locale facet the result should depend on. The default value is :LC_MESSAGES. Other possible values are :LC_CTYPE, :LC_TIME, :LC_COLLATE, :LC_MONETARY. The use of these values is useful for users who have a character/time/collation/money handling set differently from the usual message handling. Note that when a CATEGORY argument is used, the message catalog location depends on the CATEGORY: it will be expected at TEXTDOMAINDIR/ll/category/domain.mo.
Example
A non-internationalized program simulating a restaurant dialogue might look as follows.
Example 1. prog.lisp
(setq n (parse-integer (first *args*)))
(format t "~A~%" "'Your command, please?', asked the waiter.")
(format t "~@?~%"
(if (= n 1) "a piece of cake" "~D pieces of cake")
n)
|
After being internationalized, all strings are wrapped in I18N:GETTEXT calls, and I18N:NGETTEXT is used for plurals. Also, I18N:TEXTDOMAINDIR is assigned a value; in our case, for simplicity, the current directory.
Example 2. prog.lisp
(setf (textdomain) "prog")
(setf (textdomaindir "prog") "./")
(setq n (parse-integer (first *args*)))
(format t "~A~%"
(gettext "'Your command, please?', asked the waiter."))
(format t "~@?~%"
(ngettext "a piece of cake" "~D pieces of cake" n)
n)
|
For ease of reading, it is customary to define an abbreviation for the I18N:GETTEXT function. An underscore is customary.
Example 3. prog.lisp
(setf (textdomaindir "prog") "./")
(defun _ (msgid) (gettext msgid "prog"))
(setq n (parse-integer (first *args*)))
(format t "~A~%"
(_"'Your command, please?', asked the waiter."))
(format t "~@?~%"
(ngettext "a piece of cake" "~D pieces of cake" n "prog")
n)
|
Now the program's maintainer creates a message catalog template through the command
bash$ xgettext -o prog.pot prog.lisp |
The message catalog template looks roughly like this.
Example 4. prog.pot
msgid "'Your command, please?', asked the waiter." msgstr "" msgid "a piece of cake" msgid_plural "%d pieces of cake" msgstr[0] "" msgstr[1] "" |
Then a French translator creates a French message catalog
Example 5. prog.fr.po
msgid "" msgstr "" "Content-Type: text/plain; charset=ISO-8859-1\n" "Plural-Forms: nplurals=2; plural=(n > 1);\n" msgid "'Your command, please?', asked the waiter." msgstr "«Votre commande, s'il vous plait», dit le garçon." # Les gateaux allemands sont les meilleurs du monde. msgid "a piece of cake" msgid_plural "%d pieces of cake" msgstr[0] "un morceau de gateau" msgstr[1] "%d morceaux de gateau" |
and sends it to the program's maintainer.
The program's maintainer compiles the catalog as follows:
bash$ mkdir -p ./fr/LC_MESSAGES bash$ msgfmt -o ./fr/LC_MESSAGES/prog.mo prog.fr.po |
When a user in a french locale then runs the program
bash$ clisp prog.lisp 2 |
«Votre commande, s'il vous plait», dit le garçon.
2 morceaux de gateau
|
The Language
Warning: The facilities described in this section will work only for the languages for which CLISP itself is already localized.
The language CLISP uses to communicate with the user can be one of
| ENGLISH |
| DEUTSCH (i.e., German) |
| FRANÇAIS (i.e., French) |
| ESPAÑOL (i.e., Spanish) |
| NEDERLANDS (i.e. Dutch) |
This is controlled by the SYMBOL-MACRO CUSTOM:*CURRENT-LANGUAGE*, which can be set at run time as well as using -L start-up option. If you wish to change the locale directory at run time too, you can do that by setting CUSTOM:*CURRENT-LANGUAGE* to a cons cell, whose CAR is the language (a symbol, one of the above), and whose CDR is the new locale directory.
More languages can be defined through the macro I18N:DEFLANGUAGE: (I18N:DEFLANGUAGE lang). For such an additional language to take effect, you must install the corresponding message catalog, or translate the messages yourself, using GNU gettext and Emacs (or XEmacs) po-mode.
This works only for strings. For arbitrary language-dependent Lisp objects, you define one through the macro I18N:DEFINTERNATIONAL: (I18N:DEFINTERNATIONAL symbol &OPTIONAL (default-language T)) and add language-dependent values through the macro I18N:DEFLOCALIZED: (I18N:DEFLOCALIZED symbol language value-form)
(One such form for each language. Languages without an assigned value will be treated like the default-language.) You can then access the localized value by calling I18N:LOCALIZED: (I18N:LOCALIZED symbol &OPTIONAL language)
Extensions-1.4. Encodings
Introduction
An encoding describes the correspondence between CHARACTERs and raw bytes during input/output via STREAMs with STREAM-ELEMENT-TYPE CHARACTER.
An EXT:ENCODING is an object composed of the following facets:
- character set
This denotes both the set of characters that can be represented and passed through the I/O channel, and the way these characters translate into raw bytes. In this context, for example, "UTF-8" and "UCS-4" are considered different, although they can represent the same set of characters.
- line terminator mode
This denotes the way newline characters are represented.
Character Sets
- Platform dependent: Only in CLISP built without compile-time flag UNICODE.
Only one character set is understood: the platform's native (8-bit) character set. See Chapter 13.
- Platform dependent: Only in CLISP built with compile-time flag UNICODE.
The following character sets are supported, as values of the corresponding (constant) symbol in the "CHARSET" package:
UCS-2 = UNICODE-16 = UNICODE-16-BIG-ENDIAN, the 16-bit UNICODE character set. Every character is represented as two bytes.
UNICODE-16-LITTLE-ENDIAN
UCS-4 = UNICODE-32 = UNICODE-32-BIG-ENDIAN, the 32-bit UNICODE character set. Every character is represented as four bytes. Note that CLISP understands only those characters which are already contained in the 16-bit UNICODE character set.
UNICODE-32-LITTLE-ENDIAN
UTF-8, the 16-bit UNICODE character set. Every character is represented as one to three bytes. ASCII characters represent themselves and need one byte per character. Most Latin/Greek/Cyrillic/Hebrew characters need two bytes per character, and the remaining characters need three bytes per character. This is therefore, in general, the most space-efficient encoding of all of Unicode-16.
UTF-16, the 16-bit UNICODE character set. Every character is represented as two bytes.
UTF-7, the 16-bit UNICODE character set. This is a stateful 7-bit encoding. Not all ASCII characters represent themselves.
JAVA, the 16-bit UNICODE character set. ASCII characters represent themselves and need one byte per character. All other characters are represented by \unnnn sequences (nnnn a hexadecimal number) and need 6 bytes per character. While this encoding is very comfortable for editing Unicode files using only ASCII aware tools and editors, it cannot faithfully represent all UNICODE text. Only text which does not contain \u (backslash followed by lowercase Latin u) can be faithfully represented by this encoding.
ASCII, the well-known US-centric 7-bit character set (American Standard Code for Information Interchange).
ISO-8859-1, an extension of the ASCII character set, suitable for the Afrikaans, Albanian, Basque, Breton, Catalan, Cornish, Danish, Dutch, English, Faeroese, Finnish, French, Frisian, Galician, German, Greenlandic, Icelandic, Irish, Italian, Latin, Luxemburgish, Norwegian, Portuguese, Raeto-Romanic, Scottish, Spanish, and Swedish languages.
ISO-8859-2, an extension of the ASCII character set, suitable for the Croatian, Czech, German, Hungarian, Polish, Slovak, Slovenian, and Sorbian languages.
ISO-8859-3, an extension of the ASCII character set, suitable for the Esperanto and Maltese languages.
ISO-8859-4, an extension of the ASCII character set, suitable for the Estonian, Latvian, Lithuanian and Sami (Lappish) languages.
ISO-8859-5, an extension of the ASCII character set, suitable for the Bulgarian, Byelorussian, Macedonian, Russian, Serbian, and Ukrainian languages.
ISO-8859-6, suitable for the Arabic language.
ISO-8859-7, an extension of the ASCII character set, suitable for the Greek language.
ISO-8859-8, an extension of the ASCII character set, suitable for the Hebrew language (without punctuation).
ISO-8859-9, an extension of the ASCII character set, suitable for the Turkish language.
ISO-8859-10, an extension of the ASCII character set, suitable for the Estonian, Icelandic, Inuit (Greenlandic), Latvian, Lithuanian, and Sami (Lappish) languages.
ISO-8859-13, an extension of the ASCII character set, suitable for the Estonian, Latvian, Lithuanian, Polish and Sami (Lappish) languages.
ISO-8859-14, an extension of the ASCII character set, suitable for Irish Gaelic, Manx Gaelic, Scottish Gaelic, and Welsh languages.
ISO-8859-15, an extension of the ASCII character set, suitable for the ISO-8859-1 languages, with improvements for French, Finnish and the Euro.
ISO-8859-16 an extension of the ASCII character set, suitable for the Rumanian language.
KOI8-R, an extension of the ASCII character set, a popular character set for the Russian language.
KOI8-U, an extension of the ASCII character set, a popular character set for the Ukrainian language.
KOI8-RU, an extension of the ASCII character set, suitable for Russian (this is the standard Russian encoding on the Internet)
JIS_X0201, a character set for the Japanese language.
MAC-ARABIC, a platform specific extension of the ASCII character set.
MAC-CENTRAL-EUROPE, a platform specific extension of the ASCII character set.
MAC-CROATIAN, a platform specific extension of the ASCII character set.
MAC-CYRILLIC, a platform specific extension of the ASCII character set.
MAC-DINGBAT, a platform specific character set.
MAC-GREEK, a platform specific extension of the ASCII character set.
MAC-HEBREW, a platform specific extension of the ASCII character set.
MAC-ICELAND, a platform specific extension of the ASCII character set.
MAC-ROMAN = MACINTOSH, a platform specific extension of the ASCII character set.
MAC-ROMANIA, a platform specific extension of the ASCII character set.
MAC-SYMBOL, a platform specific character set.
MAC-THAI, a platform specific extension of the ASCII character set.
MAC-TURKISH, a platform specific extension of the ASCII character set.
MAC-UKRAINE, a platform specific extension of the ASCII character set.
CP437, a DOS oldie, a platform specific extension of the ASCII character set.
CP437-IBM, an IBM variant of CP437.
CP737, a DOS oldie, a platform specific extension of the ASCII character set, meant to be suitable for the Greek language.
CP775, a DOS oldie, a platform specific extension of the ASCII character set, meant to be suitable for some Baltic languages.
CP850, a DOS oldie, a platform specific extension of the ASCII character set.
CP852, a DOS oldie, a platform specific extension of the ASCII character set.
CP852-IBM, an IBM variant of CP852.
CP855, a DOS oldie, a platform specific extension of the ASCII character set, meant to be suitable for the Russian language.
CP857, a DOS oldie, a platform specific extension of the ASCII character set, meant to be suitable for the Turkish language.
CP860, a DOS oldie, a platform specific extension of the ASCII character set, meant to be suitable for the Portuguese language.
CP860-IBM, an IBM variant of CP860.
CP861, a DOS oldie, a platform specific extension of the ASCII character set, meant to be suitable for the Icelandic language.
CP861-IBM, an IBM variant of CP861.
CP862, a DOS oldie, a platform specific extension of the ASCII character set, meant to be suitable for the Hebrew language.
CP862-IBM, an IBM variant of CP862.
CP863, a DOS oldie, a platform specific extension of the ASCII character set.
CP863-IBM, an IBM variant of CP863.
CP864, a DOS oldie, meant to be suitable for the Arabic language.
CP864-IBM, an IBM variant of CP864.
CP865, a DOS oldie, a platform specific extension of the ASCII character set, meant to be suitable for some Nordic languages.
CP865-IBM, an IBM variant of CP865.
CP866, a DOS oldie, a platform specific extension of the ASCII character set, meant to be suitable for the Russian language.
CP869, a DOS oldie, a platform specific extension of the ASCII character set, meant to be suitable for the Greek language.
CP869-IBM, an IBM variant of CP869.
CP874, a DOS oldie, a platform specific extension of the ASCII character set, meant to be suitable for the Thai language.
CP874-IBM, an IBM variant of CP874.
WINDOWS-1250 = CP1250, a platform specific extension of the ASCII character set, heavily incompatible with ISO-8859-2.
WINDOWS-1251 = CP1251, a platform specific extension of the ASCII character set, heavily incompatible with ISO-8859-5, meant to be suitable for the Russian language.
WINDOWS-1252 = CP1252, a platform specific extension of the ISO-8859-1 character set.
WINDOWS-1253 = CP1253, a platform specific extension of the ASCII character set, gratuitously incompatible with ISO-8859-7, meant to be suitable for the Greek language.
WINDOWS-1254 = CP1254, a platform specific extension of the ISO-8859-9 character set.
WINDOWS-1255 = CP1255, a platform specific extension of the ASCII character set, gratuitously incompatible with ISO-8859-8, suitable for the Hebrew language.
WINDOWS-1256 = CP1256, a platform specific extension of the ASCII character set, meant to be suitable for the Arabic language.
WINDOWS-1257 = CP1257, a platform specific extension of the ASCII character set.
WINDOWS-1258 = CP1258, a platform specific extension of the ASCII character set.
HP-ROMAN8, a platform specific extension of the ASCII character set.
NEXTSTEP, a platform specific extension of the ASCII character set.
EUC-JP, a multibyte character set for the Japanese language.
SHIFT-JIS, a multibyte character set for the Japanese language.
CP932, a Microsoft variant of SHIFT-JIS.
ISO-2022-JP, a stateful 7-bit multibyte character set for the Japanese language.
ISO-2022-JP-2, a stateful 7-bit multibyte character set for the Japanese language.
ISO-2022-JP-1, a stateful 7-bit multibyte character set for the Japanese language.
EUC-CN, a multibyte character set for simplified Chinese.
HZ, a stateful 7-bit multibyte character set for simplified Chinese.
GBK, a multibyte character set for Chinese,
CP936, a Microsoft variant of GBK.
GB18030, a multibyte character set for Chinese,
EUC-TW, a multibyte character set for traditional Chinese.
BIG5, a multibyte character set for traditional Chinese.
CP950, a Microsoft variant of BIG5.
BIG5HKSCS, a multibyte character set for traditional Chinese.
ISO-2022-CN, a stateful 7-bit multibyte character set for Chinese.
ISO-2022-CN-EXT, a stateful 7-bit multibyte character set for Chinese.
EUC-KR, a multibyte character set for Korean.
CP949, a Microsoft variant of EUC-KR.
ISO-2022-KR, a stateful 7-bit multibyte character set for Korean.
ARMSCII-8, an extension of the ASCII character set, suitable for Armenian.
GEORGIAN-ACADEMY, an extension of the ASCII character set, suitable for Georgian.
GEORGIAN-PS, an extension of the ASCII character set, suitable for Georgian.
TIS-620, an extension of the ASCII character set, suitable for Thai.
MULELAO-1, an extension of the ASCII character set, suitable for Laotian.
CP1133, an extension of the ASCII character set, suitable for Laotian.
VISCII, an extension of the ASCII character set, suitable for Vietnamese.
TCVN, an extension of the ASCII character set, suitable for Vietnamese.
- [CLISP comes with it own implementation of iconv(), so the following is more or less obsolete now.] (Platform dependent: Only on UNIX systems having the C library function iconv()).
The character sets provided by the library function iconv() can also be used as encodings. To create such an encoding, call EXT:MAKE-ENCODING with the character set name (a string) as :charset argument.
These encodings are not assigned to global variables, since there is no portable way to get the list of all character sets supported by iconv().
On GNU systems (such as GNU/Linux and GNU/Hurd), you get this list by calling the program iconv: iconv --list. GNU glibc-2.1 supports in particular, among others:
EUC-JP and SHIFT-JIS, for the Japanese language,
EUC-CN, EUC-TW, BIG5 and GB, for the Chinese language,
EUC-KR and ISO-2022-KR, for the Korean language.
HP-UX systems support in particular, among others:
eucJP and sjis, for the Japanese language,
eucTW, big5 and chinese-gb, for the Chinese language,
eucKR, for the Korean language.
AIX 4.2 systems support in particular, among others:
IBM-eucJP, for the Japanese language,
IBM-eucTW, for the Chinese language,
IBM-eucKR, for the Korean language.
On Solaris systems, you can forget about iconv()-based encodings, because all the possible encodings are already built-in. (Solaris knows about Japanese, Chinese and Korean encodings, but can convert them only to/from UTF-8, not to/from UCS-2, which is the CLISP's internal encoding.)
On IRIX systems, you can forget about iconv()-based encodings as well, because all the interesting possible encodings are already built-in.
On OSF/1 systems, iconv()-based encodings are not usable at all.
When an encoding is available as a built-in and through iconv(), the built-in is preferred, because it is more efficient and available across platforms.
Line Terminators
Table 1. The line terminator mode can be one of the following three keywords
| keyword | newline representation |
|---|---|
| :UNIX | Newline is represented by the ASCII LF character (U000A). |
| :MAC | Newline is represented by the ASCII CR character (U000D). |
| :DOS | Newline is represented by the ASCII CR followed by the ASCII LF. |
Windows programs typically use the :DOS line terminator, sometimes they also accept :UNIX line terminators or produce :MAC line terminators.
The line terminator mode is relevant only for output (writing to a file/pipe/socket). During input, all three kinds of line terminators are recognized. If you do not want this, i.e., if you really want to distinguish LF, CR and CR/LF, you have to resort to binary input (function READ-BYTE).
See also 13.1.8 Treatment of Newline during Input and Output.
Function EXT:MAKE-ENCODING
The function (EXT:MAKE-ENCODING &KEY :charset :line-terminator :input-error-action :output-error-action) returns an EXT:ENCODING. The :charset argument may be an encoding, a string, or :DEFAULT. The possible values for the line terminator argument are the keywords :UNIX, :MAC, :DOS.
The :input-error-action specifies what happens when an invalid byte sequence is encountered while converting bytes to characters. Its value can be :ERROR, :IGNORE or a character to be used instead. The UNICODE character #\uFFFD is typically used to indicate an error in the input sequence.
The :output-error-action specifies what happens when an invalid character is encountered while converting characters to bytes. Its value can be :ERROR, :IGNORE, a byte to be used instead, or a character to be used instead. The UNICODE character #\uFFFD can be used here only if it is encodable in the character set.
Encodings are types. As such, they represent the set of characters encodable in the character set. In this context, the way characters are translated into raw bytes is ignored, and the line terminator mode is ignored as well. TYPEP and SUBTYPEP can be used on encodings.
Besides every file/pipe/socket stream containing an encoding, the following SYMBOL-MACRO places contain global EXT:ENCODINGs:
CUSTOM:*DEFAULT-FILE-ENCODING*. The SYMBOL-MACRO place CUSTOM:*DEFAULT-FILE-ENCODING* is the encoding used for new file/pipe/socket streams, when no :EXTERNAL-FORMAT argument was specified.
- Platform dependent: Only in CLISP built with compile-time flag UNICODE.
The following are SYMBOL-MACRO places.
- CUSTOM:*PATHNAME-ENCODING*
is the encoding used for pathnames in the file system. Normally, this is a 1:1 encoding. Its line terminator mode is ignored.
- CUSTOM:*TERMINAL-ENCODING*
is the encoding used for communication with the terminal, in particular by *TERMINAL-IO*.
- CUSTOM:*MISC-ENCODING*
is the encoding used for access to environment variables, command line options, and the like. Its line terminator mode is ignored.
- CUSTOM:*FOREIGN-ENCODING*
is the encoding for characters and strings passed through the "FFI" (some plaforms only). Its value must be a 1:1 encoding, i.e., an encoding in which every character is represented by one byte.
The default encoding objects are initialized as described in the CLISP manual page
Converting between strings and byte vectors
Encodings can also be used to convert directly between strings and their corresponding byte vector representation according to that encoding.
- (EXT:CONVERT-STRING-FROM-BYTES byte-vector encoding &KEY :START :END)
converts the subsequence of byte-vector from start to end to a string, according to the given encoding, and returns the resulting string.
- (EXT:CONVERT-STRING-TO-BYTES string encoding &KEY :START :END)
converts the subsequence of string from start to end to a (VECTOR (UNSIGNED-BYTE 8)), according to the given encoding, and returns the resulting byte vector.
Extensions-1.5. Defining new kinds of Streams
Two mechanisms are supported for creating new streams with user-defined behavior:
You can create a new subclass of GRAY:FUNDAMENTAL-STREAM and define methods for the elementary stream operations on it. These generic functions all have a name starting with the prefix "stream-".
You can create a new subclass of gstream:generic-stream-controller and define methods for the elementary stream operations on it. These generic functions all have a name starting with the prefix "generic-stream-". The stream itself is a different object, created using the function gstream:make-generic-stream.
The fundamental-stream API is based on the STREAM-DEFINITION-BY-USER:GENERIC-FUNCTIONS proposal by David N. Gray and is supported by most Common Lisp implementations currently in use. The gstream:generic-stream-controller API is CLISP specific and is now obsolete.
Gray streams
This interface permits the definition of new classes of streams, and programming their behavior by defining methods for the elementary stream operations. It is based on the proposal STREAM-DEFINITION-BY-USER:GENERIC-FUNCTIONS of David N. Gray to X3J13.
All symbols defined by this interface, starting with the prefix "fundamental-" or "stream-", are exported from the package "GRAY" and re-exported from "EXT".
Defined classes
- GRAY:FUNDAMENTAL-STREAM
This is a superclass of all user-defined streams. It is a subclass of STREAM and of STANDARD-OBJECT. Its metaclass is STANDARD-CLASS.
- GRAY:FUNDAMENTAL-INPUT-STREAM
This is a superclass of all user-defined input streams. It is a subclass of GRAY:FUNDAMENTAL-STREAM. The built-in function INPUT-STREAM-P returns true on instances of this class. This means that when you define a new stream class capable of doing input, you have to make it a subclass of GRAY:FUNDAMENTAL-INPUT-STREAM.
- GRAY:FUNDAMENTAL-OUTPUT-STREAM
This is a superclass of all user-defined output streams. It is a subclass of GRAY:FUNDAMENTAL-STREAM. The built-in function OUTPUT-STREAM-P returns true on instances of this class. This means that when you define a new stream class capable of doing output, you have to make it a subclass of GRAY:FUNDAMENTAL-OUTPUT-STREAM.
- GRAY:FUNDAMENTAL-CHARACTER-STREAM
This is a superclass of all user-defined streams whose STREAM-ELEMENT-TYPE is CHARACTER. It is a subclass of GRAY:FUNDAMENTAL-STREAM. It defines a method on STREAM-ELEMENT-TYPE that returns CHARACTER.
- GRAY:FUNDAMENTAL-BINARY-STREAM
This is a superclass of all user-defined streams whose STREAM-ELEMENT-TYPE is a subtype of INTEGER. It is a subclass of GRAY:FUNDAMENTAL-STREAM. When you define a subclass of GRAY:FUNDAMENTAL-BINARY-STREAM, you have to provide a method on STREAM-ELEMENT-TYPE.
- GRAY:FUNDAMENTAL-CHARACTER-INPUT-STREAM
This is a convenience class inheriting from both GRAY:FUNDAMENTAL-CHARACTER-STREAM and GRAY:FUNDAMENTAL-INPUT-STREAM.
- GRAY:FUNDAMENTAL-CHARACTER-OUTPUT-STREAM
This is a convenience class inheriting from both GRAY:FUNDAMENTAL-CHARACTER-STREAM and GRAY:FUNDAMENTAL-OUTPUT-STREAM.
- GRAY:FUNDAMENTAL-BINARY-INPUT-STREAM
This is a convenience class inheriting from both GRAY:FUNDAMENTAL-BINARY-STREAM and GRAY:FUNDAMENTAL-INPUT-STREAM.
- GRAY:FUNDAMENTAL-BINARY-OUTPUT-STREAM
This is a convenience class inheriting from both GRAY:FUNDAMENTAL-BINARY-STREAM and GRAY:FUNDAMENTAL-OUTPUT-STREAM.
general generic functions defined on streams
- (STREAM-ELEMENT-TYPE stream)
Returns the stream's element type, normally a subtype of CHARACTER or INTEGER.
The method for GRAY:FUNDAMENTAL-CHARACTER-STREAM returns CHARACTER.
- ((SETF STREAM-ELEMENT-TYPE) new-element-type stream)
Changes the stream's element type.
The default method signals an error.
This function is a CLISP extension (see setting STREAM-ELEMENT-TYPE)
- (CLOSE stream &KEY :ABORT)
Closes the stream and flushes any associated buffers.
When you define a primary method on this function, do not forget to CALL-NEXT-METHOD.
- (OPEN-STREAM-P stream)
Returns true before the stream has been closed, and NIL after the stream has been closed.
You do not need to add methods to this function.
generic functions for character input
- (GRAY:STREAM-READ-CHAR stream)
If a character was pushed back using GRAY:STREAM-UNREAD-CHAR, returns and consumes it. Otherwise returns and consumes the next character from the stream. Returns :EOF if the end-of-stream is reached.
You must define a method for this function.
- (GRAY:STREAM-UNREAD-CHAR stream char)
Pushes char, which must be the last character read from the stream, back onto the front of the stream.
You must define a method for this function.
- (GRAY:STREAM-READ-CHAR-NO-HANG stream)
Returns a character or :EOF, like GRAY:STREAM-READ-CHAR, if that would return immediately. If GRAY:STREAM-READ-CHAR's value is not available immediately, returns NIL instead of waiting.
The default method simply calls GRAY:STREAM-READ-CHAR; this is sufficient for streams whose GRAY:STREAM-READ-CHAR method never blocks.
- (GRAY:STREAM-PEEK-CHAR stream)
If a character was pushed back using GRAY:STREAM-UNREAD-CHAR, returns it. Otherwise returns the next character from the stream, avoiding any side effects GRAY:STREAM-READ-CHAR would do. Returns :EOF if the end-of-stream is reached.
The default method calls GRAY:STREAM-READ-CHAR and GRAY:STREAM-UNREAD-CHAR; this is sufficient for streams whose GRAY:STREAM-READ-CHAR method has no side-effects.
- (GRAY:STREAM-LISTEN stream)
If a character was pushed back using GRAY:STREAM-UNREAD-CHAR, returns it. Otherwise returns the next character from the stream, if already available. If no character is available immediately, or if end-of-stream is reached, returns NIL.
The default method calls GRAY:STREAM-READ-CHAR-NO-HANG and GRAY:STREAM-UNREAD-CHAR; this is sufficient for streams whose GRAY:STREAM-READ-CHAR method has no side-effects.
- (GRAY:STREAM-READ-CHAR-WILL-HANG-P stream)
Returns NIL if GRAY:STREAM-READ-CHAR will return immediately. Otherwise it returns true.
The default method calls GRAY:STREAM-READ-CHAR-NO-HANG and GRAY:STREAM-UNREAD-CHAR; this is sufficient for streams whose GRAY:STREAM-READ-CHAR method has no side-effects.
This function is a CLISP extension (see EXT:READ-CHAR-WILL-HANG-P).
- (GRAY:STREAM-READ-CHAR-SEQUENCE stream sequence &OPTIONAL [start [end]])
Fills the subsequence of sequence specified by :START and :END with characters consecutively read from stream. Returns the index of the first element of sequence that was not updated (= end or < end if the stream reached its end).
sequence is an array of characters, i.e. a string. start is a nonnegative integer and default to 0. end is a nonnegative integer or NIL and defaults to NIL, which stands for (LENGTH sequence).
The default method repeatedly calls GRAY:STREAM-READ-CHAR; this is always sufficient if speed does not matter.
This function is a CLISP extension (see EXT:READ-CHAR-SEQUENCE)
- (GRAY:STREAM-READ-LINE stream)
Reads a line of characters, and return two values: the line (a string, without the terminating #\Newline character), and a boolean value which is true if the line was terminated by end-of-stream instead of #\Newline.
The default method repeatedly calls GRAY:STREAM-READ-CHAR; this is always sufficient.
- (gray:stream-clear-input stream)
Clears all pending interactive input from the stream, and returns true if some pending input was removed.
The default method does nothing and returns NIL; this is sufficient for non-interactive streams.
generic functions for character output
- (GRAY:STREAM-WRITE-CHAR stream char)
Writes char.
You must define a method for this function.
- (GRAY:STREAM-LINE-COLUMN stream)
Returns the column number where the next character would be written (0 stands for the first column), or NIL if that is not meaningful for this stream.
You must define a method for this function.
- (GRAY:STREAM-START-LINE-P stream)
Returns true if the next character would be written at the start of a new line.
The default method calls GRAY:STREAM-LINE-COLUMN and compares its result with 0; this is sufficient for streams whose GRAY:STREAM-LINE-COLUMN never returns NIL.
- (GRAY:STREAM-WRITE-CHAR-SEQUENCE stream sequence &OPTIONAL [start [end]])
Outputs the subsequence of sequence specified by :START and :END to stream.
sequence is an array of characters, i.e. a string. start is a nonnegative integer and default to 0. end is a nonnegative integer or NIL and defaults to NIL, which stands for (LENGTH sequence).
The default method repeatedly calls GRAY:STREAM-WRITE-CHAR; this is always sufficient if speed does not matter.
This function is a CLISP extension (see EXT:WRITE-CHAR-SEQUENCE)
- (GRAY:STREAM-WRITE-STRING stream string &OPTIONAL [start [end]])
Outputs the subsequence of string specified by :START and :END to stream. Returns string.
string is a string. start is a nonnegative integer and default to 0. end is a nonnegative integer or NIL and defaults to NIL, which stands for (LENGTH string).
The default method calls GRAY:STREAM-WRITE-CHAR-SEQUENCE; this is always sufficient.
- (GRAY:STREAM-TERPRI stream)
Outputs a #\Newline character.
The default method calls GRAY:STREAM-WRITE-CHAR; this is always sufficient.
- (GRAY:STREAM-FRESH-LINE stream)
Possibly outputs a #\Newline character, so as to ensure that the next character would be written at the start of a new line. Returns true if it did output a #\Newline character.
The default method calls GRAY:STREAM-START-LINE-P and then GRAY:STREAM-TERPRI if necessary; this is always sufficient.
- (GRAY:STREAM-FINISH-OUTPUT stream)
Ensures that any buffered output has reached its destination, and then returns.
The default method does nothing.
- (GRAY:STREAM-FORCE-OUTPUT stream)
Brings any buffered output on its way towards its destination, and returns without waiting until it has reached its destination.
The default method does nothing.
- (GRAY:STREAM-CLEAR-OUTPUT stream)
Attempts to discard any buffered output which has not yet reached its destination.
The default method does nothing.
- (GRAY:STREAM-ADVANCE-TO-COLUMN stream column)
Ensures that the next character will be written at column at least.
The default method outputs an appropriate amount of space characters; this is sufficient for non-proportional output.
generic functions for binary input
- (GRAY:STREAM-READ-BYTE stream)
Returns and consumes the next integer from the stream. Returns :EOF if the end-of-stream is reached.
You must define a method for this function.
- (GRAY:STREAM-READ-BYTE-LOOKAHEAD stream)
To be called only if stream's STREAM-ELEMENT-TYPE is (UNSIGNED-BYTE 8) or (SIGNED-BYTE 8). Returns T if GRAY:STREAM-READ-BYTE would return immediately with an INTEGER result. Returns :EOF if the end-of-stream is already known to be reached. If GRAY:STREAM-READ-BYTE's value is not available immediately, returns NIL instead of waiting.
You must define a method for this function.
This function is a CLISP extension (see EXT:READ-BYTE-LOOKAHEAD).
- (GRAY:STREAM-READ-BYTE-WILL-HANG-P stream)
To be called only if stream's STREAM-ELEMENT-TYPE is (UNSIGNED-BYTE 8) or (SIGNED-BYTE 8). Returns NIL if GRAY:STREAM-READ-BYTE will return immediately. Otherwise it returns true.
The default method calls GRAY:STREAM-READ-BYTE-LOOKAHEAD; this is always sufficient.
- (GRAY:STREAM-READ-BYTE-NO-HANG stream)
To be called only if stream's STREAM-ELEMENT-TYPE is (UNSIGNED-BYTE 8) or (SIGNED-BYTE 8). Returns an INTEGER or :EOF, like GRAY:STREAM-READ-BYTE, if that would return immediately. If GRAY:STREAM-READ-BYTE's value is not available immediately, returns NIL instead of waiting.
The default method calls GRAY:STREAM-READ-BYTE if GRAY:STREAM-READ-BYTE-LOOKAHEAD returns true; this is always sufficient.
- (GRAY:STREAM-READ-BYTE-SEQUENCE stream sequence &OPTIONAL [start [end]])
Fills the subsequence of sequence specified by :START and :END with integers consecutively read from stream. Returns the index of the first element of sequence that was not updated (= end or < end if the stream reached its end).
sequence is an array of integers. start is a nonnegative integer and default to 0. end is a nonnegative integer or NIL and defaults to NIL, which stands for (LENGTH sequence).
The default method repeatedly calls GRAY:STREAM-READ-BYTE; this is always sufficient if speed does not matter.
This function is a CLISP extension (see EXT:READ-BYTE-SEQUENCE).
generic functions for binary output
- (GRAY:STREAM-WRITE-BYTE stream integer)
Writes integer.
You must define a method for this function.
- (GRAY:STREAM-WRITE-BYTE-SEQUENCE stream sequence &OPTIONAL [start [end]])
Outputs the subsequence of sequence specified by :START and :END to stream
sequence is an array of integers. start is a nonnegative integer and default to 0. end is a nonnegative integer or NIL and defaults to NIL, which stands for (LENGTH sequence).
The default method repeatedly calls GRAY:STREAM-WRITE-BYTE; this is always sufficient if speed does not matter.
This function is a CLISP extension (see EXT:WRITE-BYTE-SEQUENCE).
Generic streams
This interface is CLISP specific and now obsolete. Please use the Gray streams interface instead.
Generic streams are user programmable streams. The programmer interface:
- (gstream:make-generic-stream controller)
returns a generic stream.
- (gstream:generic-stream-controller stream)
returns a private object to which generic stream methods dispatch. The typical usage is to retrieve the object originally provided by the user in gstream:make-generic-stream.
- (gstream:generic-stream-p stream)
determines whether a stream is a generic stream, returning T if it is, NIL otherwise.
In order to specify the behavior of a generic stream, the user must define CLOS methods on the following CLOS generic functions. The function gstream:generic-stream-xyz corresponds to the Common Lisp function xyz. They all take a controller and some number of arguments.
- (gstream:generic-stream-read-char controller)
Returns and consumes the next character, NIL at end of file. Takes one argument, the controller object.
- (gstream:generic-stream-peek-char controller)
Returns the next character, NIL at end of file. A second value indicates whether the side effects associated with consuming the character were executed: T means that a full READ-CHAR was done, NIL means that no side effects were done. Takes one argument, the controller object.
- (gstream:generic-stream-read-byte controller)
Returns and consumes the next integer, NIL at end of file. Takes one argument, the controller object.
- (gstream:generic-stream-read-char-will-hang-p controller)
This generic function is used to query the stream's input status. It returns NIL if gstream:generic-stream-read-char and gstream:generic-stream-peek-char will certainly return immediately. Otherwise it returns true.
- (gstream:generic-stream-write-char controller char)
The first argument is the controller object. The second argument is the character to be written.
- (gstream:generic-stream-write-byte controller by)
The first argument is the controller object. The second argument is the integer to be written.
- (gstream:generic-stream-write-string controller string start length)
Writes the subsequence of string starting from start of length length. The first argument is the controller object.
- (gstream:generic-stream-clear-input controller) (gstream:generic-stream-clear-output controller) (gstream:generic-stream-finish-output controller) (gstream:generic-stream-force-output controller) (gstream:generic-stream-close controller)
Take one argument, the controller object.
Extensions-1.6. Weak Pointers
A weak pointer is an object holding a reference to a given object, without keeping the latter from being garbage-collected.
- (EXT:MAKE-WEAK-POINTER value)
returns a fresh weak pointer referring to value.
- (EXT:WEAK-POINTER-P object)
returns true if the object is of type EXT:WEAK-POINTER.
- (EXT:WEAK-POINTER-VALUE weak-pointer)
returns two values: The original value and T, if the value has not yet been garbage-collected, else NIL and NIL.
Extensions-1.7. Finalization
Calling (EXT:FINALIZE object function) has the effect that when the specified object is being garbage-collected, (FUNCALL function object) will be executed.
Calling (EXT:FINALIZE object function guardian) has a similar effect, but only as long as the "guardian" has not been garbage-collected: When object is being garbage-collected, (FUNCALL function object guardian) will be executed. If the guardian is garbage-collected before object is, nothing happens.
Note: The time when "the object is being garbage-collected" is not defined deterministically. (Actually, it might possibly never occur.) It denotes a moment at which no references to object exist from other Lisp objects. When the function is called, object (and possibly guardian) enter the "arena of live Lisp objects" again.
No finalization request will be executed more than once.
Extensions-1.8. The Prompt
The variable custom:*prompt* controls the appearance of the prompt. When its value is a function, it is called and its value is printed with PRINC. Otherwise, the value itself is printed with PRINC. The default value of custom:*prompt* prints "package[nn]> " where package is the shortest (nick)name of the current package *PACKAGE* if it is the same as it was in the beginning or if it does not contain symbol T (it is assumed that in the latter case you would want to keep in mind that your current package is something weird); and nn is the ordinal number of the current prompt (hopefully, it will remain finite). To help you in constructing your own fancy prompts, two functions are provided: ext:prompt-new-package, returning *PACKAGE* or NIL if the current package is the same as it was initially; and ext:package-short-name taking one argument, a package, and returning its shortest name or nickname. Also, a variable ext:*command-index* contains the current prompt number, it is your responsibility to increment it (this variable is bound to 0 before saving the memory image).
Extensions-1.9. Maximum ANSI CL compliance
Some [ANSI CL standard] features are turned off by default for backwards compatibility. They can be switched on, all at once by setting the SYMBOL-MACRO CUSTOM:*ANSI* to T, or they can be switched on individually. Setting CUSTOM:*ANSI* to T implies the following:
Setting CUSTOM:*PRINT-PATHNAMES-ANSI* to T.
Setting CUSTOM:*COERCE-FIXNUM-CHAR-ANSI* to T.
Setting CUSTOM:*SEQUENCE-COUNT-ANSI* to T.
Setting CUSTOM:*MERGE-PATHNAMES-ANSI* to T.
Setting CUSTOM:*PARSE-NAMESTRING-ANSI* to T.
Setting CUSTOM:*FLOATING-POINT-CONTAGION-ANSI* to T.
Please note that if you run CLISP with the -ansi switch or set the SYMBOL-MACRO CUSTOM:*ANSI* to T and save memory image, then all subsequent invocations of CLISP with this image will be as if with -ansi (regardless whether you actually supply the -ansi switch). You can always set the SYMBOL-MACRO CUSTOM:*ANSI* to NIL, or invoke CLISP with the -traditional switch, reversing the above settings, i.e.,
Setting CUSTOM:*PRINT-PATHNAMES-ANSI* to NIL.
Setting CUSTOM:*COERCE-FIXNUM-CHAR-ANSI* to NIL.
Setting CUSTOM:*SEQUENCE-COUNT-ANSI* to NIL.
Setting CUSTOM:*MERGE-PATHNAMES-ANSI* to NIL.
Setting CUSTOM:*PARSE-NAMESTRING-ANSI* to NIL.
Setting CUSTOM:*FLOATING-POINT-CONTAGION-ANSI* to NIL.
Extensions-1.10. Additional Fancy Macros
If you uncomment the (LOAD "macros3") line in the file init.lisp before doing make, or load the file macros3.lisp into a running CLISP, you can use the following macros:
Macros EXT:LETF & EXT:LETF*. These macros are similar to LET and LET*, respectively, except that they can bind places, even places with multiple values. Example:
(letf (((values a b) form)) ...) |
(multiple-value-bind (a b) form ...) |
(letf (((first l) 7)) ...) |
(LET* ((#:g1 l) (#:g2 (first #:g1))) (UNWIND-PROTECT (PROGN (SETF (first #:g1) 7) ...) (SETF (first #:g1) #:g2))) |
ext:with-collect. Similar to the LOOP's collect instruction, except that it is more "Lispy" in appearance and can appear arbitrarily deep. It defines local macros (with MACROLET) which collect objects given to it in lists, which are then returned as multiple values. E.g.,
(ext:with-collect (c0 c1) (dotimes (i 10) (if (oddp i) (c0 i) (c1 i)))) |
You might want to add a (LOAD "macros3") statement to your .clisprc file if you do not want to dump your own memory image.
Extensions-1.11. Customizing CLISP behavior.
The user-customizable variables are located in the package "CUSTOM" and thus can be listed using (APROPOS "" "CUSTOM")
Extensions-2: Platform specific Extensions
Extensions-2.1. Random Screen Access
Platform dependent: UNIX, Amiga, DOS, OS/2, Win32 platforms only.- (screen:make-window)
returns a "window stream". As long as this stream is open, the terminal is in cbreak/noecho mode. *TERMINAL-IO* should not be used for input or output during this time. (Use EXT:WITH-KEYBOARD and EXT:*KEYBOARD-INPUT* instead.)
- (screen:with-window . body)
binds screen:*window* to a window stream and executes body. The stream is guaranteed to be closed when the body is left. During its execution, *TERMINAL-IO* should not be used, as above.
- (screen:window-size window-stream)
returns the window's size, as two values: height (= ymax+1) and width (= xmax+1).
- (screen:window-cursor-position window-stream)
returns the position of the cursor in the window, as two values: line (≥0, ≤ymax, 0 means top), column (≥0, ≤xmax, 0 means left margin).
- (screen:set-window-cursor-position window-stream line column)
sets the position of the cursor in the window.
- (screen:clear-window window-stream)
clears the window's contents and puts the cursor in the upper left corner.
- (screen:clear-window-to-eot window-stream)
clears the window's contents from the cursor position to the end of window.
- (screen:clear-window-to-eol window-stream)
clears the window's contents from the cursor position to the end of line.
- (screen:delete-window-line window-stream)
removes the cursor's line, moves the lines below it up by one line and clears the window's last line.
- (screen:insert-window-line window-stream)
inserts a line at the cursor's line, moving the lines below it down by one line.
- (screen:highlight-on window-stream)
switches highlighted output on.
- (screen:highlight-off window-stream)
switches highlighted output off.
- (screen:window-cursor-on window-stream)
makes the cursor visible, a cursor block in most implementations.
- (screen:window-cursor-off window-stream)
makes the cursor invisible, in implementations where this is possible.
Extensions-2.2. External Modules
Platform dependent: UNIX platforms only.CLISP has a facility for adding external modules (written in C, for example). It is invoked through clisp-link.
A module is a piece of external code which defines extra Lisp objects, symbols and functions. A module name must consist of the characters A-Z, a-z, _, 0-9. The module name "clisp" is reserved. Normally a module name is derived from the corresponding file name.
clisp-link needs a directory containing:
modules.d
modules.c
clisp.h
clisp-link operates on CLISP linking sets and on module sets.
A linking set is a directory containing:
- makevars
some /bin/sh commands, setting the variables
- modules.h
the list of modules contained in this linking set
- modules.o
the compiled list of modules contained in this linking set
- all the FILES
listed in makevars
- lisp.run
the executable
- #P"lispinit.mem"
the memory image
To run a CLISP contained in some linking set dir, call dir/lisp.run -M dir/lispinit.mem
A module set is a directory containing:
- link.sh
some /bin/sh commands, which prepare the directory before linking, and set the variables NEW_FILES, NEW_LIBS, NEW_MODULES, TO_LOAD and optionally TO_PRELOAD
- and any other files
needed by link.sh
Note that in link.sh the module set directory is referred to as $modulename/.
- NEW_FILES
the space-separated list of files that belong to the module set and will belong to every new linking set.
- NEW_LIBS
the space-separated list of files or C compiler switches that need to be passed to the C compiler when linking the lisp.run belonging to a new linking set.
- NEW_MODULES
the space-separated list of the module names belonging to the module set. Normally, every #P".c" file in the module set defines a module of its own. The module name is derived from the file name.
- TO_LOAD
the space-separated list of Lisp files to load before building the #P"lispinit.mem" belonging to a new linking set.
- TO_PRELOAD (optional)
the space-separated list of Lisp files to load into an intermediate #P"lispinit.mem" file, before building the #P"lispinit.mem" belonging to a new linking set. This variable is usually used for defining Lisp packages which must be present when the new #P".c" files are initialized.
The command clisp-link create-module-set module-dir file1.c ... creates a module set in module-dir which refers (via symbolic links) to file1.c etc. The files are expected to be modules of their own.
The command clisp-link add-module-set module-dir source-dir destination-dir combines a linking set in source-dir and a module in module-dir to a new linking set, in a directory destination-dir which is newly created.
The command clisp-link run source-dir module-dir ... runs the linking set in source-dir, with the module in module-dir loaded. More than one module can be specified. If CLISP has been built with the configuration option --with-dynamic-modules, the loading will be performed through dynamic loading. Otherwise - this is much slower - a temporary linking set will be created and deleted afterwards. Note that dynamic loading does not work on all operating systems, and that --with-dynamic-modules precludes some efficiency optimizations which are on by default.
Example
To link in the "FFI" bindings for the GNU/Linux operating system, the following steps are needed. (Step 1 and step 2 need not be executed in this order.)
Create a new module set:
Modify the newly created linux/link.sh to add -lm; to the libraries: replace$ clisp-link create-module-set linux /somewhere/bindings/linux.c
withNEW_LIBS="$file_list"
Modify the newly created linux/link.sh to load linux.fas before saving the memory image: replaceNEW_LIBS="$file_list -lm"
withTO_LOAD=''
TO_LOAD='/somewhere/bindings/linux.fas'
Compile linux.lisp, creating linux.c:
$ clisp -c /somewhere/bindings/linux.lisp
Create a new linking set:
$ clisp-link add-module-set linux base base+linux
Run and try it:
$ base+linux/lisp.run -M base+linux/lispinit.mem > (linux::stat "/tmp")
Modules included in the distribution.
The following modules come with the distribution of CLISP:
- bindings
Call the operating system functions from CLISP. The following platforms are supported:
AmigaOS
Linux/libc5
Linux/libc6
- CLX
Call Xlib functions from CLISP. Two implementations are supplied:
mit-clx, from MIT ftp://ftp.x.org/R5contrib/CLX.R5.02.tar.Z
new-clx, by Gilbert Baumann <unk6@rz.uni-karlsruhe.de>.
- postgresql632, postgresql642
Access PostgreSQL from CLISP.
- queens
Compute the number of solutions to the n-queens problem on a n*n checkboard.
- regexp
The POSIX Regular Expressions matching, compiling, executing.
- wildcard
Shell globbing
CLISP "REGEXP" module
The "REGEXP" module implements the POSIX regular expressions via an "FFI" call to the standard C system facilities. The syntax of these regular expressions is described in many places, such as your local regexp(5) manual and Emacs info pages.
The "REGEXP" package exports the following 9 symbols:
| REGEXP:MATCH | REGEXP:MATCH-START | REGEXP:MATCH-END |
| REGEXP:MATCH-STRING | REGEXP:REGEXP-QUOTE | REGEXP:REGEXP-COMPILE |
| REGEXP:REGEXP-EXEC | REGEXP:REGEXP-SPLIT | REGEXP:WITH-LOOP-SPLIT |
API
- (REGEXP:MATCH pattern string &KEY (:START 0) :END (:CASE-SENSITIVE t))
This macro returns as first value a REGEXP::REGMATCH_T structure containing the indices of the start and end of the first match for the regular expression pattern in string; or NIL if there is no match. Additionally, a REGEXP::REGMATCH_T structure is returned for every matched "\(...\)" group in pattern, in the order that the open parentheses appear in pattern. If start is non-NIL, the search starts at that index in string. If end is non-NIL, only (SUBSEQ string start end) is considered.
Example 1. REGEXP:MATCH
(REGEXP:MATCH "quick" "The quick brown fox jumped quickly.") #S(REGEXP::REGMATCH_T :RM_SO 4 :RM_EO 9) (REGEXP:MATCH "quick" "The quick brown fox jumped quickly." :start 8) #S(REGEXP::REGMATCH_T :RM_SO 27 :RM_EO 32) (REGEXP:MATCH "quick" "The quick brown fox jumped quickly." :start 8 :end 30) NIL (REGEXP:MATCH "\\([a-z]*\\)[0-9]*\\(bar\\)" "foo12bar") #S(REGEXP::REGMATCH_T :RM_SO 0 :RM_EO 8) ; #S(REGEXP::REGMATCH_T :RM_SO 0 :RM_EO 3) ; #S(REGEXP::REGMATCH_T :RM_SO 5 :RM_EO 8)
- (REGEXP:MATCH-START match)
Extracts the start index of match.
- (REGEXP:MATCH-END match)
Extracts the end index of match.
- (REGEXP:MATCH-STRING string match)
Extracts the substring of string corresponding to the given pair of start and end indices of match. The result is shared with string. If you want a freshly consed STRING, use COPY-SEQ or (COERCE (REGEXP:MATCH-STRING ...) 'SIMPLE-STRING).
- (REGEXP:REGEXP-QUOTE string)
This function returns a regular expression string that matches exactly string and nothing else. This allows you to request an exact string match when calling a function that wants a regular expression.
One use of REGEXP:REGEXP-QUOTE is to combine an exact string match with context described as a regular expression.- (REGEXP:REGEXP-COMPILE string &OPTIONAL (case-sensitive t))
Compile the regular expression string into an object suitable for REGEXP:REGEXP-EXEC.
- (REGEXP:REGEXP-EXEC pattern string &KEY (:START 0) :END)
Execute the pattern, which must be a compiled regular expression returned by REGEXP:REGEXP-COMPILE, against the appropriate portion of the string.
- (REGEXP:REGEXP-SPLIT pattern string &KEY (:START 0) :END (:CASE-SENSITIVE t))
Return a list of substrings of string (all sharing the structure with string) separated by pattern (a regular expression string or a return value of REGEXP:REGEXP-COMPILE)
- (REGEXP:WITH-LOOP-SPLIT (variable stream pattern &KEY (:START 0) :END (:CASE-SENSITIVE t)) &BODY body)
Read lines from stream, split them with REGEXP:REGEXP-SPLIT on pattern, and bind the resulting list to variable.
The following code computes the number of people who use a particular shell:
(DEFPACKAGE "REGEXP-TEST" (:use "LISP" "REGEXP")) (IN-PACKAGE "REGEXP-TEST") (let ((h (make-hash-table :test #'equal :size 10)) (n 0)) (with-open-file (f "/etc/passwd") (with-loop-split (s f ":") (let ((sh (seventh s))) (if (gethash sh h) (incf (gethash sh h)) (setf (gethash sh h) 1))))) (with-hash-table-iterator (i h) (loop (multiple-value-bind (r k v) (i) (unless r (return)) (format t "[~d] ~s~30t== ~5:d~%" (incf n) k v))))) |
The same is done by the following Perl:
#!/usr/local/bin/perl -w
use diagnostics;
use strict;
my $IN = $ARGV[0];
open(INF,"< $IN") || die "$0: cannot read file [$IN]: $!\n;";
my %hash;
while (<INF>) {
chop;
my @all = split($ARGV[1]);
my $shell = ($#all >= 6 ? $all[6] : "");
if ($hash{$shell}) { $hash{$shell} ++; }
else { $hash{$shell} = 1; }
}
my $ii = 0;
for my $kk (keys(%hash)) {
print "[",++$ii,"] \"",$kk,"\" -- ",$hash{$kk},"\n";
}
|
Extensions-2.3. The Foreign Function Call Facility
Platform dependent: many UNIX, Win32 platforms only.A foreign function description is written as a Lisp file, and when compiled it produces a #P".c" file which is then compiled by the C compiler and may be linked together with lisp.a.
All symbols relating to the foreign function interface are exported from the package "FFI". To use them, (USE-PACKAGE "FFI").
Special "FFI" forms may appear anywhere in the Lisp file.
Overview
These are the special "FFI" forms. We have taken a pragmatic approach: the only foreign languages we support for now are C and ANSI C.
special "FFI" forms; name is any Lisp symbol; c-name is a string.
- (def-c-type name c-type)
This form makes name a shortcut for c-type. Note that c-type may already refer to name. Forward declarations of types are not possible, however.
- (def-c-var name {option}*)
This form defines a foreign variable. name is the Lisp name, a regular Lisp symbol.
The :name option specifies the name, as seen from C, as a string. If not specified, it is derived from the print name of the Lisp name.
The :type option specifies the variable's foreign type.
If the :read-only option is specified and non-NIL, it will be impossible to change the variable's value from within Lisp (using SETQ or similar).
The :alloc option can be either :NONE or :MALLOC-FREE and defaults to :NONE. If it is :MALLOC-FREE, any values of type FFI:C-STRING, FFI:C-PTR, FFI:C-PTR-NULL, FFI:C-ARRAY-PTR within the foreign value are assumed to be pointers to malloc()-allocated storage, and when SETQ replaces an old value by a new one, the old storage is freed using free() and the new storage allocated using malloc(). If it is :NONE, SETQ assumes that the pointers point to good storage (not NULL!) and overwrites the old values by the new ones. This is dangerous (just think of overwriting a string with a longer one or storing some data in a NULL pointer...) and deprecated.
- (FFI:DEF-CALL-OUT name {option}*)
Table 2.
option ::== (:name c-name) | (:arguments {(arg-name c-type [PARAM-MODE [ALLOCATION]])}*) | (:return-type c-type [ALLOCATION]) | (:LANGUAGE language) This form defines a named call-out function (a foreign function called from Lisp: control flow temporarily leaves Lisp). Any Lisp function call to #'name is redirected to call the C function c-name.
- (FFI:DEF-CALL-IN name {option}*)
Table 3.
option ::== (:name c-name) | (:arguments {(arg-name c-type [PARAM-MODE [ALLOCATION]])}*) | (:return-type c-type [ALLOCATION]) | (:LANGUAGE language) This form defines a named call-in function (i.e., a Lisp function called from the foreign language: control flow temporary enters Lisp). Any C function call to the C function c-name is redirected to call the Common Lisp function #'name.
- (FFI:DEF-C-CALL-OUT name {option}*)
This is equivalent to FFI:DEF-CALL-OUT with :LANGUAGE :STDC.
- (FFI:DEF-C-CALL-IN name {option}*)
This is equivalent to FFI:DEF-CALL-IN with :LANGUAGE :STDC.
- (FFI:DEF-C-STRUCT name (ident c-type)*)
This form defines name to be both a STRUCTURE-CLASS and a foreign C type with the given slots.
- (FFI:DEF-C-ENUM name {ident | (ident [value])}*)
This form defines idents as constants, similarly to the C declaration enum { ident [= value], ... };
- (FFI:C-LINES format-string {argument}*)
This form outputs the string (FORMAT NIL format-string {argument}*) to the C output file. This is a rarely needed low-level facility.
- (FFI:ELEMENT c-place index1 ... indexn)
Array element: If c-place is of foreign type (c-array c-type dim1 ... dimn) and 0 ≤ index1 < dim1, ..., 0 ≤ indexn < dimn, this will be the place corresponding to (AREF c-place index1 ... indexn) or c-place[index1]...[indexn]. It is a place of type c-type. If c-place is of foreign type (FFI:C-ARRAY-MAX c-type dim) and 0 ≤ index < dim, this will be the place corresponding to (AREF c-place index) or c-place[index]. It is a place of type c-type.
- (FFI:DEREF c-place)
Dereference pointer: If c-place is of foreign type (FFI:C-PTR c-type) or (FFI:C-PTR-NULL c-type), this will be the place the pointer points to. It is a place of type c-type. For (FFI:C-PTR-NULL c-type), the c-place may not be NULL.
- (FFI:SLOT c-place slot-name)
Struct or union component: If c-place is of foreign type (FFI:C-STRUCT class ... (slot-name c-type) ...) or of type (FFI:C-UNION ... (slot-name c-type) ...), this will be of type c-type.
- (FFI:CAST c-place c-type)
Type change: A place denoting the same memory locations as the original c-place, but of type c-type.
- (FFI:TYPEOF c-place)
returns the c-type corresponding to the c-place.
- (FFI:SIZEOF c-type), (FFI:SIZEOF c-place)
The first form returns the size and alignment of a C type c-type, measured in bytes.
The second form returns the size and alignment of the C type of c-place, measured in bytes.
- (FFI:BITSIZEOF c-type), (FFI:BITSIZEOF c-place)
The first form returns the size and alignment of the C type c-type, measured in bits.
The second form returns the size and alignment of the C type of c-place, measured in bits.
- (FFI:VALIDP foreign-entity)
This predicate returns NIL if the foreign-entity (e.g. the Lisp equivalent of a c-pointer) refers to a pointer which is invalid because it comes from a previous Lisp session. It returns T if foreign-entity can be used within the current Lisp process.
(Foreign) C types
Foreign C types are used in the "FFI". They are not regular Common Lisp types or CLOS classes.
A c-type is either a predefined C type or the name of a type defined by FFI:DEF-C-TYPE.
the predefined C types (c-type)
- simple-c-type
Table 4. the simple C types
Lisp name Lisp equivalent C equivalent ILU equivalent Comment NIL NIL void as a result type only BOOLEAN BOOLEAN int BOOLEAN CHARACTER CHARACTER char SHORT CHARACTER char INTEGER signed char uchar INTEGER unsigned char short INTEGER short ushort INTEGER unsigned short int INTEGER int uint INTEGER unsigned int long INTEGER long ulong INTEGER unsigned long uint8 (UNSIGNED-BYTE 8) uint8 BYTE sint8 (SIGNED-BYTE 8) sint8 uint16 (UNSIGNED-BYTE 16) uint16 SHORT CARDINAL sint16 (SIGNED-BYTE 16) sint16 SHORT INTEGER uint32 (UNSIGNED-BYTE 32) uint32 CARDINAL sint32 (SIGNED-BYTE 32) sint32 INTEGER uint64 (UNSIGNED-BYTE 64) uint64 LONG CARDINAL does not work on all platforms sint64 (SIGNED-BYTE 64) sint64 LONG INTEGER does not work on all platforms SINGLE-FLOAT SINGLE-FLOAT float DOUBLE-FLOAT DOUBLE-FLOAT double - FFI:C-POINTER
This type corresponds to what C calls void*, an opaque pointer.
- FFI:C-STRING
This type corresponds to what C calls char*, a zero-terminated string. Its Lisp equivalent is a string, without the trailing zero character.
- (FFI:C-STRUCT class (ident1 c-type1) ... (identn c-typen))
This type is equivalent to what C calls struct { c-type1 ident1; ...; c-typen identn; }. Its Lisp equivalent is: if class is VECTOR, a SIMPLE-VECTOR; if class is LIST, a list; if class is a symbol naming a structure or CLOS class, an instance of this class, with slots of names ident1, ... ,identn.
- (FFI:C-UNION (ident1 c-type1) ... (identn c-typen))
This type is equivalent to what C calls union { c-type1 ident1; ...; c-typen identn; }. Conversion to and from Lisp assumes that a value is to be viewed as being of c-type1.
- (FFI:C-ARRAY c-type dim1 ... dimn)
This type is equivalent to what C calls c-type [dim1] ... [dimn]. Note that when an array is passed as an argument to a function in C, it is actually passed as a pointer; you therefore have to write (FFI:C-PTR (FFI:C-ARRAY ...)) for this argument's type.
- (FFI:C-ARRAY-MAX c-type maxdimension)
This type is equivalent to what C calls c-type [maxdimension], an array containing up to maxdimension elements. The array is zero-terminated if it contains less than maxdimension elements. Conversion from Lisp of an array with more than maxdimension elements silently ignores the superfluous elements.
- (FFI:C-FUNCTION (:ARGUMENTS {(arg-name a-c-type [PARAM-MODE [ALLOCATION]])}*) (:return-type r-c-type [ALLOCATION]) (:LANGUAGE language))
This type designates a C function that can be called according to the given prototype (r-c-type (*) (a-c-type1, ...)). Conversion between C functions and Lisp functions is transparent.
- (FFI:C-PTR c-type)
This type is equivalent to what C calls c-type *: a pointer to a single item of the given c-type.
- (FFI:C-PTR-NULL c-type)
This type is also equivalent to what C calls c-type *: a pointer to a single item of the given c-type, with the exception that C NULL corresponds to Lisp NIL.
- (FFI:C-ARRAY-PTR c-type)
This type is equivalent to what C calls c-type (*)[]: a pointer to a zero-terminated array of items of the given c-type.
The choice of the C flavor.
FFI:C-FUNCTION, FFI:DEF-CALL-IN, FFI:DEF-CALL-OUT take :LANGUAGE argument. The language is either :C (denotes K&R C) or :STDC (denotes ANSI C) or :STDC-STDCALL (denotes ANSI C with stdcall calling convention). It specifies whether the C function (caller or callee) has been compiled by a K&R C compiler or by an ANSI C compiler, and possibly the calling convention.
Foreign variables
Foreign variables are variables whose storage is allocated in the foreign language module. They can nevertheless be evaluated and modified through SETQ, just as normal variables can, except that the range of allowed values is limited according to the variable's foreign type. Note that for a foreign variable x the form (EQL x x) is not necessarily true, since every time x is evaluated its foreign value is converted to a freshly created Lisp value. Foreign variables are defined using FFI:DEF-C-VAR.
Operations on foreign places
A foreign variable name defined by FFI:DEF-C-VAR defines a "place", i.e., a form which can also be used as argument to SETF. (An "lvalue" in C terminology.) The following operations are available on foreign places: FFI:ELEMENT, FFI:DEREF, FFI:SLOT, FFI:CAST, FFI:TYPEOF, FFI:SIZEOF, FFI:BITSIZEOF.
Foreign functions
Foreign functions are functions which are defined in the foreign language. There are named foreign functions (imported via FFI:DEF-CALL-OUT or created via FFI:DEF-CALL-IN) and anonymous foreign functions; they arise through conversion of function pointers.
A "call-out" function is a foreign function called from Lisp: control flow temporarily leaves Lisp. A "call-in" function is a Lisp function called from the foreign language: control flow temporary enters Lisp.
The following forms define foreign functions: FFI:DEF-CALL-IN, FFI:DEF-CALL-OUT, FFI:DEF-C-CALL-IN, FFI:DEF-C-CALL-OUT.
Argument and result passing conventions
When passed to and from functions, allocation of arguments and results is handled as follows:
Values of SIMPLE-C-TYPE, FFI:C-POINTER are passed on the stack, with dynamic extent. The ALLOCATION is effectively ignored.
Values of type FFI:C-STRING, FFI:C-PTR, FFI:C-PTR-NULL, FFI:C-ARRAY-PTR need storage. The ALLOCATION specifies the allocation policy:
Table 5. allocation policy
| ALLOCATION | meaning |
|---|---|
| :NONE | no storage is allocated. |
| :ALLOCA | allocation of storage on the stack, which has dynamic extent. |
| :MALLOC-FREE | storage will be allocated via malloc() and freed via free(). |
If no ALLOCATION is specified, the default ALLOCATION is :NONE for most types, but :ALLOCA for FFI:C-STRING and FFI:C-PTR and FFI:C-PTR-NULL and FFI:C-ARRAY-PTR and for :OUT arguments. [Subject to change!] The :MALLOC-FREE policy provides the ability to pass arbitrarily nested structs containing pointers pointing to structs ... within a single conversion.
- For call-out functions:
- For arguments passed from Lisp to C:
- If ALLOCATION is :MALLOC-FREE:
Lisp allocates the storage using malloc() and never deallocates it. The C function is supposed to call free() when done with it.
- If ALLOCATION is :ALLOCA:
Lisp allocates the storage on the stack, with dynamic extent. It is freed when the C function returns.
- If ALLOCATION is :NONE:
Lisp assumes that the pointer already points to a valid area of the proper size and puts the result value there. This is dangerous! and deprecated.
- For results passed from C to Lisp:
- If ALLOCATION is :MALLOC-FREE:
Lisp calls free() on it when done.
- If ALLOCATION is :NONE:
Lisp does nothing.
- For call-in functions:
- For arguments passed from C to Lisp:
- If ALLOCATION is :MALLOC-FREE:
Lisp calls free() on it when done.
- If ALLOCATION is :ALLOCA or :NONE:
Lisp does nothing.
- For results passed from Lisp to C:
- If ALLOCATION is :MALLOC-FREE:
Lisp allocates the storage using malloc() and never deallocates it. The C function is supposed to call free() when done with it.
- If ALLOCATION is :NONE:
Lisp assumes that the pointer already points to a valid area of the proper size and puts the result value there. This is dangerous! and deprecated.
A function parameter's PARAM-MODE may be
- :IN (means: read-only):
The caller passes information to the callee.
- :OUT (means: write-only):
The callee passes information back to the caller on return. When viewed as a Lisp function, there is no Lisp argument corresponding to this, instead it means an additional return value.
- :IN-OUT (means: read-write):
Information is passed from the caller to the callee and then back to the caller. When viewed as a Lisp function, the :OUT value is returned as an additional multiple value.
The default is :IN.
[Currently, only :IN is fully implemented. :OUT works only with ALLOCATION = :ALLOCA.]
- Platform dependent: Amiga platforms only.
ALLOCATION may not be :MALLOC-FREE because there is no commonly used malloc()/free() library function.
The ALLOCATION may be followed by a register specification, any of the symbols :d0, :d1, :d2, :d3, :d4, :d5, :d6, :d7, :a0, :a1, :a2, :a3, :a4, :a5, :a6, each representing one 680x0 register. This works only for integral types: integers, pointers, FFI:C-STRING, FFI:C-FUNCTION.
Passing FFI:C-STRUCT, FFI:C-UNION, FFI:C-ARRAY, FFI:C-ARRAY-MAX values as arguments (not via pointers) is only possible to the extent the C compiler supports it. Most C compilers do it right, but some C compilers (such as gcc on hppa) have problems with this.
See also CUSTOM:*FOREIGN-ENCODING*.
Examples
Example 3. Simple declarations and access
The C declaration
struct foo {
int a;
struct foo * b[100];
};
|
(def-c-struct foo (a int) (b (c-array (c-ptr foo) 100))) |
The element access
struct foo f; f.b[7].a |
(declare (type foo f)) (foo-a (aref (foo-b f) 7)) or (slot-value (aref (slot-value f 'b) 7) 'a) |
Example 4. external C variable and some accesses
struct bar {
short x, y;
char a, b;
int z;
struct bar * n;
};
extern struct bar * my_struct;
my_struct->x++;
my_struct->a = 5;
my_struct = my_struct->n;
|
(def-c-struct bar (x short) (y short) (a char) (b char) ; or (b character) if it represents a character, not a number (z int) (n (c-ptr bar))) (def-c-var my_struct (:type (c-ptr bar))) (setq my_struct (let ((s my_struct)) (incf (slot-value s 'x)) s)) or (incf (slot my_struct 'x)) (setq my_struct (let ((s my_struct)) (setf (slot-value s 'a) 5) s)) or (setf (slot my_struct 'a) 5) (setq my_struct (slot-value my_struct 'n)) or (setq my_struct (deref (slot my_struct 'n))) |
Example 5. Calling an external function
On ANSI C systems, stdlib.h contains the declarations:
typedef struct {
int quot; /* Quotient */
int rem; /* Remainder */
} div_t;
extern div_t div (int numer, int denom);
|
(def-c-struct div_t
(quot int)
(rem int))
(def-c-call-out div (:arguments (numer int) (denom int))
(:return-type div_t))
|
> (div 20 3) #S(DIV :QUOT 6 :REM 2) |
Example 6. Another example for calling an external function
Suppose the following is defined in a file cfun.c:
struct cfunr { int x; char *s; };
struct cfunr * cfun (int i,char *s,struct cfunr * r,int a[10]) {
int j;
struct cfunr * r2;
printf("i = %d\n", i);
printf("s = %s\n", s);
printf("r->x = %d\n", r->x);
printf("r->s = %s\n", r->s);
for (j = 0; j < 10; j++) printf("a[%d] = %d.\n", j, a[j]);
r2 = (struct cfunr *) malloc (sizeof (struct cfunr));
r2->x = i+5;
r2->s = "A C string";
return r2;
}
|
(DEFPACKAGE "TEST-C-CALL" (:use "LISP" "FFI")) (IN-PACKAGE "TEST-C-CALL") (def-c-struct cfunr (x int) (s c-string)) (def-c-call-out cfun (:arguments (i int) (s c-string) (r (c-ptr cfunr) :in :alloca) (a (c-ptr (c-array int 10)) :in :alloca)) (:return-type (c-ptr cfunr))) (defun call-cfun () (cfun 5 "A Lisp string" (make-cfunr :x 10 :s "Another Lisp string") '#(0 1 2 3 4 5 6 7 8 9))) |
$ clisp-link create-module-set cfun callcfun.c $ cc -O -c cfun.c $ cd cfun $ ln -s ../cfun.o cfun.o Add cfun.o to NEW_LIBS and NEW_FILES in link.sh. $ cd .. $ base/lisp.run -M base/lispinit.mem -c callcfun.lisp $ clisp-link add-module-set cfun base base+cfun $ base+cfun/lisp.run -M base+cfun/lispinit.mem -i callcfun > (test-c-call::call-cfun) i = 5 s = A Lisp string r->x = 10 r->s = Another Lisp string a[0] = 0. a[1] = 1. a[2] = 2. a[3] = 3. a[4] = 4. a[5] = 5. a[6] = 6. a[7] = 7. a[8] = 8. a[9] = 9. #S(TEST-C-CALL::CFUNR :X 10 :S "A C string") > $ rm -r base+cfun |
Note that there is a memory leak here: The return value r2 of cfun() is malloc()ed but never free()d. Specifying
(:return-type (c-ptr cfunr) :malloc-free) |
Example 7. call-in
To sort an array of double-floats using the Lisp function sort instead of the C library function qsort(), one can use the following interface code sort1.c. The main problem is to pass a variable-sized array.
extern void lispsort_begin (int);
void* lispsort_function;
void lispsort_double (int n, double * array) {
double * sorted_array;
int i;
lispsort_begin(n); /* store #'sort2 in lispsort_function */
sorted_array = ((double * (*) (double *)) lispsort_function) (array);
for (i = 0; i < n; i++) array[i] = sorted_array[i];
free(sorted_array);
}
|
(DEFPACKAGE "FFI-TEST" (:use "LISP" "FFI")) (IN-PACKAGE "FFI-TEST") (def-call-in lispsort_begin (:arguments (n int)) (:return-type nil) (:language :stdc)) (def-c-var lispsort_function (:type c-pointer)) (defun lispsort_begin (n) (setf (cast lispsort_function `(c-function (:arguments (v (c-ptr (c-array double-float ,n)))) (:return-type (c-ptr (c-array double-float ,n)) :malloc-free))) #'sort2)) (defun sort2 (v) (declare (type vector v)) (sort v #'<)) |
(def-call-out sort10
(:name "lispsort_double")
(:language :stdc)
(:arguments (n int)
(array (c-ptr (c-array double-float 10))
:in-out)))
|
$ clisp-link create-module-set sort sort2.c sorttest.c
$ cc -O -c sort1.c
$ cd sort
$ ln -s ../sort1.o sort1.o
Add sort1.o to NEW_LIBS and NEW_FILES in link.sh.
$ cd ..
$ base/lisp.run -M base/lispinit.mem -c sort2.lisp sorttest.lisp
$ clisp-link add-module-set sort base base+sort
$ base+sort/lisp.run -M base+sort/lispinit.mem -i sort2 sorttest
> (sort10 10 '#(0.501d0 0.528d0 0.615d0 0.550d0 0.711d0
0.523d0 0.585d0 0.670d0 0.271d0 0.063d0))
#(0.063d0 0.271d0 0.501d0 0.523d0 0.528d0 0.55d0 0.585d0 0.615d0 0.67d0 0.711d0)
$ rm -r base+sort
|
Extensions-2.4. The Amiga Foreign Function Call Facility
Platform dependent: Amiga platforms only.Another Foreign Function Interface. All symbols relating to the simple foreign function interface are exported from the package "AFFI". To use them, (USE-PACKAGE "AFFI").
Design issues
"AFFI" was designed to be small in size but powerful enough to use most library functions. Lisp files may be compiled to #P".fas" files without the need to load function definition files at run-time and without external C or linker support. memory images can be created, provided that the function libraries are opened at run-time.
Therefore, "AFFI" supports only primitive C types (integers 8, 16 and 32 bits wide, signed or unsigned, pointers) and defines no new types or classes. Foreign functions are not first-class objects (you can define a lambda yourself), name spaces are separate.
The "AFFI" does no tracking of resources. Use EXT:FINALIZE.
Overview
These are the "AFFI" forms:
(declare-library-base keyword-base library-name)
(require-library-functions library-name [(:import {string-name}*)])
(open-library base-symbol)
(clos-library base-symbol)
(with-open-library (base-symbol | library-name) {form}*)
(defflibfun function-name base-symbol offset mask result-type {argument-type}*)
(declare-library-function function-name library-name {option}*)
(flibcall function-name {argument}*)
(mlibcall function-name {argument}*)
(mem-read address result-type [offset])
(mem-write address type value [offset])
(mem-write-vector address vector [offset])
(nzero-pointer-p value)
Except for with-open-library, declare-library-function and mlibcall, all of the above are functions.
A library contains a collection of functions. The library is referred to by a symbol referred as library-base at the "AFFI" level. This symbol is created in the package "'AFFI'". The link between this symbol and the OS-level library name is established by declare-library-base. To avoid multiple package conflicts, this and only this function requires the symbol-name to be in the "KEYWORD" package. The function returns the library-base.
A library may be opened by open-library and closed by close-library. An opened library must be closed. with-open-library is provided to automatically close the library for you, thus it is much safer to use.
A function is contained in a library. Every function is referred to by a symbol. A function is defined through defflibfun or declare-library-function by giving the function name, the library-base, an offset into the library, a mask (or NIL) for register-based library calls, the result type and all parameter-types. require-library-functions loads the complete set of functions defined in a library file. Symbols are created in the package "'AFFI'" and imported into the current package.
flibcall and mlibcall call library functions. mlibcall is a macro that does a few checks at macroexpansion time and allows the compiler to inline the call, not requiring the foreign function to be defined again at load or execution time. The use of this macro is advertised wherever possible.
mem-read reads an arbitrary address (with offset for structure references) and returns the given type.
mem-write writes an arbitrary address. mem-write-vector copies the content of a Lisp STRING or (VECTOR (UNSIGNED-BYTE 8)) into memory.
nzero-pointer-p tests for non-NULL pointers in all recognized representations (NULL, UNSIGNED-BYTE and FFI:FOREIGN-POINTER).
Foreign Libraries
declare-library-base ought to be wrapped in an (EVAL-WHEN (compile eval load) ...) form and come before any function is referenced, because the library base symbol must be known.
open-library tries to open the library referenced by the base symbol. Therefore it must have been preceded with declare-library-base. The call returns NIL on failure. open-library calls nest. Every successful call must be matched by close-library. with-open-library does this for you and also allows you to specify the library by name, provided that its base has been declared. It is recommended to use this macro and to reference the library by name.
CLISP will not close libraries for you at program exit. [A previous version did so but now "AFFI" is a module and there are no module exit functions.] Programmers, watch AFFI::*LIBRARIES-ALIST*.
(Foreign) C types
The following foreign C types are used in "AFFI". They are not regular Common Lisp types or CLOS classes.
Table 6. foreign C types used in "AFFI"
| "AFFI" name | Lisp equivalent | C equivalent | Comment | |
|---|---|---|---|---|
| NIL | NIL | void | as a result type for functions only | |
| 4 | (UNSIGNED-BYTE 32) | unsigned long | ||
| 2 | (UNSIGNED-BYTE 16) | unsigned short | ||
| 1 | (UNSIGNED-BYTE 8) | unsigned char | ||
| -4 | (SIGNED-BYTE 32) | long | ||
| -2 | (SIGNED-BYTE 16) | short | ||
| -1 | (SIGNED-BYTE 8) | signed char | ||
| 0 | BOOLEAN | BOOL | as a result type for functions only | |
| * | opaque | void* | ||
| :EXTERNAL | opaque | void* | ||
| STRING | STRING or VECTOR | char* | ||
| :IO | STRING or VECTOR | char* |
Objects of type STRING are copied and passed NULL-terminated on the execution stack. On return, a Lisp string is allocated and filled from the address returned (unless NULL). Functions with :IO parameters are passed the address of the Lisp string or unsigned byte vector. These are not NULL-terminated! This is useful for functions like like read() which do not need an array at a constant address longer than the dynamic extent of the call (it is dangerous to define callback functions with :IO (or STRING) type parameters). Arguments of type INTEGER and FFI:FOREIGN-POINTER are always acceptable where a STRING or :IO type is specified.
See also CUSTOM:*FOREIGN-ENCODING*.
To meet the design goals, predefined types and objects were used. As such, pointers were represented as integers. Now that there is the FFI:FOREIGN-POINTER type, both representations may be used on input. The pointer type should be therefore considered as opaque. Use nzero-pointer-p for NULL tests.
Foreign functions
Foreign Functions are declared either through defflibfun or declare-library-function. The former is closer to the low-level implementation of the interface, the latter is closer to the other "FFI".
defflibfun requires the library base symbol and register mask to be specified, declare-library-function requires the library name and computes the mask from the declaration of the arguments.
The value of mask is implementation-dependent. On the Amiga, it is an integer whose hexadecimal value is the reverse of the function argument register numbers, where d0 has number 1 and a6 number #xF. A NIL mask is reserved for stack-based calls (unimplemented).
The "AFFI" type 0 is only acceptable as a function result type and yields either T or NIL. The difference between * and :EXTERNAL is the following: * uses integers, :EXTERNAL uses FFI:FOREIGN-POINTER as function result-type (except from NIL for a NULL pointer) and refuses objects of type STRING or (VECTOR (UNSIGNED-BYTE 8)) as input. Thus :EXTERNAL provides some security on the input and the ability to use EXT:FINALIZE for resource-tracking on the output side.
(declare-library-function name library-name {option}*)
- option ::==
- register ::==
:d0 | :d1 | ... | :d7 | :a0 | ... | :a6
mlibcall should be the preferred way of calling foreign functions (when they are known at compile-time) as macroexpansion-time checks may be performed and the call can be sort of inlined.
Memory access
(affi:mem-read address type offset) can read 8, 16 and 32 bit signed or unsigned integers ("AFFI" types -4, -2, -1, 1, 2, 4), a pointer (*), a NULL-terminated string (string) or, if the type argument is of type STRING or (VECTOR (UNSIGNED-BYTE 8)), it can fill this vector. :EXTERNAL is not an acceptable type as no object can be created by using affi:mem-read.
(affi:mem-write address type value [offset]) writes integers ("AFFI" type -4, -2, -1, 1, 2 and 4) or pointer values (type *), but not vectors to the specified memory address.
(affi:mem-write-vector address vector [offset]) can write memory from the given vector (of type STRING or (VECTOR (UNSIGNED-BYTE 8))).
Function Definition Files
affi:require-library-functions will REQUIRE a file of name derived from thelibrary name and with type affi. It may be used to import all names into the current package or only a given subset identified by string names, using the :import keyword (recommended use). Some definition files for standard Amiga libraries are provided. See example 1 below.
As affi:require-library-functions loads a global file which you, the programmer, may have not defined, you may consider declaring every function yourself to be certain what the return and argument types are. See example 4 below.
The file read-fd.lisp defines the function make-partial-fd-file with which the provided .affi files have been prepared from the original Amiga FD files (located in the directory FD:). They must still be edited as the function cannot know whether a function accepts a *, :IO, string or :EXTERNAL argument and because files in FD: only contain a register specification, not the width of integer arguments (-4, -2, -1, 1, 2, or 4).
Hints
By using appropriate EVAL-WHEN forms for affi:declare-library-base and affi:require-library-functions and not using affi:flibcall, it is possible to write code that only loads library function definition files at compile-time. See example 1 below.
Do not rely on EXT:FINALIZE to free resources for you, as CLISP does not call finalizers when it exits, use UNWIND-PROTECT.
Caveats
You can consider the library bases being symbols in need of being imported from the package "AFFI" originating from a brain-damage, causing the usual symbol headaches when using foreign functions calls within macros. Luckily, even if the high-level interface (or its implementation in affi1.lisp) were to change, the low-level part (affi.d) should remain untouched as all it knows are INTEGERs and FFI:FOREIGN-POINTERs, no SYMBOLs. The difficulty is just to get the library base value at run-time. Feel free to suggest enhancements to this facility!
Examples
NB: These examples are somewhat specific to the Amiga.Example 8. Using a predefined library function file
(DEFPACKAGE "AFFI-TEST" (:use "LISP" "AFFI")) (IN-PACKAGE "AFFI-TEST") ;; SysBase is the conventional name for exec.library ;; It is only enforced by the file loaded by REQUIRE-LIBRARY-FUNCTIONS (eval-when (compile eval load) (declare-library-base :SysBase "exec.library")) ;keyword avoids name conflicts ;; using only MLIBCALL allows not to load definitions at load-time (eval-when (compile eval) (require-library-functions "exec.library" :import '("FindTask"))) (with-open-library ("exec.library") (print (mlibcall FindTask 0))) |
Example 9. Using flibcall
(DEFPACKAGE "AFFI-TEST" (:use "LISP" "AFFI")) (IN-PACKAGE "AFFI-TEST") (eval-when (compile eval load) ;; keyword avoids name conflicts (declare-library-base :SysBase "exec.library")) ;; The load situation permits the use of flibcall (eval-when (eval compile load) (require-library-functions "exec.library")) (unless (open-library 'SysBase) (error "No library for SysBase")) (flibcall (if t 'FindTask 'Debug) 0) (close-library 'SysBase) |
Example 10. Be fully dynamic, defining library bases ourselves
(DEFPACKAGE "AFFI-TEST" (:use "LISP" "AFFI")) (IN-PACKAGE "AFFI-TEST") (eval-when (compile eval load) (defvar mylib (declare-library-base :foobase "foo.library"))) (eval-when (eval compile load) ;eval allows mlibcall, load flibcall (defflibfun 'foo1 mylib -30 '#xA '* 'string) (defflibfun 'foo2 mylib -36 '#x21 0 * 4)) (defun foo (name) (when (open-library mylib) (list (mlibcall foo1 name) (flibcall 'foo2 name 123213)) (close-library mylib))) |
Example 11. Some sample function definitions
(defflibfun 'FindTask 'SysBase -294 #xA '* 'string)
(eval-library-function FindTask "exec.library"
(:offset -294)
(:return-type *)
(:arguments
(name string :A1)))
(declare-library-function NameFromLock "dos.library"
(:offset -402)
(:return-type 0)
(:arguments
(lock 4 :D1)
(buffer :io :D2)
(len 4 :D3)))
(eval-when (compile eval)
(defconstant GVF_LOCAL_ONLY (ash 1 9))
(defflibfun 'SetVar 'DosBase -900 #x5432 0 'string 'string -4 4))
(defun setvar (name value)
(with-open-library (DosBase)
;; length of -1 means find length of NULL-terminated-string
(mlibcall SetVar name value -1 GVF_LOCAL_ONLY)))
|
Extensions-2.5. ARexx
Platform dependent: Amiga platforms only.CLISP comes with a small yet extensible and powerful ARexx interface.
- (rexx-do-command "return address()" :string T :result T)
tells you the name of the CLISP ARexx port. The default extension for CLISP ARexx scripts is cl.
- (rexx-do-command command &KEY :string :result :token :io :host)
- (rexx-run-command command &KEY :string :token)
- (rexx-send-command command &KEY :string :result :token :io :host)
-> arexx-msg-handle, or NIL on failure
- (rexx-wait-sent-command arexx-msg-handle)
- (rexx-loop)
-> no return, use the exit-loop.cl ARexx script to abort the loop
command may be a string denoting a command with optional arguments or a vector of strings thus denoting an ARexx function call. The first element in the vector is the function name, the others are the up to 15 arguments.
Messages may be sent to an arbitrary ARexx host, special cases are NIL (meaning "REXX", the default) and T ("AREXX" for asynchronous execution).
ARexx server mode: Like Ispell, Csh and SKsh, you can run it in server mode by calling (rexx-loop). You can then only exit with the ARexx exit-loop.cl script.
Restrictions: Currently CLISP is not able to wait for input from several sources, e.g. both a console and ARexx, at the same time.
Extensions-2.6. Socket Streams
Platform dependent: UNIX, Win32 platforms only.- (SOCKET:SOCKET-SERVER &OPTIONAL [port-or-socket])
This function creates a socket, binds a port to the socket, and then listens for connect attempts. The server exists to watch for client connect attempts. The optional argument is either a port (positive FIXNUM) or a SOCKET:SOCKET-STREAM (from whose peer the connections will be made).
- (SOCKET:SOCKET-SERVER-CLOSE socket-server)
Closes down the server socket.
- (SOCKET:SOCKET-SERVER-PORT socket-server)
Returns the port which was bound using SOCKET:SOCKET-SERVER.
- (SOCKET:SOCKET-WAIT socket-server &OPTIONAL [seconds [microseconds]])
Wait for a fixed time for a connection on the socket-server (a SOCKET:SOCKET-SERVER). Without a timeout argument, SOCKET:SOCKET-WAIT blocks indefinitely. When timeout is zero, poll.
- (SOCKET:SOCKET-ACCEPT socket-server &KEY :ELEMENT-TYPE :EXTERNAL-FORMAT :BUFFERED)
Creates the server-side two-way stream for the connection.
- (SOCKET:SOCKET-CONNECT port &OPTIONAL [host] &KEY :ELEMENT-TYPE :EXTERNAL-FORMAT :BUFFERED)
Attempts to create a client-side two-way SOCKET:SOCKET-STREAM. Blocks until the server accepts the connections.
- (SOCKET:SOCKET-STATUS socket-stream-or-list &OPTIONAL [seconds [microseconds]])
Checks whether it is possible to read from or write to a SOCKET:SOCKET-STREAM or whether a connection is available on a SOCKET:SOCKET-SERVER without blocking. (For the cognoscenti: this is the interface to select(2)). This is similar to LISTEN, which checks only one stream and only for input, and SOCKET:SOCKET-WAIT, which works only with SOCKET:SOCKET-SERVERs.
Possible values of socket-stream-or-list
- SOCKET:SOCKET-STREAM or SOCKET:SOCKET-SERVER
Returns T if a connection on the SOCKET:SOCKET-SERVER is available; or :INPUT, :OUTPUT or :IO if some input/output is possible on the SOCKET:SOCKET-STREAM
- (SOCKET:SOCKET-STREAM . direction)
Return the appropriate keyword (:INPUT, :OUTPUT or :IO) if some input/output is possible on the SOCKET:SOCKET-STREAM in the specified direction (which should be one of :INPUT, :OUTPUT or :IO).
- a list of the above
Return a list of values, one for each element of the argument list (a la MAPCAR)
The optional arguments specify the timeout. NIL means wait forever, 0 means poll. Note that this function never waits for input or output to arrive, only for information on input or output presense (so that READ-CHAR or WRITE-CHAR will not block) to become available (or a connection to become possible).
For each SOCKET:SOCKET-STREAM this function returns
Return values of SOCKET:SOCKET-STATUS
- NIL
when no information is available or no operation is possible
- :ERROR
when an i/o operation will cause an error
- :INPUT
when you can only read from the stream
- :OUTPUT
when you can only write to the stream
- :IO
when you can both read from and write to the stream
- (SOCKET:SOCKET-STREAM-HOST socket-stream), (SOCKET:SOCKET-STREAM-PORT socket-stream)
These two functions return information about the SOCKET:SOCKET-STREAM. For a server, SOCKET:SOCKET-STREAM-HOST returns NIL.
- (SOCKET:SOCKET-SERVICE-PORT &OPTIONAL service-name (protocol "tcp"))
A convenience function for looking up a port given the service name. It returns the servent struct as multiple values (name, list of aliases, port, protocol) for the given service-name and protocol, or all services as the list of vectors of LENGTH 4, if service-name is not given or is :DEFAULT or NIL.
- (SOCKET:SOCKET-STREAM-PEER socket-stream [do-not-resolve-p])
Given a stream, this function returns the name of the host on the opposite side of the connection and its port number; the server-side can use this to see who connected.
When the optional second argument is non-NIL, the hostname resolution is disabled and just the IP address is returned, without the FQDN (Fully Qualified Domain Name).
- (SOCKET:SOCKET-STREAM-LOCAL socket-stream [do-not-resolve-p])
The dual to SOCKET:SOCKET-STREAM-PEER - same information, host name and port number, but for the local host. The difference from SOCKET:SOCKET-STREAM-HOST and SOCKET:SOCKET-STREAM-PORT is that this function asks the OS (and thus returns the correct trusted values) while the other two are just accessors to the internal data structure, and basically return the arguments given to the function which created the SOCKET:SOCKET-STREAM.
Extensions-2.7. System Calls
When CLISP is configured with an option --with-export-syscalls, some system calls are available from lisp, in package "POSIX".
- (posix:resolve-host-ipaddr &OPTIONAL host)
Returns the hostent struct (name, list of aliases, list of IP addresses as dotted quads (for IPv4) or coloned octets (for IPv6), address type - IPv4 or IPv6). When host is omitted or :DEFAULT, return the data for the current host. When host is given and is NIL, all the host database is returned as a list (this would be the contents of the /etc/hosts file on a UNIX system or ${windir}/system32/etc/hosts on a Win32 system).
- (posix:file-stat pathname &OPTIONAL link-p)
Return the stat struct. pathname can be a STREAM, a PATHNAME, a STRING or a NUMBER (on a UNIX system, meaning file descriptor). The first slot of the struct returned is the string or the number on which stat(2)/fstat(2)/lstat(2) was called. The other 13 slots are numbers, members of the stat struct: device, inode, protection, number of hard links, owner's UID, owner's GID, device type, total size (bytes), blocksize for filesystem I/O, number of blocks allocated, atime, mtime, ctime (as the number of seconds since 1900-01-01). If the system does not support a particular field (e.g., Win32 does not have hard links), NIL (or the default, like 1 for the number of hard links for Win32 or DOS) is returned.
[UNIX systems only at this time, patches are welcome.]
- (posix:user-data &OPTIONAL user)
Return the passwd struct (name, encoded password, UID, GID, full name, home directory, shell). When user is NIL, return all users. When user is :DEFAULT or not supplied, return the information about the current user. If the system does not support a particular field (e.g., Win32 does not have a concept of a shell), NIL (or the default, like c:\command.com for DOS) is returned.
[UNIX systems only at this time, patches are welcome.]
- (posix:sysinfo)
Return a struct describing the OS, derived from uname(2) and sysconf(3).
- (posix:resource-usage-limits)
Return 3 structs describing the resources usage and limits, derived from getrlimit(2) and getrusage(3).
- (posix:erf real) (posix:erfc real) (posix:j0 real) (posix:j1 real) (posix:jn integer real) (posix:y0 real) (posix:y1 real) (posix:yn integer real) (posix:gamma real) (posix:lgamma real)
Compute the error functions, Bessel functions and Gamma. These functions are required by the POSIX standard and should be available in libm.so. Please note that these functions do not provide lisp-style error handling and precision, and do all the computations at the double float level.
[UNIX systems only at this time, patches are welcome.]
Extensions-2.8. Quickstarting delivery with CLISP
This section describes four ways to turn CLISP programs into executable programs, which can be started as quickly as executables written in other languages.
- UNIX
CLISP can act as a script interpreter.
- Desktop environments such as KDE, GNOME, or Windows.
Files created with CLISP can be associated with the CLISP executables so that clicking on them would make CLISP execute the appropriate code.
- Linux kernel with CONFIG_BINFMT_MISC=y
Associate the extensions #P".fas" and #P".lisp" with CLISP; then you can make the files executable and run them from the command line.
- Amiga
Files created with CLISP can be associated with a Workbench project icon so that clicking on them would make CLISP execute the appropriate code. Note that several #P".fas" files can be concatenated (using Join) into one file.
These four techniques apply to a single #P".lisp" or #P".fas" file. If your application is made up of several #P".lisp" or #P".fas" files, you can simply concatenate them (using cat(1)) into one file; the techniques then apply to that concatenated file.
- Platform dependent: UNIX platforms only.
On Unix, a text file (#P".fas" or #P".lisp") can be made executable by adding a first line of the form
and using chmod(1) to make the script executable. CLISP can be used as a script interpreter under the following circumstances:#!interpreter [interpreter-arguments]
The interpreter must be the full pathname of CLISP. The recommended path is /usr/local/bin/clisp, and if CLISP is actually installed elsewhere, making /usr/local/bin/clisp be a symbolic link to the real CLISP.
The interpreter must be a real executable, not a script. Unfortunately, in the binary distributions of CLISP on Solaris, clisp is a shell script because a C compiler cannot be assumed to be installed on this platform. If you do have a C compiler installed, build CLISP from the source yourself; make install will install clisp as a real executable.
On some platforms, the first line which specifies the interpreter is limited in length:
max. 32 characters on SunOS 4,
max. 80 characters on HP-UX,
max. 127 characters on Linux.
On Solaris and HP-UX, only the first interpreter-arg is passed to the interpreter. In order to pass more than one option (for example, -Msomewhere.mem and -C) to CLISP, separate them by hard spaces (ISO Latin-1 character 160) instead of normal spaces. (But the separator between interpreter and interpreter-arguments must still be a normal space!) CLISP will split the interpreter-arguments at hard spaces and at normal spaces.
The script should contain Lisp forms, except in the #! line. The file is loaded normally, through the function LOAD. Before it is loaded, the variable ext:*args* is bound to a list of strings, representing the arguments given to the Lisp script. *STANDARD-INPUT* and *STANDARD-OUTPUT* are bound, as usual, to the Unix standard input and output. *ERROR-OUTPUT* is bound to the Unix error output. Continuable errors will be turned to warnings. Non-continuable errors and Control-C interrupts will terminate the execution of the Lisp script with an error status. If you wish the script's contents to be compiled during loading, add -C to the interpreter-arguments.
Another, quite inferior, alternative is to put the following into a file:
#!/bin/sh exec clisp <<EOF (lisp-form) (another-lisp-form) (yet-another-lisp-form) EOF
The problem with this approach is that the return values of each form will be printed to the standard output. Another problem is that no user input will be available.
- Platform dependent: Win32 platforms only.
There are two different ways to make CLISP "executables" for Windows platforms.
Associate the #P".mem" extension with c:\clisp\lisp.exe -B c:\clisp -M %s.
Associate the #P".fas" extension with c:\clisp\lisp.exe -B c:\clisp -M c:\clisp\lispinit.mem -i %s. Alternatively, you may want to have a function main in your #P".fas" files and associate the #P".fas" extension with c:\clisp\lisp.exe -B c:\clisp -M c:\clisp\lispinit.mem -i %s -x (main).
Then clicking on the compiled lisp file (with #P".fas" extension) will load the file (thus executing all the code in the file), while the clicking on a CLISP memory image (with #P".mem" extension) will start clisp with the given memory image.
Note that CLISP is distributed with a file install.bat, which creates a file clisp.bat on your desktop and also associates #P".fas", #P".lisp", and #P".mem" files with CLISP.
- Platform dependent: Linux platforms only.
You have to build your kernel with CONFIG_BINFMT_MISC=y and CONFIG_PROC_FS=y. Then you will have a /proc/sys/fs/binfmt_misc/ directory and you will be able to do (as root; you might want to put these lines into /etc/rc.d/rc.local):
bash# echo ":CLISP:E::fas::/usr/bin/clisp:" >> /proc/sys/fs/binfmt_misc/register bash# echo ":CLISP:E::lisp::/usr/bin/clisp:" >> /proc/sys/fs/binfmt_misc/register
Then you can do the following:
bash$ cat << EOF > hello.lisp (print "hello, world!") EOF bash$ clisp -c hello.lisp Compiling file hello.lisp ... Compilation of file hello.lisp is finished. 0 errors, 0 warnings bash$ chmod +x hello.fas bash$ hello.fas "hello, world!" bash$
Please read /usr/src/linux/Documentation/binfmt_misc.txt for details.
- Platform dependent: Amiga platforms only.
Using a Workbench project file, the memory images, source and binary files can be made "executable".
Using IconEdit, create a project icon.
Set the tool to lisp:lisp.run (or wherever the binary is located).
Define a tooltype named ARGS set to -M * for a memory image project icon or to -M lisp:lispinit.mem -i * for a source or compiled lisp file. The startup code will replace an isolated * token with the file name.
Alternatively, you may want to have a function main in your files and set the ARGS tooltype to -M lisp:lispinit.mem -i * -x (main).
You might want to add more command line options to the ARGS tooltype.
You might want to add a tooltype named WINDOW which names the console window that *TERMINAL-IO* will be bound to, for example CON:0/0/500/300/CLISP-Listener/AUTO/CLOSE, or TCP:20002.
Extensions-2.9. Application delivery with CLISP
Some ways of packaging CLISP programs are discussed in the section Quickstarting delivery with CLISP.
CLISP is Free Software, covered by the GNU GPL, with special terms governing the distribution of applications that run in CLISP. The precise terms can be found in the COPYRIGHT file contained in the source and binary distributions of CLISP. Here is an informal clarification what these terms mean in practice. Please refer to the said COPYRIGHT file when in doubt.
In many cases, CLISP does not force an application to be covered by the GNU GPL. Nevertheless, we encourage you to release your software under an open source copyright. The benefits of such a copyright for your users are numerous, in particular they are free to modify the application when their needs/requirements change, and they are free to recompile the application when they upgrade their machine or operating system.
CLISP extensions, i.e. programs which need to access non-portable CLISP internal symbols (in the packages "SYSTEM", "CLOS", "FFI", ...), must be covered by GNU GPL as well.
Other programs running in CLISP have to or need not to be placed under GNU GPL, depending on their distribution form:
Programs distributed as Lisp source or #P".fas" files can be distributed without restrictions coming from CLISP.
Programs distributed as CLISP memory images can be distributed only if accompanied with the non-CLISP #P".fas" files which make up the memory image, and a #P"Makefile" for rebuilding the memory image.
If you need to distribute a modified CLISP executable (for example, incorporating additional modules written in C), you must distribute its full source under GNU GPL. If you are not satisfied with this, you can instead put the additional modules into a separate (non-CLISP) program, with which your Lisp program will communicate via SOCKET:SOCKET-STREAMs.
Extensions-2.10. Shell, Pipes and Printing
Shell
- Platform dependent: UNIX, Acorn, DOS, OS/2, platforms only.
(EXT:EXECUTE program arg1 arg2 ...) executes an external program. Its name is program (a full pathname). It is given the strings arg1, arg2, ... as arguments.
- Platform dependent: Amiga platforms only.
(EXT:EXECUTE command) executes a given command using the operating system's shell.
- Platform dependent: UNIX, Amiga, Acorn, DOS, OS/2, Win32 platforms only.
(EXT:SHELL [command]) calls the operating system's shell. (EXT:SHELL) calls the shell for interactive use. (EXT:SHELL command) calls the shell only for execution of the one given command.
- Platform dependent: UNIX, OS/2, Win32 platforms only.
The functions EXT:RUN-SHELL-COMMAND and EXT:RUN-PROGRAM are the general interface to EXT:SHELL and the above:
(EXT:RUN-SHELL-COMMAND command &KEY :INPUT :OUTPUT :IF-OUTPUT-EXISTS :WAIT) runs a shell command (including shell built-in commands, like DIR on Win32/OS/2 and for/do/done on UNIX).
(EXT:RUN-PROGRAM program &KEY :ARGUMENTS :INPUT :OUTPUT :IF-OUTPUT-EXISTS :WAIT) runs an external program.
- command
the shell command.
- Platform dependent: UNIX platforms only.
The shell the command is passed to is the value of the environment variable SHELL, which normally is /bin/sh. The command should be a "simple command"; a "command list" should be enclosed in "{ ... ; }" (for /bin/sh) or "( ... )" (for /bin/csh).
- program
the program. The directories listed in the PATH environment variable will be searched for it.
- :ARGUMENTS
a list of arguments (strings) that are given to the program.
- :INPUT
where the program's input is to come from: either :TERMINAL (the standard input) or :STREAM (a Lisp stream to be created) or a pathname (an input file) or NIL (no input at all).
- :OUTPUT
where the program's output is to be sent to: either :TERMINAL (the standard output) or :STREAM (a Lisp stream to be created) or a pathname (an output file) or NIL (ignore the output).
- :IF-OUTPUT-EXISTS
what to do if the :OUTPUT file already exists. The possible values are :OVERWRITE, :APPEND, :ERROR, with the same meaning as for OPEN.
- :WAIT
wether to wait for program termination or not (this is useful when no i/o to the process is needed).
- :MAY-EXEC
pass exec to the underlying shell (UNIX only).
- :INDIRECTP
use a shell to run the command, e.g., (EXT:RUN-PROGRAM "dir" :indirectp T) will run the shell built-in command DIR. (Win32/OS/2 only).
If :STREAM was specified for :INPUT or :OUTPUT, a Lisp stream is returned. If :STREAM was specified for :INPUT and :OUTPUT, three Lisp streams are returned, as for the function EXT:MAKE-PIPE-IO-STREAM. This use of EXT:RUN-PROGRAM can cause deadlocks, see EXT:MAKE-PIPE-IO-STREAM.
Pipes
- Platform dependent: UNIX, OS/2, Win32 platforms only.
- (EXT:MAKE-PIPE-INPUT-STREAM command &KEY :ELEMENT-TYPE :EXTERNAL-FORMAT :BUFFERED)
returns an input stream that will supply the output from the execution of the given operating system command.
- (EXT:MAKE-PIPE-OUTPUT-STREAM command &KEY :ELEMENT-TYPE :EXTERNAL-FORMAT :BUFFERED)
returns an output stream that will pass its output as input to the execution of the given operating system command.
- (EXT:MAKE-PIPE-IO-STREAM command &KEY :ELEMENT-TYPE :EXTERNAL-FORMAT :BUFFERED)
returns three values. The first value is a bidirectional stream that will simultaneously pass its output as input to the execution of the given operating system command and supply the output from this command as input. The second and third value will be the input stream and the output stream that make up the I/O stream, respectively. Note that they must be closed individually.
Warning: Improper use of this function can lead to deadlocks. Use it at your own risk!
A deadlock occurs if the command and your program either both try to read from each other at the same time or both try to write to each other at the same time. To avoid deadlocks, it is recommended that you fix a protocol between the command and your program and avoid any hidden buffering: use READ-CHAR, READ-CHAR-NO-HANG, LISTEN instead of READ-LINE and READ on the input side, and complete every output operation by a FINISH-OUTPUT. The same cautions must apply to the called command as well.
Printing
The macro EXT:WITH-OUTPUT-TO-PRINTER:
(ext:with-output-to-printer (variable [:EXTERNAL-FORMAT]) {declaration}* {form}*) |
Extensions-2.11. Directory Access
When CLISP is configured with an option --with-dir-key, some directory access is available from lisp, in package "LDAP". 3 types of directory keys may exist, depending on the compilation environment.
valid directory key types
- :win32
Win32 registry access
- :gnome
gnome-config access
- :ldap
LDAP interface via OpenLDAP or compatible
The following functions and macros are exported (please note that these features are experimental and the API may be modified in the future).
- (LDAP:DIR-KEY-OPEN dkey pathname &KEY (:DIRECTION :INPUT) :IF-DOES-NOT-EXIST
Open the directory key under dkey, which should be either an open directory key or a valid directory key type. The meaning of the :DIRECTION and :IF-DOES-NOT-EXIST keyword arguments is the same as for OPEN.
- (LDAP:DIR-KEY-CLOSE dkey)
Close the directory key. The preferred way is to use the LDAP:WITH-DIR-KEY-OPEN macro.
- (LDAP:WITH-DIR-KEY-OPEN (variable dkey pathname &REST options) &BODY body)
Open the directory key (by calling LDAP:DIR-KEY-OPEN on dkey, pathname and options), bind it to variable, execute body, then close it with LDAP:DIR-KEY-CLOSE.
- (LDAP:DIR-KEY-TYPE dkey)
Return the directory key type of the directory key
- (LDAP:DIR-KEY-PATH dkey)
Return the path of this directory key, which is the pathname argument of LDAP:DIR-KEY-OPEN if dkey was a directory key type or the concatenation of the pathname argument and the ldap:dir-key-path of dkey.
- (LDAP:DIR-KEY-DIRECTION dkey)
One of :INPUT, :OUTPUT and :IO, indicating the permitted operation on this key and its derivatives.
- (LDAP:DIR-KEY-CLOSED-P dkey)
Check whether the key has been closed. It is not an error to close a closed key.
- (LDAP:DIR-KEY-SUBKEY-DELETE dkey subkey) (LDAP:DIR-KEY-VALUE-DELETE dkey attribute)
Delete the specified subkey or attribute.
- (LDAP:DIR-KEY-SUBKEY dkey) (LDAP:DIR-KEY-ATTRIBUTES dkey)
Return the list of the subkeys or attributes.
- (LDAP:DIR-KEY-VALUE dkey attribute &OPTIONAL default)
Return the value of the specified attribute, similar to GETHASH and SETFable just like GETHASH.
- (LDAP:DIR-KEY-INFO dkey)
Return some information about the directory key. This is highly platform-dependent and will probably be removed or replaced or modified in the future.
- (LDAP:WITH-DIR-KEY-SEARCH (key-iter atribute-iter dkey pathname &KEY :scope) &BODY body)
This is the main way to iterate over the subtree under the key dkey+pathname.
key-iter is a non-NIL symbol and is bound via MACROLET to a macro, each call of which returns the next subkey.
atribute-iter is a symbol and is bound, when non-NIL, to a macro, each call of which returns two values - the next attribute and its value.
The :scope keyword argument specifies the scope of the search and can be
- :self
iterate over the key itself
- :level
iterate over the children of the key
- :tree
iterate over the subtree
LDAP:WITH-DIR-KEY-SEARCH is used to implement LDAP:DIR-KEY-VALUES, LDAP:DIR-KEY-CHILDREN and LDAP:DIR-KEY-DUMP-TREE in dirkey.lisp.
Extensions-2.12. Other
- Platform dependent: Amiga platforms only.
To have *DEBUG-IO* and *ERROR-OUTPUT* point to separate console windows (thus keeping your standard console window clean from error messages) you can use
at startup.(SETQ *ERROR-OUTPUT* (SETQ *DEBUG-IO* (OPEN "CON:0/0/500/300/CLISP-Debugger/AUTO/CLOSE" :DIRECTION :IO)))
GNU Free Documentation License
Version 1.1, March 2000
Copyright (C) 2000 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
0. PREAMBLE
The purpose of this License is to make a manual, textbook, or other written document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.
This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.
We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.
1. APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you".
A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.
A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.
The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License.
The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License.
A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not "Transparent" is called "Opaque".
Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML produced by some word processors for output purposes only.
The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.
2. VERBATIM COPYING
You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and you may publicly display copies.
3. COPYING IN QUANTITY
If you publish printed copies of the Document numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.
If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.
4. MODIFICATIONS
You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:
Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has less than five).
State on the Title page the name of the publisher of the Modified Version, as the publisher.
Preserve all the copyright notices of the Document.
Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.
Include an unaltered copy of this License.
Preserve the section entitled "History", and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
In any section entitled "Acknowledgements" or "Dedications", preserve the section's title, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.
Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
Delete any section entitled "Endorsements". Such a section may not be included in the Modified Version.
Do not retitle any existing section as "Endorsements" or to conflict in title with any Invariant Section.
If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.
You may add a section entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.
You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.
5. COMBINING DOCUMENTS
You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice.
The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections entitled "History" in the various original documents, forming one section entitled "History"; likewise combine any sections entitled "Acknowledgements", and any sections entitled "Dedications". You must delete all sections entitled "Endorsements."
6. COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.
7. AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an "aggregate", and this License does not apply to the other self-contained works thus compiled with the Document, on account of their being thus compiled, if they are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate.
8. TRANSLATION
Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail.
9. TERMINATION
You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
10. FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.
How to use this License for your documents
To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:
Copyright (c) YEAR YOUR NAME. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. A copy of the license is included in the section entitled "GNU Free Documentation License".
If you have no Invariant Sections, write "with no Invariant Sections" instead of saying which ones are invariant. If you have no Front-Cover Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being LIST"; likewise for Back-Cover Texts.
If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.
References
Books
[CLtL1] Guy L. Steele, Jr., 1984, 465, 0-201-10088-6, Digital Press, Common Lisp: the Language (1st Edition).
[CLtL2] Guy L. Steele, Jr., 1990, 1032, 0-201-10088-6, Digital Press, Common Lisp: the Language (2nd Edition).
ANSI standard documents
[ANSI CL] 1994, ANSI Common Lisp standard X3.226-1994 - Information Technology - Programming Language - Common Lisp.
[CLHS] Common Lisp HyperSpec.