\begindata{text,539466424}
\textdsversion{12}
\template{help}
\define{global
}
\define{index
menu:[Title~3,Index~91]
attr:[FontFace Italic Int Set]}
\define{indexi
menu:[Title~3,InvisibleIndex~92]
attr:[Script PreviousScriptMovement Point -2]
attr:[FontFace Italic Int Set]}
\define{text
}
\chapter{1 Lisp Primitives in ELI, the Embedded Lisp Interpreter
}
\section{1.1
Introduction
}This document gives a brief description of the data types in ELI, the
Embedded Lisp Interpreter, and full documentation for the primitives and
library functions available in ELI. ELI is the Lisp library on which
both
BGLisp and FLAMES are constructed, hence these primitives, library
functions
and data types are available in both. ELI implements an extended subset
of
Common Lisp.
\section{1.2
Data Types
}ELI supports long integers, strings, symbols and lists. Note that,
unlike
XLisp or Common Lisp, it does not provide for ratios, floating-point
numbers,
arrays or characters (among other types).
\subsection{1.2.1 Integers
}An ELI integer is stored as a C "long int".
\subsection{1.2.2 Strings
}An ELI string is entered and displayed as a C string constant. That is,
one
encloses a string in double-quotes, and ELI recognizes all of C's
backslash
escaping conventions: \\n means newline, \\t means tab, and so on.
\subsection{1.2.3 Symbols
}ELI symbols have separate value and function fields. The syntax of a
symbol
name is like the syntax of a Common Lisp symbol name. Among the
exceptions to
this rule is the fact that a period "." is a valid symbol-name character
(see
note on dotted pairs in Lists).
\subsection{1.2.4 Lists
}ELI lists are straightforward, standard Lisp lists: arbitrarily long,
with
each item in the list being any one of these four data types. Unlike
Common
Lisp, there are no dotted pairs in ELI, and as you will see, no
destructive
list operations.
\section{1.3
Library Functions
}There is a standard library of ELI functions in the file
/usr/andrew/lib/eli/elilib.eli. To load the functions in this file,
simply
type (load "elilib") while in BGLisp. The elilib library itself loads
four
sub-libraries: strings.eli, lists.eli, ints.eli and misc.eli.
\text{\section{1.4
About This Document}
This document contains user and programmer information about programming
in
Flames, as well as a reference list of Flames primitives and library
functions. This document will \bold{not} teach you how to program in
Lisp.
If you are unfamiliar with Lisp, you should find a book designed to
teach
Lisp and learn from it.
If you are using EZ to read this document, you can open an interactive
Table
of Contents window by choosing \bold{Table of Contents} from the
\italic{Page}
menu card. Clicking on a heading in the Table of Contents window that
appears
scrolls this document to bring the heading into view.
Throughout this document, \italic{italics} indicate a parameter to a
function,
and \typewriter{typewriter} indicates a Lisp expression.
Each primitive or library function is listed by name in alphabetical
order
within its section. The description of each function has several
subsections,
as follows:
\text{______________________________________________________
\italic{1.2.0.1
FunctionName}
______________________________________________}}\text{________
\typewriter{(sample call of this function from ELI)}
\bold{Parameters}
\leftindent{Description of this function's argument(s). }
\bold{Description}
\leftindent{A description of the function, as well as various facts
related to
this function that are helpful to know.
}
\bold{Return Value}
\leftindent{Summary of the types or values the function returns.
}
\bold{Defined In
}\leftindent{In which library the function is defined, or an indication
that
this function is an ELI primitive.
}
\bold{Known Bugs}
\leftindent{What are the known bugs?
bugs?}
What is the status of the known
\bold{See Also}
\leftindent{A list of related ELI or operating system functions, as well
as
documents that may be useful.}
\bold{Example}
\leftindent{A (usually) simple, practical example of this function, with
commentary.}
}
\begindata{bp,539691272}
\enddata{bp,539691272}
\view{bpv,539691272,1745,0,0}
\section{1.5
Integer Manipulation
}
______________________________________________________
\paragraph{\index{1.5.0.1
<}
}______________________________________________________
\typewriter{(< \italic{x y})
}
\bold{Parameters}
\leftindent{\italic{X} and \italic{y} must evaluate to integers.
}
\bold{Description}
\leftindent{Returns \typewriter{T} if and only if \italic{x} is less than
\italic{y}.}
\leftindent{
}\bold{Defined In
}\leftindent{ints.eli
}
\bold{Example}
\leftindent{\typewriter{(< 3 12)} returns \typewriter{T}, \typewriter{(<
-1
-2)} returns \typewriter{NIL}, \typewriter{(< 0 0)} returns
\typewriter{NIL}.}
______________________________________________________
\paragraph{\index{1.5.0.2
>}
}______________________________________________________
\typewriter{(> \italic{x y})
}
\bold{Parameters}
\leftindent{\italic{X} and \italic{y} must evaluate to integers.
}
\bold{Description}
\leftindent{Returns \typewriter{T} if and only if \italic{x} is greater
than
\italic{y}.}
\leftindent{
}\bold{Defined In
}\leftindent{ints.eli
}
\bold{Example}
\leftindent{\typewriter{(}}\typewriter{<}\leftindent{\typewriter{ 3 12)}
returns \typewriter{NIL}, \typewriter{(< -1 -2)} returns \typewriter{T},
\typewriter{(< 0 0)} returns \typewriter{NIL}.}
______________________________________________________
\paragraph{\index{1.5.0.3
BIT-AND}
}______________________________________________________
\typewriter{(bit-and \italic{x y})
}
\bold{Parameters}
\leftindent{\italic{X} and \italic{y} must evaluate to positive integers.
}
\bold{Description}
\leftindent{Returns the result of the bitwise and of \italic{x} and
\italic{y}.}
\leftindent{
}\bold{Defined In
}\leftindent{ints.eli
}
\bold{Example}
\leftindent{\typewriter{ (bit-and 10 6)} returns \typewriter{2}.}
______________________________________________________
\paragraph{\index{1.5.0.4
DIV}
}______________________________________________________
\typewriter{(div \italic{n1 n2})
}
\bold{Parameters}
\leftindent{\italic{N1} and \italic{n2} must evaluate to integers.
\bold{Description}
\leftindent{Performs integer division, returning \italic{n1} /
\italic{n2}.
It is an error for \italic{n2} to be zero.}
\leftindent{
}\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{Example}
}
\leftindent{\typewriter{(div 5 2)} returns \typewriter{2}.}
______________________________________________________
\paragraph{\index{1.5.0.5
INT-TO-STR}
}______________________________________________________
\typewriter{(int-to-str \italic{n})
}
\bold{Parameters}
\leftindent{\italic{N} must evaluate to an integer.
}
\bold{Description}
\leftindent{Returns a string containing the ASCII representation of
\italic{n}
in base 10.}
\leftindent{
}\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{Example}
\leftindent{\typewriter{(int-to-str 200)} returns \typewriter{"200"}.}
______________________________________________________
\paragraph{\index{1.5.0.6
LESSP}
}______________________________________________________
\typewriter{(lessp \italic{a b})
}
\bold{Parameters}
\leftindent{\italic{A} and \italic{b} must evaluate to integers.
}
\bold{Description}
\leftindent{Returns \typewriter{T} if \italic{a} is numerically less than
\italic{b,} otherwise returns \typewriter{NIL}.}
\bold{Defined In
}\leftindent{ELI primitive.
}
______________________________________________________
\paragraph{\index{1.5.0.7
MINUS and -}
}______________________________________________________
\typewriter{(minus \italic{a b})
(- \italic{a b})
}
\bold{Parameters}
\leftindent{\italic{A} and \italic{b} must evaluate to integers.
\italic{B}
may be omitted; }
\bold{Description}
\leftindent{if \italic{B} is omitted, returns \italic{-a,} otherwise
returns
\italic{a} - \italic{b.} }
\bold{Defined In
}\leftindent{ELI primitive.
}
______________________________________________________
\paragraph{\index{1.5.0.8
MOD}
}______________________________________________________
\typewriter{(mod \italic{x y})
}
\bold{Parameters}
\leftindent{\italic{X} and \italic{y} must evaluate to integers. }
\bold{Description}
\leftindent{Returns the remainder from the integer division of \italic{y}
into
\italic{x}.}
\leftindent{
}\bold{Defined In
}\leftindent{ints.eli
}
\bold{Example}
\leftindent{\typewriter{(mod 7 4)} returns \typewriter{3}.}
______________________________________________________
\paragraph{\index{1.5.0.9
NUMBERP}
}______________________________________________________
\typewriter{(numberp \italic{e})
}
\bold{Parameters}
\leftindent{\italic{E} may evaluate to any expression.
}
\bold{Description}
\leftindent{If \italic{e} is an integer, returns \typewriter{T},
otherwise
returns \typewriter{NIL}.}
\bold{Defined In
}\leftindent{ELI primitive.
}
______________________________________________________
\paragraph{\index{1.5.0.10
PLUS and +}
}______________________________________________________
\typewriter{(plus \italic{m1 m2 ... mn})
(+ \italic{m1 m2 ... mn})
}
\bold{Parameters}
\leftindent{\italic{M1} through \italic{mn} must evaluate to integers.
}
\bold{Description}
\leftindent{Returns the result of adding \italic{m1} through \italic{mn.}
\italic{N} may be 1.}
\bold{Defined In
}\leftindent{ELI primitive.
}
______________________________________________________
\paragraph{\index{1.5.0.11
TIMES and *}
}______________________________________________________
\typewriter{(times \italic{m1 m2 ... mn})
(* \italic{m1 m2 ... mn})
}
\bold{Parameters}
\leftindent{\italic{M1} through \italic{mn} must evaluate to integers.
}
\bold{Description}
\leftindent{Returns the result of multiplying \italic{m1} through
\italic{mn.}
\italic{N} may be one, in which case it returns \italic{m1.} }
\bold{Defined In
}\leftindent{ELI primitive.
}
______________________________________________________
\paragraph{\index{1.5.0.12
ZEROP}
}______________________________________________________
\typewriter{(zerop \italic{x})
}
\bold{Parameters}
\leftindent{\italic{X} must evaluate to an integer. }
\bold{Description}
\leftindent{Returns \typewriter{T} if \italic{x} is zero,
\typewriter{NIL}
otherwise.}
\leftindent{
}\bold{Defined In
}\leftindent{ints.eli
}
\bold{Example}
\leftindent{\typewriter{ (zerop 0)} returns \typewriter{T},
\typewriter{(zerop
1)} returns \typewriter{NIL}.}
\begindata{bp,539691208}
\enddata{bp,539691208}
\view{bpv,539691208,1746,0,0}
\section{1.6
String Manipulation
}
______________________________________________________
\paragraph{\index{1.6.0.1
A-PAT-IN-ANY-STR}
}______________________________________________________
\typewriter{(a-pat-in-any-str \italic{pat strs})
}
\bold{Parameters}
\leftindent{\italic{Pat} must evaluate to a string, \italic{strs} must
evaluate to a list of strings. }
\bold{Description}
\leftindent{Returns \typewriter{T} if the regular expression in
\italic{pat}
is found in any string in \italic{strs,} otherwise returns
\typewriter{NIL}.
Alphabetic case is significant during pattern-matching.}
\bold{Defined In
}\leftindent{strings.eli
}
______________________________________________________
\paragraph{\index{1.6.0.2
ANY-PAT-IN-ANY-STR}
}______________________________________________________
\typewriter{(any-pat-in-any-str \italic{pats strs})
}
\bold{Parameters}
\leftindent{\italic{Pat} and \italic{strs} must evaluate to lists of
strings.
}
\bold{Description}
\leftindent{Returns \typewriter{T} if any regular expression in the
strings in
\italic{pat} is found in any of the strings in \italic{strs,} otherwise
returns \typewriter{NIL}. Alphabetic case is significant during
pattern-matching.}
\bold{Defined In
}\leftindent{strings.eli
}
______________________________________________________
\paragraph{\index{1.6.0.3
A-STR-IN-ANY-STR}
}______________________________________________________
\typewriter{(a-str-in-any-str \italic{str strs ignoreCase})
}
\bold{Parameters}
\leftindent{\italic{Str} is a string and \italic{strs} is a list of
strings.
The optional third argument, if non-\typewriter{NIL}, causes alphabetic
case
to be ignored during matching. }
\bold{Description}
\leftindent{Returns \typewriter{T} if \italic{str} is contained within
any
string in \italic{strs,} otherwise returns \typewriter{NIL}.}
\bold{Defined In
}\leftindent{strings.eli
}
______________________________________________________
\paragraph{\index{1.6.0.4
ANY-STR-IN-ANY-STR}
}______________________________________________________
\typewriter{(any-str-in-any-str \italic{strs1 strs2 ignoreCase})
}
\bold{Parameters}
\leftindent{\italic{Strs1} and \italic{strs2} are lists of strings. The
optional third argument, if non-\typewriter{NIL}, causes alphabetic case
to be
ignored during matching. }
\bold{Description}
\leftindent{Returns \typewriter{T} if any string in \italic{strs1} is
contained in any string in \italic{strs2,} otherwise returns
\typewriter{NIL}.}
\bold{Defined In
}\leftindent{strings.eli
}
______________________________________________________
\paragraph{\index{1.6.0.5
INDEX}
}______________________________________________________
\typewriter{(index \italic{str char})
}
\bold{Parameters}
\leftindent{\italic{Str} and \italic{char} must evaluate to strings.
(\italic{Char} should be a one-character string.) }
\bold{Description}
\leftindent{Searches for (the first character of) \italic{char} in
\italic{str,} returning that sub-part of \italic{str} which starts with
\italic{char.} Searches from left to right, so that if \italic{str}
contains
more than one of \italic{char,} the return value will start from the
first
occurrence of \italic{char} in \italic{str.} (See RINDEX for a similar
function which searches from right to left.) If \italic{char} is not
found in
\italic{str,} \typewriter{NIL} is returned.}
\leftindent{
}\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{Example}
\leftindent{\typewriter{(index "Hawaii" "a")} returns
\typewriter{"awaii"}.}
______________________________________________________
\paragraph{\index{1.6.0.6
LCSTRING}
}______________________________________________________
\typewriter{(lcstring \italic{s})
}
\bold{Parameters}
\leftindent{\italic{S} must evaluate to a string.
}
\bold{Description}
\leftindent{Returns the string \italic{s} with all capital letters
replaced by
lower-case ones.}
\leftindent{
}\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{Example}
\leftindent{\typewriter{(lcstring "Bob Glickstein")} returns
\typewriter{"bob
glickstein"}.}
______________________________________________________
\paragraph{\index{1.6.0.7
RE-STRCONTAINS}
}______________________________________________________
\typewriter{(re-strcontains \italic{pat ref})
}
\bold{Parameters}
\leftindent{\italic{Pat} and \italic{ref} must evaluate to strings.
}
\bold{Description}
\leftindent{If the regular expression in \italic{pat} is found in
\italic{ref,}
returns \typewriter{T}, otherwise returns \typewriter{NIL}. }
\bold{See Also}\leftindent{
See the \typewriter{regexp.doc} for a discussion of the syntax and use of
regular expressions.}
\leftindent{
}\bold{Defined In
}\leftindent{ELI primitive.
}
______________________________________________________
\paragraph{\index{1.6.0.8
RE-STRDECOMPOSE}
}______________________________________________________
\typewriter{(re-strdecompose \italic{pat ref})
}
\bold{Parameters}
\leftindent{\italic{Pat} and \italic{ref} must evaluate to strings.
}
\bold{Description}
\leftindent{If the regular expression in \italic{pat} is found in
\italic{ref,}
returns a list of the form (prefix matched suffix), where prefix and
suffix
are the parts of \italic{ref} before and after the portion that
\italic{pat}
matched, and matched is the matched portion itself. If no match is
found,
\typewriter{NIL} is returned.
}\bold{See Also}\leftindent{
See the \typewriter{regexp.doc} for a discussion of the syntax and use of
regular expressions.}
\leftindent{
}\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{Example}
\leftindent{\typewriter{(re-strdecompose "S[a-z]*" "Robert Steven
Glickstein")}
returns \typewriter{("Robert " "Steven" " Glickstein")}.}
______________________________________________________
\paragraph{\index{1.6.0.9
RE-STRDECOMPOSE+}
}______________________________________________________
\typewriter{(re-strdecompose+ \italic{pat ref})
}
\bold{Parameters}
\leftindent{\italic{Pat} and \italic{ref} must evaluate to strings.
\bold{Description}
}
\leftindent{If the regular expression in \italic{pat} is found in
\italic{ref,}
returns a list of the form (prefix (matched submatch1 submatch2 ...
submatchn)
suffix), where prefix and suffix are the parts of \italic{ref} before and
after the portion that \italic{pat} matched, matched is the matched
portion
itself, and submatch1 through submatchn are the portions of \italic{ref}
which
were matched by successive ( and ) pairs. If no match is found,
\typewriter{NIL} is returned.}
\leftindent{
}\bold{See Also}\leftindent{
See the \typewriter{regexp.doc} for a discussion of the syntax and use of
regular expressions.}
\leftindent{
}\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{Example}
\leftindent{\programexample{(re-strdecompose+ "Robert (.*) Glickstein"
"Robert
Steven Glickstein, Jello Biafra")
}returns
}\programexample{\leftindent{("" ("Robert Steven Glickstein" "Steven") ",
Jello Biafra").}
}
______________________________________________________
\paragraph{\index{1.6.0.10
RINDEX}
}______________________________________________________
\typewriter{(rindex \italic{str char})
}
\bold{Parameters}
\leftindent{\italic{Str} and \italic{char} must evaluate to strings.
(\italic{Char} should be a one-character string.) }
\bold{Description}
\leftindent{Searches for (the first character of) \italic{char} in
\italic{str,} returning that sub-part of \italic{str} which starts with
char.
Searches from \italic{right} to left, so that if \italic{str} contains
more
than one of \italic{char,} the return value will start from the last
occurrence of \italic{char} in \italic{str.} (See INDEX for a similar
function which searches from left to right.) If \italic{char} is not
found in
\italic{str,} \typewriter{NIL} is returned.}
\leftindent{
}\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{Example}
\leftindent{\typewriter{(rindex "Hawaii" "a")} returns
\typewriter{"aii"}.}
______________________________________________________
\paragraph{\index{1.6.0.11
STR-TO-LIST}
}______________________________________________________
\typewriter{(str-to-list \italic{str delim})
}
\bold{Parameters}
\leftindent{\italic{Str} and \italic{delim} must evaluate to strings.
\bold{Description}
\leftindent{Breaks \italic{str} into substrings at occurrences of
\italic{delim,} and returns a list of the pieces.}
\leftindent{
}\bold{Defined In
}\leftindent{strings.eli
}
}
\bold{Example}
\leftindent{\typewriter{(str-to-list "Joe and Ted and Dan" " and ")}
returns
\typewriter{("Joe" "Ted" "Dan")}.}
______________________________________________________
\paragraph{\index{1.6.0.12
STRCAT}
}______________________________________________________
\typewriter{(strcat \italic{str1 str2 ... strn})
}
\bold{Parameters}
\leftindent{\italic{Str1} though \italic{strn} must evaluate to strings.
}
\bold{Description}
\leftindent{Returns a string which is the result of concatenating all the
\italic{stri's.} \italic{N} may be 1, in which case \italic{str1} is
returned.}
\leftindent{
}\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{Example}
\leftindent{\typewriter{(strcat "B" "G" "Lisp" ")} returns
\typewriter{"BGLisp"}.}
______________________________________________________
\paragraph{\index{1.6.0.13
STRCONTAINS}
}______________________________________________________
\typewriter{(strcontains \italic{pat ref ignoreCase})
}
\bold{Parameters}
\leftindent{\italic{Pat} and \italic{ref} must evaluate to strings,
\italic{ignoreCase} may evaluate to any expression. }
\bold{Description}
\leftindent{If the string \italic{pat} is contained in the string
\italic{ref,}
returns \typewriter{T}, otherwise returns \typewriter{NIL}.
\italic{IgnoreCase} may be omitted; if it is present, and it does not
evaluate to \typewriter{NIL}, then alphabetic case is ignored during the
search (i.e., upper-case and lower-case letters are treated as equal).}
\bold{Defined In
}\leftindent{ELI primitive.
}
______________________________________________________
\paragraph{\index{1.6.0.14
STRDECOMPOSE}
}______________________________________________________
\typewriter{(strdecompose \italic{pat ref ignoreCase})
}
\bold{Parameters}
\leftindent{\italic{Pat} and \italic{ref} must evaluate to strings,
\italic{ignoreCase} may evaluate to any expression. }
\bold{Description}
\leftindent{If the string pat is found in the string \italic{ref,}
returns a
list of the form (prefix matched suffix), where prefix and suffix are the
parts of \italic{ref} before and after the portion that \italic{pat}
matched,
and matched is the matched portion itself. \italic{IgnoreCase} may be
omitted; if it is present, and if it does not evaluate to
\typewriter{NIL},
then alphabetic case is ignored during the search (i.e., upper-case and
lower-case letters are treated as equal). If no match is found,
\typewriter{NIL} is returned.}
\leftindent{
}\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{Example}
\leftindent{\typewriter{(strdecompose "Steven" "Robert Steven
Glickstein")}
returns \typewriter{("Robert " "Steven" " Glickstein")}.}
______________________________________________________
\paragraph{\index{1.6.0.15
STRINGP}
}______________________________________________________
\typewriter{(stringp \italic{e})
}
\bold{Parameters}
\leftindent{\italic{E} may evaluate to any expression.
}
\bold{Description}
\leftindent{If \italic{e} is a string, returns \typewriter{T}, otherwise
returns \typewriter{NIL}.}
\bold{Defined In
}\leftindent{ELI primitive.
}
______________________________________________________
\paragraph{\index{1.6.0.16
STRLEN}
}______________________________________________________
\typewriter{(strlen \italic{s})
}
\bold{Parameters}
\leftindent{\italic{S} must evaluate to a string. }
\bold{Description}
\leftindent{ Returns the number of character in \italic{s.} }
\leftindent{
}\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{Example}
\leftindent{\typewriter{(strlen "hello")} returns \typewriter{5}.}
______________________________________________________
\paragraph{\index{1.6.0.17
STRSTARTS}
}______________________________________________________
\typewriter{(strstarts \italic{prefix ref})
}
\bold{Parameters}
\leftindent{\italic{Prefix} and \italic{ref} must evaluate to strings.
\bold{Description}
\leftindent{If \italic{ref} starts with the string \italic{prefix,}
returns
\typewriter{T}, otherwise returns \typewriter{NIL}.}
\leftindent{
}\bold{Defined In
}\leftindent{ELI primitive.
}
}
\bold{Example}
\leftindent{\typewriter{(strstarts "Hi" "Hi There")} returns
\typewriter{T}.
\typewriter{(strstarts "Canada" "O Canada")} returns \typewriter{NIL}.}
______________________________________________________
\paragraph{\index{1.6.0.18
STR-TO-INT}
}______________________________________________________
\typewriter{(str-to-int \italic{s})
}
\bold{Parameters}
\leftindent{\italic{S} must evaluate to a string.
}
\bold{Description}
\leftindent{If\italic{ s }is the ASCII representation of a base-10
integer,
returns that integer. If STR-TO-INT can't understand \italic{s,} returns
0.}
\leftindent{
}\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{Example}
\leftindent{\typewriter{(str-to-int "-327")} returns \typewriter{-327}.}
______________________________________________________
\paragraph{\index{1.6.0.19
SUBSTRING}
}______________________________________________________
\typewriter{(substring \italic{str start len})
}
\bold{Parameters}
\leftindent{\italic{Str} must evaluate to a string, \italic{start} and
\italic{len} must evaluate to integers. }
\bold{Description}
\leftindent{Returns a portion of \italic{str} starting at character
\italic{start} and containing the next \italic{len} characters. The
first
character in a string is numbered zero.}
\leftindent{
}\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{Example}
\leftindent{\typewriter{(substring "Bob Glickstein" 4 5)} returns
\typewriter{"Glick"}.}
______________________________________________________
\paragraph{\index{1.6.0.20
UCSTRING}
}______________________________________________________
\typewriter{(ucstring \italic{str})
}
\bold{Parameters}
\leftindent{\italic{Str} must evaluate to a string.
}
\bold{Description}
\leftindent{Returns the string \italic{str} with all lower-case letters
replaced by capital ones.}
\leftindent{
}\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{Example}
\leftindent{\typewriter{(ucstring "Bob Glickstein")} returns
\typewriter{"BOB
GLICKSTEIN"}.}
\begindata{bp,539691144}
\enddata{bp,539691144}
\view{bpv,539691144,1747,0,0}
\section{1.7
List Manipulation
}
\text{\text{______________________________________________________
\paragraph{\index{1.7.0.1
APPEND
}
}______________________________________________}}\text{________
}
\typewriter{(append \italic{l1 l2 ... ln})
}
\bold{Parameters}
\leftindent{\italic{L1} through \italic{ln} must evaluate to lists.
}
\bold{Description}
\leftindent{Returns a new list which is the result of removing the outer
parentheses from each \italic{li}, placing the lists "end to end", and
surrounding the entire result with a pair of parentheses. \italic{N} may
be
zero, in which case \typewriter{APPEND} returns \typewriter{NIL}.
}
\bold{Return Value}
\leftindent{A new list, or \typewriter{NIL}.
}
\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{See Also}
\leftindent{\typewriter{LIST, CONS, APPLY}
}
\bold{Example}
\leftindent{\typewriter{(append '(a b c) '(d e f))} returns
\typewriter{(a b c
d e f)}.
}
______________________________________________________
\paragraph{\index{1.7.0.2
ASSOC}
}______________________________________________________
\typewriter{(assoc \italic{key a-list})
}
\bold{Parameters
}\leftindent{\italic{Key} may evaluate to any expression, \italic{a-list}
should evaluate to a list of the form \italic{((k1 d1) (k2 d2) ... (kn
dn))}.
}
\bold{Description}
\leftindent{Returns the first sublist in \italic{a-list} whose car is
\italic{key}, or \typewriter{NIL} if no such sublist is found. Note that
the
sublists of \italic{a-list} can contain any number of elements, not only
a
\italic{ki} and \italic{di} pair.}
\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{Example}
\leftindent{\typewriter{(assoc 'a '((a b c) (d e) (a g h)))} returns
\typewriter{(a b c)}.}
______________________________________________________
\paragraph{\index{1.7.0.3
CAR}
}______________________________________________________
\typewriter{(car \italic{l})
}
\bold{Parameters}
\leftindent{\italic{L} must evaluate to a list.
}
\bold{Description}
\leftindent{Returns the car (first element) of the list \italic{l}.
car
of \typewriter{NIL} is \typewriter{NIL}.}
The
\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{Example}
\leftindent{\typewriter{(car '(a b c))} returns \typewriter{a}.}
______________________________________________________
\paragraph{\index{1.7.0.4
CDR}
}______________________________________________________
\typewriter{(cdr \italic{l})
}
\bold{Parameters}
\leftindent{\italic{L} must evaluate to a list.
}
\bold{Description}
\leftindent{Returns the cdr (the list of everything except the car) of
\italic{l}.
The cdr of \typewriter{NIL} is \typewriter{NIL}.}
\leftindent{
}\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{Example}
\leftindent{\typewriter{(cdr '(a b c))} returns \typewriter{(b c)}.}
______________________________________________________
\paragraph{\index{1.7.0.5
CONS}
}______________________________________________________
\typewriter{(cons \italic{e l})
}
\bold{Parameters}
\leftindent{\italic{E} may evaluate to any expression, \italic{l} must
evaluate to a list. }
\bold{Description}
\leftindent{Returns the result of prepending \italic{e} to \italic{l},
making
it the new car.}
\leftindent{
}\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{Example}
\leftindent{\typewriter{(cons 'a '(b c))} returns \typewriter{(a b c)}.}
______________________________________________________
\paragraph{\index{1.7.0.6
CONSP}
}______________________________________________________
\typewriter{(consp \italic{e})
}
\bold{Parameters}
\leftindent{\italic{E} may evaluate to any expression.
}
\bold{Description}
\leftindent{If \italic{e} is a list, returns \typewriter{T}, otherwise
returns
\typewriter{NIL}. Note that (consp \typewriter{NIL}) returns
\typewriter{T},
since \typewriter{NIL} is equivalent to the empty list ().}
\bold{Defined In
}\leftindent{ELI primitive.
}
______________________________________________________
\paragraph{\index{1.7.0.7
INTERSECT}
}______________________________________________________
\typewriter{(intersect \italic{x y})
}
\bold{Parameters}
\leftindent{\italic{X} and \italic{y} must evaluate to lists.
}
\bold{Description}
\leftindent{Returns a list of the elements common to both \italic{x} and
\italic{y}.}
\leftindent{
}\bold{Defined In
}\leftindent{lists.eli
}
\bold{Example}
\leftindent{\typewriter{(intersect '(a b c d e) '(b d f h j))} returns
\typewriter{(d b)} (yes, the elements are in reverse order).}
______________________________________________________
\paragraph{\index{1.7.0.8
LENGTH}
}______________________________________________________
\typewriter{(length \italic{x})
}
\bold{Parameters}
\leftindent{\italic{X} must evaluate to a list.
}
\bold{Description}
\leftindent{Returns the number of items in \italic{x}.}
\leftindent{
}\bold{Defined In
}\leftindent{lists.eli
}
\bold{Example}
\leftindent{\typewriter{(length '(a b (c d)))} returns \typewriter{3}
(since
\typewriter{(c d)} counts as one top-level item).}
______________________________________________________
\paragraph{\index{1.7.0.9
LIST}
}______________________________________________________
\typewriter{(list e1 e2 ... en)
}
\bold{Parameters}
\leftindent{\italic{E1} through \italic{en} may evaluate to any
expressions. }
\bold{Description}
\leftindent{Returns a list created by placing the \italic{ei's} "end-toend"
and surrounding them with parentheses. \italic{N} may be zero, in which
case
\typewriter{LIST} returns \typewriter{NIL}.}
\leftindent{
}\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{Example}
\leftindent{\typewriter{(list 'a '(b c d) 7)} returns \typewriter{(a (b c
d)
7)}.}
______________________________________________________
\paragraph{\index{1.7.0.10
LIST-TO-STR}
}______________________________________________________
\typewriter{(list-to-str \italic{strs separator})
}
\bold{Parameters}
\leftindent{\italic{Strs} must evaluate to a list of strings,
\italic{separator} must evaluate to a string. }
\bold{Description}
\leftindent{Concatenates the strings in \italic{strs,} separating each by
the
string in \italic{separator.} }
\leftindent{
}\bold{Defined In
}\leftindent{strings.eli
}
\bold{Example}
\leftindent{\typewriter{(list-to-str '("Joe" "Ted" "Dan") " and ")}
returns
\typewriter{"Joe and Ted and Dan"}.}
______________________________________________________
\paragraph{\index{1.7.0.11
MEMBER}
}______________________________________________________
\typewriter{(member \italic{elt list})
}
\bold{Parameters}
\leftindent{\italic{Elt} may evaluate to any expression, \italic{list}
must
evaluate to a list. }
\bold{Description}
\leftindent{If \italic{elt} is found in \italic{list}, returns that part
of
\italic{list} that starts with the first occurrence of \italic{elt},
otherwise
returns \typewriter{NIL}.}
\leftindent{
}\bold{Defined In
}\leftindent{lists.eli
}
\bold{Example}
\leftindent{\typewriter{(member 'c '(a b c d e))} returns \typewriter{(c
d
e)}. However, \typewriter{(member 'c '(a b (c d) e))} returns
\typewriter{NIL}, since \typewriter{c} is not a top-level element of the
list.}
______________________________________________________
\paragraph{\index{1.7.0.12
NTH}
}______________________________________________________
\typewriter{(nth \italic{num list})
}
\bold{Parameters}
\leftindent{\italic{Num} must evaluate to a non-negative integer,
\italic{list}
must evaluate to a list. }
\bold{Description}
\leftindent{Returns the \italic{num}-th element of \italic{list}, where
the
first element of \italic{list} is numbered zero.}
\leftindent{
}\bold{Defined In
}\leftindent{lists.eli
}
\bold{Example}
\leftindent{\typewriter{(nth 2 '(a b c d))} returns \typewriter{c}.}
______________________________________________________
\paragraph{\index{1.7.0.13
REMOVE-DUPLICATES}
}______________________________________________________
\typewriter{(remove-duplicates \italic{list})
}
\bold{Parameters}
\leftindent{\italic{List} must evaluate to a list.
}
\bold{Description}
\leftindent{Removes all but the last occurrence of each top-level element
of
\italic{list} that is repeated.}
\leftindent{
}\bold{Defined In
}\leftindent{lists.eli
}
\bold{Example}
\leftindent{\typewriter{(remove-duplicates '(a b c b d b))} returns
\typewriter{(a c d b)}.}
______________________________________________________
\paragraph{\index{1.7.0.14
REVERSE}
}______________________________________________________
\typewriter{(reverse \italic{list})
}
\bold{Parameters}
\leftindent{\italic{List} must evaluate to a list. }
\bold{Description}
\leftindent{ Returns the result of reversing the order of the top-level
elements in \italic{list}.}
\leftindent{
}\bold{Defined In
}\leftindent{lists.eli
}
\bold{Example}
\leftindent{\typewriter{(reverse '(a b (c d) e))} returns \typewriter{(e
(c d)
b a)}.}
______________________________________________________
\paragraph{\index{1.7.0.15
SNOC}
}______________________________________________________
\typewriter{(snoc \italic{elt list})
}
\bold{Parameters}
\leftindent{\italic{Elt} may evaluate to any expression, \italic{list}
must
evaluate to a list. }
\bold{Description}
\leftindent{Performs a CONS of \italic{elt} onto \italic{list}, but at
the end
of \italic{list} instead of at the beginning. Returns the new list.}
\leftindent{
}\bold{Defined In
}\leftindent{lists.eli
}
\bold{Example}
\leftindent{\typewriter{(snoc 'e '(a b c d))} returns \typewriter{(a b c
d
e)}.}
______________________________________________________
\paragraph{\index{1.7.0.16
UNION}
}______________________________________________________
\typewriter{(union \italic{x y})
}
\bold{Parameters}
\leftindent{\italic{X} and \italic{y} must evaluate to lists.
}
\bold{Description}
\leftindent{Returns a list containing all elements in either \italic{x}
or
\italic{y}, with overlaps removed.}
\leftindent{
}\bold{Defined In
}\leftindent{lists.eli
}
\bold{Example}
\leftindent{\typewriter{(union '(a b c) '(c d e))} returns \typewriter{(a
b c
d e)}.}
\begindata{bp,539691080}
\enddata{bp,539691080}
\view{bpv,539691080,1748,0,0}
\section{1.8
Symbols, Binding, and Functions
}
______________________________________________________
\paragraph{\index{1.8.0.1
ATOM}
}______________________________________________________
\typewriter{(atom \italic{e})
}
\bold{Parameters
}\leftindent{\italic{E} may evaluate to any expression.
}
\bold{Description}
\leftindent{Returns \typewriter{T} if \italic{e} is an "atom",
\typewriter{NIL}
otherwise. Integers, strings and symbols are atoms, as well as the empty
list
(), which is equivalent to the symbol \typewriter{NIL}.}
\bold{Defined In
}\leftindent{ELI primitive.
}
______________________________________________________
\paragraph{\index{1.8.0.2
BOUNDP}
}______________________________________________________
\typewriter{(boundp \italic{s})
}
\bold{Parameters}
\leftindent{\italic{S} must evaluate to a symbol.
}
\bold{Description}
\leftindent{If there is a value bound to \italic{s} (typically by
\typewriter{SETQ}), returns \typewriter{T}, otherwise returns
\typewriter{NIL}.}
\bold{Defined In
}\leftindent{ELI primitive.
}
______________________________________________________
\paragraph{\index{1.8.0.3
DEFUN}
}______________________________________________________
\typewriter{(defun \italic{name params body})
}
\bold{Parameters}
\leftindent{\italic{Name} is a symbol, \italic{params} is a list of
symbols
(possibly empty), \italic{body} is any expression. None of these
arguments is
evaluated. }
\bold{Description}
\leftindent{Creates a function with the name \italic{name}, whose
parameters
are given by the list \italic{params}, and whose value is the result of
evaluating \italic{body} with the given parameters. Returns
\italic{name}.}
\leftindent{
}\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{Example}
\leftindent{\typewriter{(defun two-x-plus-y (x y) (+ (* 2 x) y))} creates
a
function called \typewriter{two-x-plus-y} which, when passed two
integers,
will multiply the first one by two and add that to the second one:
\typewriter{(two-x-plus-y 3 4)} will return \typewriter{10}.
\typewriter{(two-x-plus-y (+ 1 2) (+ 3 1))} will also return
\typewriter{10}
since the parameters are evaluated (to \typewriter{3} and \typewriter{4},
respectively) before the function body is executed.}
______________________________________________________
\paragraph{\index{1.8.0.4
DEFUNQ}
}______________________________________________________
\typewriter{(defunq \italic{name params body})
}
\bold{Parameters}
\leftindent{\italic{Name} is a symbol, \italic{params} is a list of
symbols
(possibly empty), \italic{body} is any expression.
arguments is
evaluated. }
None of these
\bold{Description}
\leftindent{Creates a function with the name \italic{name}, whose
parameters
are given by the list \italic{params}, and whose value is the result of
evaluating \italic{body} with the given parameters. The difference
between
DEFUN and DEFUNQ is that functions created with DEFUN will evaluate their
parameters before executing the function body; functions created with
DEFUNQ
will not evaluate their parameters. Returns \italic{name}.}
\leftindent{
}\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{Example}
\leftindent{\typewriter{(defunq two-x-plus-y (x y) (+ (* 2 x) y))}
creates a
function called \typewriter{two-x-plus-y} which, when passed two
integers,
will multiply the first one by two and add that to the second one:
\typewriter{(two-x-plus-y 3 4)} will return \typewriter{10}. However,
\typewriter{(two-x-plus-y (+ 1 2) (+ 3 1))} will not return
\typewriter{10},
it will cause an error to occur.}
______________________________________________________
\paragraph{\index{1.8.0.5
DEFUNV}
}______________________________________________________
\typewriter{(defunv \italic{name param body})
}
\bold{Parameters}
\leftindent{\italic{Name} is a symbol, \italic{param} is a list
containing one
symbol, \italic{body} is any expression. None of these arguments is
evaluated.
}
\bold{Description}
\leftindent{Creates a function with the name \italic{name}, which can
take any
number of arguments. All arguments to the function are evaluated, placed
in a
list and assigned to the symbol in \italic{param}. Returns
\italic{name}.}
\leftindent{
}\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{Example}
\leftindent{\typewriter{(defunv two-x-plus-y (a) (+ (* 2 (car a)) (car
(cdr
a))))} creates a function called \typewriter{two-x-plus-y} which, when
passed
two integers, places those integers in a list and multiplies the first
one by
two and adds that to the second one: \typewriter{(two-x-plus-y 3 4)} will
assign the list \typewriter{(3 4)} to \typewriter{a} and return
\typewriter{10}.}
______________________________________________________
\paragraph{\index{1.8.0.6
DEFUNVQ}
}______________________________________________________
\typewriter{(defunvq \italic{name param body})
}
\bold{Parameters}
\leftindent{\italic{Name} is a symbol, \italic{param} is a list
containing one
symbol, \italic{body} is any expression. None of these arguments is
evaluated. }
\bold{Description}
\leftindent{Creates a function with the name \italic{name}, which can
take any
number of arguments. All arguments to the function are placed in a list
and
assigned to the symbol in \italic{param}. (These arguments are not
evaluated.) Returns \italic{name}.}
\leftindent{
}\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{Example}
\leftindent{\typewriter{(defunv two-x-plus-y (a) (+ (* 2 (car a)) (car
(cdr
a))))} creates a function called \typewriter{two-x-plus-y} which, when
passed
two integers, places those integers in a list and multiplies the first
one by
two and adds that to the second one: \typewriter{(two-x-plus-y 3 4)} will
assign the list \typewriter{(3 4)} to \typewriter{a} and return
\typewriter{10}. However, \typewriter{(two-x-plus-y (+ 1 2) (+ 3 1))}
will
assign \typewriter{((+ 1 2) (+ 3 1))} to \typewriter{a}, and cause an
error to
occur.}
______________________________________________________
\paragraph{\index{1.8.0.7
DISCARD}
}______________________________________________________
\typewriter{(discard \italic{s})
}
\bold{Parameters}
\leftindent{\italic{S} must evaluate to a symbol.
}
\bold{Description}
\leftindent{Removes \italic{s} from the table of "known symbols". If
\italic{s} had a function or value (or both) bound to it, they are lost.
Returns \italic{s}. }
\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{Known Bugs}
\leftindent{WHATEVER YOU DO, DO NOT USE THIS PRIMITIVE.
fairly
unpredictable side-effects.}
It has some
______________________________________________________
\paragraph{\index{1.8.0.8
FUNCTION}
}______________________________________________________
\typewriter{(function \italic{s})
}
\bold{Parameters}
\leftindent{\italic{S} must evaluate to a symbol.
}
\bold{Description}
\leftindent{Returns the function bound to \italic{s} (which was probably
done
with \typewriter{DEFUN} or \typewriter{DEFUNQ}). If the function is a
list,
it returns the list; however the function may be a compiled subroutine,
in
which case it returns an object which is a pointer to the compiled
routine.
(If this object is displayed, it comes out looking like
"\typewriter{;<Subr:#10003aec>}" or something.) If \italic{s} has no
function
bound to it, an error occurs.}
\leftindent{
}\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{Example}
\leftindent{If you \typewriter{(load "elilib")} (which, among other
things,
defines a function called "\typewriter{LENGTH}", which returns the length
of a
list), then \typewriter{(function 'length)} will return the list
\typewriter{(lambda (list) (cond ((null list) 0) (t (+ 1 (length (cdr
list))))))}.}
______________________________________________________
\paragraph{\index{1.8.0.9
GENSYM}
}______________________________________________________
\typewriter{(gensym)
}\bold{Parameters}
\leftindent{None.}
\bold{Description}
\leftindent{\typewriter{GENSYM} returns a symbol whose name is guaranteed
to
be unique among all currently existing symbols. Note that the returned
symbol
is "interned", so this function is more like Common Lisp's
\typewriter{GENTEMP}
than \typewriter{GENSYM}.}
\leftindent{
}\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{Example}
\leftindent{The first call to \typewriter{GENSYM} will return the symbol
\typewriter{g#1}, the second will return \typewriter{g#2}, etc. Note
that the
number after the \typewriter{#} mark is a hexadecimal number; that is,
after
\typewriter{g#9}, there will be \typewriter{g#a}, \typewriter{g#b},
\typewriter{g#c}, \typewriter{g#d}, \typewriter{g#e} and \typewriter{g#f}
before \typewriter{g#10}. \typewriter{GENSYM} will skip over a number in
this
sequence if there is a symbol with the same name anywhere.}
______________________________________________________
\paragraph{\index{1.8.0.10
LET}
}______________________________________________________
\typewriter{(let \italic{((var1 val1)
(var2 val2)
...
(varn valn))
body})
}
\bold{Parameters}
\leftindent{LET takes two arguments, a variable list and a \italic{body,}
neither of which are evaluated. Each of the \italic{vari's} in the
variable
list must be a symbol. }
\bold{Description}
\leftindent{LET evaluates and binds each \italic{vali} to \italic{vari,}
then
evaluates \italic{body} while these temporary variables are in effect.
The
return value is the result of evaluating \italic{body.} When LET
returns, the
\italic{vari's} revert to their previous values, if any. Note that LET
evaluates every \italic{vali} before binding any to the \italic{vari's.}
This
is not the case with LET*. There are times when each functionality is
useful.
\italic{Body} may be omitted, in which case \typewriter{NIL} is
returned.}
\leftindent{
}\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{Example}
\leftindent{If you \typewriter{(setq a 7)}, then \typewriter{(let ((a 6))
a)}
will return \typewriter{6}, not \typewriter{7}. (However, \typewriter{a}
will
be \typewriter{7} after \typewriter{LET} returns.)}
______________________________________________________
\paragraph{\index{1.8.0.11
LET*}
}______________________________________________________
\typewriter{(let* \italic{((var1 val1)
(var2 val2)
...
(varn valn))
body})
}
\bold{Parameters}
\leftindent{LET* takes two arguments, a variable list and a
\italic{body,}
neither of which are evaluated. Each of the \italic{vari's} in the
variable
list must be a symbol. }
\bold{Description}
\leftindent{LET* evaluates and binds each \italic{vali} to \italic{vari,}
then
evaluates \italic{body} while these temporary variables are in effect.
The
return value is the result of evaluating \italic{body.} When LET*
returns,
the \italic{vari's} revert to their previous values, if any. Note that
LET*
evaluates \italic{vali} and binds it to \italic{vari} before evaluating
\italic{vali+1} and binding it to \italic{vari+1.} This allows the
values of
variables bound earlier in the list to be used later in the list. This
is as
opposed to LET. \italic{Body} may be omitted, in which case
\typewriter{NIL}
is returned.}
\bold{Defined In
}\leftindent{ELI primitive.
}
______________________________________________________
\paragraph{\index{1.8.0.12
SET}
}______________________________________________________
\typewriter{(set \italic{x y})
}
\bold{Parameters}
\leftindent{\italic{X} must evaluate to a symbol, \italic{y} may evaluate
to
any expression. }
\bold{Description}
\leftindent{Exactly like \typewriter{SETQ}, except that \italic{x} is
evaluated first.}
\leftindent{
}\bold{Defined In
}\leftindent{misc.eli
}
\bold{Example}
\leftindent{If you \typewriter{(setq a 'b)}, then \typewriter{(set a 7)}
will
return \typewriter{7} and bind \typewriter{7} to the symbol
\typewriter{b},
while \typewriter{a} will retain the value \typewriter{b}.}
______________________________________________________
\paragraph{\index{1.8.0.13
SETQ}
}______________________________________________________
\typewriter{(setq \italic{var val})
}
\bold{Parameters}
\leftindent{\italic{Var} must be a symbol, \italic{val} may evaluate to
any
expression. }
\bold{Description}
\leftindent{The symbol named by \italic{var} (which is unevaluated) has
the
value \italic{val} dynamically bound to it. Returns the bound value.}
\leftindent{
}\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{Example}
\leftindent{\typewriter{(setq a (+ 3 4))} returns \typewriter{7}, and
binds
\typewriter{7} to the symbol \typewriter{a}.
\typewriter{(let ((foo 0)) (progn (setq foo 10) foo))} returns
\typewriter{10}, and doesn't change the top-level binding of
\typewriter{foo}
(if any).
}
______________________________________________________
\paragraph{\index{1.8.0.14
SYMBOLP}
}______________________________________________________
\typewriter{(symbolp \italic{e})
}
\bold{Parameters}
\leftindent{\italic{E} may evaluate to any expression.
}
\bold{Description}
\leftindent{If \italic{e} evaluates to a symbol, returns \typewriter{T},
otherwise returns \typewriter{NIL}.}
\bold{Defined In
}\leftindent{ELI primitive.
}
______________________________________________________
\paragraph{\index{1.8.0.15
SYM-TO-STR}
}______________________________________________________
\typewriter{(sym-to-str \italic{sym})
}
\bold{Parameters}
\leftindent{\italic{Sym} must evaluate to a symbol.
}
\bold{Description}
\leftindent{Returns a string containing the name of \italic{sym.} }
\leftindent{
}\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{Example}
\leftindent{\typewriter{(sym-to-str 'defun)} returns
\typewriter{"DEFUN"}.}
______________________________________________________
\paragraph{\index{1.8.0.16
UNBIND}
}______________________________________________________
\typewriter{(unbind \italic{s})
}
\bold{Parameters}
\leftindent{\italic{S} must evaluate to a symbol.
}
\bold{Description}
\leftindent{Removes the value bound to \italic{s} (which was probably
bound
with \typewriter{SETQ}). Returns \italic{s.} }
\bold{Defined In
}\leftindent{ELI primitive.
}
______________________________________________________
\paragraph{\index{1.8.0.17
UNBINDFN}
}______________________________________________________
\typewriter{(unbindfn \italic{s})
}
\bold{Parameters}
\leftindent{\italic{S} must evaluate to a symbol.
}
\bold{Description}
\leftindent{Removes the function bound to \italic{s} (which was probably
done
with \typewriter{DEFUN} or \typewriter{DEFUNQ}). Returns \italic{s.} }
\bold{Defined In
}\leftindent{ELI primitive.
}
\begindata{bp,539691016}
\enddata{bp,539691016}
\view{bpv,539691016,1749,0,0}
\section{1.9
Iteration, Application, and Conditionals
}
______________________________________________________
\paragraph{\index{1.9.0.1
AND}
}______________________________________________________
\typewriter{(and \italic{e1 e2 ... en})
}
\bold{Parameters}
\leftindent{\italic{E1} through\italic{ en} may be any expressions.
}
\bold{Description}
\leftindent{Evaluates \italic{e1} through \italic{en} in order. If any
\italic{ei} evaluates to \typewriter{NIL}, stops evaluating immediately
and
returns \typewriter{NIL}. If all \italic{n} expressions evaluate to
non-\typewriter{NIL}, returns the value of the last expression.
\italic{N}
may be zero, in which case \typewriter{AND} returns \typewriter{T}.
}
\bold{Return Value}
\leftindent{Returns \typewriter{T} or \typewriter{NIL}.
}
\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{See Also}
\typewriter{\leftindent{OR, NOT, COND, CASE
}}
\bold{Example}
\leftindent{\typewriter{(and (+ 2 3) (car '(nil t nil)) (setq foo 'bar))}
would evaluate \typewriter{(+ 2 3)}, then \typewriter{(car '(nil t nil))}
and
return \typewriter{NIL}, without evaluating the \typewriter{setq}
expression.
}
______________________________________________________
\paragraph{\index{1.9.0.2
APPLY}
}______________________________________________________
\typewriter{(apply \italic{func arglist})
}
\bold{Parameters}
\leftindent{\italic{Func} must evaluate to a symbol naming a function, or
to a
lambda list; \italic{arglist} must evaluate to a list. }
\bold{Description}
\leftindent{Calls the procedure \italic{func,} giving it the elements in
\italic{arglist} as its parameters. Returns the result of \italic{func.}
The
individual arguments to \italic{func} will not be evaluated (this is
accomplished by QUOTE-ing each of the arguments, which breaks invocation
of
functions which don't evaluate their arguments (e.g. DO, or any DEFUNV-ed
function). Try using EVAL instead.).}
\leftindent{
}\bold{Defined In
}\leftindent{lists.eli
}
\bold{Example}
\leftindent{\typewriter{(apply '+ '(3 4 5))} returns \typewriter{12}.
\typewriter{(apply 'list '(a b c))} returns \typewriter{(a b c)}.}
______________________________________________________
\paragraph{\index{1.9.0.3
CASE}
}______________________________________________________
\typewriter{(case \italic{keyform (keylist resultforms*)*})
}
\bold{Parameters}
\leftindent{Case takes a \italic{keyform} and any number of
(\italic{keylist}
\italic{resultforms)} expressions. }
\bold{Description}
\leftindent{CASE will evaluate \italic{keyform} once, and then find a
match
for it in one of the \italic{keylists.} When a match is found, the
\italic{resultforms} are executed in an implicit PROGN. If there is no
match,
or no \italic{resultforms,} then \typewriter{NIL} is returned, unless
\italic{keylist} is one of the atoms \typewriter{T} or OTHERWISE, then
the
\italic{resultforms} will always be executed. If there is just one key
in the
\italic{keylist,} then the \italic{keylist} may be written as that key
alone,
as long as it it unambiguous. Keep in mind that the keys in the
\italic{keylist} are not evaluated and should not be quoted.}
\leftindent{
}\bold{Defined In
}\leftindent{lists.eli
}
\bold{Example}
\leftindent{\programexample{(case 'foo
(bar (print "hi") 123)
(foo (print "bye") 456)
(otherwise (print "error") 999))
}prints \typewriter{"bye"} and returns \typewriter{456}.}
______________________________________________________
\paragraph{\index{1.9.0.4
COND}
}______________________________________________________
\typewriter{(cond
\italic{(t1 a1)
(t2 a2)
...
(tn an)} )
}
\bold{Parameters}
\leftindent{COND takes an arbitrary number of arguments which are not
evaluated. These arguments must each be a two-element list. Each list
must
contain a "test/action" pair. }
\bold{Description}
\leftindent{COND evaluates each \italic{ti} in order until it finds a
\italic{tj} which evaluates to non-\typewriter{NIL}. It then returns the
result of evaluating \italic{aj}. Note that \italic{n} may be zero, in
which
case COND returns \typewriter{NIL}. If every \italic{ti} evaluates to
\typewriter{NIL}, COND returns \typewriter{NIL}.}
\bold{Defined In
}\leftindent{ELI primitive.
}
______________________________________________________
\paragraph{\index{1.9.0.5
DO}
}______________________________________________________
\typewriter{(do \italic{((var1 init1 step1)
(var2 init2 step2)
...
(varn initn stepn))
(end-test return-val)
body})
}
\bold{Parameters}
\leftindent{DO takes three arguments, none of which are evaluated. The
first
is the variable list, the second is the \italic{end-test}/\italic{returnval}
pair, the third is the \italic{body} and can be any expression, or can be
omitted. Each \italic{vari} must be a symbol; each \italic{initi} and
\italic{stepi} can be any expression. }
\bold{Description}
\leftindent{First, the \italic{initi}'s are evaluated and bound to their
respective symbols \italic{vari}; then \italic{end-test} is evaluated.
If
end-test evaluates to \typewriter{NIL}, then \italic{body} is evaluated
(if it
is present). Following this, each \italic{stepi} is evaluated and bound
to
its repective \italic{vari}, replacing the old value of \italic{vari}.
The
\italic{end-test} is evaluated again, and the loop continues in this
fashion
until \italic{end-test} evaluates to non-\typewriter{NIL}. When this
occurs,
\italic{return-val} is evaluated and returned. The \italic{stepi}'s are
optional; if \italic{stepi} is omitted, then \italic{vari} will retain
the
value of \italic{initi} in each iteration. Note that in evaluating the
\italic{initi}'s and the \italic{stepi}'s, every \italic{initi} or
\italic{stepi} is evaluated before any are bound to the vari's. This is
not
the case with DO* (see below); there are times when each functionality is
useful. Note that \italic{n} (the number of variables) may be zero.
Note
also that the values bound to the variables vanish when DO returns, and
these
variables revert to their previous values, if any.}
\leftindent{
}\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{Example}
\leftindent{The expression
\programexample{(do ((lis '(a b c) (cdr lis))
(count 0 (+ count 1)))
((null lis) count))
}counts the length of the list \typewriter{(a b c)}, returning
\typewriter{3}.
\typewriter{Lis} is initially set to the list \typewriter{(a b c)}, and
\typewriter{count} is set to zero. In each iteration, \typewriter{lis}
is set
to the \typewriter{cdr} of itself, and \typewriter{count} is incremented,
until \typewriter{lis} is empty and \typewriter{count} has been
incremented
three times.
}
______________________________________________________
\paragraph{\index{1.9.0.6
DO*}
}______________________________________________________
\typewriter{(do*\italic{((var1 init1 step1)
(var2 init2 step2)
...
(varn initn stepn))
(end-test return-val)
body})
}
\bold{Parameters}
\leftindent{DO* takes three arguments, none of which are evaluated. The
first
is the variable list, the second is the \italic{end-test}/\italic{returnval}
pair, the third is the \italic{body} and can be any expression, or can be
omitted. Each \italic{vari} must be a symbol; each \italic{initi} and
\italic{stepi} can be any expression. }
\bold{Description}
\leftindent{First, the \italic{initi}'s are evaluated and bound to their
respective symbols \italic{vari}; then \italic{end-test} is evaluated.
If
\italic{end-test} evaluates to \typewriter{NIL}, then \italic{body} is
evaluated (if it is present). Following this, each \italic{stepi} is
evaluated and bound to its repective \italic{vari}, replacing the old
value of
\italic{vari}. The \italic{end-test} is evaluated again, and the loop
continues in this fashion until \italic{end-test} evaluates to
non-\typewriter{NIL}. When this occurs, \italic{return-val} is evaluated
and
returned. The \italic{stepi}'s are optional; if \italic{stepi} is
omitted,
then \italic{vari} will retain the value of \italic{initi} in each
iteration.
Note that in evaluating the \italic{initi}'s and \italic{stepi}'s, each
\italic{initi} or \italic{stepi} is evaluated and bound to \italic{vari}
before the next \italic{initi+1} or \italic{stepi+1} is evaluated (unlike
DO).
This makes values bound earlier in the variable list available for
variables
bound later in the last.}
\bold{Defined In
}\leftindent{ELI primitive.
}
______________________________________________________
\paragraph{\index{1.9.0.7
DOLIST}
}______________________________________________________
\typewriter{(dolist \italic{(var listform result) body})
}
\bold{Parameters}
\leftindent{\italic{Var} must be a symbol, \italic{listform} an
expression
evaluating to a list, and \italic{result} and \italic{body} can be any
expression.}
\bold{Description}
\leftindent{DOLIST takes two arguments, which become transformed into a
DO*
form. \italic{Var} is bound to successive CAR's of \italic{listform} for
each
evaluation of \italic{body.} The optional \italic{result} is returned as
the
value of the DOLIST form, or \typewriter{NIL} if there is no
\italic{result.} }
\leftindent{
}\bold{Defined In
}\leftindent{lists.eli
}
\bold{Example}
\leftindent{\programexample{(dolist (x '(a b c) t)
(print x))}
prints "\typewriter{ABC}" and returns \typewriter{T}.}
______________________________________________________
\paragraph{\index{1.9.0.8
EQ}
}______________________________________________________
\typewriter{(eq \italic{e1 e2})
}
\bold{Parameters}
\leftindent{\italic{E1 }and \italic{e2} may evaluate to any expression.
}
\bold{Description}
\leftindent{Tests for "strict" equality between the expressions
\italic{e1}
and \italic{e2}. Strict equality means that \italic{e1} and \italic{e2}
are
the same exact object, which is not always true even when two expressions
appear identical when displayed. Returns \typewriter{T} for true,
\typewriter{NIL} for false.}
\leftindent{
}\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{Example}
\leftindent{\typewriter{(eq 7 7)} is true. If you \typewriter{(setq a
7)},
then \typewriter{(eq a 7)} is true. \typewriter{(eq "hello" "hello")} is
true. \typewriter{(eq '(a b c) '(a b c))} is false. However, if you
\typewriter{(setq a '(a b c))} and \typewriter{(setq b a)}, then
\typewriter{(eq a b)} is true.}
______________________________________________________
\paragraph{\index{1.9.0.9
EQUAL}
}______________________________________________________
\typewriter{(equal \italic{e1 e2})
}
\bold{Parameters}
\leftindent{\italic{E1} and \italic{e2} may evaluate to any expression.
}
\bold{Description}
\leftindent{Tests for "weak" equality between the expressions \italic{e1}
and
\italic{e2}. Weak equality means that \italic{e1} and \italic{e2} are
isomorphic objects, which is generally true if and only if their
displayed
representations are true. For instance, strings are EQUAL if they
contain the
same sequence of characters; symbols are EQUAL if they have the same
names
(although they need not be the same symbol); lists are EQUAL if their
cars are
EQUAL and their cdrs are EQUAL. Returns \typewriter{T} for true,
\typewriter{NIL} for false.}
\leftindent{
}\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{Example}
\leftindent{\typewriter{(equal 'a 'a)} is true.
c)
'(a b c))} is true. You get the idea.}
\typewriter{(equal '(a b
______________________________________________________
\paragraph{\index{1.9.0.10
EVAL}
}______________________________________________________
\typewriter{(eval \italic{e})
}
\bold{Parameters}
\leftindent{\italic{E} may evaluate to any expression.
}
\bold{Description}
\leftindent{Evaluates and returns \italic{e}.}
\leftindent{
}\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{Example}
\leftindent{If you \typewriter{(setq a 7)}, then \typewriter{(eval 'a)}
returns \typewriter{7}. If you then \typewriter{(setq b 'a)},
\typewriter{(eval b)} returns \typewriter{7} also.}
______________________________________________________
\paragraph{\index{1.9.0.11
MAPCAR}
}______________________________________________________
\typewriter{(mapcar \italic{fn args)}
}
\bold{Parameters}
\leftindent{\italic{Fn} must evaluate to either a function (i.e., a
LAMBDA-list) or a symbol with a function bound to it, \italic{args} must
evaluate to a list. The function \italic{fn} must be one that expects a
single argument. }
\bold{Description}
\leftindent{Applies \italic{fn} to each of the elements of \italic{args},
returning a list of the evaluated results.}
\leftindent{
}\bold{Defined In
}\leftindent{lists.eli
}
\bold{Example}
\leftindent{\typewriter{(mapcar '(lambda (x) (+ x 1)) '(3 4 5))} returns
\typewriter{(4 5 6)}.}
______________________________________________________
\paragraph{\index{1.9.0.12
NOT and NULL}
}______________________________________________________
\typewriter{(not \italic{e})
(null \italic{e})
}
\bold{Parameters}
\leftindent{\italic{E} may evaluate to any expression.
\bold{Description}
}
\leftindent{If \italic{e} is \typewriter{NIL}, returns \typewriter{T},
otherwise returns \typewriter{NIL}.}
\bold{Defined In
}\leftindent{ELI primitive.
}
______________________________________________________
\paragraph{\index{1.9.0.13
OR}
}______________________________________________________
\typewriter{(or \italic{e1 e2 ... en})
}
\bold{Parameters}
\leftindent{\italic{E1} through \italic{en} may be any expressions.
}
\bold{Description}
\leftindent{Evaluates \italic{e1} through \italic{en} in turn until one
is
found which evaluates to non-\typewriter{NIL}, in which case its value is
returned immediately without further evaluation. If all \italic{ei's}
evaluate to \typewriter{NIL}, returns \typewriter{NIL}. \italic{N} may
be
zero, in which case \typewriter{NIL} is returned.}
\bold{Defined In
}\leftindent{ELI primitive.
}
______________________________________________________
\paragraph{\index{1.9.0.14
PROGN}
}______________________________________________________
\typewriter{(progn \italic{e1 e2 ... en})
}
\bold{Parameters}
\leftindent{\italic{E1} through \italic{en} may be any expressions.
}
\bold{Description}
\leftindent{Evaluates \italic{e1} through en in order, returning the
value of
\italic{en.} \italic{N} may be zero, in which case \typewriter{NIL} is
returned.}
\bold{Defined In
}\leftindent{ELI primitive.
}
\begindata{bp,539690952}
\enddata{bp,539690952}
\view{bpv,539690952,1750,0,0}
\section{1.10
Input, Output and System interface
}
______________________________________________________
\paragraph{\index{1.10.0.1
CATCHERR}
}______________________________________________________
\typewriter{(catcherr \italic{expr})
}
\bold{Parameters}
\leftindent{\italic{Expr} is any valid Lisp expression.
}
\bold{Description}
CATCHERR evaluates its argument. If the evaluation succeeds, CATCHERR
returns
a two-element list. The first element is the symbol \typewriter{T}, and
the
second is the result of evaluating \italic{expr}. If the evaluation
fails,
the list returned consists of the symbol \typewriter{NIL}, followed by a
string describing the type of error that occurred during evaluation,
followed
by a string describing the particular error in detail, followed
optionally by
a string describing giving a description of the Unix error that occurred
(if
applicable), optionally followed by the particular expression that caused
the
error (if available). If normal evaluation of \italic{expr} were to
signal an
error, CATCHERR provides a way to circumvent that error condition.
\leftindent{
}\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{Example}
\leftindent{\typewriter{(catcherr (read "foobarbaz"))} returns the list
\typewriter{(NIL "Bad Argument" "ELI-PRIMITIVE [READ (error opening
file)]"
"No such file or directory" "foobarbaz")}.
\typewriter{(catcherr (+ 1 2))} returns the list \typewriter{(T 3)}.
}
______________________________________________________
\paragraph{\index{1.10.0.2
FILTER}
}______________________________________________________
\typewriter{(filter \italic{timeout stdin command arg1 arg2 ... argn})
}
\bold{Parameters}
\leftindent{\italic{Timeout} must evaluate to an integer, \italic{stdin}
may
evaluate to \typewriter{NIL} or to a string, all other arguments must
evaluate
to strings. FILTER invokes the command \italic{command}, which must name
an
executable file. If the first character of \italic{command} is '/', then
\italic{command} is taken to be the full pathname to the executable. If
\italic{command} contains a '/' in its name but does not begin with one,
then
\italic{command} is taken to name an executable file relative to the
current
working directory. If \italic{command} contains no slashes, then FILTER
will
search the directories in the PATH environment variable to find
\italic{command}. (Note that these three modes correspond exactly to the
operation of the shell.) \italic{Arg1} through \italic{argn} are
supplied to
command as its command-line arguments, exactly one such argument per
\italic{argi}. If \italic{stdin} is non-\typewriter{NIL}, it is supplied
to
\italic{command} as its standard input. The \italic{timeout} parameter
is
optional. If present, it specifies a number of seconds to wait for
\italic{command} to complete (a \italic{timeout} of 0 means "wait
forever").
If the timeout period expires before \italic{command} completes, an
error is
signalled and \italic{command} is terminated. If \italic{timeout} is not
supplied, a default of 300 seconds (5 minutes) is used. }
\bold{Description}
\leftindent{FILTER returns a list containing the integer exit status of
\italic{command}, a string containing \italic{command}'s standard output,
and
a string containing \italic{command}'s diagnostic output (standard
error), in
that order. If the exit status is 256 or greater, then \italic{command}
exited abnormally and dumped core.}
\leftindent{
}\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{Example}
\leftindent{\typewriter{(filter "abc\\ndef\\nghi\\n" "grep" "-n" "e")}
returns
the list \typewriter{(0 "2:def" "")}. \typewriter{(filter 10 NIL "sleep"
"1000")} will time out, signalling an error (since 10 seconds elapse
before
sleep gets to sleep for 1000 seconds).}
\bold{Known Bugs}
\leftindent{Warning: Since the standard output and standard error from
command
are placed in strings in ELI's memory space, you should avoid executing
commands which are likely to produce large amounts of output, since you
will
then "eat" large amounts of memory.}
______________________________________________________
\paragraph{\index{1.10.0.3
GETENV}
}______________________________________________________
\typewriter{(getenv \italic{str})
}
\bold{Parameters}
\leftindent{\italic{Str} must evaluate to a string.
}
\bold{Description}
\leftindent{If \italic{str} is the name of an environment variable (in
the
shell), the value of this variable is returned (in a string); otherwise,
\typewriter{NIL} is returned.}
\leftindent{
}\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{Example}
\leftindent{\typewriter{(getenv "PATH")} returns something like
\typewriter{"/usr/local/bin:/usr/andrew/bin:/usr/ucb:/usr/bin"}.
that
environment variable names are typically all-upper-case.}
______________________________________________________
\paragraph{\index{1.10.0.4
LOAD}
}______________________________________________________
Note
\typewriter{(load \italic{filename})
}
\bold{Parameters}
\leftindent{\italic{Filename} must evaluate to a string.
}
\bold{Description}
\leftindent{Searches for a file whose name is \italic{filename} in the
directories listed in your \typewriter{*.elipath} preference in your
preferences file. Also, if ELI is running in some other application,
such as
FLAMES, it will first search along your \typewriter{*.flamespath}
preference.
\typewriter{LOAD} also looks for a default extension on the file name,
such
as "\typewriter{.eli}" or "\typewriter{.flames}". The return value is a
list
of the expressions it evaluated from the file it found. Returns
\typewriter{NIL} if it couldn't find an appropriate file to read.}
\leftindent{
}\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{Example}
\leftindent{If you are running BGLisp (which only uses the
\typewriter{*.elipath} preference), and your preferences file contains
the
line
\programexample{*.elipath: /afs/andrew/usr/bobg:/usr/andrew/lib/eli
}then \typewriter{(load "foo")} will try to load one of these files:
\programexample{/afs/andrew/usr/bobg/eli/foo
/afs/andrew/usr/bobg/eli/foo.eli
/usr/andrew/lib/eli/foo
/usr/andrew/lib/eli/foo.eli}
It will try each file in sequence until it finds one that exists. Then
it
will read and evaluate every Lisp expression in the file it finds. If
you are
using FLAMES, and your preferences file contains the lines
\programexample{*.elipath: /afs/andrew/usr/bobg/eli:/usr/andrew/lib/eli
*.flamespath: /afs/andrew/usr/bobg/flames:/usr/andrew/lib/flames
}then \typewriter{(load "foo")} will search this sequence of files:
\programexample{/afs/andrew/usr/bobg/flames/foo
/afs/andrew/usr/bobg/flames/foo.flames
/usr/andrew/lib/flames/foo
/usr/andrew/lib/flames/foo.flames
/afs/andrew/usr/bobg/eli/foo
/afs/andrew/usr/bobg/eli/foo.eli
/usr/andrew/lib/eli/foo
/usr/andrew/lib/eli/foo.eli
}}
______________________________________________________
\paragraph{\index{1.10.0.5
PRINT}
}______________________________________________________
\typewriter{(print \italic{e})
}
\bold{Parameters}
\leftindent{E may evaluate to any expression.
}
\bold{Description}
\leftindent{Prints \italic{e} on the standard output.
newline after \italic{e.} }
\bold{Defined In
}\leftindent{ELI primitive.
}
______________________________________________________
Does not place a
\paragraph{\index{1.10.0.6
PRINTF}
}______________________________________________________
\typewriter{(printf \italic{format arg1 arg2 ... argn})
}
\bold{Parameters}
\leftindent{\italic{Format} must evaluate to a string, \italic{arg1}
through
\italic{argn} may evaluate to any expressions provided that their types
match
the corresponding directives in \italic{format.} }
\bold{Description}
\leftindent{PRINTF prints the string \italic{format} on the standard
output,
except where a `%' directive is encountered. If the \italic{ith} `%'
directive is %s, then \italic{argi} must be a string, and is printed as
such
(minus quotation marks and \\ escapes). If the \italic{ith} `%'
directive is
%d, then \italic{argi} must be an integer, and is printed as such. If
the
\italic{ith} `%' directive is %S, then \italic{argi} may be any
expression and
is printed as with PRINT. (In this last case, strings will be printed
with
their surrounding quotation marks and \\ escapes.) Returns
\typewriter{T}.}
\leftindent{
}\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{Example}
\leftindent{If you \typewriter{(setq hrs 9)}, \typewriter{(setq mins 30)}
and
\typewriter{(setq day "Wednesday")}, then
\programexample{(printf "The time is %d:%d\\nToday is %s\\n%s\\n" hrs
mins day
"Here is a quote:\\nOprah spelled backwards is Harpo.")
}will print
\programexample{The time is 9:30
Today is Wednesday
Here is a quote:
Oprah spelled backwards is Harpo.
}}
______________________________________________________
\paragraph{\index{1.10.0.7
PUTS}
}______________________________________________________
\typewriter{(puts \italic{s})
}
\bold{Parameters}
\leftindent{\italic{S} must evaluate to a string.
}
\bold{Description}
\leftindent{Prints \italic{s} on the standard output, minus quotations
marks
and \\ escapes. Works exactly like (printf "%s" \italic{s),} except that
this
call returns the string that was printed.}
\leftindent{
}\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{Example}
\leftindent{\programexample{(puts "Here is a quote:\\n\\"Sinners can
repent
but stupid is forever.\\"\\n")
}will print
\programexample{Here is a quote:
"Sinners can repent but stupid is forever."
The string "Here is a quote:\\n\\"Sinners can repent but stupid is
forever.\\"\\n" will be returned.
}}
______________________________________________________
\paragraph{\index{1.10.0.8
READ}
}______________________________________________________
\typewriter{(read \italic{filename})
}
\bold{Parameters}
\leftindent{\italic{Filename} must evaluate to a string.
\italic{Filename}
can be omitted. }
\bold{Description}
\leftindent{If \italic{filename} is given, READ opens that file and reads
the
Lisp expressions contained therein, returning a list of the results of
evaluating each expression it read. If \italic{filename} is not given,
READ
reads and returns a single Lisp expression from the standard input. It
does
not evaluate this expression.}
\bold{Defined In
}\leftindent{ELI primitive.
}
______________________________________________________
\paragraph{\index{1.10.0.9
SYSTEM}
}______________________________________________________
\typewriter{(system \italic{str})
}
\bold{Parameters}
\leftindent{\italic{Str} must evaluate to a string.
}
\bold{Description}
\leftindent{Executes the command(s) in \italic{str} in a Unix subshell
(the
Bourne shell, not the familiar C-shell). Returns an integer which is the
status of the executed command(s).}
\leftindent{
}\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{Example}
\leftindent{\typewriter{(system "ls")} will list the files in the current
directory on the standard output, and assuming all went well, will return
\typewriter{0}, which is the return value of a successful "ls".}
______________________________________________________
\paragraph{\index{1.10.0.10 TERPRI}
}______________________________________________________
\typewriter{(terpri)
}
\bold{Parameters}
\leftindent{None}
\bold{Description}
\leftindent{Places a newline on the standard output.
"TERminate
current PRInt line".)}
\bold{Defined In
}\leftindent{ELI primitive.
(Stands for
}
\begindata{bp,539690824}
\enddata{bp,539690824}
\view{bpv,539690824,1751,0,0}
\section{1.11
Debugging
}
______________________________________________________
\paragraph{\index{1.11.0.1
DEBUG}
}______________________________________________________
\typewriter{(debug \italic{n str})
}
\bold{Parameters}
\leftindent{\italic{N} is an integer which may be omitted, \italic{str}
is a
string that may be omitted. }
\bold{Description}
\leftindent{This primitive has three different modes of operation,
depending
on what parameters are supplied.}
\description{\leftindent{Mode 1: If both \italic{n} and \italic{str} are
supplied, then DEBUG logs \italic{str} as a debugging message at
debugging
level \italic{n} (which means that \italic{str} gets logged if and only
if the
current debugging level is \italic{n} or greater). \italic{N} must be
greater
than 0. Returns \typewriter{T}.}
\leftindent{Mode 2: If only \italic{n} is supplied, then \italic{n}
becomes
the new debugging level. Zero turns off debugging, and higher numbers
represent higher levels of debugging information. Returns \italic{n}.}
\leftindent{Mode 3: If no arguments are supplied, prints all of the
debugging
messages which have been queued since the last request to print debugging
messages. Returns the "history number" of the last debugging message
printed,
or zero if none were.}}
\bold{Defined In
}\leftindent{ELI primitive.
}
______________________________________________________
\paragraph{\index{1.11.0.2
ERROR}
}______________________________________________________
\typewriter{(error \italic{str e})
}
\bold{Parameters}
\leftindent{\italic{Str} must evaluate to a string, \italic{e} may
evaluate to
any expression. }
\bold{Description}
\leftindent{This function causes an error to occur; the text of the error
message is \italic{str}. \italic{E} may be omitted; if it is supplied,
then
\italic{e} is recorded as the expression that caused the error.}
\leftindent{
}\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{Example}
\leftindent{\typewriter{(defunv foo (x) (cond ((null x) (error "Empty Arg
List
to Foo" x)) ... ))} defines a function which causes an error to occur if
it is
passed zero arguments.}
______________________________________________________
\paragraph{\index{1.11.0.3
PLUMBER}
}______________________________________________________
\typewriter{(plumber \italic{filename})
}
\bold{Parameters}
\leftindent{\italic{Filename} must evaluate to a string.
}
\bold{Description}
\leftindent{Creates the file \italic{filename} and writes cryptic memoryusage
information into it. Returns \typewriter{T}. It is an error for
\italic{filename} not to be writable or creatable. }
\bold{Defined In
}\leftindent{ELI primitive.
}
\bold{Known Bugs}
\leftindent{This primitive is definitely not needed by users.}
______________________________________________________
\paragraph{\index{1.11.0.4
VERSION}
}______________________________________________________
\typewriter{(version)
}
\bold{Parameters}
\leftindent{None.}
\bold{Description}
\leftindent{Returns a list containing two integers, which are the major
and
minor version numbers (respectively) of this version of ELI.}
\bold{Defined In
}\leftindent{ELI primitive.
}
\begindata{bp,537558784}
\enddata{bp,537558784}
\view{bpv,537558784,1753,0,0}
Copyright 1992 Carnegie Mellon University and IBM.
All rights reserved.
\smaller{\smaller{$Disclaimer:
Permission to use, copy, modify, and distribute this software and its
documentation for any purpose is hereby granted without fee,
provided that the above copyright notice appear in all copies and that
both that copyright notice, this permission notice, and the following
disclaimer appear in supporting documentation, and that the names of
IBM, Carnegie Mellon University, and other copyright holders, not be
used in advertising or publicity pertaining to distribution of the
software
without specific, written prior permission.
IBM, CARNEGIE MELLON UNIVERSITY, AND THE OTHER COPYRIGHT HOLDERS
DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS.
IN NO EVENT
SHALL IBM, CARNEGIE MELLON UNIVERSITY, OR ANY OTHER COPYRIGHT HOLDER
BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY
DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
OF THIS SOFTWARE.
$
}}\enddata{text,539466424}