\documentstyle{report}
\pagestyle{plain}
\pagenumbering{roman}
\begin{document}
\title{ Kyoto Common Lisp Report}
\author{Taiichi Yuasa and Masami Hagiya\\ Research Institute for
Mathematical Sciences\\ Kyoto University}
\date{}
\maketitle
\newpage
\centerline{\LARGE Preface}
\vspace{.3in}
\noindent Kyoto Common Lisp (KCL for short) is a full implementation of the
Common Lisp language described in the Common Lisp Reference Manual:
\vspace{.2in}
\centerline{\it Common Lisp: The Language}
\centerline{ by Guy L. Steele et al.}
\centerline{ Digital Press, 1984}
\vspace{.2in}
\noindent All Common Lisp functions, macros, and special
forms are defined in KCL, though a few of them have slightly different
meanings from those described in the Common Lisp Reference Manual .
All such differences are described in this report: If a Common Lisp
function (or macro or special form) does not work as described in the
Common Lisp Reference Manual and if this report does not describe the
d
ifference explicitly, then there must be a bug in KCL. All Common
Lisp variables and constants are defined in KCL exactly as described
in the Common Lisp Reference Manual .
\vspace{.2in}
\noindent Currently, there are four major versions of KCL:
\begin{enumerate}
\item KCL/AOS, under the AOS/VS operating system for Data
General's ECLIPSE MV series machines.
\item KCL/VAX, under the Unix 4.2 bsd operating system for
Digital Equipment Corporation's VAX 11 series machines.
\item KCL/SUN, under the Unix 4.2 bsd operating system for Sun
Microsystems' Sun Workstation.
\item KCL/UST, under the Unix V (Uniplus' version) operating
system for Sumitomo Electric Industries and Digital Computer
Laboratory's Ustation E15.
\end{enumerate}
\vspace{.2in}
\noindent KCL/ AOS is the original version of KCL, which was developed at the
Research Institute for Mathematical Sciences (RIMS), Kyoto University,
with the cooperation of Nippon Data General Corporation. The other
three versions, which are collectively called {\it KCL on Unix}, are
transplanted versions of KCL/AOS.
\vspace{.2in}
\noindent This report is intended to complement the {\it Common Lisp Reference
Manual}. This report describes deviations of KCL from Common Lisp,
those features specific to KCL, and the implementation-dependent
functions of Common Lisp.
\newpage
\centerline{\LARGE Acknowledgements}
\vspace{.3in}
\noindent The project of KCL was supported by many people affiliated with many
institutions. We are very grateful especially to the following people
for their contributions to the KCL project.
\vspace{.2in}
First of all, we are grateful to the contributors to the design
of Common Lisp.
Prof. Reiji Nakajima at RIMS, Kyoto University, provided us with
considerable encouragement and moral support.
Nippon Data General Corporation (NDG) helped us implement KCL/AOS.
Mr. Teruo Yabe and Mr. Toshiyasu Harada joined us during the first
stage of the KCL project and did a lot of coding. Mr. Takashi Suzuki
and Mr. Kibo Kurokawa arranged the joint project. NDG is now
supporting the distribution of KCL/AOS.
Data General Corporation in the United States sent us materials
necessary to implement a Common Lisp system, such as the preliminary
drafts of the Common Lisp reference manual and benchmark tests for
Common Lisp. For the benchmark tests we are indebted to Dr. Richard
Gabriel at Stanford University.
Dr. Daniel Weinreb at Symbolics answered most of our questions about
the language specification. He also sent us the definition of
rationalize written by Dr. Skef Wholey at CMU.
We use this definition in KCL without any change.
Dr. Carl Hoffman at Symbolics checked the top-level of KCL and gave us
advice for improving KCL. He also found some bugs in KCL and fixed
them for us.
Mr. Naruhiko Kawamura at RIMS developed a Prolog system using the
earliest version of KCL/AOS. That was one of the first big projects
with KCL and he found many bugs.
Mr. Takashi Sakuragawa at RIMS hacked with KCL/AOS and gave us much
advice concerning those features specific to KCL.
Mr. Tatsuya Hagino at Edinburgh University developed Micro EMACS on
which FeCl2, the full-screen editor embedded in KCL/AOS, is based.
Mr. Kunihiko Nakamura at Kagawa University converted the assembly
language version of Micro EMACS into the C language, which happened to
become the prototype of FeCl2.
Prof. Akinori Yonezawa at Tokyo Institute of Technology encouraged us
to port KCL/AOS to the VAX 11.
Mr. Etsuya Shibayama at Tokyo Institute of Technology helped us
while we were working with the VAX 11 at the Institute.
Hagiwara Laboratory at Kyoto University offered (and is offering)
their VAX 11 for finishing transplantation and maintaining KCL/VAX.
We got also technical advice from people at Hagiwara Laboratory.
Prof. Shuji Doshita at Kyoto University offered the SUN Workstation at
his Laboratory and gave us a lot of advice for transplantation to the
SUN Workstation.
Mr. Takashi Hattori at RIMS gave us useful information about the
Motorola 68000, the CPU chip of SUN Workstation.
\newpage
\tableofcontents
\chapter{How to Start and End a KCL Session}
\pagenumbering{arabic}
KCL on Unix is invoked by the Shell command {\tt kcl}.\hfill\break
\begin{verbatim}
% kcl
KCL (Kyoto Common Lisp) July 1, 1985
\end{verbatim}
\centerline{------------Note to KCL/AOS users------------}
\vspace{.1in}
KCL/AOS is invoked by the CLI command {\tt KCL.\hfill\break
\vspace{.1in}
\hspace*{1in}{}) KCL\hfill\break
\hspace*{1in}{}KCL (Kyoto Common Lisp) July 1, 1985}\hfill\break
\vspace{.1in}
\centerline{---------------End of Note---------------}
\vspace{.2in}
\noindent When invoked, KCL will print the banner and initialize the system.
The date in the KCL banner identifies the revision of KCL.
{\tt ``July 1, 1985''} is the value of the
function {\tt lisp-implementation-version}.
\medskip
\noindent If there exists a file named {\tt init.lsp} in the current working
directory, KCL successively evaluates the forms in the file,
immediately after the system initialization. The user may set up his
or her own KCL environment (e.g., the memory configuration) with
{\tt init.lsp}.
\medskip
\noindent After the initialization, KCL enters the {\it top-level loop} and
prints the prompt `$>$'.
\begin{verbatim}
>
\end{verbatim}
\noindent The prompt indicates that KCL is now ready to receive a form
from the terminal and to evaluate it.
\noindent Usually, the current package (i.e., the value of {\tt
*package*}) is the user package, and the prompt appears as above. If,
however, the current package is other than the user package, then the
prompt will be prefixed by the package name.\hfill\break
\vspace*{.1in}
\hspace*{.8in}{}{\it package-name$>$}\hfill\break
\vspace*{.1in}
\noindent To exit from KCL, call the function {\tt bye} (or {\tt by}).\hfill\break
\begin{verbatim}
>(bye)
Bye.
%
\end{verbatim}
\centerline{------------Note to KCL/AOS users------------}
\vspace{.1in}
\noindent In this report, we sometimes assume that KCL is invoked from
the Unix Shell. In particular, we use the standard prompt of the Unix
Shell {\tt `\%'} in most examples.
\vspace{.1in}
\centerline{---------------End of Note---------------}
\vspace{.1in}
\noindent Alternatively, you may type {\tt \^{}D} (control-D), i.e.,
press the key D while pressing down the control key.\hfill\break
\begin{verbatim}
>^Dbye.
%
\end{verbatim}
\noindent The top-level loop of KCL is almost the same as that defined
in Section 20.2 of the {\it Common Lisp Reference Manual}. Since the
input from the terminal is in line mode, each top-level form should be
followed by a newline. If more than one value is returned by the
evaluation of the top-level form, the values will be printed
successively. If no value is returned, then nothing will be
printed.\hfill\break
\vspace{.1in}
\begin{verbatim}
>(values 1 2)
1
2
>(values)
>
\end{verbatim}
\vspace{.1in}
\noindent When an error is signalled, control will enter the break loop.
\begin{verbatim}
>(defun foo (x) (bar x))
foo
>(defun bar (y) (bee y y))
bar
>(foo 'lish)
Error: The function BEE is undefined.
Error signalled by BAR.
Broken at BAR.
>>
\end{verbatim}
\vspace{.1in}
\noindent {\tt `$>>$'} in the last line is the prompt of the break loop.
Like in the top-level loop, the prompt will be prefixed by the current
package name, if the current package is other than the {\tt user}
package.
\medskip
\noindent To go back to the top-level loop, type {\tt :q}
\vspace{.1in}
\begin{verbatim}
>>:q
Top level.
>
\end{verbatim}
\vspace{.1in}
\noindent See Section 5.4 for the details of the break loop.\hfill\break
\medskip
\noindent In KCL on Unix, the terminal interrupt (usually caused by typing
{\tt \^{}C} (control-C) or by typing {\tt DELETE}) is a kind of error.
It breaks the running program and calls the break level loop.
\vspace{.1in}
Example:\hfill\break
\begin{verbatim}
>(defun foo () (do () (nil)))
foo
>(foo)
^C
Correctable error: Console interrupt.
Signalled by DO.
Broken at FOO.
>>
\end{verbatim}
\vspace{.1in}
\centerline{------------Note to KCL/AOS users------------}
\vspace{.1in}
\noindent In KCL/AOS, the console interrupt caused by typing {\tt \^{}C}
(control-C) followed by {\tt \^{}A} (control-A) is a kind of error.
Typing {\tt ctrlC} and {\tt \^{}A} breaks the running program and calls
the break loop. On the other hand, the console interrupt caused by
{\tt \^{}C} and {\tt \^{}B} (control-B) will immediately terminate KCL.
\vspace{.1in}
Example:
\vspace{.1in}
\begin{verbatim}
>(defun foo () (do () (nil)))
foo
>(foo)
^C^A
Correctable error: Console interrupt.
Signalled by DO.
Broken at FOO.
>>(foo)
^C^B
*ABORT*
CONSOLE INTERRUPT
ERROR: FROM PROGRAM
LEVEL 1
x,kcl
)
\end{verbatim}
\vspace{.1in}
\centerline{---------------End of Note---------------}
\chapter{Data Types}
KCL supports all Common Lisp data types exactly as defined
in the {\it Common Lisp Reference Manual}. This chapter simply
complements Chapter 2 of the {\it Common Lisp Reference Manual}, by
describing implementation dependent features of Common Lisp data
types. Each section in this chapter corresponds to the section in
Chapter 2 of the {\it Common Lisp Reference Manual}, with the same
section title.
\section{Numbers}
\subsection{Integers}
\noindent {\tt Fixnums} in KCL are those integers in the range -(2 to the power of 31)
to (2 to the power of 31)-1, inclusive. Other integers are {\tt bignums}.
Thus 25 factorial (25!)
\begin{verbatim}
15511210043330985984000000
\end{verbatim}
\noindent is certainly a bignum in KCL.\hfill\break
\medskip
\noindent Common Lisp constants related to integers have the following values
in KCL.
\begin{verbatim}
most-positive-fixnum = 2147483647 = (2 to the power of 31)-1
most-negative-fixnum = -2147483648 = - (2 to the power of 31)
boole-1 = 3
boole-2 = 5
boole-and = 1
boole-andc1 = 4
boole-andc2 = 2
boole-c1 = 12
boole-c2 = 10
boole-clr = 0
boole-eqv = 9
boole-ior = 7
boole-nand = 14
boole-nor = 8
boole-orc1 = 13
boole-orc2 = 11
boole-set = 15
boole-xor = 6
\end{verbatim}
\noindent See Chapter 12 of the {\it Common Lisp Reference Manual} for their
meanings.
\subsection{Ratios}
\noindent There are no implementation-dependent features for ratios.
\subsection{Floating-Point Numbers}
\noindent KCL provides two distinct internal floating-point formats. One format
is {\it short}; the other is {\it single} and serves also as {\it
double} and {\it long}. The data types {\tt single-float} , {\tt
double-float }, and {\tt long-float} are considered to be identical,
but {\tt short-float } is distinct. An expression such as {\tt (eql
1.0s0 1.0d0)} is false, but {\tt (eql 1.0f0 1.0d0)} is true. Similarly,
{\tt (typep 1.0L0 'short-float)} is false, but {\tt (typep 1.0L0
'single-float}) is true. For output purposes all floating-point
numbers are assumed to be of {\it short} or {\it single} format.
\vspace{.1in}
\noindent The floating-point precisions are:
\begin{verbatim}
Format KCL/AOS KCL/VAX KCL/SUN KCL/UST
------------------------------------------------------
Short 24 bits 23 bits 24 bits 24 bits
Single 56 bits 55 bits 53 bits 53 bits
Double 56 bits 55 bits 53bits 53 bits
Long 56 bits 55 bits 53 bits 53 bits
\end{verbatim}
\noindent The floating-point exponent sizes are:\hfill\break
\begin{verbatim}
Format KCL/AOS KCL/VAX KCL/SUN KCL/UST
------------------------------------------------------
Short 7 bits 8 bits 8 bits 8 bits
Single 7 bits 8 bits 11 bits 11 bits
Double 7 bits 8 bits 11 bits 11 bits
Long 7 bits 8 bits 11 bits 11 bits
\end{verbatim}
\noindent There is no ``minus zero.'' {\tt (eql 0.0 -0.0)} is true.\hfill\break
\medskip
\noindent Common Lisp constants related to floating-point numbers have the
following values in KCL.
\begin{verbatim}
most-positive-short-float
= - most-negative-short-float
= 7.237005s75 (KCL/AOS)
1.701412s38 (KCL/VAX)
3.402823s38 (KCL/SUN and KCL/UST)
least-positive-short-float
= - least-negative-short-float
= 5.397605s-79 (KCL/AOS)
2.938736s-39 (KCL/VAX)
1.401298s-45 (KCL/SUN and KCL/UST)
most-positive-long-float
= most-positive-double-float
= most-positive-single-float
= - most-negative-long-float
= - most-negative-double-float
= - most-negative-single-float
= 7.237005577332264f75 (KCL/AOS)
1.701411834604692f38 (KCL/VAX)
1.797693134862315f308 (KCL/SUN and KCL/UST)
least-positive-long-float
= least-positive-double-float
= least-positive-single-float
= - least-negative-long-float
= - least-negative-double-float
= - least-negative-single-float
= 5.397605346934027f-79 (KCL/AOS)
2.938735877055719f-39 (KCL/VAX)
4.940656458412469f-324 (KCL/SUN and KCL/UST)
short-float-epsilon
= 4.468372s-7 (KCL/AOS)
6.938894s-18 (KCL/VAX)
2.980232s-8 (KCL/SUN and KCL/UST)
short-float-negative-epsilon
= 2.980232s-8 (KCL/AOS)
6.938894s-18 (KCL/VAX)
2.980232s-8 (KCL/SUN and KCL/UST)
long-float-epsilon
= double-float-epsilon
= single-float-epsilon
= 1.110223024625157f-16 (KCL/AOS)
6.938893903907228f-18 (KCL/VAX)
5.5511151231257827f-17 (KCL/SUN and KCL/UST)
long-float-negative-epsilon
= double-float-negative-epsilon
= single-float-negative-epsilon
= 6.938893903907228f-18 (KCL/AOS)
6.938893903907228f-18 (KCL/VAX)
5.5511151231257827f-17 (KCL/SUN and KCL/UST)
pi = 3.141592653589793
\end{verbatim}
\noindent See Chapter 12 of the {\it Common Lisp Reference Manual} for their
meanings.
\subsection{Complex Numbers}
\noindent There are no implementation-dependent features for complex numbers.
\section{Characters}
\subsection{Standard Characters}
\noindent KCL supports all standard and semi-standard characters listed in
Section 2.2.1 of the {\it Common Lisp Reference Manual} .
Non-printing characters have the following character codes.
\begin{verbatim}
Character Code (in octal)
--------------------------------
#\Space 040
#\Newline 012
#\Backspace 010
#\Tab 011
#\Linefeed 012
#\Page 014
#\Return 015
#\Rubout 177
\end{verbatim}
\noindent Note that {\tt \#$\backslash$Linefeed} is synonymous with
{\tt \#$\backslash$Newline} and thus is a member of
{\tt standard-char}. Other semi-standard characters are not members
of {\tt standard-char}.
\vspace{.1in}
\centerline{------------ Note to KCL/AOS users------------}\hfill\break
KCL/AOS uses 025 (in octal) as the character code of
{\tt \#$\backslash$Backspace}.
\vspace{.1in}
\centerline{--------------- End of Note ---------------}\hfill\break
\subsection{Line Divisions}
\noindent Since KCL represents the {\tt \#$\backslash$Newline} character by a single
code 12 , problems with line divisions discussed in Section 2.2.2
of the {\it Common Lisp Reference Manual} cause no problem in KCL.
\subsection{Non-standard Characters}
\noindent KCL supports no additional non-standard characters.
\subsection{Character Attributes}
\noindent The bit and font fields of KCL characters are always 0 .\hfill\break
\vspace{.1in}
\noindent Common Lisp constants related to characters have the following values
in KCL.
\begin{verbatim}
char-bits-limit = 1
char-code-limit = 256
char-control-bit = 0
char-font-limit = 1
char-hyper-bit = 0
char-meta-bit = 0
char-super-bit = 0
\end{verbatim}
\noindent See Chapter 13 of the {\it Common Lisp Reference Manual} for their
meanings.
\subsection{String Characters}
\noindent Since the bit and font fields of KCL characters are always 0 ,
{\tt string-char} is considered to be identical to {\tt character}.
\section{Symbols}
\noindent The print name of a symbol may consist of up to 16777216 (i.e., the value
of {\tt array-total-size-limit}) characters. However, when a symbol is
read, the number of characters (not counting escape characters)
in the print name is limited to 2048.
\section{Lists and Conses}
\noindent There are no implementation-dependent features for lists and conses.
\section{Arrays}
\noindent KCL arrays can have up to 64 ranks.\hfill\break
\medskip
\noindent When the value of the Common Lisp variable {\tt
$\ast$print-array$\ast$} (see Section 22.1.6 of the {\it Common Lisp
Reference Manual} ) is {\tt nil}, then bit-vectors are printed as
{\tt \#}, other vectors are printed as {\tt \#},
and other arrays are printed as {\tt \#}.
\medskip
\noindent Common Lisp constants related to arrays have the following values in
KCL.
\begin{verbatim}
array-dimension-limit = 16777216
array-rank-limit = 64
array-total-size-limit = 16777216
\end{verbatim}
\noindent See Section 17.1 of the {\it Common Lisp Reference Manual} for
their meanings.
\subsection{Vectors}
\noindent In KCL, array elements are represented in one of six ways depending
on the type of the {\tt array}.
\begin{verbatim}
Array Type Element Representation
---------------------------------------------------------------
(array t) and (vector t) a cell pointer
(array fixnum) and (vector fixnum) 32 bit signed integer
(array string-char) and string 8 bit code
(array short-float) and (vector short-float) 32 bit floating point
(array long-float) and (vector long-float) 64 bit floating point
(array bit) and bit-vector 1 bit bit
\end{verbatim}
\subsection{Strings}
\noindent A string may consists of up to 16777216 (i.e., the value of
{\tt array-total-size-limit}) characters. However, when a string is
read, the number of characters (not counting escape characters) in the
string is limited to 2048.
\subsection{Bit-Vectors}
\noindent There are no implementation-dependent features for bit-vectors.
\section{Hash Tables}
\noindent All hash tables are printed as {\tt \#}.
\section{Readtables}
\noindent All readtables are printed as {\tt \#}.
\section{Packages}
\noindent The following packages are built into KCL.
\begin{verbatim}
lisp user keyword system compiler
\end{verbatim}
\noindent The {\tt compiler} package contains symbols used by the KCL compiler.
Other packages are described in Section 11.6 of the {\it Common Lisp
Reference Manual}. The {\tt system} package has two nicknames {\tt sys}
and {\tt si} ; {\tt system: symbol} may be written as {\tt sys: symbol}
or {\tt si: symbol}. Other packages have no nicknames.
\medskip
\noindent Packages are printed as {\tt \#<{\it package-name} package>}.
\section{Pathnames}
\noindent KCL provides a {\tt \#} macro {\tt \#"} that reads a
pathname: {\tt \#"{\it string}"} is equivalent
to ( a{\tt pathname "{\it string}"}) . For example,
\begin{verbatim}
#"foo.lsp"
\end{verbatim}
\noindent is equivalent to
\begin{verbatim}
(pathname "foo.lsp").
\end{verbatim}
\noindent The same format is used when a pathname is printed.
\medskip
\noindent The initial value of the Common Lisp variable {\tt
\*default-pathname-defaults\*} is {\tt \#""} (or, equivalently, {\tt (pathname "")} ).
\medskip
\noindent A pathname in the file system of Common Lisp consists of the following
six elements:
\begin{verbatim}
host device directory name type version
\end{verbatim}
\noindent Among these elements, KCL does not use {\tt host, device}, and {\tt version}.
That is, when converting a namestring into a pathname, KCL turns these
three elements into {\tt nil}. Conversely, when converting a pathname into
a namestring, KCL ignores these three elements.
\medskip
\noindent In the sequel, we explain how KCL converts a namestring into
a pathname.
\medskip
\noindent If a namestring contains one or more periods `.', the last period
separates the namestring into the file name and the filetype.
\begin{verbatim}
"foo.lsp"
name: "foo"
type: "lsp"
"a.b.c"
name: "a.b"
type: "c"
\end{verbatim}
\noindent If a namestring ends with a period, the filetype becomes the null
string.
\begin{verbatim}
"foo."
name: "foo"
type: "" (null string)
\end{verbatim}
\noindent If a namestring begins with a period, the file name becomes {\tt nil} .
\begin{verbatim}
".lsp"
name: nil
type: "lsp"
\end{verbatim}
\noindent If a namestring contains no period, the filetype is {\tt nil} .
\begin{verbatim}
"foo"
name: "foo"
type: nil
\end{verbatim}
\noindent In a pathname, the file directory is represented as a list.
\begin{verbatim}
"common/demo/foo.lsp"
directory: ("common" "demo")
name: "foo"
type: "lsp"
\end{verbatim}
\noindent If a namestring does not contain a directory, the directory component
of the pathname is {\tt nil} .
\begin{verbatim}
"foo.lsp"
directory: nil
name: "foo"
type: "lsp"
\end{verbatim}
\noindent In a pathname, the root directory is represented by the keyword
{\tt :root}.
\begin{verbatim}
"/usr/common/foo.lsp"
directory: (:root "usr" "common")
name: "foo"
type: "lsp"
\end{verbatim}
\noindent The abbreviation symbols ` . ' and ` .. ' may be used in a namestring.
\begin{verbatim}
"./demo/queen.lsp"
directory: (:current\(ri ':current) "demo")
name: "queen"
type: "lsp"
"../../demo/queen.lsp"
directory: (:parent\(ri ':parent) :parent "demo")
name: "queen"
type: "lsp"
\end{verbatim}
\noindent {\tt :current} and {\tt :parent} represent the current directory and
the parent directory, respectively.
\medskip
\noindent The part of a namestring after the last slash `{\tt /}' is always regarded
as representing the file name and the filetype. In order to represent
a pathname with both the name and the filetype {\tt nil}, end the pathname
with a slash.
\begin{verbatim}
"/usr/common/"
directory: (:root "usr" "common")
name: nil
type: nil
"/usr/common/.lsp"
directory: (:root "usr" "common")
name: nil
type: "lsp"
\end{verbatim}
\noindent ` $\ast$ ' in the place of file name or filetype becomes {\tt :wild}
\begin{verbatim}
"*.lsp"
name: :wild
type: "lsp"
"foo.*"
name: "foo"
type: :wild
\end{verbatim}
\centerline{---------- Note to KCL/AOS users ------------}\hfill\break
\noindent In KCL/AOS, all the lower-case letters are turned into
upper-case letters by pathname conversions. Thus, for example,
\begin{verbatim}
"foo.lsp"
name: "FOO"
type: "LSP"
\end{verbatim}
\noindent KCL/AOS follows the convention of the AOS/VS file system: The symbols
`{\tt /} ', ` . ', ` .. ', and ` $\ast$ ' in the examples above should be
replaced by ` : ', ` {\tt =} ', ` \^{}', and ` - ', respectively, in
KCL/AOS.
\vspace{.1in}
\centerline{--------------- End of Note ---------------}
\vspace{.1in}
\section{Streams}
\noindent Streams are printed in the following formats.
\vspace{.1in}
\noindent {\tt \# }\hfill\break
\indent An input stream from the file {\it file-name} .\hfill\break
\noindent {\tt \#