Move some documentation from help.lsp to the files where functions are...

Move some documentation from help.lsp to the files where functions are defined. Add documentation for a few functions.
parent 6b58fb9a
......@@ -1077,7 +1077,7 @@ cl_symbols[] = {
{SYS_ "BIT-ARRAY-OP", SI_ORDINARY, si_bit_array_op, 4, OBJNULL},
{SYS_ "C-ARGUMENTS-LIMIT", SI_ORDINARY, NULL, -1, MAKE_FIXNUM(C_ARGUMENTS_LIMIT)},
{SYS_ "CHAR-SET", SI_ORDINARY, si_char_set, 3, OBJNULL},
{SYS_ "CHDIR", SI_ORDINARY, si_chdir, -1, OBJNULL},
{EXT_ "CHDIR", SI_ORDINARY, si_chdir, -1, OBJNULL},
{SYS_ "CLEAR-COMPILER-PROPERTIES", SI_ORDINARY, cl_identity, 1, OBJNULL},
{SYS_ "COERCE-TO-BASE-STRING", SI_ORDINARY, si_coerce_to_base_string, 1, OBJNULL},
{SYS_ "COERCE-TO-EXTENDED-STRING", SI_ORDINARY, si_coerce_to_extended_string, 1, OBJNULL},
......@@ -1113,8 +1113,8 @@ cl_symbols[] = {
{SYS_ "GET-LIBRARY-PATHNAME", SI_ORDINARY, si_get_library_pathname, 0, OBJNULL},
#endif
{SYS_ "GET-SYSPROP", SI_ORDINARY, si_get_sysprop, 2, OBJNULL},
{SYS_ "GETENV", SI_ORDINARY, si_getenv, 1, OBJNULL},
{SYS_ "GETCWD", SI_ORDINARY, si_getcwd, 0, OBJNULL},
{EXT_ "GETENV", SI_ORDINARY, si_getenv, 1, OBJNULL},
{EXT_ "GETCWD", SI_ORDINARY, si_getcwd, 0, OBJNULL},
{SYS_ "GETPID", SI_ORDINARY, si_getpid, 0, OBJNULL},
{SYS_ "HASH-SET", SI_ORDINARY, si_hash_set, 3, OBJNULL},
{SYS_ "HASH-TABLE-ITERATOR", SI_ORDINARY, si_hash_table_iterator, 1, OBJNULL},
......@@ -1140,7 +1140,7 @@ cl_symbols[] = {
{SYS_ "MKDIR", SI_ORDINARY, si_mkdir, 2, OBJNULL},
{SYS_ "MKSTEMP", SI_ORDINARY, si_mkstemp, 1, OBJNULL},
{SYS_ "RMDIR", SI_ORDINARY, si_rmdir, 1, OBJNULL},
{SYS_ "MAKE-PIPE", SI_ORDINARY, si_make_pipe, 0, OBJNULL},
{EXT_ "MAKE-PIPE", SI_ORDINARY, si_make_pipe, 0, OBJNULL},
{SYS_ "PACKAGE-LOCK", SI_ORDINARY, si_package_lock, 2, OBJNULL},
{SYS_ "PACKAGE-HASH-TABLES", SI_ORDINARY, si_package_hash_tables, 1, OBJNULL},
{SYS_ "PATHNAME-TRANSLATIONS", SI_ORDINARY, si_pathname_translations, -1, OBJNULL},
......@@ -1204,7 +1204,6 @@ cl_symbols[] = {
#ifndef CLOS
{SYS_ "STRUCTURE-INCLUDE", SI_ORDINARY, NULL, -1, OBJNULL},
#else
{SYS_ "CHANGE-INSTANCE", SI_ORDINARY, NULL, 4, OBJNULL},
{SYS_ "COPY-INSTANCE", SI_ORDINARY, si_copy_instance, 1, OBJNULL},
{SYS_ "GENERIC-FUNCTION-P", SI_ORDINARY, si_generic_function_p, 1, OBJNULL},
{SYS_ "INSTANCE-REF-SAFE", SI_ORDINARY, si_instance_ref_safe, 2, OBJNULL},
......
......@@ -473,6 +473,11 @@ strings."
:FORMAT-ARGUMENTS (list function-name datum)))))
(defun break (&optional (format-control "Break") &rest format-arguments)
"Enters a break loop. The execution of the program can be resumed by typing
:CONTINUE at the break loop. Type :HELP to see the break-loop commands list.
If FORMAT-STRING is non-NIL, it is used as the format string to be output to
*ERROR-OUTPUT* before entering the break loop. ARGs are arguments to the
format string."
(with-simple-restart (continue "Return from BREAK.")
(invoke-debugger
(make-condition 'SIMPLE-CONDITION
......
......@@ -486,7 +486,13 @@ static cl_object VV[VM];
(or *suppress-compiler-messages* (not *compile-verbose*)))
init-name)
(declare (notinline compiler-cc))
"Compiles the file specified by INPUT-PATHNAME and generates a fasl file
specified by OUTPUT-FILE. If the filetype is not specified in INPUT-PATHNAME,
then \".lsp\" is used as the default file type for the source file. LOAD
specifies whether to load the generated fasl file after compilation. The
:O-FILE, :C-FILE, :H-FILE, and :DATA-FILE keyword parameters allow you to
control the intermediate files generated by the ECL compiler.If the file was
compiled successfully, returns the pathname of the compiled file"
;; Deprecated, to be removed in next release
(when *suppress-compiler-notes*
(setf *suppress-compiler-messages*
......@@ -623,7 +629,18 @@ static cl_object VV[VM];
(*compile-print* nil)
(*print-pretty* nil)
(*compiler-constants* t))
"Args: (name &optional definition)
If DEFINITION is NIL, NAME must be the name of a not-yet-compiled function.
In this case, COMPILE compiles the function, installs the compiled function as
the global function definition of NAME, and returns NAME. If DEFINITION is
non-NIL, it must be a lambda expression and NAME must be a symbol. COMPILE
compiles the lambda expression, installs the compiled function as the function
definition of NAME, and returns NAME. There is only one exception for this:
If NAME is NIL, then the compiled function is not installed but is simply
returned as the value of COMPILE. In any case, COMPILE creates temporary
files, whose filenames begin with \"gazonk\", which are automatically deleted
after compilation."
(unless (symbolp name) (error "~s is not a symbol." name))
;; Deprecated, to be removed in next release
......@@ -715,6 +732,14 @@ the environment variable TMPDIR to a different value." template)
&aux def disassembled-form
(*compiler-in-use* *compiler-in-use*)
(*print-pretty* nil))
"Compiles the form specified by THING and prints the intermediate C language
code for that form. But does not install the result of compilation. If THING
is NIL, then the previously DISASSEMBLEd form is re-DISASSEMBLEd. If THING is
a symbol that names a function not yet compiled, the function definition is
disassembled. If THING is a lambda expression, it is disassembled as a
function definition. Otherwise, THING itself is disassembled as a top-level
form. H-FILE and DATA-FILE specify intermediate files to build a fasl file
from the C language code. NIL means \"do not create the file\"."
(when (si::valid-function-name-p thing)
(setq thing (fdefinition thing)))
(cond ((null thing))
......
This diff is collapsed.
......@@ -100,6 +100,11 @@ as a VARIABLE doc and can be retrieved by (documentation 'NAME 'variable)."
',var))
(defmacro defconstant (&whole whole var form &optional doc-string)
"Syntax: (defconstant symbol form [doc])
Declares that the global variable named by SYMBOL is a constant with the value
of FORM as its constant value. The doc-string DOC, if supplied, is saved as a
VARIABLE doc and can be retrieved by (DOCUMENTATION 'SYMBOL 'VARIABLE)."
`(PROGN
(SYS:*MAKE-CONSTANT ',var ,form)
,@(si::expand-set-documentation var 'variable doc-string)
......@@ -242,9 +247,15 @@ SECOND-FORM."
; multiple values
(defmacro multiple-value-list (form)
"Evaluates FORM and returns a list of all values FORM returns."
`(MULTIPLE-VALUE-CALL 'LIST ,form))
(defmacro multiple-value-setq (vars form)
"Syntax: (multiple-value-setq {var}* form)
Evaluates FORM and binds the N-th VAR to the N-th value of FORM or, if FORM
returns less than N values, to NIL. Returns the first value of FORM or, if
FORM returns no value, NIL."
(do ((vl vars (cdr vl))
(sym (gensym))
(forms nil)
......@@ -257,6 +268,11 @@ SECOND-FORM."
;; We do not use this macroexpanso, and thus we do not care whether
;; it is efficiently compiled by ECL or not.
(defmacro multiple-value-bind (vars form &rest body)
"Syntax: (multiple-value-bind ({var}*) init {decl}* {form}*)
Evaluates INIT and binds the N-th VAR to the N-th value of INIT or, if INIT
returns less than N values, to NIL. Then evaluates FORMs, and returns all
values of the last FORM. If no FORM is given, returns NIL."
`(multiple-value-call #'(lambda (&optional ,@(mapcar #'list vars)) ,@body) ,form))
(defun while-until (test body jmp-op)
......
......@@ -700,6 +700,12 @@
(list (list ,@args) ',arg-types ',ret-type ,@others))))
(defmacro definline (fun arg-types type code)
"Syntax: (definline symbol ({arg-type}*) value-type body)" "
DEFINLINE behaves like a DEFCBODY (see), but also instructs the LISP compiler
to expand inline any call to function SYMBOL into code corresponding
to the C language expression BODY, whenever it can determine that
the actual arguments are of the specified type."
`(eval-when (:compile-toplevel :load-toplevel :execute)
;; defCbody must go first, because it clears symbol-plist of fun
(defCbody ,fun ,arg-types ,type ,code)
......@@ -707,16 +713,34 @@
(def-inline ,fun :always ,arg-types ,type ,code)))
(defmacro defla (&rest body)
"Syntax: (defla name lambda-list {decl | doc}* {form}*)" "
Used to DEFine Lisp Alternative. For the interpreter, DEFLA is equivalent to
DEFUN, but the compiler ignores this form."
`(eval-when (:execute)
(defun ,@body)))
(defmacro defcbody (name arg-types result-type C-expr)
"Syntax: (defcbody symbol ({arg-type}*) value-type body)" "
The compiler defines a Lisp function named by SYMBOL whose body consists of the
C code of the string BODY. In the BODY one can reference the arguments of the
function as \"#0\", \"#1\", etc.
The interpreter ignores this form. ARG-TYPEs are argument types of the
defined Lisp function and VALUE-TYPE is its the return type."
(let ((args (mapcar #'(lambda (x) (gensym)) arg-types)))
`(defun ,name ,args
(c-inline ,args ,arg-types ,result-type
,C-expr :one-liner t))))
(defmacro defentry (name arg-types c-name)
"Syntax: (defentry symbol ({arg-type}*) (value-type function-name))
The compiler defines a Lisp function named by SYMBOL whose body consists of a
calling sequence to the C language function named by FUNCTION-NAME. The
interpreter ignores this form. ARG-TYPEs are argument types of the C function
and VALUE-TYPE is the return type of the C function. Symbols OBJECT, INT,
CHAR, CHAR*, FLOAT, DOUBLE are allowed for these types."
(let ((output-type :object)
(args (mapcar #'(lambda (x) (gensym)) arg-types)))
(if (consp c-name)
......
......@@ -115,27 +115,45 @@ otherwise."
(unless (member1 (car l) list2 test test-not key)
(return nil))))
(defun rassoc-if (pred arg &key key)
(rassoc pred arg :test #'funcall :key key))
(defun rassoc-if-not (pred arg &key key)
(rassoc pred arg :test-not #'funcall :key key))
(defun assoc-if (pred arg &key key)
(assoc pred arg :test #'funcall :key key))
(defun assoc-if-not (pred arg &key key)
(assoc pred arg :test-not #'funcall :key key))
(defun member-if (pred arg &key key)
(member pred arg :test #'funcall :key key))
(defun member-if-not (pred arg &key key)
(member pred arg :test-not #'funcall :key key))
(defun subst-if (new old where &key key)
(subst new old where :test #'funcall :key key))
(defun subst-if-not (new old where &key key)
(subst new old where :test-not #'funcall :key key))
(defun nsubst-if (new old where &key key)
(nsubst new old where :test #'funcall :key key))
(defun nsubst-if-not (new old where &key key)
(nsubst new old where :test-not #'funcall :key key))
(defun rassoc-if (test alist &key key)
"Returns the first pair in ALIST whose cdr satisfies TEST. Returns NIL if no
such pair exists."
(rassoc test alist :test #'funcall :key key))
(defun rassoc-if-not (test alist &key key)
"Returns the first pair in ALIST whose cdr does not satisfy TEST. Returns NIL
if no such pair exists."
(rassoc test alist :test-not #'funcall :key key))
(defun assoc-if (test alist &key key)
"Returns the first pair in ALIST whose car satisfies TEST. Returns NIL if no
such pair exists."
(assoc test alist :test #'funcall :key key))
(defun assoc-if-not (test alist &key key)
"Returns the first pair in ALIST whose car does not satisfy TEST. Returns NIL
if no such pair exists."
(assoc test alist :test-not #'funcall :key key))
(defun member-if (test list &key key)
"Searches LIST for an element that satisfies TEST. If found, returns the
sublist of LIST that begins with the element. If not found, returns NIL."
(member test list :test #'funcall :key key))
(defun member-if-not (test list &key key)
"Searches LIST for an element that does not satisfy TEST. If found, returns
the sublist of LIST that begins with the element. If not found, returns NIL."
(member test list :test-not #'funcall :key key))
(defun subst-if (new test tree &key key)
"Substitutes NEW for subtrees of TREE that satisfy TEST and returns the result.
The original TREE is not destroyed."
(subst new test tree :test #'funcall :key key))
(defun subst-if-not (new test tree &key key)
"Substitutes NEW for subtrees of TREE that do not satisfy TEST and returns the
result. The original TREE is not destroyed."
(subst new test tree :test-not #'funcall :key key))
(defun nsubst-if (new test tree &key key)
"Destructive SUBST-IF. TREE may be modified."
(nsubst new test tree :test #'funcall :key key))
(defun nsubst-if-not (new test tree &key key)
"Destructive SUBST-IF-NOT. TREE may be modified."
(nsubst new test tree :test-not #'funcall :key key))
......@@ -17,9 +17,9 @@
(defun load-logical-pathname-translations (host)
"Search for a logical pathname named host, if not already defined. If already
defined no attempt to find or load a definition is attempted and NIL is
returned. If host is not already defined, but definition is found and loaded
successfully, T is returned, else error."
defined no attempt to find or load a definition is attempted and NIL is
returned. If host is not already defined, but definition is found and loaded
successfully, T is returned, else error."
(declare (type string host)
(values (member t nil)))
(let ((*autoload-translations* nil))
......@@ -254,6 +254,10 @@ Sunday is the *last* day of the week!!"
(decode-universal-time (get-universal-time)))
(defun ensure-directories-exist (a-pathname &key verbose)
"Args: (ensure-directories pathname &key :verbose)
Creates tree of directories specified by the given pathname. Outputs
(VALUES pathname created)
where CREATED is true only if we succeeded on creating all directories."
(let* ((created nil)
d)
(when (or (wild-pathname-p a-pathname :directory)
......@@ -273,6 +277,12 @@ Sunday is the *last* day of the week!!"
(values a-pathname created)))
(defmacro with-hash-table-iterator ((iterator package) &body body)
"Syntax: (with-hash-table-iterator (iterator package) &body body)
Loop over the elements of a hash table. ITERATOR is a lexically bound function
that outputs three values
(VALUES entry-p key value)
ENTRY-P is true only if KEY and VALUE denote a pair of key and value of the
hash table; otherwise it signals that we have reached the end of the hash table."
`(let ((,iterator (hash-table-iterator ,package)))
(macrolet ((,iterator () (list 'funcall ',iterator)))
,@body)))
......
......@@ -21,7 +21,7 @@
(defvar *modules* ()
"This is a list of module names that have been loaded into Lisp so far.
It is used by PROVIDE and REQUIRE.")
It is used by PROVIDE and REQUIRE.")
(defvar *module-provider-functions* nil
"See function documentation for REQUIRE")
......@@ -30,7 +30,7 @@
(defun provide (module-name)
"Adds a new module name to *MODULES* indicating that it has been loaded.
Module-name is a string designator"
Module-name is a string designator"
(pushnew (string module-name) *modules* :test #'string=)
t)
......@@ -41,12 +41,12 @@
(defun require (module-name &optional pathnames)
"Loads a module, unless it already has been loaded. PATHNAMES, if supplied,
is a designator for a list of pathnames to be loaded if the module
needs to be. If PATHNAMES is not supplied, functions from the list
*MODULE-PROVIDER-FUNCTIONS* are called in order with MODULE-NAME
as an argument, until one of them returns non-NIL. User code is
responsible for calling PROVIDE to indicate a successful load of the
module."
is a designator for a list of pathnames to be loaded if the module
needs to be. If PATHNAMES is not supplied, functions from the list
*MODULE-PROVIDER-FUNCTIONS* are called in order with MODULE-NAME
as an argument, until one of them returns non-NIL. User code is
responsible for calling PROVIDE to indicate a successful load of the
module."
(let ((name (string module-name)))
(when (member name *requiring* :test #'string=)
(require-error "~@<Could not ~S ~A: circularity detected. Please check ~
......
......@@ -35,21 +35,37 @@
(/= (float 1 x) (- (float 1 x) x))))
`(eval-when (compile load eval)
(defconstant short-float-epsilon
,(binary-search #'epsilon+ (coerce 0 'short-float) (coerce 1 'short-float)))
,(binary-search #'epsilon+ (coerce 0 'short-float) (coerce 1 'short-float))
"The smallest postive short-float E that satisfies
(not (= (float 1 E) (+ (float 1 E) E)))")
(defconstant single-float-epsilon
,(binary-search #'epsilon+ (coerce 0 'single-float) (coerce 1 'single-float)))
,(binary-search #'epsilon+ (coerce 0 'single-float) (coerce 1 'single-float))
"The smallest postive single-float E that satisfies
(not (= (float 1 E) (+ (float 1 E) E)))")
(defconstant double-float-epsilon
,(binary-search #'epsilon+ (coerce 0 'double-float) (coerce 1 'double-float)))
,(binary-search #'epsilon+ (coerce 0 'double-float) (coerce 1 'double-float))
"The smallest postive double-float E that satisfies
(not (= (float 1 E) (+ (float 1 E) E)))")
(defconstant long-float-epsilon
,(binary-search #'epsilon+ (coerce 0 'long-float) (coerce 1 'long-float)))
,(binary-search #'epsilon+ (coerce 0 'long-float) (coerce 1 'long-float))
"The smallest postive long-float E that satisfies
(not (= (float 1 E) (+ (float 1 E) E)))")
(defconstant short-float-negative-epsilon
,(binary-search #'epsilon- (coerce 0 'short-float) (coerce 1 'short-float)))
,(binary-search #'epsilon- (coerce 0 'short-float) (coerce 1 'short-float))
"The smallest positive short-float E that satisfies
(not (= (float 1 E) (- (float 1 E) E)))")
(defconstant single-float-negative-epsilon
,(binary-search #'epsilon- (coerce 0 'single-float) (coerce 1 'single-float)))
,(binary-search #'epsilon- (coerce 0 'single-float) (coerce 1 'single-float))
"The smallest positive single-float E that satisfies
(not (= (float 1 E) (- (float 1 E) E)))")
(defconstant double-float-negative-epsilon
,(binary-search #'epsilon- (coerce 0 'double-float) (coerce 1 'double-float)))
,(binary-search #'epsilon- (coerce 0 'double-float) (coerce 1 'double-float))
"The smallest positive double-float E that satisfies
(not (= (float 1 E) (- (float 1 E) E)))")
(defconstant long-float-negative-epsilon
,(binary-search #'epsilon- (coerce 0 'long-float) (coerce 1 'long-float)))))
,(binary-search #'epsilon- (coerce 0 'long-float) (coerce 1 'long-float))
"The smallest positive long-float E that satisfies
(not (= (float 1 E) (- (float 1 E) E)))")))
(defconstant imag-one #C(0.0 1.0))
......
......@@ -122,8 +122,14 @@ can be represented with N bits."
'(INTEGER 0 *)
`(INTEGER 0 ,(1- (expt 2 s)))))
(deftype null () '(MEMBER NIL))
(deftype sequence () '(OR CONS NULL (ARRAY * (*))))
(deftype null ()
"The type to which only NIL belongs."
'(MEMBER NIL))
(deftype sequence ()
"A sequence is either a list or a vector."
'(OR CONS NULL (ARRAY * (*))))
(deftype list ()
"As a type specifier, LIST is used to specify the type consisting of NIL and
cons objects. In our ordinary life with Lisp, however, a list is either NIL
......@@ -160,6 +166,7 @@ may be adjustable. Other vectors are called simple-vectors."
`(array ,element-type (,size)))
(deftype extended-char ()
"A character which is not of type BASE-CHAR."
'(and character (not base-char)))
(deftype string (&optional size)
......@@ -176,8 +183,15 @@ called simple-strings."
'(or (array base-char (*)) (array character (*)))))
(deftype base-string (&optional size)
"A string which is made of BASE-CHAR."
(if size `(array base-char (,size)) '(array base-char (*))))
(deftype bit-vector (&optional size)
"A bit-vector is a vector of bits. A bit-vector is notated by '#*' followed
by its elements (0 or 1). Bit-vectors may be displaced to another array, may
have a fill-pointer, or may be adjustable. Other bit-vectors are called
simple-bit-vectors. Only simple-bit-vectors can be input in the above format
using '#*'."
(if size `(array bit (,size)) '(array bit (*))))
(deftype simple-vector (&optional size)
......@@ -199,11 +213,12 @@ fill-pointer, and is not adjustable."
'(or (simple-array base-char (*)) (simple-array character (*)))))
(deftype simple-base-string (&optional size)
"A base-string which cannot be adjusted nor displaced."
(if size `(simple-array base-char (,size)) '(simple-array base-char (*))))
(deftype simple-bit-vector (&optional size)
"A simple-bit-vector is a bit-vector that is not displaced to another array,
has no fill-pointer, and is not adjustable."
"A bit-vector that is not displaced to another array, has no fill-pointer,
and is not adjustable."
(if size `(simple-array bit (,size)) '(simple-array bit (*))))
;;************************************************************
......
......@@ -305,6 +305,10 @@ PREDICATE; NIL otherwise."
(not (apply #'every predicate sequence more-sequences)))
(defun map-into (result-sequence function &rest sequences)
"Fills the output sequence with the values returned by applying FUNCTION to the
elements of the given sequences. The i-th element of RESULT-SEQUENCE is the output
of applying FUNCTION to the i-th element of each of the sequences. The map routine
stops when it reaches the end of one of the given sequences."
(let ((nel (apply #'min (if (vectorp result-sequence)
(array-dimension result-sequence 0)
(length result-sequence))
......
......@@ -51,6 +51,10 @@ SI::ARGS."
(mapc #'trace-one r)))
(defmacro untrace (&rest r)
"Syntax: (untrace {function-name}*)
Ends tracing the specified functions. With no FUNCTION-NAMEs, ends tracing
all functions."
`(untrace* ',r))
(defun untrace* (r)
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment