Contents|Symbol Index|Up: Chapter 24 Dictionary|Prev: compile-file-pathname|Next: with-compilation-unit

Function `load`

Syntax:

load filespec &key verbose print if-does-not-exist external-format → generalized-boolean

Arguments and Values:

!!! Need to think about "file designator" here.filespec—a stream, or a pathname designator. 23.4.0 4 The default is taken from *default-pathname-defaults*.

verbose—a generalized boolean. The default is the value of *load-verbose*.

print—a generalized boolean. The default is the value of *load-print*.

!!! Looks mighty strange to me! -kmp 26-Jun-93if-does-not-exist—a generalized boolean. The default is true.

external-format—an external file format designator. The default is :default.

generalized-boolean—a generalized boolean.

Description:

23.4.0 3load loads the file named by filespec into the Lisp environment.

The manner in which a source file is distinguished from a compiled file is implementation-dependent. If it is not possible to distinguish between a character file and a compiled file by \param{filespec},If the file specification is not complete and both a source file and a compiled file exist which might match, then which of those files load selects is implementation-dependent.

If filespec is a stream, load determines what kind of stream it is and loads directly from the stream. If filespec is a logical pathname, it is translated into a physical pathname as if by calling translate-logical-pathname.

Per X3J13 -kmp 5-Oct-93 \funref{load} evaluates each \term{form} it encounters in the file named by \param{filespec}.load sequentially executes each form it encounters in the file named by filespec. If the file is a source file and the implementation chooses to perform implicit compilation, load must recognize top level forms as described in Section 3.2.3.1 (Processing of Top Level Forms) and arrange for each top level form to be executed before beginning implicit compilation of the next. (Note, however, that processing of eval-when forms by load is controlled by the :execute situation.)

If \param{verbose} is \term{true}, \funref{load} prints a message KMP: This semicolon thing is environment stuff and not proper here. No portable program can rely on it, so it's stupid to require it. with a leading \term{semicolon} (a comment) to \term{standard output} indicating what file is being loaded and other useful information. Changed into a `suggestion' in response to gripe above. -kmp 7-Feb-92 I disagree with this change; CLtL doesn't say ``maybe''. Also look at the corresponding parameter for COMPILE-FILE. --sjl 4 Mar 92 Such information might be preceded by a leading \term{semicolon} (\eg as in a comment). Such information is preceded by a leading \term{semicolon} (\eg as in a comment).If verbose is true, load prints a message in the form of a comment (i.e., with a leading semicolon) to standard output indicating what file is being loaded and other useful information. 23.4.0 5If verbose is false, load does not print this information.

Barmar and I puzzled over this for a while and decided that it was best not to be overly constraining to implementations, since absolute conformance is hard to do in general if you're too strict. We softened the wording just slightly. -kmp 7-Feb-92If print is true, load incrementally prints information to standard output showing the progress of the loading process. For a source file, this information might mean printing the values yielded by each form in the file as soon as those values are returned. For a compiled file, what is printed might not reflect precisely the contents of the source file, but some information is generally printed. If print is false, load does not print this information.

23.4.0 6 23.4.0 7If the file named by filespec is successfully loaded, load returns true. !!! Removed for now because Sandra's comment below make it clear that this is confusing and wrong. -kmp 3-Dec-91 otherwise, \nil\ is returned or an error is signaled, depending upon the value of \param{if-does-not-exist}.

Reviewer: Loosemore: What happens if the file cannot be loaded for some reason other than that it doesn't exist? Editor: KMP: i.e., can it return NIL? must it?

If the file does not exist, the specific action taken depends on if-does-not-exist: if it is nil, load returns nil; otherwise, load signals an error.

The external-format specifies the external file format to be used when opening the file (see the function open), except that when the file named by filespec is a compiled file, the external-format is ignored. compile-file and load cooperate in an implementation-dependent way to assure the preservation of the similarity of characters referred to in the source file at the time the source file was processed by the file compiler under a given external file format, regardless of the value of external-format at the time the compiled file is loaded.

11.2.0 7 load binds *readtable* and *package* to the values they held before loading the file.

*load-truename* is bound by load to hold the truename of the pathname of the file being loaded.

*load-pathname* is bound by load to hold a pathname that represents filespec merged against the defaults. That is, (pathname (merge-pathnames filespec)).

Examples:

;Establish a data file...
 (with-open-file (str "data.in" :direction :output :if-exists :error)
   (print 1 str) (print '(setq a 888) str) t)
→ T
 (load "data.in") → true
 a → 888
 (load (setq p (merge-pathnames "data.in")) :verbose t)
; Loading contents of file /fred/data.in
; Finished loading /fred/data.in
→ true
 (load p :print t) 
; Loading contents of file /fred/data.in
;  1
;  888
; Finished loading /fred/data.in
→ true

 ;----[Begin file SETUP]----
 (in-package "MY-STUFF")
 (defmacro compile-truename () `',*compile-file-truename*)
 (defvar *my-compile-truename* (compile-truename) "Just for debugging.")
 (defvar *my-load-pathname* *load-pathname*)
 (defun load-my-system ()
   (dolist (module-name '("FOO" "BAR" "BAZ"))
     (load (merge-pathnames module-name *my-load-pathname*))))
 ;----[End of file SETUP]----

 
 (load "SETUP")
 (load-my-system)

Affected By:

The implementation, and the host computer's file system.

Exceptional Situations:

If :if-does-not-exist is supplied and is true, or is not supplied, load signals an error of type file-error if the file named by filespec does not exist, Additional constraint per x3j13 (05-Oct-93) -kmpor if the file system cannot perform the requested operation.

An error of type file-error might be signaled if (wild-pathname-p filespec) returns true.

Notes:

None.