diff options
Diffstat (limited to 'doc/ref')
| -rw-r--r-- | doc/ref/api-compound.texi | 110 | ||||
| -rw-r--r-- | doc/ref/api-control.texi | 42 | ||||
| -rw-r--r-- | doc/ref/api-data.texi | 189 | ||||
| -rw-r--r-- | doc/ref/api-debug.texi | 12 | ||||
| -rw-r--r-- | doc/ref/api-evaluation.texi | 24 | ||||
| -rw-r--r-- | doc/ref/api-foreign.texi | 12 | ||||
| -rw-r--r-- | doc/ref/api-io.texi | 58 | ||||
| -rw-r--r-- | doc/ref/api-macros.texi | 10 | ||||
| -rw-r--r-- | doc/ref/api-memory.texi | 2 | ||||
| -rw-r--r-- | doc/ref/api-modules.texi | 10 | ||||
| -rw-r--r-- | doc/ref/api-procedures.texi | 43 | ||||
| -rw-r--r-- | doc/ref/api-regex.texi | 4 | ||||
| -rw-r--r-- | doc/ref/api-scheduling.texi | 87 | ||||
| -rw-r--r-- | doc/ref/api-smobs.texi | 10 | ||||
| -rw-r--r-- | doc/ref/api-utility.texi | 8 | ||||
| -rw-r--r-- | doc/ref/compiler.texi | 4 | ||||
| -rw-r--r-- | doc/ref/goops.texi | 71 | ||||
| -rw-r--r-- | doc/ref/match.texi | 20 | ||||
| -rw-r--r-- | doc/ref/misc-modules.texi | 55 | ||||
| -rw-r--r-- | doc/ref/posix.texi | 96 | ||||
| -rw-r--r-- | doc/ref/r6rs.texi | 35 | ||||
| -rw-r--r-- | doc/ref/scheme-using.texi | 10 | ||||
| -rw-r--r-- | doc/ref/srfi-modules.texi | 255 | ||||
| -rw-r--r-- | doc/ref/sxml-match.texi | 6 | ||||
| -rw-r--r-- | doc/ref/vm.texi | 6 | ||||
| -rw-r--r-- | doc/ref/web.texi | 8 |
26 files changed, 617 insertions, 570 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 |