This is gcl.info, produced by makeinfo version 6.7 from gcl.texi.

This is a Texinfo GNU Common Lisp Manual based on the draft ANSI
standard for Common Lisp.

   Copyright 1994 William F. Schelter

INFO-DIR-SECTION GNU Common Lisp
START-INFO-DIR-ENTRY
* gcl: (gcl.info). GNU Common Lisp Manual
END-INFO-DIR-ENTRY


File: gcl.info,  Node: reduce,  Next: count,  Prev: map-into,  Up: Sequences Dictionary

17.3.9 reduce [Function]
------------------------

'reduce' function sequence &key key from-end start end initial-value =>
result

Arguments and Values::
......................

function--a designator for a function that might be called with either
zero or two arguments.

   sequence--a proper sequence.

   key--a designator for a function of one argument, or nil.

   from-end--a generalized boolean.  The default is false.

   start, end--bounding index designators of sequence.  The defaults for
start and end are 0 and nil, respectively.

   initial-value--an object.

   result--an object.

Description::
.............

reduce uses a binary operation, function, to combine the elements of
sequence bounded by start and end.

   The function must accept as arguments two elements of sequence or the
results from combining those elements.  The function must also be able
to accept no arguments.

   If key is supplied, it is used is used to extract the values to
reduce.  The key function is applied exactly once to each element of
sequence in the order implied by the reduction order but not to the
value of initial-value, if supplied.

   The key function typically returns part of the element of sequence.
If key is not supplied or is nil, the sequence element itself is used.

   The reduction is left-associative, unless from-end is true in which
case it is right-associative.

   If initial-value is supplied, it is logically placed before the
subsequence (or after it if from-end is true) and included in the
reduction operation.

   In the normal case, the result of reduce is the combined result of
function's being applied to successive pairs of elements of sequence.
If the subsequence contains exactly one element and no initial-value is
given, then that element is returned and function is not called.  If the
subsequence is empty and an initial-value is given, then the
initial-value is returned and function is not called.  If the
subsequence is empty and no initial-value is given, then the function is
called with zero arguments, and reduce returns whatever function does.
This is the only case where the function is called with other than two
arguments.

