3
@node System Construction, Environment, Reader, Top
4
@chapter System Construction
7
* System Construction Concepts::
8
* System Construction Dictionary::
11
@node System Construction Concepts, System Construction Dictionary, System Construction, System Construction
12
@section System Construction Concepts
14
@c including concept-systems
21
@node Loading, Features, System Construction Concepts, System Construction Concepts
24
To @b{load} a @i{file} is to treat its contents as @i{code}
25
and @i{execute} that @i{code}.
26
The @i{file} may contain @i{source code}
29
@IGindex{compiled code}
32
A @i{file} containing @i{source code} is called a @i{source file}
35
@i{Loading} a @i{source file} is accomplished essentially
36
by sequentially @i{reading}_2 the @i{forms} in the file,
37
@i{evaluating} each immediately after it is @i{read}.
39
A @i{file} containing @i{compiled code} is called a @i{compiled file}
40
@IGindex{compiled file}
42
@i{Loading} a @i{compiled file} is similar to @i{loading} a @i{source file},
43
except that the @i{file} does not contain text but rather an
44
@i{implementation-dependent} representation of pre-digested @i{expressions}
45
created by the @i{compiler}. Often, a @i{compiled file} can be @i{loaded}
46
more quickly than a @i{source file}.
47
See @ref{Compilation}.
49
The way in which a @i{source file} is distinguished from a @i{compiled file}
50
is @i{implementation-dependent}.
52
@node Features, , Loading, System Construction Concepts
57
is an aspect or attribute
59
of the @i{implementation},
60
or of the @i{environment}.
61
A @i{feature} is identified by a @i{symbol}.
63
A @i{feature} is said to be @i{present}
66
if and only if the @i{symbol} naming it is an @i{element} of the
67
@i{list} held by the @i{variable} @b{*features*},
68
which is called the @i{features list}
69
@IGindex{features list}
73
* Feature Expressions::
74
* Examples of Feature Expressions::
77
@node Feature Expressions, Examples of Feature Expressions, Features, Features
78
@subsubsection Feature Expressions
80
Boolean combinations of @i{features}, called @i{feature expressions}
81
@IGindex{feature expression}
83
are used by the @t{#+} and @t{#-} @i{reader macros} in order to
84
direct conditional @i{reading} of @i{expressions} by the @i{Lisp reader}.
86
The rules for interpreting a @i{feature expression} are as follows:
91
If a @i{symbol} naming a @i{feature} is used as a @i{feature expression},
92
the @i{feature expression} succeeds if that @i{feature} is @i{present};
95
@item @t{(not @i{feature-conditional})}
96
A @b{not} @i{feature expression} succeeds
97
if its argument @i{feature-conditional} fails;
98
otherwise, it succeeds.
100
@item @t{(and @{@i{feature-conditional}@}*)}
101
An @b{and} @i{feature expression} succeeds
102
if all of its argument @i{feature-conditionals} succeed;
105
@item @t{(or @{@i{feature-conditional}@}*)}
106
An @b{or} @i{feature expression} succeeds
107
if any of its argument @i{feature-conditionals} succeed;
112
@node Examples of Feature Expressions, , Feature Expressions, Features
113
@subsubsection Examples of Feature Expressions
115
For example, suppose that
116
in @i{implementation} A, the @i{features} @t{spice} and @t{perq} are @i{present},
117
but the @i{feature} @t{lispm} is not @i{present};
118
in @i{implementation} B, the feature @t{lispm} is @i{present},
119
but the @i{features} @t{spice} and @t{perq} are
122
in @i{implementation} C, none of the features @t{spice}, @i{lispm}, or @t{perq} are
124
Figure 24--1 shows some sample @i{expressions}, and how they would be
125
@i{read}_2 in these @i{implementations}.
130
@w{ @t{(cons #+spice "Spice" #-spice "Lispm" x)} }
131
@w{ in @i{implementation} A ... @t{(CONS "Spice" X)} }
132
@w{ in @i{implementation} B ... @t{(CONS "Lispm" X)} }
133
@w{ in @i{implementation} C ... @t{(CONS "Lispm" X)} }
134
@w{ @t{(cons #+spice "Spice" #+LispM "Lispm" x)} }
135
@w{ in @i{implementation} A ... @t{(CONS "Spice" X)} }
136
@w{ in @i{implementation} B ... @t{(CONS "Lispm" X)} }
137
@w{ in @i{implementation} C ... @t{(CONS X)} }
138
@w{ @t{(setq a '(1 2 #+perq 43 #+(not perq) 27))} }
139
@w{ in @i{implementation} A ... @t{(SETQ A '(1 2 43))} }
140
@w{ in @i{implementation} B ... @t{(SETQ A '(1 2 27))} }
141
@w{ in @i{implementation} C ... @t{(SETQ A '(1 2 27))} }
142
@w{ @t{(let ((a 3) #+(or spice lispm) (b 3)) (foo a))} }
143
@w{ in @i{implementation} A ... @t{(LET ((A 3) (B 3)) (FOO A))} }
144
@w{ in @i{implementation} B ... @t{(LET ((A 3) (B 3)) (FOO A))} }
145
@w{ in @i{implementation} C ... @t{(LET ((A 3)) (FOO A))} }
146
@w{ @t{(cons #+Lispm "#+Spice" #+Spice "foo" #-(or Lispm Spice) 7 x)} }
147
@w{ in @i{implementation} A ... @t{(CONS "foo" X)} }
148
@w{ in @i{implementation} B ... @t{(CONS "#+Spice" X)} }
149
@w{ in @i{implementation} C ... @t{(CONS 7 X)} }
152
@w{ Figure 24--1: Features examples }
157
@c end of including concept-systems
159
@node System Construction Dictionary, , System Construction Concepts, System Construction
160
@section System Construction Dictionary
162
@c including dict-system-construction
166
* compile-file-pathname::
168
* with-compilation-unit::
170
* *compile-file-pathname*::
178
@node compile-file, compile-file-pathname, System Construction Dictionary, System Construction Dictionary
179
@subsection compile-file [Function]
181
@code{compile-file} @i{input-file @r{&key} output-file verbose
182
print external-format}@*
183
@result{} @i{output-truename, warnings-p, failure-p}
185
@subsubheading Arguments and Values::
187
@i{input-file}---a @i{pathname designator}.
188
(Default fillers for unspecified components are taken from
189
@b{*default-pathname-defaults*}.)
191
@i{output-file}---a @i{pathname designator}.
192
The default is @i{implementation-defined}.
194
@i{verbose}---a @i{generalized boolean}.
195
The default is the @i{value} of @b{*compile-verbose*}.
197
@i{print}---a @i{generalized boolean}.
198
The default is the @i{value} of @b{*compile-print*}.
200
@i{external-format}---an @i{external file format designator}.
201
The default is @t{:default}.
203
@i{output-truename}---a @i{pathname} (the @b{truename} of the output @i{file}),
206
@i{warnings-p}---a @i{generalized boolean}.
208
@i{failure-p}---a @i{generalized boolean}.
210
@subsubheading Description::
212
@b{compile-file} transforms the contents of the file specified
213
by @i{input-file} into @i{implementation-dependent} binary data
214
which are placed in the file specified by @i{output-file}.
216
The @i{file} to which @i{input-file} refers should be a @i{source file}.
217
@i{output-file} can be used to specify an output @i{pathname};
219
the actual @i{pathname} of the @i{compiled file}
220
to which @i{compiled code} will be output
221
is computed as if by calling @b{compile-file-pathname}.
223
If @i{input-file} or @i{output-file} is a @i{logical pathname},
224
it is translated into a @i{physical pathname} as if by calling
225
@b{translate-logical-pathname}.
227
If @i{verbose} is @i{true},
228
@b{compile-file} prints a message in the form of a comment
229
(@i{i.e.}, with a leading @i{semicolon})
230
to @i{standard output} indicating what @i{file} is being @i{compiled}
231
and other useful information.
232
If @i{verbose} is @i{false},
233
@b{compile-file} does not print
236
If @i{print} is @i{true},
237
information about @i{top level forms} in the file being
238
compiled is printed to @i{standard output}.
239
Exactly what is printed is @i{implementation-dependent},
240
but nevertheless some information is printed.
241
If @i{print} is @b{nil}, no information is printed.
243
The @i{external-format} specifies the @i{external file format}
244
to be used when opening the @i{file}; see the @i{function} @b{open}.
245
@b{compile-file} and @b{load} must cooperate in such a way that
246
the resulting @i{compiled file} can be @i{loaded}
247
without specifying an @i{external file format} anew; see the @i{function} @b{load}.
249
@b{compile-file} binds @b{*readtable*} and @b{*package*}
250
to the values they held before processing the file.
252
@b{*compile-file-truename*} is bound by @b{compile-file}
253
to hold the @i{truename} of the @i{pathname} of the file being compiled.
255
@b{*compile-file-pathname*} is bound by @b{compile-file}
256
to hold a @i{pathname} denoted by the first argument to @b{compile-file},
257
merged against the defaults;
258
that is, @t{(pathname (merge-pathnames @i{input-file}))}.
260
The compiled @i{functions} contained in the @i{compiled file} become available
261
for use when the @i{compiled file} is @i{loaded} into Lisp.
263
Any function definition that is processed by the
264
compiler, including @t{#'(lambda ...)} forms and local function
265
definitions made by @b{flet}, @b{labels} and @b{defun} forms,
266
result in an @i{object} of @i{type} @b{compiled-function}.
268
The @i{primary value} returned by @b{compile-file}, @i{output-truename},
269
is the @b{truename} of the output file, or @b{nil} if the file could not be created.
271
The @i{secondary value}, @i{warnings-p}, is @i{false}
272
if no @i{conditions} of @i{type} @b{error} or @b{warning}
273
were detected by the compiler, and @i{true} otherwise.
275
The @i{tertiary value}, @i{failure-p}, is @i{false}
276
if no @i{conditions} of @i{type} @b{error} or @b{warning}
277
(other than @b{style-warning})
278
were detected by the compiler, and @i{true} otherwise.
280
For general information about how @i{files} are processed by the @i{file compiler},
281
see @ref{File Compilation}.
283
@i{Programs} to be compiled by the @i{file compiler} must only contain
284
@i{externalizable objects}; for details on such @i{objects},
285
see @ref{Literal Objects in Compiled Files}.
286
For information on how to extend the set of @i{externalizable objects},
287
see the @i{function} @b{make-load-form} and @ref{Additional Constraints on Externalizable Objects}.
289
@subsubheading Affected By::
293
@b{*standard-output*}, @b{*compile-verbose*}, @b{*compile-print*}
295
The computer's file system.
296
@subsubheading Exceptional Situations::
298
For information about errors detected during the compilation process,
299
see @ref{Exceptional Situations in the Compiler}.
301
An error of @i{type} @b{file-error} might be signaled if
302
@t{(wild-pathname-p @i{input-file})\/} returns true.
304
If either the attempt to open the @i{source file} for input
305
or the attempt to open the @i{compiled file} for output
307
an error of @i{type} @b{file-error} is signaled.
309
@subsubheading See Also::
317
@b{logical-pathname},
318
@ref{File System Concepts},
320
@ref{Pathnames as Filenames}
322
@node compile-file-pathname, load, compile-file, System Construction Dictionary
323
@subsection compile-file-pathname [Function]
325
@code{compile-file-pathname} @i{input-file @r{&key} output-file @r{&allow-other-keys}} @result{} @i{pathname}
327
@subsubheading Arguments and Values::
329
@i{input-file}---a @i{pathname designator}.
330
(Default fillers for unspecified components are taken from
331
@b{*default-pathname-defaults*}.)
333
@i{output-file}---a @i{pathname designator}.
334
The default is @i{implementation-defined}.
336
@i{pathname}---a @i{pathname}.
338
@subsubheading Description::
340
Returns the @i{pathname} that @b{compile-file} would write into,
341
if given the same arguments.
343
The defaults for the @i{output-file}
344
are taken from the @i{pathname}
345
that results from merging the @i{input-file}
346
with the @i{value} of @b{*default-pathname-defaults*},
347
except that the type component
348
should default to the appropriate
349
@i{implementation-defined} default type for @i{compiled files}.
351
If @i{input-file} is a @i{logical pathname} and @i{output-file}
352
is unsupplied, the result is a @i{logical pathname}.
354
If @i{input-file} is a @i{logical pathname},
355
it is translated into a physical pathname as if by calling
356
@b{translate-logical-pathname}.
358
If @i{input-file} is a @i{stream},
359
the @i{stream} can be either open or closed.
360
@b{compile-file-pathname} returns the same @i{pathname} after a
361
file is closed as it did when the file was open.
363
It is an error if @i{input-file} is a @i{stream} that is
364
created with @b{make-two-way-stream}, @b{make-echo-stream},
365
@b{make-broadcast-stream}, @b{make-concatenated-stream},
366
@b{make-string-input-stream}, @b{make-string-output-stream}.
368
If an implementation supports additional keyword arguments to @b{compile-file},
369
@b{compile-file-pathname} must accept the same arguments.
371
@subsubheading Examples::
373
See @b{logical-pathname-translations}.
375
@subsubheading Exceptional Situations::
377
An error of @i{type} @b{file-error} might be signaled if either @i{input-file} or
378
@i{output-file} is @i{wild}.
380
@subsubheading See Also::
385
@b{logical-pathname},
386
@ref{File System Concepts},
388
@ref{Pathnames as Filenames}
390
@node load, with-compilation-unit, compile-file-pathname, System Construction Dictionary
391
@subsection load [Function]
393
@code{load} @i{filespec @r{&key} verbose print
394
if-does-not-exist external-format}@*
395
@result{} @i{generalized-boolean}
397
@subsubheading Arguments and Values::
399
@i{filespec}---a @i{stream}, or a @i{pathname designator}.
400
The default is taken from @b{*default-pathname-defaults*}.
402
@i{verbose}---a @i{generalized boolean}.
403
The default is the @i{value} of @b{*load-verbose*}.
405
@i{print}---a @i{generalized boolean}.
406
The default is the @i{value} of @b{*load-print*}.
408
@i{if-does-not-exist}---a @i{generalized boolean}.
409
The default is @i{true}.
411
@i{external-format}---an @i{external file format designator}.
412
The default is @t{:default}.
414
@i{generalized-boolean}---a @i{generalized boolean}.
416
@subsubheading Description::
418
@b{load} @i{loads} the @i{file} named by @i{filespec}
419
into the @r{Lisp} environment.
421
The manner in which a @i{source file}
422
is distinguished from a @i{compiled file} is @i{implementation-dependent}.
423
If the file specification is not complete and both a @i{source file} and a
424
@i{compiled file} exist which might match,
425
then which of those files @b{load} selects is @i{implementation-dependent}.
427
If @i{filespec} is a @i{stream},
428
@b{load} determines what kind of @i{stream} it is
429
and loads directly from the @i{stream}.
431
If @i{filespec} is a @i{logical pathname},
432
it is translated into a @i{physical pathname}
433
as if by calling @b{translate-logical-pathname}.
435
@b{load} sequentially executes each @i{form} it encounters
436
in the @i{file} named by @i{filespec}.
437
If the @i{file} is a @i{source file}
438
and the @i{implementation} chooses to perform @i{implicit compilation},
439
@b{load} must recognize @i{top level forms}
440
as described in @ref{Processing of Top Level Forms}
441
and arrange for each @i{top level form} to be executed
442
before beginning @i{implicit compilation} of the next.
443
(Note, however, that processing of @b{eval-when} @i{forms}
444
by @b{load} is controlled by the @t{:execute} situation.)
446
If @i{verbose} is @i{true},
447
@b{load} prints a message in the form of a comment
448
(@i{i.e.}, with a leading @i{semicolon})
449
to @i{standard output} indicating what @i{file} is being @i{loaded}
450
and other useful information.
452
If @i{verbose} is @i{false},
453
@b{load} does not print this information.
455
If @i{print} is @i{true},
456
@b{load} incrementally prints information to @i{standard output}
457
showing the progress of the @i{loading} process.
458
For a @i{source file},
459
this information might mean printing the @i{values}
460
@i{yielded} by each @i{form} in the @i{file}
461
as soon as those @i{values} are returned.
462
For a @i{compiled file},
463
what is printed might not reflect precisely the contents of the @i{source file},
464
but some information is generally printed.
465
If @i{print} is @i{false},
466
@b{load} does not print this information.
468
If the file named by @i{filespec} is successfully loaded,
469
@b{load} returns @i{true}.
471
[Reviewer Note by Loosemore: What happens if the file cannot be loaded for some reason other
472
than that it doesn't exist?]
473
[Editorial Note by KMP: i.e., can it return NIL? must it?]
475
If the file does not exist,
476
the specific action taken depends on @i{if-does-not-exist}:
477
if it is @b{nil}, @b{load} returns @b{nil};
478
otherwise, @b{load} signals an error.
480
The @i{external-format} specifies the @i{external file format}
481
to be used when opening the @i{file} (see the @i{function} @b{open}),
482
except that when the @i{file} named by @i{filespec} is a @i{compiled file},
483
the @i{external-format} is ignored.
484
@b{compile-file} and @b{load} cooperate
485
in an @i{implementation-dependent} way to assure
486
the preservation of the @i{similarity} of @i{characters}
487
referred to in the @i{source file}
488
at the time the @i{source file} was processed by the @i{file compiler}
489
under a given @i{external file format},
490
regardless of the value of @i{external-format}
491
at the time the @i{compiled file} is @i{loaded}.
493
@b{load} binds @b{*readtable*} and @b{*package*}
494
to the values they held before @i{loading} the file.
496
@b{*load-truename*} is @i{bound} by @b{load} to hold
497
the @i{truename} of the @i{pathname} of the file being @i{loaded}.
499
@b{*load-pathname*} is @i{bound} by @b{load} to hold
500
a @i{pathname} that represents @i{filespec} merged against the defaults.
501
That is, @t{(pathname (merge-pathnames @i{filespec}))}.
503
@subsubheading Examples::
506
;Establish a data file...
507
(with-open-file (str "data.in" :direction :output :if-exists :error)
508
(print 1 str) (print '(setq a 888) str) t)
510
(load "data.in") @result{} @i{true}
512
(load (setq p (merge-pathnames "data.in")) :verbose t)
513
; Loading contents of file /fred/data.in
514
; Finished loading /fred/data.in
517
; Loading contents of file /fred/data.in
520
; Finished loading /fred/data.in
525
;----[Begin file SETUP]----
526
(in-package "MY-STUFF")
527
(defmacro compile-truename () `',*compile-file-truename*)
528
(defvar *my-compile-truename* (compile-truename) "Just for debugging.")
529
(defvar *my-load-pathname* *load-pathname*)
530
(defun load-my-system ()
531
(dolist (module-name '("FOO" "BAR" "BAZ"))
532
(load (merge-pathnames module-name *my-load-pathname*))))
533
;----[End of file SETUP]----
539
@subsubheading Affected By::
541
The implementation, and the host computer's file system.
543
@subsubheading Exceptional Situations::
545
If @t{:if-does-not-exist} is supplied and is @i{true}, or is not supplied,
546
@b{load} signals an error of @i{type} @b{file-error} if the file named by
547
@i{filespec} does not exist,
549
or if the @i{file system} cannot perform the requested operation.
551
An error of @i{type} @b{file-error} might be signaled if
552
@t{(wild-pathname-p @i{filespec})} returns @i{true}.
554
@subsubheading See Also::
558
@ref{merge-pathnames}
561
@b{*default-pathname-defaults*},
563
@b{logical-pathname},
564
@ref{File System Concepts},
566
@ref{Pathnames as Filenames}
568
@node with-compilation-unit, *features*, load, System Construction Dictionary
569
@subsection with-compilation-unit [Macro]
571
@code{with-compilation-unit} @i{@r{(}[[!@i{option}]]@r{)}
572
@{@i{form}@}*} @result{} @i{@{@i{result}@}*}
574
@w{@i{option} ::=@t{:override} override}
576
@subsubheading Arguments and Values::
578
@i{override}---a @i{generalized boolean}; evaluated.
579
The default is @b{nil}.
581
@i{forms}---an @i{implicit progn}.
583
@i{results}---the @i{values} returned by the @i{forms}.
585
@subsubheading Description::
587
Executes @i{forms} from left to right.
588
Within the @i{dynamic environment} of @b{with-compilation-unit},
589
actions deferred by the compiler until the end of compilation will be
590
deferred until the end of the outermost call to @b{with-compilation-unit}.
592
The set of @i{options} permitted may be extended by the implementation,
593
but the only @i{standardized} keyword is @t{:override}.
595
If nested dynamically only the outer call to
596
@b{with-compilation-unit} has any effect unless the value
597
associated with @t{:override} is @i{true}, in which case warnings are
598
deferred only to the end of the innermost call for which @i{override} is @i{true}.
600
The function @b{compile-file}
601
provides the effect of
604
(with-compilation-unit (:override nil) ...)
609
Any @i{implementation-dependent} extensions can only be provided as the
610
result of an explicit programmer request by use of an
611
@i{implementation-dependent} keyword. @i{Implementations} are forbidden
612
from attaching additional meaning to a use of this macro which involves either
613
no keywords or just the keyword @t{:override}.
615
@subsubheading Examples::
617
If an @i{implementation} would normally defer certain kinds of warnings,
618
such as warnings about undefined functions, to the end of a compilation
619
unit (such as a @i{file}), the following example shows how to cause those
620
warnings to be deferred to the end of the compilation of several files.
623
(defun compile-files (&rest files)
624
(with-compilation-unit ()
625
(mapcar #'(lambda (file) (compile-file file)) files)))
627
(compile-files "A" "B" "C")
630
Note however that if the implementation does not normally defer any warnings,
631
use of @i{with-compilation-unit} might not have any effect.
633
@subsubheading See Also::
639
@node *features*, *compile-file-pathname*, with-compilation-unit, System Construction Dictionary
640
@subsection *features* [Variable]
642
@subsubheading Value Type::
646
@subsubheading Initial Value::
648
@i{implementation-dependent}.
650
@subsubheading Description::
652
The @i{value} of @b{*features*} is called the @i{features list}.
653
It is a @i{list} of @i{symbols}, called @i{features},
654
that correspond to some aspect of the @i{implementation} or @i{environment}.
656
Most @i{features} have @i{implementation-dependent} meanings;
657
The following meanings have been assigned to feature names:
662
If present, indicates that the @t{LISP} @i{package} @i{purports to conform}
663
to the 1984 specification @i{Common Lisp: The Language}.
664
It is possible, but not required, for a @i{conforming implementation}
665
to have this feature because this specification specifies that
666
its @i{symbols} are to be in the @t{COMMON-LISP} @i{package},
667
not the @t{LISP} package.
670
If present, indicates that the implementation @i{purports to conform}
671
to @i{Common Lisp: The Language, Second Edition}.
672
This feature must not be present in any @i{conforming implementation},
673
since conformance to that document is not compatible with conformance
674
to this specification.
675
The name, however, is reserved by this specification in order to help
676
programs distinguish implementations which conform to that document
677
from implementations which conform to this specification.
679
@item @t{:ieee-floating-point}
680
If present, indicates that the implementation @i{purports to conform}
681
to the requirements of @i{IEEE Standard for Binary Floating-Point Arithmetic}.
684
If present, indicates that the implementation conforms to some
685
particular working draft of this specification,
686
or to some subset of features that approximates a belief about
687
what this specification might turn out to contain.
688
A @i{conforming implementation} might or might not contain
690
(This feature is intended primarily as a stopgap in order to
691
provide implementors something to use prior to the availability
692
of a draft standard, in order to discourage them from introducing
693
the @t{:draft-ansi-cl} and @t{:ansi-cl} @i{features} prematurely.)
695
@item @t{:draft-ansi-cl}
696
If present, indicates that the @i{implementation}
697
@i{purports to conform} to the first full draft of this specification,
698
which went to public review in 1992.
699
A @i{conforming implementation}
700
which has the @t{:draft-ansi-cl-2} or @t{:ansi-cl} @i{feature}
701
is not permitted to retain the @t{:draft-ansi-cl} @i{feature}
702
since incompatible changes were made subsequent to the first draft.
704
@item @t{:draft-ansi-cl-2}
705
If present, indicates that a second full draft of this specification
706
has gone to public review, and that the @i{implementation}
707
@i{purports to conform} to that specification.
708
(If additional public review drafts are produced, this keyword
709
will continue to refer to the second draft, and additional keywords
710
will be added to identify conformance with such later drafts.
711
As such, the meaning of this keyword can be relied upon not to
713
A @i{conforming implementation} which has the @t{:ansi-cl}
714
@i{feature} is only permitted to retain the @t{:draft-ansi-cl}
715
@i{feature} if the finally approved standard is not incompatible
716
with the draft standard.
719
If present, indicates that this specification has been adopted by ANSI
720
as an official standard, and that the @i{implementation}
721
@i{purports to conform}.
723
@item @t{:common-lisp}
724
This feature must appear in @b{*features*} for any implementation that
725
has one or more of the features @t{:x3j13}, @t{:draft-ansi-cl},
726
or @t{:ansi-cl}. It is intended that it should also appear in
727
implementations which have the features @t{:cltl1} or @t{:cltl2},
728
but this specification cannot force such behavior. The intent is
729
that this feature should identify the language family named ``Common Lisp,''
730
rather than some specific dialect within that family.
734
@subsubheading See Also::
736
@ref{Use of Read-Time Conditionals},
737
@ref{Standard Macro Characters}
739
@subsubheading Notes::
741
The @i{value} of @b{*features*} is used by the @t{#+} and @t{#-} reader syntax.
743
@i{Symbols} in the @i{features list} may be in any @i{package},
744
but in practice they are generally in the @t{KEYWORD} @i{package}.
745
This is because @t{KEYWORD} is the @i{package} used by default
746
when @i{reading}_2 @i{feature expressions}
747
in the @t{#+} and @t{#-} @i{reader macros}.
748
@i{Code} that needs to name a @i{feature}_2 in a
749
@i{package} P (other than @t{KEYWORD}) can do so
750
by making explicit use of a @i{package prefix} for P,
751
but note that such @i{code} must also assure that the @i{package} P
752
exists in order for the @i{feature expression} to be @i{read}_2---even
753
in cases where the @i{feature expression} is expected to fail.
755
It is generally considered wise for an @i{implementation} to include
756
one or more @i{features} identifying the specific @i{implementation},
757
so that conditional expressions can be written which distinguish
758
idiosyncrasies of one @i{implementation} from those of another.
759
Since features are normally @i{symbols} in the @t{KEYWORD} @i{package}
760
where name collisions might easily result, and since no uniquely defined mechanism
761
is designated for deciding who has the right to use which @i{symbol} for
762
what reason, a conservative strategy is to prefer names derived from
763
one's own company or product name, since those names are often trademarked
764
and are hence less likely to be used unwittingly by another @i{implementation}.
766
@node *compile-file-pathname*, *load-pathname*, *features*, System Construction Dictionary
767
@subsection *compile-file-pathname*, *compile-file-truename* [Variable]
769
@subsubheading Value Type::
771
The @i{value} of @b{*compile-file-pathname*} must always be a @i{pathname} or @b{nil}.
772
The @i{value} of @b{*compile-file-truename*} must always be a @i{physical pathname} or @b{nil}.
774
@subsubheading Initial Value::
778
@subsubheading Description::
780
During a call to @b{compile-file},
781
@b{*compile-file-pathname*} is @i{bound} to
782
the @i{pathname} denoted by the first argument to @b{compile-file},
783
merged against the defaults;
784
that is, it is @i{bound} to @t{(pathname (merge-pathnames @i{input-file}))}.
785
During the same time interval,
786
@b{*compile-file-truename*} is @i{bound} to
787
the @i{truename} of the @i{file} being @i{compiled}.
789
At other times, the @i{value} of these @i{variables} is @b{nil}.
791
If a @i{break loop} is entered while @b{compile-file} is ongoing,
792
it is @i{implementation-dependent} whether these @i{variables} retain
793
the @i{values} they had just prior to entering the @i{break loop}
794
or whether they are @i{bound} to @b{nil}.
796
The consequences are unspecified if
797
an attempt is made to @i{assign} or @i{bind} either of these @i{variables}.
799
@subsubheading Affected By::
803
@subsubheading See Also::
807
@node *load-pathname*, *compile-print*, *compile-file-pathname*, System Construction Dictionary
808
@subsection *load-pathname*, *load-truename* [Variable]
810
@subsubheading Value Type::
812
The @i{value} of @b{*load-pathname*} must always be a @i{pathname} or @b{nil}.
813
The @i{value} of @b{*load-truename*} must always be a @i{physical pathname} or @b{nil}.
815
@subsubheading Initial Value::
819
@subsubheading Description::
821
During a call to @b{load},
822
@b{*load-pathname*} is @i{bound} to
823
the @i{pathname} denoted by the the first argument to @b{load},
824
merged against the defaults;
825
that is, it is @i{bound} to @t{(pathname (merge-pathnames @i{filespec}))}.
826
During the same time interval,
827
@b{*load-truename*} is @i{bound} to
828
the @i{truename} of the @i{file} being loaded.
830
At other times, the @i{value} of these @i{variables} is @b{nil}.
832
If a @i{break loop} is entered while @b{load} is ongoing,
833
it is @i{implementation-dependent} whether these @i{variables} retain
834
the @i{values} they had just prior to entering the @i{break loop}
835
or whether they are @i{bound} to @b{nil}.
837
The consequences are unspecified if
838
an attempt is made to @i{assign} or @i{bind} either of these @i{variables}.
840
@subsubheading Affected By::
844
@subsubheading See Also::
848
@node *compile-print*, *load-print*, *load-pathname*, System Construction Dictionary
849
@subsection *compile-print*, *compile-verbose* [Variable]
851
@subsubheading Value Type::
853
a @i{generalized boolean}.
855
@subsubheading Initial Value::
857
@i{implementation-dependent}.
859
@subsubheading Description::
861
The @i{value} of @b{*compile-print*} is the default value of the @t{:print} @i{argument}
863
The @i{value} of @b{*compile-verbose*} is the default value of the @t{:verbose} @i{argument}
866
@subsubheading See Also::
870
@node *load-print*, *modules*, *compile-print*, System Construction Dictionary
871
@subsection *load-print*, *load-verbose* [Variable]
873
@subsubheading Value Type::
875
a @i{generalized boolean}.
877
@subsubheading Initial Value::
879
The initial @i{value} of @b{*load-print*} is @i{false}.
880
The initial @i{value} of @b{*load-verbose*} is @i{implementation-dependent}.
882
@subsubheading Description::
884
The @i{value} of @b{*load-print*} is the default value of the @t{:print} @i{argument} to @b{load}.
885
The @i{value} of @b{*load-verbose*} is the default value of the @t{:verbose} @i{argument} to @b{load}.
887
@subsubheading See Also::
891
@node *modules*, provide, *load-print*, System Construction Dictionary
892
@subsection *modules* [Variable]
894
@subsubheading Value Type::
896
a @i{list} of @i{strings}.
898
@subsubheading Initial Value::
900
@i{implementation-dependent}.
902
@subsubheading Description::
904
The @i{value} of @b{*modules*} is a list of names of the modules
905
that have been loaded into the current @i{Lisp image}.
907
@subsubheading Affected By::
911
@subsubheading See Also::
917
@subsubheading Notes::
919
The variable @b{*modules*} is deprecated.
921
@node provide, , *modules*, System Construction Dictionary
922
@subsection provide, require [Function]
924
@code{provide} @i{module-name} @result{} @i{@i{implementation-dependent}}
926
@code{require} @i{module-name @r{&optional} pathname-list} @result{} @i{@i{implementation-dependent}}
928
@subsubheading Arguments and Values::
930
@i{module-name}---a @i{string designator}.
932
@i{pathname-list}---@b{nil}, or
934
for a @i{non-empty} @i{list} of @i{pathname designators}.
935
The default is @b{nil}.
937
@subsubheading Description::
939
@b{provide} adds the @i{module-name} to the @i{list} held by
940
@b{*modules*}, if such a name is not already present.
942
@b{require} tests for the presence of the @i{module-name} in the
943
@i{list} held by @b{*modules*}.
944
If it is present, @b{require} immediately returns.
946
Otherwise, an attempt is made to load an appropriate set of @i{files} as follows:
947
The @i{pathname-list} argument, if @i{non-nil},
948
specifies a list of @i{pathnames} to be loaded in order, from left to right.
949
If the @i{pathname-list} is @b{nil},
950
an @i{implementation-dependent} mechanism will be invoked in an attempt
951
to load the module named @i{module-name};
952
if no such module can be loaded, an error of @i{type} @b{error} is signaled.
954
Both functions use @b{string=} to test for the presence of a @i{module-name}.
956
@subsubheading Examples::
959
;;; This illustrates a nonportable use of REQUIRE, because it
960
;;; depends on the implementation-dependent file-loading mechanism.
964
;;; This use of REQUIRE is nonportable because of the literal
965
;;; physical pathname.
967
(require "CALCULUS" "/usr/lib/lisp/calculus")
969
;;; One form of portable usage involves supplying a logical pathname,
970
;;; with appropriate translations defined elsewhere.
972
(require "CALCULUS" "lib:calculus")
974
;;; Another form of portable usage involves using a variable or
975
;;; table lookup function to determine the pathname, which again
976
;;; must be initialized elsewhere.
978
(require "CALCULUS" *calculus-module-pathname*)
981
@subsubheading Side Effects::
983
@b{provide} modifies @b{*modules*}.
985
@subsubheading Affected By::
987
The specific action taken by @b{require} is affected by calls to @b{provide}
988
(or, in general, any changes to the @i{value} of @b{*modules*}).
990
@subsubheading Exceptional Situations::
992
Should signal an error of @i{type} @b{type-error}
993
if @i{module-name} is not a @i{string designator}.
995
If @b{require} fails to perform the requested operation
996
due to a problem while interacting with the @i{file system},
997
an error of @i{type} @b{file-error} is signaled.
999
An error of @i{type} @b{file-error} might be signaled if any @i{pathname}
1000
in @i{pathname-list} is a @i{designator} for a @i{wild} @i{pathname}.
1002
@subsubheading See Also::
1006
@ref{Pathnames as Filenames}
1008
@subsubheading Notes::
1010
The functions @b{provide} and @b{require} are deprecated.
1012
If a module consists of a single @i{package},
1013
it is customary for the package and module names to be the same.
1015
@c end of including dict-system-construction
1017
@c %**end of chapter
added
removed
info/chap-24.texi
