diff options
Diffstat (limited to 'doc')
46 files changed, 617 insertions, 3974 deletions
diff --git a/doc/ref/api-compound.texi b/doc/ref/api-compound.texi index 03891fac4..6fc5b2e46 100644 --- a/doc/ref/api-compound.texi +++ b/doc/ref/api-compound.texi @@ -326,7 +326,7 @@ the last pair of the list. @c no-op since it does nothing but return the list the caller must @c have already created. @c -@deffn {Scheme Procedure} list elem1 @dots{} elemN +@deffn {Scheme Procedure} list elem @dots{} @deffnx {C Function} scm_list_1 (elem1) @deffnx {C Function} scm_list_2 (elem1, elem2) @deffnx {C Function} scm_list_3 (elem1, elem2, elem3) @@ -334,11 +334,11 @@ the last pair of the list. @deffnx {C Function} scm_list_5 (elem1, elem2, elem3, elem4, elem5) @deffnx {C Function} scm_list_n (elem1, @dots{}, elemN, @nicode{SCM_UNDEFINED}) @rnindex list -Return a new list containing elements @var{elem1} to @var{elemN}. +Return a new list containing elements @var{elem} @enddots{}. @code{scm_list_n} takes a variable number of arguments, terminated by the special @code{SCM_UNDEFINED}. That final @code{SCM_UNDEFINED} is -not included in the list. None of @var{elem1} to @var{elemN} can +not included in the list. None of @var{elem} @dots{} can themselves be @code{SCM_UNDEFINED}, or @code{scm_list_n} will terminate at that point. @end deffn @@ -430,12 +430,14 @@ pairs. This is why you should be careful when using the side-effecting variants. @rnindex append -@deffn {Scheme Procedure} append lst1 @dots{} lstN -@deffnx {Scheme Procedure} append! lst1 @dots{} lstN +@deffn {Scheme Procedure} append lst @dots{} obj +@deffnx {Scheme Procedure} append +@deffnx {Scheme Procedure} append! lst @dots{} obj +@deffnx {Scheme Procedure} append! @deffnx {C Function} scm_append (lstlst) @deffnx {C Function} scm_append_x (lstlst) -Return a list comprising all the elements of lists @var{lst1} to -@var{lstN}. +Return a list comprising all the elements of lists @var{lst} @dots{} +@var{obj}. If called with no arguments, return the empty list. @lisp (append '(x) '(y)) @result{} (x y) @@ -443,7 +445,7 @@ Return a list comprising all the elements of lists @var{lst1} to (append '(a (b)) '((c))) @result{} (a (b) (c)) @end lisp -The last argument @var{lstN} may actually be any object; an improper +The last argument @var{obj} may actually be any object; an improper list results if the last argument is not a proper list. @lisp @@ -452,11 +454,11 @@ list results if the last argument is not a proper list. @end lisp @code{append} doesn't modify the given lists, but the return may share -structure with the final @var{lstN}. @code{append!} modifies the +structure with the final @var{obj}. @code{append!} modifies the given lists to form its return. For @code{scm_append} and @code{scm_append_x}, @var{lstlst} is a list -of the list operands @var{lst1} @dots{} @var{lstN}. That @var{lstlst} +of the list operands @var{lst} @dots{} @var{obj}. That @var{lstlst} itself is not modified or used in the return. @end deffn @@ -709,7 +711,7 @@ thus created is determined implicitly by the number of arguments given. @rnindex vector @rnindex list->vector -@deffn {Scheme Procedure} vector . l +@deffn {Scheme Procedure} vector arg @dots{} @deffnx {Scheme Procedure} list->vector l @deffnx {C Function} scm_vector (l) Return a newly allocated vector composed of the @@ -775,19 +777,19 @@ in the vector. @rnindex vector-length @deffn {Scheme Procedure} vector-length vector -@deffnx {C Function} scm_vector_length vector +@deffnx {C Function} scm_vector_length (vector) Return the number of elements in @var{vector} as an exact integer. @end deffn -@deftypefn {C Function} size_t scm_c_vector_length (SCM v) -Return the number of elements in @var{vector} as a @code{size_t}. +@deftypefn {C Function} size_t scm_c_vector_length (SCM vec) +Return the number of elements in @var{vec} as a @code{size_t}. @end deftypefn @rnindex vector-ref -@deffn {Scheme Procedure} vector-ref vector k -@deffnx {C Function} scm_vector_ref vector k -Return the contents of position @var{k} of @var{vector}. -@var{k} must be a valid index of @var{vector}. +@deffn {Scheme Procedure} vector-ref vec k +@deffnx {C Function} scm_vector_ref (vec, k) +Return the contents of position @var{k} of @var{vec}. +@var{k} must be a valid index of @var{vec}. @lisp (vector-ref '#(1 1 2 3 5 8 13 21) 5) @result{} 8 (vector-ref '#(1 1 2 3 5 8 13 21) @@ -798,9 +800,9 @@ Return the contents of position @var{k} of @var{vector}. @end lisp @end deffn -@deftypefn {C Function} SCM scm_c_vector_ref (SCM v, size_t k) +@deftypefn {C Function} SCM scm_c_vector_ref (SCM vec, size_t k) Return the contents of position @var{k} (a @code{size_t}) of -@var{vector}. +@var{vec}. @end deftypefn A vector created by one of the dynamic vector constructor procedures @@ -813,10 +815,10 @@ considered as constants. Currently, however, Guile does not detect this error. @rnindex vector-set! -@deffn {Scheme Procedure} vector-set! vector k obj -@deffnx {C Function} scm_vector_set_x vector k obj -Store @var{obj} in position @var{k} of @var{vector}. -@var{k} must be a valid index of @var{vector}. +@deffn {Scheme Procedure} vector-set! vec k obj +@deffnx {C Function} scm_vector_set_x (vec, k, obj) +Store @var{obj} in position @var{k} of @var{vec}. +@var{k} must be a valid index of @var{vec}. The value returned by @samp{vector-set!} is unspecified. @lisp (let ((vec (vector 0 '(2 2 2 2) "Anna"))) @@ -825,14 +827,14 @@ The value returned by @samp{vector-set!} is unspecified. @end lisp @end deffn -@deftypefn {C Function} void scm_c_vector_set_x (SCM v, size_t k, SCM obj) -Store @var{obj} in position @var{k} (a @code{size_t}) of @var{v}. +@deftypefn {C Function} void scm_c_vector_set_x (SCM vec, size_t k, SCM obj) +Store @var{obj} in position @var{k} (a @code{size_t}) of @var{vec}. @end deftypefn @rnindex vector-fill! -@deffn {Scheme Procedure} vector-fill! v fill -@deffnx {C Function} scm_vector_fill_x (v, fill) -Store @var{fill} in every position of @var{vector}. The value +@deffn {Scheme Procedure} vector-fill! vec fill +@deffnx {C Function} scm_vector_fill_x (vec, fill) +Store @var{fill} in every position of @var{vec}. The value returned by @code{vector-fill!} is unspecified. @end deffn @@ -1010,7 +1012,7 @@ Like @code{scm_make_bitvector}, but the length is given as a @code{size_t}. @end deftypefn -@deffn {Scheme Procedure} bitvector . bits +@deffn {Scheme Procedure} bitvector bit @dots{} @deffnx {C Function} scm_bitvector (bits) Create a new bitvector with the arguments as elements. @end deffn @@ -1031,7 +1033,7 @@ Return the element at index @var{idx} of the bitvector @var{vec}. @end deffn -@deftypefn {C Function} SCM scm_c_bitvector_ref (SCM obj, size_t idx) +@deftypefn {C Function} SCM scm_c_bitvector_ref (SCM vec, size_t idx) Return the element at index @var{idx} of the bitvector @var{vec}. @end deftypefn @@ -1042,7 +1044,7 @@ Set the element at index @var{idx} of the bitvector @var{vec} when @var{val} is true, else clear it. @end deffn -@deftypefn {C Function} SCM scm_c_bitvector_set_x (SCM obj, size_t idx, SCM val) +@deftypefn {C Function} SCM scm_c_bitvector_set_x (SCM vec, size_t idx, SCM val) Set the element at index @var{idx} of the bitvector @var{vec} when @var{val} is true, else clear it. @end deftypefn @@ -1427,8 +1429,8 @@ stored in the variable @code{*unspecified*} so that for example @code{(make-typed-array 'u32 *unspecified* 4)} creates a uninitialized @code{u32} vector of length 4. -Each @var{bound} may be a positive non-zero integer @var{N}, in which -case the index for that dimension can range from 0 through @var{N-1}; or +Each @var{bound} may be a positive non-zero integer @var{n}, in which +case the index for that dimension can range from 0 through @var{n}-1; or an explicit index range specifier in the form @code{(LOWER UPPER)}, where both @var{lower} and @var{upper} are integers, possibly less than zero, and possibly the same number (however, @var{lower} cannot be @@ -1512,8 +1514,8 @@ For example, @end example @end deffn -@deffn {Scheme Procedure} array-rank obj -@deffnx {C Function} scm_array_rank (obj) +@deffn {Scheme Procedure} array-rank array +@deffnx {C Function} scm_array_rank (array) Return the rank of @var{array}. @end deffn @@ -1546,7 +1548,7 @@ is unspecified. @end deffn @c begin (texi-doc-string "guile" "array-equal?") -@deffn {Scheme Procedure} array-equal? array1 array2 @dots{} +@deffn {Scheme Procedure} array-equal? array @dots{} Return @code{#t} if all arguments are arrays with the same shape, the same type, and have corresponding elements which are either @code{equal?} or @code{array-equal?}. This function differs from @@ -1563,7 +1565,7 @@ same type, and have corresponding elements which are either @c at least vaguely matches array-map!, but is it meant to be a @c documented feature? -@deffn {Scheme Procedure} array-map! dst proc src1 @dots{} srcN +@deffn {Scheme Procedure} array-map! dst proc src @dots{} @deffnx {Scheme Procedure} array-map-in-order! dst proc src1 @dots{} srcN @deffnx {C Function} scm_array_map_x (dst, proc, srclist) Set each element of the @var{dst} array to values obtained from calls @@ -1580,10 +1582,10 @@ range in @var{dst}. This ensures all @var{dst} indices are valid in each @var{src}. @end deffn -@deffn {Scheme Procedure} array-for-each proc src1 @dots{} srcN +@deffn {Scheme Procedure} array-for-each proc src1 src2 @dots{} @deffnx {C Function} scm_array_for_each (proc, src1, srclist) -Apply @var{proc} to each tuple of elements of @var{src1} @dots{} -@var{srcN}, in row-major order. The value returned is unspecified. +Apply @var{proc} to each tuple of elements of @var{src1} @var{src2} +@dots{}, in row-major order. The value returned is unspecified. @end deffn @deffn {Scheme Procedure} array-index-map! dst proc @@ -1625,10 +1627,10 @@ $\left(\matrix{% @deffn {Scheme Procedure} uniform-array-read! ra [port_or_fd [start [end]]] @deffnx {C Function} scm_uniform_array_read_x (ra, port_or_fd, start, end) -Attempt to read all elements of @var{ura}, in lexicographic order, as -binary objects from @var{port-or-fdes}. +Attempt to read all elements of array @var{ra}, in lexicographic order, as +binary objects from @var{port_or_fd}. If an end of file is encountered, -the objects up to that point are put into @var{ura} +the objects up to that point are put into @var{ra} (starting at the beginning) and the remainder of the array is unchanged. @@ -1637,21 +1639,21 @@ a specified region of a vector (or linearized array) to be read, leaving the remainder of the vector unchanged. @code{uniform-array-read!} returns the number of objects read. -@var{port-or-fdes} may be omitted, in which case it defaults to the value +@var{port_or_fd} may be omitted, in which case it defaults to the value returned by @code{(current-input-port)}. @end deffn -@deffn {Scheme Procedure} uniform-array-write v [port_or_fd [start [end]]] -@deffnx {C Function} scm_uniform_array_write (v, port_or_fd, start, end) -Writes all elements of @var{ura} as binary objects to -@var{port-or-fdes}. +@deffn {Scheme Procedure} uniform-array-write ra [port_or_fd [start [end]]] +@deffnx {C Function} scm_uniform_array_write (ra, port_or_fd, start, end) +Writes all elements of @var{ra} as binary objects to +@var{port_or_fd}. The optional arguments @var{start} and @var{end} allow a specified region of a vector (or linearized array) to be written. The number of objects actually written is returned. -@var{port-or-fdes} may be +@var{port_or_fd} may be omitted, in which case it defaults to the value returned by @code{(current-output-port)}. @end deffn @@ -1663,7 +1665,7 @@ omitted, in which case it defaults to the value returned by @deffnx {C Function} scm_make_shared_array (oldarray, mapfunc, boundlist) Return a new array which shares the storage of @var{oldarray}. Changes made through either affect the same underlying storage. The -@var{bound@dots{}} arguments are the shape of the new array, the same +@var{bound} @dots{} arguments are the shape of the new array, the same as @code{make-array} (@pxref{Array Procedures}). @var{mapfunc} translates coordinates from the new array to the @@ -1793,7 +1795,7 @@ be returned only if its elements are stored internally contiguous in memory. @end deffn -@deffn {Scheme Procedure} transpose-array array dim1 @dots{} +@deffn {Scheme Procedure} transpose-array array dim1 dim2 @dots{} @deffnx {C Function} scm_transpose_array (array, dimlist) Return an array sharing contents with @var{array}, but with dimensions arranged in a different order. There must be one @@ -2235,7 +2237,7 @@ Return a new vlist, as for SRFI-1 @code{unfold} and @code{unfold-right} (@pxref{SRFI-1, @code{unfold}}). @end deffn -@deffn {Scheme Procedure} vlist-append vlists ... +@deffn {Scheme Procedure} vlist-append vlist @dots{} Append the given vlists and return the resulting vlist. @end deffn @@ -2465,7 +2467,7 @@ This section describes the basic procedures for working with structures. @code{make-struct} creates a structure, and @code{struct-ref} and @code{struct-set!} access write fields. -@deffn {Scheme Procedure} make-struct vtable tail-size [init...] +@deffn {Scheme Procedure} make-struct vtable tail-size init @dots{} @deffnx {C Function} scm_make_struct (vtable, tail_size, init_list) Create a new structure, with layout per the given @var{vtable} (@pxref{Vtables}). diff --git a/doc/ref/api-control.texi b/doc/ref/api-control.texi index 7935d5633..fc5935070 100644 --- a/doc/ref/api-control.texi +++ b/doc/ref/api-control.texi @@ -44,7 +44,7 @@ If the test is true, we want to display ``greater'' to the current output port, then display a newline. We use @code{begin} to form a compound expression out of this sequence of sub-expressions. -@deffn syntax begin expr1 expr2 @dots{} +@deffn syntax begin expr @dots{} The expression(s) are evaluated in left-to-right order and the value of the last expression is returned as the value of the @code{begin}-expression. This expression type is used when the @@ -277,7 +277,7 @@ Scheme programs is normally expressed using recursion. Nevertheless, R5RS defines a construct for programming loops, calling @code{do}. In addition, Guile has an explicit looping syntax called @code{while}. -@deffn syntax do ((variable init [step]) @dots{}) (test [expr @dots{}]) body @dots{} +@deffn syntax do ((variable init [step]) @dots{}) (test expr @dots{}) body @dots{} Bind @var{variable}s and evaluate @var{body} until @var{test} is true. The return value is the last @var{expr} after @var{test}, if given. A simple example will illustrate the basic form, @@ -348,7 +348,7 @@ Run a loop executing the @var{body} forms while @var{cond} is true. Within @code{while}, two extra bindings are provided, they can be used from both @var{cond} and @var{body}. -@deffn {Scheme Procedure} break break-arg... +@deffn {Scheme Procedure} break break-arg @dots{} Break out of the @code{while} form. @end deffn @@ -487,7 +487,7 @@ tag allows some useful prompt and abort idioms, discussed in the next section. @end deffn -@deffn {Scheme Procedure} abort-to-prompt tag val ... +@deffn {Scheme Procedure} abort-to-prompt tag val1 val2 @dots{} Unwind the dynamic and control context to the nearest prompt named @var{tag}, also passing the given values. @end deffn @@ -599,8 +599,9 @@ The @code{%} symbol is chosen because it looks like a prompt. Likewise there is an abbreviation for @code{abort-to-prompt}, which assumes the default prompt tag: -@deffn {Scheme Procedure} abort val... -Abort to the default prompt tag, passing @var{val...} to the handler. +@deffn {Scheme Procedure} abort val1 val2 @dots{} +Abort to the default prompt tag, passing @var{val1} @var{val2} @dots{} +to the handler. @end deffn As mentioned before, @code{(ice-9 control)} also provides other @@ -627,19 +628,22 @@ If both continuation and handler implicitly add prompts, then the operator is @dfn{+F+}. @code{shift} and @code{reset} are such operators. -@deffn {Scheme Syntax} reset body... -Establish a prompt, and evaluate @var{body...} within that prompt. +@deffn {Scheme Syntax} reset body1 body2 @dots{} +Establish a prompt, and evaluate @var{body1} @var{body2} @dots{} within +that prompt. The prompt handler is designed to work with @code{shift}, described below. @end deffn -@deffn {Scheme Syntax} shift cont body... -Abort to the nearest @code{reset}, and evaluate @var{body...} in a -context in which the captured continuation is bound to @var{cont}. +@deffn {Scheme Syntax} shift cont body1 body2 @dots{} +Abort to the nearest @code{reset}, and evaluate @var{body1} @var{body2} +@dots{} in a context in which the captured continuation is bound to +@var{cont}. -As mentioned above, both the @var{body...} expression and invocations of -@var{cont} implicitly establish a prompt. +As mentioned above, taken together, the @var{body1} @var{body2} @dots{} +expressions and the invocations of @var{cont} implicitly establish a +prompt. @end deffn Interested readers are invited to explore Oleg Kiselyov's wonderful web @@ -803,7 +807,7 @@ multiple values with a procedure which accepts these values as parameters. @rnindex values -@deffn {Scheme Procedure} values arg1 @dots{} argN +@deffn {Scheme Procedure} values arg @dots{} @deffnx {C Function} scm_values (args) Delivers all of its arguments to its continuation. Except for continuations created by the @code{call-with-values} procedure, @@ -1220,10 +1224,10 @@ depends on the exception type. The documentation for each possible type of exception should specify the additional arguments that are expected for that kind of exception. -@deffn {Scheme Procedure} throw key . args +@deffn {Scheme Procedure} throw key arg @dots{} @deffnx {C Function} scm_throw (key, args) -Invoke the catch form matching @var{key}, passing @var{args} to the -@var{handler}. +Invoke the catch form matching @var{key}, passing @var{arg} @dots{} to +the @var{handler}. @var{key} is a symbol. It will match catches of the same symbol or of @code{#t}. @@ -1312,9 +1316,9 @@ Guile provides a set of convenience procedures for signaling error conditions that are implemented on top of the exception primitives just described. -@deffn {Scheme Procedure} error msg args @dots{} +@deffn {Scheme Procedure} error msg arg @dots{} Raise an error with key @code{misc-error} and a message constructed by -displaying @var{msg} and writing @var{args}. +displaying @var{msg} and writing @var{arg} @enddots{}. @end deffn @deffn {Scheme Procedure} scm-error key subr message args data diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi index bcfbae365..4fc11c81d 100644 --- a/doc/ref/api-data.texi +++ b/doc/ref/api-data.texi @@ -695,10 +695,10 @@ value, including the special values @samp{+nan.0}, @samp{+inf.0} and @deffn {Scheme Procedure} complex? z @deffnx {C Function} scm_complex_p (z) -Return @code{#t} if @var{x} is a complex number, @code{#f} +Return @code{#t} if @var{z} is a complex number, @code{#f} otherwise. Note that the sets of real, rational and integer values form subsets of the set of complex numbers, i.e.@: the -predicate will also be fulfilled if @var{x} is a real, +predicate will also be fulfilled if @var{z} is a real, rational or integer number. @end deffn @@ -2324,22 +2324,22 @@ Return @code{#t} if @var{obj} is a character set, @code{#f} otherwise. @end deffn -@deffn {Scheme Procedure} char-set= . char_sets +@deffn {Scheme Procedure} char-set= char_set @dots{} @deffnx {C Function} scm_char_set_eq (char_sets) Return @code{#t} if all given character sets are equal. @end deffn -@deffn {Scheme Procedure} char-set<= . char_sets +@deffn {Scheme Procedure} char-set<= char_set @dots{} @deffnx {C Function} scm_char_set_leq (char_sets) -Return @code{#t} if every character set @var{cs}i is a subset -of character set @var{cs}i+1. +Return @code{#t} if every character set @var{char_set}i is a subset +of character set @var{char_set}i+1. @end deffn @deffn {Scheme Procedure} char-set-hash cs [bound] @deffnx {C Function} scm_char_set_hash (cs, bound) Compute a hash value for the character set @var{cs}. If @var{bound} is given and non-zero, it restricts the -returned value to the range 0 @dots{} @var{bound - 1}. +returned value to the range 0 @dots{} @var{bound} - 1. @end deffn @c =================================================================== @@ -2443,8 +2443,8 @@ Return a newly allocated character set containing all characters in @var{cs}. @end deffn -@deffn {Scheme Procedure} char-set . rest -@deffnx {C Function} scm_char_set (rest) +@deffn {Scheme Procedure} char-set chr @dots{} +@deffnx {C Function} scm_char_set (chrs) Return a character set containing all given characters. @end deffn @@ -2607,26 +2607,26 @@ such as union, complement, intersection etc. All of these procedures provide side-effecting variants, which modify their character set argument(s). -@deffn {Scheme Procedure} char-set-adjoin cs . rest -@deffnx {C Function} scm_char_set_adjoin (cs, rest) +@deffn {Scheme Procedure} char-set-adjoin cs chr @dots{} +@deffnx {C Function} scm_char_set_adjoin (cs, chrs) Add all character arguments to the first argument, which must be a character set. @end deffn -@deffn {Scheme Procedure} char-set-delete cs . rest -@deffnx {C Function} scm_char_set_delete (cs, rest) +@deffn {Scheme Procedure} char-set-delete cs chr @dots{} +@deffnx {C Function} scm_char_set_delete (cs, chrs) Delete all character arguments from the first argument, which must be a character set. @end deffn -@deffn {Scheme Procedure} char-set-adjoin! cs . rest -@deffnx {C Function} scm_char_set_adjoin_x (cs, rest) +@deffn {Scheme Procedure} char-set-adjoin! cs chr @dots{} +@deffnx {C Function} scm_char_set_adjoin_x (cs, chrs) Add all character arguments to the first argument, which must be a character set. @end deffn -@deffn {Scheme Procedure} char-set-delete! cs . rest -@deffnx {C Function} scm_char_set_delete_x (cs, rest) +@deffn {Scheme Procedure} char-set-delete! cs chr @dots{} +@deffnx {C Function} scm_char_set_delete_x (cs, chrs) Delete all character arguments from the first argument, which must be a character set. @end deffn @@ -2642,28 +2642,28 @@ characters). It may be helpful to modify the output of @code{char-set-complement} by computing its intersection with the set of designated code points, @code{char-set:designated}. -@deffn {Scheme Procedure} char-set-union . rest -@deffnx {C Function} scm_char_set_union (rest) +@deffn {Scheme Procedure} char-set-union cs @dots{} +@deffnx {C Function} scm_char_set_union (char_sets) Return the union of all argument character sets. @end deffn -@deffn {Scheme Procedure} char-set-intersection . rest -@deffnx {C Function} scm_char_set_intersection (rest) +@deffn {Scheme Procedure} char-set-intersection cs @dots{} +@deffnx {C Function} scm_char_set_intersection (char_sets) Return the intersection of all argument character sets. @end deffn -@deffn {Scheme Procedure} char-set-difference cs1 . rest -@deffnx {C Function} scm_char_set_difference (cs1, rest) +@deffn {Scheme Procedure} char-set-difference cs1 cs @dots{} +@deffnx {C Function} scm_char_set_difference (cs1, char_sets) Return the difference of all argument character sets. @end deffn -@deffn {Scheme Procedure} char-set-xor . rest -@deffnx {C Function} scm_char_set_xor (rest) +@deffn {Scheme Procedure} char-set-xor cs @dots{} +@deffnx {C Function} scm_char_set_xor (char_sets) Return the exclusive-or of all argument character sets. @end deffn -@deffn {Scheme Procedure} char-set-diff+intersection cs1 . rest -@deffnx {C Function} scm_char_set_diff_plus_intersection (cs1, rest) +@deffn {Scheme Procedure} char-set-diff+intersection cs1 cs @dots{} +@deffnx {C Function} scm_char_set_diff_plus_intersection (cs1, char_sets) Return the difference and the intersection of all argument character sets. @end deffn @@ -2673,28 +2673,28 @@ character sets. Return the complement of the character set @var{cs}. @end deffn -@deffn {Scheme Procedure} char-set-union! cs1 . rest -@deffnx {C Function} scm_char_set_union_x (cs1, rest) +@deffn {Scheme Procedure} char-set-union! cs1 cs @dots{} +@deffnx {C Function} scm_char_set_union_x (cs1, char_sets) Return the union of all argument character sets. @end deffn -@deffn {Scheme Procedure} char-set-intersection! cs1 . rest -@deffnx {C Function} scm_char_set_intersection_x (cs1, rest) +@deffn {Scheme Procedure} char-set-intersection! cs1 cs @dots{} +@deffnx {C Function} scm_char_set_intersection_x (cs1, char_sets) Return the intersection of all argument character sets. @end deffn -@deffn {Scheme Procedure} char-set-difference! cs1 . rest -@deffnx {C Function} scm_char_set_difference_x (cs1, rest) +@deffn {Scheme Procedure} char-set-difference! cs1 cs @dots{} +@deffnx {C Function} scm_char_set_difference_x (cs1, char_sets) Return the difference of all argument character sets. @end deffn -@deffn {Scheme Procedure} char-set-xor! cs1 . rest -@deffnx {C Function} scm_char_set_xor_x (cs1, rest) +@deffn {Scheme Procedure} char-set-xor! cs1 cs @dots{} +@deffnx {C Function} scm_char_set_xor_x (cs1, char_sets) Return the exclusive-or of all argument character sets. @end deffn -@deffn {Scheme Procedure} char-set-diff+intersection! cs1 cs2 . rest -@deffnx {C Function} scm_char_set_diff_plus_intersection_x (cs1, cs2, rest) +@deffn {Scheme Procedure} char-set-diff+intersection! cs1 cs2 cs @dots{} +@deffnx {C Function} scm_char_set_diff_plus_intersection_x (cs1, cs2, char_sets) Return the difference and the intersection of all argument character sets. @end deffn @@ -2714,7 +2714,7 @@ useful, several predefined character set variables exist. These character sets are locale independent and are not recomputed upon a @code{setlocale} call. They contain characters from the whole range of Unicode code points. For instance, @code{char-set:letter} -contains about 94,000 characters. +contains about 100,000 characters. @defvr {Scheme Variable} char-set:lower-case @defvrx {C Variable} scm_char_set_lower_case @@ -3099,7 +3099,7 @@ reverse order. Return a newly allocated string of length @var{k}. If @var{chr} is given, then all elements of the string are initialized to @var{chr}, otherwise the contents -of the @var{string} are unspecified. +of the string are unspecified. @end deffn @deftypefn {C Function} SCM scm_c_make_string (size_t len, SCM chr) @@ -3118,7 +3118,7 @@ produce the corresponding string element. The order in which @deffn {Scheme Procedure} string-join ls [delimiter [grammar]] @deffnx {C Function} scm_string_join (ls, delimiter, grammar) Append the string in the string list @var{ls}, using the string -@var{delim} as a delimiter between the elements of @var{ls}. +@var{delimiter} as a delimiter between the elements of @var{ls}. @var{grammar} is a symbol which specifies how the delimiter is placed between the strings, and defaults to the symbol @code{infix}. @@ -3279,7 +3279,7 @@ Return all but the last @var{n} characters of @var{s}. @deffnx {C Function} scm_string_pad (s, len, chr, start, end) @deffnx {C Function} scm_string_pad_right (s, len, chr, start, end) Take characters @var{start} to @var{end} from the string @var{s} and -either pad with @var{char} or truncate them to give @var{len} +either pad with @var{chr} or truncate them to give @var{len} characters. @code{string-pad} pads or truncates on the left, so for example @@ -3404,11 +3404,11 @@ comparison. See @xref{Text Collation, the @code{(ice-9 i18n)} module}, for locale-dependent string comparison. @rnindex string=? -@deffn {Scheme Procedure} string=? [s1 [s2 . rest]] +@deffn {Scheme Procedure} string=? s1 s2 s3 @dots{} @deffnx {C Function} scm_i_string_equal_p (s1, s2, rest) -Lexicographic equality predicate; return @code{#t} if the two -strings are the same length and contain the same characters in -the same positions, otherwise return @code{#f}. +Lexicographic equality predicate; return @code{#t} if all strings are +the same length and contain the same characters in the same positions, +otherwise return @code{#f}. The procedure @code{string-ci=?} treats upper and lower case letters as though they were the same character, but @@ -3417,72 +3417,80 @@ characters. @end deffn @rnindex string<? -@deffn {Scheme Procedure} string<? [s1 [s2 . rest]] +@deffn {Scheme Procedure} string<? s1 s2 s3 @dots{} @deffnx {C Function} scm_i_string_less_p (s1, s2, rest) -Lexicographic ordering predicate; return @code{#t} if @var{s1} -is lexicographically less than @var{s2}. +Lexicographic ordering predicate; return @code{#t} if, for every pair of +consecutive string arguments @var{str_i} and @var{str_i+1}, @var{str_i} is +lexicographically less than @var{str_i+1}. @end deffn @rnindex string<=? -@deffn {Scheme Procedure} string<=? [s1 [s2 . rest]] +@deffn {Scheme Procedure} string<=? s1 s2 s3 @dots{} @deffnx {C Function} scm_i_string_leq_p (s1, s2, rest) -Lexicographic ordering predicate; return @code{#t} if @var{s1} -is lexicographically less than or equal to @var{s2}. +Lexicographic ordering predicate; return @code{#t} if, for every pair of +consecutive string arguments @var{str_i} and @var{str_i+1}, @var{str_i} is +lexicographically less than or equal to @var{str_i+1}. @end deffn @rnindex string>? -@deffn {Scheme Procedure} string>? [s1 [s2 . rest]] +@deffn {Scheme Procedure} string>? s1 s2 s3 @dots{} @deffnx {C Function} scm_i_string_gr_p (s1, s2, rest) -Lexicographic ordering predicate; return @code{#t} if @var{s1} -is lexicographically greater than @var{s2}. +Lexicographic ordering predicate; return @code{#t} if, for every pair of +consecutive string arguments @var{str_i} and @var{str_i+1}, @var{str_i} is +lexicographically greater than @var{str_i+1}. @end deffn @rnindex string>=? -@deffn {Scheme Procedure} string>=? [s1 [s2 . rest]] +@deffn {Scheme Procedure} string>=? s1 s2 s3 @dots{} @deffnx {C Function} scm_i_string_geq_p (s1, s2, rest) -Lexicographic ordering predicate; return @code{#t} if @var{s1} -is lexicographically greater than or equal to @var{s2}. +Lexicographic ordering predicate; return @code{#t} if, for every pair of +consecutive string arguments @var{str_i} and @var{str_i+1}, @var{str_i} is +lexicographically greater than or equal to @var{str_i+1}. @end deffn @rnindex string-ci=? -@deffn {Scheme Procedure} string-ci=? [s1 [s2 . rest]] +@deffn {Scheme Procedure} string-ci=? s1 s2 s3 @dots{} @deffnx {C Function} scm_i_string_ci_equal_p (s1, s2, rest) Case-insensitive string equality predicate; return @code{#t} if -the two strings are the same length and their component +all strings are the same length and their component characters match (ignoring case) at each position; otherwise return @code{#f}. @end deffn @rnindex string-ci<? -@deffn {Scheme Procedure} string-ci<? [s1 [s2 . rest]] +@deffn {Scheme Procedure} string-ci<? s1 s2 s3 @dots{} @deffnx {C Function} scm_i_string_ci_less_p (s1, s2, rest) -Case insensitive lexicographic ordering predicate; return -@code{#t} if @var{s1} is lexicographically less than @var{s2} +Case insensitive lexicographic ordering predicate; return @code{#t} if, +for every pair of consecutive string arguments @var{str_i} and +@var{str_i+1}, @var{str_i} is lexicographically less than @var{str_i+1} regardless of case. @end deffn @rnindex string<=? -@deffn {Scheme Procedure} string-ci<=? [s1 [s2 . rest]] +@deffn {Scheme Procedure} string-ci<=? s1 s2 s3 @dots{} @deffnx {C Function} scm_i_string_ci_leq_p (s1, s2, rest) -Case insensitive lexicographic ordering predicate; return -@code{#t} if @var{s1} is lexicographically less than or equal -to @var{s2} regardless of case. +Case insensitive lexicographic ordering predicate; return @code{#t} if, +for every pair of consecutive string arguments @var{str_i} and +@var{str_i+1}, @var{str_i} is lexicographically less than or equal to +@var{str_i+1} regardless of case. @end deffn @rnindex string-ci>? -@deffn {Scheme Procedure} string-ci>? [s1 [s2 . rest]] +@deffn {Scheme Procedure} string-ci>? s1 s2 s3 @dots{} @deffnx {C Function} scm_i_string_ci_gr_p (s1, s2, rest) -Case insensitive lexicographic ordering predicate; return -@code{#t} if @var{s1} is lexicographically greater than -@var{s2} regardless of case. +Case insensitive lexicographic ordering predicate; return @code{#t} if, +for every pair of consecutive string arguments @var{str_i} and +@var{str_i+1}, @var{str_i} is lexicographically greater than +@var{str_i+1} regardless of case. @end deffn @rnindex string-ci>=? -@deffn {Scheme Procedure} string-ci>=? [s1 [s2 . rest]] +@deffn {Scheme Procedure} string-ci>=? s1 s2 s3 @dots{} @deffnx {C Function} scm_i_string_ci_geq_p (s1, s2, rest) -Case insensitive lexicographic ordering predicate; return -@code{#t} if @var{s1} is lexicographically greater than or -equal to @var{s2} regardless of case. +Case insensitive lexicographic ordering predicate; return @code{#t} if, +for every pair of consecutive string arguments @var{str_i} and +@var{str_i+1}, @var{str_i} is lexicographically greater than or equal to +@var{str_i+1} regardless of case. @end deffn @deffn {Scheme Procedure} string-compare s1 s2 proc_lt proc_eq proc_gt [start1 [end1 [start2 [end2]]]] @@ -3587,12 +3595,12 @@ case-insensitively. @deffn {Scheme Procedure} string-hash s [bound [start [end]]] @deffnx {C Function} scm_substring_hash (s, bound, start, end) -Compute a hash value for @var{S}. The optional argument @var{bound} is a non-negative exact integer specifying the range of the hash function. A positive value restricts the return value to the range [0,bound). +Compute a hash value for @var{s}. The optional argument @var{bound} is a non-negative exact integer specifying the range of the hash function. A positive value restricts the return value to the range [0,bound). @end deffn @deffn {Scheme Procedure} string-hash-ci s [bound [start [end]]] @deffnx {C Function} scm_substring_hash_ci (s, bound, start, end) -Compute a hash value for @var{S}. The optional argument @var{bound} is a non-negative exact integer specifying the range of the hash function. A positive value restricts the return value to the range [0,bound). +Compute a hash value for @var{s}. The optional argument @var{bound} is a non-negative exact integer specifying the range of the hash function. A positive value restricts the return value to the range [0,bound). @end deffn Because the same visual appearance of an abstract Unicode character can @@ -3934,10 +3942,10 @@ operate on. The return value is unspecified. @end deffn @rnindex string-append -@deffn {Scheme Procedure} string-append . args +@deffn {Scheme Procedure} string-append arg @dots{} @deffnx {C Function} scm_string_append (args) Return a newly allocated string whose characters form the -concatenation of the given strings, @var{args}. +concatenation of the given strings, @var{arg} @enddots{}. @example (let ((h "hello ")) @@ -3946,17 +3954,16 @@ concatenation of the given strings, @var{args}. @end example @end deffn -@deffn {Scheme Procedure} string-append/shared . rest -@deffnx {C Function} scm_string_append_shared (rest) +@deffn {Scheme Procedure} string-append/shared arg @dots{} +@deffnx {C Function} scm_string_append_shared (args) Like @code{string-append}, but the result may share memory with the argument strings. @end deffn @deffn {Scheme Procedure} string-concatenate ls @deffnx {C Function} scm_string_concatenate (ls) -Append the elements of @var{ls} (which must be strings) -together into a single string. Guaranteed to return a freshly -allocated string. +Append the elements (which must be strings) of @var{ls} together into a +single string. Guaranteed to return a freshly allocated string. @end deffn @deffn {Scheme Procedure} string-concatenate-reverse ls [final_string [end]] @@ -5181,9 +5188,9 @@ Return a newly allocated symbol made from a list of characters. @end deffn @rnindex symbol-append -@deffn {Scheme Procedure} symbol-append . args +@deffn {Scheme Procedure} symbol-append arg @dots{} Return a newly allocated symbol whose characters form the -concatenation of the given symbols, @var{args}. +concatenation of the given symbols, @var{arg} @enddots{}. @example (let ((h 'hello)) @@ -5253,15 +5260,15 @@ When you want to do more from C, you should convert between symbols and strings using @code{scm_symbol_to_string} and @code{scm_string_to_symbol} and work with the strings. -@deffn {C Function} scm_from_latin1_symbol (const char *name) -@deffnx {C Function} scm_from_utf8_symbol (const char *name) +@deftypefn {C Function} scm_from_latin1_symbol (const char *name) +@deftypefnx {C Function} scm_from_utf8_symbol (const char *name) Construct and return a Scheme symbol whose name is specified by the null-terminated C string @var{name}. These are appropriate when the C string is hard-coded in the source code. -@end deffn +@end deftypefn -@deffn {C Function} scm_from_locale_symbol (const char *name) -@deffnx {C Function} scm_from_locale_symboln (const char *name, size_t len) +@deftypefn {C Function} scm_from_locale_symbol (const char *name) +@deftypefnx {C Function} scm_from_locale_symboln (const char *name, size_t len) Construct and return a Scheme symbol whose name is specified by @var{name}. For @code{scm_from_locale_symbol}, @var{name} must be null terminated; for @code{scm_from_locale_symboln} the length of @var{name} is @@ -5271,7 +5278,7 @@ Note that these functions should @emph{not} be used when @var{name} is a C string constant, because there is no guarantee that the current locale will match that of the source code. In such cases, use @code{scm_from_latin1_symbol} or @code{scm_from_utf8_symbol}. -@end deffn +@end deftypefn @deftypefn {C Function} SCM scm_take_locale_symbol (char *str) @deftypefnx {C Function} SCM scm_take_locale_symboln (char *str, size_t len) diff --git a/doc/ref/api-debug.texi b/doc/ref/api-debug.texi index 2083daab6..cf9ea5aca 100644 --- a/doc/ref/api-debug.texi +++ b/doc/ref/api-debug.texi @@ -80,15 +80,15 @@ describes the Scheme stack at that point. Use @code{start-stack} to limit the stack extent captured by future @code{make-stack} calls. -@deffn {Scheme Procedure} make-stack obj . args +@deffn {Scheme Procedure} make-stack obj arg @dots{} @deffnx {C Function} scm_make_stack (obj, args) Create a new stack. If @var{obj} is @code{#t}, the current evaluation stack is used for creating the stack frames, otherwise the frames are taken from @var{obj} (which must be a continuation or a frame object). -@var{args} should be a list containing any combination of -integer, procedure, prompt tag and @code{#t} values. +@var{arg} @dots{} can be any combination of integer, procedure, prompt +tag and @code{#t} values. These values specify various ways of cutting away uninteresting stack frames from the top and bottom of the stack that @@ -96,7 +96,7 @@ stack frames from the top and bottom of the stack that @code{(@var{inner_cut_1} @var{outer_cut_1} @var{inner_cut_2} @var{outer_cut_2} @dots{})}. -Each @var{inner_cut_N} can be @code{#t}, an integer, a prompt +Each @var{inner_cut_i} can be @code{#t}, an integer, a prompt tag, or a procedure. @code{#t} means to cut away all frames up to but excluding the first user module frame. An integer means to cut away exactly that number of frames. A prompt tag means @@ -105,14 +105,14 @@ tag. A procedure means to cut away all frames up to but excluding the application frame whose procedure matches the specified one. -Each @var{outer_cut_N} can be an integer, a prompt tag, or a +Each @var{outer_cut_i} can be an integer, a prompt tag, or a procedure. An integer means to cut away that number of frames. A prompt tag means to cut away all frames that are outside a prompt with the given tag. A procedure means to cut away frames down to but excluding the application frame whose procedure matches the specified one. -If the @var{outer_cut_N} of the last pair is missing, it is +If the @var{outer_cut_i} of the last pair is missing, it is taken as 0. @end deffn diff --git a/doc/ref/api-evaluation.texi b/doc/ref/api-evaluation.texi index 8c41d1efd..611283225 100644 --- a/doc/ref/api-evaluation.texi +++ b/doc/ref/api-evaluation.texi @@ -444,10 +444,10 @@ it as code. @deffn {Scheme Procedure} eval exp module_or_state @deffnx {C Function} scm_eval (exp, module_or_state) Evaluate @var{exp}, a list representing a Scheme expression, -in the top-level environment specified by @var{module}. +in the top-level environment specified by @var{module_or_state}. While @var{exp} is evaluated (using @code{primitive-eval}), -@var{module} is made the current module. The current module -is reset to its previous value when @var{eval} returns. +@var{module_or_state} is made the current module. The current module +is reset to its previous value when @code{eval} returns. XXX - dynamic states. Example: (eval '(+ 1 2) (interaction-environment)) @end deffn @@ -504,23 +504,22 @@ eval-string)}, evaluating within @var{module} or the current module. of an @code{SCM}. @end deftypefn -@deffn {Scheme Procedure} apply proc arg1 @dots{} argN arglst +@deffn {Scheme Procedure} apply proc arg @dots{} arglst @deffnx {C Function} scm_apply_0 (proc, arglst) @deffnx {C Function} scm_apply_1 (proc, arg1, arglst) @deffnx {C Function} scm_apply_2 (proc, arg1, arg2, arglst) @deffnx {C Function} scm_apply_3 (proc, arg1, arg2, arg3, arglst) @deffnx {C Function} scm_apply (proc, arg, rest) @rnindex apply -Call @var{proc} with arguments @var{arg1} @dots{} @var{argN} plus the +Call @var{proc} with arguments @var{arg} @dots{} and the elements of the @var{arglst} list. @code{scm_apply} takes parameters corresponding to a Scheme level -@code{(lambda (proc arg . rest) ...)}. So @var{arg} and all but the -last element of the @var{rest} list make up -@var{arg1}@dots{}@var{argN} and the last element of @var{rest} is the -@var{arglst} list. Or if @var{rest} is the empty list @code{SCM_EOL} -then there's no @var{arg1}@dots{}@var{argN} and @var{arg} is the -@var{arglst}. +@code{(lambda (proc arg1 . rest) ...)}. So @var{arg1} and all but the +last element of the @var{rest} list make up @var{arg} @dots{}, and the +last element of @var{rest} is the @var{arglst} list. Or if @var{rest} +is the empty list @code{SCM_EOL} then there's no @var{arg} @dots{}, and +(@var{arg1}) is the @var{arglst}. @var{arglst} is not modified, but the @var{rest} list passed to @code{scm_apply} is modified. @@ -645,6 +644,7 @@ name is as for @code{compile-file} (see below). @item -W @var{warning} @itemx --warn=@var{warning} +@cindex warnings, compiler Emit warnings of type @var{warning}; use @code{--warn=help} for a list of available warnings and their description. Currently recognized warnings include @code{unused-variable}, @code{unused-toplevel}, @@ -1012,7 +1012,7 @@ by @code{file-encoding}, if any, again by using @code{set-port-encoding!}. Then the code can be read as normal. @deffn {Scheme Procedure} file-encoding port -@deffnx {C Function} scm_file_encoding port +@deffnx {C Function} scm_file_encoding (port) Scan the port for an Emacs-like character coding declaration near the top of the contents of a port with random-accessible contents (@pxref{Recognize Coding, how Emacs recognizes file encoding,, emacs, diff --git a/doc/ref/api-foreign.texi b/doc/ref/api-foreign.texi index 6ece7f8ed..2e60d8a22 100644 --- a/doc/ref/api-foreign.texi +++ b/doc/ref/api-foreign.texi @@ -540,7 +540,7 @@ A value returned by @code{dynamic-pointer} is a Scheme wrapper for a C pointer. @deffn {Scheme Procedure} pointer-address pointer -@deffnx {C Function} scm_pointer_address pointer +@deffnx {C Function} scm_pointer_address (pointer) Return the numerical value of @var{pointer}. @example @@ -594,7 +594,7 @@ module contains procedures that can be used to convert byte sequences to Scheme objects such as strings, floating point numbers, or integers. @deffn {Scheme Procedure} pointer->bytevector pointer len [offset [uvec_type]] -@deffnx {C Function} scm_foreign_to_bytevector pointer len offset uvec_type +@deffnx {C Function} scm_foreign_to_bytevector (pointer, len, offset, uvec_type) Return a bytevector aliasing the @var{len} bytes pointed to by @var{pointer}. @@ -614,7 +614,7 @@ Mutating the returned bytevector mutates the memory pointed to by @end deffn @deffn {Scheme Procedure} bytevector->pointer bv [offset] -@deffnx {C Function} scm_bytevector_to_pointer bv offset +@deffnx {C Function} scm_bytevector_to_pointer (bv, offset) Return a pointer pointer aliasing the memory pointed to by @var{bv} or @var{offset} bytes after @var{bv} when @var{offset} is passed. @end deffn @@ -740,7 +740,7 @@ its type, offset, and alignment. Guile has some primitives to support this. @deffn {Scheme Procedure} sizeof type -@deffnx {C Function} scm_sizeof type +@deffnx {C Function} scm_sizeof (type) Return the size of @var{type}, in bytes. @var{type} should be a valid C type, like @code{int}. @@ -751,7 +751,7 @@ also be a list of types, in which case the size of a @end deffn @deffn {Scheme Procedure} alignof type -@deffnx {C Function} scm_alignof type +@deffnx {C Function} scm_alignof (type) Return the alignment of @var{type}, in bytes. @var{type} should be a valid C type, like @code{int}. @@ -801,7 +801,7 @@ Of course, the land of C is not all nouns and no verbs: there are functions too, and Guile allows you to call them. @deffn {Scheme Procedure} pointer->procedure return_type func_ptr arg_types -@deffnx {C Procedure} scm_pointer_to_procedure return_type func_ptr arg_types +@deffnx {C Procedure} scm_pointer_to_procedure (return_type, func_ptr, arg_types) Make a foreign function. Given the foreign void pointer @var{func_ptr}, its argument and diff --git a/doc/ref/api-io.texi b/doc/ref/api-io.texi index 9799c31d5..24c2706df 100644 --- a/doc/ref/api-io.texi +++ b/doc/ref/api-io.texi @@ -129,7 +129,7 @@ this fluid otherwise. @end defvr @deffn {Scheme Procedure} port-encoding port -@deffnx {C Function} scm_port_encoding +@deffnx {C Function} scm_port_encoding (port) Returns, as a string, the character encoding that @var{port} uses to interpret its input and output. The value @code{#f} is equivalent to @code{"ISO-8859-1"}. @end deffn @@ -251,7 +251,7 @@ sequence when the error is raised. @deffn {Scheme Procedure} unread-char cobj [port] @deffnx {C Function} scm_unread_char (cobj, port) -Place @var{char} in @var{port} so that it will be read by the +Place character @var{cobj} in @var{port} so that it will be read by the next read operation. If called multiple times, the unread characters will be read again in last-in first-out order. If @var{port} is not supplied, the current input port is used. @@ -343,7 +343,7 @@ the current output port. @var{message} can contain @code{~A} (was @code{%s}) and @code{~S} (was @code{%S}) escapes. When printed, the escapes are replaced with corresponding members of -@var{ARGS}: +@var{args}: @code{~A} formats using @code{display} and @code{~S} formats using @code{write}. If @var{destination} is @code{#t}, then use the current output @@ -426,7 +426,7 @@ open. @deffn {Scheme Procedure} seek fd_port offset whence @deffnx {C Function} scm_seek (fd_port, offset, whence) -Sets the current position of @var{fd/port} to the integer +Sets the current position of @var{fd_port} to the integer @var{offset}, which is interpreted according to the value of @var{whence}. @@ -441,7 +441,7 @@ Seek from the current position. @defvar SEEK_END Seek from the end of the file. @end defvar -If @var{fd/port} is a file descriptor, the underlying system +If @var{fd_port} is a file descriptor, the underlying system call is @code{lseek}. @var{port} may be a string port. The value returned is the new position in the file. This means @@ -454,7 +454,7 @@ that the current position of a port can be obtained using: @deffn {Scheme Procedure} ftell fd_port @deffnx {C Function} scm_ftell (fd_port) Return an integer representing the current position of -@var{fd/port}, measured from the beginning. Equivalent to: +@var{fd_port}, measured from the beginning. Equivalent to: @lisp (seek port 0 SEEK_CUR) @@ -922,7 +922,7 @@ of the respective current port is restored. The current port setting is managed with @code{dynamic-wind}, so the previous value is restored no matter how @var{thunk} exits (eg.@: an exception), and if @var{thunk} is re-entered (via a captured -continuation) then it's set again to the @var{FILENAME} port. +continuation) then it's set again to the @var{filename} port. The port is closed when @var{thunk} returns normally, but not when exited via an exception or new continuation. This ensures it's still @@ -1414,7 +1414,7 @@ This condition type could be defined by An exception with this type is raised when one of the operations for textual output to a port encounters a character that cannot be translated into bytes by the output direction of the port's transcoder. -@var{Char} is the character that could not be encoded. +@var{char} is the character that could not be encoded. @end deffn @deffn {Scheme Syntax} error-handling-mode @var{error-handling-mode-symbol} @@ -1430,7 +1430,7 @@ symbol acceptable as a @var{handling-mode} argument to raised. @quotation Note - Only the name of @var{error-handling-style-symbol} is significant. + Only the name of @var{error-handling-mode-symbol} is significant. @end quotation The error-handling mode of a transcoder specifies the behavior @@ -1470,7 +1470,7 @@ symbol; and @var{handling-mode}, if present, an error-handling-mode symbol. @var{eol-style} may be omitted, in which case it defaults to the native -end-of-line style of the underlying platform. @var{Handling-mode} may +end-of-line style of the underlying platform. @var{handling-mode} may be omitted, in which case it defaults to @code{replace}. The result is a transcoder with the behavior specified by its arguments. @end deffn @@ -1566,11 +1566,11 @@ encoding. Likewise, Guile does not prevent use of @end deffn @deffn {Scheme Procedure} textual-port? port -Always return @var{#t}, as all ports can be used for textual I/O in +Always return @code{#t}, as all ports can be used for textual I/O in Guile. @end deffn -@deffn {Scheme Procedure} transcoded-port obj +@deffn {Scheme Procedure} transcoded-port binary-port transcoder The @code{transcoded-port} procedure returns a new textual port with the specified @var{transcoder}. Otherwise the new textual port's state is largely the same as @@ -1629,12 +1629,12 @@ of @var{proc}. Return the return values of @var{proc}. @node R6RS Input Ports @subsubsection Input Ports -@deffn {Scheme Procedure} input-port? obj@ +@deffn {Scheme Procedure} input-port? obj Returns @code{#t} if the argument is an input port (or a combined input and output port), and returns @code{#f} otherwise. @end deffn -@deffn {Scheme Procedure} port-eof? port +@deffn {Scheme Procedure} port-eof? input-port Returns @code{#t} if the @code{lookahead-u8} procedure (if @var{input-port} is a binary port) or the @code{lookahead-char} procedure (if @var{input-port} is a textual port) @@ -1648,7 +1648,7 @@ but the port cannot be determined to be at end of file. @deffnx {Scheme Procedure} open-file-input-port filename file-options @deffnx {Scheme Procedure} open-file-input-port filename file-options buffer-mode @deffnx {Scheme Procedure} open-file-input-port filename file-options buffer-mode maybe-transcoder -@var{Maybe-transcoder} must be either a transcoder or @code{#f}. +@var{maybe-transcoder} must be either a transcoder or @code{#f}. The @code{open-file-input-port} procedure returns an input port for the named file. The @var{file-options} and @@ -1718,13 +1718,13 @@ indicating the number of bytes read, or @code{0} to indicate the end-of-file. Optionally, if @var{get-position} is not @code{#f}, it must be a thunk -that will be called when @var{port-position} is invoked on the custom +that will be called when @code{port-position} is invoked on the custom binary port and should return an integer indicating the position within the underlying data stream; if @var{get-position} was not supplied, the -returned port does not support @var{port-position}. +returned port does not support @code{port-position}. Likewise, if @var{set-position!} is not @code{#f}, it should be a -one-argument procedure. When @var{set-port-position!} is invoked on the +one-argument procedure. When @code{set-port-position!} is invoked on the custom binary input port, @var{set-position!} is passed an integer indicating the position of the next byte is to read. @@ -1806,7 +1806,7 @@ end-of-file object (if no data were available). @node R6RS Textual Input @subsubsection Textual Input -@deffn {Scheme Procedure} get-char port +@deffn {Scheme Procedure} get-char textual-input-port Reads from @var{textual-input-port}, blocking as necessary, until a complete character is available from @var{textual-input-port}, or until an end of file is reached. @@ -1817,14 +1817,14 @@ point past the character. If an end of file is reached before any character is read, @code{get-char} returns the end-of-file object. @end deffn -@deffn {Scheme Procedure} lookahead-char port +@deffn {Scheme Procedure} lookahead-char textual-input-port The @code{lookahead-char} procedure is like @code{get-char}, but it does not update @var{textual-input-port} to point past the character. @end deffn -@deffn {Scheme Procedure} get-string-n port count +@deffn {Scheme Procedure} get-string-n textual-input-port count -@var{Count} must be an exact, non-negative integer object, representing +@var{count} must be an exact, non-negative integer object, representing the number of characters to be read. The @code{get-string-n} procedure reads from @var{textual-input-port}, @@ -1840,11 +1840,11 @@ to point just past the characters read. If no characters can be read before an end of file, the end-of-file object is returned. @end deffn -@deffn {Scheme Procedure} get-string-n! port string start count +@deffn {Scheme Procedure} get-string-n! textual-input-port string start count -@var{Start} and @var{count} must be exact, non-negative integer objects, +@var{start} and @var{count} must be exact, non-negative integer objects, with @var{count} representing the number of characters to be read. -@var{String} must be a string with at least $@var{start} + @var{count}$ +@var{string} must be a string with at least $@var{start} + @var{count}$ characters. The @code{get-string-n!} procedure reads from @var{textual-input-port} @@ -1858,7 +1858,7 @@ exact integer object. If no characters can be read before an end of file, the end-of-file object is returned. @end deffn -@deffn {Scheme Procedure} get-string-all port count +@deffn {Scheme Procedure} get-string-all textual-input-port count Reads from @var{textual-input-port} until an end of file, decoding characters in the same manner as @code{get-string-n} and @code{get-string-n!}. @@ -1868,7 +1868,7 @@ all the characters decoded from that data are returned. If no character precedes the end of file, the end-of-file object is returned. @end deffn -@deffn {Scheme Procedure} get-line port +@deffn {Scheme Procedure} get-line textual-input-port Reads from @var{textual-input-port} up to and including the linefeed character or end of file, decoding characters in the same manner as @code{get-string-n} and @code{get-string-n!}. @@ -1887,7 +1887,7 @@ any characters are read, the end-of-file object is returned. @end quotation @end deffn -@deffn {Scheme Procedure} get-datum port count +@deffn {Scheme Procedure} get-datum textual-input-port count Reads an external representation from @var{textual-input-port} and returns the datum it represents. The @code{get-datum} procedure returns the next datum that can be parsed from the given @var{textual-input-port}, updating @@ -2048,7 +2048,7 @@ Writes @var{char} to the port. The @code{put-char} procedure returns @code{put-string} procedure returns an unspecified value. @end deffn -@deffn {Scheme Procedure} put-datum port datum +@deffn {Scheme Procedure} put-datum textual-output-port datum @var{datum} should be a datum value. The @code{put-datum} procedure writes an external representation of @var{datum} to @var{textual-output-port}. The specific external representation is diff --git a/doc/ref/api-macros.texi b/doc/ref/api-macros.texi index f6a03bc32..347d02589 100644 --- a/doc/ref/api-macros.texi +++ b/doc/ref/api-macros.texi @@ -81,8 +81,9 @@ source code will invoke the syntax transformer defined by @var{transformer}. One can also establish local syntactic bindings with @code{let-syntax}. -@deffn {Syntax} let-syntax ((keyword transformer) ...) exp... -Bind @var{keyword...} to @var{transformer...} while expanding @var{exp...}. +@deffn {Syntax} let-syntax ((keyword transformer) @dots{}) exp1 exp2 @dots{} +Bind each @var{keyword} to its corresponding @var{transformer} while +expanding @var{exp1} @var{exp2} @enddots{}. A @code{let-syntax} binding only exists at expansion-time. @@ -104,8 +105,9 @@ top-level, or locally. Just as a local @code{define} expands out to an instance of @code{letrec}, a local @code{define-syntax} expands out to @code{letrec-syntax}. -@deffn {Syntax} letrec-syntax ((keyword transformer) ...) exp... -Bind @var{keyword...} to @var{transformer...} while expanding @var{exp...}. +@deffn {Syntax} letrec-syntax ((keyword transformer) @dots{}) exp1 exp2 @dots{} +Bind each @var{keyword} to its corresponding @var{transformer} while +expanding @var{exp1} @var{exp2} @enddots{}. In the spirit of @code{letrec} versus @code{let}, an expansion produced by @var{transformer} may reference a @var{keyword} bound by the diff --git a/doc/ref/api-memory.texi b/doc/ref/api-memory.texi index 6dca7a270..ff202e00e 100644 --- a/doc/ref/api-memory.texi +++ b/doc/ref/api-memory.texi @@ -398,7 +398,7 @@ set to @var{fill}. The default value for @var{fill} is the empty list. @end deffn -@deffn {Scheme Procedure} weak-vector . l +@deffn {Scheme Procedure} weak-vector elem @dots{} @deffnx {Scheme Procedure} list->weak-vector l @deffnx {C Function} scm_weak_vector (l) Construct a weak vector from a list: @code{weak-vector} uses diff --git a/doc/ref/api-modules.texi b/doc/ref/api-modules.texi index b9f975864..c91c2d409 100644 --- a/doc/ref/api-modules.texi +++ b/doc/ref/api-modules.texi @@ -250,7 +250,7 @@ Export all bindings which should be in the public interface, either by using @code{define-public} or @code{export} (both documented below). @end itemize -@deffn syntax define-module module-name [options @dots{}] +@deffn syntax define-module module-name option @dots{} @var{module-name} is a list of one or more symbols. @lisp @@ -260,8 +260,8 @@ by using @code{define-public} or @code{export} (both documented below). @code{define-module} makes this module available to Guile programs under the given @var{module-name}. -The @var{options} are keyword/value pairs which specify more about the -defined module. The recognized options and their meaning is shown in +@var{option} @dots{} are keyword/value pairs which specify more about the +defined module. The recognized options and their meaning are shown in the following table. @table @code @@ -962,7 +962,7 @@ SCM my_eval_string (SCM str) Like @code{scm_public_lookup} or @code{scm_private_lookup}, but additionally dereferences the variable. If the variable object is unbound, signals an error. Returns the value bound to @var{name} in -@var{module}. +@var{module_name}. @end deftypefn In addition, there are a number of other lookup-related procedures. We @@ -1009,7 +1009,7 @@ module is used instead of the current one. @end deftypefn @deftypefn {C Function} SCM scm_module_reverse_lookup (SCM @var{module}, SCM @var{variable}) -Find the symbol that is bound to @var{variable} in @var{module}. When no such binding is found, return @var{#f}. +Find the symbol that is bound to @var{variable} in @var{module}. When no such binding is found, return @code{#f}. @end deftypefn @deftypefn {C Function} SCM scm_c_define_module ({const char *}@var{name}, void (*@var{init})(void *), void *@var{data}) diff --git a/doc/ref/api-procedures.texi b/doc/ref/api-procedures.texi index 1cecadf10..0e0ad15f2 100644 --- a/doc/ref/api-procedures.texi +++ b/doc/ref/api-procedures.texi @@ -103,7 +103,7 @@ useful mechanism, combining the process of registration (@code{scm_c_make_gsubr}) and definition (@code{scm_define}). @deftypefun SCM scm_c_make_gsubr (const char *name, int req, int opt, int rst, fcn) -Register a C procedure @var{FCN} as a ``subr'' --- a primitive +Register a C procedure @var{fcn} as a ``subr'' --- a primitive subroutine that can be called from Scheme. It will be associated with the given @var{name} but no environment binding will be created. The arguments @var{req}, @var{opt} and @var{rst} specify the number of @@ -115,7 +115,7 @@ to @var{fcn}, but may not exceed 10. The number of rest arguments should be 0 o @end deftypefun @deftypefun SCM scm_c_define_gsubr (const char *name, int req, int opt, int rst, fcn) -Register a C procedure @var{FCN}, as for @code{scm_c_make_gsubr} +Register a C procedure @var{fcn}, as for @code{scm_c_make_gsubr} above, and additionally create a top-level Scheme binding for the procedure in the ``current environment'' using @code{scm_define}. @code{scm_c_define_gsubr} returns a handle for the procedure in the @@ -418,8 +418,8 @@ elements. @code{let-optional} binds all variables simultaneously, while @code{let-optional*} binds them sequentially, consistent with @code{let} and @code{let*} (@pxref{Local Bindings}). -@deffn {library syntax} let-optional rest-arg (binding @dots{}) expr @dots{} -@deffnx {library syntax} let-optional* rest-arg (binding @dots{}) expr @dots{} +@deffn {library syntax} let-optional rest-arg (binding @dots{}) body1 body2 @dots{} +@deffnx {library syntax} let-optional* rest-arg (binding @dots{}) body1 body2 @dots{} These two macros give you an optional argument interface that is very @dfn{Schemey} and introduces no fancy syntax. They are compatible with the scsh macros of the same name, but are slightly extended. Each of @@ -431,22 +431,22 @@ runs out, the remaining vars are bound either to the default values or @code{#f} if no default value was specified. @var{rest-arg} remains bound to whatever may have been left of @var{rest-arg}. -After binding the variables, the expressions @var{expr} @dots{} are -evaluated in order. +After binding the variables, the expressions @var{body1} @var{body2} @dots{} +are evaluated in order. @end deffn Similarly, @code{let-keywords} and @code{let-keywords*} extract values from keyword style argument lists, binding local variables to those values or to defaults. -@deffn {library syntax} let-keywords args allow-other-keys? (binding @dots{}) body @dots{} -@deffnx {library syntax} let-keywords* args allow-other-keys? (binding @dots{}) body @dots{} +@deffn {library syntax} let-keywords args allow-other-keys? (binding @dots{}) body1 body2 @dots{} +@deffnx {library syntax} let-keywords* args allow-other-keys? (binding @dots{}) body1 body2 @dots{} @var{args} is evaluated and should give a list of the form @code{(#:keyword1 value1 #:keyword2 value2 @dots{})}. The -@var{binding}s are variables and default expressions, with the -variables to be set (by name) from the keyword values. The @var{body} -forms are then evaluated and the last is the result. An example will -make the syntax clearest, +@var{binding}s are variables and default expressions, with the variables +to be set (by name) from the keyword values. The @var{body1} +@var{body2} @dots{} forms are then evaluated and the last is the +result. An example will make the syntax clearest, @example (define args '(#:xyzzy "hello" #:foo "world")) @@ -478,12 +478,12 @@ exist for defining macros with the improved argument list handling possibilities. The @code{-public} versions not only define the procedures/macros, but also export them from the current module. -@deffn {library syntax} define*-public formals body +@deffn {library syntax} define*-public formals body1 body2 @dots{} Like a mix of @code{define*} and @code{define-public}. @end deffn -@deffn {library syntax} defmacro* name formals body -@deffnx {library syntax} defmacro*-public name formals body +@deffn {library syntax} defmacro* name formals body1 body2 @dots{} +@deffnx {library syntax} defmacro*-public name formals body1 body2 @dots{} These are just like @code{defmacro} and @code{defmacro-public} except that they take @code{lambda*}-style extended parameter lists, where @code{#:optional}, @code{#:key}, @code{#:allow-other-keys} and @code{#:rest} are allowed with the usual @@ -611,10 +611,11 @@ Return a procedure with the same arity as @var{proc} that returns the @end lisp @end deffn -@deffn {Scheme Procedure} compose proc rest ... -Compose @var{proc} with the procedures in @var{rest}, such that the last -one in @var{rest} is applied first and @var{proc} last, and return the -resulting procedure. The given procedures must have compatible arity. +@deffn {Scheme Procedure} compose proc1 proc2 @dots{} +Compose @var{proc1} with the procedures @var{proc2} @dots{} such that +the last @var{proc} argument is applied first and @var{proc1} last, and +return the resulting procedure. The given procedures must have +compatible arity. @lisp (procedure? (compose 1+ 1-)) @result{} #t @@ -835,9 +836,9 @@ making large procedures inlinable will probably result in an increase in code size. Additionally, the elimination of the call overhead rarely matters for large procedures. -@deffn {Scheme Syntax} define-inlinable (name parameter ...) body ... +@deffn {Scheme Syntax} define-inlinable (name parameter @dots{}) body1 body2 @dots{} Define @var{name} as a procedure with parameters @var{parameter}s and -body @var{body}. +bodies @var{body1}, @var{body2}, @enddots{}. @end deffn @c Local Variables: diff --git a/doc/ref/api-regex.texi b/doc/ref/api-regex.texi index 1435aeb05..11a31fca0 100644 --- a/doc/ref/api-regex.texi +++ b/doc/ref/api-regex.texi @@ -228,7 +228,7 @@ and replace them with the contents of another string. The following functions are convenient ways to do this. @c begin (scm-doc-string "regex.scm" "regexp-substitute") -@deffn {Scheme Procedure} regexp-substitute port match [item@dots{}] +@deffn {Scheme Procedure} regexp-substitute port match item @dots{} Write to @var{port} selected parts of the match structure @var{match}. Or if @var{port} is @code{#f} then form a string from those parts and return that. @@ -276,7 +276,7 @@ re-ordering and hyphenating the fields. @c begin (scm-doc-string "regex.scm" "regexp-substitute") -@deffn {Scheme Procedure} regexp-substitute/global port regexp target [item@dots{}] +@deffn {Scheme Procedure} regexp-substitute/global port regexp target item@dots{} @cindex search and replace Write to @var{port} selected parts of matches of @var{regexp} in @var{target}. If @var{port} is @code{#f} then form a string from diff --git a/doc/ref/api-scheduling.texi b/doc/ref/api-scheduling.texi index 6b0ed22bc..a30166394 100644 --- a/doc/ref/api-scheduling.texi +++ b/doc/ref/api-scheduling.texi @@ -316,15 +316,15 @@ Higher level thread procedures are available by loading the @code{(ice-9 threads)} module. These provide standardized thread creation. -@deffn macro make-thread proc [args@dots{}] -Apply @var{proc} to @var{args} in a new thread formed by +@deffn macro make-thread proc arg @dots{} +Apply @var{proc} to @var{arg} @dots{} in a new thread formed by @code{call-with-new-thread} using a default error handler that display -the error to the current error port. The @var{args@dots{}} +the error to the current error port. The @var{arg} @dots{} expressions are evaluated in the new thread. @end deffn -@deffn macro begin-thread first [rest@dots{}] -Evaluate forms @var{first} and @var{rest} in a new thread formed by +@deffn macro begin-thread expr1 expr2 @dots{} +Evaluate forms @var{expr1} @var{expr2} @dots{} in a new thread formed by @code{call-with-new-thread} using a default error handler that display the error to the current error port. @end deffn @@ -353,10 +353,10 @@ Acquiring requisite mutexes in a fixed order (like always A before B) in all threads is one way to avoid such problems. @sp 1 -@deffn {Scheme Procedure} make-mutex . flags +@deffn {Scheme Procedure} make-mutex flag @dots{} @deffnx {C Function} scm_make_mutex () @deffnx {C Function} scm_make_mutex_with_flags (SCM flags) -Return a new mutex. It is initially unlocked. If @var{flags} is +Return a new mutex. It is initially unlocked. If @var{flag} @dots{} is specified, it must be a list of symbols specifying configuration flags for the newly-created mutex. The supported flags are: @table @code @@ -523,25 +523,25 @@ available from (use-modules (ice-9 threads)) @end example -@deffn macro with-mutex mutex [body@dots{}] -Lock @var{mutex}, evaluate the @var{body} forms, then unlock -@var{mutex}. The return value is the return from the last @var{body} -form. +@deffn macro with-mutex mutex body1 body2 @dots{} +Lock @var{mutex}, evaluate the body @var{body1} @var{body2} @dots{}, +then unlock @var{mutex}. The return value is that returned by the last +body form. The lock, body and unlock form the branches of a @code{dynamic-wind} (@pxref{Dynamic Wind}), so @var{mutex} is automatically unlocked if an -error or new continuation exits @var{body}, and is re-locked if -@var{body} is re-entered by a captured continuation. +error or new continuation exits the body, and is re-locked if +the body is re-entered by a captured continuation. @end deffn -@deffn macro monitor body@dots{} -Evaluate the @var{body} forms, with a mutex locked so only one thread -can execute that code at any one time. The return value is the return -from the last @var{body} form. +@deffn macro monitor body1 body2 @dots{} +Evaluate the body form @var{body1} @var{body2} @dots{} with a mutex +locked so only one thread can execute that code at any one time. The +return value is the return from the last body form. Each @code{monitor} form has its own private mutex and the locking and evaluation is as per @code{with-mutex} above. A standard mutex -(@code{make-mutex}) is used, which means @var{body} must not +(@code{make-mutex}) is used, which means the body must not recursively re-enter the @code{monitor} form. The term ``monitor'' comes from operating system theory, where it @@ -751,12 +751,12 @@ set/restored when control enter or leaves the established dynamic extent. @end deffn -@deffn {Scheme Macro} with-fluids ((fluid value) ...) body... -Execute @var{body...} while each @var{fluid} is set to the -corresponding @var{value}. Both @var{fluid} and @var{value} are -evaluated and @var{fluid} must yield a fluid. @var{body...} is -executed inside a @code{dynamic-wind} and the fluids are set/restored -when control enter or leaves the established dynamic extent. +@deffn {Scheme Macro} with-fluids ((fluid value) @dots{}) body1 body2 @dots{} +Execute body @var{body1} @var{body2} @dots{} while each @var{fluid} is +set to the corresponding @var{value}. Both @var{fluid} and @var{value} +are evaluated and @var{fluid} must yield a fluid. The body is executed +inside a @code{dynamic-wind} and the fluids are set/restored when +control enter or leaves the established dynamic extent. @end deffn @deftypefn {C Function} SCM scm_c_with_fluids (SCM fluids, SCM vals, SCM (*cproc)(void *), void *data) @@ -890,11 +890,11 @@ canonical form. For example, @end example @end defun -@deffn {Scheme Syntax} parameterize ((param value) @dots{}) body @dots{} +@deffn {library syntax} parameterize ((param value) @dots{}) body1 body2 @dots{} Establish a new dynamic scope with the given @var{param}s bound to new -locations and set to the given @var{value}s. @var{body} is evaluated -in that environment, the result is the return from the last form in -@var{body}. +locations and set to the given @var{value}s. @var{body1} @var{body2} +@dots{} is evaluated in that environment. The value returned is that of +last body form. Each @var{param} is an expression which is evaluated to get the parameter object. Often this will just be the name of a variable @@ -1043,33 +1043,32 @@ are implemented in terms of futures (@pxref{Futures}). Thus they are relatively cheap as they re-use existing threads, and portable, since they automatically use one thread per available CPU core. -@deffn syntax parallel expr1 @dots{} exprN +@deffn syntax parallel expr @dots{} Evaluate each @var{expr} expression in parallel, each in its own thread. -Return the results as a set of @var{N} multiple values -(@pxref{Multiple Values}). +Return the results of @var{n} expressions as a set of @var{n} multiple +values (@pxref{Multiple Values}). @end deffn -@deffn syntax letpar ((var1 expr1) @dots{} (varN exprN)) body@dots{} +@deffn syntax letpar ((var expr) @dots{}) body1 body2 @dots{} Evaluate each @var{expr} in parallel, each in its own thread, then bind -the results to the corresponding @var{var} variables and evaluate -@var{body}. +the results to the corresponding @var{var} variables, and then evaluate +@var{body1} @var{body2} @enddots{} @code{letpar} is like @code{let} (@pxref{Local Bindings}), but all the expressions for the bindings are evaluated in parallel. @end deffn -@deffn {Scheme Procedure} par-map proc lst1 @dots{} lstN -@deffnx {Scheme Procedure} par-for-each proc lst1 @dots{} lstN +@deffn {Scheme Procedure} par-map proc lst1 lst2 @dots{} +@deffnx {Scheme Procedure} par-for-each proc lst1 lst2 @dots{} Call @var{proc} on the elements of the given lists. @code{par-map} returns a list comprising the return values from @var{proc}. @code{par-for-each} returns an unspecified value, but waits for all calls to complete. -The @var{proc} calls are @code{(@var{proc} @var{elem1} @dots{} -@var{elemN})}, where each @var{elem} is from the corresponding -@var{lst}. Each @var{lst} must be the same length. The calls are -potentially made in parallel, depending on the number of CPU cores -available. +The @var{proc} calls are @code{(@var{proc} @var{elem1} @var{elem2} +@dots{})}, where each @var{elem} is from the corresponding @var{lst} . +Each @var{lst} must be the same length. The calls are potentially made +in parallel, depending on the number of CPU cores available. These functions are like @code{map} and @code{for-each} (@pxref{List Mapping}), but make their @var{proc} calls in parallel. @@ -1085,8 +1084,8 @@ completion, which makes them quite expensive. Therefore, they should be avoided. -@deffn {Scheme Procedure} n-par-map n proc lst1 @dots{} lstN -@deffnx {Scheme Procedure} n-par-for-each n proc lst1 @dots{} lstN +@deffn {Scheme Procedure} n-par-map n proc lst1 lst2 @dots{} +@deffnx {Scheme Procedure} n-par-for-each n proc lst1 lst2 @dots{} Call @var{proc} on the elements of the given lists, in the same way as @code{par-map} and @code{par-for-each} above, but use no more than @var{n} threads at any one time. The order in which calls are @@ -1098,7 +1097,7 @@ a dual-CPU system for instance @math{@var{n}=4} might be enough to keep the CPUs utilized, and not consume too much memory. @end deffn -@deffn {Scheme Procedure} n-for-each-par-map n sproc pproc lst1 @dots{} lstN +@deffn {Scheme Procedure} n-for-each-par-map n sproc pproc lst1 lst2 @dots{} Apply @var{pproc} to the elements of the given lists, and apply @var{sproc} to each result returned by @var{pproc}. The final return value is unspecified, but all calls will have been completed before diff --git a/doc/ref/api-smobs.texi b/doc/ref/api-smobs.texi index db8161cdd..6b042367e 100644 --- a/doc/ref/api-smobs.texi +++ b/doc/ref/api-smobs.texi @@ -22,8 +22,8 @@ If @var{size} is 0, the default @emph{free} function will do nothing. If @var{size} is not 0, the default @emph{free} function will deallocate the memory block pointed to by @code{SCM_SMOB_DATA} with -@code{scm_gc_free}. The @var{WHAT} parameter in the call to -@code{scm_gc_free} will be @var{NAME}. +@code{scm_gc_free}. The @var{what} parameter in the call to +@code{scm_gc_free} will be @var{name}. Default values are provided for the @emph{mark}, @emph{free}, @emph{print}, and @emph{equalp} functions, as described in @@ -43,7 +43,7 @@ a @dfn{finalizer}) for the smob type specified by the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}. The @var{free} procedure must deallocate all resources that are -directly associated with the smob instance @var{OBJ}. It must assume +directly associated with the smob instance @var{obj}. It must assume that all @code{SCM} values that it references have already been freed and are thus invalid. @@ -107,14 +107,14 @@ with @code{scm_display}, @code{scm_write}, @code{scm_simple_format}, and @code{scm_puts}. @end deftypefn -@deftypefn {C Function} void scm_set_smob_equalp (scm_t_bits tc, SCM (*equalp) (SCM obj1, SCM obj1)) +@deftypefn {C Function} void scm_set_smob_equalp (scm_t_bits tc, SCM (*equalp) (SCM obj1, SCM obj2)) This function sets the smob equality-testing predicate for the smob type specified by the tag @var{tc}. @var{tc} is the tag returned by @code{scm_make_smob_type}. The @var{equalp} procedure should return @code{SCM_BOOL_T} when @var{obj1} is @code{equal?} to @var{obj2}. Else it should return -@var{SCM_BOOL_F}. Both @var{obj1} and @var{obj2} are instances of the +@code{SCM_BOOL_F}. Both @var{obj1} and @var{obj2} are instances of the smob type @var{tc}. @end deftypefn diff --git a/doc/ref/api-utility.texi b/doc/ref/api-utility.texi index ba6139f8c..9ab1eeea5 100644 --- a/doc/ref/api-utility.texi +++ b/doc/ref/api-utility.texi @@ -583,11 +583,11 @@ value of this procedure is not specified. Convert the procedure list of @var{hook} to a list. @end deffn -@deffn {Scheme Procedure} run-hook hook . args +@deffn {Scheme Procedure} run-hook hook arg @dots{} @deffnx {C Function} scm_run_hook (hook, args) -Apply all procedures from the hook @var{hook} to the arguments -@var{args}. The order of the procedure application is first to -last. The return value of this procedure is not specified. +Apply all procedures from the hook @var{hook} to the arguments @var{arg} +@enddots{}. The order of the procedure application is first to last. +The return value of this procedure is not specified. @end deffn If, in C code, you are certain that you have a hook object and well diff --git a/doc/ref/compiler.texi b/doc/ref/compiler.texi index 3d6dbf327..692cb3684 100644 --- a/doc/ref/compiler.texi +++ b/doc/ref/compiler.texi @@ -437,9 +437,9 @@ any, then the rest argument if any, then all of the keyword arguments. @var{body} is the body of the clause. If the procedure is called with an appropriate number of arguments, @var{body} is evaluated in tail -position. Otherwise, if there is a @var{consequent}, it should be a +position. Otherwise, if there is an @var{alternate}, it should be a @code{<lambda-case>} expression, representing the next clause to try. -If there is no @var{consequent}, a wrong-number-of-arguments error is +If there is no @var{alternate}, a wrong-number-of-arguments error is signaled. @end deftp @deftp {Scheme Variable} <let> src names gensyms vals exp diff --git a/doc/ref/goops.texi b/doc/ref/goops.texi index 10192eb3b..bc04985cf 100644 --- a/doc/ref/goops.texi +++ b/doc/ref/goops.texi @@ -97,11 +97,12 @@ Class options, slot descriptions and inheritance are discussed more below. @cindex slot -@deffn syntax define-class name (super @dots{}) slot-definition @dots{} . options +@deffn syntax define-class name (super @dots{}) @ + slot-definition @dots{} class-option @dots{} Define a class called @var{name} that inherits from @var{super}s, with -direct slots defined by @var{slot-definition}s and class options -@var{options}. The newly created class is bound to the variable name -@var{name} in the current environment. +direct slots defined by @var{slot-definition}s and @var{class-option}s. +The newly created class is bound to the variable name @var{name} in the +current environment. Each @var{slot-definition} is either a symbol that names the slot or a list, @@ -115,8 +116,7 @@ list with an even number of elements. The even-numbered elements of @var{slot-options} (counting from zero) are slot option keywords; the odd-numbered elements are the corresponding values for those keywords. -@var{options} is a similarly structured list containing class option -keywords and corresponding values. +Each @var{class-option} is an option keyword and corresponding value. @end deffn As an example, let us define a type for representing a complex number @@ -183,13 +183,13 @@ creates a new @code{<my-complex>} object and binds it to the Scheme variable @code{c}. @deffn generic make -@deffnx method make (class <class>) . initargs +@deffnx method make (class <class>) initarg @dots{} Create and return a new instance of class @var{class}, initialized using -@var{initargs}. +@var{initarg} @enddots{}. -In theory, @var{initargs} can have any structure that is understood by -whatever methods get applied when the @code{initialize} generic function -is applied to the newly allocated instance. +In theory, @var{initarg} @dots{} can have any structure that is +understood by whatever methods get applied when the @code{initialize} +generic function is applied to the newly allocated instance. In practice, specialized @code{initialize} methods would normally call @code{(next-method)}, and so eventually the standard GOOPS @@ -206,7 +206,7 @@ instance's class. Any unprocessed keyword value pairs are ignored. @end deffn @deffn generic make-instance -@deffnx method make-instance (class <class>) . initargs +@deffnx method make-instance (class <class>) initarg @dots{} @code{make-instance} is an alias for @code{make}. @end deffn @@ -674,9 +674,9 @@ setter). Any other previous value, including an existing generic function, is discarded and replaced by a new, empty generic function. @end deffn -@deffn syntax define-method (generic parameter @dots{}) . body +@deffn syntax define-method (generic parameter @dots{}) body @dots{} Define a method for the generic function or accessor @var{generic} with -parameters @var{parameter}s and body @var{body}. +parameters @var{parameter}s and body @var{body} @enddots{}. @var{generic} is a generic function. If @var{generic} is a variable which is not yet bound to a generic function object, the expansion of @@ -688,12 +688,12 @@ generic-with-setter object, the expansion will include a call to Each @var{parameter} must be either a symbol or a two-element list @code{(@var{symbol} @var{class})}. The symbols refer to variables in -the @var{body} that will be bound to the parameters supplied by the +the body forms that will be bound to the parameters supplied by the caller when calling this method. The @var{class}es, if present, specify the possible combinations of parameters to which this method can be applied. -@var{body} is the body of the method definition. +@var{body} @dots{} are the bodies of the method definition. @end deffn @code{define-method} expressions look a little like Scheme procedure @@ -1698,10 +1698,10 @@ If you customize these functions for particular classes or metaclasses, you may still want to use @code{goops-error} to signal any error conditions that you detect. -@deffn procedure goops-error format-string . args +@deffn procedure goops-error format-string arg @dots{} Raise an error with key @code{goops-error} and error message constructed -from @var{format-string} and @var{args}. Error message formatting is -as done by @code{scm-error}. +from @var{format-string} and @var{arg} @enddots{}. Error message +formatting is as done by @code{scm-error}. @end deffn @@ -2228,11 +2228,12 @@ handles the redefinition by invoking @code{class-redefinition} (@pxref{Redefining a Class}). @end itemize -@deffn syntax class name (super @dots{}) slot-definition @dots{} . options +@deffn syntax class name (super @dots{}) @ + slot-definition @dots{} class-option @dots{} Return a newly created class that inherits from @var{super}s, with -direct slots defined by @var{slot-definition}s and class options -@var{options}. For the format of @var{slot-definition}s and -@var{options}, see @ref{Class Definition,, define-class}. +direct slots defined by @var{slot-definition}s and @var{class-option}s. +For the format of @var{slot-definition}s and @var{class-option}s, see +@ref{Class Definition,, define-class}. @end deffn @noindent @code{class} expands to an expression which @@ -2250,13 +2251,12 @@ calls @code{make-class} to create the class with the processed and evaluated parameters. @end itemize -@deffn procedure make-class supers slots . options +@deffn procedure make-class supers slots class-option @dots{} Return a newly created class that inherits from @var{supers}, with -direct slots defined by @var{slots} and class options @var{options}. -For the format of @var{slots} and @var{options}, see @ref{Class +direct slots defined by @var{slots} and @var{class-option}s. For the +format of @var{slots} and @var{class-option}s, see @ref{Class Definition,, define-class}, except note that for @code{make-class}, -@var{slots} and @var{options} are separate list parameters: @var{slots} -here is a list of slot definitions. +@var{slots} is a separate list of slot definitions. @end deffn @noindent @code{make-class} @@ -2307,18 +2307,19 @@ has to be created once. The @code{env} parameter is ignored. @end deffn -@deffn generic make metaclass @dots{} +@deffn generic make metaclass initarg @dots{} @var{metaclass} is the metaclass of the class being defined, either taken from the @code{#:metaclass} class option or computed by @code{ensure-metaclass}. The applied method must create and return the fully initialized class metaobject for the new class definition. @end deffn -The @code{(make @var{metaclass} @dots{})} invocation is a particular -case of the instance creation protocol covered in the previous section. -It will create an class metaobject with metaclass @var{metaclass}. By -default, this metaobject will be initialized by the @code{initialize} -method that is specialized for instances of type @code{<class>}. +The @code{(make @var{metaclass} @var{initarg} @dots{})} invocation is a +particular case of the instance creation protocol covered in the +previous section. It will create an class metaobject with metaclass +@var{metaclass}. By default, this metaobject will be initialized by the +@code{initialize} method that is specialized for instances of type +@code{<class>}. The @code{initialize} method for classes (signature @code{(initialize <class> initargs)}) calls the following generic functions. @@ -2565,7 +2566,7 @@ calls @code{add-method!} to add this method to the relevant generic function. @end itemize -@deffn syntax method (parameter @dots{}) . body +@deffn syntax method (parameter @dots{}) body @dots{} Make a method whose specializers are defined by the classes in @var{parameter}s and whose procedure definition is constructed from the @var{parameter} symbols and @var{body} forms. diff --git a/doc/ref/match.texi b/doc/ref/match.texi index d1618ce6e..40b5be899 100644 --- a/doc/ref/match.texi +++ b/doc/ref/match.texi @@ -64,16 +64,16 @@ bound to, respectively, the first and second element of @var{l}. The pattern matcher is defined as follows: -@deffn {Scheme Syntax} match exp clause ... -Match object @var{exp} against the patterns in the given @var{clause}s, -in the order in which they appear. Return the value produced by the -first matching clause. If no @var{clause} matches, throw an exception -with key @code{match-error}. - -Each @var{clause} has the form @code{(pattern body)}. Each -@var{pattern} must follow the syntax described below. Each @var{body} -is an arbitrary Scheme expression, possibly referring to pattern -variables of @var{pattern}. +@deffn {Scheme Syntax} match exp clause1 clause2 @dots{} +Match object @var{exp} against the patterns in @var{clause1} +@var{clause2} @dots{} in the order in which they appear. Return the +value produced by the first matching clause. If no clause matches, +throw an exception with key @code{match-error}. + +Each clause has the form @code{(pattern body1 body2 @dots{})}. Each +@var{pattern} must follow the syntax described below. Each body is an +arbitrary Scheme expression, possibly referring to pattern variables of +@var{pattern}. @end deffn @c FIXME: Document other forms: diff --git a/doc/ref/misc-modules.texi b/doc/ref/misc-modules.texi index 00354ac73..cf1e0e49f 100644 --- a/doc/ref/misc-modules.texi +++ b/doc/ref/misc-modules.texi @@ -90,13 +90,13 @@ dots.}, or in the worst case, displayed as @nicode{#}. @deffn {Scheme Procedure} truncated-print obj [port] [keyword-options] Print @var{obj}, truncating the output, if necessary, to make it fit -into @var{width} characters. By default, @var{x} will be printed using +into @var{width} characters. By default, @var{obj} will be printed using @code{write}, though that behavior can be overridden via the @var{display?} keyword argument. The default behaviour is to print depth-first, meaning that the entire -remaining width will be available to each sub-expression of @var{x} -- -e.g., if @var{x} is a vector, each member of @var{x}. One can attempt to +remaining width will be available to each sub-expression of @var{obj} -- +e.g., if @var{obj} is a vector, each member of @var{obj}. One can attempt to ``ration'' the available width, trying to allocate it equally to each sub-expression, via the @var{breadth-first?} keyword argument. @@ -156,7 +156,7 @@ C programmers will note the similarity between @code{format} and instead of @nicode{%}, and are more powerful. @sp 1 -@deffn {Scheme Procedure} format dest fmt [args@dots{}] +@deffn {Scheme Procedure} format dest fmt arg @dots{} Write output specified by the @var{fmt} string to @var{dest}. @var{dest} can be an output port, @code{#t} for @code{current-output-port} (@pxref{Default Ports}), or @code{#f} to @@ -269,7 +269,7 @@ Integer. Parameters: @var{minwidth}, @var{padchar}, @var{commachar}, @var{commawidth}. Output an integer argument as a decimal, hexadecimal, octal or binary -integer (respectively). +integer (respectively), in a locale-independent way. @example (format #t "~d" 123) @print{} 123 @@ -297,7 +297,9 @@ minimum), it's padded on the left with the @var{padchar} parameter @end example @nicode{~:d} adds commas (or the @var{commachar} parameter) every -three digits (or the @var{commawidth} parameter many). +three digits (or the @var{commawidth} parameter many). However, when +your intent is to write numbers in a way that follows typographical +conventions, using @nicode{~h} is recommended. @example (format #t "~:d" 1234567) @print{} 1,234,567 @@ -404,6 +406,29 @@ printed instead of the value. (format #t "~5,,,'xf" 12345) @print{} xxxxx @end example +@item @nicode{~h} +Localized number@footnote{The @nicode{~h} format specifier first +appeared in Guile version 2.0.6.}. Parameters: @var{width}, +@var{decimals}, @var{padchar}. + +Like @nicode{~f}, output an exact or floating point number, but do so +according to the current locale, or according to the given locale object +when the @code{:} modifier is used (@pxref{Number Input and Output, +@code{number->locale-string}}). + +@example +(format #t "~h" 12345.5678) ; with "C" as the current locale +@print{} 12345.5678 + +(format #t "~14,,'*:h" 12345.5678 + (make-locale LC_ALL "en_US")) +@print{} ***12,345.5678 + +(format #t "~,2:h" 12345.5678 + (make-locale LC_NUMERIC "fr_FR")) +@print{} 12 345,56 +@end example + @item @nicode{~e} Exponential float. Parameters: @var{width}, @var{mantdigits}, @var{expdigits}, @var{intdigits}, @var{overflowchar}, @var{padchar}, @@ -1670,35 +1695,35 @@ secondly the number of elements in that list. Return a vector which is the entire contents of @var{stream}. @end deffn -@deffn {Scheme Procedure} stream-fold proc init stream0 @dots{} streamN +@defun stream-fold proc init stream1 stream2 @dots{} Apply @var{proc} successively over the elements of the given streams, from first to last until the end of the shortest stream is reached. Return the result from the last @var{proc} call. -Each call is @code{(@var{proc} elem0 @dots{} elemN prev)}, where each +Each call is @code{(@var{proc} elem1 elem2 @dots{} prev)}, where each @var{elem} is from the corresponding @var{stream}. @var{prev} is the return from the previous @var{proc} call, or the given @var{init} for the first call. -@end deffn +@end defun -@deffn {Scheme Procedure} stream-for-each proc stream0 @dots{} streamN +@defun stream-for-each proc stream1 stream2 @dots{} Call @var{proc} on the elements from the given @var{stream}s. The return value is unspecified. -Each call is @code{(@var{proc} elem0 @dots{} elemN)}, where each +Each call is @code{(@var{proc} elem1 elem2 @dots{})}, where each @var{elem} is from the corresponding @var{stream}. @code{stream-for-each} stops when it reaches the end of the shortest @var{stream}. -@end deffn +@end defun -@deffn {Scheme Procedure} stream-map proc stream0 @dots{} streamN +@defun stream-map proc stream1 stream2 @dots{} Return a new stream which is the results of applying @var{proc} to the elements of the given @var{stream}s. -Each call is @code{(@var{proc} elem0 @dots{} elemN)}, where each +Each call is @code{(@var{proc} elem1 elem2 @dots{})}, where each @var{elem} is from the corresponding @var{stream}. The new stream ends when the end of the shortest given @var{stream} is reached. -@end deffn +@end defun @node Buffered Input diff --git a/doc/ref/posix.texi b/doc/ref/posix.texi index 1dc5a80e8..0a688e92d 100644 --- a/doc/ref/posix.texi +++ b/doc/ref/posix.texi @@ -1,7 +1,7 @@ @c -*-texinfo-*- @c This is part of the GNU Guile Reference Manual. -@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007, 2008, 2009, 2010, 2011 -@c Free Software Foundation, Inc. +@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007, +@c 2008, 2009, 2010, 2011, 2012 Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. @node POSIX @@ -211,8 +211,8 @@ initialized to zero. The @var{modes} string is the same as that accepted by @code{open-file} (@pxref{File Ports, open-file}). @end deffn -@deffn {Scheme Procedure} fdes->ports fd -@deffnx {C Function} scm_fdes_to_ports (fd) +@deffn {Scheme Procedure} fdes->ports fdes +@deffnx {C Function} scm_fdes_to_ports (fdes) Return a list of existing ports which have @var{fdes} as an underlying file descriptor, without changing their revealed counts. @@ -230,8 +230,8 @@ descriptor, if one exists, and increments its revealed count. Otherwise, returns a new output port with a revealed count of 1. @end deffn -@deffn {Scheme Procedure} primitive-move->fdes port fd -@deffnx {C Function} scm_primitive_move_to_fdes (port, fd) +@deffn {Scheme Procedure} primitive-move->fdes port fdes +@deffnx {C Function} scm_primitive_move_to_fdes (port, fdes) Moves the underlying file descriptor for @var{port} to the integer value @var{fdes} without changing the revealed count of @var{port}. Any other ports already using this descriptor will be automatically @@ -252,10 +252,10 @@ The return value is unspecified. Decrements the revealed count for a port. @end deffn -@deffn {Scheme Procedure} fsync object -@deffnx {C Function} scm_fsync (object) +@deffn {Scheme Procedure} fsync port_or_fd +@deffnx {C Function} scm_fsync (port_or_fd) Copies any unwritten data for the specified output file descriptor to disk. -If @var{port/fd} is a port, its buffer is flushed before the underlying +If @var{port_or_fd} is a port, its buffer is flushed before the underlying file descriptor is fsync'd. The return value is unspecified. @end deffn @@ -402,11 +402,11 @@ port. This procedure is equivalent to @code{(dup->port @var{port} @var{modes})}. @end deffn -@deffn {Scheme Procedure} redirect-port old new -@deffnx {C Function} scm_redirect_port (old, new) +@deffn {Scheme Procedure} redirect-port old_port new_port +@deffnx {C Function} scm_redirect_port (old_port, new_port) This procedure takes two ports and duplicates the underlying file -descriptor from @var{old-port} into @var{new-port}. The -current file descriptor in @var{new-port} will be closed. +descriptor from @var{old_port} into @var{new_port}. The +current file descriptor in @var{new_port} will be closed. After the redirection the two ports will share a file position and file status flags. @@ -648,7 +648,7 @@ The GNU C Library Reference Manual}. @deffn {Scheme Procedure} stat object @deffnx {C Function} scm_stat (object) Return an object containing various information about the file -determined by @var{obj}. @var{obj} can be a string containing +determined by @var{object}. @var{object} can be a string containing a file name or a port or integer file descriptor which is open on a file (in which case @code{fstat} is used as the underlying system call). @@ -728,8 +728,8 @@ An integer representing the access permission bits. @end deffn @end deffn -@deffn {Scheme Procedure} lstat str -@deffnx {C Function} scm_lstat (str) +@deffn {Scheme Procedure} lstat path +@deffnx {C Function} scm_lstat (path) Similar to @code{stat}, but does not follow symbolic links, i.e., it will return information about a symbolic link itself, not the file it points to. @var{path} must be a string. @@ -762,8 +762,8 @@ as @code{-1}, then that ID is not changed. @findex fchmod @deffn {Scheme Procedure} chmod object mode @deffnx {C Function} scm_chmod (object, mode) -Changes the permissions of the file referred to by @var{obj}. -@var{obj} can be a string containing a file name or a port or integer file +Changes the permissions of the file referred to by @var{object}. +@var{object} can be a string containing a file name or a port or integer file descriptor which is open on a file (in which case @code{fchmod} is used as the underlying system call). @var{mode} specifies @@ -774,7 +774,7 @@ The return value is unspecified. @deffn {Scheme Procedure} utime pathname [actime [modtime [actimens [modtimens [flags]]]]] @deffnx {C Function} scm_utime (pathname, actime, modtime, actimens, modtimens, flags) @code{utime} sets the access and modification times for the -file named by @var{path}. If @var{actime} or @var{modtime} is +file named by @var{pathname}. If @var{actime} or @var{modtime} is not supplied, then the current time is used. @var{actime} and @var{modtime} must be integer time values as returned by the @code{current-time} procedure. @@ -953,7 +953,7 @@ which is usual for ordinary file creation, @end deffn @deffn {Scheme Procedure} tmpfile -@deffnx {C Function} scm_tmpfile +@deffnx {C Function} scm_tmpfile () Return an input/output port to a unique temporary file named using the path prefix @code{P_tmpdir} defined in @file{stdio.h}. @@ -1055,7 +1055,7 @@ stream. Otherwise, close the stream. The @code{setpwent} and @deffn {Scheme Procedure} getpw [user] @deffnx {C Function} scm_getpwuid (user) -Look up an entry in the user database. @var{obj} can be an integer, +Look up an entry in the user database. @var{user} can be an integer, a string, or omitted, giving the behaviour of getpwuid, getpwnam or getpwent respectively. @end deffn @@ -1108,9 +1108,9 @@ stream. Otherwise, close the stream. The @code{setgrent} and @code{endgrent} procedures are implemented on top of this. @end deffn -@deffn {Scheme Procedure} getgr [name] -@deffnx {C Function} scm_getgrgid (name) -Look up an entry in the group database. @var{obj} can be an integer, +@deffn {Scheme Procedure} getgr [group] +@deffnx {C Function} scm_getgrgid (group) +Look up an entry in the group database. @var{group} can be an integer, a string, or omitted, giving the behaviour of getgrgid, getgrnam or getgrent respectively. @end deffn @@ -1284,7 +1284,7 @@ names are from the current locale and in the locale character set. @cindex time parsing Performs the reverse action to @code{strftime}, parsing @var{string} according to the specification supplied in -@var{template}. The interpretation of month and day names is +@var{format}. The interpretation of month and day names is dependent on the current locale. The value returned is a pair. The @acronym{CAR} has an object with time components in the form returned by @code{localtime} or @code{gmtime}, @@ -1411,8 +1411,8 @@ The given strings are all copied, so the C data is not accessed again once @code{scm_set_program_arguments} returns. @end deftypefn -@deffn {Scheme Procedure} getenv nam -@deffnx {C Function} scm_getenv (nam) +@deffn {Scheme Procedure} getenv name +@deffnx {C Function} scm_getenv (name) @cindex environment Looks up the string @var{name} in the current environment. The return value is @code{#f} unless a string of the form @code{NAME=VALUE} is @@ -1442,8 +1442,8 @@ If @var{env} is omitted, return the current environment (in the Unix sense) as a list of strings. Otherwise set the current environment, which is also the default environment for child processes, to the supplied list of strings. Each member of -@var{env} should be of the form @var{NAME}=@var{VALUE} and values of -@var{NAME} should not be duplicated. If @var{env} is supplied +@var{env} should be of the form @var{name}=@var{value} and values of +@var{name} should not be duplicated. If @var{env} is supplied then the return value is unspecified. @end deffn @@ -1452,11 +1452,11 @@ then the return value is unspecified. Modifies the environment of the current process, which is also the default environment inherited by child processes. -If @var{string} is of the form @code{NAME=VALUE} then it will be written +If @var{str} is of the form @code{NAME=VALUE} then it will be written directly into the environment, replacing any existing environment string with -name matching @code{NAME}. If @var{string} does not contain an equal -sign, then any existing string with name matching @var{string} will +name matching @code{NAME}. If @var{str} does not contain an equal +sign, then any existing string with name matching @var{str} will be removed. The return value is unspecified. @@ -1472,7 +1472,7 @@ The return value is unspecified. @deffn {Scheme Procedure} chdir str @deffnx {C Function} scm_chdir (str) @cindex current directory -Change the current working directory to @var{path}. +Change the current working directory to @var{str}. The return value is unspecified. @end deffn @@ -1698,12 +1698,12 @@ If @code{system} is called without arguments, return a boolean indicating whether the command processor is available. @end deffn -@deffn {Scheme Procedure} system* . args +@deffn {Scheme Procedure} system* arg1 arg2 @dots{} @deffnx {C Function} scm_system_star (args) -Execute the command indicated by @var{args}. The first element must -be a string indicating the command to be executed, and the remaining -items must be strings representing each of the arguments to that -command. +Execute the command indicated by @var{arg1} @var{arg2} @enddots{}. The +first element must be a string indicating the command to be executed, +and the remaining items must be strings representing each of the +arguments to that command. This function returns the exit status of the command as provided by @code{waitpid}. This value can be handled with @code{status:exit-val} @@ -1743,22 +1743,22 @@ in the child would upset the protocol in the parent, so @code{primitive-_exit} should be used to exit without that. @end deffn -@deffn {Scheme Procedure} execl filename . args +@deffn {Scheme Procedure} execl filename arg @dots{} @deffnx {C Function} scm_execl (filename, args) -Executes the file named by @var{path} as a new process image. +Executes the file named by @var{filename} as a new process image. The remaining arguments are supplied to the process; from a C program they are accessible as the @code{argv} argument to @code{main}. -Conventionally the first @var{arg} is the same as @var{path}. +Conventionally the first @var{arg} is the same as @var{filename}. All arguments must be strings. -If @var{arg} is missing, @var{path} is executed with a null +If @var{arg} is missing, @var{filename} is executed with a null argument list, which may have system-dependent side-effects. This procedure is currently implemented using the @code{execv} system call, but we call it @code{execl} because of its Scheme calling interface. @end deffn -@deffn {Scheme Procedure} execlp filename . args +@deffn {Scheme Procedure} execlp filename arg @dots{} @deffnx {C Function} scm_execlp (filename, args) Similar to @code{execl}, however if @var{filename} does not contain a slash @@ -1769,7 +1769,7 @@ This procedure is currently implemented using the @code{execvp} system call, but we call it @code{execlp} because of its Scheme calling interface. @end deffn -@deffn {Scheme Procedure} execle filename env . args +@deffn {Scheme Procedure} execle filename env arg @dots{} @deffnx {C Function} scm_execle (filename, env, args) Similar to @code{execl}, but the environment of the new process is specified by @var{env}, which must be a list of strings as returned by the @@ -2502,9 +2502,9 @@ Either @var{name} does not resolve for the supplied parameters, or neither @var{name} nor @var{service} were supplied. @item EAI_NODATA -This non-POSIX error code can be returned on GNU systems when a -request was actually made but returned no data, meaning -that no address is associated with @var{name}. Error handling +This non-POSIX error code can be returned on some systems (GNU +and Darwin, at least), for example when @var{name} is known +but requests that were made turned out no data. Error handling code should be prepared to handle it when it is defined. @item EAI_SERVICE @@ -2841,7 +2841,7 @@ created with, @deffn {Scheme Procedure} make-socket-address AF_INET ipv4addr port @deffnx {Scheme Procedure} make-socket-address AF_INET6 ipv6addr port [flowinfo [scopeid]] @deffnx {Scheme Procedure} make-socket-address AF_UNIX path -@deffnx {C Function} scm_make_socket_address family address arglist +@deffnx {C Function} scm_make_socket_address (family, address, arglist) Return a new socket address object. The first argument is the address family, one of the @code{AF} constants, then the arguments vary according to the family. diff --git a/doc/ref/r6rs.texi b/doc/ref/r6rs.texi index df14cc050..f9bc9e977 100644 --- a/doc/ref/r6rs.texi +++ b/doc/ref/r6rs.texi @@ -273,8 +273,10 @@ grouped below by the existing manual sections to which they correspond. @end deffn @deffn {Scheme Syntax} define-syntax keyword expression -@deffnx {Scheme Syntax} let-syntax ((keyword transformer) ...) exp ... -@deffnx {Scheme Syntax} letrec-syntax ((keyword transformer) ...) exp ... +@deffnx {Scheme Syntax} let-syntax ((keyword transformer) @dots{}) + exp1 exp2 @dots{} +@deffnx {Scheme Syntax} letrec-syntax ((keyword transformer) @dots{}) + exp1 exp2 @dots{} @xref{Defining Macros}, for documentation. @end deffn @@ -403,7 +405,7 @@ grouped below by the existing manual sections to which they correspond. @xref{SRFI-1 Fold and Map}, for documentation. @end deffn -@deffn {Scheme Procedure} list elem1 ... elemN +@deffn {Scheme Procedure} list elem @dots{} @xref{List Constructors}, for documentation. @end deffn @@ -413,7 +415,8 @@ grouped below by the existing manual sections to which they correspond. @xref{List Selection}, for documentation. @end deffn -@deffn {Scheme Procedure} append lst1 ... lstN +@deffn {Scheme Procedure} append lst @dots{} obj +@deffnx {Scheme Procedure} append @deffnx {Scheme Procedure} reverse lst @xref{Append/Reverse}, for documentation. @end deffn @@ -440,15 +443,15 @@ grouped below by the existing manual sections to which they correspond. @xref{String Selection}, for documentation. @end deffn -@deffn {Scheme Procedure} string=? [s1 [s2 . rest]] -@deffnx {Scheme Procedure} string<? [s1 [s2 . rest]] -@deffnx {Scheme Procedure} string>? [s1 [s2 . rest]] -@deffnx {Scheme Procedure} string<=? [s1 [s2 . rest]] -@deffnx {Scheme Procedure} string>=? [s1 [s2 . rest]] +@deffn {Scheme Procedure} string=? s1 s2 s3 @dots{} +@deffnx {Scheme Procedure} string<? s1 s2 s3 @dots{} +@deffnx {Scheme Procedure} string>? s1 s2 s3 @dots{} +@deffnx {Scheme Procedure} string<=? s1 s2 s3 @dots{} +@deffnx {Scheme Procedure} string>=? s1 s2 s3 @dots{} @xref{String Comparison}, for documentation. @end deffn -@deffn {Scheme Procedure} string-append . args +@deffn {Scheme Procedure} string-append arg @dots{} @xref{Reversing and Appending Strings}, for documentation. @end deffn @@ -579,7 +582,7 @@ These procedures implement the @code{map} and @code{for-each} contracts over vectors. @end deffn -@deffn {Scheme Procedure} vector . l +@deffn {Scheme Procedure} vector arg @dots{} @deffnx {Scheme Procedure} vector? obj @deffnx {Scheme Procedure} make-vector len @deffnx {Scheme Procedure} make-vector len fill @@ -600,7 +603,7 @@ over vectors. @xref{Continuations}, for documentation. @end deffn -@deffn {Scheme Procedure} values arg1 ... argN +@deffn {Scheme Procedure} values arg @dots{} @deffnx {Scheme Procedure} call-with-values producer consumer @xref{Multiple Values}, for documentation. @end deffn @@ -609,7 +612,7 @@ over vectors. @xref{Dynamic Wind}, for documentation. @end deffn -@deffn {Scheme Procedure} apply proc arg1 ... argN arglst +@deffn {Scheme Procedure} apply proc arg @dots{} arglst @xref{Fly Evaluation}, for documentation. @end deffn @@ -717,8 +720,8 @@ These procedures are identical to the ones provided by SRFI-1. @xref{SRFI-1 Filtering and Partitioning}, for @code{partition}. @end deffn -@deffn {Scheme Procedure} fold-left combine nil list1 list2 ... listn -@deffnx {Scheme Procedure} fold-right combine nil list1 list2 ... listn +@deffn {Scheme Procedure} fold-left combine nil list1 list2 @dots{} +@deffnx {Scheme Procedure} fold-right combine nil list1 list2 @dots{} These procedures are identical to the @code{fold} and @code{fold-right} procedures provided by SRFI-1. @xref{SRFI-1 Fold and Map}, for documentation. @@ -903,7 +906,7 @@ compatible with either. The @code{(rnrs records syntactic (6))} library exports the syntactic API for working with R6RS records. -@deffn {Scheme Syntax} define-record-type name-spec record-clause* +@deffn {Scheme Syntax} define-record-type name-spec record-clause @dots{} Defines a new record type, introducing bindings for a record-type descriptor, a record constructor descriptor, a constructor procedure, a record predicate, and accessor and mutator procedures for the new diff --git a/doc/ref/scheme-using.texi b/doc/ref/scheme-using.texi index ae608d70a..3d439132b 100644 --- a/doc/ref/scheme-using.texi +++ b/doc/ref/scheme-using.texi @@ -230,7 +230,7 @@ Show description/documentation. Change modules / Show current module. @end deffn -@deffn {REPL Command} import [module ...] +@deffn {REPL Command} import module @dots{} Import modules / List those imported. @end deffn @@ -247,7 +247,7 @@ List current bindings. @end deffn @deffn {REPL Command} in module expression -@deffnx {REPL Command} in module command [args ...] +@deffnx {REPL Command} in module command arg @dots{} Evaluate an expression, or alternatively, execute another meta-command in the context of a module. For example, @samp{,in (foo bar) ,binding} will show the bindings in the module @code{(foo bar)}. @@ -311,7 +311,7 @@ they do not work at the top level. @deffn {REPL Command} backtrace [count] [#:width w] [#:full? f] Print a backtrace. -Print a backtrace of all stack frames, or innermost @var{COUNT} frames. +Print a backtrace of all stack frames, or innermost @var{count} frames. If @var{count} is negative, the last @var{count} frames will be shown. @end deffn @@ -406,11 +406,11 @@ reenter the REPL. @node Inspect Commands @subsubsection Inspect Commands -@deffn {REPL Command} inspect EXP +@deffn {REPL Command} inspect exp Inspect the result(s) of evaluating @var{exp}. @end deffn -@deffn {REPL Command} pretty-print EXP +@deffn {REPL Command} pretty-print exp Pretty-print the result(s) of evaluating @var{exp}. @end deffn diff --git a/doc/ref/srfi-modules.texi b/doc/ref/srfi-modules.texi index 09b93ac39..44e7928bc 100644 --- a/doc/ref/srfi-modules.texi +++ b/doc/ref/srfi-modules.texi @@ -475,15 +475,14 @@ first containing the first elements of each lists and the second containing the second elements of each lists, and so on. @end deffn -@deffn {Scheme Procedure} count pred lst1 @dots{} lstN +@deffn {Scheme Procedure} count pred lst1 lst2 @dots{} Return a count of the number of times @var{pred} returns true when called on elements from the given lists. @var{pred} is called with @var{N} parameters @code{(@var{pred} -@var{elem1} @dots{} @var{elemN})}, each element being from the -corresponding @var{lst1} @dots{} @var{lstN}. The first call is with -the first element of each list, the second with the second element -from each, and so on. +@var{elem1} @dots{} @var{elemN} )}, each element being from the +corresponding list. The first call is with the first element of each +list, the second with the second element from each, and so on. Counting stops when the end of the shortest list is reached. At least one list must be non-circular. @@ -497,14 +496,14 @@ one list must be non-circular. @c FIXME::martin: Review me! -@deffn {Scheme Procedure} fold proc init lst1 @dots{} lstN -@deffnx {Scheme Procedure} fold-right proc init lst1 @dots{} lstN -Apply @var{proc} to the elements of @var{lst1} @dots{} @var{lstN} to +@deffn {Scheme Procedure} fold proc init lst1 lst2 @dots{} +@deffnx {Scheme Procedure} fold-right proc init lst1 lst2 @dots{} +Apply @var{proc} to the elements of @var{lst1} @var{lst2} @dots{} to build a result, and return that result. -Each @var{proc} call is @code{(@var{proc} @var{elem1} @dots{} -@var{elemN} @var{previous})}, where @var{elem1} is from @var{lst1}, -through @var{elemN} from @var{lstN}. @var{previous} is the return +Each @var{proc} call is @code{(@var{proc} @var{elem1} @var{elem2} +@dots{} @var{previous})}, where @var{elem1} is from @var{lst1}, +@var{elem2} is from @var{lst2}, and so on. @var{previous} is the return from the previous call to @var{proc}, or the given @var{init} for the first call. If any list is empty, just @var{init} is returned. @@ -534,11 +533,11 @@ string, and the last among equal longest, @result{} "xyz" @end example -If @var{lst1} through @var{lstN} have different lengths, @code{fold} +If @var{lst1} @var{lst2} @dots{} have different lengths, @code{fold} stops when the end of the shortest is reached; @code{fold-right} -commences at the last element of the shortest. Ie.@: elements past -the length of the shortest are ignored in the other @var{lst}s. At -least one @var{lst} must be non-circular. +commences at the last element of the shortest. Ie.@: elements past the +length of the shortest are ignored in the other @var{lst}s. At least +one @var{lst} must be non-circular. @code{fold} should be preferred over @code{fold-right} if the order of processing doesn't matter, or can be arranged either way, since @@ -567,8 +566,8 @@ a variable in which to build the result, but a self-contained @code{for-each} would have to be written out each time. @end deffn -@deffn {Scheme Procedure} pair-fold proc init lst1 @dots{} lstN -@deffnx {Scheme Procedure} pair-fold-right proc init lst1 @dots{} lstN +@deffn {Scheme Procedure} pair-fold proc init lst1 lst2 @dots{} +@deffnx {Scheme Procedure} pair-fold-right proc init lst1 lst2 @dots{} The same as @code{fold} and @code{fold-right}, but apply @var{proc} to the pairs of the lists instead of the list elements. @end deffn @@ -839,48 +838,51 @@ wanting to use @code{break} from within a @code{while} loop will need to make a new define under a different name. @end deffn -@deffn {Scheme Procedure} any pred lst1 lst2 @dots{} lstN -Test whether any set of elements from @var{lst1} @dots{} lstN -satisfies @var{pred}. If so the return value is the return from the -successful @var{pred} call, or if not the return is @code{#f}. +@deffn {Scheme Procedure} any pred lst1 lst2 @dots{} +Test whether any set of elements from @var{lst1} @var{lst2} @dots{} +satisfies @var{pred}. If so, the return value is the return value from +the successful @var{pred} call, or if not, the return value is +@code{#f}. -Each @var{pred} call is @code{(@var{pred} @var{elem1} @dots{} -@var{elemN})} taking an element from each @var{lst}. The calls are -made successively for the first, second, etc elements of the lists, -stopping when @var{pred} returns non-@code{#f}, or when the end of the -shortest list is reached. +If there are n list arguments, then @var{pred} must be a predicate +taking n arguments. Each @var{pred} call is @code{(@var{pred} +@var{elem1} @var{elem2} @dots{} )} taking an element from each +@var{lst}. The calls are made successively for the first, second, etc. +elements of the lists, stopping when @var{pred} returns non-@code{#f}, +or when the end of the shortest list is reached. -The @var{pred} call on the last set of elements (ie.@: when the end of +The @var{pred} call on the last set of elements (i.e., when the end of the shortest list has been reached), if that point is reached, is a tail call. @end deffn -@deffn {Scheme Procedure} every pred lst1 lst2 @dots{} lstN -Test whether every set of elements from @var{lst1} @dots{} lstN -satisfies @var{pred}. If so the return value is the return from the -final @var{pred} call, or if not the return is @code{#f}. +@deffn {Scheme Procedure} every pred lst1 lst2 @dots{} +Test whether every set of elements from @var{lst1} @var{lst2} @dots{} +satisfies @var{pred}. If so, the return value is the return from the +final @var{pred} call, or if not, the return value is @code{#f}. -Each @var{pred} call is @code{(@var{pred} @var{elem1} @dots{} -@var{elemN})} taking an element from each @var{lst}. The calls are -made successively for the first, second, etc elements of the lists, -stopping if @var{pred} returns @code{#f}, or when the end of any of -the lists is reached. +If there are n list arguments, then @var{pred} must be a predicate +taking n arguments. Each @var{pred} call is @code{(@var{pred} +@var{elem1} @var{elem2 @dots{}})} taking an element from each +@var{lst}. The calls are made successively for the first, second, etc. +elements of the lists, stopping if @var{pred} returns @code{#f}, or when +the end of any of the lists is reached. -The @var{pred} call on the last set of elements (ie.@: when the end of +The @var{pred} call on the last set of elements (i.e., when the end of the shortest list has been reached) is a tail call. -If one of @var{lst1} @dots{} @var{lstN} is empty then no calls to -@var{pred} are made, and the return is @code{#t}. +If one of @var{lst1} @var{lst2} @dots{}is empty then no calls to +@var{pred} are made, and the return value is @code{#t}. @end deffn -@deffn {Scheme Procedure} list-index pred lst1 @dots{} lstN +@deffn {Scheme Procedure} list-index pred lst1 lst2 @dots{} Return the index of the first set of elements, one from each of -@var{lst1}@dots{}@var{lstN}, which satisfies @var{pred}. +@var{lst1} @var{lst2} @dots{}, which satisfies @var{pred}. -@var{pred} is called as @code{(@var{pred} elem1 @dots{} elemN)}. +@var{pred} is called as @code{(@var{elem1} @var{elem2 @dots{}})}. Searching stops when the end of the shortest @var{lst} is reached. The return index starts from 0 for the first set of elements. If no -set of elements pass then the return is @code{#f}. +set of elements pass, then the return value is @code{#f}. @example (list-index odd? '(2 4 6 9)) @result{} 3 @@ -1045,11 +1047,11 @@ sameness. This predicate must be consistent with @code{eq?} @code{eq?} then they must also be equal under the predicate. This simply means a given object must be equal to itself. -@deffn {Scheme Procedure} lset<= = list1 list2 @dots{} +@deffn {Scheme Procedure} lset<= = list @dots{} Return @code{#t} if each list is a subset of the one following it. -Ie.@: @var{list1} a subset of @var{list2}, @var{list2} a subset of -@var{list3}, etc, for as many lists as given. If only one list or no -lists are given then the return is @code{#t}. +I.e., @var{list1} is a subset of @var{list2}, @var{list2} is a subset of +@var{list3}, etc., for as many lists as given. If only one list or no +lists are given, the return value is @code{#t}. A list @var{x} is a subset of @var{y} if each element of @var{x} is equal to some element in @var{y}. Elements are compared using the @@ -1062,11 +1064,11 @@ given @var{=} procedure, called as @code{(@var{=} xelem yelem)}. @end example @end deffn -@deffn {Scheme Procedure} lset= = list1 list2 @dots{} +@deffn {Scheme Procedure} lset= = list @dots{} Return @code{#t} if all argument lists are set-equal. @var{list1} is -compared to @var{list2}, @var{list2} to @var{list3}, etc, for as many -lists as given. If only one list or no lists are given then the -return is @code{#t}. +compared to @var{list2}, @var{list2} to @var{list3}, etc., for as many +lists as given. If only one list or no lists are given, the return +value is @code{#t}. Two lists @var{x} and @var{y} are set-equal if each element of @var{x} is equal to some element of @var{y} and conversely each element of @@ -1082,14 +1084,14 @@ yelem)}, but exactly which calls are made is unspecified. @end example @end deffn -@deffn {Scheme Procedure} lset-adjoin = list elem1 @dots{} -Add to @var{list} any of the given @var{elem}s not already in the -list. @var{elem}s are @code{cons}ed onto the start of @var{list} (so -the return shares a common tail with @var{list}), but the order -they're added is unspecified. +@deffn {Scheme Procedure} lset-adjoin = list elem @dots{} +Add to @var{list} any of the given @var{elem}s not already in the list. +@var{elem}s are @code{cons}ed onto the start of @var{list} (so the +return value shares a common tail with @var{list}), but the order that +the @var{elem}s are added is unspecified. The given @var{=} procedure is used for comparing elements, called as -@code{(@var{=} listelem elem)}, ie.@: the second argument is one of +@code{(@var{=} listelem elem)}, i.e., the second argument is one of the given @var{elem} parameters. @example @@ -1097,11 +1099,11 @@ the given @var{elem} parameters. @end example @end deffn -@deffn {Scheme Procedure} lset-union = list1 list2 @dots{} -@deffnx {Scheme Procedure} lset-union! = list1 list2 @dots{} +@deffn {Scheme Procedure} lset-union = list @dots{} +@deffnx {Scheme Procedure} lset-union! = list @dots{} Return the union of the argument list sets. The result is built by taking the union of @var{list1} and @var{list2}, then the union of -that with @var{list3}, etc, for as many lists as given. For one list +that with @var{list3}, etc., for as many lists as given. For one list argument that list itself is the result, for no list arguments the result is the empty list. @@ -1197,8 +1199,8 @@ a tail with @var{list1}. @code{lset-diff+intersection!} may modify @var{list1} to form its results. @end deffn -@deffn {Scheme Procedure} lset-xor = list1 list2 @dots{} -@deffnx {Scheme Procedure} lset-xor! = list1 list2 @dots{} +@deffn {Scheme Procedure} lset-xor = list @dots{} +@deffnx {Scheme Procedure} lset-xor! = list @dots{} Return an XOR of the argument lists. For two lists this means those elements which are in exactly one of the lists. For more than two lists it means those elements which appear in an odd number of the @@ -1461,18 +1463,18 @@ indicated type. @deffnx {Scheme Procedure} make-f64vector n [value] @deffnx {Scheme Procedure} make-c32vector n [value] @deffnx {Scheme Procedure} make-c64vector n [value] -@deffnx {C Function} scm_make_u8vector n [value] -@deffnx {C Function} scm_make_s8vector n [value] -@deffnx {C Function} scm_make_u16vector n [value] -@deffnx {C Function} scm_make_s16vector n [value] -@deffnx {C Function} scm_make_u32vector n [value] -@deffnx {C Function} scm_make_s32vector n [value] -@deffnx {C Function} scm_make_u64vector n [value] -@deffnx {C Function} scm_make_s64vector n [value] -@deffnx {C Function} scm_make_f32vector n [value] -@deffnx {C Function} scm_make_f64vector n [value] -@deffnx {C Function} scm_make_c32vector n [value] -@deffnx {C Function} scm_make_c64vector n [value] +@deffnx {C Function} scm_make_u8vector (n, value) +@deffnx {C Function} scm_make_s8vector (n, value) +@deffnx {C Function} scm_make_u16vector (n, value) +@deffnx {C Function} scm_make_s16vector (n, value) +@deffnx {C Function} scm_make_u32vector (n, value) +@deffnx {C Function} scm_make_s32vector (n, value) +@deffnx {C Function} scm_make_u64vector (n, value) +@deffnx {C Function} scm_make_s64vector (n, value) +@deffnx {C Function} scm_make_f32vector (n, value) +@deffnx {C Function} scm_make_f64vector (n, value) +@deffnx {C Function} scm_make_c32vector (n, value) +@deffnx {C Function} scm_make_c64vector (n, value) Return a newly allocated homogeneous numeric vector holding @var{n} elements of the indicated type. If @var{value} is given, the vector is initialized with that value, otherwise the contents are @@ -1547,18 +1549,18 @@ Return the number of elements in @var{vec}. @deffnx {Scheme Procedure} f64vector-ref vec i @deffnx {Scheme Procedure} c32vector-ref vec i @deffnx {Scheme Procedure} c64vector-ref vec i -@deffnx {C Function} scm_u8vector_ref (vec i) -@deffnx {C Function} scm_s8vector_ref (vec i) -@deffnx {C Function} scm_u16vector_ref (vec i) -@deffnx {C Function} scm_s16vector_ref (vec i) -@deffnx {C Function} scm_u32vector_ref (vec i) -@deffnx {C Function} scm_s32vector_ref (vec i) -@deffnx {C Function} scm_u64vector_ref (vec i) -@deffnx {C Function} scm_s64vector_ref (vec i) -@deffnx {C Function} scm_f32vector_ref (vec i) -@deffnx {C Function} scm_f64vector_ref (vec i) -@deffnx {C Function} scm_c32vector_ref (vec i) -@deffnx {C Function} scm_c64vector_ref (vec i) +@deffnx {C Function} scm_u8vector_ref (vec, i) +@deffnx {C Function} scm_s8vector_ref (vec, i) +@deffnx {C Function} scm_u16vector_ref (vec, i) +@deffnx {C Function} scm_s16vector_ref (vec, i) +@deffnx {C Function} scm_u32vector_ref (vec, i) +@deffnx {C Function} scm_s32vector_ref (vec, i) +@deffnx {C Function} scm_u64vector_ref (vec, i) +@deffnx {C Function} scm_s64vector_ref (vec, i) +@deffnx {C Function} scm_f32vector_ref (vec, i) +@deffnx {C Function} scm_f64vector_ref (vec, i) +@deffnx {C Function} scm_c32vector_ref (vec, i) +@deffnx {C Function} scm_c64vector_ref (vec, i) Return the element at index @var{i} in @var{vec}. The first element in @var{vec} is index 0. @end deffn @@ -1575,18 +1577,18 @@ in @var{vec} is index 0. @deffnx {Scheme Procedure} f64vector-set! vec i value @deffnx {Scheme Procedure} c32vector-set! vec i value @deffnx {Scheme Procedure} c64vector-set! vec i value -@deffnx {C Function} scm_u8vector_set_x (vec i value) -@deffnx {C Function} scm_s8vector_set_x (vec i value) -@deffnx {C Function} scm_u16vector_set_x (vec i value) -@deffnx {C Function} scm_s16vector_set_x (vec i value) -@deffnx {C Function} scm_u32vector_set_x (vec i value) -@deffnx {C Function} scm_s32vector_set_x (vec i value) -@deffnx {C Function} scm_u64vector_set_x (vec i value) -@deffnx {C Function} scm_s64vector_set_x (vec i value) -@deffnx {C Function} scm_f32vector_set_x (vec i value) -@deffnx {C Function} scm_f64vector_set_x (vec i value) -@deffnx {C Function} scm_c32vector_set_x (vec i value) -@deffnx {C Function} scm_c64vector_set_x (vec i value) +@deffnx {C Function} scm_u8vector_set_x (vec, i, value) +@deffnx {C Function} scm_s8vector_set_x (vec, i, value) +@deffnx {C Function} scm_u16vector_set_x (vec, i, value) +@deffnx {C Function} scm_s16vector_set_x (vec, i, value) +@deffnx {C Function} scm_u32vector_set_x (vec, i, value) +@deffnx {C Function} scm_s32vector_set_x (vec, i, value) +@deffnx {C Function} scm_u64vector_set_x (vec, i, value) +@deffnx {C Function} scm_s64vector_set_x (vec, i, value) +@deffnx {C Function} scm_f32vector_set_x (vec, i, value) +@deffnx {C Function} scm_f64vector_set_x (vec, i, value) +@deffnx {C Function} scm_c32vector_set_x (vec, i, value) +@deffnx {C Function} scm_c64vector_set_x (vec, i, value) Set the element at index @var{i} in @var{vec} to @var{value}. The first element in @var{vec} is index 0. The return value is unspecified. @@ -1734,13 +1736,13 @@ Return the number of elements in @var{vec}. @end deffn @deffn {Scheme Procedure} uniform-vector-ref vec i -@deffnx {C Function} scm_uniform_vector_ref (vec i) +@deffnx {C Function} scm_uniform_vector_ref (vec, i) Return the element at index @var{i} in @var{vec}. The first element in @var{vec} is index 0. @end deffn @deffn {Scheme Procedure} uniform-vector-set! vec i value -@deffnx {C Function} scm_uniform_vector_set_x (vec i value) +@deffnx {C Function} scm_uniform_vector_set_x (vec, i, value) Set the element at index @var{i} in @var{vec} to @var{value}. The first element in @var{vec} is index 0. The return value is unspecified. @@ -2322,7 +2324,7 @@ any) will be stored for later retrieval via a call to Wait for @var{thread} to terminate and return its exit value. When a time value @var{timeout} is given, it specifies a point in time where the waiting should be aborted. When the waiting is aborted, -@var{timeoutval} is returned if it is specified; otherwise, a +@var{timeout-val} is returned if it is specified; otherwise, a @code{join-timeout-exception} exception is raised (@pxref{SRFI-18 Exceptions}). Exceptions may also be raised if the thread was terminated by a call to @code{thread-terminate!} @@ -2430,8 +2432,8 @@ replaces a procedure of the same name in the core library. @end defun @defun condition-variable-name condition-variable -Returns the name assigned to @var{thread} at the time of its creation, -or @code{#f} if it was not given a name. +Returns the name assigned to @var{condition-variable} at the time of its +creation, or @code{#f} if it was not given a name. @end defun @defun condition-variable-specific condition-variable @@ -3156,10 +3158,10 @@ parameters of a function. It can be used with, (use-modules (srfi srfi-26)) @end example -@deffn {library syntax} cut slot @dots{} -@deffnx {library syntax} cute slot @dots{} -Return a new procedure which will make a call (@var{slot} @dots{}) but -with selected parameters specialized to given expressions. +@deffn {library syntax} cut slot1 slot2 @dots{} +@deffnx {library syntax} cute slot1 slot2 @dots{} +Return a new procedure which will make a call (@var{slot1} @var{slot2} +@dots{}) but with selected parameters specialized to given expressions. An example will illustrate the idea. The following is a specialization of @code{write}, sending output to @@ -3517,7 +3519,7 @@ values as in the following example: Note that all fields of @var{type} and its supertypes must be specified. @end deffn -@deffn {Scheme Procedure} make-compound-condition . conditions +@deffn {Scheme Procedure} make-compound-condition condition1 condition2 @dots{} Return a new compound condition composed of @var{conditions}. The returned condition has the type of each condition of @var{conditions} (per @code{condition-has-type?}). @@ -3533,7 +3535,7 @@ Return the value of the field named @var{field-name} from condition @var{c}. If @var{c} is a compound condition and several underlying condition types contain a field named @var{field-name}, then the value of the first such field is returned, using the order in which conditions were -passed to @var{make-compound-condition}. +passed to @code{make-compound-condition}. @end deffn @deffn {Scheme Procedure} extract-condition c type @@ -3569,13 +3571,14 @@ The example below defines condition type @code{&foo}, inheriting from @end lisp @end deffn -@deffn {library syntax} condition type-field-bindings... -Return a new condition, or compound condition, initialized according to -@var{type-field-bindings}. Each @var{type-field-binding} must have the -form @code{(type field-specs...)}, where @var{type} is the name of a -variable bound to condition type; each @var{field-spec} must have the -form @code{(field-name value)} where @var{field-name} is a symbol -denoting the field being initialized to @var{value}. As for +@deffn {library syntax} condition type-field-binding1 type-field-binding2 @dots{} +Return a new condition or compound condition, initialized according to +@var{type-field-binding1} @var{type-field-binding2} @enddots{}. Each +@var{type-field-binding} must have the form @code{(type +field-specs...)}, where @var{type} is the name of a variable bound to a +condition type; each @var{field-spec} must have the form +@code{(field-name value)} where @var{field-name} is a symbol denoting +the field being initialized to @var{value}. As for @code{make-condition}, all fields must be specified. The following example returns a simple condition: @@ -3703,12 +3706,12 @@ Return the specified field of @var{opt}, an option object, as described above for @code{option}. @end deffn -@deffn {Scheme Procedure} args-fold args options unrecognized-option-proc operand-proc seeds @dots{} -Process @var{args}, a list of program arguments such as that returned -by @code{(cdr (program-arguments))}, in order against @var{options}, a -list of option objects as described above. All functions called take -the ``seeds'', or the last multiple-values as multiple arguments, -starting with @var{seeds}, and must return the new seeds. Return the +@deffn {Scheme Procedure} args-fold args options unrecognized-option-proc operand-proc seed @dots{} +Process @var{args}, a list of program arguments such as that returned by +@code{(cdr (program-arguments))}, in order against @var{options}, a list +of option objects as described above. All functions called take the +``seeds'', or the last multiple-values as multiple arguments, starting +with @var{seed} @dots{}, and must return the new seeds. Return the final seeds. Call @code{unrecognized-option-proc}, which is like an option object's @@ -3858,7 +3861,7 @@ This is a Guile-specific addition to the SRFI, similar to the core @defun with-parameters* param-list value-list thunk Establish a new dynamic scope, as per @code{parameterize} above, taking parameters from @var{param-list} and corresponding values from -@var{values-list}. A call @code{(@var{thunk})} is made in the new +@var{value-list}. A call @code{(@var{thunk})} is made in the new scope and the result from that @var{thunk} is the return from @code{with-parameters*}. @end defun @@ -4021,9 +4024,9 @@ SRFI-55 provides @code{require-extension} which is a portable mechanism to load selected SRFI modules. This is implemented in the Guile core, there's no module needed to get SRFI-55 itself. -@deffn {library syntax} require-extension clause@dots{} -Require each of the given @var{clause} features, throwing an error if -any are unavailable. +@deffn {library syntax} require-extension clause1 clause2 @dots{} +Require the features of @var{clause1} @var{clause2} @dots{} , throwing +an error if any are unavailable. A @var{clause} is of the form @code{(@var{identifier} arg...)}. The only @var{identifier} currently supported is @code{srfi} and the diff --git a/doc/ref/sxml-match.texi b/doc/ref/sxml-match.texi index 7b82e1177..7a1a9ac7c 100644 --- a/doc/ref/sxml-match.texi +++ b/doc/ref/sxml-match.texi @@ -64,7 +64,7 @@ Dybvig at Indiana University. @code{sxml-match} provides @code{case}-like form for pattern matching of XML nodes. -@deffn {Scheme Syntax} sxml-match input-expression clause ... +@deffn {Scheme Syntax} sxml-match input-expression clause1 clause2 @dots{} Match @var{input-expression}, an SXML tree, according to the given @var{clause}s (one or more), each consisting of a pattern and one or more expressions to be evaluated if the pattern match succeeds. Optionally, each @var{clause} within @@ -356,8 +356,8 @@ transformation that formats a ``TV Guide'' into HTML. @unnumberedsubsec @code{sxml-match-let} and @code{sxml-match-let*} -@deffn {Scheme Syntax} sxml-match-let ((pat expr) ...) expression0 expression ...) -@deffnx {Scheme Syntax} sxml-match-let* ((pat expr) ...) expression0 expression ...) +@deffn {Scheme Syntax} sxml-match-let ((pat expr) ...) expression0 expression ... +@deffnx {Scheme Syntax} sxml-match-let* ((pat expr) ...) expression0 expression ... These forms generalize the @code{let} and @code{let*} forms of Scheme to allow an XML pattern in the binding position, rather than a simple variable. @end deffn diff --git a/doc/ref/vm.texi b/doc/ref/vm.texi index 398129e2b..c5b80761c 100644 --- a/doc/ref/vm.texi +++ b/doc/ref/vm.texi @@ -432,7 +432,7 @@ then @code{local-set}, used when binding boxed variables. @end deffn @deffn Instruction empty-box index -Set the @var{indext}h local variable to a box containing a variable +Set the @var{index}th local variable to a box containing a variable whose value is unbound. Used when compiling some @code{letrec} expressions. @end deffn @@ -918,13 +918,13 @@ Jump to @var{offset} if the object on the stack is false. @deffn Instruction br-if-eq offset Jump to @var{offset} if the two objects located on the stack are -equal in the sense of @var{eq?}. Note that, for this instruction, the +equal in the sense of @code{eq?}. Note that, for this instruction, the stack pointer is decremented by two Scheme objects instead of only one. @end deffn @deffn Instruction br-if-not-eq offset -Same as @var{br-if-eq} for non-@code{eq?} objects. +Same as @code{br-if-eq} for non-@code{eq?} objects. @end deffn @deffn Instruction br-if-null offset diff --git a/doc/ref/web.texi b/doc/ref/web.texi index a08cd2cce..81c77dd0b 100644 --- a/doc/ref/web.texi +++ b/doc/ref/web.texi @@ -1116,7 +1116,7 @@ if there was no request body. @end deffn @deffn {Scheme Procedure} write-request-body r bv -Write @var{body}, a bytevector, to the port corresponding to the HTTP +Write @var{bv}, a bytevector, to the port corresponding to the HTTP request @var{r}. @end deffn @@ -1212,7 +1212,7 @@ As a side effect, sets the encoding on @var{port} to ISO-8859-1 discussion of character sets in @ref{Responses}, for more information. @end deffn -@deffn {Scheme Procedure} build-response [#:version='(1 . 1)] [#:code=200] [#:reason-phrase=#f] [#:headers='()] [#:port=#f] [#:validate-headers=#t] +@deffn {Scheme Procedure} build-response [#:version='(1 . 1)] [#:code=200] [#:reason-phrase=#f] [#:headers='()] [#:port=#f] [#:validate-headers?=#t] Construct an HTTP response object. If @var{validate-headers?} is true, the headers are each run through their respective validators. @end deffn @@ -1241,7 +1241,7 @@ if there was no response body. @end deffn @deffn {Scheme Procedure} write-response-body r bv -Write @var{body}, a bytevector, to the port corresponding to the HTTP +Write @var{bv}, a bytevector, to the port corresponding to the HTTP response @var{r}. @end deffn @@ -1291,7 +1291,7 @@ the lower-level HTTP, request, and response modules. @deffn {Scheme Procedure} open-socket-for-uri uri @end deffn -@deffn {Scheme Procedure} http-get uri [#:port=(open-socket-for-uri uri)] [#:version='(1 . 1)] [#:keep-alive?=#f] [#:extra-headers='()] [#:decode-body=#t] +@deffn {Scheme Procedure} http-get uri [#:port=(open-socket-for-uri uri)] [#:version='(1 . 1)] [#:keep-alive?=#f] [#:extra-headers='()] [#:decode-body?=#t] Connect to the server corresponding to @var{uri} and ask for the resource, using the @code{GET} method. If you already have a port open, pass it as @var{port}. The port will be closed at the end of the diff --git a/doc/sources/ChangeLog-2008 b/doc/sources/ChangeLog-2008 deleted file mode 100644 index 1df00138b..000000000 --- a/doc/sources/ChangeLog-2008 +++ /dev/null @@ -1,5 +0,0 @@ -2001-08-27 Neil Jerram <neil@ossau.uklinux.net> - - The change log for files in this directory continues backwards - from 2001-08-27 in ../ChangeLog, as all the Guile documentation - prior to this date was contained in a single directory. diff --git a/doc/sources/Makefile.am b/doc/sources/Makefile.am deleted file mode 100644 index 253d4b31d..000000000 --- a/doc/sources/Makefile.am +++ /dev/null @@ -1,7 +0,0 @@ -# -*- Makefile -*- - -EXTRA_DIST = libguile-overview.texi snarf.texi contributors.texi \ - libguile-tools.texi strings.texi data-rep.texi new-types.texi tk.texi \ - debug-c.texi old-intro.texi unix-other.texi debug-scheme.texi \ - sample-APIs.texi unix.texi guile-slib.texi scheme-concepts.texi \ - jimb-org.texi scm-ref.texi ChangeLog-2008 diff --git a/doc/sources/contributors.texi b/doc/sources/contributors.texi deleted file mode 100644 index 578c358f7..000000000 --- a/doc/sources/contributors.texi +++ /dev/null @@ -1,80 +0,0 @@ -@node Contributors to Guile -@appendix Contributors to Guile - -This Guile Manual was written by Mark Galassi, Jim Blandy and Gary -Houston. - -Guile was developed over many years by the following people: - -@table @strong -@item George Carrette -Wrote files present in Siod version 2.3, released in December of 1989. - -@item Aubrey Jaffer -Wrote substantial portions of guile.texi, and surely others. -Changes to: eval.c, ioext.c, posix.c, gscm.c, scm.h, socket.c, -gsubr.c, sys.c, test.scm, stime.c, and unif.c. - -@item Gary Houston -changes to many files in libguile. - -wrote: libguile/socket.c, ice-9/expect.scm - -@item Tom Lord -Many changes throughout. -In the subdirectory ctax, wrote: - Makefile.in configure.in hashtabs.scm macros.scm scm-ops.scm - c-ops.scm grammar.scm lexer.scm reader.scm -In the subdirectory gtcltk-lib, wrote: - Makefile.in guile-tcl.c guile-tk.c - configure.in guile-tcl.h guile-tk.h -In the subdirectory guile, wrote: - Makefile.in getopt.c getopt1.c - configure.in getopt.h guile.c -In the subdirectory ice-9, wrote: - Makefile.in configure.in lineio.scm poe.scm - boot-9.scm hcons.scm mapping.scm -In the subdirectory lang, wrote: - Makefile.in grammar.scm lr0.scm pp.scm - configure.in lex.scm lr1.scm -In the subdirectory rx, wrote: - Makefile.in runtests.c rxbitset.h rxnfa.c rxspencer.c - TESTS rx.c rxcontext.h rxnfa.h rxspencer.h - TESTS2C.sed rx.h rxcset.c rxnode.c rxstr.c - _rx.h rxall.h rxcset.h rxnode.h rxstr.h - configure.in rxanal.c rxdbug.c rxposix.c rxsuper.c - hashrexp.c rxanal.h rxgnucomp.c rxposix.h rxsuper.h - inst-rxposix.h rxbasic.c rxgnucomp.h rxproto.h rxunfa.c - rgx.c rxbasic.h rxhash.c rxsimp.c rxunfa.h - rgx.h rxbitset.c rxhash.h rxsimp.h testcases.h -In the subdirectory doc, wrote: - ctax.texi gtcltk.texi in.texi lang.texi -and portions of guile.texi. - -@item Anthony Green -wrote the original code in the 'threads' directory, and -ice-9/threads.scm. - -@item Mikael Djurfeldt -@example -In the subdirectory libguile, wrote: - backtrace.c debug.c options.c root.c srcprop.c stacks.c - backtrace.h debug.h options.h root.h srcprop.h stacks.h -In the subdirectory threads, rewrote: - coop-threads.c coop.c mit-pthreads.c threads.c - coop-threads.h fsu-pthreads.h mit-pthreads.h threads.h -Many other changes throughout. -@end example - -@item Mark Galassi -@example -Designed and implemented the high-level libguile API (the @code{gh_} -interface), based largely on the defunct @code{gscm_} interface. In the -subdirectory gh, wrote: -gh.c gh_eval.c gh_io.c gh_test_c.c -gh.h gh_funcs.c gh_list.c gh_test_repl.c -gh_data.c gh_init.c gh_predicates.c -@end example - - -@end table diff --git a/doc/sources/debug-c.texi b/doc/sources/debug-c.texi deleted file mode 100644 index 77d02f440..000000000 --- a/doc/sources/debug-c.texi +++ /dev/null @@ -1,2 +0,0 @@ -@node Debugging libguile -@chapter Debugging libguile diff --git a/doc/sources/debug-scheme.texi b/doc/sources/debug-scheme.texi deleted file mode 100644 index 35340f943..000000000 --- a/doc/sources/debug-scheme.texi +++ /dev/null @@ -1,2 +0,0 @@ -@node Debugging Scheme programs -@chapter Debugging Scheme programs diff --git a/doc/sources/env.texi b/doc/sources/env.texi deleted file mode 100644 index 7a37b768b..000000000 --- a/doc/sources/env.texi +++ /dev/null @@ -1,1165 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename env.info -@settitle Top-level Environments in Guile -@c %**end of header - -@setchapternewpage odd - -@c Changes since Jost's implementation: -@c "finite environments" -> "leaf environments" -@c "scm_foo_internal" -> "scm_c_foo" - -@c To do: -@c add spec for soft environments - -@c When merged into the main manual, add cross-references for: -@c weak references -@c smobs (esp. module's mark and free functions) - - -[[add refs for all conditions signalled]] - -@ifinfo -Copyright 1999, 2006, 2012 Free Software Foundation, Inc. -@end ifinfo - -@titlepage -@sp 10 -@comment The title is printed in a large font. -@center @titlefont{Top-level Environments in Guile} - -@c The following two commands start the copyright page. -@page -@vskip 0pt plus 1filll -Copyright @copyright{} 1999, 2006 Free Software Foundation, Inc. -@end titlepage - -@node Top, Motivation, (dir), (dir) - -@menu -* Motivation:: -* Top-Level Environments in Guile:: -* Modules:: -@end menu - -@node Motivation, Top-Level Environments in Guile, Top, Top -@chapter Motivation - -@example -$Id: env.texi,v 1.2 2006-04-16 23:05:07 kryde Exp $ -@end example - -This is a draft proposal for a new datatype for representing top-level -environments in Guile. Upon completion, this proposal will be posted to -the mailing list @samp{guile@@cygnus.com} for discussion, revised in -light of whatever insights that may produce, and eventually implemented. - -Note that this is @emph{not} a proposal for a module system; rather, it -is a proposal for a data structure which encapsulates the ideas one -needs when writing a module system, and, most importantly, a fixed -interface which insulates the interpreter from the details of the module -system. Using these environments, one could implement any module system -one pleased, without changing the interpreter. - -I hope this text will eventually become a chapter of the Guile manual; -thus, the description of environments in written in the present tense, -as if it were already implemented, not in the future tense. However, -this text does not actually describe the present state of Guile. - -I'm especially interested in improving the vague, rambling presentation -of environments in the section "Modules and Environments". I'm trying -to orient the user for the discussion that follows, but I wonder if I'm -just confusing the issue. I would appreciate suggestions if they are -concrete --- please provide new wording. - -Note also: I'm trying out a convention I'm considering for use in the -manual. When a Scheme procedure which is directly implemented by a C -procedure, and both are useful to call from their respective languages, -we document the Scheme procedure only, and call it a "Primitive". If a -Scheme function is marked as a primitive, you can derive the name of the -corresponding C function by changing @code{-} to @code{_}, @code{!} to -@code{_x}, @code{?} to @code{_p}, and prepending @code{scm_}. The C -function's arguments will be all of the Scheme procedure's arguments, -both required and optional; if the Scheme procedure takes a ``rest'' -argument, that will be a final argument to the C function. The C -function's arguments, as well as its return type, will be @code{SCM}. -Thus, a procedure documented like this: -@deffn Primitive set-car! pair value -@end deffn - -has a corresponding C function which would be documented like this: -@deftypefn {Libguile function} SCM scm_set_car_x (SCM @var{pair}, SCM @var{value}) -@end deftypefn - -The hope is that this will be an uncluttered way to document both the C -and Scheme interfaces, without unduly confusing users interested only in -the Scheme level. - -When there is a C function which provides the same functionality as a -primitive, but with a different interface tailored for C's needs, it -usually has the same name as the primitive's C function, but with the -prefix @code{scm_c_} instead of simply @code{scm_}. Thus, -@code{scm_c_environment_ref} is almost identical to -@code{scm_environment_ref}, except that it indicates an unbound variable -in a manner friendlier to C code. - - - -@node Top-Level Environments in Guile, Modules, Motivation, Top -@chapter Top-Level Environments in Guile - -In Guile, an environment is a mapping from symbols onto variables, and -a variable is a location containing a value. Guile uses the datatype -described here to represent its top-level environments. - - -@menu -* Modules and Environments:: Modules are environments, with bookkeeping. -* Common Environment Operations:: Looking up bindings, creating bindings, etc. -* Standard Environment Types:: Guile has some fundamental environment types. -* Implementing Environments:: You can extend Guile with new kinds of - environments. -* Switching to Environments:: Changes needed to today's Guile to - implement the features described here. -@end menu - -@node Modules and Environments, Common Environment Operations, Top-Level Environments in Guile, Top-Level Environments in Guile -@section Modules and Environments - -Guile distinguishes between environments and modules. A module is a -unit of code sharing; it has a name, like @code{(math random)}, an -implementation (e.g., Scheme source code, a dynamically linked library, -or a set of primitives built into Guile), and finally, an environment -containing the definitions which the module exports for its users. - -An environment, by contrast, is simply an abstract data type -representing a mapping from symbols onto variables which the Guile -interpreter uses to look up top-level definitions. The @code{eval} -procedure interprets its first argument, an expression, in the context -of its second argument, an environment. - -Guile uses environments to implement its module system. A module -created by loading Scheme code might be built from several environments. -In addition to the environment of exported definitions, such a module -might have an internal top-level environment, containing both exported -and private definitions, and perhaps environments for imported -definitions alone and local definitions alone. - -The interface described here includes a full set of functions for -mutating environments, and the system goes to some length to maintain -its consistency as environments' bindings change. This is necessary -because Guile is an interactive system. The user may create new -definitions or modify and reload modules while Guile is running; the -system should handle these changes in a consistent and predictable way. - -A typical Guile system will have several distinct top-level -environments. (This is why we call them ``top-level'', and not -``global''.) For example, consider the following fragment of an -interactive Guile session: - -@example -guile> (use-modules (ice-9 regex)) -guile> (define pattern "^(..+)\\1+$") -guile> (string-match pattern "xxxx") -#("xxxx" (0 . 4) (0 . 2)) -guile> (string-match pattern "xxxxx") -#f -guile> -@end example -@noindent -Guile evaluates the expressions the user types in a top-level -environment reserved for that purpose; the definition of @code{pattern} -goes there. That environment is distinct from the one holding the -private definitions of the @code{(ice-9 regex)} module. At the Guile -prompt, the user does not see the module's private definitions, and the -module is unaffected by definitions the user makes at the prompt. The -@code{use-modules} form copies the module's public bindings into the -user's environment. - -All Scheme evaluation takes place with respect to some top-level -environment. Just as the procedure created by a @code{lambda} form -closes over any local scopes surrounding that form, it also closes over -the surrounding top-level environment. Thus, since the -@code{string-match} procedure is defined in the @code{(ice-9 regex)} -module, it closes over that module's top-level environment. Thus, when -the user calls @code{string-match} from the Guile prompt, any free -variables in @code{string-match}'s definition are resolved with respect -to the module's top-level environment, not the user's. - -Although the Guile interaction loop maintains a ``current'' top-level -environment in which it evaluates the user's input, it would be -misleading to extend the concept of a ``current top-level environment'' -to the system as a whole. Each procedure closes over its own top-level -environment, in which that procedure will find bindings for its free -variables. Thus, the top-level environment in force at any given time -depends on the procedure Guile happens to be executing. The global -``current'' environment is a figment of the interaction loop's -imagination. - -Since environments provide all the operations the Guile interpreter -needs to evaluate code, they effectively insulate the interpreter from -the details of the module system. Without changing the interpreter, you -can implement any module system you like, as long as its efforts produce -an environment object the interpreter can consult. - -Finally, environments may prove a convenient way for Guile to access the -features of other systems. For example, one might export The GIMP's -Procedural Database to Guile as a custom environment type; this -environment could create Scheme procedure objects corresponding to GIMP -procedures, as the user referenced them. - - -@node Common Environment Operations, Standard Environment Types, Modules and Environments, Top-Level Environments in Guile -@section Common Environment Operations - -This section describes the common set of operations that all environment -objects support. To create an environment object, or to perform an -operation specific to a particular kind of environment, see -@ref{Standard Environment Types}. - -In this section, the following names for formal parameters imply that -the actual parameters must have a certain type: - -@table @var - -@item env -an environment - -@item symbol -a symbol - -@item proc -a procedure - -@item value -@itemx object -an arbitrary Scheme value - -@end table - - -@menu -* Examining Environments:: -* Changing Environments:: -* Caching Environment Lookups:: -* Observing Changes to Environments :: -* Environment Errors:: -@end menu - -@node Examining Environments, Changing Environments, Common Environment Operations, Common Environment Operations -@subsection Examining Environments - -@deffn Primitive environment? object -Return @code{#t} if @var{object} is an environment, or @code{#f} otherwise. -@end deffn - -@deffn Primitive environment-ref env symbol -Return the value of the location bound to @var{symbol} in @var{env}. -If @var{symbol} is unbound in @var{env}, signal an @code{environment:unbound} -error (@pxref{Environment Errors}). -@end deffn - -@deffn Primitive environment-bound? env symbol -Return @code{#t} if @var{symbol} is bound in @var{env}, or @code{#f} -otherwise. -@end deffn - -@deffn Primitive environment-fold env proc init -Iterate over all the bindings in an environment, accumulating some value. - -For each binding in @var{env}, apply @var{proc} to the symbol bound, its -value, and the result from the previous application of @var{proc}. Use -@var{init} as @var{proc}'s third argument the first time @var{proc} is -applied. - -If @var{env} contains no bindings, this function simply returns @var{init}. - -If @var{env} binds the symbol @var{sym1} to the value @var{val1}, -@var{sym2} to @var{val2}, and so on, then this procedure computes: -@example -(@var{proc} @var{sym1} @var{val1} - (@var{proc} @var{sym2} @var{val2} - ... - (@var{proc} @var{symn} @var{valn} - @var{init}))) -@end example - -Each binding in @var{env} is processed at most once. -@code{environment-fold} makes no guarantees about the order in which the -bindings are processed. - -If @var{env} is not modified while the iteration is taking place, -@code{environment-fold} will apply @var{proc} to each binding in -@var{env} exactly once. - -If @var{env} is modified while the iteration is taking place, we need to -be more subtle in describing @code{environment-fold}'s behavior. -@code{environment-fold} repeatedly applies @var{proc} to a binding which -was present in @var{env} when @code{environment-fold} was invoked and is -still present in @var{env}, until there are no such bindings remaining. -(If no mutations take place, this definition is equivalent to the -simpler one given above.) By this definition, bindings added during the -iteration will not be passed to @var{proc}. - -Here is a function which, given an environment, constructs an -association list representing that environment's bindings, using -@code{environment-fold}: -@example -(define (environment->alist env) - (environment-fold env - (lambda (sym val tail) - (cons (cons sym val) tail)) - '())) -@end example -@end deffn - -@deftypefn {Libguile macro} int SCM_ENVP (@var{object}) -Return non-zero if @var{object} is an environment. -@end deftypefn - -@deftypefn {Libguile function} SCM scm_c_environment_ref (SCM @var{env}, SCM @var{symbol}) -This C function is identical to @code{environment-ref}, except that if -@var{symbol} is unbound in @var{env}, it returns the value -@code{SCM_UNDEFINED}, instead of signalling an error. -@end deftypefn - -@deftypefn {Libguile function} SCM scm_c_environment_fold (SCM @var{env}, scm_environment_folder *@var{proc}, SCM @var{data}, SCM @var{init}) -This is the C-level analog of @code{environment-fold}. For each binding in -@var{env}, make the call: -@example -(*@var{proc}) (@var{data}, @var{symbol}, @var{value}, @var{previous}) -@end example -@noindent -where @var{previous} is the value returned from the last call to -@code{*@var{proc}}, or @var{init} for the first call. If @var{env} -contains no bindings, return @var{init}. -@end deftypefn - -@deftp {Libguile data type} scm_environment_folder SCM (SCM @var{data}, SCM @var{symbol}, SCM @var{value}, SCM @var{tail}) -The type of a folding function to pass to @code{scm_c_environment_fold}. -@end deftp - - -@node Changing Environments, Caching Environment Lookups, Examining Environments, Common Environment Operations -@subsection Changing Environments - -Here are functions for changing symbols' bindings and values. - -Although it is common to say that an environment binds a symbol to a -value, this is not quite accurate; an environment binds a symbol to a -location, and the location contains a value. In the descriptions below, -we will try to make clear how each function affects bindings and -locations. - -Note that some environments may contain some immutable bindings, or may -bind symbols to immutable locations. If you attempt to change an -immutable binding or value, these functions will signal an -@code{environment:immutable-binding} or -@code{environment:immutable-location} error. However, simply because a -binding cannot be changed via these functions does @emph{not} imply that -it is constant. Mechanisms outside the scope of this section (say, -re-loading a module's source code) may change a binding or value which -is immutable via these functions. - -@deffn Primitive environment-define env symbol value -Bind @var{symbol} to a new location containing @var{value} in @var{env}. -If @var{symbol} is already bound to another location in @var{env}, that -binding is replaced. The new binding and location are both mutable. -The return value is unspecified. - -If @var{symbol} is already bound in @var{env}, and the binding is -immutable, signal an @code{environment:immutable-binding} error. -@end deffn - -@deffn Primitive environment-undefine env symbol -Remove any binding for @var{symbol} from @var{env}. If @var{symbol} is -unbound in @var{env}, do nothing. The return value is unspecified. - -If @var{symbol} is already bound in @var{env}, and the binding is -immutable, signal an @code{environment:immutable-binding} error. -@end deffn - -@deffn Primitive environment-set! env symbol value -If @var{env} binds @var{symbol} to some location, change that location's -value to @var{value}. The return value is unspecified. - -If @var{symbol} is not bound in @var{env}, signal an -@code{environment:unbound} error. If @var{env} binds @var{symbol} to an -immutable location, signal an @code{environment:immutable-location} -error. -@end deffn - - -@node Caching Environment Lookups, Observing Changes to Environments , Changing Environments, Common Environment Operations -@subsection Caching Environment Lookups - -Some applications refer to variables' values so frequently that the -overhead of @code{environment-ref} and @code{environment-set!} is -unacceptable. For example, variable reference speed is a critical -factor in the performance of the Guile interpreter itself. If an -application can tolerate some additional complexity, the -@code{environment-cell} function described here can provide very -efficient access to variable values. - -In the Guile interpreter, most variables are represented by pairs; the -@sc{cdr} of the pair holds the variable's value. Thus, a variable -reference corresponds to taking the @sc{cdr} of one of these pairs, and -setting a variable corresponds to a @code{set-cdr!} operation. A pair -used to represent a variable's value in this manner is called a -@dfn{value cell}. Value cells represent the ``locations'' to which -environments bind symbols. - -The @code{environment-cell} function returns the value cell bound to a -symbol. For example, an interpreter might make the call -@code{(environment-cell @var{env} @var{symbol} #t)} to find the value -cell which @var{env} binds to @var{symbol}, and then use @code{cdr} and -@code{set-cdr!} to reference and assign to that variable, instead of -calling @code{environment-ref} or @var{environment-set!} for each -variable reference. - -There are a few caveats that apply here: - -@itemize @bullet - -@item -Environments are not required to represent variables' values using value -cells. An environment is free to return @code{#f} in response to a -request for a symbol's value cell; in this case, the caller must use -@code{environment-ref} and @code{environment-set!} to manipulate the -variable. - -@item -An environment's binding for a symbol may change. For example, the user -could override an imported variable with a local definition, associating -a new value cell with that symbol. If an interpreter has used -@code{environment-cell} to obtain the variable's value cell, it no -longer needs to use @code{environment-ref} and @code{environment-set!} -to access the variable, and it may not see the new binding. - -Thus, code which uses @code{environment-cell} should almost always use -@code{environment-observe} to track changes to the symbol's binding; -this is the additional complexity hinted at above. @xref{Observing -Changes to Environments}. - -@item -Some variables should be immutable. If a program uses -@code{environment-cell} to obtain the value cell of such a variable, -then it is impossible for the environment to prevent the program from -changing the variable's value, using @code{set-cdr!}. However, this is -discouraged; it is probably better to redesign the interface than to -disregard such a request. To make it easy for programs to honor the -immutability of a variable, @code{environment-cell} takes an argument -indicating whether the caller intends to mutate the cell's value; if -this argument is true, then @code{environment-cell} signals an -@code{environment:immutable-location} error. - -Programs should therefore make separate calls to @code{environment-cell} -to obtain value cells for reference and for assignment. It is incorrect -for a program to call @code{environment-cell} once to obtain a value -cell, and then use that cell for both reference and mutation. - -@end itemize - -@deffn Primitive environment-cell env symbol for-write -Return the value cell which @var{env} binds to @var{symbol}, or -@code{#f} if the binding does not live in a value cell. - -The argument @var{for-write} indicates whether the caller intends to -modify the variable's value by mutating the value cell. If the variable -is immutable, then @code{environment-cell} signals an -@code{environment:immutable-location} error. - -If @var{symbol} is unbound in @var{env}, signal an @code{environment:unbound} -error. - -If you use this function, you should consider using -@code{environment-observe}, to be notified when @code{symbol} gets -re-bound to a new value cell, or becomes undefined. -@end deffn - -@deftypefn {Libguile function} SCM scm_c_environment_cell (SCM @var{env}, SCM @var{symbol}, int for_write) -This C function is identical to @code{environment-cell}, except that if -@var{symbol} is unbound in @var{env}, it returns the value -@code{SCM_UNDEFINED}, instead of signalling an error. -@end deftypefn - -[[After we have some experience using this, we may find that we want to -be able to explicitly ask questions like, "Is this variable mutable?" -without the annoyance of error handling. But maybe this is fine.]] - - -@node Observing Changes to Environments , Environment Errors, Caching Environment Lookups, Common Environment Operations -@subsection Observing Changes to Environments - -The procedures described here allow you to add and remove @dfn{observing -procedures} for an environment. - - -@menu -* Registering Observing Procedures:: -* Observations and Garbage Collection:: -* Observing Environments from C Code:: -@end menu - -@node Registering Observing Procedures, Observations and Garbage Collection, Observing Changes to Environments , Observing Changes to Environments -@subsubsection Registering Observing Procedures - -A program may register an @dfn{observing procedure} for an environment, -which will be called whenever a binding in a particular environment -changes. For example, if the user changes a module's source code and -re-loads the module, other parts of the system may want to throw away -information they have cached about the bindings of the older version of -the module. To support this, each environment retains a set of -observing procedures which it will invoke whenever its bindings change. -We say that these procedures @dfn{observe} the environment's bindings. -You can register new observing procedures for an environment using -@code{environment-observe}. - -@deffn Primitive environment-observe env proc -Whenever @var{env}'s bindings change, apply @var{proc} to @var{env}. - -This function returns an object, @var{token}, which you can pass to -@code{environment-unobserve} to remove @var{proc} from the set of -procedures observing @var{env}. The type and value of @var{token} is -unspecified. -@end deffn - -@deffn Primitive environment-unobserve token -Cancel the observation request which returned the value @var{token}. -The return value is unspecified. - -If a call @code{(environment-observe @var{env} @var{proc})} returns -@var{token}, then the call @code{(environment-unobserve @var{token})} -will cause @var{proc} to no longer be called when @var{env}'s bindings -change. -@end deffn - -There are some limitations on observation: -@itemize @bullet -@item -These procedures do not allow you to observe specific bindings; you -can only observe an entire environment. -@item -These procedures observe bindings, not locations. There is no way -to receive notification when a location's value changes, using these -procedures. -@item -These procedures do not promise to call the observing procedure for each -individual binding change. However, if multiple bindings do change -between calls to the observing procedure, those changes will appear -atomic to the entire system, not just to a few observing procedures. -@item -Since a single environment may have several procedures observing it, a -correct design obviously may not assume that nothing else in the system -has yet observed a given change. -@end itemize - -(One weakness of this observation architecture is that observing -procedures make no promises to the observer. That's fine if you're just -trying to implement an accurate cache, but too weak to implement things -that walk the environment tree.) - -@node Observations and Garbage Collection, Observing Environments from C Code, Registering Observing Procedures, Observing Changes to Environments -@subsubsection Observations and Garbage Collection - -When writing observing procedures, pay close attention to garbage -collection issues. If you use @code{environment-observe} to register -observing procedures for an environment, the environment will hold a -reference to those procedures; while that environment is alive, its -observing procedures will live, as will any data they close over. If -this is not appropriate, you can use the @code{environment-observe-weak} -procedure to create a weak reference from the environment to the -observing procedure. - -For example, suppose an interpreter uses @code{environment-cell} to -reference variables efficiently, as described above in @ref{Caching -Environment Lookups}. That interpreter must register observing -procedures to track changes to the environment. If those procedures -retain any reference to the data structure representing the program -being interpreted, then that structure cannot be collected as long as -the observed environment lives. This is almost certainly incorrect --- -if there are no other references to the structure, it can never be -invoked, so it should be collected. In this case, the interpreter -should register its observing procedure using -@code{environment-observe-weak}, and retain a pointer to it from the -code it updates. Thus, when the code is no longer referenced elsewhere -in the system, the weak link will be broken, and Guile will collect the -code (and its observing procedure). - -@deffn Primitive environment-observe-weak env proc -This function is the same as @code{environment-observe}, except that the -reference @var{env} retains to @var{proc} is a weak reference. This -means that, if there are no other live, non-weak references to -@var{proc}, it will be garbage-collected, and dropped from @var{env}'s -list of observing procedures. -@end deffn - - -@node Observing Environments from C Code, , Observations and Garbage Collection, Observing Changes to Environments -@subsubsection Observing Environments from C Code - -It is also possible to write code that observes an environment in C. -The @code{scm_c_environment_observe} function registers a C -function to observe an environment. The typedef -@code{scm_environment_observer} is the type a C observer function must -have. - -@deftypefn {Libguile function} SCM scm_c_environment_observe (SCM @var{env}, scm_environment_observer *proc, SCM @var{data}, int weak_p) -This is the C-level analog of the Scheme function -@code{environment-observe}. Whenever @var{env}'s bindings change, call -the function @var{proc}, passing it @var{env} and @var{data}. If -@var{weak_p} is non-zero, @var{env} will retain only a weak reference to -@var{data}, and if @var{data} is garbage collected, the entire -observation will be dropped. - -This function returns a token, with the same meaning as those returned -by @code{environment-observe}. -@end deftypefn - -@deftp {Libguile data type} scm_environment_observer void (SCM @var{env}, SCM @var{data}) -The type for observing functions written in C. A function meant to be -passed to @code{scm_c_environment_observe} should have the type -@code{scm_environment_observer}. -@end deftp - -Note that, like all other primitives, @code{environment-observe} is also -available from C, under the name @code{scm_environment_observe}. - - -@node Environment Errors, , Observing Changes to Environments , Common Environment Operations -@subsection Environment Errors - -Here are the error conditions signalled by the environment routines -described above. In these conditions, @var{func} is a string naming a -particular procedure. - -@deffn Condition environment:unbound func message args env symbol -By calling @var{func}, the program attempted to retrieve the value of -@var{symbol} in @var{env}, but @var{symbol} is unbound in @var{env}. -@end deffn - -@deffn Condition environment:immutable-binding func message args env symbol -By calling @var{func}, the program attempted to change the binding of -@var{symbol} in @var{env}, but that binding is immutable. -@end deffn - -@deffn Condition environment:immutable-location func message args env symbol -By calling @var{func}, the program attempted to change the value of -the location to which @var{symbol} is bound in @var{env}, but that -location is immutable. -@end deffn - - -@node Standard Environment Types, Implementing Environments, Common Environment Operations, Top-Level Environments in Guile -@section Standard Environment Types - -Guile supports several different kinds of environments. The operations -described above are actually only the common functionality provided by -all the members of a family of environment types, each designed for a -separate purpose. - -Each environment type has a constructor procedure for building elements -of that type, and extends the set of common operations with its own -procedures, providing specialized functions. For an example of how -these environment types work together, see @ref{Modules of Interpreted -Scheme Code}. - -Guile allows users to define their own environment types. Given a set -of procedures that implement the common environment operations, Guile -will construct a new environment object based on those procedures. - -@menu -* Leaf Environments:: A simple set of bindings. -* Eval Environments:: Local definitions, shadowing - imported definitions. -* Import Environments:: The union of a list of environments. -* Export Environments:: A selected subset of an environment. -* General Environments:: Environments implemented by user - functions. -@end menu - -@node Leaf Environments, Eval Environments, Standard Environment Types, Standard Environment Types -@subsection Leaf Environments - -A @dfn{leaf} environment is simply a mutable set of definitions. A mutable -environment supports no operations beyond the common set. - -@deffn Primitive make-leaf-environment -Create a new leaf environment, containing no bindings. All bindings -and locations in the new environment are mutable. -@end deffn - -@deffn Primitive leaf-environment? object -Return @code{#t} if @var{object} is a leaf environment, or @var{#f} -otherwise. -@end deffn - - -In Guile, each module of interpreted Scheme code uses a leaf -environment to hold the definitions made in that module. - -Leaf environments are so named because their bindings are not computed -from the contents of other environments. Most other environment types -have no bindings of their own, but compute their binding sets based on -those of their operand environments. Thus, the environments in a -running Guile system form a tree, with interior nodes computing their -contents from their child nodes. Leaf environments are the leaves of -such trees. - - -@node Eval Environments, Import Environments, Leaf Environments, Standard Environment Types -@subsection Eval Environments - -A module's source code refers to definitions imported from other -modules, and definitions made within itself. An @dfn{eval} environment -combines two environments --- a @dfn{local} environment and an -@dfn{imported} environment --- to produce a new environment in which -both sorts of references can be resolved. - -@deffn Primitive make-eval-environment local imported -Return a new environment object @var{eval} whose bindings are the union -of the bindings in the environments @var{local} and @var{imported}, with -bindings from @var{local} taking precedence. Definitions made in -@var{eval} are placed in @var{local}. - -Applying @code{environment-define} or @code{environment-undefine} to -@var{eval} has the same effect as applying the procedure to @var{local}. -This means that applying @code{environment-undefine} to a symbol bound -in @var{imported} and free in @var{local} has no effect on the bindings -visible in @var{eval}, which may be surprising. - -Note that @var{eval} incorporates @var{local} and @var{imported} -@emph{by reference} --- if, after creating @var{eval}, the program -changes the bindings of @var{local} or @var{imported}, those changes -will be visible in @var{eval}. - -Since most Scheme evaluation takes place in @var{eval} environments, -they transparently cache the bindings received from @var{local} and -@var{imported}. Thus, the first time the program looks up a symbol in -@var{eval}, @var{eval} may make calls to @var{local} or @var{imported} -to find their bindings, but subsequent references to that symbol will be -as fast as references to bindings in leaf environments. - -In typical use, @var{local} will be a leaf environment, and -@var{imported} will be an import environment, described below. -@end deffn - -@deffn Primitive eval-environment? object -Return @code{#t} if @var{object} is an eval environment, or @code{#f} -otherwise. -@end deffn - -@deffn Primitive eval-environment-local env -@deffnx Primitive eval-environment-imported env -Return the @var{local} or @var{imported} environment of @var{env}; -@var{env} must be an eval environment. -@end deffn - - -@node Import Environments, Export Environments, Eval Environments, Standard Environment Types -@subsection Import Environments - -An @dfn{import} environment combines the bindings of a set of -argument environments, and checks for naming clashes. - -@deffn Primitive make-import-environment imports conflict-proc -Return a new environment @var{imp} whose bindings are the union of the -bindings from the environments in @var{imports}; @var{imports} must be a -list of environments. That is, @var{imp} binds @var{symbol} to -@var{location} when some element of @var{imports} does. - -If two different elements of @var{imports} have a binding for the same -symbol, apply @var{conflict-proc} to the two environments. If the bindings -of any of the @var{imports} ever changes, check for conflicts again. - -All bindings in @var{imp} are immutable. If you apply -@code{environment-define} or @code{environment-undefine} to @var{imp}, -Guile will signal an @code{environment:immutable-binding} error. -However, notice that the set of bindings in @var{imp} may still change, -if one of its imported environments changes. -@end deffn - -@deffn Primitive import-environment? object -Return @code{#t} if @var{object} is an import environment, or @code{#f} -otherwise. -@end deffn - -@deffn Primitive import-environment-imports env -Return the list of @var{env}'s imported environments; @var{env} must be -an import env. -@end deffn - -@deffn Primitive import-environment-set-imports! env imports -Change @var{env}'s list of imported environments to @var{imports}, and -check for conflicts. -@end deffn - -I'm not at all sure about the way @var{conflict-proc} works. I think -module systems should warn you if it seems you're likely to get the -wrong binding, but exactly how and when those warnings should be -generated, I don't know. - - -@node Export Environments, General Environments, Import Environments, Standard Environment Types -@subsection Export Environments - -An export environment restricts an environment a specified set of -bindings. - -@deffn Primitive make-export-environment private signature -Return a new environment @var{exp} containing only those bindings in -@var{private} whose symbols are present in @var{signature}. The -@var{private} argument must be an environment. - -The environment @var{exp} binds @var{symbol} to @var{location} when -@var{env} does, and @var{symbol} is exported by @var{signature}. - -@var{Signature} is a list specifying which of the bindings in -@var{private} should be visible in @var{exp}. Each element of -@var{signature} should be a list of the form: -@example -(@var{symbol} @var{attribute} ...) -@end example -@noindent -where each @var{attribute} is one of the following: -@table @asis -@item the symbol @code{mutable-location} -@var{exp} should treat the location bound to @var{symbol} as mutable. -That is, @var{exp} will pass calls to @var{env-set!} or -@code{environment-cell} directly through to @var{private}. - -@item the symbol @code{immutable-location} -@var{exp} should treat the location bound to @var{symbol} as immutable. -If the program applies @code{environment-set!} to @var{exp} and -@var{symbol}, or calls @code{environment-cell} to obtain a writable -value cell, @code{environment-set!} will signal an -@code{environment:immutable-location} error. - -Note that, even if an export environment treats a location as immutable, -the underlying environment may treat it as mutable, so its value may -change. -@end table - -It is an error for an element of @var{signature} to specify both -@code{mutable-location} and @code{immutable-location}. If neither is -specified, @code{immutable-location} is assumed. - -As a special case, if an element of @var{signature} is a lone symbol -@var{sym}, it is equivalent to an element of the form -@code{(@var{sym})}. - -All bindings in @var{exp} are immutable. If you apply -@code{environment-define} or @code{environment-undefine} to @var{exp}, -Guile will signal an @code{environment:immutable-binding} error. -However, notice that the set of bindings in @var{exp} may still change, -if the bindings in @var{private} change. -@end deffn - -@deffn Primitive export-environment? object -Return @code{#t} if @var{object} is an export environment, or @code{#f} -otherwise. -@end deffn - -@deffn Primitive export-environment-private env -@deffnx Primitive export-environment-set-private! env -@deffnx Primitive export-environment-signature env -@deffnx Primitive export-environment-set-signature! env -Accessors and mutators for the private environment and signature of -@var{env}; @var{env} must be an export environment. -@end deffn - - -@node General Environments, , Export Environments, Standard Environment Types -@subsection General Environments - -[[user provides the procedures]] -[[A observers B and C; B observes C; C changes; A should only be -notified once, right?]] -[[observation loops?]] - -@node Implementing Environments, Switching to Environments, Standard Environment Types, Top-Level Environments in Guile -@section Implementing Environments - -This section describes how to implement new environment types in Guile. - -Guile's internal representation of environments allows you to extend -Guile with new kinds of environments without modifying Guile itself. -Every environment object carries a pointer to a structure of pointers to -functions implementing the common operations for that environment. The -procedures @code{environment-ref}, @code{environment-set!}, etc. simply -find this structure and invoke the appropriate function. - -[[It would be nice to have an example around here. How about a -persistent environment, bound to a directory, where ref and set actually -access files? Ref on a directory would return another -environment... Hey, let's import my home directory!]] - - -@menu -* Environment Function Tables:: -* Environment Data:: -* Environment Example:: -@end menu - - -@node Environment Function Tables, Environment Data, Implementing Environments, Implementing Environments -@subsection Environment Function Tables - -An environment object is a smob whose @sc{cdr} is a pointer to a pointer -to a @code{struct environment_funcs}: -@example -struct environment_funcs @{ - SCM (*ref) (SCM self, SCM symbol); - SCM (*fold) (SCM self, scm_environment_folder *proc, SCM data, SCM init); - void (*define) (SCM self, SCM symbol, SCM value); - void (*undefine) (SCM self, SCM symbol); - void (*set) (SCM self, SCM symbol, SCM value); - SCM (*cell) (SCM self, SCM symbol, int for_write); - SCM (*observe) (SCM self, scm_environment_observer *proc, SCM data, int weak_p); - void (*unobserve) (SCM self, SCM token); - SCM (*mark) (SCM self); - scm_sizet (*free) (SCM self); - int (*print) (SCM self, SCM port, scm_print_state *pstate); -@}; -@end example - -You can use the following macro to access an environment's function table: - -@deftypefn {Libguile macro} struct environment_funcs *SCM_ENVIRONMENT_FUNCS (@var{env}) -Return a pointer to the @code{struct environment_func} for the environment -@var{env}. If @var{env} is not an environment object, the behavior of -this macro is undefined. -@end deftypefn - -Here is what each element of @var{env_funcs} must do to correctly -implement an environment. In all of these calls, @var{self} is the -environment whose function is being invoked. - -@table @code - -@item SCM ref (SCM @var{self}, SCM @var{symbol}); -This function must have the effect described above for the C call: -@example -scm_c_environment_ref (@var{self}, @var{symbol}) -@end example -@xref{Examining Environments}. - -Note that the @code{ref} element of a @code{struct environment_funcs} -may be zero if a @code{cell} function is provided. - -@item SCM fold (SCM self, scm_environment_folder *proc, SCM data, SCM init); -This function must have the effect described above for the C call: -@example -scm_c_environment_fold (@var{self}, @var{proc}, @var{data}, @var{init}) -@end example -@xref{Examining Environments}. - -@item void define (SCM self, SCM symbol, SCM value); -This function must have the effect described above for the Scheme call: -@example -(environment-define @var{self} @var{symbol} @var{value}) -@end example -@xref{Changing Environments}. - -@item void undefine (SCM self, SCM symbol); -This function must have the effect described above for the Scheme call: -@example -(environment-undefine @var{self} @var{symbol}) -@end example -@xref{Changing Environments}. - -@item void set (SCM self, SCM symbol, SCM value); -This function must have the effect described above for the Scheme call: -@example -(environment-set! @var{self} @var{symbol} @var{value}) -@end example -@xref{Changing Environments}. - -Note that the @code{set} element of a @code{struct environment_funcs} -may be zero if a @code{cell} function is provided. - -@item SCM cell (SCM self, SCM symbol, int for_write); -This function must have the effect described above for the C call: -@example -scm_c_environment_cell (@var{self}, @var{symbol}) -@end example -@xref{Caching Environment Lookups}. - -@item SCM observe (SCM self, scm_environment_observer *proc, SCM data, int weak_p); -This function must have the effect described above for the C call: -@example -scm_c_environment_observe (@var{env}, @var{proc}, @var{data}, @var{weak_p}) -@end example -@xref{Observing Changes to Environments}. - -@item void unobserve (SCM self, SCM token); -Cancel the request to observe @var{self} that returned @var{token}. -@xref{Observing Changes to Environments}. - -@item SCM mark (SCM self); -Set the garbage collection mark all Scheme cells referred to by -@var{self}. Assume that @var{self} itself is already marked. Return a -final object to be marked recursively. - -@item scm_sizet free (SCM self); -Free all non-cell storage associated with @var{self}; return the number -of bytes freed that were obtained using @code{scm_must_malloc} or -@code{scm_must_realloc}. - -@item SCM print (SCM self, SCM port, scm_print_state *pstate); -Print an external representation of @var{self} on @var{port}, passing -@var{pstate} to any recursive calls to the object printer. - -@end table - - -@node Environment Data, Environment Example, Environment Function Tables, Implementing Environments -@subsection Environment Data - -When you implement a new environment type, you will likely want to -associate some data of your own design with each environment object. -Since ANSI C promises that casts will safely convert between a pointer -to a structure and a pointer to its first element, you can have the -@sc{cdr} of an environment smob point to your structure, as long as your -structure's first element is a pointer to a @code{struct -environment_funcs}. Then, your code can use the macro below to retrieve -a pointer to the structure, and cast it to the appropriate type. - -@deftypefn {Libguile macro} struct environment_funcs **SCM_ENVIRONMENT_DATA (@var{env}) -Return the @sc{cdr} of @var{env}, as a pointer to a pointer to an -@code{environment_funcs} structure. -@end deftypefn - -@node Environment Example, , Environment Data, Implementing Environments -@subsection Environment Example - -[[perhaps a simple environment based on association lists]] - - -@node Switching to Environments, , Implementing Environments, Top-Level Environments in Guile -@section Switching to Environments - -Here's what we'd need to do to today's Guile to install the system -described above. This work would probably be done on a branch, because -it involves crippling Guile while a lot of work gets done. Also, it -could change the default set of bindings available pretty drastically, -so the next minor release should not contain these changes. - -After each step here, we should have a Guile that we can at least -interact with, perhaps with some limitations. - -@itemize @bullet - -@item -For testing purposes, make an utterly minimal version of -@file{boot-9.scm}: no module system, no R5RS, nothing. I think a simple -REPL is all we need. - -@item -Implement the environment datatypes in libguile, and test them using -this utterly minimal system. - -@item -Change the interpreter to use the @code{environment-cell} and -@code{environment-observe} instead of the symbol value slots, -first-class variables, etc. Modify the rest of libguile as necessary to -register all the primitives in a single environment. We'll segregate -them into modules later. - -@item -Reimplement the current module system in terms of environments. It -should still be in Scheme. - -@item -Reintegrate the rest of @file{boot-9.scm}. This might be a good point -to move it into modules. - -@item -Do some profiling and optimization. - -@end itemize - -Once this is done, we can make the following simplifications to Guile: - -@itemize @bullet - -@item -A good portion of symbols.c can go away. Symbols no longer need value -slots. The mishmash of @code{scm_sym2ovcell}, -@code{scm_intern_obarray_soft}, etc. can go away. @code{intern} becomes -simpler. - -@item -Remove first-class variables: @file{variables.c} and @file{variables.h}. - -@item -Organize the primitives into environments. - -@item -The family of environment types is clearly an abstract class/concrete -subclass arrangement. We should provide GOOPS classes/metaclasses that -make defining new environment types easy and consistent. - -@end itemize - - - -@node Modules, , Top-Level Environments in Guile, Top -@chapter Modules - -The material here is just a sketch. Don't take it too seriously. The -point is that environments allow us to experiment without getting -tangled up with the interpreter. - -@menu -* Modules of Guile Primitives:: -* Modules of Interpreted Scheme Code:: -@end menu - -@node Modules of Guile Primitives, Modules of Interpreted Scheme Code, Modules, Modules -@section Modules of Guile Primitives - -@node Modules of Interpreted Scheme Code, , Modules of Guile Primitives, Modules -@section Modules of Interpreted Scheme Code - -If a module is implemented by interpreted Scheme code, Guile represents -it using several environments: - -@table @asis - -@item the @dfn{local} environment -This environment holds all the definitions made locally by the module, -both public and private. - -@item the @dfn{import} environment -This environment holds all the definitions this module imports from -other modules. - -@item the @dfn{evaluation} environment -This is the environment in which the module's code is actually -evaluated, and the one closed over by the module's procedures, both -public and private. Its bindings are the union of the @var{local} and -@var{import} environments, with local bindings taking precedence. - -@item the @dfn{exported} environment -This environment holds the module's public definitions. This is the -only environment that the module's users have access to. It is the -@var{evaluation} environment, restricted to the set of exported -definitions. - -@end table - -Each of these environments is implemented using a separate environment -type. Some of these types, like the evaluation and import environments, -actually just compute their bindings by consulting other environments; -they have no bindings in their own right. They implement operations -like @code{environment-ref} and @code{environment-define} by passing -them through to the environments from which they are derived. For -example, the evaluation environment will pass definitions through to the -local environment, and search for references and assignments first in -the local environment, and then in the import environment. - - - -@bye diff --git a/doc/sources/format.texi b/doc/sources/format.texi deleted file mode 100644 index 122e0453d..000000000 --- a/doc/sources/format.texi +++ /dev/null @@ -1,434 +0,0 @@ - -@menu -* Format Interface:: -* Format Specification:: -@end menu - -@node Format Interface, Format Specification, Format, Format -@subsection Format Interface - -@defun format destination format-string . arguments -An almost complete implementation of Common LISP format description -according to the CL reference book @cite{Common LISP} from Guy L. -Steele, Digital Press. Backward compatible to most of the available -Scheme format implementations. - -Returns @code{#t}, @code{#f} or a string; has side effect of printing -according to @var{format-string}. If @var{destination} is @code{#t}, -the output is to the current output port and @code{#t} is returned. If -@var{destination} is @code{#f}, a formatted string is returned as the -result of the call. NEW: If @var{destination} is a string, -@var{destination} is regarded as the format string; @var{format-string} is -then the first argument and the output is returned as a string. If -@var{destination} is a number, the output is to the current error port -if available by the implementation. Otherwise @var{destination} must be -an output port and @code{#t} is returned.@refill - -@var{format-string} must be a string. In case of a formatting error -format returns @code{#f} and prints a message on the current output or -error port. Characters are output as if the string were output by the -@code{display} function with the exception of those prefixed by a tilde -(~). For a detailed description of the @var{format-string} syntax -please consult a Common LISP format reference manual. For a test suite -to verify this format implementation load @file{formatst.scm}. Please -send bug reports to @code{lutzeb@@cs.tu-berlin.de}. - -Note: @code{format} is not reentrant, i.e. only one @code{format}-call -may be executed at a time. - -@end defun - -@node Format Specification, , Format Interface, Format -@subsection Format Specification (Format version 3.0) - -Please consult a Common LISP format reference manual for a detailed -description of the format string syntax. For a demonstration of the -implemented directives see @file{formatst.scm}.@refill - -This implementation supports directive parameters and modifiers -(@code{:} and @code{@@} characters). Multiple parameters must be -separated by a comma (@code{,}). Parameters can be numerical parameters -(positive or negative), character parameters (prefixed by a quote -character (@code{'}), variable parameters (@code{v}), number of rest -arguments parameter (@code{#}), empty and default parameters. Directive -characters are case independent. The general form of a directive -is:@refill - -@noindent -@var{directive} ::= ~@{@var{directive-parameter},@}[:][@@]@var{directive-character} - -@noindent -@var{directive-parameter} ::= [ [-|+]@{0-9@}+ | '@var{character} | v | # ] - - -@subsubsection Implemented CL Format Control Directives - -Documentation syntax: Uppercase characters represent the corresponding -control directive characters. Lowercase characters represent control -directive parameter descriptions. - -@table @asis -@item @code{~A} -Any (print as @code{display} does). -@table @asis -@item @code{~@@A} -left pad. -@item @code{~@var{mincol},@var{colinc},@var{minpad},@var{padchar}A} -full padding. -@end table -@item @code{~S} -S-expression (print as @code{write} does). -@table @asis -@item @code{~@@S} -left pad. -@item @code{~@var{mincol},@var{colinc},@var{minpad},@var{padchar}S} -full padding. -@end table -@item @code{~D} -Decimal. -@table @asis -@item @code{~@@D} -print number sign always. -@item @code{~:D} -print comma separated. -@item @code{~@var{mincol},@var{padchar},@var{commachar}D} -padding. -@end table -@item @code{~X} -Hexadecimal. -@table @asis -@item @code{~@@X} -print number sign always. -@item @code{~:X} -print comma separated. -@item @code{~@var{mincol},@var{padchar},@var{commachar}X} -padding. -@end table -@item @code{~O} -Octal. -@table @asis -@item @code{~@@O} -print number sign always. -@item @code{~:O} -print comma separated. -@item @code{~@var{mincol},@var{padchar},@var{commachar}O} -padding. -@end table -@item @code{~B} -Binary. -@table @asis -@item @code{~@@B} -print number sign always. -@item @code{~:B} -print comma separated. -@item @code{~@var{mincol},@var{padchar},@var{commachar}B} -padding. -@end table -@item @code{~@var{n}R} -Radix @var{n}. -@table @asis -@item @code{~@var{n},@var{mincol},@var{padchar},@var{commachar}R} -padding. -@end table -@item @code{~@@R} -print a number as a Roman numeral. -@item @code{~:@@R} -print a number as an ``old fashioned'' Roman numeral. -@item @code{~:R} -print a number as an ordinal English number. -@item @code{~:@@R} -print a number as a cardinal English number. -@item @code{~P} -Plural. -@table @asis -@item @code{~@@P} -prints @code{y} and @code{ies}. -@item @code{~:P} -as @code{~P but jumps 1 argument backward.} -@item @code{~:@@P} -as @code{~@@P but jumps 1 argument backward.} -@end table -@item @code{~C} -Character. -@table @asis -@item @code{~@@C} -prints a character as the reader can understand it (i.e. @code{#\} prefixing). -@item @code{~:C} -prints a character as emacs does (eg. @code{^C} for ASCII 03). -@end table -@item @code{~F} -Fixed-format floating-point (prints a flonum like @var{mmm.nnn}). -@table @asis -@item @code{~@var{width},@var{digits},@var{scale},@var{overflowchar},@var{padchar}F} -@item @code{~@@F} -If the number is positive a plus sign is printed. -@end table -@item @code{~E} -Exponential floating-point (prints a flonum like @var{mmm.nnn}@code{E}@var{ee}). -@table @asis -@item @code{~@var{width},@var{digits},@var{exponentdigits},@var{scale},@var{overflowchar},@var{padchar},@var{exponentchar}E} -@item @code{~@@E} -If the number is positive a plus sign is printed. -@end table -@item @code{~G} -General floating-point (prints a flonum either fixed or exponential). -@table @asis -@item @code{~@var{width},@var{digits},@var{exponentdigits},@var{scale},@var{overflowchar},@var{padchar},@var{exponentchar}G} -@item @code{~@@G} -If the number is positive a plus sign is printed. -@end table -@item @code{~$} -Dollars floating-point (prints a flonum in fixed with signs separated). -@table @asis -@item @code{~@var{digits},@var{scale},@var{width},@var{padchar}$} -@item @code{~@@$} -If the number is positive a plus sign is printed. -@item @code{~:@@$} -A sign is always printed and appears before the padding. -@item @code{~:$} -The sign appears before the padding. -@end table -@item @code{~%} -Newline. -@table @asis -@item @code{~@var{n}%} -print @var{n} newlines. -@end table -@item @code{~&} -print newline if not at the beginning of the output line. -@table @asis -@item @code{~@var{n}&} -prints @code{~&} and then @var{n-1} newlines. -@end table -@item @code{~|} -Page Separator. -@table @asis -@item @code{~@var{n}|} -print @var{n} page separators. -@end table -@item @code{~~} -Tilde. -@table @asis -@item @code{~@var{n}~} -print @var{n} tildes. -@end table -@item @code{~}<newline> -Continuation Line. -@table @asis -@item @code{~:}<newline> -newline is ignored, white space left. -@item @code{~@@}<newline> -newline is left, white space ignored. -@end table -@item @code{~T} -Tabulation. -@table @asis -@item @code{~@@T} -relative tabulation. -@item @code{~@var{colnum,colinc}T} -full tabulation. -@end table -@item @code{~?} -Indirection (expects indirect arguments as a list). -@table @asis -@item @code{~@@?} -extracts indirect arguments from format arguments. -@end table -@item @code{~(@var{str}~)} -Case conversion (converts by @code{string-downcase}). -@table @asis -@item @code{~:(@var{str}~)} -converts by @code{string-capitalize}. -@item @code{~@@(@var{str}~)} -converts by @code{string-capitalize-first}. -@item @code{~:@@(@var{str}~)} -converts by @code{string-upcase}. -@end table -@item @code{~*} -Argument Jumping (jumps 1 argument forward). -@table @asis -@item @code{~@var{n}*} -jumps @var{n} arguments forward. -@item @code{~:*} -jumps 1 argument backward. -@item @code{~@var{n}:*} -jumps @var{n} arguments backward. -@item @code{~@@*} -jumps to the 0th argument. -@item @code{~@var{n}@@*} -jumps to the @var{n}th argument (beginning from 0) -@end table -@item @code{~[@var{str0}~;@var{str1}~;...~;@var{strn}~]} -Conditional Expression (numerical clause conditional). -@table @asis -@item @code{~@var{n}[} -take argument from @var{n}. -@item @code{~@@[} -true test conditional. -@item @code{~:[} -if-else-then conditional. -@item @code{~;} -clause separator. -@item @code{~:;} -default clause follows. -@end table -@item @code{~@{@var{str}~@}} -Iteration (args come from the next argument (a list)). -@table @asis -@item @code{~@var{n}@{} -at most @var{n} iterations. -@item @code{~:@{} -args from next arg (a list of lists). -@item @code{~@@@{} -args from the rest of arguments. -@item @code{~:@@@{} -args from the rest args (lists). -@end table -@item @code{~^} -Up and out. -@table @asis -@item @code{~@var{n}^} -aborts if @var{n} = 0 -@item @code{~@var{n},@var{m}^} -aborts if @var{n} = @var{m} -@item @code{~@var{n},@var{m},@var{k}^} -aborts if @var{n} <= @var{m} <= @var{k} -@end table -@end table - - -@subsubsection Not Implemented CL Format Control Directives - -@table @asis -@item @code{~:A} -print @code{#f} as an empty list (see below). -@item @code{~:S} -print @code{#f} as an empty list (see below). -@item @code{~<~>} -Justification. -@item @code{~:^} -(sorry I don't understand its semantics completely) -@end table - - -@subsubsection Extended, Replaced and Additional Control Directives - -@table @asis -@item @code{~@var{mincol},@var{padchar},@var{commachar},@var{commawidth}D} -@item @code{~@var{mincol},@var{padchar},@var{commachar},@var{commawidth}X} -@item @code{~@var{mincol},@var{padchar},@var{commachar},@var{commawidth}O} -@item @code{~@var{mincol},@var{padchar},@var{commachar},@var{commawidth}B} -@item @code{~@var{n},@var{mincol},@var{padchar},@var{commachar},@var{commawidth}R} -@var{commawidth} is the number of characters between two comma characters. -@end table - -@table @asis -@item @code{~I} -print an R5RS complex number as @code{~F~@@Fi} with passed parameters for -@code{~F}. -@item @code{~Y} -Pretty print formatting of an argument for scheme code lists. -@item @code{~K} -Same as @code{~?.} -@item @code{~!} -Flushes the output if format @var{destination} is a port. -@item @code{~_} -Print a @code{#\space} character -@table @asis -@item @code{~@var{n}_} -print @var{n} @code{#\space} characters. -@end table -@item @code{~/} -Print a @code{#\tab} character -@table @asis -@item @code{~@var{n}/} -print @var{n} @code{#\tab} characters. -@end table -@item @code{~@var{n}C} -Takes @var{n} as an integer representation for a character. No arguments -are consumed. @var{n} is converted to a character by -@code{integer->char}. @var{n} must be a positive decimal number.@refill -@item @code{~:S} -Print out readproof. Prints out internal objects represented as -@code{#<...>} as strings @code{"#<...>"} so that the format output can always -be processed by @code{read}. -@refill -@item @code{~:A} -Print out readproof. Prints out internal objects represented as -@code{#<...>} as strings @code{"#<...>"} so that the format output can always -be processed by @code{read}. -@item @code{~Q} -Prints information and a copyright notice on the format implementation. -@table @asis -@item @code{~:Q} -prints format version. -@end table -@refill -@item @code{~F, ~E, ~G, ~$} -may also print number strings, i.e. passing a number as a string and -format it accordingly. -@end table - -@subsubsection Configuration Variables - -Format has some configuration variables at the beginning of -@file{format.scm} to suit the systems and users needs. There should be -no modification necessary for the configuration that comes with SLIB. -If modification is desired the variable should be set after the format -code is loaded. Format detects automatically if the running scheme -system implements floating point numbers and complex numbers. - -@table @asis - -@item @var{format:symbol-case-conv} -Symbols are converted by @code{symbol->string} so the case type of the -printed symbols is implementation dependent. -@code{format:symbol-case-conv} is a one arg closure which is either -@code{#f} (no conversion), @code{string-upcase}, @code{string-downcase} -or @code{string-capitalize}. (default @code{#f}) - -@item @var{format:iobj-case-conv} -As @var{format:symbol-case-conv} but applies for the representation of -implementation internal objects. (default @code{#f}) - -@item @var{format:expch} -The character prefixing the exponent value in @code{~E} printing. (default -@code{#\E}) - -@end table - -@subsubsection Compatibility With Other Format Implementations - -@table @asis -@item SLIB format 2.x: -See @file{format.doc}. - -@item SLIB format 1.4: -Downward compatible except for padding support and @code{~A}, @code{~S}, -@code{~P}, @code{~X} uppercase printing. SLIB format 1.4 uses C-style -@code{printf} padding support which is completely replaced by the CL -@code{format} padding style. - -@item MIT C-Scheme 7.1: -Downward compatible except for @code{~}, which is not documented -(ignores all characters inside the format string up to a newline -character). (7.1 implements @code{~a}, @code{~s}, -~@var{newline}, @code{~~}, @code{~%}, numerical and variable -parameters and @code{:/@@} modifiers in the CL sense).@refill - -@item Elk 1.5/2.0: -Downward compatible except for @code{~A} and @code{~S} which print in -uppercase. (Elk implements @code{~a}, @code{~s}, @code{~~}, and -@code{~%} (no directive parameters or modifiers)).@refill - -@item Scheme->C 01nov91: -Downward compatible except for an optional destination parameter: S2C -accepts a format call without a destination which returns a formatted -string. This is equivalent to a #f destination in S2C. (S2C implements -@code{~a}, @code{~s}, @code{~c}, @code{~%}, and @code{~~} (no directive -parameters or modifiers)).@refill - -@end table - -This implementation of format is solely useful in the SLIB context -because it requires other components provided by SLIB.@refill diff --git a/doc/sources/guile-slib.texi b/doc/sources/guile-slib.texi deleted file mode 100644 index c8f07d1b2..000000000 --- a/doc/sources/guile-slib.texi +++ /dev/null @@ -1,2 +0,0 @@ -@node Guile and SLIB -@chapter Guile and SLIB diff --git a/doc/sources/jimb-org.texi b/doc/sources/jimb-org.texi deleted file mode 100644 index c4ad9ea41..000000000 --- a/doc/sources/jimb-org.texi +++ /dev/null @@ -1,131 +0,0 @@ -@menu -Preliminary - -* Introduction:: -* Using Guile:: - - - -@bye - ->You can actually put any English text to break up the menu, so you ->could put the "Part n" headings in it. - - - -Introduction - --- Explains Guile's goals, and gives brief examples of how to use - Guile interactively (show off repl), as a script interpreter, - and as an embedded interpreter. - -Part I: Guile Scheme - R4RS Scheme as a Starting Point - --- Here we refer to R4RS, and explain that we're only - describing differences. - Block comments and interpreter triggers - Symbol case - Keywords - Exceptions - Modules - --- the preceding three come first, because we need them - in order to explain the behavior of some things later - Exception Handling - --- mention that repls usually establish default exception handlers - Dynamic Wind - Records - Structures - Arrays - Binary Numeric Operations - Shared and Read-Only Strings - Object Properties - Association Lists and Hash Tables - (Dictionaries In General) - association lists - hash tables (Hash Values) - Input/Output ports - file ports - soft ports - string ports - extended I/O (fseek; line read/write) - Garbage Collection - Threads and Dynamic Roots - Reflection - eval - Tag Values - Weak references - Regular Expressions - SLIB - POSIX system calls and networking - --- I think people will generally know whether they're looking - for a system call or not, so this should be an okay category. - conventions (includes error handling) - ports vs. file descriptors - file system (mknod goes here, no?) - user database - time (includes gettimeofday or whatever, strftime, strptime) - processes - terminals and pseudo-terminals - pipes - networking (includes databases, address conversion, and sockets) - system identification (uname) - locales (setlocale) - --- Note that there is no more 'misc'. It's better to have - small sections than unhelpful names. - SCSH - --- includes info on how to get SCSH features (open this - module), but mostly just a pointer to the SCSH manual. - This should not be under POSIX. SCSH includes plenty of - high-level stuff for starting processes and string - processing. SCSH is not a subset of POSIX, nor the - reverse. - Tcl/Tk interface - Module internals - first-class variables - first-class modules - internal debugging interface - --- The name of this chapter needs to clearly distinguish it - from the appendix describing the debugger UI. The intro - should have a pointer to the UI appendix. - -Part II: Using Scheme with C --- a Portable Interface - --- We cover gh in a completely separate section. Why? I admit - I'm on shaky ground, but here's my reasoning: People who want - to write portable C code need to restrict themselves to only - using GH, and GH's semantics are (necessarily) well-defined - without reference to Guile's particulars. This makes life - more difficult for folks who just prefer to use the GH - interface when they can, but I really think the SCM interface - is not so bad, once you're used to it. A *lot* of GH - functions are just wrappers for SCM functions. - --- We cover repls here too, since GH has repl functions. - -Part III: Using Scheme with C --- Guile's Interface - Scheme data representation - Relationship between Scheme and C functions - --- this is where we explain that all the functions marked as - "Primitive Functions" are also accessible from C, and how - to derive the C interface given the Scheme interface, when - we don't spell it out. - ... I think there's other stuff needed here ... - I/O internals - linking Guile with your code - --- Mark's "Tools to automate adding libraries" is not a - well-defined concept. I think this is closer to what we - want to cover for now. - snarfing - -Appendices: - Obtaining and Installing Guile - Invoking Guile - --- mentions read-eval-print loops - --- both the SCSH and GAWK manuals relegate invocation details - to an appendix. We can give examples in the introduction. - debugger user interface - --- The title and introduction of this appendix need to - distinguish this clearly from the chapter on the internal - debugging interface. - -Indices: - --- At the top of the function/variable index, remind people - to look for functions under their Scheme names as well as - their C names. diff --git a/doc/sources/libguile-overview.texi b/doc/sources/libguile-overview.texi deleted file mode 100644 index 96a4a76ce..000000000 --- a/doc/sources/libguile-overview.texi +++ /dev/null @@ -1,30 +0,0 @@ -@node Libguile overview -@chapter Libguile overview -@cindex libguile - overview - -Extension languages, like Guile, Python and Tcl, can be embedded into a -C program, @footnote{Or a C++ or Fortran or Pascal program if you want.} -and thus allow the user to @emph{extend} the C program. - -The way this is done is by providing a C language library with a well -defined interface. The interface consists of a set of public and -documented C-callable routines that offer the full interpreter -functionality, and allow the conversion of data between C and the -extension language. - -@menu -* An example of libguile functionality:: -* What can be done with libguile:: -* Schizofrenia -- two APIs:: -@end menu - -@node An example of libguile functionality -@section An example of libguile functionality - -[Two examples: using strings and using data conversion.] - -@node What can be done with libguile -@section What can be done with libguile - -@node Schizofrenia -- two APIs -@section Schizofrenia -- two APIs diff --git a/doc/sources/libguile-tools.texi b/doc/sources/libguile-tools.texi deleted file mode 100644 index d434406e9..000000000 --- a/doc/sources/libguile-tools.texi +++ /dev/null @@ -1,191 +0,0 @@ -@node Tools to automate adding libraries -@chapter Tools to automate adding libraries - -You want to ... - -The chapters @ref{Libguile -- high level interface} and @ref{Libguile -- -SCM interface} showed how to make C libraries available from Scheme. -Here I will describe some automated tools that the Guile team has made -available. Some have been written especially for Guile (the Guile Magic -Snarfer), and some are also in use with other languages (Python, Perl, -...) - -@menu -* By hand with gh_:: -* By hand with Guile Magic Snarfer:: -* Automatically using libtool:: -* Automatically using SWIG:: -@end menu - -@node By hand with gh_ -@section By hand with gh_ - -@node By hand with Guile Magic Snarfer -@section By hand with Guile Magic Snarfer - -When writing C code for use with Guile, you typically define a set of C -functions, and then make some of them visible to the Scheme world by -calling the @code{scm_make_gsubr} function; a C functions published in -this way is called a @dfn{subr}. If you have many subrs to publish, it -can sometimes be annoying to keep the list of calls to -@code{scm_make_gsubr} in sync with the list of function definitions. -Frequently, a programmer will define a new subr in C, recompile his -application, and then discover that the Scheme interpreter cannot see -the subr, because he forgot to call @code{scm_make_gsubr}. - -Guile provides the @code{guile-snarf} command to manage this problem. -Using this tool, you can keep all the information needed to define the -subr alongside the function definition itself; @code{guile-snarf} will -extract this information from your source code, and automatically -generate a file of calls to @code{scm_make_gsubr} which you can -@code{#include} into an initialization function. (The command name -comes from the verb ``to snarf'', here meaning ``to unceremoniously -extract information from a somewhat unwilling source.'') - -@menu -* How guile-snarf works:: Using the @code{guile-snarf} command. -* Macros guile-snarf recognizes:: How to mark up code for @code{guile-snarf}. -@end menu - -@node How guile-snarf works -@subsection How @code{guile-snarf} works - -For example, here is how you might define a new subr called -@code{clear-image}, implemented by the C function @code{clear_image}: - -@example -@group -#include <libguile.h> - -@dots{} - -SCM_PROC (s_clear_image, "clear-image", 1, 0, 0, clear_image); - -SCM -clear_image (SCM image_smob) -@{ - @dots{} -@} - -@dots{} - -void -init_image_type () -@{ -#include "image-type.x" -@} -@end group -@end example - -The @code{SCM_PROC} declaration says that the C function -@code{clear_image} implements a Scheme subr called @code{clear-image}, -which takes one required argument, no optional arguments, and no tail -argument. @code{SCM_PROC} also declares a static array of characters -named @code{s_clear_image}, initialized to the string -@code{"clear-image"}. The body of @code{clear_image} may use the array -in error messages, instead of writing out the literal string; this may -save string space on some systems. - -Assuming the text above lives in a file named @file{image-type.c}, you will -need to execute the following command to compile this file: -@example -guile-snarf image-type.c > image-type.x -@end example -@noindent This scans @file{image-type.c} for @code{SCM_PROC} -declarations, and sends the following output to the file -@file{image-type.x}: -@example -scm_make_gsubr (s_clear_image, 1, 0, 0, clear_image); -@end example -When compiled normally, @code{SCM_PROC} is a macro which expands to a -declaration of the @code{s_clear_image} string. - -In other words, @code{guile-snarf} scans source code looking for uses of -the @code{SCM_PROC} macro, and generates C code to define the -appropriate subrs. You need to provide all the same information you -would if you were using @code{scm_make_gsubr} yourself, but you can -place the information near the function definition itself, so it is less -likely to become incorrect or out-of-date. - -If you have many files that @code{guile-snarf} must process, you should -consider using a rule like the following in your Makefile: -@example -.SUFFIXES: .x -.c.x: - ./guile-snarf $(DEFS) $(INCLUDES) $(CPPFLAGS) $(CFLAGS) $< > $@ -@end example -This tells make to run @code{guile-snarf} to produce each needed -@file{.x} file from the corresponding @file{.c} file. - -@code{guile-snarf} passes all its command-line arguments directly to the -C preprocessor, which it uses to extract the information it needs from -the source code. this means you can pass normal compilation flags to -@code{guile-snarf} to define preprocessor symbols, add header file -directories, and so on. - - - -@node Macros guile-snarf recognizes -@subsection Macros @code{guile-snarf} recognizes - -Here are the macros you can use in your source code from which -@code{guile-snarf} can construct initialization code: - - -@defmac SCM_PROC (@var{namestr}, @var{name}, @var{req}, @var{opt}, @var{tail}, @var{c_func}) -Declare a new Scheme primitive function, or @dfn{subr}. The new subr -will be named @var{name} in Scheme code, and be implemented by the C -function @var{c_func}. The subr will take @var{req} required arguments -and @var{opt} optional arguments. If @var{tail} is non-zero, the -function will accept any remaining arguments as a list. - -Use this macro outside all function bodies, preferably above the -definition of @var{c_func} itself. When compiled, the @code{SCM_PROC} -declaration will expand to a definition for the @var{namestr} array, -initialized to @var{name}. The @code{guile-snarf} command uses this -declaration to automatically generate initialization code to create the -subr and bind it in the top-level environment. @xref{How guile-snarf -works}, for more info. - -@xref{Subrs}, for details on argument passing and how to write -@var{c_func}. -@end defmac - - -@defmac SCM_GLOBAL (@var{var}, @var{scheme_name}) -Declare a global Scheme variable named @var{scheme_name}, and a static C -variable named @var{var} to point to it. The value of the Scheme -variable lives in the @sc{cdr} of the cell @var{var} points to. -Initialize the variable to @code{#f}. - -Use this macro outside all function bodies. When compiled, the -@code{SCM_GLOBAL} macro will expand to a definition for the variable -@var{var}, initialized to an innocuous value. The @code{guile-snarf} -command will use this declaration to automatically generate code to -create a global variable named @var{scheme_name}, and store a pointer to -its cell in @var{var}. -@end defmac - - -@defmac SCM_CONST_LONG (@var{var}, @var{scheme_name}, @var{value}) -Like @code{SCM_GLOBAL}, but initialize the variable to @var{value}, -which must be an integer. -@end defmac - - -@defmac SCM_SYMBOL (@var{var}, @var{name}) -Declare a C variable of type @code{SCM} named @var{var}, and initialize -it to the Scheme symbol object whose name is @var{name}. - -Use this macro outside all function bodies. When compiled, the -@code{SCM_SYMBOL} macro will expand to a definition for the variable -@var{var}, initialized to an innocuous value. The @code{guile-snarf} -command will use this declaration to automatically generate code to -create a symbol named @var{name}, and store it in @var{var}. -@end defmac - -@node Automatically using libtool -@section Automatically using libtool - -@node Automatically using SWIG -@section Automatically using SWIG diff --git a/doc/sources/new-types.texi b/doc/sources/new-types.texi deleted file mode 100644 index 1840b214f..000000000 --- a/doc/sources/new-types.texi +++ /dev/null @@ -1,2 +0,0 @@ -@node Adding types to Guile -@chapter Adding types to Guile diff --git a/doc/sources/old-intro.texi b/doc/sources/old-intro.texi deleted file mode 100644 index 0774f64d4..000000000 --- a/doc/sources/old-intro.texi +++ /dev/null @@ -1,290 +0,0 @@ -@node Introduction -@chapter Introduction - -Guile is an interpreter for Scheme, a clean, economical programming -language in the Lisp family. You can invoke Guile from the shell to -evaluate Scheme expressions interactively, or use it as an interpreter -for script files. However, Guile is also packaged as a library, to be -embedded as an extension language into other applications. The -application can supplement the base language with special-purpose -functions and datatypes, allowing the user to customize and extend it by -writing Scheme code. - -In its simplest form, Guile is an ordinary interpreter. The -@code{guile} program can read and evaluate Scheme expressions entered -from the terminal. Here is a sample interaction between Guile and a -user; the user's input appears after the @code{$} and @code{guile>} -prompts: - -@example -$ guile -guile> (+ 1 2 3) ; add some numbers -6 -guile> (define (factorial n) ; define a function - (if (zero? n) 1 (* n (factorial (- n 1))))) -guile> (factorial 20) -2432902008176640000 -guile> (getpwnam "jimb") ; find my entry in /etc/passwd -#("jimb" ".0krIpK2VqNbU" 4008 10 "Jim Blandy" "/u/jimb" - "/usr/local/bin/bash") -guile> @kbd{C-d} -$ -@end example - -Guile can also interpret script files. For example, here is a Guile script -containing a script which displays the - - -application can -supplement the base language with its own functions, datatypes and -syntax, allowing the user to extend and - - - Guile interpret - -. An -application the Guile interpreter to allow - - -, allowing -applications to incorporate the Scheme interpreter for customization - -[[interactive]] -[[script interpreter]] -[[embedded]] - -[[other languages]] -The concept of an extension language library does not originate with -Guile. However, Guile is the first to offer users a choice of languages -to program in. - - -Guile currently supports Scheme and Ctax , and we expect to support Emacs Lisp in the near future. - - -Scheme is powerful enough that other languages can be -conveniently translated into it, - -However, unlike other extension packages, Guile gives users a choice of -languages to program in. Guile can - - -In this sense, Guile resembles the Tcl and Python packages, providing -both an ordinary interpreter and an extension language library. -However, unlike those packages, Guile supports more than one programming -language. - -; users can -write Scheme code to control and customize applications which -incorporate Guile - -, adding their own functions, -datatypes, and syntax, to allow the user to programm - - -link it into your own programs to make them - - - -Guile is a library containing an interpreter for Scheme, a complete but -economical programming language, which the developer can customize to -suit the application at hand by adding new functions, data types, and -control structures. These may be implemented in C, and then -``exported'' for use by the interpreted code. Because Guile already -provides a full-featured interpreter, the developer need not neglect the -language's design in order to concentrate on code relevant to the task. -In this way, Guile provides a framework for the construction of -domain-specific languages. - -Guile provides first-class functions, a rich set of data types, -exception handling, a module system, and a powerful macro facility. -Guile also supports dynamic linking and direct access to Unix system -calls. Releases in the near future will support a source-level -debugger and bindings for the Tk user interface toolkit. - - - -Guile is a framework for writing applications controlled by specialized -languages. In its simplest form, Guile is an interpreter for Scheme, a -clean, economical programming language in the Lisp family. However, -Guile is packaged as a library, allowing applications to link against it -and use Scheme as their extension language. The application can add -primitive functions to the language, implement new data types, and even -adjust the language's syntax. - - - -[the introduction is probably not what Jim has in mind; I just took the -one I had in earlier, since the file had the same name intro.texi] - -Guile is an implementation of the Scheme programming language, but, like -other modern implementations of Scheme, it adds many features that the -community of Scheme programmers considers necessary for an ``industrial -strength'' language. - -Examples of extensions to Scheme are the module system -(@pxref{Modules}), the Unix system programming tools (@pxref{POSIX -system calls and networking} and @pxref{The Scheme shell (scsh)}), an -interface to @emph{libtool} to make it easier to add C libraries as -primitives (@pxref{Linking Guile with your code}), and (FIXME add more). - -On top of these extensions, which many other Scheme implementations -provide, Guile also offers the possibility of writing routines in other -languages and running them simultaneously with Scheme. The desire to -implement other languages (in particular Emacs Lisp) on top of Scheme is -responsible for Guile's only deviation from the R4RS @footnote{R4RS is -the Revised^4 Report on the Algorithmic Language Scheme, the closest -thing to a standard Scheme specification today} Scheme standard -(@cite{r4rs}): Guile is case sensitive, whereas ``standard'' Scheme is -not. - -But even more fundamentally, Guile is meant to be an @emph{embeddable} -Scheme interpreter. This means that a lot of work has gone into -packaging the interpreter as a C library (@pxref{A Portable C to Scheme Interface} and @pxref{Scheme data representation}). - -This reference manual is mainly driven by the need to document all the -features that go beyond standard Scheme. - -@menu -* Getting started:: -* Guile feature list:: -* What you need to use Guile:: -* Roadmap to the Manual:: -* Motivation for Guile:: -* History of Guile:: -@end menu - -@node Getting started -@section Getting started - -We assume that you know how to program in Scheme, although we do not -assume advanced knowledge. If you don't know Scheme, there are many -good books on Scheme at all levels, and the Guile Tutorial might give -you a good enough feel for the language. We also assume that you know -how to program in C, since there will be many examples of how to program -in C using Guile as a library. - -Many diverse topics from the world of Unix hacking will be covered here, -such as shared libraries, socket programming, garbage collection, and so -forth. If at any time you feel you don't have enough background on a -given topic, just go up a level or two in the manual, and you will find -that the chapter begins with a few paragraphs that introduce the topic. -If you are still lost, read through the Guile tutorial and then come -back to this reference manual. - -To run the core Guile interpreter and extension library you need no more -than a basically configured GNU/Unix system and the Guile sources. You -should download and install the Guile sources (@pxref{Obtaining and -Installing Guile}). - - -@node Guile feature list -@section Guile feature list - -In a reductionist view, Guile could be regarded as: -@itemize @bullet -@item -An R4RS-compliant Scheme interpreter. - -@item -Some Scheme features that go beyond the R4RS standard, notably a module -system, exception handling primitives and an interface to Aubrey -Jaffer's SLIB. - -@item -A symbolic debugger for Scheme, and gdb extensions to facilitate -debugging libguile programs. - -@item -An embeddable version of the same interpreter, called @emph{libguile}. - -@item -A portable high level API on top of libguile (the @code{gh_} interface). - -@item -A collection of bundled C libraries with a Guile API. As we write, this -list includes: - -@table @strong -@item Rx -a regular expression library. - -@item Unix -a low-level interface to the POSIX system calls, socket library -and other Unix system services. - -@item Tk -an interface to John Ousterhout's Tk toolkit. - -@end table - -@item -A set of tools for implementing other languages @emph{on top of Scheme}, -and an example implementation of a language called @emph{Ctax}. - - -@end itemize - - -@node What you need to use Guile -@section What you need to use Guile - - -@node Roadmap to the Manual -@section Roadmap to the Manual - -@node Motivation for Guile -@section Motivation for Guile - -@node History of Guile -@section History of Guile - -@page -@node Using Guile -@chapter Using Guile - -[I think that this might go in the appendix in Jim's view of the manual] - -@page -@node Invoking Guile -@appendix Invoking Guile - --- mentions read-eval-print loops - --- both the SCSH and GAWK manuals relegate invocation details - to an appendix. We can give examples in the introduction. - -@table @samp -@item -h -@itemx --help -Display a helpful message. -@item -v -@item --version -Display the current version. -@item --emacs -To be used for emacs editing support. -@item -s @var{file} -Process @var{file} as a script then quit. This is a terminating option: -any further command line arguments can be accessed by the script using -the @code{(program-arguments)} procedure. - -An executable script can start with the following: - -@smallexample -#!/usr/bin/guile -s -!# -@end smallexample - -Note the @code{!#} token on the second line. It is very important -to include this token when writing Guile scripts. Guile and SCSH, -the Scheme shell, share the convention that @code{#!} and -@code{!#} may be used to mark block comments (@pxref{Block -comments and interpreter triggers}). If the closing @code{!#} -token is not included, then Guile will consider the block comment -to be unclosed, and the script will probably not compile -correctly. - -It is also important to include the @samp{-s} option at the -beginning of the Guile script, so that Guile knows not to behave -in an interactive fashion. - -@end table - diff --git a/doc/sources/sample-APIs.texi b/doc/sources/sample-APIs.texi deleted file mode 100644 index c8c4b8e72..000000000 --- a/doc/sources/sample-APIs.texi +++ /dev/null @@ -1,6 +0,0 @@ -@node Examples of adding libraries -@chapter Examples of adding libraries - -Should contain examples of brute-force gh_, Guile magic snarfer, -libtool, SWIG on a dummy API, followed by some real examples of how -libraries are added. diff --git a/doc/sources/scheme-concepts.texi b/doc/sources/scheme-concepts.texi deleted file mode 100644 index 0e9ae6cf8..000000000 --- a/doc/sources/scheme-concepts.texi +++ /dev/null @@ -1,249 +0,0 @@ -@node Guile Scheme concepts -@chapter Guile Scheme concepts - -Most Scheme implementations go beyond what is specified in the R4RS -document @footnote{Remember? R4RS is the Revised^4 report on the -Algorithmic Language Scheme}, mostly because R4RS does not give -specifications (or even recommendations) regarding some issues that are -quite important in practical programming. - -Here is a list of how Guile implements some of these much-needed Scheme -extensions; other Scheme implementations do so quite similarly. - -@menu -* Scheme slang:: -* Read-eval-print loops:: -* Extra data types:: -* Miscellaneous features:: -@end menu - -@node Scheme slang -@section Scheme slang -@cindex slang - -Even if you read some of the nice books on Scheme, or the R4RS report, -you might not find some of the terms frequently used by Scheme hackers, -both in the manual and in the @url{news:comp.lang.scheme} newsgroup. - -Here is a glossary of some of the terms that make Scheme beginners and -intermediate users say ``huh?'' - -@table @strong -@item thunk -@cindex thunk -A Scheme procedure that takes no arguments. In this example, -@code{thunk} and @code{another-thunk} are both thunks: -@lisp -(define (thunk) - (display "Dude, I'm a thunk!") - (newline)) -(define another-thunk - (lambda () - (display "Me too!\n") - (newline))) -@end lisp - -@item closure -@cindex closure -A closure is a procedure. However, the term emphasizes the fact that a -Scheme procedure remembers (or @dfn{closes over}) the variables that -were visible when the @code{lambda} expression was -evaluated. - -In the example below, we might refer to @code{q} as a closure, because -it has closed over the value of @code{x}: -@lisp -(define p - (lambda (x) - (lambda (y) - (+ x y)))) -(define q (p 5.7)) - -(q 10) -@result{} 15.7 -@end lisp - -However, strictly speaking, every Scheme procedure is really a closure, -since it closes over the top-level environment. - -@item alist -@itemx association list - -@item plist -@itemx property list - -@end table - - -@node Read-eval-print loops -@section Read-eval-print loops -@cindex Read-eval-print loop -@cindex REPL - -To explicitly mention the Scheme read-eval-print loop (REPL) seems weird -because we are all accustomed to firing up an interpreter and having it -read and execute commands. - -But the REPL is not specified in R4RS; rather, it is proposed by the -Scheme Bible @cite{Structure and Interpretation of Computer Programs} -(also known as @emph{SICP}), and implemented in some form in all Scheme -interpreters. -@cindex Structure and Interpretation of Computer Programs -@cindex SICP - -[FIXME: Someone needs to tell me what needs to be said about Guile's -REPL.] - -@node Extra data types -@section Extra data types - -The fundamental Scheme data types specified in R4RS are @emph{numbers} -(both exact and inexact), @emph{characters}, @emph{strings}, -@emph{symbols}, @emph{vectors}, @emph{pairs} and @emph{lists} [FIXME: is -this complete?]. - -Many Scheme interpreters offer more types, and Guile is no exception. -Guile is based on Aubrey Jaffer's SCM interpreter, and thus inherits -@emph{uniform arrays}, [FIXME: any others? How about records?]. - -On top of that, Guile allows you to add extra types, but that is covered -in @ref{Adding types to Guile}. Here I will simply document all the -extra Scheme types shipped with Guile. - -@menu -* Conventional arrays:: -* Uniform arrays:: -* Bit vectors:: -* Complex numbers:: -@end menu - -@node Conventional arrays -@subsection Conventional arrays - -@node Uniform arrays -@subsection Uniform arrays -@cindex arrays - uniform - -The motivation for uniform arrays in Scheme is performance. A vector -provides a performance increase over lists when you want a fixed-size -indexable list. But the elements in a vector can be of different types, -and this makes for larger storage requirements and slightly lower -performance. - -A uniform array is similar to a vector, but all elements have to be of -the same type. - -arrays, uniform arrays, bit vectors: - -@deffn procedure array-fill ra fill -@end deffn -@deffn procedure serial-array-copy! src dst -@end deffn -@deffn procedure serial-array-map ra0 proc [lra] -@end deffn -@deffn procedure array-map ra0 proc [lra] -@end deffn -@deffn procedure array-for-each proc ra0 [lra] -@end deffn -@deffn procedure array-index-map! ra proc -@end deffn -@deffn procedure array-copy! src dst -@end deffn -@deffn procedure array-copy! src dst -@end deffn -@deffn procedure array-copy! src dst -@end deffn -@deffn procedure array-copy! src dst -@end deffn -@deffn procedure array-copy! src dst -@end deffn -@deffn procedure array? ra [prot] -@end deffn -@deffn procedure array-rank ra -@end deffn -@deffn procedure array-dimensions ra -@end deffn -@deffn procedure dimensions->uniform-array dims prot fill ... -@end deffn -@deffn procedure make-shared-array ra mapfunc dims ... -@end deffn -@deffn procedure transpose-array arg ... -@end deffn -@deffn procedure enclose-array axes ... -@end deffn -@deffn procedure array-in-bounds? arg ... -@end deffn -@deffn procedure array-ref ra arg .. -@end deffn -@deffn procedure uniform-vector-ref vec pos -@end deffn -@deffn procedure array-set! ra obj arg ... -@end deffn -@deffn procedure uniform-array-set1! ua obj arg -@end deffn -@deffn procedure array-contents ra [strict] -@end deffn -@deffn procedure uniform-array-read! ra [port-or-fd] [start] [end] -@end deffn -@deffn procedure uniform-array-write! ra [port-or-fd] [start] [end] -@end deffn -@deffn procedure bit-count item seq -@end deffn -@deffn procedure bit-position item v k -@end deffn -@deffn procedure bit-set! v kv obj -@end deffn -@deffn procedure bit-count* v kv obj -@end deffn -@deffn procedure bit-invert v -@end deffn -@deffn procedure array->list ra -@end deffn -@deffn procedure list->uniform-array ndim prot list -@end deffn -@deffn procedure array-prototype ra -@end deffn - -Uniform arrays can be written and read, but @code{read} won't recognize -them unless the optional @code{read-sharp} parameter is supplied, -e.g, -@smalllisp -(read port #t read-sharp) -@end smalllisp - -where @code{read-sharp} is the default procedure for parsing extended -sharp notations. - -Reading an array is not very efficient at present, since it's implemented -by reading a list and converting the list to an array. - -@c FIXME: must use @deftp, but its generation of TeX code is buggy. -@c Must fix it when TeXinfo gets fixed. -@deftp {Scheme type} {uniform array} - -@end deftp - -@node Bit vectors -@subsection Bit vectors - -@node Complex numbers -@subsection Complex numbers - -@c FIXME: must use @deftp, but its generation of TeX code is buggy. -@c Must fix it when TeXinfo gets fixed. -@deftp {Scheme type} complex -Standard complex numbers. -@end deftp - -@node Miscellaneous features -@section Miscellaneous features - -@defun defined? symbol -Returns @code{#t} if a symbol is bound to a value, @code{#f} otherwise. -This kind of procedure is not specified in R4RS because @c FIXME: finish -this thought -@end defun - -@defun object-properties OBJ -and so forth -@end defun diff --git a/doc/sources/scm-ref.texi b/doc/sources/scm-ref.texi deleted file mode 100644 index eca672580..000000000 --- a/doc/sources/scm-ref.texi +++ /dev/null @@ -1,4 +0,0 @@ -@node Libguile -- SCM interface -@chapter Libguile -- SCM interface - - diff --git a/doc/sources/strings.texi b/doc/sources/strings.texi deleted file mode 100644 index 9a1ddc952..000000000 --- a/doc/sources/strings.texi +++ /dev/null @@ -1,45 +0,0 @@ -@node Strings -@chapter Facilities for string manipulation - -@deffn procedure string? string -@end deffn -@deffn procedure read-only-string? string -@end deffn -@deffn procedure list->string list -@end deffn -@deffn procedure make-string length [char] -@end deffn -@deffn procedure string-length string -@end deffn -@deffn procedure string-ref string [index] -@end deffn -@deffn procedure string-set! string index char -@end deffn -@deffn procedure substring string start [end] -@end deffn -@deffn procedure string-append arg ... -@end deffn -@deffn procedure make-shared-substring string [from] [to] -@end deffn -@deffn procedure string-set! string index char -@end deffn -@deffn procedure string-index string char [from] [to] -@end deffn -@deffn procedure string-rindex string char [from] [to] -@end deffn -@deffn procedure substring-move-left! string1 start1 [end1] [string2] [start2] -@end deffn -@deffn procedure substring-move-right! string1 start1 [end1] [string2] [start2] -@end deffn -@deffn procedure substring-fill! string start [end] [fill] -@end deffn -@deffn procedure string-null? string -@end deffn -@deffn procedure string->list string -@end deffn -@deffn procedure string-copy string -@end deffn -@deffn procedure string-upcase! string -@end deffn -@deffn procedure string-downcase! string -@end deffn diff --git a/doc/sources/tk.texi b/doc/sources/tk.texi deleted file mode 100644 index 176c8c7b8..000000000 --- a/doc/sources/tk.texi +++ /dev/null @@ -1,5 +0,0 @@ -@node Tk interface -@chapter Tk interface - -For now Guile has no well-specified Tk interface. It is an important part -of Guile, though, and will be documented here when it is written. diff --git a/doc/sources/unix-other.texi b/doc/sources/unix-other.texi deleted file mode 100644 index 7b810d5d6..000000000 --- a/doc/sources/unix-other.texi +++ /dev/null @@ -1,132 +0,0 @@ -@node Other Unix -@chapter Other Unix-specific facilities - -@menu -* Expect:: Expect, for pattern matching from a port. -@end menu - -@node Expect -@section Expect: Pattern Matching from a Port - -@code{expect} is a macro for selecting actions based on the output from -a port. The name comes from a tool of similar functionality by Don Libes. -Actions can be taken when a particular string is matched, when a timeout -occurs, or when end-of-file is seen on the port. The @code{expect} macro -is described below; @code{expect-strings} is a front-end to @code{expect} -based on regexec @xref{Regular expressions}. - -Using these macros requires for now: -@smalllisp -(load-from-path "ice-9/expect") -@end smalllisp - -@defun expect-strings clause @dots{} -By default, @code{expect-strings} will read from the current input port. -The first term in each clause consists of an expression evaluating to -a string pattern (regular expression). As characters -are read one-by-one from the port, they are accumulated in a buffer string -which is matched against each of the patterns. When a -pattern matches, the remaining expression(s) in -the clause are evaluated and the value of the last is returned. For example: - -@smalllisp -(with-input-from-file "/etc/passwd" - (lambda () - (expect-strings - ("^nobody" (display "Got a nobody user.\n") - (display "That's no problem.\n")) - ("^daemon" (display "Got a daemon user.\n"))))) -@end smalllisp - -The regular expression is compiled with the @code{REG_NEWLINE} flag, so -that the @code{^} and @code{$} anchors will match at any newline, not -just at the start -and end of the string. - -There are two other ways to write a clause: - -The expression(s) to evaluate on a match -can be omitted, in which case the result of the match -(converted to strings, as obtained from regexec with @var{match-pick} -set to @code{""}) will be returned if the pattern matches. - -The symbol @code{=>} can be used to indicate that there is a single -expression to evaluate on a match, which must be a -procedure which will accept the result of a successful match (converted -to strings, as obtained from regexec with @var{match-pick} set to -@code{""}). E.g., - -@smalllisp -("^daemon" => write) -("^d\\(aemon\\)" => (lambda args (map write args))) -("^da\\(em\\)on" => (lambda (all sub) - (write all) - (write sub))) -@end smalllisp - -The order of the substrings corresponds to the order in which the -opening brackets occur in the regular expression. - -A number of variables can be used to control the behaviour -of @code{expect} (and @code{expect-strings}). -By default they are all bound at the top level to -the value @code{#f}, which produces the default behaviour. -They can be redefined at the -top level or locally bound in a form enclosing the @code{expect} expression. - -@table @code -@item expect-port -A port to read characters from, instead of the current input port. -@item expect-timeout -@code{expect} will terminate after this number of -seconds, returning @code{#f} or the value returned by -@code{expect-timeout-proc}. -@item expect-timeout-proc -A procedure called if timeout occurs. The procedure takes a single argument: -the accumulated string. -@item expect-eof-proc -A procedure called if end-of-file is detected on the input port. The -procedure takes a single argument: the accumulated string. -@item expect-char-proc -A procedure to be called every time a character is read from the -port. The procedure takes a single argument: the character which was read. -@end table - -Here's an example using all of the variables: - -@smalllisp -(let ((expect-port (open-input-file "/etc/passwd")) - (expect-timeout 1) - (expect-timeout-proc - (lambda (s) (display "Times up!\n"))) - (expect-eof-proc - (lambda (s) (display "Reached the end of the file!\n"))) - (expect-char-proc display)) - (expect-strings - ("^nobody" (display "Got a nobody user\n")))) -@end smalllisp -@end defun - -@defun expect clause @dots{} -@code{expect} is used in the same way as @code{expect-strings}, -but tests are specified not as patterns, but as procedures. The -procedures are called in turn after each character is read from the -port, with the value of the accumulated string as the argument. The -test is successful if the procedure returns a non-false value. - -If the @code{=>} syntax is used, then if the test succeeds it must return -a list containing the arguments to be provided to the corresponding -expression. - -In the following example, a string will only be matched at the beginning -of the file: -@smalllisp -(let ((expect-port (open-input-file "/etc/passwd"))) - (expect - ((lambda (s) (string=? s "fnord!")) - (display "Got a nobody user!\n")))) -@end smalllisp - -The control variables described for @code{expect-strings} can also -be used with @code{expect}. -@end defun diff --git a/doc/sources/unix.texi b/doc/sources/unix.texi deleted file mode 100644 index b8bf2cdb3..000000000 --- a/doc/sources/unix.texi +++ /dev/null @@ -1,622 +0,0 @@ -@node Low level Unix -@chapter Low level Unix interfaces - -The low level Unix interfaces are currently available by -default in the Guile top level. However in the future they will probably -be placed in a module and @code{use-modules} or something similar will -be required to make them available. - -@menu -* Unix conventions:: Conventions followed by the low level Unix - interfaces. -* Ports and descriptors:: Ports, file descriptors and how they - interact. -* Extended I/O:: Reading and writing to ports. -* File system:: Working in a hierarchical file system. -* User database:: Information about users from system databases. -* Processes:: Information and control of Unix processes. -* Terminals:: Terminals and pseudo-terminals. -* Network databases:: Network address conversion and information - from system databases. -* Network sockets:: An interface to the BSD socket library. -* Miscellaneous Unix:: Miscellaneous Unix interfaces. -@end menu - -@node Unix conventions -@section Low level Unix conventions - -The low-level interfaces are designed to give Scheme programs -access to as much functionality as possible from the underlying -Unix system. They can be used to implement higher level -interfaces such as the Scheme shell @ref{scsh}. - -Generally there is a single procedure for each corresponding Unix -facility. However some of the procedures are implemented for -speed and convenience in Scheme and have no Unix equivalent -(e.g., @code{read-delimited}, @code{copy-file}.) - -This interface is intended as far as possible to be portable across -different versions of Unix, so that Scheme programmers don't need to be -concerned with implementation differences. In some cases procedures -which can't be implemented (or reimplemented) on particular systems may -become no-ops, or perform limited actions. In other cases they may -throw errors. It should be possible to use the feature system to -determine what functionality is available. - -General naming conventions are as follows: - -@itemize @bullet -@item -The Scheme name is often identical to the name of the underlying Unix -facility. -@item -Underscores in Unix names are converted to hyphens. -@item -Procedures which destructively modify Scheme data gain appended -exclamation marks, e.g., @code{recv!}. -@item -Predicates have question marks appended, e.g., @code{access?}. -@item -Some names are changed to avoid conflict with dissimilar interfaces -defined by scsh. -@item -Unix preprocessor names such as @code{EPERM} or @code{R_OK} are converted -to Scheme variables of the same name (underscores are not replaced -with hyphens) -@end itemize - -Most of the Unix interface procedures can be relied on to return a -well-specified value. Unexpected conditions are handled by raising -exceptions. - -There are a few procedures which return a special -value if they don't succeed, e.g., @code{getenv} returns @code{#f} -if it the requested string is not found in the environment. These -cases will be noted in the documentation. - -For ways to deal with exceptions, @ref{Exceptions}. - -Errors which the C-library would report by returning a NULL -pointer or through some other means cause a @code{system-error} exception -to be raised. The value of the Unix @code{errno} variable is available -in the data passed by the exception, so there is no need to access the -global errno value (doing so would be unreliable in the presence of -continuations or multiple threads). - -@deffn procedure errno [n] -@end deffn -@deffn procedure perror string -@end deffn - -@node Ports and descriptors -@section Ports and file descriptors - -@deffn procedure move->fdes port fd -@end deffn -@deffn procedure release-port-handle port -@end deffn -@deffn procedure set-port-revealed! @var{port} count -@end deffn -@deffn procedure fdes->ports fdes -@end deffn -@deffn procedure fileno port -@end deffn -@deffn procedure fdopen fdes modes -@end deffn -@deffn procedure duplicate-port port modes -@end deffn -@deffn procedure redirect-port into-port from-port -@end deffn -@deffn procedure freopen filename modes port -@end deffn - -@node Extended I/O -@section Extended I/O - -Extended I/O procedures are available which read or write lines of text, -read text delimited by a specified set of characters, or report or -set the current position of a port. - -@findex fwrite -@findex fread -Interfaces to @code{read}/@code{fread} and @code{write}/@code{fwrite} are -also available, as @code{uniform-array-read!} and @code{uniform-array-write!}, -@ref{Uniform arrays}. - -@deffn procedure read-line [port] [handle-delim] -Return a line of text from @var{port} if specified, otherwise from the -value returned by @code{(current-input-port)}. Under Unix, a line of text -is terminated by the first end-of-line character or by end-of-file. - -If @var{handle-delim} is specified, it should be one of the following -symbols: -@table @code -@item trim -Discard the terminating delimiter. This is the default, but it will -be impossible to tell whether the read terminated with a delimiter or -end-of-file. -@item concat -Append the terminating delimiter (if any) to the returned string. -@item peek -Push the terminating delimiter (if any) back on to the port. -@item split -Return a pair containing the string read from the port and the -terminating delimiter or end-of-file object. - -NOTE: if the scsh module is loaded then -multiple values are returned instead of a pair. -@end table -@end deffn -@deffn procedure read-line! buf [port] -Read a line of text into the supplied string @var{buf} and return the -number of characters added to @var{buf}. If @var{buf} is filled, then -@code{#f} is returned. -Read from @var{port} if -specified, otherwise from the value returned by @code{(current-input-port)}. -@end deffn -@deffn procedure read-delimited delims [port] [handle-delim] -Read text until one of the characters in the string @var{delims} is found -or end-of-file is reached. Read from @var{port} if supplied, otherwise -from the value returned by @code{(current-input-port)}. -@var{handle-delim} takes the same values as described for @code{read-line}. - -NOTE: if the scsh module is loaded then @var{delims} must be an scsh -char-set, not a string. -@end deffn -@deffn procedure read-delimited! delims buf [port] [handle-delim] [start] [end] -Read text into the supplied string @var{buf} and return the number of -characters added to @var{buf} (subject to @var{handle-delim}, which takes -the same values specified for @code{read-line}. If @var{buf} is filled, -@code{#f} is returned for both the number of characters read and the -delimiter. Also terminates if one of the characters in the string -@var{delims} is found -or end-of-file is reached. Read from @var{port} if supplied, otherwise -from the value returned by @code{(current-input-port)}. - -NOTE: if the scsh module is loaded then @var{delims} must be an scsh -char-set, not a string. -@end deffn -@deffn procedure write-line obj [port] -Display @var{obj} and a new-line character to @var{port} if specified, -otherwise to the -value returned by @code{(current-output-port)}; equivalent to: - -@smalllisp -(display obj [port]) -(newline [port]) -@end smalllisp -@end deffn -@deffn procedure ftell port -Returns an integer representing the current position of @var{port}, -measured from the beginning. -@end deffn -@deffn procedure fseek port offset whence -Sets the current position of @var{port} to the integer @var{offset}, -which is interpreted according to the value of @var{whence}. - -One of the following variables should be supplied -for @var{whence}: -@defvar SEEK_SET -Seek from the beginning of the file. -@end defvar -@defvar SEEK_CUR -Seek from the current position. -@end defvar -@defvar SEEK_END -Seek from the end of the file. -@end defvar -@end deffn - -@node File system -@section File system - -These procedures query and set file system attributes (such as owner, -permissions, sizes and types of files); deleting, copying, renaming and -linking files; creating and removing directories and querying their -contents; and the @code{sync} interface. - -@deffn procedure access? path how -Evaluates to @code{#t} if @var{path} corresponds to an existing -file and the current process -has the type of access specified by @var{how}, otherwise -@code{#f}. -@var{how} should be specified -using the values of the variables listed below. Multiple values can -be combined using a bitwise or, in which case @code{#t} will only -be returned if all accesses are granted. - -Permissions are checked using the real id of the current process, -not the effective id, although it's the effective id which determines -whether the access would actually be granted. - -@defvar R_OK -test for read permission. -@end defvar -@defvar W_OK -test for write permission. -@end defvar -@defvar X_OK -test for execute permission. -@end defvar -@defvar F_OK -test for existence of the file. -@end defvar -@end deffn -@findex fstat -@deffn procedure stat obj -Evaluates to an object containing various information -about the file determined by @var{obj}. -@var{obj} can be a string containing a file name or a port or file -descriptor which is open on a file (in which case @code{fstat} is used -as the underlying system call). - -The object returned by @code{stat} can be passed as a single parameter -to the following procedures, all of which return integers: - -@table @r -@item stat:dev -The device containing the file. -@item stat:ino -The file serial number, which distinguishes this file from all other -files on the same device. -@item stat:mode -The mode of the file. This includes file type information -and the file permission bits. See @code{stat:type} and @code{stat:perms} -below. -@item stat:nlink -The number of hard links to the file. -@item stat:uid -The user ID of the file's owner. -@item stat:gid -The group ID of the file. -@item stat:rdev -Device ID; this entry is defined only for character or block -special files. -@item stat:size -The size of a regular file in bytes. -@item stat:atime -The last access time for the file. -@item stat:mtime -The last modification time for the file. -@item stat:ctime -The last modification time for the attributes of the file. -@item stat:blksize -The optimal block size for reading or writing the file, in bytes. -@item stat:blocks -The amount of disk space that the file occupies measured in units of -512 byte blocks. -@end table - -In addition, the following procedures return the information -from stat:mode in a more convenient form: - -@table @r -@item stat:type -A symbol representing the type of file. Possible values are -currently: regular, directory, symlink, block-special, char-special, -fifo, socket, unknown -@item stat:perms -An integer representing the access permission bits. -@end table -@end deffn -@deffn procedure lstat path -Similar to @code{stat}, but does not follow symbolic links, i.e., -it will return information about a symbolic link itself, not the -file it points to. @var{path} must be a string. -@end deffn -@deffn procedure readlink path -@end deffn -@deffn procedure chown path owner group -@end deffn -@deffn procedure chmod port-or-path mode -@end deffn -@deffn procedure utime path [actime] [modtime] -@end deffn -@deffn procedure delete-file path -@end deffn -@deffn procedure copy-file path-from path-to -@end deffn -@deffn procedure rename-file path-from path-to -@end deffn -@deffn procedure link path-from path-to -@end deffn -@deffn procedure symlink path-from path-to -@end deffn -@deffn procedure mkdir path [mode] -@end deffn -@deffn procedure rmdir path -@end deffn -@deffn procedure opendir path -@end deffn -@deffn procedure readdir port -@end deffn -@deffn procedure rewinddir port -@end deffn -@deffn procedure closedir port -@end deffn -@deffn procedure sync -@end deffn - -@node User database -@section User database - -@deffn procedure getpwuid uid -@end deffn -@deffn procedure getpwnam name -@end deffn -@deffn procedure getpwent -@end deffn -@deffn procedure setpwent port -@end deffn -@deffn procedure endpwent -@end deffn -@deffn procedure getgrgid uid -@end deffn -@deffn procedure getgrnam name -@end deffn -@deffn procedure getgrent -@end deffn -@deffn procedure setgrent port -@end deffn -@deffn procedure endgrent -@end deffn - -@node Processes -@section Processes - -@deffn procedure chdir path -@end deffn -@deffn procedure getcwd -@end deffn -@deffn procedure umask [mode] -@end deffn -@deffn procedure getpid -@end deffn -@deffn procedure getgroups -@end deffn -@deffn procedure kill pid sig - -@var{sig} should be specified using a variable corresponding to -the Unix symbolic name, e.g, -@defvar SIGHUP -Hang-up signal. -@end defvar -@defvar SIGINT -Interrupt signal. -@end defvar -@end deffn -@deffn procedure waitpid pid options -@defvar WAIT_ANY -@end defvar -@defvar WAIT_MYPGRP -@end defvar -@defvar WNOHANG -@end defvar -@defvar WUNTRACED -@end defvar -@end deffn -@deffn procedure getppid -@end deffn -@deffn procedure getuid -@end deffn -@deffn procedure getgid -@end deffn -@deffn procedure geteuid -@end deffn -@deffn procedure getegid -@end deffn -@deffn procedure setuid id -@end deffn -@deffn procedure setgid id -@end deffn -@deffn procedure seteuid id -@end deffn -@deffn procedure setegid id -@end deffn -@deffn procedure getpgrp -@end deffn -@deffn procedure setpgid pid pgid -@end deffn -@deffn procedure setsid -@end deffn -@deffn procedure execl arg ... -@end deffn -@deffn procedure execlp arg ... -@end deffn -@deffn procedure primitive-fork -@end deffn -@deffn procedure environ [env] -@end deffn -@deffn procedure putenv string -@end deffn -@deffn procedure nice incr -@end deffn - -@node Terminals -@section Terminals and pseudo-terminals - -@deffn procedure isatty? port -@end deffn -@deffn procedure ttyname port -@end deffn -@deffn procedure ctermid -@end deffn -@deffn procedure tcgetpgrp port -@end deffn -@deffn procedure tcsetpgrp port pgid -@end deffn - -@node Network databases -@section Network address conversion and system databases - -@deffn procedure inet-aton address -@end deffn -@deffn procedure inet-ntoa number -@end deffn -@deffn procedure inet-netof address -@end deffn -@deffn procedure inet-lnaof address -@end deffn -@deffn procedure inet-makeaddr net lna -@end deffn -@deffn procedure gethostbyname name -@end deffn -@deffn procedure gethostbyaddr address -@end deffn -@deffn procedure gethostent -@end deffn -@deffn procedure sethostent port -@end deffn -@deffn procedure endhostent -@end deffn -@deffn procedure getnetbyname name -@end deffn -@deffn procedure getnetbyaddr address -@end deffn -@deffn procedure getnetent -@end deffn -@deffn procedure setnetent port -@end deffn -@deffn procedure endnetent -@end deffn -@deffn procedure getprotobyname name -@end deffn -@deffn procedure getprotobynumber number -@end deffn -@deffn procedure getprotoent -@end deffn -@deffn procedure setprotoent port -@end deffn -@deffn procedure endprotoent -@end deffn -@deffn procedure getservbyname name protocol -@end deffn -@deffn procedure getservbyport port protocol -@end deffn -@deffn procedure getservent -@end deffn -@deffn procedure setservent port -@end deffn -@deffn procedure endservent -@end deffn - -@node Network sockets -@section BSD socket library interface - -@deffn procedure socket family style protocol -@end deffn -@deffn procedure socketpair family style protocol -@end deffn -@deffn procedure getsockopt socket level optname -@end deffn -@deffn procedure setsockopt socket level optname value -@end deffn -@deffn procedure shutdown socket how -@end deffn -@deffn procedure connect socket family address arg ... -@end deffn -@deffn procedure bind socket family address arg ... -@end deffn -@deffn procedure listen socket backlog -@end deffn -@deffn procedure accept socket -@end deffn -@deffn procedure getsockname socket -@end deffn -@deffn procedure getpeername socket -@end deffn -@deffn procedure recv! socket buf [flags] -@end deffn -@deffn procedure send socket message [flags] -@end deffn -@deffn procedure recvfrom! socket buf [flags] [start] [end] -@end deffn -@deffn procedure sendto socket message family address args ... [flags] -@end deffn - -@node Miscellaneous Unix -@section Miscellaneous Unix interfaces - -Things which haven't been classified elsewhere (yet?). - -@deffn procedure open path flags [mode] -@defvar O_RDONLY -@end defvar -@defvar O_WRONLY -@end defvar -@defvar O_RDWR -@end defvar -@defvar O_CREAT -@end defvar -@defvar O_EXCL -@end defvar -@defvar O_NOCTTY -@end defvar -@defvar O_TRUNC -@end defvar -@defvar O_APPEND -@end defvar -@defvar O_NONBLOCK -@end defvar -@defvar O_NDELAY -@end defvar -@defvar O_SYNC -@end defvar -@end deffn -@deffn procedure select reads writes excepts secs msecs -@end deffn -@deffn procedure uname -@end deffn -@deffn procedure pipe -@end deffn -@deffn procedure open-pipe command modes -@end deffn -@deffn procedure open-input-pipe command -@end deffn -@deffn procedure open-output-pipe command -@end deffn -@deffn procedure setlocale category [locale] -@defvar LC_COLLATE -@end defvar -@defvar LC_CTYPE -@end defvar -@defvar LC_MONETARY -@end defvar -@defvar LC_NUMERIC -@end defvar -@defvar LC_TIME -@end defvar -@defvar LC_MESSAGES -@end defvar -@defvar LC_ALL -@end defvar -@end deffn -@deffn procedure strftime format stime -@end deffn -@deffn procedure strptime format string -@end deffn -@deffn procedure mknod -@end deffn - -@node scsh -@chapter The Scheme shell (scsh) - -Guile includes an incomplete port of the Scheme shell (scsh) 0.4.4. - -For information about scsh on the Web see -@url{http://www-swiss.ai.mit.edu/scsh/scsh.html}. -The original scsh is available by ftp from -@url{ftp://swiss-ftp.ai.mit.edu:/pub/su}. - -This port of scsh does not currently use the Guile module system, but -can be initialized using: -@smalllisp -(load-from-path "scsh/init") -@end smalllisp - -Note that SLIB must be installed before scsh can be initialized, see -@ref{SLIB} for details. - -@node Threads -@chapter Programming Threads. - |