Examples::
..........

      (reduce #'* '(1 2 3 4 5)) =>  120
      (reduce #'append '((1) (2)) :initial-value '(i n i t)) =>  (I N I T 1 2)
      (reduce #'append '((1) (2)) :from-end t
                                  :initial-value '(i n i t)) =>  (1 2 I N I T)
      (reduce #'- '(1 2 3 4)) == (- (- (- 1 2) 3) 4) =>  -8
      (reduce #'- '(1 2 3 4) :from-end t)    ;Alternating sum.
     == (- 1 (- 2 (- 3 4))) =>  -2
      (reduce #'+ '()) =>  0
      (reduce #'+ '(3)) =>  3
      (reduce #'+ '(foo)) =>  FOO
      (reduce #'list '(1 2 3 4)) =>  (((1 2) 3) 4)
      (reduce #'list '(1 2 3 4) :from-end t) =>  (1 (2 (3 4)))
      (reduce #'list '(1 2 3 4) :initial-value 'foo) =>  ((((foo 1) 2) 3) 4)
      (reduce #'list '(1 2 3 4)
             :from-end t :initial-value 'foo) =>  (1 (2 (3 (4 foo))))

Exceptional Situations::
........................

Should be prepared to signal an error of type type-error if sequence is
not a proper sequence.

See Also::
..........

*note Traversal Rules and Side Effects::


File: gcl.info,  Node: count,  Next: length,  Prev: reduce,  Up: Sequences Dictionary

17.3.10 count, count-if, count-if-not [Function]
------------------------------------------------

'count' item sequence &key from-end start end key test test-not => n

   'count-if' predicate sequence &key from-end start end key => n

   'count-if-not' predicate sequence &key from-end start end key => n

Arguments and Values::
......................

item--an object.

   sequence--a proper sequence.

   predicate--a designator for a function of one argument that returns a
generalized boolean.

   from-end--a generalized boolean.  The default is false.

   test--a designator for a function of two arguments that returns a
generalized boolean.

   test-not--a designator for a function of two arguments that returns a
generalized boolean.

   start, end--bounding index designators of sequence.  The defaults for
start and end are 0 and nil, respectively.

   key--a designator for a function of one argument, or nil.

   n--a non-negative integer less than or equal to the length of
sequence.

Description::
.............

count, count-if, and count-if-not count and return the number of
elements in the sequence bounded by start and end that satisfy the test.

   The from-end has no direct effect on the result.  However, if
from-end is true, the elements of sequence will be supplied as arguments
to the test, test-not, and key in reverse order, which may change the
side-effects, if any, of those functions.

Examples::
..........

      (count #\a "how many A's are there in here?") =>  2
      (count-if-not #'oddp '((1) (2) (3) (4)) :key #'car) =>  2
      (count-if #'upper-case-p "The Crying of Lot 49" :start 4) =>  2

Exceptional Situations::
........................

Should be prepared to signal an error of type type-error if sequence is
not a proper sequence.

See Also::
..........

*note Rules about Test Functions::,

   *note Traversal Rules and Side Effects::

Notes::
.......

The :test-not argument is deprecated.

   The function count-if-not is deprecated.


File: gcl.info,  Node: length,  Next: reverse,  Prev: count,  Up: Sequences Dictionary

17.3.11 length [Function]
-------------------------

'length' sequence => n

Arguments and Values::
......................

sequence--a proper sequence.

   n--a non-negative integer.

Description::
.............

Returns the number of elements in sequence.

   If sequence is a vector with a fill pointer, the active length as
specified by the fill pointer is returned.

Examples::
..........

      (length "abc") =>  3
      (setq str (make-array '(3) :element-type 'character
                                 :initial-contents "abc"
                                 :fill-pointer t)) =>  "abc"
      (length str) =>  3
      (setf (fill-pointer str) 2) =>  2
      (length str) =>  2

Exceptional Situations::
........................

Should be prepared to signal an error of type type-error if sequence is
not a proper sequence.

See Also::
..........

*note list-length:: , sequence


File: gcl.info,  Node: reverse,  Next: sort,  Prev: length,  Up: Sequences Dictionary

17.3.12 reverse, nreverse [Function]
------------------------------------

'reverse' sequence => reversed-sequence

   'nreverse' sequence => reversed-sequence

Arguments and Values::
......................

sequence--a proper sequence.

   reversed-sequence--a sequence.

Description::
.............

reverse and nreverse return a new sequence of the same kind as sequence,
containing the same elements, but in reverse order.

   reverse and nreverse differ in that reverse always creates and
returns a new sequence, whereas nreverse might modify and return the
given sequence.  reverse never modifies the given sequence.

   For reverse, if sequence is a vector, the result is a fresh simple
array of rank one that has the same actual array element type as
sequence.  If sequence is a list, the result is a fresh list.

   For nreverse, if sequence is a vector, the result is a vector that
has the same actual array element type as sequence.  If sequence is a
list, the result is a list.

   For nreverse, sequence might be destroyed and re-used to produce the
result.  The result might or might not be identical to sequence.

   Specifically, when sequence is a list, nreverse is permitted to setf
any part, car or cdr, of any cons that is part of the list structure of
sequence.  When sequence is a vector, nreverse is permitted to re-order
the elements of sequence in order to produce the resulting vector.

Examples::
..........

      (setq str "abc") =>  "abc"
      (reverse str) =>  "cba"
      str =>  "abc"
      (setq str (copy-seq str)) =>  "abc"
      (nreverse str) =>  "cba"
      str =>  implementation-dependent
      (setq l (list 1 2 3)) =>  (1 2 3)
      (nreverse l) =>  (3 2 1)
      l =>  implementation-dependent

Side Effects::
..............

nreverse might either create a new sequence, modify the argument
sequence, or both.  (reverse does not modify sequence.)

Exceptional Situations::
........................

Should be prepared to signal an error of type type-error if sequence is
not a proper sequence.


File: gcl.info,  Node: sort,  Next: find,  Prev: reverse,  Up: Sequences Dictionary

17.3.13 sort, stable-sort [Function]
------------------------------------

'sort' sequence predicate &key key => sorted-sequence

   'stable-sort' sequence predicate &key key => sorted-sequence

Arguments and Values::
......................

sequence--a proper sequence.

   predicate--a designator for a function of two arguments that returns
a generalized boolean.

   key--a designator for a function of one argument, or nil.

   sorted-sequence--a sequence.

Description::
.............

sort and stable-sort destructively sort sequences according to the order
determined by the predicate function.

   If sequence is a vector, the result is a vector that has the same
actual array element type as sequence.  The result might or might not be
simple, and might or might not be identical to sequence.  If sequence is
a list, the result is a list.

   sort determines the relationship between two elements by giving keys
extracted from the elements to the predicate.  The first argument to the
predicate function is the part of one element of sequence extracted by
the key function (if supplied); the second argument is the part of
another element of sequence extracted by the key function (if supplied).
Predicate should return true if and only if the first argument is
strictly less than the second (in some appropriate sense).  If the first
argument is greater than or equal to the second (in the appropriate
sense), then the predicate should return false.

   The argument to the key function is the sequence element.  The return
value of the key function becomes an argument to predicate.  If key is
not supplied or nil, the sequence element itself is used.  There is no
guarantee on the number of times the key will be called.

   If the key and predicate always return, then the sorting operation
will always terminate, producing a sequence containing the same elements
as sequence (that is, the result is a permutation of sequence).  This is
guaranteed even if the predicate does not really consistently represent
a total order (in which case the elements will be scrambled in some
unpredictable way, but no element will be lost).  If the key
consistently returns meaningful keys, and the predicate does reflect
some total ordering criterion on those keys, then the elements of the
sorted-sequence will be properly sorted according to that ordering.

   The sorting operation performed by sort is not guaranteed stable.
Elements considered equal by the predicate might or might not stay in
their original order.  The predicate is assumed to consider two elements
x and y to be equal if (funcall predicate x y) and (funcall predicate y
x) are both false.  stable-sort guarantees stability.

   The sorting operation can be destructive in all cases.  In the case
of a vector argument, this is accomplished by permuting the elements in
place.  In the case of a list, the list is destructively reordered in
the same manner as for nreverse.

Examples::
..........

      (setq tester (copy-seq "lkjashd")) =>  "lkjashd"
      (sort tester #'char-lessp) =>  "adhjkls"
      (setq tester (list '(1 2 3) '(4 5 6) '(7 8 9))) =>  ((1 2 3) (4 5 6) (7 8 9))
      (sort tester #'> :key #'car)  =>  ((7 8 9) (4 5 6) (1 2 3))
      (setq tester (list 1 2 3 4 5 6 7 8 9 0)) =>  (1 2 3 4 5 6 7 8 9 0)
      (stable-sort tester #'(lambda (x y) (and (oddp x) (evenp y))))
     =>  (1 3 5 7 9 2 4 6 8 0)
      (sort (setq committee-data
                  (vector (list (list "JonL" "White") "Iteration")
                          (list (list "Dick" "Waters") "Iteration")
                          (list (list "Dick" "Gabriel") "Objects")
                          (list (list "Kent" "Pitman") "Conditions")
                          (list (list "Gregor" "Kiczales") "Objects")
                          (list (list "David" "Moon") "Objects")
                          (list (list "Kathy" "Chapman") "Editorial")
                          (list (list "Larry" "Masinter") "Cleanup")
                          (list (list "Sandra" "Loosemore") "Compiler")))
            #'string-lessp :key #'cadar)
     =>  #((("Kathy" "Chapman") "Editorial")
          (("Dick" "Gabriel") "Objects")
          (("Gregor" "Kiczales") "Objects")
          (("Sandra" "Loosemore") "Compiler")
          (("Larry" "Masinter") "Cleanup")
          (("David" "Moon") "Objects")
          (("Kent" "Pitman") "Conditions")
          (("Dick" "Waters") "Iteration")
          (("JonL" "White") "Iteration"))
      ;; Note that individual alphabetical order within `committees'
      ;; is preserved.
      (setq committee-data
            (stable-sort committee-data #'string-lessp :key #'cadr))
     =>  #((("Larry" "Masinter") "Cleanup")
          (("Sandra" "Loosemore") "Compiler")
          (("Kent" "Pitman") "Conditions")
          (("Kathy" "Chapman") "Editorial")
          (("Dick" "Waters") "Iteration")
          (("JonL" "White") "Iteration")
          (("Dick" "Gabriel") "Objects")
          (("Gregor" "Kiczales") "Objects")
          (("David" "Moon") "Objects"))

Exceptional Situations::
........................

Should be prepared to signal an error of type type-error if sequence is
not a proper sequence.

See Also::
..........

*note merge:: ,

   *note Compiler Terminology::,

   *note Traversal Rules and Side Effects::,

   *note Destructive Operations::


File: gcl.info,  Node: find,  Next: position,  Prev: sort,  Up: Sequences Dictionary

17.3.14 find, find-if, find-if-not [Function]
---------------------------------------------

'find' item sequence &key from-end test test-not start end key =>
element

   'find-if' predicate sequence &key from-end start end key => element

   'find-if-not' predicate sequence &key from-end start end key =>
element

Arguments and Values::
......................

item--an object.

   sequence--a proper sequence.

   predicate--a designator for a function of one argument that returns a
generalized boolean.

   from-end--a generalized boolean.  The default is false.

   test--a designator for a function of two arguments that returns a
generalized boolean.

   test-not--a designator for a function of two arguments that returns a
generalized boolean.

   start, end--bounding index designators of sequence.  The defaults for
start and end are 0 and nil, respectively.

   key--a designator for a function of one argument, or nil.

   element--an element of the sequence, or nil.

Description::
.............

find, find-if, and find-if-not each search for an element of the
sequence bounded by start and end that satisfies the predicate predicate
or that satisfies the test test or test-not, as appropriate.

   If from-end is true, then the result is the rightmost element that
satisfies the test.

   If the sequence contains an element that satisfies the test, then the
leftmost or rightmost sequence element, depending on from-end, is
returned; otherwise nil is returned.

Examples::
..........

      (find #\d "here are some letters that can be looked at" :test #'char>)
     =>  #\Space
      (find-if #'oddp '(1 2 3 4 5) :end 3 :from-end t) =>  3
      (find-if-not #'complexp
                  '#(3.5 2 #C(1.0 0.0) #C(0.0 1.0))
                  :start 2) =>  NIL

Exceptional Situations::
........................

Should be prepared to signal an error of type type-error if sequence is
not a proper sequence.

See Also::
..........

*note position:: , *note Rules about Test Functions::,

   *note Traversal Rules and Side Effects::

Notes::
.......

The :test-not argument is deprecated.

   The function find-if-not is deprecated.


File: gcl.info,  Node: position,  Next: search,  Prev: find,  Up: Sequences Dictionary

17.3.15 position, position-if, position-if-not [Function]
---------------------------------------------------------

'position' item sequence &key from-end test test-not start end key =>
position

   'position-if' predicate sequence &key from-end start end key =>
position

   'position-if-not' predicate sequence &key from-end start end key =>
position

Arguments and Values::
......................

item--an object.

   sequence--a proper sequence.

   predicate--a designator for a function of one argument that returns a
generalized boolean.

   from-end--a generalized boolean.  The default is false.

   test--a designator for a function of two arguments that returns a
generalized boolean.

   test-not--a designator for a function of two arguments that returns a
generalized boolean.

   start, end--bounding index designators of sequence.  The defaults for
start and end are 0 and nil, respectively.

   key--a designator for a function of one argument, or nil.

   position--a bounding index of sequence, or nil.

Description::
.............

position, position-if, and position-if-not each search sequence for an
element that satisfies the test.

   The position returned is the index within sequence of the leftmost
(if from-end is true) or of the rightmost (if from-end is false) element
that satisfies the test; otherwise nil is returned.  The index returned
is relative to the left-hand end of the entire sequence, regardless of
the value of start, end, or from-end.

Examples::
..........

      (position #\a "baobab" :from-end t) =>  4
      (position-if #'oddp '((1) (2) (3) (4)) :start 1 :key #'car) =>  2
      (position 595 '()) =>  NIL
      (position-if-not #'integerp '(1 2 3 4 5.0)) =>  4

Exceptional Situations::
........................

Should be prepared to signal an error of type type-error if sequence is
not a proper sequence.

See Also::
..........

*note find:: ,

   *note Traversal Rules and Side Effects::

Notes::
.......

The :test-not argument is deprecated.

   The function position-if-not is deprecated.


File: gcl.info,  Node: search,  Next: mismatch,  Prev: position,  Up: Sequences Dictionary

17.3.16 search [Function]
-------------------------

'search' sequence-1 sequence-2 &key from-end test test-not key start1
start2 end1 end2
=> position

Arguments and Values::
......................

Sequence-1--a sequence.

   Sequence-2--a sequence.

   from-end--a generalized boolean.  The default is false.

   test--a designator for a function of two arguments that returns a
generalized boolean.

   test-not--a designator for a function of two arguments that returns a
generalized boolean.

   key--a designator for a function of one argument, or nil.

   start1, end1--bounding index designators of sequence-1.  The defaults
for start1 and end1 are 0 and nil, respectively.

   start2, end2--bounding index designators of sequence-2.  The defaults
for start2 and end2 are 0 and nil, respectively.

   position--a bounding index of sequence-2, or nil.

Description::
.............

Searches sequence-2 for a subsequence that matches sequence-1.

   The implementation may choose to search sequence-2 in any order;
there is no guarantee on the number of times the test is made.  For
example, when start-end is true, the sequence might actually be searched
from left to right instead of from right to left (but in either case
would return the rightmost matching subsequence).  If the search
succeeds, search returns the offset into sequence-2 of the first element
of the leftmost or rightmost matching subsequence, depending on
from-end; otherwise search returns nil.

   If from-end is true, the index of the leftmost element of the
rightmost matching subsequence is returned.

Examples::
..........

      (search "dog" "it's a dog's life") =>  7
      (search '(0 1) '(2 4 6 1 3 5) :key #'oddp) =>  2

See Also::
..........

*note Traversal Rules and Side Effects::

Notes::
.......

The :test-not argument is deprecated.


File: gcl.info,  Node: mismatch,  Next: replace,  Prev: search,  Up: Sequences Dictionary

17.3.17 mismatch [Function]
---------------------------

'mismatch' sequence-1 sequence-2 &key from-end test test-not key start1
start2 end1 end2
=> position

Arguments and Values::
......................

Sequence-1--a sequence.

   Sequence-2--a sequence.

   from-end--a generalized boolean.  The default is false.

   test--a designator for a function of two arguments that returns a
generalized boolean.

   test-not--a designator for a function of two arguments that returns a
generalized boolean.

   start1, end1--bounding index designators of sequence-1.  The defaults
for start1 and end1 are 0 and nil, respectively.

   start2, end2--bounding index designators of sequence-2.  The defaults
for start2 and end2 are 0 and nil, respectively.

   key--a designator for a function of one argument, or nil.

   position--a bounding index of sequence-1, or nil.

Description::
.............

The specified subsequences of sequence-1 and sequence-2 are compared
element-wise.

   The key argument is used for both the sequence-1 and the sequence-2.

   If sequence-1 and sequence-2 are of equal length and match in every
element, the result is false.  Otherwise, the result is a non-negative
integer, the index within sequence-1 of the leftmost or rightmost
position, depending on from-end, at which the two subsequences fail to
match.  If one subsequence is shorter than and a matching prefix of the
other, the result is the index relative to sequence-1 beyond the last
position tested.

   If from-end is true, then one plus the index of the rightmost
position in which the sequences differ is returned.  In effect, the
subsequences are aligned at their right-hand ends; then, the last
elements are compared, the penultimate elements, and so on.  The index
returned is an index relative to sequence-1.

Examples::
..........

      (mismatch "abcd" "ABCDE" :test #'char-equal) =>  4
      (mismatch '(3 2 1 1 2 3) '(1 2 3) :from-end t) =>  3
      (mismatch '(1 2 3) '(2 3 4) :test-not #'eq :key #'oddp) =>  NIL
      (mismatch '(1 2 3 4 5 6) '(3 4 5 6 7) :start1 2 :end2 4) =>  NIL

See Also::
..........

*note Traversal Rules and Side Effects::

Notes::
.......

The :test-not argument is deprecated.


File: gcl.info,  Node: replace,  Next: substitute,  Prev: mismatch,  Up: Sequences Dictionary

17.3.18 replace [Function]
--------------------------

'replace' sequence-1 sequence-2 &key start1 end1 start2 end2 =>
sequence-1

Arguments and Values::
......................

sequence-1--a sequence.

   sequence-2--a sequence.

   start1, end1--bounding index designators of sequence-1.  The defaults
for start1 and end1 are 0 and nil, respectively.

   start2, end2--bounding index designators of sequence-2.  The defaults
for start2 and end2 are 0 and nil, respectively.

Description::
.............

Destructively modifies sequence-1 by replacing the elements of
subsequence-1 bounded by start1 and end1 with the elements of
subsequence-2 bounded by start2 and end2.

   Sequence-1 is destructively modified by copying successive elements
into it from sequence-2.  Elements of the subsequence of sequence-2
bounded by start2 and end2 are copied into the subsequence of sequence-1
bounded by start1 and end1.  If these subsequences are not of the same
length, then the shorter length determines how many elements are copied;
the extra elements near the end of the longer subsequence are not
involved in the operation.  The number of elements copied can be
expressed as:

      (min (- end1 start1) (- end2 start2))

   If sequence-1 and sequence-2 are the same object and the region being
modified overlaps the region being copied from, then it is as if the
entire source region were copied to another place and only then copied
back into the target region.  However, if sequence-1 and sequence-2 are
not the same, but the region being modified overlaps the region being
copied from (perhaps because of shared list structure or displaced
arrays), then after the replace operation the subsequence of sequence-1
being modified will have unpredictable contents.  It is an error if the
elements of sequence-2 are not of a type that can be stored into
sequence-1.

Examples::
..........

      (replace "abcdefghij" "0123456789" :start1 4 :end1 7 :start2 4)
     =>  "abcd456hij"
      (setq lst "012345678") =>  "012345678"
      (replace lst lst :start1 2 :start2 0) =>  "010123456"
      lst =>  "010123456"

Side Effects::
..............

The sequence-1 is modified.

See Also::
..........

*note fill::


File: gcl.info,  Node: substitute,  Next: concatenate,  Prev: replace,  Up: Sequences Dictionary

17.3.19 substitute, substitute-if, substitute-if-not,
-----------------------------------------------------

nsubstitute, nsubstitute-if, nsubstitute-if-not
-----------------------------------------------

                                                             [Function]

   'substitute' newitem olditem sequence &key from-end test test-not
start end count key
=> result-sequence

   'substitute-if' newitem predicate sequence &key from-end start end
count key
=> result-sequence

   'substitute-if-not' newitem predicate sequence &key from-end start
end count key
=> result-sequence

   'nsubstitute' newitem olditem sequence &key from-end test test-not
start end count key
=> sequence

   'nsubstitute-if' newitem predicate sequence &key from-end start end
count key
=> sequence

   'nsubstitute-if-not' newitem predicate sequence &key from-end start
end count key
=> sequence

Arguments and Values::
......................

newitem--an object.

   olditem--an object.

   sequence--a proper sequence.

   predicate--a designator for a function of one argument that returns a
generalized boolean.

   from-end--a generalized boolean.  The default is false.

   test--a designator for a function of two arguments that returns a
generalized boolean.

   test-not--a designator for a function of two arguments that returns a
generalized boolean.

   start, end--bounding index designators of sequence.  The defaults for
start and end are 0 and nil, respectively.

   count--an integer or nil.

   The default is nil.

   key--a designator for a function of one argument, or nil.

   result-sequence--a sequence.

Description::
.............

substitute, substitute-if, and substitute-if-not return a copy of
sequence in which each element that satisfies the test has been replaced
with newitem.

   nsubstitute, nsubstitute-if, and nsubstitute-if-not are like
substitute, substitute-if, and substitute-if-not respectively, but they
may modify sequence.

   If sequence is a vector, the result is a vector that has the same
actual array element type as sequence.  The result might or might not be
simple, and might or might not be identical to sequence.  If sequence is
a list, the result is a list.

   Count, if supplied, limits the number of elements altered; if more
than count elements satisfy the test, then of these elements only the
leftmost or rightmost, depending on from-end, are replaced, as many as
specified by count.

   If count is supplied and negative, the behavior is as if zero had
been supplied instead.

   If count is nil, all matching items are affected.

   Supplying a from-end of true matters only when the count is provided
(and non-nil); in that case, only the rightmost count elements
satisfying the test are removed (instead of the leftmost).

   predicate, test, and test-not might be called more than once for each
sequence element, and their side effects can happen in any order.

   The result of all these functions is a sequence of the same type as
sequence that has the same elements except that those in the subsequence
bounded by start and end and satisfying the test have been replaced by
newitem.

   substitute, substitute-if, and substitute-if-not return a sequence
which can share with sequence or may be identical to the input sequence
if no elements need to be changed.

   nsubstitute and nsubstitute-if are required to setf any car (if
sequence is a list) or aref (if sequence is a vector) of sequence that
is required to be replaced with newitem.  If sequence is a list, none of
the cdrs of the top-level list can be modified.

Examples::
..........

      (substitute #\. #\SPACE "0 2 4 6") =>  "0.2.4.6"
      (substitute 9 4 '(1 2 4 1 3 4 5)) =>  (1 2 9 1 3 9 5)
      (substitute 9 4 '(1 2 4 1 3 4 5) :count 1) =>  (1 2 9 1 3 4 5)
      (substitute 9 4 '(1 2 4 1 3 4 5) :count 1 :from-end t)
     =>  (1 2 4 1 3 9 5)
      (substitute 9 3 '(1 2 4 1 3 4 5) :test #'>) =>  (9 9 4 9 3 4 5)

      (substitute-if 0 #'evenp '((1) (2) (3) (4)) :start 2 :key #'car)
     =>  ((1) (2) (3) 0)
      (substitute-if 9 #'oddp '(1 2 4 1 3 4 5)) =>  (9 2 4 9 9 4 9)
      (substitute-if 9 #'evenp '(1 2 4 1 3 4 5) :count 1 :from-end t)
     =>  (1 2 4 1 3 9 5)

      (setq some-things (list 'a 'car 'b 'cdr 'c)) =>  (A CAR B CDR C)
      (nsubstitute-if "function was here" #'fboundp some-things
                      :count 1 :from-end t) =>  (A CAR B "function was here" C)
      some-things =>  (A CAR B "function was here" C)
      (setq alpha-tester (copy-seq "ab ")) =>  "ab "
      (nsubstitute-if-not #\z #'alpha-char-p alpha-tester) =>  "abz"
      alpha-tester =>  "abz"

Side Effects::
..............

nsubstitute, nsubstitute-if, and nsubstitute-if-not modify sequence.

Exceptional Situations::
........................

Should be prepared to signal an error of type type-error if sequence is
not a proper sequence.

See Also::
..........

*note subst:: , nsubst,

   *note Compiler Terminology::,

   *note Traversal Rules and Side Effects::

Notes::
.......

The :test-not argument is deprecated.

   The functions substitute-if-not and nsubstitute-if-not are
deprecated.

   nsubstitute and nsubstitute-if can be used in for-effect-only
positions in code.

   Because the side-effecting variants (e.g., nsubstitute) potentially
change the path that is being traversed, their effects in the presence
of shared or circular structure may vary in surprising ways when
compared to their non-side-effecting alternatives.  To see this,
consider the following side-effect behavior, which might be exhibited by
some implementations:

      (defun test-it (fn)
        (let ((x (cons 'b nil)))
          (rplacd x x)
          (funcall fn 'a 'b x :count 1)))
      (test-it #'substitute) =>  (A . #1=(B . #1#))
      (test-it #'nsubstitute) =>  (A . #1#)


File: gcl.info,  Node: concatenate,  Next: merge,  Prev: substitute,  Up: Sequences Dictionary

17.3.20 concatenate [Function]
------------------------------

'concatenate' result-type &rest sequences => result-sequence

Arguments and Values::
......................

result-type--a sequence type specifier.

   sequences--a sequence.

   result-sequence--a proper sequence of type result-type.

Description::
.............

concatenate returns a sequence that contains all the individual elements
of all the sequences in the order that they are supplied.  The sequence
is of type result-type, which must be a subtype of type sequence.

   All of the sequences are copied from; the result does not share any
structure with any of the sequences.  Therefore, if only one sequence is
provided and it is of type result-type, concatenate is required to copy
sequence rather than simply returning it.

   It is an error if any element of the sequences cannot be an element
of the sequence result.

   [Reviewer Note by Barmar: Should signal?]

   If the result-type is a subtype of list, the result will be a list.

   If the result-type is a subtype of vector, then if the implementation
can determine the element type specified for the result-type, the
element type of the resulting array is the result of upgrading that
element type; or, if the implementation can determine that the element
type is unspecified (or *), the element type of the resulting array is
t; otherwise, an error is signaled.

Examples::
..........

     (concatenate 'string "all" " " "together" " " "now") =>  "all together now"
     (concatenate 'list "ABC" '(d e f) #(1 2 3) #*1011)
     =>  (#\A #\B #\C D E F 1 2 3 1 0 1 1)
     (concatenate 'list) =>  NIL

       (concatenate '(vector * 2) "a" "bc") should signal an error

Exceptional Situations::
........................

An error is signaled if the result-type is neither a recognizable
subtype of list, nor a recognizable subtype of vector.

   An error of type type-error should be signaled if result-type
specifies the number of elements and the sum of sequences is different
from that number.

See Also::
..........

*note append::


File: gcl.info,  Node: merge,  Next: remove,  Prev: concatenate,  Up: Sequences Dictionary

17.3.21 merge [Function]
------------------------

'merge' result-type sequence-1 sequence-2 predicate &key key =>
result-sequence

Arguments and Values::
......................

result-type--a sequence type specifier.

   sequence-1--a sequence.

   sequence-2--a sequence.

   predicate--a designator for a function of two arguments that returns
a generalized boolean.

   key--a designator for a function of one argument, or nil.

   result-sequence--a proper sequence of type result-type.

Description::
.............

Destructively merges sequence-1 with sequence-2 according to an order
determined by the predicate.  merge determines the relationship between
two elements by giving keys extracted from the sequence elements to the
predicate.

   The first argument to the predicate function is an element of
sequence-1 as returned by the key (if supplied); the second argument is
an element of sequence-2 as returned by the key (if supplied).
Predicate should return true if and only if its first argument is
strictly less than the second (in some appropriate sense).  If the first
argument is greater than or equal to the second (in the appropriate
sense), then predicate should return false.  merge considers two
elements x and y to be equal if (funcall predicate x y) and (funcall
predicate y x) both yield false.

   The argument to the key is the sequence element.  Typically, the
return value of the key becomes the argument to predicate.  If key is
not supplied or nil, the sequence element itself is used.  The key may
be executed more than once for each sequence element, and its side
effects may occur in any order.

   If key and predicate return, then the merging operation will
terminate.  The result of merging two sequences x and y is a new
sequence of type result-type z, such that the length of z is the sum of
the lengths of x and y, and z contains all the elements of x and y.  If
x1 and x2 are two elements of x, and x1 precedes x2 in x, then x1
precedes x2 in z, and similarly for elements of y.  In short, z is an
interleaving of x and y.

   If x and y were correctly sorted according to the predicate, then z
will also be correctly sorted.  If x or y is not so sorted, then z will
not be sorted, but will nevertheless be an interleaving of x and y.

   The merging operation is guaranteed stable; if two or more elements
are considered equal by the predicate, then the elements from sequence-1
will precede those from sequence-2 in the result.

   sequence-1 and/or sequence-2 may be destroyed.

   If the result-type is a subtype of list, the result will be a list.

   If the result-type is a subtype of vector, then if the implementation
can determine the element type specified for the result-type, the
element type of the resulting array is the result of upgrading that
element type; or, if the implementation can determine that the element
type is unspecified (or *), the element type of the resulting array is
t; otherwise, an error is signaled.

Examples::
..........

      (setq test1 (list 1 3 4 6 7))
      (setq test2 (list 2 5 8))
      (merge 'list test1 test2 #'<) =>  (1 2 3 4 5 6 7 8)
      (setq test1 (copy-seq "BOY"))
      (setq test2 (copy-seq :nosy"))
      (merge 'string test1 test2 #'char-lessp) =>  "BnOosYy"
      (setq test1 (vector ((red . 1) (blue . 4))))
      (setq test2 (vector ((yellow . 2) (green . 7))))
      (merge 'vector test1 test2 #'< :key #'cdr)
     =>  #((RED . 1) (YELLOW . 2) (BLUE . 4) (GREEN . 7))

      (merge '(vector * 4) '(1 5) '(2 4 6) #'<) should signal an error

Exceptional Situations::
........................

An error must be signaled if the result-type is neither a recognizable
subtype of list, nor a recognizable subtype of vector.

   An error of type type-error should be signaled if result-type
specifies the number of elements and the sum of the lengths of
sequence-1 and sequence-2 is different from that number.

See Also::
..........

*note sort:: , stable-sort,

   *note Compiler Terminology::,

   *note Traversal Rules and Side Effects::


File: gcl.info,  Node: remove,  Next: remove-duplicates,  Prev: merge,  Up: Sequences Dictionary

17.3.22 remove, remove-if, remove-if-not,
-----------------------------------------

delete, delete-if, delete-if-not
--------------------------------

                                                             [Function]

   'remove' item sequence &key from-end test test-not start end count
key => result-sequence

   'remove-if' test sequence &key from-end start end count key =>
result-sequence

   'remove-if-not' test sequence &key from-end start end count key =>
result-sequence

   'delete' item sequence &key from-end test test-not start end count
key => result-sequence

   'delete-if' test sequence &key from-end start end count key =>
result-sequence

   'delete-if-not' test sequence &key from-end start end count key =>
result-sequence

Arguments and Values::
......................

item--an object.

   sequence--a proper sequence.

   test--a designator for a function of one argument that returns a
generalized boolean.

   from-end--a generalized boolean.  The default is false.

   test--a designator for a function of two arguments that returns a
generalized boolean.

   test-not--a designator for a function of two arguments that returns a
generalized boolean.

   start, end--bounding index designators of sequence.  The defaults for
start and end are 0 and nil, respectively.

   count--an integer or nil.

   The default is nil.

   key--a designator for a function of one argument, or nil.

   result-sequence--a sequence.

Description::
.............

remove, remove-if, and remove-if-not return a sequence from which the
elements that satisfy the test have been removed.

   delete, delete-if, and delete-if-not are like remove, remove-if, and
remove-if-not respectively, but they may modify sequence.

   If sequence is a vector, the result is a vector that has the same
actual array element type as sequence.  The result might or might not be
simple, and might or might not be identical to sequence.  If sequence is
a list, the result is a list.

   Supplying a from-end of true matters only when the count is provided;
in that case only the rightmost count elements satisfying the test are
deleted.

   Count, if supplied, limits the number of elements removed or deleted;
if more than count elements satisfy the test, then of these elements
only the leftmost or rightmost, depending on from-end, are deleted or
removed, as many as specified by count.

   If count is supplied and negative, the behavior is as if zero had
been supplied instead.

   If count is nil, all matching items are affected.

   For all these functions, elements not removed or deleted occur in the
same order in the result as they did in sequence.

   remove, remove-if, remove-if-not return a sequence of the same type
as sequence that has the same elements except that those in the
subsequence bounded by start and end and satisfying the test have been
removed.  This is a non-destructive operation.  If any elements need to
be removed, the result will be a copy.  The result of remove may share
with sequence; the result may be identical to the input sequence if no
elements need to be removed.

   delete, delete-if, and delete-if-not return a sequence of the same
type as sequence that has the same elements except that those in the
subsequence bounded by start and end and satisfying the test have been
deleted.  Sequence may be destroyed and used to construct the result;
however, the result might or might not be identical to sequence.

   delete, when sequence is a list, is permitted to setf any part, car
or cdr, of the top-level list structure in that sequence.  When sequence
is a vector, delete is permitted to change the dimensions of the vector
and to slide its elements into new positions without permuting them to
produce the resulting vector.

   delete-if is constrained to behave exactly as follows:

      (delete nil sequence
                  :test #'(lambda (ignore item) (funcall test item))
                  ...)

Examples::
..........

      (remove 4 '(1 3 4 5 9)) =>  (1 3 5 9)
      (remove 4 '(1 2 4 1 3 4 5)) =>  (1 2 1 3 5)
      (remove 4 '(1 2 4 1 3 4 5) :count 1) =>  (1 2 1 3 4 5)
      (remove 4 '(1 2 4 1 3 4 5) :count 1 :from-end t) =>  (1 2 4 1 3 5)
      (remove 3 '(1 2 4 1 3 4 5) :test #'>) =>  (4 3 4 5)
      (setq lst '(list of four elements)) =>  (LIST OF FOUR ELEMENTS)
      (setq lst2 (copy-seq lst)) =>  (LIST OF FOUR ELEMENTS)
      (setq lst3 (delete 'four lst)) =>  (LIST OF ELEMENTS)
      (equal lst lst2) =>  false
      (remove-if #'oddp '(1 2 4 1 3 4 5)) =>  (2 4 4)
      (remove-if #'evenp '(1 2 4 1 3 4 5) :count 1 :from-end t)
     =>  (1 2 4 1 3 5)
      (remove-if-not #'evenp '(1 2 3 4 5 6 7 8 9) :count 2 :from-end t)
     =>  (1 2 3 4 5 6 8)
      (setq tester (list 1 2 4 1 3 4 5)) =>  (1 2 4 1 3 4 5)
      (delete 4 tester) =>  (1 2 1 3 5)
      (setq tester (list 1 2 4 1 3 4 5)) =>  (1 2 4 1 3 4 5)
      (delete 4 tester :count 1) =>  (1 2 1 3 4 5)
      (setq tester (list 1 2 4 1 3 4 5)) =>  (1 2 4 1 3 4 5)
      (delete 4 tester :count 1 :from-end t) =>  (1 2 4 1 3 5)
      (setq tester (list 1 2 4 1 3 4 5)) =>  (1 2 4 1 3 4 5)
      (delete 3 tester :test #'>) =>  (4 3 4 5)
      (setq tester (list 1 2 4 1 3 4 5)) =>  (1 2 4 1 3 4 5)
      (delete-if #'oddp tester) =>  (2 4 4)
      (setq tester (list 1 2 4 1 3 4 5)) =>  (1 2 4 1 3 4 5)
      (delete-if #'evenp tester :count 1 :from-end t) =>  (1 2 4 1 3 5)
      (setq tester (list 1 2 3 4 5 6)) =>  (1 2 3 4 5 6)
      (delete-if #'evenp tester) =>  (1 3 5)
      tester =>  implementation-dependent

      (setq foo (list 'a 'b 'c)) =>  (A B C)
      (setq bar (cdr foo)) =>  (B C)
      (setq foo (delete 'b foo)) =>  (A C)
      bar =>  ((C)) or ...
      (eq (cdr foo) (car bar)) =>  T or ...

Side Effects::
..............

For delete, delete-if, and delete-if-not, sequence may be destroyed and
used to construct the result.

Exceptional Situations::
........................

Should be prepared to signal an error of type type-error if sequence is
not a proper sequence.

See Also::
..........

*note Compiler Terminology::,

   *note Traversal Rules and Side Effects::

Notes::
.......

The :test-not argument is deprecated.

   The functions delete-if-not and remove-if-not are deprecated.


File: gcl.info,  Node: remove-duplicates,  Prev: remove,  Up: Sequences Dictionary

17.3.23 remove-duplicates, delete-duplicates [Function]
-------------------------------------------------------

'remove-duplicates' sequence &key from-end test test-not start end key
=> result-sequence

   'delete-duplicates' sequence &key from-end test test-not start end
key
=> result-sequence

Arguments and Values::
......................

sequence--a proper sequence.

   from-end--a generalized boolean.  The default is false.

   test--a designator for a function of two arguments that returns a
generalized boolean.

   test-not--a designator for a function of two arguments that returns a
generalized boolean.

   start, end--bounding index designators of sequence.  The defaults for
start and end are 0 and nil, respectively.

   key--a designator for a function of one argument, or nil.

   result-sequence--a sequence.

Description::
.............

remove-duplicates returns a modified copy of sequence from which any
element that matches another element occurring in sequence has been
removed.

   If sequence is a vector, the result is a vector that has the same
actual array element type as sequence.  The result might or might not be
simple, and might or might not be identical to sequence.  If sequence is
a list, the result is a list.

   delete-duplicates is like remove-duplicates, but delete-duplicates
may modify sequence.

   The elements of sequence are compared pairwise, and if any two match,
then the one occurring earlier in sequence is discarded, unless from-end
is true, in which case the one later in sequence is discarded.

   remove-duplicates and delete-duplicates return a sequence of the same
type as sequence with enough elements removed so that no two of the
remaining elements match.  The order of the elements remaining in the
result is the same as the order in which they appear in sequence.

   remove-duplicates returns a sequence that may share with sequence or
may be identical to sequence if no elements need to be removed.

   delete-duplicates, when sequence is a list, is permitted to setf any
part, car or cdr, of the top-level list structure in that sequence.
When sequence is a vector, delete-duplicates is permitted to change the
dimensions of the vector and to slide its elements into new positions
without permuting them to produce the resulting vector.

Examples::
..........

      (remove-duplicates "aBcDAbCd" :test #'char-equal :from-end t) =>  "aBcD"
      (remove-duplicates '(a b c b d d e)) =>  (A C B D E)
      (remove-duplicates '(a b c b d d e) :from-end t) =>  (A B C D E)
      (remove-duplicates '((foo #\a) (bar #\%) (baz #\A))
          :test #'char-equal :key #'cadr) =>  ((BAR #\%) (BAZ #\A))
      (remove-duplicates '((foo #\a) (bar #\%) (baz #\A))
          :test #'char-equal :key #'cadr :from-end t) =>  ((FOO #\a) (BAR #\%))
      (setq tester (list 0 1 2 3 4 5 6))
      (delete-duplicates tester :key #'oddp :start 1 :end 6) =>  (0 4 5 6)

Side Effects::
..............

delete-duplicates might destructively modify sequence.

Exceptional Situations::
........................

Should signal an error of type type-error if sequence is not a proper
sequence.

See Also::
..........

*note Compiler Terminology::,

   *note Traversal Rules and Side Effects::

Notes::
.......

The :test-not argument is deprecated.

   These functions are useful for converting sequence into a canonical
form suitable for representing a set.


File: gcl.info,  Node: Hash Tables,  Next: Filenames,  Prev: Sequences,  Up: Top

18 Hash Tables
**************

* Menu:

* Hash Table Concepts::
* Hash Tables Dictionary::


File: gcl.info,  Node: Hash Table Concepts,  Next: Hash Tables Dictionary,  Prev: Hash Tables,  Up: Hash Tables

18.1 Hash Table Concepts
========================

* Menu:

* Hash-Table Operations::
* Modifying Hash Table Keys::


File: gcl.info,  Node: Hash-Table Operations,  Next: Modifying Hash Table Keys,  Prev: Hash Table Concepts,  Up: Hash Table Concepts

18.1.1 Hash-Table Operations
----------------------------

Figure 18-1 lists some defined names that are applicable to hash tables.
The following rules apply to hash tables.

-
     A hash table can only associate one value with a given key.  If an
     attempt is made to add a second value for a given key, the second
     value will replace the first.  Thus, adding a value to a hash table
     is a destructive operation; the hash table is modified.

-
     There are four kinds of hash tables: those whose keys are compared
     with eq, those whose keys are compared with eql, those whose keys
     are compared with equal, and

     those whose keys are compared with equalp.

-
     Hash tables are created by make-hash-table.  gethash is used to
     look up a key and find the associated value.  New entries are added
     to hash tables using setf with gethash.  remhash is used to remove
     an entry.  For example:

           (setq a (make-hash-table)) =>  #<HASH-TABLE EQL 0/120 32536573>
           (setf (gethash 'color a) 'brown) =>  BROWN
           (setf (gethash 'name a) 'fred) =>  FRED
           (gethash 'color a) =>  BROWN, true
           (gethash 'name a) =>  FRED, true
           (gethash 'pointy a) =>  NIL, false

     In this example, the symbols color and name are being used as keys,
     and the symbols brown and fred are being used as the associated
     values.  The hash table has two items in it, one of which
     associates from color to brown, and the other of which associates
     from name to fred.

-
     A key or a value may be any object.

-
     The existence of an entry in the hash table can be determined from
     the secondary value returned by gethash.

  clrhash           hash-table-p     remhash  
  gethash           make-hash-table  sxhash   
  hash-table-count  maphash                   

     Figure 18-1: Hash-table defined names   



File: gcl.info,  Node: Modifying Hash Table Keys,  Prev: Hash-Table Operations,  Up: Hash Table Concepts

18.1.2 Modifying Hash Table Keys
--------------------------------

The function supplied as the :test argument to make-hash-table specifies
the 'equivalence test' for the hash table it creates.

   An object is 'visibly modified' with regard to an equivalence test if
there exists some set of objects (or potential objects) which are
equivalent to the object before the modification but are no longer
equivalent afterwards.

   If an object O_1 is used as a key in a hash table H and is then
visibly modified with regard to the equivalence test of H, then the
consequences are unspecified if O_1, or any object O_2 equivalent to O_1
under the equivalence test (either before or after the modification), is
used as a key in further operations on H. The consequences of using O_1
as a key are unspecified even if O_1 is visibly modified and then later
modified again in such a way as to undo the visible modification.

   Following are specifications of the modifications which are visible
to the equivalence tests which must be supported by hash tables.  The
modifications are described in terms of modification of components, and
are defined recursively.  Visible modifications of components of the
object are visible modifications of the object.

* Menu:

* Visible Modification of Objects with respect to EQ and EQL::
* Visible Modification of Objects with respect to EQUAL::
* Visible Modification of Conses with respect to EQUAL::
* Visible Modification of Bit Vectors and Strings with respect to EQUAL::
* Visible Modification of Objects with respect to EQUALP::
* Visible Modification of Structures with respect to EQUALP::
* Visible Modification of Arrays with respect to EQUALP::
* Visible Modification of Hash Tables with respect to EQUALP::
* Visible Modifications by Language Extensions::


File: gcl.info,  Node: Visible Modification of Objects with respect to EQ and EQL,  Next: Visible Modification of Objects with respect to EQUAL,  Prev: Modifying Hash Table Keys,  Up: Modifying Hash Table Keys

18.1.2.1 Visible Modification of Objects with respect to EQ and EQL
...................................................................

No standardized function is provided that is capable of visibly
modifying an object with regard to eq or eql.


File: gcl.info,  Node: Visible Modification of Objects with respect to EQUAL,  Next: Visible Modification of Conses with respect to EQUAL,  Prev: Visible Modification of Objects with respect to EQ and EQL,  Up: Modifying Hash Table Keys

18.1.2.2 Visible Modification of Objects with respect to EQUAL
..............................................................

As a consequence of the behavior for equal, the rules for visible
modification of objects not explicitly mentioned in this section are
inherited from those in *note Visible Modification of Objects with
respect to EQ and EQL::.


File: gcl.info,  Node: Visible Modification of Conses with respect to EQUAL,  Next: Visible Modification of Bit Vectors and Strings with respect to EQUAL,  Prev: Visible Modification of Objects with respect to EQUAL,  Up: Modifying Hash Table Keys

18.1.2.3 Visible Modification of Conses with respect to EQUAL
.............................................................

Any visible change to the car or the cdr of a cons is considered a
visible modification with regard to equal.


File: gcl.info,  Node: Visible Modification of Bit Vectors and Strings with respect to EQUAL,  Next: Visible Modification of Objects with respect to EQUALP,  Prev: Visible Modification of Conses with respect to EQUAL,  Up: Modifying Hash Table Keys

18.1.2.4 Visible Modification of Bit Vectors and Strings with respect to EQUAL
..............................................................................

For a vector of type bit-vector or of type string, any visible change to
an active element of the vector, or to the length of the vector (if it
is actually adjustable or has a fill pointer) is considered a visible
modification with regard to equal.


File: gcl.info,  Node: Visible Modification of Objects with respect to EQUALP,  Next: Visible Modification of Structures with respect to EQUALP,  Prev: Visible Modification of Bit Vectors and Strings with respect to EQUAL,  Up: Modifying Hash Table Keys

18.1.2.5 Visible Modification of Objects with respect to EQUALP
...............................................................

As a consequence of the behavior for equalp, the rules for visible
modification of objects not explicitly mentioned in this section are
inherited from those in *note Visible Modification of Objects with
respect to EQUAL::.


File: gcl.info,  Node: Visible Modification of Structures with respect to EQUALP,  Next: Visible Modification of Arrays with respect to EQUALP,  Prev: Visible Modification of Objects with respect to EQUALP,  Up: Modifying Hash Table Keys

18.1.2.6 Visible Modification of Structures with respect to EQUALP
..................................................................

Any visible change to a slot of a structure is considered a visible
modification with regard to equalp.


File: gcl.info,  Node: Visible Modification of Arrays with respect to EQUALP,  Next: Visible Modification of Hash Tables with respect to EQUALP,  Prev: Visible Modification of Structures with respect to EQUALP,  Up: Modifying Hash Table Keys

18.1.2.7 Visible Modification of Arrays with respect to EQUALP
..............................................................

In an array, any visible change to an active element, to the fill
pointer (if the array can and does have one), or to the dimensions (if
the array is actually adjustable) is considered a visible modification
with regard to equalp.


File: gcl.info,  Node: Visible Modification of Hash Tables with respect to EQUALP,  Next: Visible Modifications by Language Extensions,  Prev: Visible Modification of Arrays with respect to EQUALP,  Up: Modifying Hash Table Keys

18.1.2.8 Visible Modification of Hash Tables with respect to EQUALP
...................................................................

In a hash table, any visible change to the count of entries in the hash
table, to the keys, or to the values associated with the keys is
considered a visible modification with regard to equalp.

   Note that the visibility of modifications to the keys depends on the
equivalence test of the hash table, not on the specification of equalp.


File: gcl.info,  Node: Visible Modifications by Language Extensions,  Prev: Visible Modification of Hash Tables with respect to EQUALP,  Up: Modifying Hash Table Keys

18.1.2.9 Visible Modifications by Language Extensions
.....................................................

Implementations that extend the language by providing additional mutator
functions (or additional behavior for existing mutator functions) must
document how the use of these extensions interacts with equivalence
tests and hash table searches.

   Implementations that extend the language by defining additional
acceptable equivalence tests for hash tables (allowing additional values
for the :test argument to make-hash-table) must document the visible
components of these tests.


File: gcl.info,  Node: Hash Tables Dictionary,  Prev: Hash Table Concepts,  Up: Hash Tables

18.2 Hash Tables Dictionary
===========================

* Menu:

* hash-table::
* make-hash-table::
* hash-table-p::
* hash-table-count::
* hash-table-rehash-size::
* hash-table-rehash-threshold::
* hash-table-size::
* hash-table-test::
* gethash::
* remhash::
* maphash::
* with-hash-table-iterator::
* clrhash::
* sxhash::


File: gcl.info,  Node: hash-table,  Next: make-hash-table,  Prev: Hash Tables Dictionary,  Up: Hash Tables Dictionary

18.2.1 hash-table [System Class]
--------------------------------

Class Precedence List::
.......................

hash-table, t

Description::
.............

Hash tables provide a way of mapping any object (a key) to an associated
object (a value).

See Also::
..........

*note Hash Table Concepts::, *note Printing Other Objects::

Notes::
.......

The intent is that this mapping be implemented by a hashing mechanism,
such as that described in Section 6.4 "Hashing" of The Art of Computer
Programming, Volume 3 (pp506-549).  In spite of this intent, no
conforming implementation is required to use any particular technique to
implement the mapping.


File: gcl.info,  Node: make-hash-table,  Next: hash-table-p,  Prev: hash-table,  Up: Hash Tables Dictionary

18.2.2 make-hash-table [Function]
---------------------------------

'make-hash-table' &key test size rehash-size rehash-threshold =>
hash-table

Arguments and Values::
......................

test--a designator for one of the functions eq, eql, equal, or

   equalp.

   The default is eql.

   size--a non-negative integer.

   The default is implementation-dependent.

   rehash-size--a real of type (or (integer 1 *) (float (1.0) *)).  The
default is implementation-dependent.

   rehash-threshold--a real of type (real 0 1).  The default is
implementation-dependent.

   hash-table--a hash table.

Description::
.............

Creates and returns a new hash table.

   test determines how keys are compared.  An object is said to be
present in the hash-table if that object is the same under the test as
the key for some entry in the hash-table.

   size is a hint to the implementation about how much initial space to
allocate in the hash-table.

   This information, taken together with the rehash-threshold, controls
the approximate number of entries which it should be possible to insert
before the table has to grow.

   The actual size might be rounded up from size to the next 'good'
size; for example, some implementations might round to the next prime
number.

   rehash-size specifies a minimum amount to increase the size of the
hash-table when it becomes full enough to require rehashing; see
rehash-theshold below.

   If rehash-size is an integer, the expected growth rate for the table
is additive and the integer is the number of entries to add; if it is a
float, the expected growth rate for the table is multiplicative and the
float is the ratio of the new size to the old size.

   As with size, the actual size of the increase might be rounded up.

   rehash-threshold specifies how full the hash-table can get before it
must grow.

   It specifies the maximum desired hash-table occupancy level.

   The values of rehash-size and rehash-threshold do not constrain the
implementation to use any particular method for computing when and by
how much the size of hash-table should be enlarged.  Such decisions are
implementation-dependent, and these values only hints from the
programmer to the implementation, and the implementation is permitted to
ignore them.

Examples::
..........

      (setq table (make-hash-table)) =>  #<HASH-TABLE EQL 0/120 46142754>
      (setf (gethash "one" table) 1) =>  1
      (gethash "one" table) =>  NIL, false
      (setq table (make-hash-table :test 'equal)) =>  #<HASH-TABLE EQUAL 0/139 46145547>
      (setf (gethash "one" table) 1) =>  1
      (gethash "one" table) =>  1, T
      (make-hash-table :rehash-size 1.5 :rehash-threshold 0.7)
     =>  #<HASH-TABLE EQL 0/120 46156620>

See Also::
..........

*note gethash:: , hash-table


File: gcl.info,  Node: hash-table-p,  Next: hash-table-count,  Prev: make-hash-table,  Up: Hash Tables Dictionary

18.2.3 hash-table-p [Function]
------------------------------

'hash-table-p' object => generalized-boolean

Arguments and Values::
......................

object--an object.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if object is of type hash-table; otherwise, returns false.

Examples::
..........

      (setq table (make-hash-table)) =>  #<HASH-TABLE EQL 0/120 32511220>
      (hash-table-p table) =>  true
      (hash-table-p 37) =>  false
      (hash-table-p '((a . 1) (b . 2))) =>  false

Notes::
.......

      (hash-table-p object) == (typep object 'hash-table)


File: gcl.info,  Node: hash-table-count,  Next: hash-table-rehash-size,  Prev: hash-table-p,  Up: Hash Tables Dictionary

18.2.4 hash-table-count [Function]
----------------------------------

'hash-table-count' hash-table => count

Arguments and Values::
......................

hash-table--a hash table.

   count--a non-negative integer.

Description::
.............

Returns the number of entries in the hash-table.  If hash-table has just
been created or newly cleared (see clrhash) the entry count is 0.

Examples::
..........

      (setq table (make-hash-table)) =>  #<HASH-TABLE EQL 0/120 32115135>
      (hash-table-count table) =>  0
      (setf (gethash 57 table) "fifty-seven") =>  "fifty-seven"
      (hash-table-count table) =>  1
      (dotimes (i 100) (setf (gethash i table) i)) =>  NIL
      (hash-table-count table) =>  100

Affected By::
.............

clrhash, remhash, setf of gethash

See Also::
..........

*note hash-table-size::

Notes::
.......

The following relationships are functionally correct, although in
practice using hash-table-count is probably much faster:

      (hash-table-count table) ==
      (loop for value being the hash-values of table count t) ==
      (let ((total 0))
        (maphash #'(lambda (key value)
                     (declare (ignore key value))
                     (incf total))
                 table)
        total)


File: gcl.info,  Node: hash-table-rehash-size,  Next: hash-table-rehash-threshold,  Prev: hash-table-count,  Up: Hash Tables Dictionary

18.2.5 hash-table-rehash-size [Function]
----------------------------------------

'hash-table-rehash-size' hash-table => rehash-size

Arguments and Values::
......................

hash-table--a hash table.

   rehash-size--a real of type (or (integer 1 *) (float (1.0) *)).

Description::
.............

Returns the current rehash size of hash-table, suitable for use in a
call to make-hash-table in order to produce a hash table with state
corresponding to the current state of the hash-table.

Examples::
..........

      (setq table (make-hash-table :size 100 :rehash-size 1.4))
     =>  #<HASH-TABLE EQL 0/100 2556371>
      (hash-table-rehash-size table) =>  1.4

Exceptional Situations::
........................

Should signal an error of type type-error if hash-table is not a hash
table.

See Also::
..........

*note make-hash-table:: , *note hash-table-rehash-threshold::

Notes::
.......

If the hash table was created with an integer rehash size, the result is
an integer, indicating that the rate of growth of the hash-table when
rehashed is intended to be additive; otherwise, the result is a float,
indicating that the rate of growth of the hash-table when rehashed is
intended to be multiplicative.  However, this value is only advice to
the implementation; the actual amount by which the hash-table will grow
upon rehash is implementation-dependent.


File: gcl.info,  Node: hash-table-rehash-threshold,  Next: hash-table-size,  Prev: hash-table-rehash-size,  Up: Hash Tables Dictionary

18.2.6 hash-table-rehash-threshold [Function]
---------------------------------------------

'hash-table-rehash-threshold' hash-table => rehash-threshold

Arguments and Values::
......................

hash-table--a hash table.

   rehash-threshold--a real of type (real 0 1).

Description::
.............

Returns the current rehash threshold of hash-table, which is suitable
for use in a call to make-hash-table in order to produce a hash table
with state corresponding to the current state of the hash-table.

Examples::
..........

      (setq table (make-hash-table :size 100 :rehash-threshold 0.5))
     =>  #<HASH-TABLE EQL 0/100 2562446>
      (hash-table-rehash-threshold table) =>  0.5

Exceptional Situations::
........................

Should signal an error of type type-error if hash-table is not a hash
table.

See Also::
..........

*note make-hash-table:: , *note hash-table-rehash-size::


File: gcl.info,  Node: hash-table-size,  Next: hash-table-test,  Prev: hash-table-rehash-threshold,  Up: Hash Tables Dictionary

18.2.7 hash-table-size [Function]
---------------------------------

'hash-table-size' hash-table => size

Arguments and Values::
......................

hash-table--a hash table.

   size--a non-negative integer.

Description::
.............

Returns the current size of hash-table, which is suitable for use in a
call to make-hash-table in order to produce a hash table with state
corresponding to the current state of the hash-table.

Exceptional Situations::
........................

Should signal an error of type type-error if hash-table is not a hash
table.

See Also::
..........

*note hash-table-count:: , *note make-hash-table::


File: gcl.info,  Node: hash-table-test,  Next: gethash,  Prev: hash-table-size,  Up: Hash Tables Dictionary

18.2.8 hash-table-test [Function]
---------------------------------

'hash-table-test' hash-table => test

Arguments and Values::
......................

hash-table--a hash table.

   test--a function designator.  For the four standardized hash table
test functions (see make-hash-table), the test value returned is always
a symbol.  If an implementation permits additional tests, it is
implementation-dependent whether such tests are returned as function
objects or function names.

Description::
.............

Returns the test used for comparing keys in hash-table.

Exceptional Situations::
........................

Should signal an error of type type-error if hash-table is not a hash
table.

See Also::
..........

*note make-hash-table::


File: gcl.info,  Node: gethash,  Next: remhash,  Prev: hash-table-test,  Up: Hash Tables Dictionary

18.2.9 gethash [Accessor]
-------------------------

'gethash' key hash-table &optional default => value, present-p

   (setf (' gethash' key hash-table &optional default) new-value)

Arguments and Values::
......................

key--an object.

   hash-table--a hash table.

   default--an object.  The default is nil.

   value--an object.

   present-p--a generalized boolean.

Description::
.............

Value is the object in hash-table whose key is the same as key under the
hash-table's equivalence test.  If there is no such entry, value is the
default.

   Present-p is true if an entry is found; otherwise, it is false.

   setf may be used with gethash to modify the value associated with a
given key, or to add a new entry.

   When a gethash form is used as a setf place, any default which is
supplied is evaluated according to normal left-to-right evaluation
rules, but its value is ignored.

Examples::
..........

      (setq table (make-hash-table)) =>  #<HASH-TABLE EQL 0/120 32206334>
      (gethash 1 table) =>  NIL, false
      (gethash 1 table 2) =>  2, false
      (setf (gethash 1 table) "one") =>  "one"
      (setf (gethash 2 table "two") "two") =>  "two"
      (gethash 1 table) =>  "one", true
      (gethash 2 table) =>  "two", true
      (gethash nil table) =>  NIL, false
      (setf (gethash nil table) nil) =>  NIL
      (gethash nil table) =>  NIL, true
      (defvar *counters* (make-hash-table)) =>  *COUNTERS*
      (gethash 'foo *counters*) =>  NIL, false
      (gethash 'foo *counters* 0) =>  0, false
      (defmacro how-many (obj) `(values (gethash ,obj *counters* 0))) =>  HOW-MANY
      (defun count-it (obj) (incf (how-many obj))) =>  COUNT-IT
      (dolist (x '(bar foo foo bar bar baz)) (count-it x))
      (how-many 'foo) =>  2
      (how-many 'bar) =>  3
      (how-many 'quux) =>  0

See Also::
..........

*note remhash::

Notes::
.......

The secondary value, present-p, can be used to distinguish the absence
of an entry from the presence of an entry that has a value of default.


File: gcl.info,  Node: remhash,  Next: maphash,  Prev: gethash,  Up: Hash Tables Dictionary

18.2.10 remhash [Function]
--------------------------

'remhash' key hash-table => generalized-boolean

Arguments and Values::
......................

key--an object.

   hash-table--a hash table.

   generalized-boolean--a generalized boolean.

Description::
.............

Removes the entry for key in hash-table, if any.  Returns true if there
was such an entry, or false otherwise.

Examples::
..........

      (setq table (make-hash-table)) =>  #<HASH-TABLE EQL 0/120 32115666>
      (setf (gethash 100 table) "C") =>  "C"
      (gethash 100 table) =>  "C", true
      (remhash 100 table) =>  true
      (gethash 100 table) =>  NIL, false
      (remhash 100 table) =>  false

Side Effects::
..............

The hash-table is modified.


File: gcl.info,  Node: maphash,  Next: with-hash-table-iterator,  Prev: remhash,  Up: Hash Tables Dictionary

18.2.11 maphash [Function]
--------------------------

'maphash' function hash-table => nil

Arguments and Values::
......................

function--a designator for a function of two arguments, the key and the
value.

   hash-table--a hash table.

Description::
.............

Iterates over all entries in the hash-table.  For each entry, the
function is called with two arguments-the key and the value of that
entry.

   The consequences are unspecified if any attempt is made to add or
remove an entry from the hash-table while a maphash is in progress, with
two exceptions: the function can use can use setf of gethash to change
the value part of the entry currently being processed, or it can use
remhash to remove that entry.

Examples::
..........

      (setq table (make-hash-table)) =>  #<HASH-TABLE EQL 0/120 32304110>
      (dotimes (i 10) (setf (gethash i table) i)) =>  NIL
      (let ((sum-of-squares 0))
         (maphash #'(lambda (key val)
                      (let ((square (* val val)))
                        (incf sum-of-squares square)
                        (setf (gethash key table) square)))
                  table)
         sum-of-squares) =>  285
      (hash-table-count table) =>  10
      (maphash #'(lambda (key val)
                    (when (oddp val) (remhash key table)))
                table) =>  NIL
      (hash-table-count table) =>  5
      (maphash #'(lambda (k v) (print (list k v))) table)
     (0 0)
     (8 64)
     (2 4)
     (6 36)
     (4 16)
     =>  NIL

Side Effects::
..............

None, other than any which might be done by the function.

See Also::
..........

*note loop:: , *note with-hash-table-iterator:: ,

   *note Traversal Rules and Side Effects::


File: gcl.info,  Node: with-hash-table-iterator,  Next: clrhash,  Prev: maphash,  Up: Hash Tables Dictionary

18.2.12 with-hash-table-iterator [Macro]
----------------------------------------

'with-hash-table-iterator' (name hash-table) {declaration}* {form}* =>
{result}*

Arguments and Values::
......................

name--a name suitable for the first argument to macrolet.

   hash-table--a form, evaluated once, that should produce a hash table.

   declaration--a declare expression; not evaluated.

   forms--an implicit progn.

   results--the values returned by forms.

Description::
.............

Within the lexical scope of the body, name is defined via macrolet such
that successive invocations of (name) return the items, one by one, from
the hash table that is obtained by evaluating hash-table only once.

   An invocation (name) returns three values as follows:

1.
     A generalized boolean that is true if an entry is returned.
2.
     The key from the hash-table entry.
3.
     The value from the hash-table entry.

   After all entries have been returned by successive invocations of
(name), then only one value is returned, namely nil.

   It is unspecified what happens if any of the implicit interior state
of an iteration is returned outside the dynamic extent of the
with-hash-table-iterator form such as by returning some closure over the
invocation form.

   Any number of invocations of with-hash-table-iterator can be nested,
and the body of the innermost one can invoke all of the locally
established macros, provided all of those macros have distinct names.

Examples::
..........

The following function should return t on any hash table, and signal an
error if the usage of with-hash-table-iterator does not agree with the
corresponding usage of maphash.

      (defun test-hash-table-iterator (hash-table)
        (let ((all-entries '())
              (generated-entries '())
              (unique (list nil)))
          (maphash #'(lambda (key value) (push (list key value) all-entries))
                   hash-table)
          (with-hash-table-iterator (generator-fn hash-table)
            (loop
              (multiple-value-bind (more? key value) (generator-fn)
                (unless more? (return))
                (unless (eql value (gethash key hash-table unique))
                  (error "Key ~S not found for value ~S" key value))
                (push (list key value) generated-entries))))
          (unless (= (length all-entries)
                     (length generated-entries)
                     (length (union all-entries generated-entries
                                    :key #'car :test (hash-table-test hash-table))))
            (error "Generated entries and Maphash entries don't correspond"))
          t))

   The following could be an acceptable definition of maphash,
implemented by with-hash-table-iterator.

      (defun maphash (function hash-table)
        (with-hash-table-iterator (next-entry hash-table)
          (loop (multiple-value-bind (more key value) (next-entry)
                  (unless more (return nil))
                  (funcall function key value)))))

Exceptional Situations::
........................

The consequences are undefined if the local function named name
established by with-hash-table-iterator is called after it has returned
false as its primary value.

See Also::
..........

*note Traversal Rules and Side Effects::


File: gcl.info,  Node: clrhash,  Next: sxhash,  Prev: with-hash-table-iterator,  Up: Hash Tables Dictionary

18.2.13 clrhash [Function]
--------------------------

'clrhash' hash-table => hash-table

Arguments and Values::
......................

hash-table--a hash table.

Description::
.............

Removes all entries from hash-table, and then returns that empty hash
table.

Examples::
..........

      (setq table (make-hash-table)) =>  #<HASH-TABLE EQL 0/120 32004073>
      (dotimes (i 100) (setf (gethash i table) (format nil "~R" i))) =>  NIL
      (hash-table-count table) =>  100
      (gethash 57 table) =>  "fifty-seven", true
      (clrhash table) =>  #<HASH-TABLE EQL 0/120 32004073>
      (hash-table-count table) =>  0
      (gethash 57 table) =>  NIL, false

Side Effects::
..............

The hash-table is modified.


File: gcl.info,  Node: sxhash,  Prev: clrhash,  Up: Hash Tables Dictionary

18.2.14 sxhash [Function]
-------------------------

'sxhash' object => hash-code

Arguments and Values::
......................

object--an object.

   hash-code--a non-negative fixnum.

Description::
.............

sxhash returns a hash code for object.

   The manner in which the hash code is computed is
implementation-dependent, but subject to certain constraints:

1.
     (equal x y) implies (= (sxhash x) (sxhash y)).

2.
     For any two objects, x and y, both of which are bit vectors,
     characters, conses, numbers, pathnames, strings, or symbols, and
     which are similar, (sxhash x) and (sxhash y) yield the same
     mathematical value even if x and y exist in different Lisp images
     of the same implementation.  See *note Literal Objects in Compiled
     Files::.

3.
     The hash-code for an object is always the same within a single
     session provided that the object is not visibly modified with
     regard to the equivalence test equal.  See *note Modifying Hash
     Table Keys::.

4.
     The hash-code is intended for hashing.  This places no verifiable
     constraint on a conforming implementation, but the intent is that
     an implementation should make a good-faith effort to produce
     hash-codes that are well distributed within the range of
     non-negative fixnums.

5.
     Computation of the hash-code must terminate, even if the object
     contains circularities.

Examples::
..........

      (= (sxhash (list 'list "ab")) (sxhash (list 'list "ab"))) =>  true
      (= (sxhash "a") (sxhash (make-string 1 :initial-element #\a))) =>  true
      (let ((r (make-random-state)))
        (= (sxhash r) (sxhash (make-random-state r))))
     =>  implementation-dependent

Affected By::
.............

The implementation.

Notes::
.......

Many common hashing needs are satisfied by make-hash-table and the
related functions on hash tables.  sxhash is intended for use where the
pre-defined abstractions are insufficient.  Its main intent is to allow
the user a convenient means of implementing more complicated hashing
paradigms than are provided through hash tables.

   The hash codes returned by sxhash are not necessarily related to any
hashing strategy used by any other function in Common Lisp.

   For objects of types that equal compares with eq, item 3 requires
that the hash-code be based on some immutable quality of the identity of
the object.  Another legitimate implementation technique would be to
have sxhash assign (and cache) a random hash code for these objects,
since there is no requirement that similar but non-eq objects have the
same hash code.

   Although similarity is defined for symbols in terms of both the
symbol's name and the packages in which the symbol is accessible, item 3
disallows using package information to compute the hash code, since
changes to the package status of a symbol are not visible to equal.


File: gcl.info,  Node: Filenames,  Next: Files,  Prev: Hash Tables,  Up: Top

19 Filenames
************

* Menu:

* Overview of Filenames::
* Pathnames::
* Logical Pathnames::
* Filenames Dictionary::


File: gcl.info,  Node: Overview of Filenames,  Next: Pathnames,  Prev: Filenames,  Up: Filenames

19.1 Overview of Filenames
==========================

There are many kinds of file systems, varying widely both in their
superficial syntactic details, and in their underlying power and
structure.  The facilities provided by Common Lisp for referring to and
manipulating files has been chosen to be compatible with many kinds of
file systems, while at the same time minimizing the program-visible
differences between kinds of file systems.

   Since file systems vary in their conventions for naming files, there
are two distinct ways to represent filenames: as namestrings and as
pathnames.

* Menu:

* Namestrings as Filenames::
* Pathnames as Filenames::
* Parsing Namestrings Into Pathnames::


File: gcl.info,  Node: Namestrings as Filenames,  Next: Pathnames as Filenames,  Prev: Overview of Filenames,  Up: Overview of Filenames

19.1.1 Namestrings as Filenames
-------------------------------

A namestring is a string that represents a filename.

   In general, the syntax of namestrings involves the use of
implementation-defined conventions, usually those customary for the file
system in which the named file resides.  The only exception is the
syntax of a logical pathname namestring, which is defined in this
specification; see *note Syntax of Logical Pathname Namestrings::.

   A conforming program must never unconditionally use a literal
namestring other than a logical pathname namestring because Common Lisp
does not define any namestring syntax other than that for logical
pathnames that would be guaranteed to be portable.  However, a
conforming program can, if it is careful, successfully manipulate
user-supplied data which contains or refers to non-portable namestrings.

   A namestring can be coerced to a pathname by the functions pathname
or parse-namestring.


File: gcl.info,  Node: Pathnames as Filenames,  Next: Parsing Namestrings Into Pathnames,  Prev: Namestrings as Filenames,  Up: Overview of Filenames

19.1.2 Pathnames as Filenames
-----------------------------

Pathnames are structured objects that can represent, in an
implementation-independent way, the filenames that are used natively by
an underlying file system.

   In addition, pathnames can also represent certain partially composed
filenames for which an underlying file system might not have a specific
namestring representation.

   A pathname need not correspond to any file that actually exists, and
more than one pathname can refer to the same file.  For example, the
pathname with a version of :newest might refer to the same file as a
pathname with the same components except a certain number as the
version.  Indeed, a pathname with version :newest might refer to
different files as time passes, because the meaning of such a pathname
depends on the state of the file system.

   Some file systems naturally use a structural model for their
filenames, while others do not.  Within the Common Lisp pathname model,
all filenames are seen as having a particular structure, even if that
structure is not reflected in the underlying file system.  The nature of
the mapping between structure imposed by pathnames and the structure, if
any, that is used by the underlying file system is
implementation-defined.

   Every pathname has six components: a host, a device, a directory, a
name, a type, and a version.  By naming files with pathnames, Common
Lisp programs can work in essentially the same way even in file systems
that seem superficially quite different.  For a detailed description of
these components, see *note Pathname Components::.

   The mapping of the pathname components into the concepts peculiar to
each file system is implementation-defined.  There exist conceivable
pathnames for which there is no mapping to a syntactically valid
filename in a particular implementation.  An implementation may use
various strategies in an attempt to find a mapping; for example, an
implementation may quietly truncate filenames that exceed length
limitations imposed by the underlying file system, or ignore certain
pathname components for which the file system provides no support.  If
such a mapping cannot be found, an error of type file-error is signaled.

   The time at which this mapping and associated error signaling occurs
is implementation-dependent.  Specifically, it may occur at the time the
pathname is constructed, when coercing a pathname to a namestring, or
when an attempt is made to open or otherwise access the file designated
by the pathname.

   Figure 19-1 lists some defined names that are applicable to
pathnames.

  *default-pathname-defaults*  namestring          pathname-name          
  directory-namestring         open                pathname-type          
  enough-namestring            parse-namestring    pathname-version       
  file-namestring              pathname            pathnamep              
  file-string-length           pathname-device     translate-pathname     
  host-namestring              pathname-directory  truename               
  make-pathname                pathname-host       user-homedir-pathname  
  merge-pathnames              pathname-match-p    wild-pathname-p        

                     Figure 19-1: Pathname Operations                    



File: gcl.info,  Node: Parsing Namestrings Into Pathnames,  Prev: Pathnames as Filenames,  Up: Overview of Filenames

19.1.3 Parsing Namestrings Into Pathnames
-----------------------------------------

Parsing is the operation used to convert a namestring into a pathname.

   Except in the case of parsing logical pathname namestrings,

   this operation is implementation-dependent, because the format of
namestrings is implementation-dependent.

   A conforming implementation is free to accommodate other file system
features in its pathname representation and provides a parser that can
process such specifications in namestrings.  Conforming programs must
not depend on any such features, since those features will not be
portable.


File: gcl.info,  Node: Pathnames,  Next: Logical Pathnames,  Prev: Overview of Filenames,  Up: Filenames

19.2 Pathnames
==============

* Menu:

* Pathname Components::
* Interpreting Pathname Component Values::
* Merging Pathnames::


File: gcl.info,  Node: Pathname Components,  Next: Interpreting Pathname Component Values,  Prev: Pathnames,  Up: Pathnames

19.2.1 Pathname Components
--------------------------

A pathname has six components: a host, a device, a directory, a name, a
type, and a version.

* Menu:

* The Pathname Host Component::
* The Pathname Device Component::
* The Pathname Directory Component::
* The Pathname Name Component::
* The Pathname Type Component::
* The Pathname Version Component::


File: gcl.info,  Node: The Pathname Host Component,  Next: The Pathname Device Component,  Prev: Pathname Components,  Up: Pathname Components

19.2.1.1 The Pathname Host Component
....................................

The name of the file system on which the file resides, or the name of a
logical host.


File: gcl.info,  Node: The Pathname Device Component,  Next: The Pathname Directory Component,  Prev: The Pathname Host Component,  Up: Pathname Components

19.2.1.2 The Pathname Device Component
......................................

Corresponds to the "device" or "file structure" concept in many host
file systems: the name of a logical or physical device containing files.


File: gcl.info,  Node: The Pathname Directory Component,  Next: The Pathname Name Component,  Prev: The Pathname Device Component,  Up: Pathname Components

19.2.1.3 The Pathname Directory Component
.........................................

Corresponds to the "directory" concept in many host file systems: the
name of a group of related files.


File: gcl.info,  Node: The Pathname Name Component,  Next: The Pathname Type Component,  Prev: The Pathname Directory Component,  Up: Pathname Components

19.2.1.4 The Pathname Name Component
....................................

The "name" part of a group of files that can be thought of as
conceptually related.


File: gcl.info,  Node: The Pathname Type Component,  Next: The Pathname Version Component,  Prev: The Pathname Name Component,  Up: Pathname Components

19.2.1.5 The Pathname Type Component
....................................

Corresponds to the "filetype" or "extension" concept in many host file
systems.  This says what kind of file this is.  This component is always
a string, nil, :wild, or :unspecific.


File: gcl.info,  Node: The Pathname Version Component,  Prev: The Pathname Type Component,  Up: Pathname Components

19.2.1.6 The Pathname Version Component
.......................................

Corresponds to the "version number" concept in many host file systems.

   The version is either a positive integer or a symbol from the
following list: nil, :wild, :unspecific, or :newest (refers to the
largest version number that already exists in the file system when
reading a file, or to a version number greater than any already existing
in the file system when writing a new file).  Implementations can define
other special version symbols.


File: gcl.info,  Node: Interpreting Pathname Component Values,  Next: Merging Pathnames,  Prev: Pathname Components,  Up: Pathnames

19.2.2 Interpreting Pathname Component Values
---------------------------------------------

* Menu:

* Strings in Component Values::
* Special Characters in Pathname Components::
* Case in Pathname Components::
* Local Case in Pathname Components::
* Common Case in Pathname Components::
* Special Pathname Component Values::
* NIL as a Component Value::
* ->WILD as a Component Value::
* ->UNSPECIFIC as a Component Value::
* Relation between component values NIL and ->UNSPECIFIC::
* Restrictions on Wildcard Pathnames::
* Restrictions on Examining Pathname Components::
* Restrictions on Examining a Pathname Host Component::
* Restrictions on Examining a Pathname Device Component::
* Restrictions on Examining a Pathname Directory Component::
* Directory Components in Non-Hierarchical File Systems::
* Restrictions on Examining a Pathname Name Component::
* Restrictions on Examining a Pathname Type Component::
* Restrictions on Examining a Pathname Version Component::
* Notes about the Pathname Version Component::
* Restrictions on Constructing Pathnames::


File: gcl.info,  Node: Strings in Component Values,  Next: Special Characters in Pathname Components,  Prev: Interpreting Pathname Component Values,  Up: Interpreting Pathname Component Values

19.2.2.1 Strings in Component Values
....................................


File: gcl.info,  Node: Special Characters in Pathname Components,  Next: Case in Pathname Components,  Prev: Strings in Component Values,  Up: Interpreting Pathname Component Values

19.2.2.2 Special Characters in Pathname Components
..................................................

Strings in pathname component values never contain special characters
that represent separation between pathname fields, such as slash in Unix
filenames.  Whether separator characters are permitted as part of a
string in a pathname component is implementation-defined; however, if
the implementation does permit it, it must arrange to properly "quote"
the character for the file system when constructing a namestring.  For
example,

      ;; In a TOPS-20 implementation, which uses ^V to quote
      (NAMESTRING (MAKE-PATHNAME :HOST "OZ" :NAME "<TEST>"))
     =>  #P"OZ:PS:^V<TEST^V>"
     NOT=> #P"OZ:PS:<TEST>"


File: gcl.info,  Node: Case in Pathname Components,  Next: Local Case in Pathname Components,  Prev: Special Characters in Pathname Components,  Up: Interpreting Pathname Component Values

19.2.2.3 Case in Pathname Components
....................................

Namestrings always use local file system case conventions, but Common
Lisp functions that manipulate pathname components allow the caller to
select either of two conventions for representing case in component
values by supplying a value for the :case keyword argument.  Figure 19-2
lists the functions relating to pathnames that permit a :case argument:

  make-pathname    pathname-directory  pathname-name  
  pathname-device  pathname-host       pathname-type  

  Figure 19-2: Pathname functions using a :CASE argument



File: gcl.info,  Node: Local Case in Pathname Components,  Next: Common Case in Pathname Components,  Prev: Case in Pathname Components,  Up: Interpreting Pathname Component Values

19.2.2.4 Local Case in Pathname Components
..........................................

For the functions in Figure~19-2, a value of :local for the :case
argument (the default for these functions) indicates that the functions
should receive and yield strings in component values as if they were
already represented according to the host file system's convention for
case.

   If the file system supports both cases, strings given or received as
pathname component values under this protocol are to be used exactly as
written.  If the file system only supports one case, the strings will be
translated to that case.


File: gcl.info,  Node: Common Case in Pathname Components,  Next: Special Pathname Component Values,  Prev: Local Case in Pathname Components,  Up: Interpreting Pathname Component Values

19.2.2.5 Common Case in Pathname Components
...........................................

For the functions in Figure~19-2, a value of :common for the :case
argument that these functions should receive and yield strings in
component values according to the following conventions:

*
     All uppercase means to use a file system's customary case.
*
     All lowercase means to use the opposite of the customary case.
*
     Mixed case represents itself.

   Note that these conventions have been chosen in such a way that
translation from :local to :common and back to :local is
information-preserving.


File: gcl.info,  Node: Special Pathname Component Values,  Next: NIL as a Component Value,  Prev: Common Case in Pathname Components,  Up: Interpreting Pathname Component Values

19.2.2.6 Special Pathname Component Values
..........................................


File: gcl.info,  Node: NIL as a Component Value,  Next: ->WILD as a Component Value,  Prev: Special Pathname Component Values,  Up: Interpreting Pathname Component Values

19.2.2.7 NIL as a Component Value
.................................

As a pathname component value, nil represents that the component is
"unfilled"; see *note Merging Pathnames::.

   The value of any pathname component can be nil.

   When constructing a pathname, nil in the host component might mean a
default host rather than an actual nil in some implementations.


File: gcl.info,  Node: ->WILD as a Component Value,  Next: ->UNSPECIFIC as a Component Value,  Prev: NIL as a Component Value,  Up: Interpreting Pathname Component Values

19.2.2.8 :WILD as a Component Value
...................................

If :wild is the value of a pathname component, that component is
considered to be a wildcard, which matches anything.

   A conforming program must be prepared to encounter a value of :wild
as the value of any pathname component, or as an element of a list that
is the value of the directory component.

   When constructing a pathname, a conforming program may use :wild as
the value of any or all of the directory, name, type, or version
component, but must not use :wild as the value of the host, or device
component.

   If :wild is used as the value of the directory component in the
construction of a pathname, the effect is equivalent to specifying the
list (:absolute :wild-inferiors), or the same as (:absolute :wild) in a
file system that does not support :wild-inferiors.


File: gcl.info,  Node: ->UNSPECIFIC as a Component Value,  Next: Relation between component values NIL and ->UNSPECIFIC,  Prev: ->WILD as a Component Value,  Up: Interpreting Pathname Component Values

19.2.2.9 :UNSPECIFIC as a Component Value
.........................................

If :unspecific is the value of a pathname component, the component is
considered to be "absent" or to "have no meaning" in the filename being
represented by the pathname.

   Whether a value of :unspecific is permitted for any component on any
given file system accessible to the implementation is
implementation-defined.  A conforming program must never unconditionally
use a :unspecific as the value of a pathname component because such a
value is not guaranteed to be permissible in all implementations.
However, a conforming program can, if it is careful, successfully
manipulate user-supplied data which contains or refers to non-portable
pathname components.  And certainly a conforming program should be
prepared for the possibility that any components of a pathname could be
:unspecific.

   When reading_1 the value of any pathname component, conforming
programs should be prepared for the value to be :unspecific.

   When writing_1 the value of any pathname component, the consequences
are undefined if :unspecific is given for a pathname in a file system
for which it does not make sense.


File: gcl.info,  Node: Relation between component values NIL and ->UNSPECIFIC,  Next: Restrictions on Wildcard Pathnames,  Prev: ->UNSPECIFIC as a Component Value,  Up: Interpreting Pathname Component Values

19.2.2.10 Relation between component values NIL and :UNSPECIFIC
...............................................................

If a pathname is converted to a namestring, the symbols nil and
:unspecific cause the field to be treated as if it were empty.  That is,
both nil and :unspecific cause the component not to appear in the
namestring.

   However, when merging a pathname with a set of defaults, only a nil
value for a component will be replaced with the default for that
component, while a value of :unspecific will be left alone as if the
field were "filled"; see the function merge-pathnames and *note Merging
Pathnames::.


File: gcl.info,  Node: Restrictions on Wildcard Pathnames,  Next: Restrictions on Examining Pathname Components,  Prev: Relation between component values NIL and ->UNSPECIFIC,  Up: Interpreting Pathname Component Values

19.2.2.11 Restrictions on Wildcard Pathnames
............................................

Wildcard pathnames can be used with directory but not with open, and
return true from wild-pathname-p.  When examining wildcard components of
a wildcard pathname, conforming programs must be prepared to encounter
any of the following additional values in any component or any element
of a list that is the directory component:

*
     The symbol :wild, which matches anything.

*
     A string containing implementation-dependent special wildcard
     characters.

*
     Any object, representing an implementation-dependent wildcard
     pattern.


File: gcl.info,  Node: Restrictions on Examining Pathname Components,  Next: Restrictions on Examining a Pathname Host Component,  Prev: Restrictions on Wildcard Pathnames,  Up: Interpreting Pathname Component Values

19.2.2.12 Restrictions on Examining Pathname Components
.......................................................

The space of possible objects that a conforming program must be prepared
to read_1 as the value of a pathname component is substantially larger
than the space of possible objects that a conforming program is
permitted to write_1 into such a component.

   While the values discussed in the subsections of this section, in
*note Special Pathname Component Values::, and in *note Restrictions on
Wildcard Pathnames:: apply to values that might be seen when reading the
component values, substantially more restrictive rules apply to
constructing pathnames; see *note Restrictions on Constructing
Pathnames::.

   When examining pathname components, conforming programs should be
aware of the following restrictions.


File: gcl.info,  Node: Restrictions on Examining a Pathname Host Component,  Next: Restrictions on Examining a Pathname Device Component,  Prev: Restrictions on Examining Pathname Components,  Up: Interpreting Pathname Component Values

19.2.2.13 Restrictions on Examining a Pathname Host Component
.............................................................

It is implementation-dependent what object is used to represent the
host.


File: gcl.info,  Node: Restrictions on Examining a Pathname Device Component,  Next: Restrictions on Examining a Pathname Directory Component,  Prev: Restrictions on Examining a Pathname Host Component,  Up: Interpreting Pathname Component Values

19.2.2.14 Restrictions on Examining a Pathname Device Component
...............................................................

The device might be a string, :wild, :unspecific, or nil.

   Note that :wild might result from an attempt to read_1 the pathname
component, even though portable programs are restricted from writing_1
such a component value; see *note Restrictions on Wildcard Pathnames::
and *note Restrictions on Constructing Pathnames::.


File: gcl.info,  Node: Restrictions on Examining a Pathname Directory Component,  Next: Directory Components in Non-Hierarchical File Systems,  Prev: Restrictions on Examining a Pathname Device Component,  Up: Interpreting Pathname Component Values

19.2.2.15 Restrictions on Examining a Pathname Directory Component
..................................................................

The directory might be a string, :wild, :unspecific, or nil.

   The directory can be a list of strings and symbols.

   The car of the list is one of the symbols :absolute or :relative ,
meaning:

:absolute
     A list whose car is the symbol :absolute represents a directory
     path starting from the root directory.  The list (:absolute)
     represents the root directory.  The list (:absolute "foo" "bar"
     "baz") represents the directory called "/foo/bar/baz" in Unix
     (except possibly for case).

:relative
     A list whose car is the symbol :relative represents a directory
     path starting from a default directory.  The list (:relative) has
     the same meaning as nil and hence is not used.  The list (:relative
     "foo" "bar") represents the directory named "bar" in the directory
     named "foo" in the default directory.

   Each remaining element of the list is a string or a symbol.

   Each string names a single level of directory structure.  The strings
should contain only the directory names themselves--no punctuation
characters.

   In place of a string, at any point in the list, symbols can occur to
indicate special file notations.  Figure 19-3 lists the symbols that
have standard meanings.  Implementations are permitted to add additional
objects of any type that is disjoint from string if necessary to
represent features of their file systems that cannot be represented with
the standard strings and symbols.

   Supplying any non-string, including any of the symbols listed below,
to a file system for which it does not make sense signals an error of
type file-error.  For example, Unix does not support :wild-inferiors in
most implementations.

  Symbol           Meaning                                             
  :wild            Wildcard match of one level of directory structure  
  :wild-inferiors  Wildcard match of any number of directory levels    
  :up              Go upward in directory structure (semantic)         
  :back            Go upward in directory structure (syntactic)        

          Figure 19-3: Special Markers In Directory Component         


   The following notes apply to the previous figure:

Invalid Combinations
     Using :absolute or :wild-inferiors immediately followed by :up or
     :back signals an error of type file-error.

Syntactic vs Semantic
     "Syntactic" means that the action of :back depends only on the
     pathname and not on the contents of the file system.

     "Semantic" means that the action of :up depends on the contents of
     the file system; to resolve a pathname containing :up to a pathname
     whose directory component contains only :absolute and strings
     requires probing the file system.

     :up differs from :back only in file systems that support multiple
     names for directories, perhaps via symbolic links.  For example,
     suppose that there is a directory (:absolute "X" "Y" "Z") linked to
     (:absolute "A" "B" "C") and there also exist directories (:absolute
     "A" "B" "Q") and (:absolute "X" "Y" "Q").  Then (:absolute "X" "Y"
     "Z" :up "Q") designates (:absolute "A" "B" "Q") while (:absolute
     "X" "Y" "Z" :back "Q") designates (:absolute "X" "Y" "Q")


File: gcl.info,  Node: Directory Components in Non-Hierarchical File Systems,  Next: Restrictions on Examining a Pathname Name Component,  Prev: Restrictions on Examining a Pathname Directory Component,  Up: Interpreting Pathname Component Values

19.2.2.16 Directory Components in Non-Hierarchical File Systems
...............................................................

In non-hierarchical file systems, the only valid list values for the
directory component of a pathname are (:absolute string) and (:absolute
:wild).  :relative directories and the keywords :wild-inferiors, :up,
and :back are not used in non-hierarchical file systems.


File: gcl.info,  Node: Restrictions on Examining a Pathname Name Component,  Next: Restrictions on Examining a Pathname Type Component,  Prev: Directory Components in Non-Hierarchical File Systems,  Up: Interpreting Pathname Component Values

19.2.2.17 Restrictions on Examining a Pathname Name Component
.............................................................

The name might be a string, :wild, :unspecific, or nil.


File: gcl.info,  Node: Restrictions on Examining a Pathname Type Component,  Next: Restrictions on Examining a Pathname Version Component,  Prev: Restrictions on Examining a Pathname Name Component,  Up: Interpreting Pathname Component Values

19.2.2.18 Restrictions on Examining a Pathname Type Component
.............................................................

The type might be a string, :wild, :unspecific, or nil.


File: gcl.info,  Node: Restrictions on Examining a Pathname Version Component,  Next: Notes about the Pathname Version Component,  Prev: Restrictions on Examining a Pathname Type Component,  Up: Interpreting Pathname Component Values

19.2.2.19 Restrictions on Examining a Pathname Version Component
................................................................

The version can be any symbol or any integer.

   The symbol :newest refers to the largest version number that already
exists in the file system when reading, overwriting, appending,
superseding, or directory listing an existing file.  The symbol :newest
refers to the smallest version number greater than any existing version
number when creating a new file.

   The symbols nil, :unspecific, and :wild have special meanings and
restrictions; see *note Special Pathname Component Values:: and *note
Restrictions on Constructing Pathnames::.

   Other symbols and integers have implementation-defined meaning.


File: gcl.info,  Node: Notes about the Pathname Version Component,  Next: Restrictions on Constructing Pathnames,  Prev: Restrictions on Examining a Pathname Version Component,  Up: Interpreting Pathname Component Values

19.2.2.20 Notes about the Pathname Version Component
....................................................

It is suggested, but not required, that implementations do the
following:

*
     Use positive integers starting at 1 as version numbers.

*
     Recognize the symbol :oldest to designate the smallest existing
     version number.

*
     Use keywords for other special versions.


File: gcl.info,  Node: Restrictions on Constructing Pathnames,  Prev: Notes about the Pathname Version Component,  Up: Interpreting Pathname Component Values

19.2.2.21 Restrictions on Constructing Pathnames
................................................

When constructing a pathname from components, conforming programs must
follow these rules:

*
     Any component can be nil.  nil in the host might mean a default
     host rather than an actual nil in some implementations.

*
     The host, device, directory, name, and type can be strings.  There
     are implementation-dependent limits on the number and type of
     characters in these strings.

*
     The directory can be a list of strings and symbols.  There are
     implementation-dependent limits on the list's length and contents.

*
     The version can be :newest.

*
     Any component can be taken from the corresponding component of
     another pathname.  When the two pathnames are for different file
     systems (in implementations that support multiple file systems), an
     appropriate translation occurs.  If no meaningful translation is
     possible, an error is signaled.  The definitions of "appropriate"
     and "meaningful" are implementation-dependent.

*
     An implementation might support other values for some components,
     but a portable program cannot use those values.  A conforming
     program can use implementation-dependent values but this can make
     it non-portable; for example, it might work only with Unix file
     systems.


File: gcl.info,  Node: Merging Pathnames,  Prev: Interpreting Pathname Component Values,  Up: Pathnames

19.2.3 Merging Pathnames
------------------------

Merging takes a pathname with unfilled components and supplies values
for those components from a source of defaults.

   If a component's value is nil, that component is considered to be
unfilled.  If a component's value is any non-nil object, including
:unspecific, that component is considered to be filled.

   Except as explicitly specified otherwise, for functions that
manipulate or inquire about files in the file system, the pathname
argument to such a function is merged with *default-pathname-defaults*
before accessing the file system (as if by merge-pathnames).

* Menu:

* Examples of Merging Pathnames::


File: gcl.info,  Node: Examples of Merging Pathnames,  Prev: Merging Pathnames,  Up: Merging Pathnames

19.2.3.1 Examples of Merging Pathnames
......................................

Although the following examples are possible to execute only in
implementations which permit :unspecific in the indicated position
andwhich permit four-letter type components, they serve to illustrate
the basic concept of pathname merging.

      (pathname-type
        (merge-pathnames (make-pathname :type "LISP")
                         (make-pathname :type "TEXT")))
     =>  "LISP"

      (pathname-type
        (merge-pathnames (make-pathname :type nil)
                         (make-pathname :type "LISP")))
     =>  "LISP"

      (pathname-type
        (merge-pathnames (make-pathname :type :unspecific)
                         (make-pathname :type "LISP")))
     =>  :UNSPECIFIC


File: gcl.info,  Node: Logical Pathnames,  Next: Filenames Dictionary,  Prev: Pathnames,  Up: Filenames

19.3 Logical Pathnames
======================

* Menu:

* Syntax of Logical Pathname Namestrings::
* Logical Pathname Components::


File: gcl.info,  Node: Syntax of Logical Pathname Namestrings,  Next: Logical Pathname Components,  Prev: Logical Pathnames,  Up: Logical Pathnames

19.3.1 Syntax of Logical Pathname Namestrings
---------------------------------------------

The syntax of a logical pathname namestring is as follows.  (Note that
unlike many notational descriptions in this document, this is a
syntactic description of character sequences, not a structural
description of objects.)

   logical-pathname ::=[!host host-marker] 
                     [!relative-directory-marker] {!directory directory-marker}* 
                     [!name] [type-marker !type [version-marker !version]]

   host ::=!word

   directory ::=!word | !wildcard-word | !wild-inferiors-word

   name ::=!word | !wildcard-word

   type ::=!word | !wildcard-word

   version ::=!pos-int | newest-word | wildcard-version

   host-marker--a colon.

   relative-directory-marker--a semicolon.

   directory-marker--a semicolon.

   type-marker--a dot.

   version-marker--a dot.

   wild-inferiors-word--The two character sequence "**" (two asterisks).

   newest-word--The six character sequence "newest" or the six character
sequence "NEWEST".

   wildcard-version--an asterisk.

   wildcard-word--one or more asterisks, uppercase letters, digits, and
hyphens, including at least one asterisk, with no two asterisks
adjacent.

   word--one or more uppercase letters, digits, and hyphens.

   pos-int--a positive integer.

* Menu:

* Additional Information about Parsing Logical Pathname Namestrings::
* The Host part of a Logical Pathname Namestring::
* The Device part of a Logical Pathname Namestring::
* The Directory part of a Logical Pathname Namestring::
* The Type part of a Logical Pathname Namestring::
* The Version part of a Logical Pathname Namestring::
* Wildcard Words in a Logical Pathname Namestring::
* Lowercase Letters in a Logical Pathname Namestring::
* Other Syntax in a Logical Pathname Namestring::


File: gcl.info,  Node: Additional Information about Parsing Logical Pathname Namestrings,  Next: The Host part of a Logical Pathname Namestring,  Prev: Syntax of Logical Pathname Namestrings,  Up: Syntax of Logical Pathname Namestrings

19.3.1.1 Additional Information about Parsing Logical Pathname Namestrings
..........................................................................


File: gcl.info,  Node: The Host part of a Logical Pathname Namestring,  Next: The Device part of a Logical Pathname Namestring,  Prev: Additional Information about Parsing Logical Pathname Namestrings,  Up: Syntax of Logical Pathname Namestrings

19.3.1.2 The Host part of a Logical Pathname Namestring
.......................................................

The host must have been defined as a logical pathname host; this can be
done by using setf of logical-pathname-translations.

   The logical pathname host name "SYS" is reserved for the
implementation.  The existence and meaning of SYS: logical pathnames is
implementation-defined.


File: gcl.info,  Node: The Device part of a Logical Pathname Namestring,  Next: The Directory part of a Logical Pathname Namestring,  Prev: The Host part of a Logical Pathname Namestring,  Up: Syntax of Logical Pathname Namestrings

19.3.1.3 The Device part of a Logical Pathname Namestring
.........................................................

There is no syntax for a logical pathname device since the device
component of a logical pathname is always :unspecific; see *note
Unspecific Components of a Logical Pathname::.


File: gcl.info,  Node: The Directory part of a Logical Pathname Namestring,  Next: The Type part of a Logical Pathname Namestring,  Prev: The Device part of a Logical Pathname Namestring,  Up: Syntax of Logical Pathname Namestrings

19.3.1.4 The Directory part of a Logical Pathname Namestring
............................................................

If a relative-directory-marker precedes the directories, the directory
component parsed is as relative; otherwise, the directory component is
parsed as absolute.

   If a wild-inferiors-marker is specified, it parses into
:wild-inferiors.


File: gcl.info,  Node: The Type part of a Logical Pathname Namestring,  Next: The Version part of a Logical Pathname Namestring,  Prev: The Directory part of a Logical Pathname Namestring,  Up: Syntax of Logical Pathname Namestrings

19.3.1.5 The Type part of a Logical Pathname Namestring
.......................................................

The type of a logical pathname for a source file is "LISP".  This should
be translated into whatever type is appropriate in a physical pathname.


File: gcl.info,  Node: The Version part of a Logical Pathname Namestring,  Next: Wildcard Words in a Logical Pathname Namestring,  Prev: The Type part of a Logical Pathname Namestring,  Up: Syntax of Logical Pathname Namestrings

19.3.1.6 The Version part of a Logical Pathname Namestring
..........................................................

Some file systems do not have versions.  Logical pathname translation to
such a file system ignores the version.  This implies that a program
cannot rely on being able to store more than one version of a file named
by a logical pathname.

   If a wildcard-version is specified, it parses into :wild.


File: gcl.info,  Node: Wildcard Words in a Logical Pathname Namestring,  Next: Lowercase Letters in a Logical Pathname Namestring,  Prev: The Version part of a Logical Pathname Namestring,  Up: Syntax of Logical Pathname Namestrings

19.3.1.7 Wildcard Words in a Logical Pathname Namestring
........................................................

Each asterisk in a wildcard-word matches a sequence of zero or more
characters.  The wildcard-word "*" parses into :wild; other
wildcard-words parse into strings.


File: gcl.info,  Node: Lowercase Letters in a Logical Pathname Namestring,  Next: Other Syntax in a Logical Pathname Namestring,  Prev: Wildcard Words in a Logical Pathname Namestring,  Up: Syntax of Logical Pathname Namestrings

19.3.1.8 Lowercase Letters in a Logical Pathname Namestring
...........................................................

When parsing words and wildcard-words, lowercase letters are translated
to uppercase.


File: gcl.info,  Node: Other Syntax in a Logical Pathname Namestring,  Prev: Lowercase Letters in a Logical Pathname Namestring,  Up: Syntax of Logical Pathname Namestrings

19.3.1.9 Other Syntax in a Logical Pathname Namestring
......................................................

The consequences of using characters other than those specified here in
a logical pathname namestring are unspecified.

   The consequences of using any value not specified here as a logical
pathname component are unspecified.


File: gcl.info,  Node: Logical Pathname Components,  Prev: Syntax of Logical Pathname Namestrings,  Up: Logical Pathnames

19.3.2 Logical Pathname Components
----------------------------------

* Menu:

* Unspecific Components of a Logical Pathname::
* Null Strings as Components of a Logical Pathname::


File: gcl.info,  Node: Unspecific Components of a Logical Pathname,  Next: Null Strings as Components of a Logical Pathname,  Prev: Logical Pathname Components,  Up: Logical Pathname Components

19.3.2.1 Unspecific Components of a Logical Pathname
....................................................

The device component of a logical pathname is always :unspecific; no
other component of a logical pathname can be :unspecific.


File: gcl.info,  Node: Null Strings as Components of a Logical Pathname,  Prev: Unspecific Components of a Logical Pathname,  Up: Logical Pathname Components

19.3.2.2 Null Strings as Components of a Logical Pathname
.........................................................

The null string, "", is not a valid value for any component of a logical
pathname.


File: gcl.info,  Node: Filenames Dictionary,  Prev: Logical Pathnames,  Up: Filenames

19.4 Filenames Dictionary
=========================

* Menu:

* pathname (System Class)::
* logical-pathname (System Class)::
* pathname::
* make-pathname::
* pathnamep::
* pathname-host::
* load-logical-pathname-translations::
* logical-pathname-translations::
* logical-pathname::
* *default-pathname-defaults*::
* namestring::
* parse-namestring::
* wild-pathname-p::
* pathname-match-p::
* translate-logical-pathname::
* translate-pathname::
* merge-pathnames::


File: gcl.info,  Node: pathname (System Class),  Next: logical-pathname (System Class),  Prev: Filenames Dictionary,  Up: Filenames Dictionary

19.4.1 pathname [System Class]
------------------------------

Class Precedence List::
.......................

pathname, t

Description::
.............

A pathname is a structured object which represents a filename.

   There are two kinds of pathnames--physical pathnames and logical
pathnames.


File: gcl.info,  Node: logical-pathname (System Class),  Next: pathname,  Prev: pathname (System Class),  Up: Filenames Dictionary

19.4.2 logical-pathname [System Class]
--------------------------------------

Class Precedence List::
.......................

logical-pathname, pathname, t

Description::
.............

A pathname that uses a namestring syntax that is
implementation-independent, and that has component values that are
implementation-independent.  Logical pathnames do not refer directly to
filenames

See Also::
..........

*note File System Concepts::, *note Sharpsign P::, *note Printing
Pathnames::


File: gcl.info,  Node: pathname,  Next: make-pathname,  Prev: logical-pathname (System Class),  Up: Filenames Dictionary

19.4.3 pathname [Function]
--------------------------

'pathname' pathspec => pathname

Arguments and Values::
......................

pathspec--a pathname designator.

   pathname--a pathname.

Description::
.............

Returns the pathname denoted by pathspec.

   If the pathspec designator is a stream, the stream can be either open
or closed; in both cases, the pathname returned corresponds to the
filename used to open the file.  pathname returns the same pathname for
a file stream after it is closed as it did when it was open.

   If the pathspec designator is a file stream created by opening a
logical pathname, a logical pathname is returned.

Examples::
..........

      ;; There is a great degree of variability permitted here.  The next
      ;; several examples are intended to illustrate just a few of the many
      ;; possibilities.  Whether the name is canonicalized to a particular
      ;; case (either upper or lower) depends on both the file system and the
      ;; implementation since two different implementations using the same
      ;; file system might differ on many issues.  How information is stored
      ;; internally (and possibly presented in #S notation) might vary,
      ;; possibly requiring `accessors' such as PATHNAME-NAME to perform case
      ;; conversion upon access.  The format of a namestring is dependent both
      ;; on the file system and the implementation since, for example, one
      ;; implementation might include the host name in a namestring, and
      ;; another might not.  #S notation would generally only be used in a
      ;; situation where no appropriate namestring could be constructed for use
      ;; with #P.
      (setq p1 (pathname "test"))
     =>  #P"CHOCOLATE:TEST" ; with case canonicalization (e.g., VMS)
     OR=> #P"VANILLA:test"   ; without case canonicalization (e.g., Unix)
     OR=> #P"test"
     OR=> #S(PATHNAME :HOST "STRAWBERRY" :NAME "TEST")
     OR=> #S(PATHNAME :HOST "BELGIAN-CHOCOLATE" :NAME "test")
      (setq p2 (pathname "test"))
     =>  #P"CHOCOLATE:TEST"
     OR=> #P"VANILLA:test"
     OR=> #P"test"
     OR=> #S(PATHNAME :HOST "STRAWBERRY" :NAME "TEST")
     OR=> #S(PATHNAME :HOST "BELGIAN-CHOCOLATE" :NAME "test")
      (pathnamep p1) =>  true
      (eq p1 (pathname p1)) =>  true
      (eq p1 p2)
     =>  true
     OR=> false
      (with-open-file (stream "test" :direction :output)
        (pathname stream))
     =>  #P"ORANGE-CHOCOLATE:>Gus>test.lisp.newest"

See Also::
..........

pathname, logical-pathname, *note File System Concepts::,

   *note Pathnames as Filenames::


File: gcl.info,  Node: make-pathname,  Next: pathnamep,  Prev: pathname,  Up: Filenames Dictionary

19.4.4 make-pathname [Function]
-------------------------------

'make-pathname' &key host device directory name type version defaults
case
=> pathname

Arguments and Values::
......................

host--a valid physical pathname host.  Complicated defaulting behavior;
see below.

   device--a valid pathname device.  Complicated defaulting behavior;
see below.

   directory--a valid pathname directory.  Complicated defaulting
behavior; see below.

   name--a valid pathname name.  Complicated defaulting behavior; see
below.

   type--a valid pathname type.  Complicated defaulting behavior; see
below.

   version--a valid pathname version.  Complicated defaulting behavior;
see below.

   defaults--a pathname designator.  The default is a pathname whose
host component is the same as the host component of the value of
*default-pathname-defaults*, and whose other components are all nil.

   case--one of :common or :local.  The default is :local.

   pathname--a pathname.

Description::
.............

Constructs and returns a pathname from the supplied keyword arguments.

   After the components supplied explicitly by host, device, directory,
name, type, and version are filled in, the merging rules used by
merge-pathnames are used to fill in any unsupplied components from the
defaults supplied by defaults.

   Whenever a pathname is constructed the components may be
canonicalized if appropriate.  For the explanation of the arguments that
can be supplied for each component, see *note Pathname Components::.

   If case is supplied, it is treated as described in *note Case in
Pathname Components::.

   The resulting pathname is a logical pathname if and only its host
component is a logical host or a string that names a defined logical
host.

   If the directory is a string, it should be the name of a top level
directory, and should not contain any punctuation characters; that is,
specifying a string, str, is equivalent to specifying the list
(:absolute str).  Specifying the symbol :wild is equivalent to
specifying the list (:absolute :wild-inferiors), or (:absolute :wild) in
a file system that does not support :wild-inferiors.

Examples::
..........

      ;; Implementation A -- an implementation with access to a single
      ;;  Unix file system.  This implementation happens to never display
      ;;  the `host' information in a namestring, since there is only one host.
      (make-pathname :directory '(:absolute "public" "games")
                     :name "chess" :type "db")
     =>  #P"/public/games/chess.db"

      ;; Implementation B -- an implementation with access to one or more
      ;;  VMS file systems.  This implementation displays `host' information
      ;;  in the namestring only when the host is not the local host.
      ;;  It uses a double colon to separate a host name from the host's local
      ;;  file name.
      (make-pathname :directory '(:absolute "PUBLIC" "GAMES")
                     :name "CHESS" :type "DB")
     =>  #P"SYS$DISK:[PUBLIC.GAMES]CHESS.DB"
      (make-pathname :host "BOBBY"
                     :directory '(:absolute "PUBLIC" "GAMES")
                     :name "CHESS" :type "DB")
     =>  #P"BOBBY::SYS$DISK:[PUBLIC.GAMES]CHESS.DB"

      ;; Implementation C -- an implementation with simultaneous access to
      ;;  multiple file systems from the same Lisp image.  In this
      ;;  implementation, there is a convention that any text preceding the
      ;;  first colon in a pathname namestring is a host name.
      (dolist (case '(:common :local))
        (dolist (host '("MY-LISPM" "MY-VAX" "MY-UNIX"))
          (print (make-pathname :host host :case case
                                :directory '(:absolute "PUBLIC" "GAMES")
                                :name "CHESS" :type "DB"))))
      |>  #P"MY-LISPM:>public>games>chess.db"
      |>  #P"MY-VAX:SYS$DISK:[PUBLIC.GAMES]CHESS.DB"
      |>  #P"MY-UNIX:/public/games/chess.db"
      |>  #P"MY-LISPM:>public>games>chess.db"
      |>  #P"MY-VAX:SYS$DISK:[PUBLIC.GAMES]CHESS.DB"
      |>  #P"MY-UNIX:/PUBLIC/GAMES/CHESS.DB"
     =>  NIL

Affected By::
.............

The file system.

See Also::
..........

*note merge-pathnames:: , pathname, logical-pathname, *note File System
Concepts::,

   *note Pathnames as Filenames::

Notes::
.......

Portable programs should not supply :unspecific for any component.  See
*note ->UNSPECIFIC as a Component Value::.


File: gcl.info,  Node: pathnamep,  Next: pathname-host,  Prev: make-pathname,  Up: Filenames Dictionary

19.4.5 pathnamep [Function]
---------------------------

'pathnamep' object => generalized-boolean

Arguments and Values::
......................

object--an object.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if object is of type pathname; otherwise, returns false.

Examples::
..........

      (setq q "test")  =>  "test"
      (pathnamep q) =>  false
      (setq q (pathname "test"))
     =>  #S(PATHNAME :HOST NIL :DEVICE NIL :DIRECTORY NIL :NAME "test" :TYPE NIL
            :VERSION NIL)
      (pathnamep q) =>  true
      (setq q (logical-pathname "SYS:SITE;FOO.SYSTEM"))
     =>  #P"SYS:SITE;FOO.SYSTEM"
      (pathnamep q) =>  true

Notes::
.......

      (pathnamep object) == (typep object 'pathname)


File: gcl.info,  Node: pathname-host,  Next: load-logical-pathname-translations,  Prev: pathnamep,  Up: Filenames Dictionary

19.4.6 pathname-host, pathname-device, pathname-directory,
----------------------------------------------------------

pathname-name, pathname-type, pathname-version
----------------------------------------------

                                                             [Function]

   'pathname-host' pathname &key case => host

   'pathname-device' pathname &key case => device

   'pathname-directory' pathname &key case => directory

   'pathname-name' pathname &key case => name

   'pathname-type' pathname &key case => type

   'pathname-version' pathname => version

Arguments and Values::
......................

pathname--a pathname designator.

   case--one of :local or :common.  The default is :local.

   host--a valid pathname host.

   device--a valid pathname device.

   directory--a valid pathname directory.

   name--a valid pathname name.

   type--a valid pathname type.

   version--a valid pathname version.

Description::
.............

These functions return the components of pathname.

   If the pathname designator is a pathname, it represents the name used
to open the file.  This may be, but is not required to be, the actual
name of the file.

   If case is supplied, it is treated as described in *note Case in
Pathname Components::.

Examples::
..........

      (setq q (make-pathname :host "KATHY"
                             :directory "CHAPMAN"
                             :name "LOGIN" :type "COM"))
     =>  #P"KATHY::[CHAPMAN]LOGIN.COM"
      (pathname-host q) =>  "KATHY"
      (pathname-name q) =>  "LOGIN"
      (pathname-type q) =>  "COM"

      ;; Because namestrings are used, the results shown in the remaining
      ;; examples are not necessarily the only possible results.  Mappings
      ;; from namestring representation to pathname representation are
      ;; dependent both on the file system involved and on the implementation
      ;; (since there may be several implementations which can manipulate the
      ;; the same file system, and those implementations are not constrained
      ;; to agree on all details). Consult the documentation for each
      ;; implementation for specific information on how namestrings are treated
      ;; that implementation.

      ;; VMS
      (pathname-directory (parse-namestring "[FOO.*.BAR]BAZ.LSP"))
     =>  (:ABSOLUTE "FOO" "BAR")
      (pathname-directory (parse-namestring "[FOO.*.BAR]BAZ.LSP") :case :common)
     =>  (:ABSOLUTE "FOO" "BAR")

      ;; Unix
      (pathname-directory "foo.l") =>  NIL
      (pathname-device "foo.l") =>  :UNSPECIFIC
      (pathname-name "foo.l") =>  "foo"
      (pathname-name "foo.l" :case :local) =>  "foo"
      (pathname-name "foo.l" :case :common) =>  "FOO"
      (pathname-type "foo.l") =>  "l"
      (pathname-type "foo.l" :case :local) =>  "l"
      (pathname-type "foo.l" :case :common) =>  "L"
      (pathname-type "foo") =>  :UNSPECIFIC
      (pathname-type "foo" :case :common) =>  :UNSPECIFIC
      (pathname-type "foo.") =>  ""
      (pathname-type "foo." :case :common) =>  ""
      (pathname-directory (parse-namestring "/foo/bar/baz.lisp") :case :local)
     =>  (:ABSOLUTE "foo" "bar")
      (pathname-directory (parse-namestring "/foo/bar/baz.lisp") :case :local)
     =>  (:ABSOLUTE "FOO" "BAR")
      (pathname-directory (parse-namestring "../baz.lisp"))
     =>  (:RELATIVE :UP)
      (PATHNAME-DIRECTORY (PARSE-NAMESTRING "/foo/BAR/../Mum/baz"))
     =>  (:ABSOLUTE "foo" "BAR" :UP "Mum")
      (PATHNAME-DIRECTORY (PARSE-NAMESTRING "/foo/BAR/../Mum/baz") :case :common)
     =>  (:ABSOLUTE "FOO" "bar" :UP "Mum")
      (PATHNAME-DIRECTORY (PARSE-NAMESTRING "/foo/*/bar/baz.l"))
     =>  (:ABSOLUTE "foo" :WILD "bar")
      (PATHNAME-DIRECTORY (PARSE-NAMESTRING "/foo/*/bar/baz.l") :case :common)
     =>  (:ABSOLUTE "FOO" :WILD "BAR")

      ;; Symbolics LMFS
      (pathname-directory (parse-namestring ">foo>**>bar>baz.lisp"))
     =>  (:ABSOLUTE "foo" :WILD-INFERIORS "bar")
      (pathname-directory (parse-namestring ">foo>*>bar>baz.lisp"))
     =>  (:ABSOLUTE "foo" :WILD "bar")
      (pathname-directory (parse-namestring ">foo>*>bar>baz.lisp") :case :common)
     =>  (:ABSOLUTE "FOO" :WILD "BAR")
      (pathname-device (parse-namestring ">foo>baz.lisp")) =>  :UNSPECIFIC

Affected By::
.............

The implementation and the host file system.

Exceptional Situations::
........................

Should signal an error of type type-error if its first argument is not a
pathname.

See Also::
..........

pathname, logical-pathname, *note File System Concepts::,

   *note Pathnames as Filenames::


File: gcl.info,  Node: load-logical-pathname-translations,  Next: logical-pathname-translations,  Prev: pathname-host,  Up: Filenames Dictionary

19.4.7 load-logical-pathname-translations [Function]
----------------------------------------------------

'load-logical-pathname-translations' host => just-loaded

Arguments and Values::
......................

host--a string.

   just-loaded--a generalized boolean.

Description::
.............

Searches for and loads the definition of a logical host named host, if
it is not already defined.  The specific nature of the search is
implementation-defined.

   If the host is already defined, no attempt to find or load a
definition is attempted, and false is returned.  If the host is not
already defined, but a definition is successfully found and loaded, true
is returned.  Otherwise, an error is signaled.

Examples::
..........

      (translate-logical-pathname "hacks:weather;barometer.lisp.newest")
      |>  Error: The logical host HACKS is not defined.
      (load-logical-pathname-translations "HACKS")
      |>  ;; Loading SYS:SITE;HACKS.TRANSLATIONS
      |>  ;; Loading done.
     =>  true
      (translate-logical-pathname "hacks:weather;barometer.lisp.newest")
     =>  #P"HELIUM:[SHARED.HACKS.WEATHER]BAROMETER.LSP;0"
      (load-logical-pathname-translations "HACKS")
     =>  false

Exceptional Situations::
........................

If no definition is found, an error of type error is signaled.

See Also::
..........

logical-pathname

Notes::
.......

Logical pathname definitions will be created not just by implementors
but also by programmers.  As such, it is important that the search
strategy be documented.  For example, an implementation might define
that the definition of a host is to be found in a file called
"host.translations" in some specifically named directory.


File: gcl.info,  Node: logical-pathname-translations,  Next: logical-pathname,  Prev: load-logical-pathname-translations,  Up: Filenames Dictionary

19.4.8 logical-pathname-translations [Accessor]
-----------------------------------------------

'logical-pathname-translations' host => translations

   (setf (' logical-pathname-translations' host) new-translations)

Arguments and Values::
......................

host-a logical host designator.

   translations, new-translations--a list.

Description::
.............

Returns the host's list of translations.  Each translation is a list of
at least two elements: from-wildcard and to-wildcard.  Any additional
elements are implementation-defined.  From-wildcard is a logical
pathname whose host is host.  To-wildcard is a pathname.

   [Reviewer Note by Laddaga: Can this be a logical pathname?]

   (setf (logical-pathname-translations host) translations) sets a
logical pathname host's list of translations.  If host is a string that
has not been previously used as a logical pathname host, a new logical
pathname host is defined; otherwise an existing host's translations are
replaced.  logical pathname host names are compared with string-equal.

   When setting the translations list, each from-wildcard can be a
logical pathname whose host is host or a logical pathname namestring
parseable by (parse-namestring string host), where host represents the
appropriate object as defined by parse-namestring.  Each to-wildcard can
be anything coercible to a pathname by (pathname to-wildcard).  If
to-wildcard coerces to a logical pathname, translate-logical-pathname
will perform repeated translation steps when it uses it.

   host is either the host component of a logical pathname or a string
that has been defined as a logical pathname host name by setf of
logical-pathname-translations.

Examples::
..........

[Reviewer Note by Laddaga: Shouldn't there be some *.*'s in the list of
translations for PROG below?]

      ;;;A very simple example of setting up a logical pathname host.  No
      ;;;translations are necessary to get around file system restrictions, so
      ;;;all that is necessary is to specify the root of the physical directory
      ;;;tree that contains the logical file system.
      ;;;The namestring syntax on the right-hand side is implementation-dependent.
      (setf (logical-pathname-translations "foo")
            '(("**;*.*.*"              "MY-LISPM:>library>foo>**>")))

      ;;;Sample use of that logical pathname.  The return value
      ;;;is implementation-dependent.
      (translate-logical-pathname "foo:bar;baz;mum.quux.3")
     =>  #P"MY-LISPM:>library>foo>bar>baz>mum.quux.3"

      ;;;A more complex example, dividing the files among two file servers
      ;;;and several different directories.  This Unix doesn't support
      ;;;:WILD-INFERIORS in the directory, so each directory level must
      ;;;be translated individually.  No file name or type translations
      ;;;are required except for .MAIL to .MBX.
      ;;;The namestring syntax on the right-hand side is implementation-dependent.
      (setf (logical-pathname-translations "prog")
            '(("RELEASED;*.*.*"        "MY-UNIX:/sys/bin/my-prog/")
              ("RELEASED;*;*.*.*"      "MY-UNIX:/sys/bin/my-prog/*/")
              ("EXPERIMENTAL;*.*.*"    "MY-UNIX:/usr/Joe/development/prog/")
              ("EXPERIMENTAL;DOCUMENTATION;*.*.*"
                                       "MY-VAX:SYS$DISK:[JOE.DOC]")
              ("EXPERIMENTAL;*;*.*.*"  "MY-UNIX:/usr/Joe/development/prog/*/")
              ("MAIL;**;*.MAIL"        "MY-VAX:SYS$DISK:[JOE.MAIL.PROG...]*.MBX")))

      ;;;Sample use of that logical pathname.  The return value
      ;;;is implementation-dependent.
      (translate-logical-pathname "prog:mail;save;ideas.mail.3")
     =>  #P"MY-VAX:SYS$DISK:[JOE.MAIL.PROG.SAVE]IDEAS.MBX.3"

      ;;;Example translations for a program that uses three files main.lisp,
      ;;;auxiliary.lisp, and documentation.lisp.  These translations might be
      ;;;supplied by a software supplier as examples.

      ;;;For Unix with long file names
      (setf (logical-pathname-translations "prog")
            '(("CODE;*.*.*"             "/lib/prog/")))

      ;;;Sample use of that logical pathname.  The return value
      ;;;is implementation-dependent.
      (translate-logical-pathname "prog:code;documentation.lisp")
     =>  #P"/lib/prog/documentation.lisp"

      ;;;For Unix with 14-character file names, using .lisp as the type
      (setf (logical-pathname-translations "prog")
            '(("CODE;DOCUMENTATION.*.*" "/lib/prog/docum.*")
              ("CODE;*.*.*"             "/lib/prog/")))

      ;;;Sample use of that logical pathname.  The return value
      ;;;is implementation-dependent.
      (translate-logical-pathname "prog:code;documentation.lisp")
     =>  #P"/lib/prog/docum.lisp"

      ;;;For Unix with 14-character file names, using .l as the type
      ;;;The second translation shortens the compiled file type to .b
      (setf (logical-pathname-translations "prog")
            `(("**;*.LISP.*"            ,(logical-pathname "PROG:**;*.L.*"))
              (,(compile-file-pathname (logical-pathname "PROG:**;*.LISP.*"))
                                        ,(logical-pathname "PROG:**;*.B.*"))
              ("CODE;DOCUMENTATION.*.*" "/lib/prog/documentatio.*")
              ("CODE;*.*.*"             "/lib/prog/")))

      ;;;Sample use of that logical pathname.  The return value
      ;;;is implementation-dependent.
      (translate-logical-pathname "prog:code;documentation.lisp")
     =>  #P"/lib/prog/documentatio.l"

      ;;;For a Cray with 6 character names and no directories, types, or versions.
      (setf (logical-pathname-translations "prog")
            (let ((l '(("MAIN" "PGMN")
                       ("AUXILIARY" "PGAUX")
                       ("DOCUMENTATION" "PGDOC")))
                  (logpath (logical-pathname "prog:code;"))
                  (phypath (pathname "XXX")))
              (append
                ;; Translations for source files
                (mapcar #'(lambda (x)
                            (let ((log (first x))
                                  (phy (second x)))
                              (list (make-pathname :name log
                                                   :type "LISP"
                                                   :version :wild
                                                   :defaults logpath)
                                    (make-pathname :name phy
                                                   :defaults phypath))))
                        l)
                ;; Translations for compiled files
                (mapcar #'(lambda (x)
                            (let* ((log (first x))
                                   (phy (second x))
                                   (com (compile-file-pathname
                                          (make-pathname :name log
                                                         :type "LISP"
                                                         :version :wild
                                                         :defaults logpath))))
                              (setq phy (concatenate 'string phy "B"))
                              (list com
                                    (make-pathname :name phy
                                                   :defaults phypath))))
                        l))))

      ;;;Sample use of that logical pathname.  The return value
      ;;;is implementation-dependent.
      (translate-logical-pathname "prog:code;documentation.lisp")
     =>  #P"PGDOC"

Exceptional Situations::
........................

If host is incorrectly supplied, an error of type type-error is
signaled.

See Also::
..........

logical-pathname,

   *note Pathnames as Filenames::

Notes::
.......

Implementations can define additional functions that operate on logical
pathname hosts, for example to specify additional translation rules or
options.


File: gcl.info,  Node: logical-pathname,  Next: *default-pathname-defaults*,  Prev: logical-pathname-translations,  Up: Filenames Dictionary

19.4.9 logical-pathname [Function]
----------------------------------

'logical-pathname' pathspec => logical-pathname

Arguments and Values::
......................

pathspec--a logical pathname, a logical pathname namestring, or a
stream.

   logical-pathname--a logical pathname.

Description::
.............

logical-pathname converts pathspec to a logical pathname and returns the
new logical pathname.  If pathspec is a logical pathname namestring, it
should contain a host component and its following colon.  If pathspec is
a stream, it should be one for which pathname returns a logical
pathname.

   If pathspec is a stream, the stream can be either open or closed.
logical-pathname returns the same logical pathname after a file is
closed as it did when the file was open.

   It is an error if pathspec is a stream that is created with
make-two-way-stream, make-echo-stream, make-broadcast-stream,
make-concatenated-stream, make-string-input-stream, or
make-string-output-stream.

Exceptional Situations::
........................

Signals an error of type type-error if pathspec isn't supplied
correctly.

See Also::
..........

logical-pathname, *note translate-logical-pathname:: , *note Logical
Pathnames::


File: gcl.info,  Node: *default-pathname-defaults*,  Next: namestring,  Prev: logical-pathname,  Up: Filenames Dictionary

19.4.10 *default-pathname-defaults* [Variable]
----------------------------------------------

Value Type::
............

a pathname object.

Initial Value::
...............

An implementation-dependent pathname, typically in the working directory
that was current when Common Lisp was started up.

Description::
.............

a pathname, used as the default whenever a function needs a default
pathname and one is not supplied.

Examples::
..........

      ;; This example illustrates a possible usage for a hypothetical Lisp running on a
      ;; DEC TOPS-20 file system.  Since pathname conventions vary between Lisp
      ;; implementations and host file system types, it is not possible to provide a
      ;; general-purpose, conforming example.
      *default-pathname-defaults* =>  #P"PS:<FRED>"
      (merge-pathnames (make-pathname :name "CALENDAR"))
     =>  #P"PS:<FRED>CALENDAR"
      (let ((*default-pathname-defaults* (pathname "<MARY>")))
        (merge-pathnames (make-pathname :name "CALENDAR")))
     =>  #P"<MARY>CALENDAR"

Affected By::
.............

The implementation.


File: gcl.info,  Node: namestring,  Next: parse-namestring,  Prev: *default-pathname-defaults*,  Up: Filenames Dictionary

19.4.11 namestring, file-namestring, directory-namestring,
----------------------------------------------------------

host-namestring, enough-namestring
----------------------------------

                                                             [Function]

   'namestring' pathname => namestring

   'file-namestring' pathname => namestring

   'directory-namestring' pathname => namestring

   'host-namestring' pathname => namestring

   'enough-namestring' pathname &optional defaults => namestring

Arguments and Values::
......................

pathname--a pathname designator.

   defaults--a pathname designator.

   The default is the value of *default-pathname-defaults*.

   namestring--a string or nil.

   [Editorial Note by KMP: Under what circumstances can NIL be
returned??]

Description::
.............

These functions convert pathname into a namestring.  The name
represented by pathname is returned as a namestring in an
implementation-dependent canonical form.

   namestring returns the full form of pathname.

   file-namestring returns just the name, type, and version components
of pathname.

   directory-namestring returns the directory name portion.

   host-namestring returns the host name.

   enough-namestring returns an abbreviated namestring that is just
sufficient to identify the file named by pathname when considered
relative to the defaults.  It is required that

      (merge-pathnames (enough-namestring pathname defaults) defaults)
     == (merge-pathnames (parse-namestring pathname nil defaults) defaults)

   in all cases, and the result of enough-namestring is the shortest
reasonable string that will satisfy this criterion.

   It is not necessarily possible to construct a valid namestring by
concatenating some of the three shorter namestrings in some order.

Examples::
..........

      (namestring "getty")
     =>  "getty"
      (setq q (make-pathname :host "kathy"
                              :directory
                                (pathname-directory *default-pathname-defaults*)
                              :name "getty"))
     =>  #S(PATHNAME :HOST "kathy" :DEVICE NIL :DIRECTORY directory-name
            :NAME "getty" :TYPE NIL :VERSION NIL)
      (file-namestring q) =>  "getty"
      (directory-namestring q) =>  directory-name
      (host-namestring q) =>  "kathy"

      ;;;Using Unix syntax and the wildcard conventions used by the
      ;;;particular version of Unix on which this example was created:
      (namestring
        (translate-pathname "/usr/dmr/hacks/frob.l"
                            "/usr/d*/hacks/*.l"
                            "/usr/d*/backup/hacks/backup-*.*"))
     =>  "/usr/dmr/backup/hacks/backup-frob.l"
      (namestring
        (translate-pathname "/usr/dmr/hacks/frob.l"
                            "/usr/d*/hacks/fr*.l"
                            "/usr/d*/backup/hacks/backup-*.*"))
     =>  "/usr/dmr/backup/hacks/backup-ob.l"

      ;;;This is similar to the above example but uses two different hosts,
      ;;;U: which is a Unix and V: which is a VMS.  Note the translation
      ;;;of file type and alphabetic case conventions.
      (namestring
        (translate-pathname "U:/usr/dmr/hacks/frob.l"
                            "U:/usr/d*/hacks/*.l"
                            "V:SYS$DISK:[D*.BACKUP.HACKS]BACKUP-*.*"))
     =>  "V:SYS$DISK:[DMR.BACKUP.HACKS]BACKUP-FROB.LSP"
      (namestring
        (translate-pathname "U:/usr/dmr/hacks/frob.l"
                            "U:/usr/d*/hacks/fr*.l"
                            "V:SYS$DISK:[D*.BACKUP.HACKS]BACKUP-*.*"))
     =>  "V:SYS$DISK:[DMR.BACKUP.HACKS]BACKUP-OB.LSP"

See Also::
..........

*note truename:: , *note merge-pathnames:: , pathname, logical-pathname,
*note File System Concepts::,

   *note Pathnames as Filenames::


File: gcl.info,  Node: parse-namestring,  Next: wild-pathname-p,  Prev: namestring,  Up: Filenames Dictionary

19.4.12 parse-namestring [Function]
-----------------------------------

'parse-namestring' thing &optional host default-pathname &key start end
junk-allowed
=> pathname, position

Arguments and Values::
......................

thing--a string, a pathname, or a stream associated with a file.

   host--a valid pathname host, a logical host, or nil.

   default-pathname--a pathname designator.  The default is the value of
*default-pathname-defaults*.

   start, end--bounding index designators of thing.  The defaults for
start and end are 0 and nil, respectively.

   junk-allowed--a generalized boolean.  The default is false.

   pathname--a pathname, or nil.

   position--a bounding index designator for thing.

Description::
.............

Converts thing into a pathname.

   The host supplies a host name with respect to which the parsing
occurs.

   If thing is a stream associated with a file, processing proceeds as
if the pathname used to open that file had been supplied instead.

   If thing is a pathname, the host and the host component of thing are
compared.  If they match, two values are immediately returned: thing and
start; otherwise (if they do not match), an error is signaled.

   Otherwise (if thing is a string), parse-namestring parses the name of
a file within the substring of thing bounded by start and end.

   If thing is a string then the substring of thing bounded by start and
end is parsed into a pathname as follows:

*
     If host is a logical host then thing is parsed as a logical
     pathname namestring on the host.

*
     If host is nil and thing is a syntactically valid logical pathname
     namestring containing an explicit host, then it is parsed as a
     logical pathname namestring.

*
     If host is nil, default-pathname is a logical pathname, and thing
     is a syntactically valid logical pathname namestring without an
     explicit host, then it is parsed as a logical pathname namestring
     on the host that is the host component of default-pathname.

*
     Otherwise, the parsing of thing is implementation-defined.

   In the first of these cases, the host portion of the logical pathname
namestring and its following colon are optional.

   If the host portion of the namestring and host are both present and
do not match, an error is signaled.

   If junk-allowed is true, then the primary value is the pathname
parsed or, if no syntactically correct pathname was seen, nil.  If
junk-allowed is false, then the entire substring is scanned, and the
primary value is the pathname parsed.

   In either case, the secondary value is the index into thing of the
delimiter that terminated the parse, or the index beyond the substring
if the parse terminated at the end of the substring (as will always be
the case if junk-allowed is false).

   Parsing a null string always succeeds, producing a pathname with all
components (except the host) equal to nil.

   If thing contains an explicit host name and no explicit device name,
then it is implementation-defined whether parse-namestring will supply
the standard default device for that host as the device component of the
resulting pathname.

Examples::
..........

      (setq q (parse-namestring "test"))
     =>  #S(PATHNAME :HOST NIL :DEVICE NIL :DIRECTORY NIL :NAME "test"
            :TYPE NIL :VERSION NIL)
      (pathnamep q) =>  true
      (parse-namestring "test")
     =>  #S(PATHNAME :HOST NIL :DEVICE NIL :DIRECTORY NIL :NAME "test"
            :TYPE NIL :VERSION NIL), 4
      (setq s (open xxx)) =>  #<Input File Stream...>
      (parse-namestring s)
     =>  #S(PATHNAME :HOST NIL :DEVICE NIL :DIRECTORY NIL :NAME xxx
            :TYPE NIL :VERSION NIL), 0
      (parse-namestring "test" nil nil :start 2 :end 4 )
      =>  #S(PATHNAME ...), 15
      (parse-namestring "foo.lisp")
     =>  #P"foo.lisp"

Exceptional Situations::
........................

If junk-allowed is false, an error of type parse-error is signaled if
thing does not consist entirely of the representation of a pathname,
possibly surrounded on either side by whitespace_1 characters if that is
appropriate to the cultural conventions of the implementation.

   If host is supplied and not nil, and thing contains a manifest host
name, an error of type error is signaled if the hosts do not match.

   If thing is a logical pathname namestring and if the host portion of
the namestring and host are both present and do not match, an error of
type error is signaled.

See Also::
..........

pathname, logical-pathname, *note File System Concepts::,

   *note ->UNSPECIFIC as a Component Value::,

   *note Pathnames as Filenames::


File: gcl.info,  Node: wild-pathname-p,  Next: pathname-match-p,  Prev: parse-namestring,  Up: Filenames Dictionary

19.4.13 wild-pathname-p [Function]
----------------------------------

'wild-pathname-p' pathname &optional field-key => generalized-boolean

Arguments and Values::
......................

pathname--a pathname designator.

   Field-key--one of :host, :device :directory, :name, :type, :version,
or nil.

   generalized-boolean--a generalized boolean.

Description::
.............

wild-pathname-p tests pathname for the presence of wildcard components.

   If pathname is a pathname (as returned by pathname) it represents the
name used to open the file.  This may be, but is not required to be, the
actual name of the file.

   If field-key is not supplied or nil, wild-pathname-p returns true if
pathname has any wildcard components, nil if pathname has none.  If
field-key is non-nil, wild-pathname-p returns true if the indicated
component of pathname is a wildcard, nil if the component is not a
wildcard.

Examples::
..........

      ;;;The following examples are not portable.  They are written to run
      ;;;with particular file systems and particular wildcard conventions.
      ;;;Other implementations will behave differently.  These examples are
      ;;;intended to be illustrative, not to be prescriptive.

      (wild-pathname-p (make-pathname :name :wild)) =>  true
      (wild-pathname-p (make-pathname :name :wild) :name) =>  true
      (wild-pathname-p (make-pathname :name :wild) :type) =>  false
      (wild-pathname-p (pathname "s:>foo>**>")) =>  true ;Lispm
      (wild-pathname-p (pathname :name "F*O")) =>  true ;Most places

Exceptional Situations::
........................

If pathname is not a pathname, a string, or a stream associated with a
file an error of type type-error is signaled.

See Also::
..........

pathname, logical-pathname, *note File System Concepts::,

   *note Pathnames as Filenames::

Notes::
.......

Not all implementations support wildcards in all fields.  See *note
->WILD as a Component Value:: and *note Restrictions on Wildcard
Pathnames::.


File: gcl.info,  Node: pathname-match-p,  Next: translate-logical-pathname,  Prev: wild-pathname-p,  Up: Filenames Dictionary

19.4.14 pathname-match-p [Function]
-----------------------------------

'pathname-match-p' pathname wildcard => generalized-boolean

Arguments and Values::
......................

pathname--a pathname designator.

   wildcard--a designator for a wild pathname.

   generalized-boolean--a generalized boolean.

Description::
.............

pathname-match-p returns true if pathname matches wildcard, otherwise
nil.  The matching rules are implementation-defined but should be
consistent with directory.  Missing components of wildcard default to
:wild.

   It is valid for pathname to be a wild pathname; a wildcard field in
pathname only matches a wildcard field in wildcard (i.e.,
pathname-match-p is not commutative).  It is valid for wildcard to be a
non-wild pathname.

Exceptional Situations::
........................

If pathname or wildcard is not a pathname, string, or stream associated
with a file an error of type type-error is signaled.

See Also::
..........

*note directory:: , pathname, logical-pathname, *note File System
Concepts::,

   *note Pathnames as Filenames::


File: gcl.info,  Node: translate-logical-pathname,  Next: translate-pathname,  Prev: pathname-match-p,  Up: Filenames Dictionary

19.4.15 translate-logical-pathname [Function]
---------------------------------------------

'translate-logical-pathname' pathname &key => physical-pathname

Arguments and Values::
......................

pathname--a pathname designator, or a logical pathname namestring.

   physical-pathname--a physical pathname.

Description::
.............

Translates pathname to a physical pathname, which it returns.

   If pathname is a stream, the stream can be either open or closed.
translate-logical-pathname returns the same physical pathname after a
file is closed as it did when the file was open.

   It is an error if pathname is a stream that is created with
make-two-way-stream, make-echo-stream, make-broadcast-stream,
make-concatenated-stream, make-string-input-stream,
make-string-output-stream.

   If pathname is a logical pathname namestring, the host portion of the
logical pathname namestring and its following colon are required.

   Pathname is first coerced to a pathname.  If the coerced pathname is
a physical pathname, it is returned.  If the coerced pathname is a
logical pathname, the first matching translation (according to
pathname-match-p) of the logical pathname host is applied, as if by
calling translate-pathname.  If the result is a logical pathname, this
process is repeated.  When the result is finally a physical pathname, it
is returned.  If no translation matches, an error is signaled.

   translate-logical-pathname might perform additional translations,
typically to provide translation of file types to local naming
conventions, to accomodate physical file systems with limited length
names, or to deal with special character requirements such as
translating hyphens to underscores or uppercase letters to lowercase.
Any such additional translations are implementation-defined.  Some
implementations do no additional translations.

   There are no specified keyword arguments for
translate-logical-pathname, but implementations are permitted to extend
it by adding keyword arguments.

Examples::
..........

See logical-pathname-translations.

Exceptional Situations::
........................

If pathname is incorrectly supplied, an error of type type-error is
signaled.

   If no translation matches, an error of type file-error is signaled.

   [Editorial Note by KMP: Is file-error really right, or should it be
pathname-error?]

See Also::
..........

*note logical-pathname:: , *note logical-pathname-translations:: ,
logical-pathname, *note File System Concepts::,

   *note Pathnames as Filenames::


File: gcl.info,  Node: translate-pathname,  Next: merge-pathnames,  Prev: translate-logical-pathname,  Up: Filenames Dictionary

19.4.16 translate-pathname [Function]
-------------------------------------

'translate-pathname' source from-wildcard to-wildcard &key
=> translated-pathname

Arguments and Values::
......................

source--a pathname designator.

   from-wildcard--a pathname designator.

   to-wildcard--a pathname designator.

   translated-pathname--a pathname.

Description::
.............

translate-pathname translates source (that matches from-wildcard) into a
corresponding pathname that matches to-wildcard, and returns the
corresponding pathname.

   The resulting pathname is to-wildcard with each wildcard or missing
field replaced by a portion of source.  A "wildcard field" is a pathname
component with a value of :wild, a :wild element of a list-valued
directory component, or an implementation-defined portion of a
component, such as the "*" in the complex wildcard string "foo*bar" that
some implementations support.  An implementation that adds other
wildcard features, such as regular expressions, must define how
translate-pathname extends to those features.  A "missing field" is a
pathname component with a value of nil.

   The portion of source that is copied into the resulting pathname is
implementation-defined.  Typically it is determined by the user
interface conventions of the file systems involved.  Usually it is the
portion of source that matches a wildcard field of from-wildcard that is
in the same position as the wildcard or missing field of to-wildcard.
If there is no wildcard field in from-wildcard at that position, then
usually it is the entire corresponding pathname component of source, or
in the case of a list-valued directory component, the entire
corresponding list element.

   During the copying of a portion of source into the resulting
pathname, additional implementation-defined translations of case or file
naming conventions might occur, especially when from-wildcard and
to-wildcard are for different hosts.

   It is valid for source to be a wild pathname; in general this will
produce a wild result.  It is valid for from-wildcard and/or to-wildcard
to be non-wild pathnames.

   There are no specified keyword arguments for translate-pathname, but
implementations are permitted to extend it by adding keyword arguments.

   translate-pathname maps customary case in source into customary case
in the output pathname.

Examples::
..........

      ;; The results of the following five forms are all implementation-dependent.
      ;; The second item in particular is shown with multiple results just to
      ;; emphasize one of many particular variations which commonly occurs.
      (pathname-name (translate-pathname "foobar" "foo*" "*baz")) =>  "barbaz"
      (pathname-name (translate-pathname "foobar" "foo*" "*"))
     =>  "foobar"
     OR=> "bar"
      (pathname-name (translate-pathname "foobar" "*"    "foo*")) =>  "foofoobar"
      (pathname-name (translate-pathname "bar"    "*"    "foo*")) =>  "foobar"
      (pathname-name (translate-pathname "foobar" "foo*" "baz*")) =>  "bazbar"

      (defun translate-logical-pathname-1 (pathname rules)
        (let ((rule (assoc pathname rules :test #'pathname-match-p)))
          (unless rule (error "No translation rule for ~A" pathname))
          (translate-pathname pathname (first rule) (second rule))))
      (translate-logical-pathname-1 "FOO:CODE;BASIC.LISP"
                            '(("FOO:DOCUMENTATION;" "MY-UNIX:/doc/foo/")
                              ("FOO:CODE;"          "MY-UNIX:/lib/foo/")
                              ("FOO:PATCHES;*;"     "MY-UNIX:/lib/foo/patch/*/")))
     =>  #P"MY-UNIX:/lib/foo/basic.l"

     ;;;This example assumes one particular set of wildcard conventions
     ;;;Not all file systems will run this example exactly as written
      (defun rename-files (from to)
        (dolist (file (directory from))
          (rename-file file (translate-pathname file from to))))
      (rename-files "/usr/me/*.lisp" "/dev/her/*.l")
        ;Renames /usr/me/init.lisp to /dev/her/init.l
      (rename-files "/usr/me/pcl*/*" "/sys/pcl/*/")
        ;Renames /usr/me/pcl-5-may/low.lisp to /sys/pcl/pcl-5-may/low.lisp
        ;In some file systems the result might be /sys/pcl/5-may/low.lisp
      (rename-files "/usr/me/pcl*/*" "/sys/library/*/")
        ;Renames /usr/me/pcl-5-may/low.lisp to /sys/library/pcl-5-may/low.lisp
        ;In some file systems the result might be /sys/library/5-may/low.lisp
      (rename-files "/usr/me/foo.bar" "/usr/me2/")
        ;Renames /usr/me/foo.bar to /usr/me2/foo.bar
      (rename-files "/usr/joe/*-recipes.text" "/usr/jim/cookbook/joe's-*-rec.text")
        ;Renames /usr/joe/lamb-recipes.text to /usr/jim/cookbook/joe's-lamb-rec.text
        ;Renames /usr/joe/pork-recipes.text to /usr/jim/cookbook/joe's-pork-rec.text
        ;Renames /usr/joe/veg-recipes.text to /usr/jim/cookbook/joe's-veg-rec.text

Exceptional Situations::
........................

If any of source, from-wildcard, or to-wildcard is not a pathname, a
string, or a stream associated with a file an error of type type-error
is signaled.

   (pathname-match-p source from-wildcard) must be true or an error of
type error is signaled.

See Also::
..........

*note namestring:: , *note pathname-host:: ,

   pathname, logical-pathname, *note File System Concepts::,

   *note Pathnames as Filenames::

Notes::
.......

The exact behavior of translate-pathname cannot be dictated by the
Common Lisp language and must be allowed to vary, depending on the user
interface conventions of the file systems involved.

   The following is an implementation guideline.  One file system
performs this operation by examining each piece of the three pathnames
in turn, where a piece is a pathname component or a list element of a
structured component such as a hierarchical directory.  Hierarchical
directory elements in from-wildcard and to-wildcard are matched by
whether they are wildcards, not by depth in the directory hierarchy.  If
the piece in to-wildcard is present and not wild, it is copied into the
result.  If the piece in to-wildcard is :wild or nil, the piece in
source is copied into the result.  Otherwise, the piece in to-wildcard
might be a complex wildcard such as "foo*bar" and the piece in
from-wildcard should be wild; the portion of the piece in source that
matches the wildcard portion of the piece in from-wildcard replaces the
wildcard portion of the piece in to-wildcard and the value produced is
used in the result.


File: gcl.info,  Node: merge-pathnames,  Prev: translate-pathname,  Up: Filenames Dictionary

19.4.17 merge-pathnames [Function]
----------------------------------

'merge-pathnames' pathname &optional default-pathname default-version
=> merged-pathname

Arguments and Values::
......................

pathname--a pathname designator.

   default-pathname--a pathname designator.

   The default is the value of *default-pathname-defaults*.

   default-version--a valid pathname version.

   The default is :newest.

   merged-pathname--a pathname.

Description::
.............

Constructs a pathname from pathname by filling in any unsupplied
components with the corresponding values from default-pathname and
default-version.

   Defaulting of pathname components is done by filling in components
taken from another pathname.

   This is especially useful for cases such as a program that has an
input file and an output file.  Unspecified components of the output
pathname will come from the input pathname, except that the type should
not default to the type of the input pathname but rather to the
appropriate default type for output from the program; for example, see
the function compile-file-pathname.

   If no version is supplied, default-version is used.  If
default-version is nil, the version component will remain unchanged.

   If pathname explicitly specifies a host and not a device, and if the
host component of default-pathname matches the host component of
pathname, then the device is taken from the default-pathname; otherwise
the device will be the default file device for that host.  If pathname
does not specify a host, device, directory, name, or type, each such
component is copied from default-pathname.  If pathname does not specify
a name, then the version, if not provided, will come from
default-pathname, just like the other components.  If pathname does
specify a name, then the version is not affected by default-pathname.
If this process leaves the version missing, the default-version is used.
If the host's file name syntax provides a way to input a version without
a name or type, the user can let the name and type default but supply a
version different from the one in default-pathname.

   If pathname is a stream, pathname effectively becomes (pathname
pathname).  merge-pathnames can be used on either an open or a closed
stream.

   If pathname is a pathname it represents the name used to open the
file.  This may be, but is not required to be, the actual name of the
file.

   merge-pathnames recognizes a logical pathname namestring when
default-pathname is a logical pathname,

   or when the namestring begins with the name of a defined logical host
followed by a colon.  In the first of these two cases,

   the host portion of the logical pathname namestring and its following
colon are optional.

   merge-pathnames returns a logical pathname if and only if its first
argument is a logical pathname,

   or its first argument is a logical pathname namestring with an
explicit host, or its first argument does not specify a host and the
default-pathname is a logical pathname.

   Pathname merging treats a relative directory specially.  If
(pathname-directory pathname) is a list whose car is :relative, and
(pathname-directory default-pathname) is a list, then the merged
directory is the value of

      (append (pathname-directory default-pathname)
              (cdr  ;remove :relative from the front
                (pathname-directory pathname)))

   except that if the resulting list contains a string or :wild
immediately followed by :back, both of them are removed.  This removal
of redundant :back keywords is repeated as many times as possible.  If
(pathname-directory default-pathname) is not a list or
(pathname-directory pathname) is not a list whose car is :relative, the
merged directory is (or (pathname-directory pathname)
(pathname-directory default-pathname))

   merge-pathnames maps customary case in pathname into customary case
in the output pathname.

Examples::
..........

      (merge-pathnames "CMUC::FORMAT"
                       "CMUC::PS:<LISPIO>.FASL")
     =>  #P"CMUC::PS:<LISPIO>FORMAT.FASL.0"

See Also::
..........

*default-pathname-defaults*, pathname, logical-pathname, *note File
System Concepts::,

   *note Pathnames as Filenames::

Notes::
.......

The net effect is that if just a name is supplied, the host, device,
directory, and type will come from default-pathname, but the version
will come from default-version.  If nothing or just a directory is
supplied, the name, type, and version will come from default-pathname
together.


File: gcl.info,  Node: Files,  Next: Streams,  Prev: Filenames,  Up: Top

20 Files
********

* Menu:

* File System Concepts::
* Files Dictionary::


File: gcl.info,  Node: File System Concepts,  Next: Files Dictionary,  Prev: Files,  Up: Files

20.1 File System Concepts
=========================

This section describes the Common Lisp interface to file systems.  The
model used by this interface assumes that files are named by filenames ,
that a filename can be represented by a pathname object, and that given
a pathname a stream can be constructed that connects to a file whose
filename it represents.

   For information about opening and closing files, and manipulating
their contents, see *note Streams::.

   Figure 20-1 lists some operators that are applicable to files and
directories.

  compile-file  file-length      open            
  delete-file   file-position    probe-file      
  directory     file-write-date  rename-file     
  file-author   load             with-open-file  

    Figure 20-1: File and Directory Operations  


* Menu:

* Coercion of Streams to Pathnames::
* File Operations on Open and Closed Streams::
* Truenames::


File: gcl.info,  Node: Coercion of Streams to Pathnames,  Next: File Operations on Open and Closed Streams,  Prev: File System Concepts,  Up: File System Concepts

20.1.1 Coercion of Streams to Pathnames
---------------------------------------

A stream associated with a file is either a file stream or a synonym
stream whose target is a stream associated with a file .  Such streams
can be used as pathname designators.

   Normally, when a stream associated with a file is used as a pathname
designator, it denotes the pathname used to open the file; this may be,
but is not required to be, the actual name of the file.

   Some functions, such as truename and delete-file, coerce streams to
pathnames in a different way that involves referring to the actual file
that is open, which might or might not be the file whose name was opened
originally.  Such special situations are always notated specifically and
are not the default.


File: gcl.info,  Node: File Operations on Open and Closed Streams,  Next: Truenames,  Prev: Coercion of Streams to Pathnames,  Up: File System Concepts

20.1.2 File Operations on Open and Closed Streams
-------------------------------------------------

Many functions that perform file operations accept either open or closed
streams as arguments; see *note Stream Arguments to Standardized
Functions::.

   Of these, the functions in Figure 20-2 treat open and closed streams
differently.

  delete-file  file-author      probe-file  
  directory    file-write-date  truename    

  Figure 20-2: File Functions that Treat Open and Closed Streams Differently


   Since treatment of open streams by the file system may vary
considerably between implementations, however, a closed stream might be
the most reliable kind of argument for some of these functions--in
particular, those in Figure 20-3.  For example, in some file systems,
open files are written under temporary names and not renamed until
closed and/or are held invisible until closed.  In general, any code
that is intended to be portable should use such functions carefully.

  directory  probe-file  truename  

  Figure 20-3: File Functions where Closed Streams Might Work Best



File: gcl.info,  Node: Truenames,  Prev: File Operations on Open and Closed Streams,  Up: File System Concepts

20.1.3 Truenames
----------------

Many file systems permit more than one filename to designate a
particular file.

   Even where multiple names are possible, most file systems have a
convention for generating a canonical filename in such situations.  Such
a canonical filename (or the pathname representing such a filename) is
called a truename .

   The truename of a file may differ from other filenames for the file
because of symbolic links, version numbers, logical device translations
in the file system, logical pathname translations within Common Lisp, or
other artifacts of the file system.

   The truename for a file is often, but not necessarily, unique for
each file.  For instance, a Unix file with multiple hard links could
have several truenames.

* Menu:

* Examples of Truenames::


File: gcl.info,  Node: Examples of Truenames,  Prev: Truenames,  Up: Truenames

20.1.3.1 Examples of Truenames
..............................

For example, a DEC TOPS-20 system with files PS:<JOE>FOO.TXT.1 and
PS:<JOE>FOO.TXT.2 might permit the second file to be referred to as
PS:<JOE>FOO.TXT.0, since the ".0" notation denotes "newest" version of
several files.  In the same file system, a "logical device" "JOE:" might
be taken to refer to PS:<JOE>" and so the names JOE:FOO.TXT.2 or
JOE:FOO.TXT.0 might refer to PS:<JOE>FOO.TXT.2.  In all of these cases,
the truename of the file would probably be PS:<JOE>FOO.TXT.2.

   If a file is a symbolic link to another file (in a file system
permitting such a thing), it is conventional for the truename to be the
canonical name of the file after any symbolic links have been followed;
that is, it is the canonical name of the file whose contents would
become available if an input stream to that file were opened.

   In the case of a file still being created (that is, of an output
stream open to such a file), the exact truename of the file might not be
known until the stream is closed.  In this case, the function truename
might return different values for such a stream before and after it was
closed.  In fact, before it is closed, the name returned might not even
be a valid name in the file system--for example, while a file is being
written, it might have version :newest and might only take on a specific
numeric value later when the file is closed even in a file system where
all files have numeric versions.


File: gcl.info,  Node: Files Dictionary,  Prev: File System Concepts,  Up: Files

20.2 Files Dictionary
=====================

* Menu:

* directory::
* probe-file::
* ensure-directories-exist::
* truename::
* file-author::
* file-write-date::
* rename-file::
* delete-file::
* file-error::
* file-error-pathname::


File: gcl.info,  Node: directory,  Next: probe-file,  Prev: Files Dictionary,  Up: Files Dictionary

20.2.1 directory [Function]
---------------------------

'directory' pathspec &key => pathnames

Arguments and Values::
......................

pathspec--a pathname designator, which may contain wild components.

   pathnames--a list of

   physical pathnames.

Description::
.............

Determines which, if any, files that are present in the file system have
names matching pathspec, and returns a

   fresh

   list of pathnames corresponding to the truenames of those files.

   An implementation may be extended to accept implementation-defined
keyword arguments to directory.

Affected By::
.............

The host computer's file system.

Exceptional Situations::
........................

If the attempt to obtain a directory listing is not successful, an error
of type file-error is signaled.

See Also::
..........

pathname,

   logical-pathname,

   *note ensure-directories-exist:: , *note File System Concepts::,
*note File Operations on Open and Closed Streams::,

   *note Pathnames as Filenames::

Notes::
.......

If the pathspec is not wild, the resulting list will contain either zero
or one elements.

   Common Lisp specifies "&key" in the argument list to directory even
though no standardized keyword arguments to directory are defined.
":allow-other-keys t" may be used in conforming programs in order to
quietly ignore any additional keywords which are passed by the program
but not supported by the implementation.


File: gcl.info,  Node: probe-file,  Next: ensure-directories-exist,  Prev: directory,  Up: Files Dictionary

20.2.2 probe-file [Function]
----------------------------

'probe-file' pathspec => truename

Arguments and Values::
......................

pathspec--a pathname designator.

   truename--a physical pathname or nil.

Description::
.............

probe-file tests whether a file exists.

   probe-file returns false if there is no file named pathspec, and
otherwise returns the truename of pathspec.

   If the pathspec designator is an open stream, then probe-file
produces the truename of its associated file.

   If pathspec is a stream, whether open or closed, it is coerced to a
pathname as if by the function pathname.

Affected By::
.............

The host computer's file system.

Exceptional Situations::
........................

An error of type file-error is signaled if pathspec is wild.

   An error of type file-error is signaled if the file system cannot
perform the requested operation.

See Also::
..........

*note truename:: , *note open:: , *note ensure-directories-exist:: ,
pathname,

   logical-pathname,

   *note File System Concepts::, *note File Operations on Open and
Closed Streams::,

   *note Pathnames as Filenames::


File: gcl.info,  Node: ensure-directories-exist,  Next: truename,  Prev: probe-file,  Up: Files Dictionary

20.2.3 ensure-directories-exist [Function]
------------------------------------------

'ensure-directories-exist' pathspec &key verbose => pathspec, created

Arguments and Values::
......................

pathspec--a pathname designator.

   verbose--a generalized boolean.

   created--a generalized boolean.

Description::
.............

Tests whether the directories containing the specified file actually
exist, and attempts to create them if they do not.

   If the containing directories do not exist and if verbose is true,
then the implementation is permitted (but not required) to perform
output to standard output saying what directories were created.  If the
containing directories exist, or if verbose is false, this function
performs no output.

   The primary value is the given pathspec so that this operation can be
straightforwardly composed with other file manipulation expressions.
The secondary value, created, is true if any directories were created.

Affected By::
.............

The host computer's file system.

Exceptional Situations::
........................

An error of type file-error is signaled if the host, device, or
directory part of pathspec is wild.

   If the directory creation attempt is not successful, an error of type
file-error is signaled; if this occurs, it might be the case that none,
some, or all of the requested creations have actually occurred within
the file system.

See Also::
..........

*note probe-file:: , *note open:: ,

   *note Pathnames as Filenames::


File: gcl.info,  Node: truename,  Next: file-author,  Prev: ensure-directories-exist,  Up: Files Dictionary

20.2.4 truename [Function]
--------------------------

'truename' filespec => truename

Arguments and Values::
......................

filespec--a pathname designator.

   truename--a physical pathname.

Description::
.............

truename tries to find the file indicated by filespec and returns its
truename.  If the filespec designator is an open stream, its associated
file is used.

   If filespec is a stream, truename can be used whether the stream is
open or closed.  It is permissible for truename to return more specific
information after the stream is closed than when the stream was open.

   If filespec is a pathname it represents the name used to open the
file.  This may be, but is not required to be, the actual name of the
file.

Examples::
..........

     ;; An example involving version numbers.  Note that the precise nature of
     ;; the truename is implementation-dependent while the file is still open.
      (with-open-file (stream ">vistor>test.text.newest")
        (values (pathname stream)
                (truename stream)))
     =>  #P"S:>vistor>test.text.newest", #P"S:>vistor>test.text.1"
     OR=> #P"S:>vistor>test.text.newest", #P"S:>vistor>test.text.newest"
     OR=> #P"S:>vistor>test.text.newest", #P"S:>vistor>_temp_._temp_.1"

     ;; In this case, the file is closed when the truename is tried, so the
     ;; truename information is reliable.
      (with-open-file (stream ">vistor>test.text.newest")
        (close stream)
        (values (pathname stream)
                (truename stream)))
     =>  #P"S:>vistor>test.text.newest", #P"S:>vistor>test.text.1"

     ;; An example involving TOP-20's implementation-dependent concept
     ;; of logical devices -- in this case, "DOC:" is shorthand for
     ;; "PS:<DOCUMENTATION>" ...
      (with-open-file (stream "CMUC::DOC:DUMPER.HLP")
        (values (pathname stream)
                (truename stream)))
     =>  #P"CMUC::DOC:DUMPER.HLP", #P"CMUC::PS:<DOCUMENTATION>DUMPER.HLP.13"

Exceptional Situations::
........................

An error of type file-error is signaled if an appropriate file cannot be
located within the file system for the given filespec,

   or if the file system cannot perform the requested operation.

   An error of type file-error is signaled if pathname is wild.

See Also::
..........

pathname, logical-pathname, *note File System Concepts::,

   *note Pathnames as Filenames::

Notes::
.......

truename may be used to account for any filename translations performed
by the file system.


File: gcl.info,  Node: file-author,  Next: file-write-date,  Prev: truename,  Up: Files Dictionary

20.2.5 file-author [Function]
-----------------------------

'file-author' pathspec => author

Arguments and Values::
......................

pathspec--a pathname designator.

   author--a string or nil.

Description::
.............

Returns a string naming the author of the file specified by pathspec, or
nil if the author's name cannot be determined.

Examples::
..........

      (with-open-file (stream ">relativity>general.text")
        (file-author s))
     =>  "albert"

Affected By::
.............

The host computer's file system.

   Other users of the file named by pathspec.

Exceptional Situations::
........................

An error of type file-error is signaled if pathspec is wild.

   An error of type file-error is signaled if the file system cannot
perform the requested operation.

See Also::
..........

pathname, logical-pathname, *note File System Concepts::,

   *note Pathnames as Filenames::


File: gcl.info,  Node: file-write-date,  Next: rename-file,  Prev: file-author,  Up: Files Dictionary

20.2.6 file-write-date [Function]
---------------------------------

'file-write-date' pathspec => date

Arguments and Values::
......................

pathspec--a pathname designator.

   date--a universal time or nil.

Description::
.............

Returns a universal time representing the time at which the file
specified by pathspec was last written (or created), or returns nil if
such a time cannot be determined.

Examples::
..........

      (with-open-file (s "noel.text"
                         :direction :output :if-exists :error)
        (format s "~&Dear Santa,~2
                     Please leave lots of toys.~2
                  ~2
        (truename s))
     =>  #P"CUPID:/susan/noel.text"
      (with-open-file (s "noel.text")
        (file-write-date s))
     =>  2902600800

Affected By::
.............

The host computer's file system.

Exceptional Situations::
........................

An error of type file-error is signaled if pathspec is wild.

   An error of type file-error is signaled if the file system cannot
perform the requested operation.

See Also::
..........

*note Universal Time::,

   *note Pathnames as Filenames::


File: gcl.info,  Node: rename-file,  Next: delete-file,  Prev: file-write-date,  Up: Files Dictionary

20.2.7 rename-file [Function]
-----------------------------

'rename-file' filespec new-name => defaulted-new-name, old-truename,
new-truename

Arguments and Values::
......................

filespec--a pathname designator.

   new-name--a pathname designator other than a stream.

   defaulted-new-name--a pathname

   old-truename--a physical pathname.

   new-truename--a physical pathname.

Description::
.............

rename-file modifies the file system in such a way that the file
indicated by filespec is renamed to defaulted-new-name.

   It is an error to specify a filename containing a wild component, for
filespec to contain a nil component where the file system does not
permit a nil component, or for the result of defaulting missing
components of new-name from filespec to contain a nil component where
the file system does not permit a nil component.

   If new-name is a logical pathname, rename-file returns a logical
pathname as its primary value.

   rename-file returns three values if successful.  The primary value,
defaulted-new-name, is the resulting name which is composed of new-name
with any missing components filled in by performing a merge-pathnames
operation using filespec as the defaults.  The secondary value,
old-truename, is the truename of the file before it was renamed.  The
tertiary value, new-truename, is the truename of the file after it was
renamed.

   If the filespec designator is an open stream, then the stream itself
and the file associated with it are affected (if the file system
permits).

Examples::
..........

     ;; An example involving logical pathnames.
      (with-open-file (stream "sys:chemistry;lead.text"
                              :direction :output :if-exists :error)
        (princ "eureka" stream)
        (values (pathname stream) (truename stream)))
     =>  #P"SYS:CHEMISTRY;LEAD.TEXT.NEWEST", #P"Q:>sys>chem>lead.text.1"
      (rename-file "sys:chemistry;lead.text" "gold.text")
     =>  #P"SYS:CHEMISTRY;GOLD.TEXT.NEWEST",
        #P"Q:>sys>chem>lead.text.1",
        #P"Q:>sys>chem>gold.text.1"

Exceptional Situations::
........................

If the renaming operation is not successful, an error of type file-error
is signaled.

   An error of type file-error might be signaled if filespec is wild.

See Also::
..........

*note truename:: , pathname, logical-pathname, *note File System
Concepts::,

   *note Pathnames as Filenames::


File: gcl.info,  Node: delete-file,  Next: file-error,  Prev: rename-file,  Up: Files Dictionary

20.2.8 delete-file [Function]
-----------------------------

'delete-file' filespec => t

Arguments and Values::
......................

filespec--a pathname designator.

Description::
.............

Deletes the file specified by filespec.

   If the filespec designator is an open stream, then filespec and the
file associated with it are affected (if the file system permits), in
which case filespec might be closed immediately, and the deletion might
be immediate or delayed until filespec is explicitly closed, depending
on the requirements of the file system.

   It is implementation-dependent whether an attempt to delete a
nonexistent file is considered to be successful.

   delete-file returns true if it succeeds, or signals an error of type
file-error if it does not.

   The consequences are undefined if filespec has a wild component, or
if filespec has a nil component and the file system does not permit a
nil component.

Examples::
..........

      (with-open-file (s "delete-me.text" :direction :output :if-exists :error))
     =>  NIL
      (setq p (probe-file "delete-me.text")) =>  #P"R:>fred>delete-me.text.1"
      (delete-file p) =>  T
      (probe-file "delete-me.text") =>  false
      (with-open-file (s "delete-me.text" :direction :output :if-exists :error)
        (delete-file s))
     =>  T
      (probe-file "delete-me.text") =>  false

Exceptional Situations::
........................

If the deletion operation is not successful, an error of type file-error
is signaled.

   An error of type file-error might be signaled if filespec is wild.

See Also::
..........

pathname, logical-pathname, *note File System Concepts::,

   *note Pathnames as Filenames::


File: gcl.info,  Node: file-error,  Next: file-error-pathname,  Prev: delete-file,  Up: Files Dictionary

20.2.9 file-error [Condition Type]
----------------------------------

Class Precedence List::
.......................

file-error, error, serious-condition, condition, t

Description::
.............

The type file-error consists of error conditions that occur during an
attempt to open or close a file, or during some low-level transactions
with a file system.  The "offending pathname" is initialized by the
:pathname initialization argument to make-condition, and is accessed by
the function file-error-pathname.

See Also::
..........

file-error-pathname, *note open:: , *note probe-file:: , *note
directory:: , *note ensure-directories-exist::


File: gcl.info,  Node: file-error-pathname,  Prev: file-error,  Up: Files Dictionary

20.2.10 file-error-pathname [Function]
--------------------------------------

'file-error-pathname' condition => pathspec

Arguments and Values::
......................

condition--a condition of type file-error.

   pathspec--a pathname designator.

Description::
.............

Returns the "offending pathname" of a condition of type file-error.

Exceptional Situations::
........................

See Also::
..........

file-error, *note Conditions::


File: gcl.info,  Node: Streams,  Next: Printer,  Prev: Files,  Up: Top

21 Streams
**********

* Menu:

* Stream Concepts::
* Streams Dictionary::


File: gcl.info,  Node: Stream Concepts,  Next: Streams Dictionary,  Prev: Streams,  Up: Streams

21.1 Stream Concepts
====================

* Menu:

* Introduction to Streams::
* Stream Variables::
* Stream Arguments to Standardized Functions::
* Restrictions on Composite Streams::


File: gcl.info,  Node: Introduction to Streams,  Next: Stream Variables,  Prev: Stream Concepts,  Up: Stream Concepts

21.1.1 Introduction to Streams
------------------------------

A stream is an object that can be used with an input or output function
to identify an appropriate source or sink of characters or bytes for
that operation.  A character stream is a source or sink of characters.
A binary stream is a source or sink of bytes.

   Some operations may be performed on any kind of stream; Figure 21-1
provides a list of standardized operations that are potentially useful
with any kind of stream.

  close                 stream-element-type  
  input-stream-p        streamp              
  interactive-stream-p  with-open-stream     
  output-stream-p                            

  Figure 21-1: Some General-Purpose Stream Operations


   Other operations are only meaningful on certain stream types.  For
example, read-char is only defined for character streams and read-byte
is only defined for binary streams.

* Menu:

* Abstract Classifications of Streams (Introduction to Streams)::
* Input::
* Open and Closed Streams::
* Interactive Streams::
* Abstract Classifications of Streams::
* File Streams::
* Other Subclasses of Stream::


File: gcl.info,  Node: Abstract Classifications of Streams (Introduction to Streams),  Next: Input,  Prev: Introduction to Streams,  Up: Introduction to Streams

21.1.1.1 Abstract Classifications of Streams
............................................


File: gcl.info,  Node: Input,  Next: Open and Closed Streams,  Prev: Abstract Classifications of Streams (Introduction to Streams),  Up: Introduction to Streams

21.1.1.2 Input, Output, and Bidirectional Streams
.................................................

A stream, whether a character stream or a binary stream, can be an input
stream (source of data), an output stream (sink for data), both, or
(e.g., when ":direction :probe" is given to open) neither.

   Figure 21-2 shows operators relating to input streams.

  clear-input  read-byte            read-from-string            
  listen       read-char            read-line                   
  peek-char    read-char-no-hang    read-preserving-whitespace  
  read         read-delimited-list  unread-char                 

        Figure 21-2: Operators relating to Input Streams.      


   Figure 21-3 shows operators relating to output streams.

  clear-output   prin1            write            
  finish-output  prin1-to-string  write-byte       
  force-output   princ            write-char       
  format         princ-to-string  write-line       
  fresh-line     print            write-string     
  pprint         terpri           write-to-string  

  Figure 21-3: Operators relating to Output Streams.


   A stream that is both an input stream and an output stream is called
a bidirectional stream .  See the functions input-stream-p and
output-stream-p.

   Any of the operators listed in Figure~21-2 or Figure~21-3 can be used
with bidirectional streams.  In addition, Figure 21-4 shows a list of
operators that relate specificaly to bidirectional streams.

  y-or-n-p  yes-or-no-p    

  Figure 21-4: Operators relating to Bidirectional Streams.



File: gcl.info,  Node: Open and Closed Streams,  Next: Interactive Streams,  Prev: Input,  Up: Introduction to Streams

21.1.1.3 Open and Closed Streams
................................

Streams are either open or closed .

   Except as explicitly specified otherwise, operations that create and
return streams return open streams.

   The action of closing a stream marks the end of its use as a source
or sink of data, permitting the implementation to reclaim its internal
data structures, and to free any external resources which might have
been locked by the stream when it was opened.

   Except as explicitly specified otherwise, the consequences are
undefined when a closed stream is used where a stream is called for.

   Coercion of streams to pathnames is permissible for closed streams;
in some situations, such as for a truename computation, the result might
be different for an open stream and for that same stream once it has
been closed.


File: gcl.info,  Node: Interactive Streams,  Next: Abstract Classifications of Streams,  Prev: Open and Closed Streams,  Up: Introduction to Streams

21.1.1.4 Interactive Streams
............................

An interactive stream is one on which it makes sense to perform
interactive querying.

   The precise meaning of an interactive stream is
implementation-defined, and may depend on the underlying operating
system.  Some examples of the things that an implementation might choose
to use as identifying characteristics of an interactive stream include:

*
     The stream is connected to a person (or equivalent) in such a way
     that the program can prompt for information and expect to receive
     different input depending on the prompt.

*
     The program is expected to prompt for input and support "normal
     input editing".

*
     read-char might wait for the user to type something before
     returning instead of immediately returning a character or
     end-of-file.

   The general intent of having some streams be classified as
interactive streams is to allow them to be distinguished from streams
containing batch (or background or command-file) input.  Output to batch
streams is typically discarded or saved for later viewing, so
interactive queries to such streams might not have the expected effect.

   Terminal I/O might or might not be an interactive stream.


File: gcl.info,  Node: Abstract Classifications of Streams,  Next: File Streams,  Prev: Interactive Streams,  Up: Introduction to Streams

21.1.1.5 Abstract Classifications of Streams
............................................


File: gcl.info,  Node: File Streams,  Next: Other Subclasses of Stream,  Prev: Abstract Classifications of Streams,  Up: Introduction to Streams

21.1.1.6 File Streams
.....................

Some streams, called file streams , provide access to files.  An object
of class file-stream is used to represent a file stream.

   The basic operation for opening a file is open, which typically
returns a file stream (see its dictionary entry for details).  The basic
operation for closing a stream is close.  The macro with-open-file is
useful to express the common idiom of opening a file for the duration of
a given body of code, and assuring that the resulting stream is closed
upon exit from that body.


File: gcl.info,  Node: Other Subclasses of Stream,  Prev: File Streams,  Up: Introduction to Streams

21.1.1.7 Other Subclasses of Stream
...................................

The class stream has a number of subclasses defined by this
specification.  Figure 21-5 shows some information about these
subclasses.

  Class                Related Operators             
  broadcast-stream     make-broadcast-stream         
                       broadcast-stream-streams      
  concatenated-stream  make-concatenated-stream      
                       concatenated-stream-streams   
  echo-stream          make-echo-stream              
                       echo-stream-input-stream      
                       echo-stream-output-stream     
  string-stream        make-string-input-stream      
                       with-input-from-string        
                       make-string-output-stream     
                       with-output-to-string         
                       get-output-stream-string      
  synonym-stream       make-synonym-stream           
                       synonym-stream-symbol         
  two-way-stream       make-two-way-stream           
                       two-way-stream-input-stream   
                       two-way-stream-output-stream  

  Figure 21-5: Defined Names related to Specialized Streams



File: gcl.info,  Node: Stream Variables,  Next: Stream Arguments to Standardized Functions,  Prev: Introduction to Streams,  Up: Stream Concepts

21.1.2 Stream Variables
-----------------------

Variables whose values must be streams are sometimes called stream
variables .

   Certain stream variables are defined by this specification to be the
proper source of input or output in various situations where no specific
stream has been specified instead.  A complete list of such standardized
stream variables appears in Figure 21-6.  The consequences are undefined
if at any time the value of any of these variables is not an open
stream.

  Glossary Term    Variable Name      
  debug I/O        *debug-io*         
  error output     *error-output*     
  query I/O        *query-io*         
  standard input   *standard-input*   
  standard output  *standard-output*  
  terminal I/O     *terminal-io*      
  trace output     *trace-output*     

  Figure 21-6: Standardized Stream Variables


   Note that, by convention, standardized stream variables have names
ending in "-input*" if they must be input streams, ending in "-output*"
if they must be output streams, or ending in "-io*" if they must be
bidirectional streams.

   User programs may assign or bind any standardized stream variable
except *terminal-io*.


File: gcl.info,  Node: Stream Arguments to Standardized Functions,  Next: Restrictions on Composite Streams,  Prev: Stream Variables,  Up: Stream Concepts

21.1.3 Stream Arguments to Standardized Functions
-------------------------------------------------

The operators in Figure 21-7 accept stream arguments that might be
either open or closed streams.

  broadcast-stream-streams     file-author       pathnamep                     
  close                        file-namestring   probe-file                    
  compile-file                 file-write-date   rename-file                   
  compile-file-pathname        host-namestring   streamp                       
  concatenated-stream-streams  load              synonym-stream-symbol         
  delete-file                  logical-pathname  translate-logical-pathname    
  directory                    merge-pathnames   translate-pathname            
  directory-namestring         namestring        truename                      
  dribble                      open              two-way-stream-input-stream   
  echo-stream-input-stream     open-stream-p     two-way-stream-output-stream  
  echo-stream-ouput-stream     parse-namestring  wild-pathname-p               
  ed                           pathname          with-open-file                
  enough-namestring            pathname-match-p                                

        Figure 21-7: Operators that accept either Open or Closed Streams      


   The operators in Figure 21-8 accept stream arguments that must be
open streams.

 clear-input              output-stream-p         read-char-no-hang          
 clear-output             peek-char               read-delimited-list        
 file-length              pprint                  read-line                  
 file-position            pprint-fill             read-preserving-whitespace 
 file-string-length       pprint-indent           stream-element-type        
 finish-output            pprint-linear           stream-external-format     
 force-output             pprint-logical-block    terpri                     
 format                   pprint-newline          unread-char                
 fresh-line               pprint-tab              with-open-stream           
 get-output-stream-string pprint-tabular          write                      
 input-stream-p           prin1                   write-byte                 
 interactive-stream-p     princ                   write-char                 
 listen                   print                   write-line                 
 make-broadcast-stream    print-object            write-string               
 make-concatenated-stream print-unreadable-object y-or-n-p                   
 make-echo-stream         read                    yes-or-no-p                
 make-synonym-stream      read-byte                                          
 make-two-way-stream      read-char                                          

             Figure 21-8: Operators that accept Open Streams only            



File: gcl.info,  Node: Restrictions on Composite Streams,  Prev: Stream Arguments to Standardized Functions,  Up: Stream Concepts

21.1.4 Restrictions on Composite Streams
----------------------------------------

The consequences are undefined if any component of a composite stream is
closed before the composite stream is closed.

   The consequences are undefined if the synonym stream symbol is not
bound to an open stream from the time of the synonym stream's creation
until the time it is closed.


File: gcl.info,  Node: Streams Dictionary,  Prev: Stream Concepts,  Up: Streams

21.2 Streams Dictionary
=======================

* Menu:

* stream::
* broadcast-stream::
* concatenated-stream::
* echo-stream::
* file-stream::
* string-stream::
* synonym-stream::
* two-way-stream::
* input-stream-p::
* interactive-stream-p::
* open-stream-p::
* stream-element-type::
* streamp::
* read-byte::
* write-byte::
* peek-char::
* read-char::
* read-char-no-hang::
* terpri::
* unread-char::
* write-char::
* read-line::
* write-string::
* read-sequence::
* write-sequence::
* file-length::
* file-position::
* file-string-length::
* open::
* stream-external-format::
* with-open-file::
* close::
* with-open-stream::
* listen::
* clear-input::
* finish-output::
* y-or-n-p::
* make-synonym-stream::
* synonym-stream-symbol::
* broadcast-stream-streams::
* make-broadcast-stream::
* make-two-way-stream::
* two-way-stream-input-stream::
* echo-stream-input-stream::
* make-echo-stream::
* concatenated-stream-streams::
* make-concatenated-stream::
* get-output-stream-string::
* make-string-input-stream::
* make-string-output-stream::
* with-input-from-string::
* with-output-to-string::
* *debug-io*::
* *terminal-io*::
* stream-error::
* stream-error-stream::
* end-of-file::


File: gcl.info,  Node: stream,  Next: broadcast-stream,  Prev: Streams Dictionary,  Up: Streams Dictionary

21.2.1 stream [System Class]
----------------------------

Class Precedence List::
.......................

stream, t

Description::
.............

A stream is an object that can be used with an input or output function
to identify an appropriate source or sink of characters or bytes for
that operation.

   For more complete information, see *note Stream Concepts::.

See Also::
..........

*note Stream Concepts::, *note Printing Other Objects::, *note
Printer::, *note Reader::


File: gcl.info,  Node: broadcast-stream,  Next: concatenated-stream,  Prev: stream,  Up: Streams Dictionary

21.2.2 broadcast-stream [System Class]
--------------------------------------

Class Precedence List::
.......................

broadcast-stream, stream, t

Description::
.............

A broadcast stream is an output stream which has associated with it a
set of zero or more output streams such that any output sent to the
broadcast stream gets passed on as output to each of the associated
output streams.  (If a broadcast stream has no component streams, then
all output to the broadcast stream is discarded.)

   The set of operations that may be performed on a broadcast stream is
the intersection of those for its associated output streams.

   Some output operations (e.g., fresh-line) return values based on the
state of the stream at the time of the operation.

   Since these values might differ for each of the component streams, it
is necessary to describe their return value specifically:

*
     stream-element-type returns the value from the last component
     stream, or t if there are no component streams.

*
     fresh-line returns the value from the last component stream, or nil
     if there are no component streams.

*
     The functions file-length, file-position, file-string-length, and
     stream-external-format return the value from the last component
     stream; if there are no component streams, file-length and
     file-position return 0, file-string-length returns 1, and
     stream-external-format returns :default.

*
     The functions streamp and output-stream-p always return true for
     broadcast streams.

*
     The functions open-stream-p tests whether the broadcast stream is
     open_2, not whether its component streams are open.

*
     The functions input-stream-p and interactive-stream-p return an
     implementation-defined, generalized boolean value.

*
     For the input operations clear-input listen, peek-char, read-byte,
     read-char-no-hang, read-char, read-line, and unread-char, the
     consequences are undefined if the indicated operation is performed.
     However, an implementation is permitted to define such a behavior
     as an implementation-dependent extension.

   For any output operations not having their return values explicitly
specified above or elsewhere in this document, it is defined that the
values returned by such an operation are the values resulting from
performing the operation on the last of its component streams; the
values resulting from performing the operation on all preceding streams
are discarded.  If there are no component streams, the value is
implementation-dependent.

See Also::
..........

*note broadcast-stream-streams:: , *note make-broadcast-stream::


File: gcl.info,  Node: concatenated-stream,  Next: echo-stream,  Prev: broadcast-stream,  Up: Streams Dictionary

21.2.3 concatenated-stream [System Class]
-----------------------------------------

Class Precedence List::
.......................

concatenated-stream, stream, t

Description::
.............

A concatenated stream is an input stream which is a composite stream of
zero or more other input streams, such that the sequence of data which
can be read from the concatenated stream is the same as the
concatenation of the sequences of data which could be read from each of
the constituent streams.

   Input from a concatenated stream is taken from the first of the
associated input streams until it reaches end of file_1; then that
stream is discarded, and subsequent input is taken from the next input
stream, and so on.  An end of file on the associated input streams is
always managed invisibly by the concatenated stream--the only time a
client of a concatenated stream sees an end of file is when an attempt
is made to obtain data from the concatenated stream but it has no
remaining input streams from which to obtain such data.

See Also::
..........

*note concatenated-stream-streams:: , *note make-concatenated-stream::


File: gcl.info,  Node: echo-stream,  Next: file-stream,  Prev: concatenated-stream,  Up: Streams Dictionary

21.2.4 echo-stream [System Class]
---------------------------------

Class Precedence List::
.......................

echo-stream, stream, t

Description::
.............

An echo stream is a bidirectional stream that gets its input from an
associated input stream and sends its output to an associated output
stream.

   All input taken from the input stream is echoed to the output stream.
Whether the input is echoed immediately after it is encountered, or
after it has been read from the input stream is
implementation-dependent.

See Also::
..........

*note echo-stream-input-stream:: , echo-stream-output-stream, *note
make-echo-stream::


File: gcl.info,  Node: file-stream,  Next: string-stream,  Prev: echo-stream,  Up: Streams Dictionary

21.2.5 file-stream [System Class]
---------------------------------

Class Precedence List::
.......................

file-stream, stream, t

Description::
.............

An object of type file-stream is a stream the direct source or sink of
which is a file.  Such a stream is created explicitly by open and
with-open-file, and implicitly by functions such as load that process
files.

See Also::
..........

*note load:: , *note open:: , *note with-open-file::


File: gcl.info,  Node: string-stream,  Next: synonym-stream,  Prev: file-stream,  Up: Streams Dictionary

21.2.6 string-stream [System Class]
-----------------------------------

Class Precedence List::
.......................

string-stream, stream, t

Description::
.............

A string stream is a stream which reads input from or writes output to
an associated string.

   The stream element type of a string stream is always a subtype of
type character.

See Also::
..........

*note make-string-input-stream:: , *note make-string-output-stream:: ,
*note with-input-from-string:: , *note with-output-to-string::


File: gcl.info,  Node: synonym-stream,  Next: two-way-stream,  Prev: string-stream,  Up: Streams Dictionary

21.2.7 synonym-stream [System Class]
------------------------------------

Class Precedence List::
.......................

synonym-stream, stream, t

Description::
.............

A stream that is an alias for another stream, which is the value of a
dynamic variable whose name is the synonym stream symbol of the synonym
stream.

   Any operations on a synonym stream will be performed on the stream
that is then the value of the dynamic variable named by the synonym
stream symbol.  If the value of the variable should change, or if the
variable should be bound, then the stream will operate on the new value
of the variable.

See Also::
..........

*note make-synonym-stream:: , *note synonym-stream-symbol::


File: gcl.info,  Node: two-way-stream,  Next: input-stream-p,  Prev: synonym-stream,  Up: Streams Dictionary

21.2.8 two-way-stream [System Class]
------------------------------------

Class Precedence List::
.......................

two-way-stream, stream, t

Description::
.............

A bidirectional composite stream that receives its input from an
associated input stream and sends its output to an associated output
stream.

See Also::
..........

*note make-two-way-stream:: , *note two-way-stream-input-stream:: ,
two-way-stream-output-stream


File: gcl.info,  Node: input-stream-p,  Next: interactive-stream-p,  Prev: two-way-stream,  Up: Streams Dictionary

21.2.9 input-stream-p, output-stream-p [Function]
-------------------------------------------------

'input-stream-p' stream => generalized-boolean

   'output-stream-p' stream => generalized-boolean

Arguments and Values::
......................

stream--a stream.

   generalized-boolean--a generalized boolean.

Description::
.............

input-stream-p returns true if stream is an input stream; otherwise,
returns false.

   output-stream-p returns true if stream is an output stream;
otherwise, returns false.

Examples::
..........

      (input-stream-p *standard-input*) =>  true
      (input-stream-p *terminal-io*) =>  true
      (input-stream-p (make-string-output-stream)) =>  false

      (output-stream-p *standard-output*) =>  true
      (output-stream-p *terminal-io*) =>  true
      (output-stream-p (make-string-input-stream "jr")) =>  false

Exceptional Situations::
........................

Should signal an error of type type-error if stream is not a stream.


File: gcl.info,  Node: interactive-stream-p,  Next: open-stream-p,  Prev: input-stream-p,  Up: Streams Dictionary

21.2.10 interactive-stream-p [Function]
---------------------------------------

'interactive-stream-p' stream => generalized-boolean

Arguments and Values::
......................

stream--a stream.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if stream is an interactive stream; otherwise, returns
false.

Examples::
..........

      (when (> measured limit)
        (let ((error (round (* (- measured limit) 100)
                            limit)))
          (unless (if (interactive-stream-p *query-io*)
                      (yes-or-no-p "The frammis is out of tolerance by ~D
                                    Is it safe to proceed? " error)
                      (< error 15))  ;15
            (error "The frammis is out of tolerance by ~D

Exceptional Situations::
........................

Should signal an error of type type-error if stream is not a stream.

See Also::
..........

*note Stream Concepts::


File: gcl.info,  Node: open-stream-p,  Next: stream-element-type,  Prev: interactive-stream-p,  Up: Streams Dictionary

21.2.11 open-stream-p [Function]
--------------------------------

'open-stream-p' stream => generalized-boolean

Arguments and Values::
......................

stream--a stream.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if stream is an open stream; otherwise, returns false.

   Streams are open until they have been explicitly closed with close,
or until they are implicitly closed due to exit from a
with-output-to-string, with-open-file, with-input-from-string, or
with-open-stream form.

Examples::
..........

      (open-stream-p *standard-input*) =>  true

Affected By::
.............

close.

Exceptional Situations::
........................

Should signal an error of type type-error if stream is not a stream.


File: gcl.info,  Node: stream-element-type,  Next: streamp,  Prev: open-stream-p,  Up: Streams Dictionary

21.2.12 stream-element-type [Function]
--------------------------------------

'stream-element-type' stream => typespec

Arguments and Values::
......................

stream--a stream.

   typespec--a type specifier.

Description::
.............

stream-element-type returns a type specifier that indicates the types of
objects that may be read from or written to stream.

   Streams created by open have an element type restricted to integer or
a subtype of type character.

Examples::
..........

     ;; Note that the stream must accomodate at least the specified type,
     ;; but might accomodate other types.  Further note that even if it does
     ;; accomodate exactly the specified type, the type might be specified in
     ;; any of several ways.
      (with-open-file (s "test" :element-type '(integer 0 1)
                                :if-exists :error
                                :direction :output)
        (stream-element-type s))
     =>  INTEGER
     OR=> (UNSIGNED-BYTE 16)
     OR=> (UNSIGNED-BYTE 8)
     OR=> BIT
     OR=> (UNSIGNED-BYTE 1)
     OR=> (INTEGER 0 1)
     OR=> (INTEGER 0 (2))

Exceptional Situations::
........................

Should signal an error of type type-error if stream is not a stream.


File: gcl.info,  Node: streamp,  Next: read-byte,  Prev: stream-element-type,  Up: Streams Dictionary

21.2.13 streamp [Function]
--------------------------

'streamp' object => generalized-boolean

Arguments and Values::
......................

object--an object.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if object is of type stream; otherwise, returns false.

   streamp is unaffected by whether object, if it is a stream, is open
or closed.

Examples::
..........

      (streamp *terminal-io*) =>  true
      (streamp 1) =>  false

Notes::
.......

      (streamp object) == (typep object 'stream)


File: gcl.info,  Node: read-byte,  Next: write-byte,  Prev: streamp,  Up: Streams Dictionary

21.2.14 read-byte [Function]
----------------------------

'read-byte' stream &optional eof-error-p eof-value => byte

Arguments and Values::
......................

stream--a binary input stream.

   eof-error-p--a generalized boolean.  The default is true.

   eof-value--an object.  The default is nil.

   byte--an integer, or the eof-value.

Description::
.............

read-byte reads and returns one byte from stream.

   If an end of file_2 occurs and eof-error-p is false, the eof-value is
returned.

Examples::
..........

      (with-open-file (s "temp-bytes"
                          :direction :output
                          :element-type 'unsigned-byte)
         (write-byte 101 s)) =>  101
      (with-open-file (s "temp-bytes" :element-type 'unsigned-byte)
         (format t "~S ~S" (read-byte s) (read-byte s nil 'eof)))
      |>  101 EOF
     =>  NIL

Side Effects::
..............

Modifies stream.

Exceptional Situations::
........................

Should signal an error of type type-error if stream is not a stream.

   Should signal an error of type error if stream is not a binary input
stream.

   If there are no bytes remaining in the stream and eof-error-p is
true, an error of type end-of-file is signaled.

See Also::
..........

*note read-char:: ,

   *note read-sequence:: ,

   *note write-byte::


File: gcl.info,  Node: write-byte,  Next: peek-char,  Prev: read-byte,  Up: Streams Dictionary

21.2.15 write-byte [Function]
-----------------------------

'write-byte' byte stream => byte

Arguments and Values::
......................

byte--an integer of the stream element type of stream.

   stream--a binary output stream.

Description::
.............

write-byte writes one byte, byte, to stream.

Examples::
..........

      (with-open-file (s "temp-bytes"
                         :direction :output
                         :element-type 'unsigned-byte)
         (write-byte 101 s)) =>  101

Side Effects::
..............

stream is modified.

Affected By::
.............

The element type of the stream.

Exceptional Situations::
........................

Should signal an error of type type-error if stream is not a stream.
Should signal an error of type error if stream is not a binary output
stream.

   Might signal an error of type type-error if byte is not an integer of
the stream element type of stream.

See Also::
..........

*note read-byte:: , *note write-char:: ,

   *note write-sequence::


File: gcl.info,  Node: peek-char,  Next: read-char,  Prev: write-byte,  Up: Streams Dictionary

21.2.16 peek-char [Function]
----------------------------

'peek-char' &optional peek-type input-stream eof-error-p eof-value
recursive-p => char

Arguments and Values::
......................

peek-type--a character or t or nil.

   input-stream--input stream designator.  The default is standard
input.

   eof-error-p--a generalized boolean.  The default is true.

   eof-value--an object.  The default is nil.

   recursive-p--a generalized boolean.  The default is false.

   char--a character or the eof-value.

Description::
.............

peek-char obtains the next character in input-stream without actually
reading it, thus leaving the character to be read at a later time.  It
can also be used to skip over and discard intervening characters in the
input-stream until a particular character is found.

   If peek-type is not supplied or nil, peek-char returns the next
character to be read from input-stream, without actually removing it
from input-stream.  The next time input is done from input-stream, the
character will still be there.  If peek-type is t, then peek-char skips
over whitespace_2 characters, but not comments, and then performs the
peeking operation on the next character.  The last character examined,
the one that starts an object, is not removed from input-stream.  If
peek-type is a character, then peek-char skips over input characters
until a character that is char= to that character is found; that
character is left in input-stream.

   If an end of file_2 occurs and eof-error-p is false, eof-value is
returned.

   If recursive-p is true, this call is expected to be embedded in a
higher-level call to read or a similar function used by the Lisp reader.

   When input-stream is an echo stream, characters that are only peeked
at are not echoed.  In the case that peek-type is not nil, the
characters that are passed by peek-char are treated as if by read-char,
and so are echoed unless they have been marked otherwise by unread-char.

Examples::
..........

      (with-input-from-string (input-stream "    1 2 3 4 5")
         (format t "~S ~S ~S"
                 (peek-char t input-stream)
                 (peek-char #\4 input-stream)
                 (peek-char nil input-stream)))
      |>  #\1 #\4 #\4
     =>  NIL

Affected By::
.............

*readtable*, *standard-input*, *terminal-io*.

Exceptional Situations::
........................

If eof-error-p is true and an end of file_2 occurs an error of type
end-of-file is signaled.

   If peek-type is a character, an end of file_2 occurs, and eof-error-p
is true, an error of type end-of-file is signaled.

   If recursive-p is true and an end of file_2 occurs, an error of type
end-of-file is signaled.


File: gcl.info,  Node: read-char,  Next: read-char-no-hang,  Prev: peek-char,  Up: Streams Dictionary

21.2.17 read-char [Function]
----------------------------

'read-char' &optional input-stream eof-error-p eof-value recursive-p =>
char

Arguments and Values::
......................

input-stream--an input stream designator.  The default is standard
input.

   eof-error-p--a generalized boolean.  The default is true.

   eof-value--an object.  The default is nil.

   recursive-p--a generalized boolean.  The default is false.

   char--a character or the eof-value.

Description::
.............

read-char returns the next character from input-stream.

   When input-stream is an echo stream, the character is echoed on
input-stream the first time the character is seen.  Characters that are
not echoed by read-char are those that were put there by unread-char and
hence are assumed to have been echoed already by a previous call to
read-char.

   If recursive-p is true, this call is expected to be embedded in a
higher-level call to read or a similar function used by the Lisp reader.

   If an end of file_2 occurs and eof-error-p is false, eof-value is
returned.

Examples::
..........

      (with-input-from-string (is "0123")
         (do ((c (read-char is) (read-char is nil 'the-end)))
             ((not (characterp c)))
          (format t "~S " c)))
      |>  #\0 #\1 #\2 #\3
     =>  NIL

Affected By::
.............

*standard-input*, *terminal-io*.

Exceptional Situations::
........................

If an end of file_2 occurs before a character can be read, and
eof-error-p is true, an error of type end-of-file is signaled.

See Also::
..........

*note read-byte:: ,

   *note read-sequence:: ,

   *note write-char:: , *note read::

Notes::
.......

The corresponding output function is write-char.


File: gcl.info,  Node: read-char-no-hang,  Next: terpri,  Prev: read-char,  Up: Streams Dictionary

21.2.18 read-char-no-hang [Function]
------------------------------------

'read-char-no-hang' &optional input-stream eof-error-p eof-value
recursive-p => char

Arguments and Values::
......................

input-stream - an input stream designator.  The default is standard
input.

   eof-error-p--a generalized boolean.  The default is true.

   eof-value--an object.  The default is nil.

   recursive-p--a generalized boolean.  The default is false.

   char--a character or nil or the eof-value.

Description::
.............

read-char-no-hang returns a character from input-stream if such a
character is available.  If no character is available, read-char-no-hang
returns nil.

   If recursive-p is true, this call is expected to be embedded in a
higher-level call to read or a similar function used by the Lisp reader.

   If an end of file_2 occurs and eof-error-p is false, eof-value is
returned.

Examples::
..........

     ;; This code assumes an implementation in which a newline is not
     ;; required to terminate input from the console.
      (defun test-it ()
        (unread-char (read-char))
        (list (read-char-no-hang)
              (read-char-no-hang)
              (read-char-no-hang)))
     =>  TEST-IT
     ;; Implementation A, where a Newline is not required to terminate
     ;; interactive input on the console.
      (test-it)
      |>  |>>a<<|
     =>  (#\a NIL NIL)
     ;; Implementation B, where a Newline is required to terminate
     ;; interactive input on the console, and where that Newline remains
     ;; on the input stream.
      (test-it)
      |>  |>>a[<-~]<<|
     =>  (#\a #\Newline NIL)

Affected By::
.............

*standard-input*, *terminal-io*.

Exceptional Situations::
........................

If an end of file_2 occurs when eof-error-p is true, an error of type
end-of-file is signaled .

See Also::
..........

*note listen::

Notes::
.......

read-char-no-hang is exactly like read-char, except that if it would be
necessary to wait in order to get a character (as from a keyboard), nil
is immediately returned without waiting.


File: gcl.info,  Node: terpri,  Next: unread-char,  Prev: read-char-no-hang,  Up: Streams Dictionary

21.2.19 terpri, fresh-line [Function]
-------------------------------------

'terpri' &optional output-stream => nil

   'fresh-line' &optional output-stream => generalized-boolean

Arguments and Values::
......................

output-stream - an output stream designator.  The default is standard
output.

   generalized-boolean--a generalized boolean.

Description::
.............

terpri outputs a newline to output-stream.

   fresh-line is similar to terpri but outputs a newline only if the
output-stream is not already at the start of a line.  If for some reason
this cannot be determined, then a newline is output anyway.  fresh-line
returns true if it outputs a newline; otherwise it returns false.

Examples::
..........

      (with-output-to-string (s)
         (write-string "some text" s)
         (terpri s)
         (terpri s)
         (write-string "more text" s))
     =>  "some text

     more text"
      (with-output-to-string (s)
         (write-string "some text" s)
         (fresh-line s)
         (fresh-line s)
         (write-string "more text" s))
     =>  "some text
     more text"

Side Effects::
..............

The output-stream is modified.

Affected By::
.............

*standard-output*, *terminal-io*.

Exceptional Situations::
........................

None.

   [Reviewer Note by Barmar: What if stream is closed?]

Notes::
.......

terpri is identical in effect to

      (write-char #\Newline output-stream)


File: gcl.info,  Node: unread-char,  Next: write-char,  Prev: terpri,  Up: Streams Dictionary

21.2.20 unread-char [Function]
------------------------------

'unread-char' character &optional input-stream => nil

Arguments and Values::
......................

character--a character; must be the last character that was read from
input-stream.

   input-stream--an input stream designator.  The default is standard
input.

Description::
.............

unread-char places character back onto the front of input-stream so that
it will again be the next character in input-stream.

   When input-stream is an echo stream, no attempt is made to undo any
echoing of the character that might already have been done on
input-stream.  However, characters placed on input-stream by unread-char
are marked in such a way as to inhibit later re-echo by read-char.

   It is an error to invoke unread-char twice consecutively on the same
stream without an intervening call to read-char (or some other input
operation which implicitly reads characters) on that stream.

   Invoking peek-char or read-char commits all previous characters.  The
consequences of invoking unread-char on any character preceding that
which is returned by peek-char (including those passed over by peek-char
that has a non-nil peek-type) are unspecified.  In particular, the
consequences of invoking unread-char after peek-char are unspecified.

Examples::
..........

      (with-input-from-string (is "0123")
         (dotimes (i 6)
           (let ((c (read-char is)))
             (if (evenp i) (format t "~&~S ~S~
      |>  0 #\0
      |>  2 #\1
      |>  4 #\2
     =>  NIL

Affected By::
.............

*standard-input*, *terminal-io*.

See Also::
..........

*note peek-char:: , *note read-char:: , *note Stream Concepts::

Notes::
.......

unread-char is intended to be an efficient mechanism for allowing the
Lisp reader and other parsers to perform one-character lookahead in
input-stream.


File: gcl.info,  Node: write-char,  Next: read-line,  Prev: unread-char,  Up: Streams Dictionary

21.2.21 write-char [Function]
-----------------------------

'write-char' character &optional output-stream => character

Arguments and Values::
......................

character--a character.

   output-stream - an output stream designator.  The default is standard
output.

Description::
.............

write-char outputs character to output-stream.

Examples::
..........

      (write-char #\a)
      |>  a
     =>  #\a
      (with-output-to-string (s)
        (write-char #\a s)
        (write-char #\Space s)
        (write-char #\b s))
     =>  "a b"

Side Effects::
..............

The output-stream is modified.

Affected By::
.............

*standard-output*, *terminal-io*.

See Also::
..........

*note read-char:: , *note write-byte:: ,

   *note write-sequence::


File: gcl.info,  Node: read-line,  Next: write-string,  Prev: write-char,  Up: Streams Dictionary

21.2.22 read-line [Function]
----------------------------

'read-line' &optional input-stream eof-error-p eof-value recursive-p
=> line, missing-newline-p

Arguments and Values::
......................

input-stream--an input stream designator.  The default is standard
input.

   eof-error-p--a generalized boolean.  The default is true.

   eof-value--an object.  The default is nil.

   recursive-p--a generalized boolean.  The default is false.

   line--a string or the eof-value.

   missing-newline-p--a generalized boolean.

Description::
.............

Reads from input-stream a line of text that is terminated by a newline
or end of file.

   If recursive-p is true, this call is expected to be embedded in a
higher-level call to read or a similar function used by the Lisp reader.

   The primary value, line, is the line that is read, represented as a
string (without the trailing newline, if any).  If eof-error-p is false
and the end of file for input-stream is reached before any characters
are read, eof-value is returned as the line.

   The secondary value, missing-newline-p, is a generalized boolean that
is false if the line was terminated by a newline, or true if the line
was terminated by the end of file for input-stream (or if the line is
the eof-value).

Examples::
..........

      (setq a "line 1
      line2")
     =>  "line 1
      line2"
      (read-line (setq input-stream (make-string-input-stream a)))
     =>  "line 1", false
      (read-line input-stream)
     =>  "line2", true
      (read-line input-stream nil nil)
     =>  NIL, true

Affected By::
.............

*standard-input*, *terminal-io*.

Exceptional Situations::
........................

If an end of file_2 occurs before any characters are read in the line,
an error is signaled if eof-error-p is true.

See Also::
..........

*note read::

Notes::
.......

The corresponding output function is write-line.


File: gcl.info,  Node: write-string,  Next: read-sequence,  Prev: read-line,  Up: Streams Dictionary

21.2.23 write-string, write-line [Function]
-------------------------------------------

'write-string' string &optional output-stream &key start end => string

   'write-line' string &optional output-stream &key start end => string

Arguments and Values::
......................

string--a string.

   output-stream - an output stream designator.  The default is standard
output.

   start, end--bounding index designators of string.  The defaults for
start and end are 0 and nil, respectively.

Description::
.............

write-string writes the characters of the subsequence of string bounded
by start and end to output-stream.  write-line does the same thing, but
then outputs a newline afterwards.

Examples::
..........

      (prog1 (write-string "books" nil :end 4) (write-string "worms"))
      |>  bookworms
     =>  "books"
      (progn (write-char #\*)
             (write-line "test12" *standard-output* :end 5)
             (write-line "*test2")
             (write-char #\*)
             nil)
      |>  *test1
      |>  *test2
      |>  *
     =>  NIL

Affected By::
.............

*standard-output*, *terminal-io*.

See Also::
..........

*note read-line:: , *note write-char::

Notes::
.......

write-line and write-string return string, not the substring bounded by
start and end.

      (write-string string)
     == (dotimes (i (length string)
           (write-char (char string i)))

      (write-line string)
     == (prog1 (write-string string) (terpri))


File: gcl.info,  Node: read-sequence,  Next: write-sequence,  Prev: write-string,  Up: Streams Dictionary

21.2.24 read-sequence [Function]
--------------------------------

'read-sequence' sequence stream &key start end => position

   sequence--a sequence.

   stream--an input stream.

   start, end--bounding index designators of sequence.  The defaults for
start and end are 0 and nil, respectively.

   position--an integer greater than or equal to zero, and less than or
equal to the length of the sequence.

Description::
.............

Destructively modifies sequence by replacing the elements of sequence
bounded by start and end with elements read from stream.

   Sequence is destructively modified by copying successive elements
into it from stream.  If the end of file for stream is reached before
copying all elements of the subsequence, then the extra elements near
the end of sequence are not updated.

   Position is the index of the first element of sequence that was not
updated, which might be less than end because the end of file was
reached.

Examples::
..........

      (defvar *data* (make-array 15 :initial-element nil))
      (values (read-sequence *data* (make-string-input-stream "test string")) *data*)
      =>  11, #(#\t #\e #\s #\t #\Space #\s #\t #\r #\i #\n #\g NIL NIL NIL NIL)

Side Effects::
..............

Modifies stream and sequence.

Exceptional Situations::
........................

Should be prepared to signal an error of type type-error if sequence is
not a proper sequence.  Should signal an error of type type-error if
start is not a non-negative integer.  Should signal an error of type
type-error if end is not a non-negative integer or nil.

   Might signal an error of type type-error if an element read from the
stream is not a member of the element type of the sequence.

See Also::
..........

*note Compiler Terminology::, *note write-sequence:: , *note read-line::

Notes::
.......

read-sequence is identical in effect to iterating over the indicated
subsequence and reading one element at a time from stream and storing it
into sequence, but may be more efficient than the equivalent loop.  An
efficient implementation is more likely to exist for the case where the
sequence is a vector with the same element type as the stream.


File: gcl.info,  Node: write-sequence,  Next: file-length,  Prev: read-sequence,  Up: Streams Dictionary

21.2.25 write-sequence [Function]
---------------------------------

'write-sequence' sequence stream &key start end => sequence

   sequence--a sequence.

   stream--an output stream.

   start, end--bounding index designators of sequence.  The defaults for
start and end are 0 and nil, respectively.

Description::
.............

write-sequence writes the elements of the subsequence of sequence
bounded by start and end to stream.

Examples::
..........

      (write-sequence "bookworms" *standard-output* :end 4)
       |>  book
      =>  "bookworms"

Side Effects::
..............

Modifies stream.

Exceptional Situations::
........................

Should be prepared to signal an error of type type-error if sequence is
not a proper sequence.  Should signal an error of type type-error if
start is not a non-negative integer.  Should signal an error of type
type-error if end is not a non-negative integer or nil.

   Might signal an error of type type-error if an element of the bounded
sequence is not a member of the stream element type of the stream.

See Also::
..........

*note Compiler Terminology::, *note read-sequence:: , *note
write-string:: , write-line

Notes::
.......

write-sequence is identical in effect to iterating over the indicated
subsequence and writing one element at a time to stream, but may be more
efficient than the equivalent loop.  An efficient implementation is more
likely to exist for the case where the sequence is a vector with the
same element type as the stream.


File: gcl.info,  Node: file-length,  Next: file-position,  Prev: write-sequence,  Up: Streams Dictionary

21.2.26 file-length [Function]
------------------------------

'file-length' stream => length

Arguments and Values::
......................

stream--a stream associated with a file.

   length--a non-negative integer or nil.

Description::
.............

file-length returns the length of stream, or nil if the length cannot be
determined.

   For a binary file, the length is measured in units of the element
type of the stream.

Examples::
..........

      (with-open-file (s "decimal-digits.text"
                         :direction :output :if-exists :error)
        (princ "0123456789" s)
        (truename s))
     =>  #P"A:>Joe>decimal-digits.text.1"
      (with-open-file (s "decimal-digits.text")
        (file-length s))
     =>  10

Exceptional Situations::
........................

Should signal an error of type type-error if stream is not a stream
associated with a file.

See Also::
..........

*note open::


File: gcl.info,  Node: file-position,  Next: file-string-length,  Prev: file-length,  Up: Streams Dictionary

21.2.27 file-position [Function]
--------------------------------

'file-position' stream => position

   'file-position' stream position-spec => success-p

Arguments and Values::
......................

stream--a stream.

   position-spec--a file position designator.

   position--a file position or nil.

   success-p--a generalized boolean.

Description::
.............

Returns or changes the current position within a stream.

   When position-spec is not supplied, file-position returns the current
file position in the stream, or nil if this cannot be determined.

   When position-spec is supplied, the file position in stream is set to
that file position (if possible).  file-position returns true if the
repositioning is performed successfully, or false if it is not.

   An integer returned by file-position of one argument should be
acceptable as position-spec for use with the same file.

   For a character file, performing a single read-char or write-char
operation may cause the file position to be increased by more than 1
because of character-set translations (such as translating between the
Common Lisp #\Newline character and an external ASCII
carriage-return/line-feed sequence) and other aspects of the
implementation.  For a binary file, every read-byte or write-byte
operation increases the file position by 1.

Examples::
..........

      (defun tester ()
        (let ((noticed '()) file-written)
          (flet ((notice (x) (push x noticed) x))
            (with-open-file (s "test.bin"
                               :element-type '(unsigned-byte 8)
                               :direction :output
                               :if-exists :error)
               (notice (file-position s)) ;1
               (write-byte 5 s)
               (write-byte 6 s)
               (let ((p (file-position s)))
                 (notice p) ;2
                 (notice (when p (file-position s (1- p))))) ;3
               (write-byte 7 s)
               (notice (file-position s)) ;4
               (setq file-written (truename s)))
             (with-open-file (s file-written
                                :element-type '(unsigned-byte 8)
                                :direction :input)
               (notice (file-position s)) ;5
               (let ((length (file-length s)))
                 (notice length) ;6
                 (when length
                   (dotimes (i length)
                     (notice (read-byte s)))))) ;7,...
             (nreverse noticed))))
     =>  tester
      (tester)
     =>  (0 2 T 2 0 2 5 7)
     OR=> (0 2 NIL 3 0 3 5 6 7)
     OR=> (NIL NIL NIL NIL NIL NIL)

Side Effects::
..............

When the position-spec argument is supplied, the file position in the
stream might be moved.

Affected By::
.............

The value returned by file-position increases monotonically as input or
output operations are performed.

Exceptional Situations::
........................

If position-spec is supplied, but is too large or otherwise
inappropriate, an error is signaled.

See Also::
..........

*note file-length:: , *note file-string-length:: , *note open::

Notes::
.......

Implementations that have character files represented as a sequence of
records of bounded size might choose to encode the file position as, for
example,
<<record-number>>*<<max-record-size>>+<<character-within-record>>.  This
is a valid encoding because it increases monotonically as each character
is read or written, though not necessarily by 1 at each step.  An
integer might then be considered "inappropriate" as position-spec to
file-position if, when decoded into record number and character number,
it turned out that the supplied record was too short for the specified
character number.


File: gcl.info,  Node: file-string-length,  Next: open,  Prev: file-position,  Up: Streams Dictionary

21.2.28 file-string-length [Function]
-------------------------------------

'file-string-length' stream object => length

Arguments and Values::
......................

stream--an output character file stream.

   object--a string or a character.

   length--a non-negative integer, or nil.

Description::
.............

file-string-length returns the difference between what (file-position
stream) would be after writing object and its current value, or nil if
this cannot be determined.

   The returned value corresponds to the current state of stream at the
time of the call and might not be the same if it is called again when
the state of the stream has changed.


File: gcl.info,  Node: open,  Next: stream-external-format,  Prev: file-string-length,  Up: Streams Dictionary

21.2.29 open [Function]
-----------------------

'open' filespec &key direction element-type if-exists if-does-not-exist
external-format
=> stream

Arguments and Values::
......................

filespec--a pathname designator.

   direction--one of :input, :output, :io, or :probe.  The default is
:input.

   element-type--a type specifier for recognizable subtype of character;
or a type specifier for a finite recognizable subtype of integer; or one
of the symbols signed-byte, unsigned-byte, or :default.  The default is
character.

   if-exists--one of :error, :new-version, :rename, :rename-and-delete,
:overwrite, :append, :supersede, or nil.  The default is :new-version if
the version component of filespec is :newest, or :error otherwise.

   if-does-not-exist--one of :error, :create, or nil.  The default is
:error if direction is :input or if-exists is :overwrite or :append;
:create if direction is :output or :io, and if-exists is neither
:overwrite nor :append; or nil when direction is :probe.

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

   stream--a file stream or nil.

Description::
.............

open creates, opens, and returns a file stream that is connected to the
file specified by filespec.  Filespec is the name of the file to be
opened.  If the filespec designator is a stream, that stream is not
closed first or otherwise affected.

   The keyword arguments to open specify the characteristics of the file
stream that is returned, and how to handle errors.

   If direction is :input or :probe, or if if-exists is not :new-version
and the version component of the filespec is :newest, then the file
opened is that file already existing in the file system that has a
version greater than that of any other file in the file system whose
other pathname components are the same as those of filespec.

   An implementation is required to recognize all of the open keyword
options and to do something reasonable in the context of the host
operating system.  For example, if a file system does not support
distinct file versions and does not distinguish the notions of deletion
and expunging, :new-version might be treated the same as :rename or
:supersede, and :rename-and-delete might be treated the same as
:supersede.

:direction
     These are the possible values for direction, and how they affect
     the nature of the stream that is created:

     :input
          Causes the creation of an input file stream.

     :output
          Causes the creation of an output file stream.

     :io
          Causes the creation of a bidirectional file stream.

     :probe
          Causes the creation of a "no-directional" file stream; in
          effect, the file stream is created and then closed prior to
          being returned by open.

:element-type
     The element-type specifies the unit of transaction for the file
     stream.  If it is :default, the unit is determined by file system,
     possibly based on the file.

:if-exists
     if-exists specifies the action to be taken if direction is :output
     or :io and a file of the name filespec already exists.  If
     direction is :input, not supplied, or :probe, if-exists is ignored.
     These are the results of open as modified by if-exists:

     :error
          An error of type file-error is signaled.

     :new-version
          A new file is created with a larger version number.

     :rename
          The existing file is renamed to some other name and then a new
          file is created.

     :rename-and-delete
          The existing file is renamed to some other name, then it is
          deleted but not expunged, and then a new file is created.

     :overwrite
          Output operations on the stream destructively modify the
          existing file.  If direction is :io the file is opened in a
          bidirectional mode that allows both reading and writing.  The
          file pointer is initially positioned at the beginning of the
          file; however, the file is not truncated back to length zero
          when it is opened.

     :append
          Output operations on the stream destructively modify the
          existing file.  The file pointer is initially positioned at
          the end of the file.

          If direction is :io, the file is opened in a bidirectional
          mode that allows both reading and writing.

     :supersede
          The existing file is superseded; that is, a new file with the
          same name as the old one is created.  If possible, the
          implementation should not destroy the old file until the new
          stream is closed.

     nil
          No file or stream is created; instead, nil is returned to
          indicate failure.

:if-does-not-exist
     if-does-not-exist specifies the action to be taken if a file of
     name filespec does not already exist.  These are the results of
     open as modified by if-does-not-exist:

     :error
          An error of type file-error is signaled.

     :create
          An empty file is created.  Processing continues as if the file
          had already existed but no processing as directed by if-exists
          is performed.

     nil
          No file or stream is created; instead, nil is returned to
          indicate failure.

:external-format
     This option selects an external file format for the file: The only
     standardized value for this option is :default, although
     implementations are permitted to define additional external file
     formats and implementation-dependent values returned by
     stream-external-format can also be used by conforming programs.

     The external-format is meaningful for any kind of file stream whose
     element type is a subtype of character.  This option is ignored for
     streams for which it is not meaningful; however, implementations
     may define other element types for which it is meaningful.  The
     consequences are unspecified if a character is written that cannot
     be represented by the given external file format.

   When a file is opened, a file stream is constructed to serve as the
file system's ambassador to the Lisp environment; operations on the file
stream are reflected by operations on the file in the file system.

   A file can be deleted, renamed, or destructively modified by open.

   For information about opening relative pathnames, see *note Merging
Pathnames::.

Examples::
..........

      (open filespec :direction :probe)  =>  #<Closed Probe File Stream...>
      (setq q (merge-pathnames (user-homedir-pathname) "test"))
     =>  #<PATHNAME :HOST NIL :DEVICE device-name :DIRECTORY directory-name
         :NAME "test" :TYPE NIL :VERSION :NEWEST>
      (open filespec :if-does-not-exist :create) =>  #<Input File Stream...>
      (setq s (open filespec :direction :probe)) =>  #<Closed Probe File Stream...>
      (truename s) =>  #<PATHNAME :HOST NIL :DEVICE device-name :DIRECTORY
         directory-name :NAME filespec :TYPE extension :VERSION 1>
      (open s :direction :output :if-exists nil) =>  NIL

Affected By::
.............

The nature and state of the host computer's file system.

Exceptional Situations::
........................

If if-exists is :error, (subject to the constraints on the meaning of
if-exists listed above), an error of type file-error is signaled.

   If if-does-not-exist is :error (subject to the constraints on the
meaning of if-does-not-exist listed above), an error of type file-error
is signaled.

   If it is impossible for an implementation to handle some option in a
manner close to what is specified here, an error of type error might be
signaled.

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

   An error of type error is signaled if the external-format is not
understood by the implementation.

   The various file systems in existence today have widely differing
capabilities, and some aspects of the file system are beyond the scope
of this specification to define.  A given implementation might not be
able to support all of these options in exactly the manner stated.  An
implementation is required to recognize all of these option keywords and
to try to do something "reasonable" in the context of the host file
system.  Where necessary to accomodate the file system, an
implementation deviate slightly from the semantics specified here
without being disqualified for consideration as a conforming
implementation.  If it is utterly impossible for an implementation to
handle some option in a manner similar to what is specified here, it may
simply signal an error.

   With regard to the :element-type option, if a type is requested that
is not supported by the file system, a substitution of types such as
that which goes on in upgrading is permissible.  As a minimum
requirement, it should be the case that opening an output stream to a
file in a given element type and later opening an input stream to the
same file in the same element type should work compatibly.

See Also::
..........

*note with-open-file:: , *note close:: , pathname, logical-pathname,

   *note Merging Pathnames::,

   *note Pathnames as Filenames::

Notes::
.......

open does not automatically close the file when an abnormal exit occurs.

   When element-type is a subtype of character, read-char and/or
write-char can be used on the resulting file stream.

   When element-type is a subtype of integer, read-byte and/or
write-byte can be used on the resulting file stream.

   When element-type is :default, the type can be determined by using
stream-element-type.


File: gcl.info,  Node: stream-external-format,  Next: with-open-file,  Prev: open,  Up: Streams Dictionary

21.2.30 stream-external-format [Function]
-----------------------------------------

'stream-external-format' stream => format

Arguments and Values::
......................

stream--a file stream.

   format--an external file format.

Description::
.............

Returns an external file format designator for the stream.

Examples::
..........

      (with-open-file (stream "test" :direction :output)
        (stream-external-format stream))
     =>  :DEFAULT
     OR=> :ISO8859/1-1987
     OR=> (:ASCII :SAIL)
     OR=> ACME::PROPRIETARY-FILE-FORMAT-17
     OR=> #<FILE-FORMAT :ISO646-1983 2343673>

See Also::
..........

the :external-format argument to the function *note open:: and the *note
with-open-file:: macro.

Notes::
.......

The format returned is not necessarily meaningful to other
implementations.


File: gcl.info,  Node: with-open-file,  Next: close,  Prev: stream-external-format,  Up: Streams Dictionary

21.2.31 with-open-file [macro]
------------------------------

Syntax::
........

'with-open-file' (stream filespec {options}*) {declaration}* {form}*
=> results

Arguments and Values::
......................

stream - a variable.

   filespec--a pathname designator.

   options - forms; evaluated.

   declaration--a declare expression; not evaluated.

   forms--an implicit progn.

   results--the values returned by the forms.

Description::
.............

with-open-file uses open to create a file stream

   to file named by filespec.  Filespec is the name of the file to be
opened.  Options are used as keyword arguments to open.

   The stream object to which the stream variable is bound has dynamic
extent; its extent ends when the form is exited.

   with-open-file evaluates the forms as an implicit progn with stream
bound to

   the value returned by open.

   When control leaves the body, either normally or abnormally (such as
by use of throw), the file is automatically closed.  If a new output
file is being written, and control leaves abnormally, the file is
aborted and the file system is left, so far as possible, as if the file
had never been opened.

   It is possible by the use of :if-exists nil or :if-does-not-exist nil
for stream to be bound to nil.

   Users of :if-does-not-exist nil should check for a valid stream.

   The consequences are undefined if an attempt is made to assign the
stream variable.  The compiler may choose to issue a warning if such an
attempt is detected.

Examples::
..........

      (setq p (merge-pathnames "test"))
     =>  #<PATHNAME :HOST NIL :DEVICE device-name :DIRECTORY directory-name
         :NAME "test" :TYPE NIL :VERSION :NEWEST>
      (with-open-file (s p :direction :output :if-exists :supersede)
         (format s "Here are a couple~
      (with-open-file (s p)
         (do ((l (read-line s) (read-line s nil 'eof)))
             ((eq l 'eof) "Reached end of file.")
          (format t "~&*** ~A~
      |>  *** Here are a couple
      |>  *** of test data lines
     =>  "Reached end of file."

     ;; Normally one would not do this intentionally because it is
     ;; not perspicuous, but beware when using :IF-DOES-NOT-EXIST NIL
     ;; that this doesn't happen to you accidentally...
      (with-open-file (foo "no-such-file" :if-does-not-exist nil)
        (read foo))
      |>  |>>hello?<<|
     =>  HELLO? ;This value was read from the terminal, not a file!

     ;; Here's another bug to avoid...
      (with-open-file (foo "no-such-file" :direction :output :if-does-not-exist nil)
        (format foo "Hello"))
     =>  "Hello" ;FORMAT got an argument of NIL!

Side Effects::
..............

Creates a stream to the file named by filename (upon entry), and closes
the stream (upon exit).  In some implementations, the file might be
locked in some way while it is open.  If the stream is an output stream,
a file might be created.

Affected By::
.............

The host computer's file system.

Exceptional Situations::
........................

See the function open.

See Also::
..........

*note open:: , *note close:: , pathname, logical-pathname,

   *note Pathnames as Filenames::


File: gcl.info,  Node: close,  Next: with-open-stream,  Prev: with-open-file,  Up: Streams Dictionary

21.2.32 close [Function]
------------------------

'close' stream &key abort => result

Arguments and Values::
......................

stream--a stream (either open or closed).

   abort--a generalized boolean.  The default is false.

   result--t if the stream was open at the time it was received as an
argument, or implementation-dependent otherwise.

Description::
.............

close closes stream.  Closing a stream means that it may no longer be
used in input or output operations.  The act of closing a file stream
ends the association between the stream and its associated file; the
transaction with the file system is terminated, and input/output may no
longer be performed on the stream.

   If abort is true, an attempt is made to clean up any side effects of
having created stream.  If stream performs output to a file that was
created when the stream was created, the file is deleted and any
previously existing file is not superseded.

   It is permissible to close an already closed stream, but in that case
the result is implementation-dependent.

   After stream is closed, it is still possible to perform the following
query operations upon it:

   streamp, pathname, truename, merge-pathnames, pathname-host,
pathname-device, pathname-directory,pathname-name, pathname-type,
pathname-version, namestring, file-namestring, directory-namestring,
host-namestring, enough-namestring, open, probe-file, and directory.

   The effect of close on a constructed stream is to close the argument
stream only.  There is no effect on the constituents of composite
streams.

   For a stream created with make-string-output-stream, the result of
get-output-stream-string is unspecified after close.

Examples::
..........

      (setq s (make-broadcast-stream)) =>  #<BROADCAST-STREAM>
      (close s) =>  T
      (output-stream-p s) =>  true

Side Effects::
..............

The stream is closed (if necessary).  If abort is true and the stream is
an output file stream, its associated file might be deleted.

See Also::
..........

*note open::


File: gcl.info,  Node: with-open-stream,  Next: listen,  Prev: close,  Up: Streams Dictionary

21.2.33 with-open-stream [Macro]
--------------------------------

'with-open-stream' (var stream) {declaration}* {form}*
=> {result}*

Arguments and Values::
......................

var--a variable name.

   stream--a form; evaluated to produce a stream.

   declaration--a declare expression; not evaluated.

   forms--an implicit progn.

   results--the values returned by the forms.

Description::
.............

with-open-stream performs a series of operations on stream, returns a
value, and then closes the stream.

   Var is bound to the value of stream, and then forms are executed as
an implicit progn.  stream is automatically closed on exit from
with-open-stream, no matter whether the exit is normal or abnormal.

   The stream has dynamic extent; its extent ends when the form is
exited.

   The consequences are undefined if an attempt is made to assign the
the variable var with the forms.

Examples::
..........

      (with-open-stream (s (make-string-input-stream "1 2 3 4"))
         (+ (read s) (read s) (read s))) =>  6

Side Effects::
..............

The stream is closed (upon exit).

See Also::
..........

*note close::


File: gcl.info,  Node: listen,  Next: clear-input,  Prev: with-open-stream,  Up: Streams Dictionary

21.2.34 listen [Function]
-------------------------

'listen' &optional input-stream => generalized-boolean

Arguments and Values::
......................

input-stream--an input stream designator.  The default is standard
input.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if there is a character immediately available from
input-stream; otherwise, returns false.  On a non-interactive
input-stream, listen returns true except when at end of file_1.  If an
end of file is encountered, listen returns false.  listen is intended to
be used when input-stream obtains characters from an interactive device
such as a keyboard.

Examples::
..........

      (progn (unread-char (read-char)) (list (listen) (read-char)))
      |>  |>>1<<|
     =>  (T #\1)
      (progn (clear-input) (listen))
     =>  NIL ;Unless you're a very fast typist!

Affected By::
.............

*standard-input*

See Also::
..........

*note interactive-stream-p:: , *note read-char-no-hang::


File: gcl.info,  Node: clear-input,  Next: finish-output,  Prev: listen,  Up: Streams Dictionary

21.2.35 clear-input [Function]
------------------------------

'clear-input' &optional input-stream => nil

Arguments and Values::
......................

input-stream--an input stream designator.  The default is standard
input.

Description::
.............

Clears any available input from input-stream.

   If clear-input does not make sense for input-stream, then clear-input
does nothing.

Examples::
..........

     ;; The exact I/O behavior of this example might vary from implementation
     ;; to implementation depending on the kind of interactive buffering that
     ;; occurs.  (The call to SLEEP here is intended to help even out the
     ;; differences in implementations which do not do line-at-a-time buffering.)

     (defun read-sleepily (&optional (clear-p nil) (zzz 0))
       (list (progn (print '>) (read))
             ;; Note that input typed within the first ZZZ seconds
             ;; will be discarded.
             (progn (print '>)
                    (if zzz (sleep zzz))
                    (print '>>)
                    (if clear-p (clear-input))
                    (read))))

     (read-sleepily)
      |>  > |>>10<<|
      |>  >
      |>  >> |>>20<<|
     =>  (10 20)

     (read-sleepily t)
      |>  > |>>10<<|
      |>  >
      |>  >> |>>20<<|
     =>  (10 20)

     (read-sleepily t 10)
      |>  > |>>10<<|
      |>  > |>>20<<|  ; Some implementations won't echo typeahead here.
      |>  >> |>>30<<|
     =>  (10 30)

Side Effects::
..............

The input-stream is modified.

Affected By::
.............

*standard-input*

Exceptional Situations::
........................

Should signal an error of type type-error if input-stream is not a
stream designator.

See Also::
..........

clear-output


File: gcl.info,  Node: finish-output,  Next: y-or-n-p,  Prev: clear-input,  Up: Streams Dictionary

21.2.36 finish-output, force-output, clear-output [Function]
------------------------------------------------------------

'finish-output' &optional output-stream => nil

   'force-output' &optional output-stream => nil

   'clear-output' &optional output-stream => nil

Arguments and Values::
......................

output-stream--an output stream designator.  The default is standard
output.

Description::
.............

finish-output, force-output, and clear-output exercise control over the
internal handling of buffered stream output.

   finish-output attempts to ensure that any buffered output sent to
output-stream has reached its destination, and then returns.

   force-output initiates the emptying of any internal buffers but does
not wait for completion or acknowledgment to return.

   clear-output attempts to abort any outstanding output operation in
progress in order to allow as little output as possible to continue to
the destination.

   If any of these operations does not make sense for output-stream,
then it does nothing.  The precise actions of these functions are
implementation-dependent.

Examples::
..........

     ;; Implementation A
      (progn (princ "am i seen?") (clear-output))
     =>  NIL

     ;; Implementation B
      (progn (princ "am i seen?") (clear-output))
      |>  am i seen?
     =>  NIL

Affected By::
.............

*standard-output*

Exceptional Situations::
........................

Should signal an error of type type-error if output-stream is not a
stream designator.

See Also::
..........

*note clear-input::


File: gcl.info,  Node: y-or-n-p,  Next: make-synonym-stream,  Prev: finish-output,  Up: Streams Dictionary

21.2.37 y-or-n-p, yes-or-no-p [Function]
----------------------------------------

'y-or-n-p' &optional control &rest arguments => generalized-boolean

   'yes-or-no-p' &optional control &rest arguments =>
generalized-boolean

Arguments and Values::
......................

control--a format control.

   arguments--format arguments for control.

   generalized-boolean--a generalized boolean.

Description::
.............

These functions ask a question and parse a response from the user.  They
return true if the answer is affirmative, or false if the answer is
negative.

   y-or-n-p is for asking the user a question whose answer is either
"yes" or "no."  It is intended that the reply require the user to answer
a yes-or-no question with a single character.  yes-or-no-p is also for
asking the user a question whose answer is either "Yes" or "No."  It is
intended that the reply require the user to take more action than just a
single keystroke, such as typing the full word yes or no followed by a
newline.

   y-or-n-p types out a message (if supplied), reads an answer in some
implementation-dependent manner (intended to be short and simple, such
as reading a single character such as Y or N).  yes-or-no-p types out a
message (if supplied), attracts the user's attention (for example, by
ringing the terminal's bell), and reads an answer in some
implementation-dependent manner (intended to be multiple characters,
such as YES or NO).

   If format-control is supplied and not nil, then a fresh-line
operation is performed; then a message is printed as if format-control
and arguments were given to format.  In any case, yes-or-no-p and
y-or-n-p will provide a prompt such as "(Y or N)" or "(Yes or No)" if
appropriate.

   All input and output are performed using query I/O.

Examples::
..........

      (y-or-n-p "(t or nil) given by")
      |>  (t or nil) given by (Y or N) |>>Y<<|
     =>  true
      (yes-or-no-p "a ~S message" 'frightening)
      |>  a FRIGHTENING message (Yes or No) |>>no<<|
     =>  false
      (y-or-n-p "Produce listing file?")
      |>  Produce listing file?
      |>  Please respond with Y or N. |>>n<<|
     =>  false

Side Effects::
..............

Output to and input from query I/O will occur.

Affected By::
.............

*query-io*.

See Also::
..........

*note format::

Notes::
.......

yes-or-no-p and yes-or-no-p do not add question marks to the end of the
prompt string, so any desired question mark or other punctuation should
be explicitly included in the text query.


File: gcl.info,  Node: make-synonym-stream,  Next: synonym-stream-symbol,  Prev: y-or-n-p,  Up: Streams Dictionary

21.2.38 make-synonym-stream [Function]
--------------------------------------

'make-synonym-stream' symbol => synonym-stream

Arguments and Values::
......................

symbol--a symbol that names a dynamic variable.

   synonym-stream--a synonym stream.

Description::
.............

Returns a synonym stream whose synonym stream symbol is symbol.

Examples::
..........

      (setq a-stream (make-string-input-stream "a-stream")
             b-stream (make-string-input-stream "b-stream"))
     =>  #<String Input Stream>
      (setq s-stream (make-synonym-stream 'c-stream))
     =>  #<SYNONYM-STREAM for C-STREAM>
      (setq c-stream a-stream)
     =>  #<String Input Stream>
      (read s-stream) =>  A-STREAM
      (setq c-stream b-stream)
     =>  #<String Input Stream>
      (read s-stream) =>  B-STREAM

Exceptional Situations::
........................

Should signal type-error if its argument is not a symbol.

See Also::
..........

*note Stream Concepts::


File: gcl.info,  Node: synonym-stream-symbol,  Next: broadcast-stream-streams,  Prev: make-synonym-stream,  Up: Streams Dictionary

21.2.39 synonym-stream-symbol [Function]
----------------------------------------

'synonym-stream-symbol' synonym-stream => symbol

Arguments and Values::
......................

synonym-stream--a synonym stream.

   symbol--a symbol.

Description::
.............

Returns the symbol whose symbol-value the synonym-stream is using.

See Also::
..........

*note make-synonym-stream::


File: gcl.info,  Node: broadcast-stream-streams,  Next: make-broadcast-stream,  Prev: synonym-stream-symbol,  Up: Streams Dictionary

21.2.40 broadcast-stream-streams [Function]
-------------------------------------------

'broadcast-stream-streams' broadcast-stream => streams

Arguments and Values::
......................

broadcast-stream--a broadcast stream.

   streams--a list of streams.

Description::
.............

Returns a list of output streams that constitute all the streams to
which the broadcast-stream is broadcasting.


File: gcl.info,  Node: make-broadcast-stream,  Next: make-two-way-stream,  Prev: broadcast-stream-streams,  Up: Streams Dictionary

21.2.41 make-broadcast-stream [Function]
----------------------------------------

'make-broadcast-stream' &rest streams => broadcast-stream

Arguments and Values::
......................

stream--an output stream.

   broadcast-stream--a broadcast stream.

Description::
.............

Returns a broadcast stream.

Examples::
..........

      (setq a-stream (make-string-output-stream)
             b-stream (make-string-output-stream)) =>  #<String Output Stream>
      (format (make-broadcast-stream a-stream b-stream)
               "this will go to both streams") =>  NIL
      (get-output-stream-string a-stream) =>  "this will go to both streams"
      (get-output-stream-string b-stream) =>  "this will go to both streams"

Exceptional Situations::
........................

Should signal an error of type type-error if any stream is not an output
stream.

See Also::
..........

*note broadcast-stream-streams::


File: gcl.info,  Node: make-two-way-stream,  Next: two-way-stream-input-stream,  Prev: make-broadcast-stream,  Up: Streams Dictionary

21.2.42 make-two-way-stream [Function]
--------------------------------------

'make-two-way-stream' input-stream output-stream => two-way-stream

Arguments and Values::
......................

input-stream--a stream.

   output-stream--a stream.

   two-way-stream--a two-way stream.

Description::
.............

Returns a two-way stream that gets its input from input-stream and sends
its output to output-stream.

Examples::
..........

      (with-output-to-string (out)
         (with-input-from-string (in "input...")
           (let ((two (make-two-way-stream in out)))
             (format two "output...")
             (setq what-is-read (read two))))) =>  "output..."
      what-is-read =>  INPUT...

Exceptional Situations::
........................

Should signal an error of type type-error if input-stream is not an
input stream.  Should signal an error of type type-error if
output-stream is not an output stream.


File: gcl.info,  Node: two-way-stream-input-stream,  Next: echo-stream-input-stream,  Prev: make-two-way-stream,  Up: Streams Dictionary

21.2.43 two-way-stream-input-stream, two-way-stream-output-stream
-----------------------------------------------------------------

                                                             [Function]

   'two-way-stream-input-stream' two-way-stream => input-stream

   'two-way-stream-output-stream' two-way-stream => output-stream

Arguments and Values::
......................

two-way-stream--a two-way stream.

   input-stream--an input stream.

   output-stream--an output stream.

Description::
.............

two-way-stream-input-stream returns the stream from which two-way-stream
receives input.

   two-way-stream-output-stream returns the stream to which
two-way-stream sends output.


File: gcl.info,  Node: echo-stream-input-stream,  Next: make-echo-stream,  Prev: two-way-stream-input-stream,  Up: Streams Dictionary

21.2.44 echo-stream-input-stream, echo-stream-output-stream [Function]
----------------------------------------------------------------------

'echo-stream-input-stream' echo-stream => input-stream

   'echo-stream-output-stream' echo-stream => output-stream

Arguments and Values::
......................

echo-stream--an echo stream.

   input-stream--an input stream.

   output-stream--an output stream.

Description::
.............

echo-stream-input-stream returns the input stream from which echo-stream
receives input.

   echo-stream-output-stream returns the output stream to which
echo-stream sends output.


File: gcl.info,  Node: make-echo-stream,  Next: concatenated-stream-streams,  Prev: echo-stream-input-stream,  Up: Streams Dictionary

21.2.45 make-echo-stream [Function]
-----------------------------------

'make-echo-stream' input-stream output-stream => echo-stream

Arguments and Values::
......................

input-stream--an input stream.

   output-stream--an output stream.

   echo-stream--an echo stream.

Description::
.............

Creates and returns an echo stream that takes input from input-stream
and sends output to output-stream.

Examples::
..........

      (let ((out (make-string-output-stream)))
         (with-open-stream
             (s (make-echo-stream
                 (make-string-input-stream "this-is-read-and-echoed")
                 out))
           (read s)
           (format s " * this-is-direct-output")
           (get-output-stream-string out)))
     =>  "this-is-read-and-echoed * this-is-direct-output"

See Also::
..........

*note echo-stream-input-stream:: , echo-stream-output-stream, *note
make-two-way-stream::


File: gcl.info,  Node: concatenated-stream-streams,  Next: make-concatenated-stream,  Prev: make-echo-stream,  Up: Streams Dictionary

21.2.46 concatenated-stream-streams [Function]
----------------------------------------------

'concatenated-stream-streams' concatenated-stream => streams

Arguments and Values::
......................

concatenated-stream - a concatenated stream.

   streams--a list of input streams.

Description::
.............

Returns a list of input streams that constitute the ordered set of
streams the concatenated-stream still has to read from, starting with
the current one it is reading from.  The list may be empty if no more
streams remain to be read.

   The consequences are undefined if the list structure of the streams
is ever modified.


File: gcl.info,  Node: make-concatenated-stream,  Next: get-output-stream-string,  Prev: concatenated-stream-streams,  Up: Streams Dictionary

21.2.47 make-concatenated-stream [Function]
-------------------------------------------

'make-concatenated-stream' &rest input-streams => concatenated-stream

Arguments and Values::
......................

input-stream--an input stream.

   concatenated-stream--a concatenated stream.

Description::
.............

Returns a concatenated stream that has the indicated input-streams
initially associated with it.

Examples::
..........

      (read (make-concatenated-stream
              (make-string-input-stream "1")
              (make-string-input-stream "2"))) =>  12

Exceptional Situations::
........................

Should signal type-error if any argument is not an input stream.

See Also::
..........

*note concatenated-stream-streams::


File: gcl.info,  Node: get-output-stream-string,  Next: make-string-input-stream,  Prev: make-concatenated-stream,  Up: Streams Dictionary

21.2.48 get-output-stream-string [Function]
-------------------------------------------

'get-output-stream-string' string-output-stream => string

Arguments and Values::
......................

string-output-stream--a stream.

   string--a string.

Description::
.............

Returns a string containing, in order, all the characters that have been
output to string-output-stream.  This operation clears any characters on
string-output-stream, so the string contains only those characters which
have been output since the last call to get-output-stream-string or
since the creation of the string-output-stream, whichever occurred most
recently.

Examples::
..........

      (setq a-stream (make-string-output-stream)
             a-string "abcdefghijklm") =>  "abcdefghijklm"
      (write-string a-string a-stream) =>  "abcdefghijklm"
      (get-output-stream-string a-stream) =>  "abcdefghijklm"
      (get-output-stream-string a-stream) =>  ""

Side Effects::
..............

The string-output-stream is cleared.

Exceptional Situations::
........................

The consequences are undefined if stream-output-string is closed.

   The consequences are undefined if string-output-stream is a stream
that was not produced by make-string-output-stream.

   The consequences are undefined if string-output-stream was created
implicitly by with-output-to-string or format.

See Also::
..........

*note make-string-output-stream::


File: gcl.info,  Node: make-string-input-stream,  Next: make-string-output-stream,  Prev: get-output-stream-string,  Up: Streams Dictionary

21.2.49 make-string-input-stream [Function]
-------------------------------------------

'make-string-input-stream' string &optional start end => string-stream

Arguments and Values::
......................

string--a string.

   start, end--bounding index designators of string.  The defaults for
start and end are 0 and nil, respectively.

   string-stream--an input string stream.

Description::
.............

Returns an input string stream.  This stream will supply, in order, the
characters in the substring of string bounded by start and end.  After
the last character has been supplied, the string stream will then be at
end of file.

Examples::
..........

      (let ((string-stream (make-string-input-stream "1 one ")))
        (list (read string-stream nil nil)
              (read string-stream nil nil)
              (read string-stream nil nil)))
     =>  (1 ONE NIL)

      (read (make-string-input-stream "prefixtargetsuffix" 6 12)) =>  TARGET

See Also::
..........

*note with-input-from-string::


File: gcl.info,  Node: make-string-output-stream,  Next: with-input-from-string,  Prev: make-string-input-stream,  Up: Streams Dictionary

21.2.50 make-string-output-stream [Function]
--------------------------------------------

'make-string-output-stream' &key element-type => string-stream

Arguments and Values::
......................

element-type--a type specifier.  The default is character.

   string-stream--an output string stream.

Description::
.............

Returns

   an output string stream that accepts characters and makes available
(via get-output-stream-string) a string that contains the characters
that were actually output.

   The element-type names the type of the elements of the string; a
string is constructed of the most specialized type that can accommodate
elements of that element-type.

Examples::
..........

      (let ((s (make-string-output-stream)))
        (write-string "testing... " s)
        (prin1 1234 s)
        (get-output-stream-string s))
     =>  "testing... 1234"

   None..

See Also::
..........

*note get-output-stream-string:: , *note with-output-to-string::


File: gcl.info,  Node: with-input-from-string,  Next: with-output-to-string,  Prev: make-string-output-stream,  Up: Streams Dictionary

21.2.51 with-input-from-string [Macro]
--------------------------------------

'with-input-from-string' (var string &key index start end)
{declaration}* {form}*
=> {result}*

Arguments and Values::
......................

var--a variable name.

   string--a form; evaluated to produce a string.

   index--a place.

   start, end--bounding index designators of string.  The defaults for
start and end are 0 and nil, respectively.

   declaration--a declare expression; not evaluated.

   forms--an implicit progn.

   result--the values returned by the forms.

Description::
.............

Creates an

   input string stream,

   provides an opportunity to perform operations on the stream
(returning zero or more values), and then closes the string stream.

   String is evaluated first, and var is bound to a character input
string stream that supplies characters from the subsequence of the
resulting string bounded by start and end.  The body is executed as an
implicit progn.

   The input string stream is automatically closed on exit from
with-input-from-string, no matter whether the exit is normal or
abnormal.

   The input string stream to which the variable var is bound has
dynamic extent; its extent ends when the form is exited.

   The index is a pointer within the string to be advanced.  If
with-input-from-string is exited normally, then index will have as its
value the index into the string indicating the first character not read
which is (length string) if all characters were used.  The place
specified by index is not updated as reading progresses, but only at the
end of the operation.

   start and index may both specify the same variable, which is a
pointer within the string to be advanced, perhaps repeatedly by some
containing loop.

   The consequences are undefined if an attempt is made to assign the
variable var.

Examples::
..........

      (with-input-from-string (s "XXX1 2 3 4xxx"
                                  :index ind
                                  :start 3 :end 10)
         (+ (read s) (read s) (read s))) =>  6
      ind =>  9
      (with-input-from-string (s "Animal Crackers" :index j :start 6)
        (read s)) =>  CRACKERS

   The variable j is set to 15.

Side Effects::
..............

The value of the place named by index, if any, is modified.

See Also::
..........

*note make-string-input-stream:: ,

   *note Traversal Rules and Side Effects::


File: gcl.info,  Node: with-output-to-string,  Next: *debug-io*,  Prev: with-input-from-string,  Up: Streams Dictionary

21.2.52 with-output-to-string [Macro]
-------------------------------------

'with-output-to-string' (var &optional string-form &key element-type)
{declaration}* {form}*
=> {result}*

Arguments and Values::
......................

var--a variable name.

   string-form--a form or nil; if non-nil, evaluated to produce string.

   string--a string that has a fill pointer.

   element-type--a type specifier; evaluated.

   The default is character.

   declaration--a declare expression; not evaluated.

   forms--an implicit progn.

   results--If a string-form is not supplied or nil, a string;
otherwise, the values returned by the forms.

Description::
.............

with-output-to-string creates a

   character output stream, performs a series of operations that may
send results to this stream, and then closes the stream.

   The element-type names the type of the elements of the stream; a
stream is constructed of the most specialized type that can accommodate
elements of the given type.

   The body is executed as an implicit progn with var bound to an output
string stream.  All output to that string stream is saved in a string.

   If string is supplied, element-type is ignored, and the output is
incrementally appended to string as if by use of vector-push-extend.

   The output stream is automatically closed on exit from
with-output-from-string, no matter whether the exit is normal or
abnormal.

   The output string stream to which the variable var is bound has
dynamic extent; its extent ends when the form is exited.

   If no string is provided, then with-output-from-string

   produces a stream that accepts characters and returns a string of the
indicated element-type.

   If string is provided, with-output-to-string returns the results of
evaluating the last form.

   The consequences are undefined if an attempt is made to assign the
variable var.

Examples::
..........

      (setq fstr (make-array '(0) :element-type 'base-char
                                  :fill-pointer 0 :adjustable t)) =>  ""
      (with-output-to-string (s fstr)
         (format s "here's some output")
         (input-stream-p s)) =>  false
      fstr =>  "here's some output"

Side Effects::
..............

The string is modified.

Exceptional Situations::
........................

The consequences are undefined if destructive modifications are
performed directly on the string during the dynamic extent of the call.

See Also::
..........

*note make-string-output-stream:: , vector-push-extend,

   *note Traversal Rules and Side Effects::


File: gcl.info,  Node: *debug-io*,  Next: *terminal-io*,  Prev: with-output-to-string,  Up: Streams Dictionary

21.2.53 *debug-io*, *error-output*, *query-io*,
-----------------------------------------------

*standard-input*, *standard-output*,
------------------------------------

*trace-output*
--------------

                                                             [Variable]

Value Type::
............

For *standard-input*: an input stream

   For *error-output*, *standard-output*, and *trace-output*: an output
stream.

   For *debug-io*, *query-io*: a bidirectional stream.

Initial Value::
...............

implementation-dependent, but it must be an open stream that is not a
generalized synonym stream to an I/O customization variables but that
might be a generalized synonym stream to the value of some I/O
customization variable.  The initial value might also be a generalized
synonym stream to either the symbol *terminal-io* or to the stream that
is its value.

Description::
.............

These variables are collectively called the standardized I/O
customization variables.  They can be bound or assigned in order to
change the default destinations for input and/or output used by various
standardized operators and facilities.

   The value of *debug-io*, called debug I/O, is a stream to be used for
interactive debugging purposes.

   The value of *error-output*, called error output, is a stream to
which warnings and non-interactive error messages should be sent.

   The value of *query-io*, called query I/O, is a bidirectional stream
to be used when asking questions of the user.  The question should be
output to this stream, and the answer read from it.

   The value of *standard-input*, called standard input, is a stream
that is used by many operators as a default source of input when no
specific input stream is explicitly supplied.

   The value of *standard-output*, called standard output, is a stream
that is used by many operators as a default destination for output when
no specific output stream is explicitly supplied.

   The value of *trace-output*, called trace output, is the stream on
which traced functions (see trace) and the time macro print their
output.

Examples::
..........

      (with-output-to-string (*error-output*)
        (warn "this string is sent to *error-output*"))
      =>  "Warning: this string is sent to *error-output*
     " ;The exact format of this string is implementation-dependent.

      (with-input-from-string (*standard-input* "1001")
         (+ 990 (read))) =>  1991

      (progn (setq out (with-output-to-string (*standard-output*)
                          (print "print and format t send things to")
                          (format t "*standard-output* now going to a string")))
             :done)
     =>  :DONE
      out
     =>  "
     \"print and format t send things to\" *standard-output* now going to a string"

      (defun fact (n) (if (< n 2) 1 (* n (fact (- n 1)))))
     =>  FACT
      (trace fact)
     =>  (FACT)
     ;; Of course, the format of traced output is implementation-dependent.
      (with-output-to-string (*trace-output*)
        (fact 3))
     =>  "
     1 Enter FACT 3
     | 2 Enter FACT 2
     |   3 Enter FACT 1
     |   3 Exit FACT 1
     | 2 Exit FACT 2
     1 Exit FACT 6"

See Also::
..........

*terminal-io*, synonym-stream, *note Time:: , *note trace:: , *note
Conditions::, *note Reader::, *note Printer::

Notes::
.......

The intent of the constraints on the initial value of the I/O
customization variables is to ensure that it is always safe to bind or
assign such a variable to the value of another I/O customization
variable, without unduly restricting implementation flexibility.

   It is common for an implementation to make the initial values of
*debug-io* and *query-io* be the same stream, and to make the initial
values of *error-output* and *standard-output* be the same stream.

   The functions y-or-n-p and yes-or-no-p use query I/O for their input
and output.

   In the normal Lisp read-eval-print loop, input is read from standard
input.  Many input functions, including read and read-char, take a
stream argument that defaults to standard input.

   In the normal Lisp read-eval-print loop, output is sent to standard
output.  Many output functions, including print and write-char, take a
stream argument that defaults to standard output.

   A program that wants, for example, to divert output to a file should
do so by binding *standard-output*; that way error messages sent to
*error-output* can still get to the user by going through *terminal-io*
(if *error-output* is bound to *terminal-io*), which is usually what is
desired.


File: gcl.info,  Node: *terminal-io*,  Next: stream-error,  Prev: *debug-io*,  Up: Streams Dictionary

21.2.54 *terminal-io* [Variable]
--------------------------------

Value Type::
............

a bidirectional stream.

Initial Value::
...............

implementation-dependent, but it must be an open stream that is not a
generalized synonym stream to an I/O customization variables but that
might be a generalized synonym stream to the value of some I/O
customization variable.

Description::
.............

The value of *terminal-io*, called terminal I/O, is ordinarily a
bidirectional stream that connects to the user's console.  Typically,
writing to this stream would cause the output to appear on a display
screen, for example, and reading from the stream would accept input from
a keyboard.  It is intended that standard input functions such as read
and read-char, when used with this stream, cause echoing of the input
into the output side of the stream.  The means by which this is
accomplished are implementation-dependent.

   The effect of changing the value of *terminal-io*, either by binding
or assignment, is implementation-defined.

Examples::
..........

      (progn (prin1 'foo) (prin1 'bar *terminal-io*))
      |>  FOOBAR
     =>  BAR
      (with-output-to-string (*standard-output*)
        (prin1 'foo)
        (prin1 'bar *terminal-io*))
      |>  BAR
     =>  "FOO"

See Also::
..........

*debug-io*, *error-output*, *query-io*, *standard-input*,
*standard-output*, *trace-output*


File: gcl.info,  Node: stream-error,  Next: stream-error-stream,  Prev: *terminal-io*,  Up: Streams Dictionary

21.2.55 stream-error [Condition Type]
-------------------------------------

Class Precedence List::
.......................

stream-error, error, serious-condition, condition, t

Description::
.............

The type stream-error consists of error conditions that are related to
receiving input from or sending output to a stream.  The "offending
stream" is initialized by the :stream initialization argument to
make-condition, and is accessed by the function stream-error-stream.

See Also::
..........

*note stream-error-stream::


File: gcl.info,  Node: stream-error-stream,  Next: end-of-file,  Prev: stream-error,  Up: Streams Dictionary

21.2.56 stream-error-stream [Function]
--------------------------------------

'stream-error-stream' condition => stream

Arguments and Values::
......................

condition--a condition of type stream-error.

   stream--a stream.

Description::
.............

Returns the offending stream of a condition of type stream-error.

Examples::
..........

      (with-input-from-string (s "(FOO")
        (handler-case (read s)
          (end-of-file (c)
            (format nil "~&End of file on ~S." (stream-error-stream c)))))
     "End of file on #<String Stream>."

See Also::
..........

stream-error, *note Conditions::


File: gcl.info,  Node: end-of-file,  Prev: stream-error-stream,  Up: Streams Dictionary

21.2.57 end-of-file [Condition Type]
------------------------------------

Class Precedence List::
.......................

end-of-file, stream-error, error, serious-condition, condition, t

Description::
.............

The type end-of-file consists of error conditions related to read
operations that are done on streams that have no more data.

See Also::
..........

*note stream-error-stream::

