LISP: *PACKAGE*
[V][CLTL 11]
SYNOPSIS:
*package*
DESCRIPTION:
The value of this variable must be a package; this package is said to be the current package. The initial value of *package* is the user package. The function load rebinds *package* to its current value. If some form in the file changes the value of *package* during loading, the old value will be restored when the loading is completed.
LISP: PACKAGE
[T]
SYNOPSIS:
package
DESCRIPTION:
This is the type specifier symbol which indicates the set of all package objects.
LISP: PACKAGE-NAME
C: PkgNm
min args: 1
max args: 1
[F][CLTL]
SYNOPSIS:
package-name package
DESCRIPTION:
The argument must be a package. This function returns the
string that names package.
Package-name
can also accept a package name or nickname, in which case the primary name of the package so specified is returned (see section 11.2).Package-name
will return nil instead of a package name if applied to a deleted package object. See delete-package.
LISP: PACKAGE-NICKNAMES
C: PkgNN
min args: 1
max args: 1
[F][CLTL]
SYNOPSIS:
package-nicknames package
DESCRIPTION:
The argument must be a package. This function returns the list of nickname strings for package, not including the primary name.
Package-nicknames
can also accept a package name or nickname, in which case the nicknames of package are returned.
LISP: PACKAGE-SHADOWING-SYMBOLS
C: PkgShadSym
min args: 1
max args: 1
[F][CLTL]
SYNOPSIS:
package-shadowing-symbols package
DESCRIPTION:
A list is returned of symbols that have been declared as shadowing symbols in package by shadow or shadowing-import. All symbols on this list are present in package.
The package argument may be either a package object or a package name.
LISP: PACKAGE-USE-LIST
C: PkgULs
min args: 1
max args: 1
[F][CLTL]
SYNOPSIS:
package-use-list package
DESCRIPTION:
A list of other packages used by the argument package is returned.
The package argument may be either a package object or a package name.
LISP: PACKAGE-USED-BY-LIST
C: LPkgUBL
min args: 1
max args: 1
[F][CLTL]
SYNOPSIS:
package-used-by-list package
DESCRIPTION:
A list of other packages that use the argument package is returned.
The package argument may be either a package object or package name.
LISP: PAIRLIS
C: Lpairlis
min args: 2
max args: 3
[F][CLTL 15]
SYNOPSIS:
pairlis keys data &optional a-list
DESCRIPTION:
pairlis
takes two lists and makes an association list that associates elements of the first list to corresponding elements of the second list. It is an error if the two lists keys and data are not of the same length. If the optional argument a-list is provided, then the new pairs are added to the front of it.The new pairs may appear in the resulting a-list in any order; in particular, either forward or backward order is permitted. Therefore the result of the call
(pairlis '(one two) '(1 2) '((three .3) (four .19)))
might be
((one . 1) (two . 2) (three . 3) (four . 19))
but one could equally well be
((two . 2) (one . 1) (three . 3) (four . 19))
LISP: PATHNAME
[Typespec]
SYNOPSIS:
pathname
DESCRIPTION:
This is the type specifier symbol which indicates the set of all pathname objects.
NOTES:
The pathname object is not supported in this implementation; pathnames are represented in most cases simply by symbols or strings whose printed representation is the full or relative DOS pathname for a file or directory. This type is supported for compatibility only.
LISP: PHASE-OF-MOON
C: POM
min args: 0
max args: 1
[F][SSCL]
SYNOPSIS:
phase-of-moon &optional universal-time
DESCRIPTION:
This function reports the current phase of the moon. If no arguments are specified, the current system time is used; if one argument is specified it considered as a date expressed in universal time. This is a Star Sapphire specific function.
There are three return values. The first is a string which briefly describes the phase of the moon for the given date; the second is the 'phase' value (a number between 1 and 0, where 1 is completely full); and the third value returned is the moon's 'age' in degrees, where 0 is new and 180 is full; for instance, 90 is waxing half, and 270 is waning half -- both of these values will be of phase 0.5.
Phase-of-moon
can be used for generating random number seeds and other non-deterministic input data.The values are accurate to within about a fifth of a degree and take into account the first three levels of correction. No attempt is made to perform the additional adjustments that would be required if a moonshot was at stake.
NOTES:
There is some archeological evidence (per Alexander Marshak) that the first calculating tools consisted of groups of scratches on bones to count lunar months. Hence the phase-of-moon feature can be considered to be the ultimate in backwards compatibility.
The phase value can be used to predict the probability of what has been termed 'POM dependencies' in the literature (of course this is a completely non-linear relationship). To summarize this extensive body of knowledge, cybernetic systems tend to produce non-deterministic results and/or will malfunction completely when the phase value exceeds ~87.999%. Care is definitely advised in this case. (:-)
BUGS:
Universal times before 1970 do not work correctly.
LISP: PI
[C][CLTL 12]
SYNOPSIS:
pi
DESCRIPTION:
This constant is initialized as part of the startup process to the value of pi.
LISP: PLUSP
C: Lplusp
min args: 1
max args: 1
[F][CLTL 12]
SYNOPSIS:
plusp number
DESCRIPTION:
This predicate is true if number is strictly greater than zero, and is false otherwise. It is an error if the argument number is not a non-complex number.
LISP: POP
[M][CLTL 15]
SYNOPSIS:
pop place
DESCRIPTION:
The form place should be the name of a generalized variable containing a list. The result of pop is the car of the contents of place, and as a side effect the cdr of the contents is stored back into place. The form place may be any form acceptable as a generalized variable to setf. If the list held in place is viewed as a push-down stack, then pop pops an element from the top of the stack and returns it.
EXAMPLES:
setq stack '(a b c))
(pop stack) => a and now stack => (b c)
The effect of (pop place) is roughly equivalent to
(prog1 (car place) (setf place (cdr place)))
except that the latter would evaluate any subforms of place three times, while pop takes care to evaluate them only once. Moreover, for certain place forms pop may be significantly more efficient than the setf version.
NOTES:
The definition for this macro is normally loaded at startup in the file defsetf.fsl. That is, in order to use this facility, you must load defsetf.fsl.
LISP: POSITION
C: Lpos
min args: 2
max args: -1
[F][CLTL 14]
SYNOPSIS:
position item sequence &key :from-end :test :test-not :start :end :key
DESCRIPTION:
If the sequence contains an element satisfying the test, then the index within the sequence of the leftmost such element is returned as a non-negative integer; otherwise nil is returned.
If :start and :end keyword arguments are given, only the specified subsequence of sequence is searched. However, the index returned is relative to the entire sequence, not to the subsequence.
If a non-nil :from-end keyword argument is specified, then the result is the index of the rightmost element satisfying the test. (The index returned, however, is an index from the left-hand end, as usual.)
LISP: POSITION-IF
C: Lposif
min args: 2
max args: -1
[F][CLTL 14]
SYNOPSIS:
position-if test sequence &key :from-end :start :end :key
DESCRIPTION:
See position.
LISP: POSITION-IF-NOT
C: Lposifn
min args: 2
max args: -1
[F][CLTL 14]
SYNOPSIS:
position-if-not test sequence &key :from-end :start :end :key
DESCRIPTION:
See position.
LISP: PPRINT
C: L_Pprint
min args: 1
max args: 2
[F][CLTL 22]
SYNOPSIS:
pprint object &optional output-stream
DESCRIPTION:
pprint
is just like print except that the trailing space is omitted and the object is printed with the *print-pretty* flag non-nil to produce "pretty" output. pprint returns no values (that is, it returns what the expression (values) returns: zero values).LISP: PRIN1
C: L_Prin1
min args: 1
max args: 2
[F][CLTL 22]
SYNOPSIS:
prin1 object &optional output-stream
DESCRIPTION:
prin1
outputs the printed representation of object to output-stream. Escape characters are used as appropriate. Roughly speaking, the output from prin1 is suitable for input to the function read. prin1 returns object.(prin1 object output-stream)
== (write object :stream output-stream :escape t)
LISP: PRINC
C: L_Princ
min args: 1
max args: 2
[F][CLTL 22]
SYNOPSIS:
princ object &optional output-stream
DESCRIPTION:
princ
is just like prin1 except that the output has no escape characters. A symbol is printed as simply the characters of its print name; a string is printed without surrounding double quotes, and there may be differences for other data types as well. The general rule is that output from princ is intended to look good to people, while output from prin1 is object.(princ object output-stream)
== (write object :stream output-stream :escape nil)intended to be acceptable to the function read. princ returns
LISP: PRINT
C: L_Print
min args: 1
max args: 2
[F][CLTL 22]
SYNOPSIS:
print object &optional output-stream
DESCRIPTION:
LISP: *PRINT-ARRAY*
[V][CLTL 22]
SYNOPSIS:
*print-array*
DESCRIPTION:
If *print-array* is nil, then the contents of arrays other than strings are never printed. Instead, arrays are printed in a concise form using #< that gives enough information for the user to be able to identify the array, but does not include the entire array contents. If print-array is not nil, non-string arrays are printed using #(, #*, or #nA syntax. The initial value of *print-array* is nil.
NOTES:
The initial value of *print-array* in Star Sapphire is t.
LISP: *PRINT-BASE*
[V][CLTL 22]
SYNOPSIS:
*print-base*
DESCRIPTION:
The value of *print-base* determines in what radix the printer will print rationals. This may be any integer from 2 to 36, inclusive. For radices above 10, letters of the alphabet are used to represent digits above 9.
The initial and default value of this variable is 10.
LISP: *PRINT-CASE*
[V][CLTL 22]
SYNOPSIS:
*print-case*
DESCRIPTION:
The read function normally converts lowercase characters appearing in symbols to corresponding uppercase characters, so that internally print names normally contain only uppercase characters. However, users may prefer to see output using lowercase letters or letters of mixed case. This variable controls the case (upper, lower, or mixed) in which to print any uppercase characters in the names of symbols when vertical-bar syntax is not used. The value of *print-case* should be one of the keywords :upcase, :downcase, or :capitalize; the initial value is :upcase.
Lowercase characters in the internal print name are always printed in lowercase, and are preceded by a single escape character or enclosed by multiple escape characters. Uppercase characters in the internal print name are printed in upper case, in lower case, or in mixed case so as to capitalize words, according to the value of *print-case*. The convention for what constitutes a "word" is the same as for the function string-capitalize.
LISP: *PRINT-ESCAPE*
[V][CLTL 22]
SYNOPSIS:
*print-escape*
DESCRIPTION:
When this flag is nil then escape characters are not output when an expression is printed. In particular, a symbol is printed by simply printing the characters of its print name. The function princ effectively binds *print-escape* to nil.
When this flag is not nil, then an attempt is made to print an expression in such a way that it can be read again to produce an equal structure. The function prin1 effectively binds *print-escape* to t. The initial value of this variable is t.
LISP: *PRINT-FUNOBJ*
[V][CLTL 22]
SYNOPSIS:
*print-funobj*
DESCRIPTION:
This Star Sapphire specific variable controls the printing of functional objects. If it is nil (the default at startup), then such objects are printed as #<FUNOBJ>. Otherwise they will be printed in their full format which can include the complete compiled code for the object. This is usually too much information; if more information while debugging, tracing, stepping is required about functional objects, then non-nil value should be assigned to *print-funobj*.
LISP: *PRINT-GENSYM*
[V][CLTL 22]
SYNOPSIS:
*print-gensym*
DESCRIPTION:
The *print-gensym* variable controls whether the prefix #: is printed before symbols that have no home package. Such is the case with symbols generated by gensym, thus the variable name.
The prefix is printed if the variable is not nil. The initial value of *print-gensym* is t.
LISP: *PRINT-LENGTH*
[V][CLTL 22]
SYNOPSIS:
*print-length*
DESCRIPTION:
The *print-length* variable controls how many elements at a given level are printed. A value of nil (the initial value) indicates that there be no limit to the number of components printed. Otherwise, the value of *print-length* should be an integer. Should the number of elements of a data object exceed the value *print-length*, the printer will print three dots, ..., in place of those elements beyond the number specified by *print-length*. (In the case of a dotted list, if the list contains exactly as many elements as the value of *print-length*, and in addition has the non-null atom terminating it, that terminating atom is printed rather than printing three dots.)
The LISP reader will normally signal an error when reading an expression that has been abbreviated because of level or length limits. This signal is given because the # dispatch character normally signals an error when followed by whitespace or ), and because ... is defined to be an illegal token, as are all tokens consisting entirely of periods (other than the single dot used in dot notation).
As an example, here are the ways the object
(if (member x y) (+ (car x) 3) '(foo . bar)))
would be printed for various values of
*print-level*=v and *print-length*=n.
v |
n |
output |
0 |
1 |
# |
1 |
1 |
(if ...) |
1 |
2 |
(if # ...) |
1 |
3 |
(if # # ...) |
1 |
4 |
(if # # #) |
2 |
1 |
(if ...) |
2 |
2 |
(if (member x ...) ...) |
2 |
3 |
(if (member x y) (+ # 3) ...) |
3 |
2 |
(if (member x ...) ...) |
3 |
3 |
(if (member x y) (+ (car x) 3) ...) |
3 |
4 |
(if (member x y) (+ (car x) 3) '(foo . bar))) |
SEE ALSO:
*print-level*
NOTES:
*print-length*
and *print-level* get accessed whenever any printing whatsoever occurs. If bound to a spurious value (not nil or a positive integer), they would produce an infinitely cascading error message (since the very act of printing the message would trigger the error again). In this case, the value is automatically reset to nil to avoid the cascade.
LISP: *PRINT-LEVEL*
[V][CLTL 22]
SYNOPSIS:
*print-level*
DESCRIPTION:
The *print-level* variable controls how many levels deep a nested list will print. If *print-level* is nil (the initial value), then no control is exercised. Otherwise, the value should be an integer, indicating the maximum level to be printed. An object to be printed is at level 0; its components (as of a list or vector) are at level 1; and so on. If an object to be recursively printed has components and is at a level equal to or greater than the value of *print-level*, then the object is printed as simply #.
SEE ALSO:
*print-length*
NOTES:
This is most useful in conjunction with (trace t), to avoid having to print out long arguments and values. To turn off the printing of arguments and values completely, try tracef.
*print-length*
and *print-level* get accessed whenever any printing whatsoever occurs. If bound to a spurious value (not nil or a positive integer), they would produce an infinitely cascading error message (since the very act of printing the message would trigger the error again). In this case, the value is automatically reset to nil to avoid the cascade.
LISP: *PRINT-PRETTY*
[V][CLTL 22]
SYNOPSIS:
*print-pretty*
DESCRIPTION:
When this flag is nil, then only a small amount of whitespace is output when printing an expression.
When this flag is not nil then the printer will insert newlines and tabs to indent list forms in a readable way. This is very useful in conjunction with dribble as long list forms will normally be dumped into the dribble file as very long lines which can choke EMACS; with *print-pretty* set to t, they can be edited.
The initial value of *print-pretty* is nil.
LISP: *PRINT-RADIX*
[V][CLTL 22]
SYNOPSIS:
*print-radix*
DESCRIPTION:
If the variable *print-radix* is non-nil, the printer will print a radix specifier to indicate the radix in which it is printing a rational number. To prevent confusion of the letter O with the digit 0, and of the letter B with the digit 8, the radix specifier is always printed using a lowercase letter.
For example, if the current base is twenty-four (decimal), the decimal integer twenty-three would print as #24rN. If *print-base* is 2, 8, or 16, then the radix specifier used is #b, #o, or #x. For integers, base ten is indicated by a trailing decimal point instead of a leading radix specifier; for ratios, however, #10r is used. The default value of *print-radix* is nil.
LISP: *PRINTER-OUTPUT*
[V][SSCL]
SYNOPSIS:
*printer-output*
DESCRIPTION:
This Star Sapphire specific stream is opened at startup to access the C file stdprn which normally gets mapped to the DOS printer device.
LISP: PROBE-FILE
C: Lprobe_file
min args: 1
max args: 1
[F][CLTL]
SYNOPSIS:
probe-file file
DESCRIPTION:
This function is used to test for the existence of a file named file.The file argument in this implementation must be a string or a symbol. The return value is nil if the file does not exist and the file name if the file does exist.
LISP: PROG
See: PROG and PROG*
LISP: PROG*
See PROG and PROG*
LISP: PROG and PROG*
C: SFCProgs
[M][CLTL 7]
SYNOPSIS:
prog r [init])}*) {declaration}* {tag | statement}*
prog* (({var | (var {var | (var[init])}*) {declaration}* {tag | statement}*
DESCRIPTION:
The prog construct is a synthesis of let, block, and tagbody, allowing bound variables and the use of return and go within a single construct. A typical prog construct looks like this:
(prog (var
1 var2 (var3 init3) var4 (var5 init5)){declaration}*
statement
1tag
1statement
2statement
3statement
4tag
2statement
5...
)
The list after the keyword prog is a set of specifications for binding var1, var2, etc., which are temporary variables bound locally to the prog. This list is processed exactly as the list in a let statement: First all the init forms are evaluated from left to right (where nil is used for any omitted init form), and then the variables are all bound in parallel to the respective results. Any declaration appearing in the prog is used as if appearing at the top of the let body.
The body of the prog is executed as if it were a tagbody construct; the go statement may be used to transfer control to a tag.
A prog implicitly establishes a block named nil around the entire prog construct, so that return may be used at any time to exit from the prog construct.
The prog construct may be explained in terms of the simpler constructs block, let, and tagbody as follows:
(prog variable-list {declaration}* . body)
== (block nil (let variable-list {declaration}* (tagbody . body)))
The prog* special form is almost the same as prog. The only difference is that the binding and initialization of the temporary variables is done sequentially, so that the init form for each one can use the values of previous ones. Therefore prog* is to prog as let* is to let. For example,
(prog* ((y z) (x (car y)))
(return x))
returns the car of the value of z.
LISP: PROGN
C: EProgn
min args: 0
max args: -1
[S][CLTL 7]
SYNOPSIS:
progn {form}*
DESCRIPTION:
The progn construct takes a number of forms and evaluates them sequentially, in order, from left to right. The values of all the forms but the last are discarded; whatever the last form returns is returned by the progn form. One says that all the forms but the last are evaluated for effect, because their execution is useful only for the side effects caused, but the last form is executed for value. progn is the primitive control structure construct for "compound statements," such as begin-end blocks in ALGOL-like languages. Many LISP constructs are "implicit progn" forms, in that as part of their syntax each allows many forms to be written that are to be evaluated sequentially, discarding the results of all forms but the last and returning the results of the last form.
If the last form of the progn returns multiple values, then those multiple values are returned by the progn form. If there are no forms for the progn, then the result is nil. These rules generally hold for implicit progn forms as well.
LISP: PROG1
C: EProg1
min args: 1
max args: -1
[M][CLTL 7]
SYNOPSIS:
prog1 first {form}*
DESCRIPTION:
prog1 is similar to progn, but it returns the value of its first form. All the argument forms are executed sequentially; the value the first form produces is saved while all the others are executed and is then returned.
prog1 is most commonly used to evaluate an expression with side effects and return a value that must be computed before the side effects happen. For example:
(prog1 (car x) (rplaca x 'foo))
alters the car of x to be foo and returns the old car of x.
prog1
always returns a single value, even if the first form tries to return multiple values. As a consequence of this, (prog1 x) and (progn x) may behave differently if x can produce multiple values. (See multiple-value-prog1.) A point of style: Although prog1 can be used to force exactly a single value to be returned, it is conventional to use the function values for this purpose.
LISP: PROG2
C: EProg2
min args: 2
max args: -1
[M][CLTL 7]
SYNOPSIS:
prog2 first second {form}*
DESCRIPTION:
prog2
is similar to prog1, but it returns the value of its second form. All the argument forms are executed sequentially; the value of the second form is saved while all the other forms are executed and is then returned. prog2 is provided mostly for historical compatibility.(prog2 a b c ... z) == (progn a (prog1 b c ... z))
Occasionally it is desirable to perform one side effect, then a value-producing operation, then another side effect. In such a peculiar case, prog2 is fairly useful. For example:
(prog2 (open-a-file) (process-the-file) (close-the-file))
;value is that of process-the-file
prog2
, like prog1, always returns a single value, even if the second form tries to return multiple values. As a consequence of this, (prog2 x y) and (progn x y) may behave differently if y can produce multiple values.
LISP: PUTHASH
C: Lputhash
min args: 3
max args: 4
[F][CLTL 13]
SYNOPSIS:
puthash key hash-table value &optional default
DESCRIPTION:
This is the setf method for gethash. The value of key in the given hash-table is altered to be value. If there is no such entry yet, one is created.
The default argument is not used; it is included so that this function's syntax is compatible with the setf definition.
In order to use puthash with setf, you must define it as the setf method using the following code which can be found in init0.lsp:
(defsetf gethash (k h &optional d) (v) `(puthash ,k ,h ,v))
If you do not, setf will produce an error which states that it cannot obtain the setf method for gethash.
LISP: PUTPROP
C: Lputprop
min args: 3
max args: 3
[F][SSCL]
SYNOPSIS:
putprop symbol value property
DESCRIPTION:
The putprop function sets property to value' for symbol returning the self-same value.
The putprop function is implemented to be the setf method for get.
Assuming that the defsetf code has been loaded, putprop can be made into get's setf method by the invocation:
(defsetf get (s p &optional d) (v) `(putprop ,s ,v ,p))
This code fragment is from init0.lsp where all the other setf methods can be found.
NOTES:
The Star Sapphire specific putprop function is based on the MACLISP function of the same name.
Although is putprop non-standard, it can be assumed that other implementations of Common LISP will have some equivalent internal function; possibly with a similar name and calling sequence.
However, code which is intended to be portable will not use this function directly, rather via setf of get.
LISP: PUSH
[M][CLTL 15]
SYNOPSIS:
push item place
DESCRIPTION:
The form place should be the name of a generalized variable containing a list; item may refer to any LISP object. The item is consed onto the front of the list, and the augmented list is stored back into place and returned. The form place may be any form acceptable as a generalized variable to setf. If the list held in place is viewed as a push-down stack, then push pushes an element onto the top of the stack. For example:
(setq x '(a b c) d))
(push 5 (cadr x)) => (5 b c) and now x => (a 5 b c) d)
The effect of (push item place) is roughly equivalent to
(setf place (cons item place))
except that the latter would evaluate any subforms of place twice, while push takes care to evaluate them only once. Moreover, for certain place forms push may be significantly more efficient than the setf version.
NOTES:
The definition for this macro is normally loaded at startup in the file defsetf.fsl. That is, in order to use this facility, you must load defsetf.fsl.
LISP: PUSHNEW
[M][CLTL 15]
SYNOPSIS:
pushnew item place &key :test :test-not :key
DESCRIPTION:
The form place should be the name of a generalized variable containing a list; item may refer to any LISP object. If the item is not already a member of the list (as determined by comparisons using :test predicate, which defaults to eql), then the item is consed onto the front of the list, and the augmented list is stored back into place and returned; otherwise the unaugmented list is returned. The form place may be any form acceptable as a generalized variable to setf. If the list held in place is viewed as a set, then pushnew adjoins an element to the set; see adjoin.
The keyword arguments to pushnew follow the conventions for the generic sequence functions. See Chapter 14. In effect, these keywords are simply passed on to the adjoin function.
pushnew returns the new contents of the place. For example:
(setq x '(a (b c) d))
(pushnew 5 (cadr x)) => (5 b c) and now x => (a (5 b c) d)
(pushnew 'b (cadr x)) => (5 b c) and x is unchanged
The effect of
(pushnew item place :test p)
is roughly equivalent to
(setf place (adjoin item place :test p))
except that the latter would evaluate any subform of place twice, while pushnew takes care to evaluate them only once. Moreover, for certain place forms pushnew may be significantly more efficient than the setf version.
NOTES:
The definition for this macro can be found in init0.lsp.