mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-04-29 19:30:36 +02:00
Code Activity

Fix typos throughout codebase.

Browse source 
* NEWS:
* doc/ref/api-control.texi:
* doc/ref/api-data.texi:
* doc/ref/api-debug.texi:
* doc/ref/api-deprecated.texi:
* doc/ref/api-evaluation.texi:
* doc/ref/api-foreign.texi:
* doc/ref/api-i18n.texi:
* doc/ref/api-io.texi:
* doc/ref/api-languages.texi:
* doc/ref/api-macros.texi:
* doc/ref/api-memory.texi:
* doc/ref/api-modules.texi:
* doc/ref/api-options.texi:
* doc/ref/api-peg.texi:
* doc/ref/api-procedures.texi:
* doc/ref/api-scheduling.texi:
* doc/ref/api-undocumented.texi:
* doc/ref/api-utility.texi:
* doc/ref/expect.texi:
* doc/ref/goops.texi:
* doc/ref/misc-modules.texi:
* doc/ref/posix.texi:
* doc/ref/repl-modules.texi:
* doc/ref/scheme-ideas.texi:
* doc/ref/scheme-scripts.texi:
* doc/ref/srfi-modules.texi:
* gc-benchmarks/larceny/dynamic.sch:
* gc-benchmarks/larceny/twobit-input-long.sch:
* gc-benchmarks/larceny/twobit.sch:
* libguile/gc.h:
* libguile/ioext.c:
* libguile/list.c:
* libguile/options.c:
* libguile/posix.c:
* libguile/threads.c:
* module/ice-9/boot-9.scm:
* module/ice-9/optargs.scm:
* module/ice-9/ports.scm:
* module/ice-9/pretty-print.scm:
* module/ice-9/psyntax.scm:
* module/language/elisp/parser.scm:
* module/language/tree-il/compile-bytecode.scm:
* module/srfi/srfi-37.scm:
* module/srfi/srfi-43.scm:
* module/statprof.scm:
* module/texinfo/reflection.scm:
* test-suite/tests/eval.test:
* test-suite/tests/fluids.test:
Fix typos.

Signed-off-by: Ludovic Courtès <ludo@gnu.org>
This commit is contained in:
Morgan Smith 2024-02-01 14:32:59 -05:00 • committed by Ludovic Courtès
parent 5fcf6ff17a
commit f27e8b855f
No known key found for this signature in database
GPG key ID: 090B11993D9AEBB5
49 changed files with 409 additions and 400 deletions
Download patch file Download diff file Expand all files Collapse all files

2
NEWS
View file

@ -9549,7 +9549,7 @@ Use scm_object_to_string instead.
** Deprecated function: scm_wta ** Deprecated function: scm_wta
Use scm_wrong_type_arg, or another appropriate error signalling function Use scm_wrong_type_arg, or another appropriate error signaling function
instead. instead.
** Explicit support for obarrays has been deprecated. ** Explicit support for obarrays has been deprecated.

20
doc/ref/api-control.texi
View file

@ -404,7 +404,7 @@ For example,
Note that each @code{break} and @code{continue} procedure can only be Note that each @code{break} and @code{continue} procedure can only be
used within the dynamic extent of its @code{while}. Outside the used within the dynamic extent of its @code{while}. Outside the
@code{while} their behaviour is unspecified. @code{while} their behavior is unspecified.
@end deffn @end deffn
@cindex named let @cindex named let
@ -567,14 +567,14 @@ incremented by 34:
@end example @end example
The last example illustrates what we mean when we say, "composes with the The last example illustrates what we mean when we say, "composes with the
current continuation". We mean that there is a current continuation -- some current continuation". We mean that there is a current continuation -- some
remaining things to compute, like @code{(lambda (x) (* x 2))} -- and that remaining things to compute, like @code{(lambda (x) (* x 2))} -- and that
calling the saved continuation doesn't wipe out the current continuation, it calling the saved continuation doesn't wipe out the current continuation, it
composes the saved continuation with the current one. composes the saved continuation with the current one.
We're belaboring the point here because traditional Scheme continuations, as We're belaboring the point here because traditional Scheme continuations, as
discussed in the next section, aren't composable, and are actually less discussed in the next section, aren't composable, and are actually less
expressive than continuations captured by prompts. But there's a place for them expressive than continuations captured by prompts. But there's a place for them
both. both.
Before moving on, we should mention that if the handler of a prompt is a Before moving on, we should mention that if the handler of a prompt is a
@ -1553,7 +1553,7 @@ The above @code{scm_with_throw_handler} takes Scheme procedures as body
(thunk) and handler arguments. @code{scm_c_with_throw_handler} is an (thunk) and handler arguments. @code{scm_c_with_throw_handler} is an
equivalent taking C functions. See @code{scm_c_catch} equivalent taking C functions. See @code{scm_c_catch}
(@pxref{Exceptions and C}) for a description of the parameters, the (@pxref{Exceptions and C}) for a description of the parameters, the
behaviour however of course follows @code{with-throw-handler}. behavior however of course follows @code{with-throw-handler}.
@end deftypefn @end deftypefn
@ -1655,12 +1655,12 @@ scm_foo (SCM s1, SCM s2)
c_s1 = scm_to_locale_string (s1); c_s1 = scm_to_locale_string (s1);
/* Call 'free (c_s1)' when the dynwind context is left. /* Call 'free (c_s1)' when the dynwind context is left.
*/ */
scm_dynwind_unwind_handler (free, c_s1, SCM_F_WIND_EXPLICITLY); scm_dynwind_unwind_handler (free, c_s1, SCM_F_WIND_EXPLICITLY);
c_s2 = scm_to_locale_string (s2); c_s2 = scm_to_locale_string (s2);
/* Same as above, but more concisely. /* Same as above, but more concisely.
*/ */
scm_dynwind_free (c_s2); scm_dynwind_free (c_s2);
@ -1891,7 +1891,7 @@ Return @code{#t} if @var{obj} is a fluid; otherwise, return
@deffnx {C Function} scm_fluid_ref (fluid) @deffnx {C Function} scm_fluid_ref (fluid)
Return the value associated with @var{fluid} in the current Return the value associated with @var{fluid} in the current
dynamic root. If @var{fluid} has not been set, then return dynamic root. If @var{fluid} has not been set, then return
its default value. Calling @code{fluid-ref} on an unbound fluid produces its default value. Calling @code{fluid-ref} on an unbound fluid produces
a runtime error. a runtime error.
@end deffn @end deffn
@ -1996,7 +1996,7 @@ dynamic state object.
@deffnx {C Function} scm_set_current_dynamic_state (state) @deffnx {C Function} scm_set_current_dynamic_state (state)
Restore the saved fluid-value associations from @var{state}, replacing Restore the saved fluid-value associations from @var{state}, replacing
the current fluid-value associations. Return the current fluid-value the current fluid-value associations. Return the current fluid-value
associatoins as a dynamic state object, as in associations as a dynamic state object, as in
@code{current-dynamic-state}. @code{current-dynamic-state}.
@end deffn @end deffn
@ -2302,7 +2302,7 @@ Output}), and the corresponding arguments in the @var{args} list.
@end deftypefn @end deftypefn
@subsubsection Signalling Type Errors @subsubsection Signaling Type Errors
Every function visible at the Scheme level should aggressively check the Every function visible at the Scheme level should aggressively check the
types of its arguments, to avoid misinterpreting a value, and perhaps types of its arguments, to avoid misinterpreting a value, and perhaps
@ -2310,7 +2310,7 @@ causing a segmentation fault. Guile provides some macros to make this
easier. easier.
@deftypefn Macro void SCM_ASSERT (int @var{test}, SCM @var{obj}, unsigned int @var{position}, const char *@var{subr}) @deftypefn Macro void SCM_ASSERT (int @var{test}, SCM @var{obj}, unsigned int @var{position}, const char *@var{subr})
@deftypefnx Macro void SCM_ASSERT_TYPE (int @var{test}, SCM @var{obj}, unsigned int @var{position}, const char *@var{subr}, const char *@var{expected}) @deftypefnx Macro void SCM_ASSERT_TYPE (int @var{test}, SCM @var{obj}, unsigned int @var{position}, const char *@var{subr}, const char *@var{expected})
If @var{test} is zero, signal a ``wrong type argument'' error, If @var{test} is zero, signal a ``wrong type argument'' error,
attributed to the subroutine named @var{subr}, operating on the value attributed to the subroutine named @var{subr}, operating on the value
@var{obj}, which is the @var{position}'th argument of @var{subr}. @var{obj}, which is the @var{position}'th argument of @var{subr}.

147
doc/ref/api-data.texi
View file

@ -33,7 +33,7 @@ complex.
* Structures:: Low-level record representation. * Structures:: Low-level record representation.
* Dictionary Types:: About dictionary types in general. * Dictionary Types:: About dictionary types in general.
* Association Lists:: List-based dictionaries. * Association Lists:: List-based dictionaries.
* VHashes:: VList-based dictionaries. * VHashes:: VList-based dictionaries.
* Hash Tables:: Table-based dictionaries. * Hash Tables:: Table-based dictionaries.
* Other Types:: Other sections describe data types too. * Other Types:: Other sections describe data types too.
@end menu @end menu
@ -190,17 +190,17 @@ Whole numbers, positive or negative; e.g.@: --5, 0, 18.
@item rationals @item rationals
The set of numbers that can be expressed as @math{@var{p}/@var{q}} The set of numbers that can be expressed as @math{@var{p}/@var{q}}
where @var{p} and @var{q} are integers; e.g.@: @math{9/16} works, but where @var{p} and @var{q} are integers; e.g.@: @math{9/16} works, but
pi (an irrational number) doesn't. These include integers pi (an irrational number) doesn't. These include integers
(@math{@var{n}/1}). (@math{@var{n}/1}).
@item real numbers @item real numbers
The set of numbers that describes all possible positions along a The set of numbers that describes all possible positions along a
one-dimensional line. This includes rationals as well as irrational one-dimensional line. This includes rationals as well as irrational
numbers. numbers.
@item complex numbers @item complex numbers
The set of numbers that describes all possible positions in a two The set of numbers that describes all possible positions in a two
dimensional space. This includes real as well as imaginary numbers dimensional space. This includes real as well as imaginary numbers
(@math{@var{a}+@var{b}i}, where @var{a} is the @dfn{real part}, (@math{@var{a}+@var{b}i}, where @var{a} is the @dfn{real part},
@var{b} is the @dfn{imaginary part}, and @math{i} is the square root of @var{b} is the @dfn{imaginary part}, and @math{i} is the square root of
@minus{}1.) @minus{}1.)
@ -595,7 +595,7 @@ rational numbers, i.e.@: the predicate will also be fulfilled if
@deffn {Scheme Procedure} rationalize x eps @deffn {Scheme Procedure} rationalize x eps
@deffnx {C Function} scm_rationalize (x, eps) @deffnx {C Function} scm_rationalize (x, eps)
Returns the @emph{simplest} rational number differing Returns the @emph{simplest} rational number differing
from @var{x} by no more than @var{eps}. from @var{x} by no more than @var{eps}.
As required by @acronym{R5RS}, @code{rationalize} only returns an As required by @acronym{R5RS}, @code{rationalize} only returns an
exact result when both its arguments are exact. Thus, you might need exact result when both its arguments are exact. Thus, you might need
@ -767,7 +767,7 @@ otherwise.
Return a @code{1} if the number @var{z} is exact, and @code{0} Return a @code{1} if the number @var{z} is exact, and @code{0}
otherwise. This is equivalent to @code{scm_is_true (scm_exact_p (z))}. otherwise. This is equivalent to @code{scm_is_true (scm_exact_p (z))}.
An alternate approch to testing the exactness of a number is to An alternate approach to testing the exactness of a number is to
use @code{scm_is_signed_integer} or @code{scm_is_unsigned_integer}. use @code{scm_is_signed_integer} or @code{scm_is_unsigned_integer}.
@end deftypefn @end deftypefn
@ -800,7 +800,7 @@ number that has been marked exact with the ``#e'' prefix, Guile is
able to represent it correctly. able to represent it correctly.
@lisp @lisp
(inexact->exact 1.2) (inexact->exact 1.2)
@result{} 5404319552844595/4503599627370496 @result{} 5404319552844595/4503599627370496
#e1.2 #e1.2
@ -1831,7 +1831,7 @@ Return a number in [0, @var{n}).
Accepts a positive integer or real n and returns a Accepts a positive integer or real n and returns a
number of the same type between zero (inclusive) and number of the same type between zero (inclusive) and
@var{n} (exclusive). The values returned have a uniform @var{n} (exclusive). The values returned have a uniform
distribution. distribution.
@end deffn @end deffn
@ -1943,7 +1943,7 @@ applications, do this during initialization of your program:
@subsection Characters @subsection Characters
@tpindex Characters @tpindex Characters
In Scheme, there is a data type to describe a single character. In Scheme, there is a data type to describe a single character.
Defining what exactly a character @emph{is} can be more complicated Defining what exactly a character @emph{is} can be more complicated
than it seems. Guile follows the advice of R6RS and uses The Unicode than it seems. Guile follows the advice of R6RS and uses The Unicode
@ -1985,7 +1985,7 @@ this convenient notation is not valid code. Guile does not interpret
In Scheme, a character literal is written as @code{#\@var{name}} where In Scheme, a character literal is written as @code{#\@var{name}} where
@var{name} is the name of the character that you want. Printable @var{name} is the name of the character that you want. Printable
characters have their usual single character name; for example, characters have their usual single character name; for example,
@code{#\a} is a lower case @code{a}. @code{#\a} is a lower case @code{a}.
Some of the code points are 'combining characters' that are not meant Some of the code points are 'combining characters' that are not meant
to be printed by themselves but are instead meant to modify the to be printed by themselves but are instead meant to modify the
@ -2202,8 +2202,8 @@ Return @code{#t} if @var{chr} is either uppercase or lowercase, else
@deffn {Scheme Procedure} char-general-category chr @deffn {Scheme Procedure} char-general-category chr
@deffnx {C Function} scm_char_general_category (chr) @deffnx {C Function} scm_char_general_category (chr)
Return a symbol giving the two-letter name of the Unicode general Return a symbol giving the two-letter name of the Unicode general
category assigned to @var{chr} or @code{#f} if no named category is category assigned to @var{chr} or @code{#f} if no named category is
assigned. The following table provides a list of category names along assigned. The following table provides a list of category names along
with their meanings. with their meanings.
@ -2305,12 +2305,12 @@ Return the lowercase character version of @var{chr}.
@deffn {Scheme Procedure} char-titlecase chr @deffn {Scheme Procedure} char-titlecase chr
@deffnx {C Function} scm_char_titlecase (chr) @deffnx {C Function} scm_char_titlecase (chr)
Return the titlecase character version of @var{chr} if one exists; Return the titlecase character version of @var{chr} if one exists;
otherwise return the uppercase version. otherwise return the uppercase version.
For most characters these will be the same, but the Unicode Standard For most characters these will be the same, but the Unicode Standard
includes certain digraph compatibility characters, such as @code{U+01F3} includes certain digraph compatibility characters, such as @code{U+01F3}
``dz'', for which the uppercase and titlecase characters are different ``dz'', for which the uppercase and titlecase characters are different
(@code{U+01F1} ``DZ'' and @code{U+01F2} ``Dz'' in this case, (@code{U+01F1} ``DZ'' and @code{U+01F2} ``Dz'' in this case,
respectively). respectively).
@end deffn @end deffn
@ -2452,7 +2452,7 @@ from the initial seed: @var{seed}, (@var{g} @var{seed}),
(@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}), @dots{} (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}), @dots{}
@item @var{p} tells us when to stop -- when it returns true @item @var{p} tells us when to stop -- when it returns true
when applied to one of the seed values. when applied to one of the seed values.
@item @var{f} maps each seed value to a character. These @item @var{f} maps each seed value to a character. These
characters are added to the base character set @var{base_cs} to characters are added to the base character set @var{base_cs} to
form the result; @var{base_cs} defaults to the empty set. form the result; @var{base_cs} defaults to the empty set.
@end itemize @end itemize
@ -2467,7 +2467,7 @@ from the initial seed: @var{seed}, (@var{g} @var{seed}),
(@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}), @dots{} (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}), @dots{}
@item @var{p} tells us when to stop -- when it returns true @item @var{p} tells us when to stop -- when it returns true
when applied to one of the seed values. when applied to one of the seed values.
@item @var{f} maps each seed value to a character. These @item @var{f} maps each seed value to a character. These
characters are added to the base character set @var{base_cs} to characters are added to the base character set @var{base_cs} to
form the result; @var{base_cs} defaults to the empty set. form the result; @var{base_cs} defaults to the empty set.
@end itemize @end itemize
@ -2580,7 +2580,7 @@ returned.
@deffn {Scheme Procedure} ->char-set x @deffn {Scheme Procedure} ->char-set x
@deffnx {C Function} scm_to_char_set (x) @deffnx {C Function} scm_to_char_set (x)
Coerces x into a char-set. @var{x} may be a string, character or Coerces x into a char-set. @var{x} may be a string, character or
char-set. A string is converted to the set of its constituent char-set. A string is converted to the set of its constituent
characters; a character is converted to a singleton set; a char-set is characters; a character is converted to a singleton set; a char-set is
returned as-is. returned as-is.
@end deffn @end deffn
@ -2595,7 +2595,7 @@ procedures.
@deffn {Scheme Procedure} %char-set-dump cs @deffn {Scheme Procedure} %char-set-dump cs
Returns an association list containing debugging information Returns an association list containing debugging information
for @var{cs}. The association list has the following entries. for @var{cs}. The association list has the following entries.
@table @code @table @code
@item char-set @item char-set
The char-set itself The char-set itself
@ -2768,7 +2768,7 @@ useful, several predefined character set variables exist.
These character sets are locale independent and are not recomputed These character sets are locale independent and are not recomputed
upon a @code{setlocale} call. They contain characters from the whole upon a @code{setlocale} call. They contain characters from the whole
range of Unicode code points. For instance, @code{char-set:letter} range of Unicode code points. For instance, @code{char-set:letter}
contains about 100,000 characters. contains about 100,000 characters.
@defvr {Scheme Variable} char-set:lower-case @defvr {Scheme Variable} char-set:lower-case
@ -3578,7 +3578,7 @@ mismatch index, depending upon whether @var{s1} is less than,
equal to, or greater than @var{s2}. The mismatch index is the equal to, or greater than @var{s2}. The mismatch index is the
largest index @var{i} such that for every 0 <= @var{j} < largest index @var{i} such that for every 0 <= @var{j} <
@var{i}, @var{s1}[@var{j}] = @var{s2}[@var{j}] -- that is, @var{i}, @var{s1}[@var{j}] = @var{s2}[@var{j}] -- that is,
@var{i} is the first position where the lowercased letters @var{i} is the first position where the lowercased letters
do not match. do not match.
@end deffn @end deffn
@ -3663,32 +3663,36 @@ case-insensitively.
@deffn {Scheme Procedure} string-hash s [bound [start [end]]] @deffn {Scheme Procedure} string-hash s [bound [start [end]]]
@deffnx {C Function} scm_substring_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 @end deffn
@deffn {Scheme Procedure} string-hash-ci s [bound [start [end]]] @deffn {Scheme Procedure} string-hash-ci s [bound [start [end]]]
@deffnx {C Function} scm_substring_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 @end deffn
Because the same visual appearance of an abstract Unicode character can Because the same visual appearance of an abstract Unicode character can
be obtained via multiple sequences of Unicode characters, even the be obtained via multiple sequences of Unicode characters, even the
case-insensitive string comparison functions described above may return case-insensitive string comparison functions described above may return
@code{#f} when presented with strings containing different @code{#f} when presented with strings containing different
representations of the same character. For example, the Unicode representations of the same character. For example, the Unicode
character ``LATIN SMALL LETTER S WITH DOT BELOW AND DOT ABOVE'' can be character ``LATIN SMALL LETTER S WITH DOT BELOW AND DOT ABOVE'' can be
represented with a single character (U+1E69) or by the character ``LATIN represented with a single character (U+1E69) or by the character ``LATIN
SMALL LETTER S'' (U+0073) followed by the combining marks ``COMBINING SMALL LETTER S'' (U+0073) followed by the combining marks ``COMBINING
DOT BELOW'' (U+0323) and ``COMBINING DOT ABOVE'' (U+0307). DOT BELOW'' (U+0323) and ``COMBINING DOT ABOVE'' (U+0307).
For this reason, it is often desirable to ensure that the strings For this reason, it is often desirable to ensure that the strings
to be compared are using a mutually consistent representation for every to be compared are using a mutually consistent representation for every
character. The Unicode standard defines two methods of normalizing the character. The Unicode standard defines two methods of normalizing the
contents of strings: Decomposition, which breaks composite characters contents of strings: Decomposition, which breaks composite characters
into a set of constituent characters with an ordering defined by the into a set of constituent characters with an ordering defined by the
Unicode Standard; and composition, which performs the converse. Unicode Standard; and composition, which performs the converse.
There are two decomposition operations. ``Canonical decomposition'' There are two decomposition operations. ``Canonical decomposition''
produces character sequences that share the same visual appearance as produces character sequences that share the same visual appearance as
the original characters, while ``compatibility decomposition'' produces the original characters, while ``compatibility decomposition'' produces
ones whose visual appearances may differ from the originals but which ones whose visual appearances may differ from the originals but which
@ -4229,7 +4233,8 @@ a predicate, if it is a character, it is tested for equality and if it
is a character set, it is tested for membership. is a character set, it is tested for membership.
@end deffn @end deffn
The following additional functions are available in the module @code{(ice-9 string-fun)}. They can be used with: The following additional functions are available in the module
@code{(ice-9 string-fun)}. They can be used with:
@example @example
(use-modules (ice-9 string-fun)) (use-modules (ice-9 string-fun))
@ -4237,7 +4242,7 @@ The following additional functions are available in the module @code{(ice-9 stri
@deffn {Scheme Procedure} string-replace-substring str substring replacement @deffn {Scheme Procedure} string-replace-substring str substring replacement
Return a new string where every instance of @var{substring} in string Return a new string where every instance of @var{substring} in string
@var{str} has been replaced by @var{replacement}. For example: @var{str} has been replaced by @var{replacement}. For example:
@lisp @lisp
(string-replace-substring "a ring of strings" "ring" "rut") (string-replace-substring "a ring of strings" "ring" "rut")
@ -4248,7 +4253,7 @@ Return a new string where every instance of @var{substring} in string
@node Representing Strings as Bytes @node Representing Strings as Bytes
@subsubsection Representing Strings as Bytes @subsubsection Representing Strings as Bytes
Out in the cold world outside of Guile, not all strings are treated in In the cold world outside of Guile, not all strings are treated in
the same way. Out there there are only bytes, and there are many ways the same way. Out there there are only bytes, and there are many ways
of representing a strings (sequences of characters) as binary data of representing a strings (sequences of characters) as binary data
(sequences of bytes). (sequences of bytes).
@ -4552,7 +4557,7 @@ Return the number of bytes used to encode a Unicode code point in string
@deffn {Scheme Procedure} %string-dump str @deffn {Scheme Procedure} %string-dump str
@deffnx {C Function} scm_sys_string_dump (str) @deffnx {C Function} scm_sys_string_dump (str)
Returns an association list containing debugging information for Returns an association list containing debugging information for
@var{str}. The association list has the following entries. @var{str}. The association list has the following entries.
@table @code @table @code
@item string @item string
@ -4670,15 +4675,15 @@ themselves to @code{eq?} comparison. But symbols are more descriptive
than numbers, because a symbol's name can be used directly to describe than numbers, because a symbol's name can be used directly to describe
the concept for which that symbol stands. the concept for which that symbol stands.
For example, imagine that you need to represent some colours in a For example, imagine that you need to represent some colors in a
computer program. Using numbers, you would have to choose arbitrarily computer program. Using numbers, you would have to choose arbitrarily
some mapping between numbers and colours, and then take care to use that some mapping between numbers and colors, and then take care to use that
mapping consistently: mapping consistently:
@lisp @lisp
;; 1=red, 2=green, 3=purple ;; 1=red, 2=green, 3=purple
(if (eq? (colour-of vehicle) 1) (if (eq? (color-of vehicle) 1)
...) ...)
@end lisp @end lisp
@ -4691,16 +4696,16 @@ defining constants:
(define green 2) (define green 2)
(define purple 3) (define purple 3)
(if (eq? (colour-of vehicle) red) (if (eq? (color-of vehicle) red)
...) ...)
@end lisp @end lisp
@noindent @noindent
But the simplest and clearest approach is not to use numbers at all, but But the simplest and clearest approach is not to use numbers at all, but
symbols whose names specify the colours that they refer to: symbols whose names specify the colors that they refer to:
@lisp @lisp
(if (eq? (colour-of vehicle) 'red) (if (eq? (color-of vehicle) 'red)
...) ...)
@end lisp @end lisp
@ -4754,7 +4759,7 @@ mixing all the properties up together in a flat list, we could use an
association list like this: association list like this:
@lisp @lisp
(define car1-properties '((colour . red) (define car1-properties '((color . red)
(transmission . manual) (transmission . manual)
(fuel . unleaded) (fuel . unleaded)
(steering . power-assisted))) (steering . power-assisted)))
@ -4767,11 +4772,11 @@ It also allows further properties to use the same symbols among their
possible values without becoming ambiguous: possible values without becoming ambiguous:
@lisp @lisp
(define car1-properties '((colour . red) (define car1-properties '((color . red)
(transmission . manual) (transmission . manual)
(fuel . unleaded) (fuel . unleaded)
(steering . power-assisted) (steering . power-assisted)
(seat-colour . red) (seat-color . red)
(locking . manual))) (locking . manual)))
@end lisp @end lisp
@ -4783,13 +4788,13 @@ extract or change individual pieces of information:
(assq-ref car1-properties 'fuel) @result{} unleaded (assq-ref car1-properties 'fuel) @result{} unleaded
(assq-ref car1-properties 'transmission) @result{} manual (assq-ref car1-properties 'transmission) @result{} manual
(assq-set! car1-properties 'seat-colour 'black) (assq-set! car1-properties 'seat-color 'black)
@result{} @result{}
((colour . red) ((color . red)
(transmission . manual) (transmission . manual)
(fuel . unleaded) (fuel . unleaded)
(steering . power-assisted) (steering . power-assisted)
(seat-colour . black) (seat-color . black)
(locking . manual))) (locking . manual)))
@end lisp @end lisp
@ -4927,11 +4932,11 @@ reading symbols case-insensitively, @var{str} is converted to lowercase
before the returned symbol is looked up or created. before the returned symbol is looked up or created.
@end deffn @end deffn
The following examples illustrate Guile's detailed behaviour as regards The following examples illustrate Guile's detailed behavior as regards
the case-sensitivity of symbols: the case-sensitivity of symbols:
@lisp @lisp
(read-enable 'case-insensitive) ; R5RS compliant behaviour (read-enable 'case-insensitive) ; R5RS compliant behavior
(symbol->string 'flying-fish) @result{} "flying-fish" (symbol->string 'flying-fish) @result{} "flying-fish"
(symbol->string 'Martin) @result{} "martin" (symbol->string 'Martin) @result{} "martin"
@ -4947,7 +4952,7 @@ the case-sensitivity of symbols:
(symbol->string (symbol->string
(string->symbol "K. Harper, M.D."))) @result{} #t (string->symbol "K. Harper, M.D."))) @result{} #t
(read-disable 'case-insensitive) ; Guile default behaviour (read-disable 'case-insensitive) ; Guile default behavior
(symbol->string 'flying-fish) @result{} "flying-fish" (symbol->string 'flying-fish) @result{} "flying-fish"
(symbol->string 'Martin) @result{} "Martin" (symbol->string 'Martin) @result{} "Martin"
@ -5708,7 +5713,7 @@ or a pair which has a list in its cdr.
@c FIXME::martin: What is a proper, what an improper list? @c FIXME::martin: What is a proper, what an improper list?
@c What is a circular list? @c What is a circular list?
@c FIXME::martin: Maybe steal some graphics from the Elisp reference @c FIXME::martin: Maybe steal some graphics from the Elisp reference
@c manual? @c manual?
@menu @menu
@ -5752,7 +5757,7 @@ up a list. An example will clear that up:
This example also shows that lists have to be quoted when written This example also shows that lists have to be quoted when written
(@pxref{Expression Syntax}), because they would otherwise be (@pxref{Expression Syntax}), because they would otherwise be
mistakingly taken as procedure applications (@pxref{Simple mistakenly taken as procedure applications (@pxref{Simple
Invocation}). Invocation}).
@ -5863,7 +5868,7 @@ Return the number of elements in list @var{lst}.
@deffn {Scheme Procedure} last-pair lst @deffn {Scheme Procedure} last-pair lst
@deffnx {C Function} scm_last_pair (lst) @deffnx {C Function} scm_last_pair (lst)
Return the last pair in @var{lst}, signalling an error if Return the last pair in @var{lst}, signaling an error if
@var{lst} is circular. @var{lst} is circular.
@end deffn @end deffn
@ -6333,7 +6338,7 @@ Copy the block of elements from vector @var{src} in the range
to the length of @var{src}. to the length of @var{src}.
It is an error for @var{dst} to have a length less than @var{at} + It is an error for @var{dst} to have a length less than @var{at} +
(@var{end} - @var{start}). (@var{end} - @var{start}).
The order in which elements are copied is unspecified, except that if the The order in which elements are copied is unspecified, except that if the
source and destination overlap, copying takes place as if the source is source and destination overlap, copying takes place as if the source is
@ -7285,11 +7290,11 @@ numeric vectors, bytevectors, bit vectors and ordinary vectors as one
dimensional arrays. dimensional arrays.
@menu @menu
* Array Syntax:: * Array Syntax::
* Array Procedures:: * Array Procedures::
* Shared Arrays:: * Shared Arrays::
* Arrays as arrays of arrays:: * Arrays as arrays of arrays::
* Accessing Arrays from C:: * Accessing Arrays from C::
@end menu @end menu
@node Array Syntax @node Array Syntax
@ -7333,7 +7338,7 @@ As a special case, an array of rank 0 is printed as
@code{#0<vectag>(<scalar>)}, where @code{<scalar>} is the result of @code{#0<vectag>(<scalar>)}, where @code{<scalar>} is the result of
printing the single element of the array. printing the single element of the array.
Thus, Thus,
@table @code @table @code
@item #(1 2 3) @item #(1 2 3)
@ -7840,16 +7845,16 @@ themselves arrays (`cells').
We speak of the first @math{n-k} dimensions of the array as the We speak of the first @math{n-k} dimensions of the array as the
@math{n-k}-`frame' of the array, while the last @math{k} dimensions are @math{n-k}-`frame' of the array, while the last @math{k} dimensions are
the dimensions of the @math{k}-`cells'. For example, a 3-array can be the dimensions of the @math{k}-`cells'. For example, a 3-array can be
seen as a 2-array of vectors (1-arrays) or as a 1-array of matrices seen as a 2-array of vectors (1-arrays) or as a 1-array of matrices
(2-arrays). In each case, the vectors or matrices are the 1-cells or (2-arrays). In each case, the vectors or matrices are the 1-cells or
2-cells of the array. This terminology originates in the J language. 2-cells of the array. This terminology originates in the J language.
@cindex array slice @cindex array slice
@cindex prefix slice @cindex prefix slice
The more vague concept of a `slice' refers to a subset of the array The more vague concept of a `slice' refers to a subset of the array
where some indices are fixed and others are left free. As a Guile data where some indices are fixed and others are left free. As a Guile data
object, a cell is the same as a `prefix slice' (the first @math{n-k} object, a cell is the same as a `prefix slice' (the first @math{n-k}
indices into the original array are fixed), except that a 0-cell is not indices into the original array are fixed), except that a 0-cell is not
a shared array of the original array, but a 0-slice (where all the a shared array of the original array, but a 0-slice (where all the
@ -7858,7 +7863,7 @@ indices into the original array are fixed) is.
@cindex enclosed array @cindex enclosed array
Before @w{version 2.0}, Guile had a feature called `enclosed arrays' to Before @w{version 2.0}, Guile had a feature called `enclosed arrays' to
create special `array of arrays' objects. The functions in this section create special `array of arrays' objects. The functions in this section
do not need special types; instead, the frame rank is stated in each do not need special types; instead, the frame rank is stated in each
function call, either implicitly or explicitly. function call, either implicitly or explicitly.
@ -7866,7 +7871,7 @@ function call, either implicitly or explicitly.
@deffnx {C Function} scm_array_cell_ref (array, idxlist) @deffnx {C Function} scm_array_cell_ref (array, idxlist)
If the length of @var{idxlist} equals the rank @math{n} of @var{array}, If the length of @var{idxlist} equals the rank @math{n} of @var{array},
return the element at @code{(idx @dots{})}, just like @code{(array-ref return the element at @code{(idx @dots{})}, just like @code{(array-ref
array idx @dots{})}. If, however, the length @math{k} of @var{idxlist} array idx @dots{})}. If, however, the length @math{k} of @var{idxlist}
is smaller than @math{n}, then return the @math{(n-k)}-cell of is smaller than @math{n}, then return the @math{(n-k)}-cell of
@var{array} given by @var{idxlist}, as a shared array. @var{array} given by @var{idxlist}, as a shared array.
@ -7896,7 +7901,7 @@ For example:
@deffnx {C Function} scm_array_slice (array, idxlist) @deffnx {C Function} scm_array_slice (array, idxlist)
Like @code{(array-cell-ref array idx @dots{})}, but return a 0-rank Like @code{(array-cell-ref array idx @dots{})}, but return a 0-rank
shared array into @var{ARRAY} if the length of @var{idxlist} matches the shared array into @var{ARRAY} if the length of @var{idxlist} matches the
rank of @var{array}. This can be useful when using @var{ARRAY} as a rank of @var{array}. This can be useful when using @var{ARRAY} as a
place to write to. place to write to.
Compare: Compare:
@ -9158,7 +9163,7 @@ scheme@@(guile-user)> (struct-ref $3 vtable-index-layout)
$6 = pwuhuhpwphuhuhpwpwpw $6 = pwuhuhpwphuhuhpwpwpw
scheme@@(guile-user)> (struct-ref $4 vtable-index-layout) scheme@@(guile-user)> (struct-ref $4 vtable-index-layout)
$7 = pwuhuhpwphuhuh $7 = pwuhuhpwphuhuh
scheme@@(guile-user)> standard-vtable-fields scheme@@(guile-user)> standard-vtable-fields
$8 = "pwuhuhpwphuhuh" $8 = "pwuhuhpwphuhuh"
scheme@@(guile-user)> (struct-ref $2 vtable-offset-user) scheme@@(guile-user)> (struct-ref $2 vtable-offset-user)
$9 = module $9 = module
@ -9228,7 +9233,7 @@ class fields.
(let* ((fields (compute-fields parent fields)) (let* ((fields (compute-fields parent fields))
(layout (compute-layout fields))) (layout (compute-layout fields)))
(make-struct/no-tail <class> (make-struct/no-tail <class>
layout layout
(lambda (x port) (lambda (x port)
(print-instance x port)) (print-instance x port))
name name
@ -9382,7 +9387,7 @@ procedures for manipulating them.
@subsubsection Alist Key Equality @subsubsection Alist Key Equality
All of Guile's dedicated association list procedures, apart from All of Guile's dedicated association list procedures, apart from
@code{acons}, come in three flavours, depending on the level of equality @code{acons}, come in three flavors, depending on the level of equality
that is required to decide whether an existing key in the association that is required to decide whether an existing key in the association
list is the same as the key that the procedure call uses to identify the list is the same as the key that the procedure call uses to identify the
required entry. required entry.

82
doc/ref/api-debug.texi
View file

@ -36,19 +36,19 @@ A Scheme stack always exists implicitly, and can be summoned into
concrete existence as a first-class Scheme value by the concrete existence as a first-class Scheme value by the
@code{make-stack} call, so that an introspective Scheme program -- such @code{make-stack} call, so that an introspective Scheme program -- such
as a debugger -- can present it in some way and allow the user to query as a debugger -- can present it in some way and allow the user to query
its details. The first thing to understand, therefore, is how Guile's its details. The first thing to understand, therefore, is how Guile's
function call convention creates the stack. function call convention creates the stack.
Broadly speaking, Guile represents all control flow on a stack. Calling Broadly speaking, Guile represents all control flow on a stack. Calling
a function involves pushing an empty frame on the stack, then evaluating a function involves pushing an empty frame on the stack, then evaluating
the procedure and its arguments, then fixing up the new frame so that it the procedure and its arguments, then fixing up the new frame so that it
points to the old one. Frames on the stack are thus linked together. A points to the old one. Frames on the stack are thus linked together. A
tail call is the same, except it reuses the existing frame instead of tail call is the same, except it reuses the existing frame instead of
pushing on a new one. pushing on a new one.
In this way, the only frames that are on the stack are ``active'' In this way, the only frames that are on the stack are ``active''
frames, frames which need to do some work before the computation is frames, frames which need to do some work before the computation is
complete. On the other hand, a function that has tail-called another complete. On the other hand, a function that has tail-called another
function will not be on the stack, as it has no work left to do. function will not be on the stack, as it has no work left to do.
Therefore, when an error occurs in a running program, or the program Therefore, when an error occurs in a running program, or the program
@ -83,7 +83,7 @@ Use @code{start-stack} to limit the stack extent captured by future
@deffn {Scheme Procedure} make-stack obj arg @dots{} @deffn {Scheme Procedure} make-stack obj arg @dots{}
@deffnx {C Function} scm_make_stack (obj, args) @deffnx {C Function} scm_make_stack (obj, args)
Create a new stack. If @var{obj} is @code{#t}, the current Create a new stack. If @var{obj} is @code{#t}, the current
evaluation stack is used for creating the stack frames, evaluation stack is used for creating the stack frames,
otherwise the frames are taken from @var{obj} (which must be otherwise the frames are taken from @var{obj} (which must be
a continuation or a frame object). a continuation or a frame object).
@ -239,7 +239,7 @@ output.
Additionally, the @code{(system vm frame)} module defines a number of Additionally, the @code{(system vm frame)} module defines a number of
higher-level introspective procedures, for example to retrieve the names higher-level introspective procedures, for example to retrieve the names
of local variables, and the source location to correspond to a of local variables, and the source location to correspond to a
frame. See its source code for more details. frame. See its source code for more details.
@node Source Properties @node Source Properties
@ -341,7 +341,7 @@ with the new pair.
@subsection Programmatic Error Handling @subsection Programmatic Error Handling
For better or for worse, all programs have bugs, and dealing with bugs For better or for worse, all programs have bugs, and dealing with bugs
is part of programming. This section deals with that class of bugs that is part of programming. This section deals with that class of bugs that
causes an exception to be raised -- from your own code, from within a causes an exception to be raised -- from your own code, from within a
library, or from Guile itself. library, or from Guile itself.
@ -733,7 +733,7 @@ warn-deprecated no Warn when deprecated features are used.
@end smallexample @end smallexample
The boolean options may be toggled with @code{debug-enable} and The boolean options may be toggled with @code{debug-enable} and
@code{debug-disable}. The non-boolean options must be set using @code{debug-disable}. The non-boolean options must be set using
@code{debug-set!}. @code{debug-set!}.
@deffn {Scheme Procedure} debug-enable option-name @deffn {Scheme Procedure} debug-enable option-name
@ -766,16 +766,16 @@ it chooses for examining the evaluation stack as program execution
proceeds, and for suspending execution to be resumed later. proceeds, and for suspending execution to be resumed later.
VM hooks are very low-level, though, and so Guile also has a library of VM hooks are very low-level, though, and so Guile also has a library of
higher-level @dfn{traps} on top of the VM hooks. A trap is an execution higher-level @dfn{traps} on top of the VM hooks. A trap is an execution
condition that, when fulfilled, will fire a handler. For example, Guile condition that, when fulfilled, will fire a handler. For example, Guile
defines a trap that fires when control reaches a certain source defines a trap that fires when control reaches a certain source
location. location.
Finally, Guile also defines a third level of abstractions: per-thread Finally, Guile also defines a third level of abstractions: per-thread
@dfn{trap states}. A trap state exists to give names to traps, and to @dfn{trap states}. A trap state exists to give names to traps, and to
hold on to the set of traps so that they can be enabled, disabled, or hold on to the set of traps so that they can be enabled, disabled, or
removed. The trap state infrastructure defines the most useful removed. The trap state infrastructure defines the most useful
abstractions for most cases. For example, Guile's REPL uses trap state abstractions for most cases. For example, Guile's REPL uses trap state
functions to set breakpoints and tracepoints. functions to set breakpoints and tracepoints.
The following subsections describe all this in detail, for both the The following subsections describe all this in detail, for both the
@ -789,7 +789,7 @@ understanding how the interface hangs together.
* Low-Level Traps:: The various kinds of low-level traps. * Low-Level Traps:: The various kinds of low-level traps.
* Tracing Traps:: Traps to trace procedure calls and returns. * Tracing Traps:: Traps to trace procedure calls and returns.
* Trap States:: One state (per thread) to bind them. * Trap States:: One state (per thread) to bind them.
* High-Level Traps:: The highest-level trap interface. Use this. * High-Level Traps:: The highest-level trap interface. Use this.
@end menu @end menu
@ -800,8 +800,8 @@ Everything that runs in Guile runs on its virtual machine, a C program
that defines a number of operations that Scheme programs can that defines a number of operations that Scheme programs can
perform. perform.
Note that there are multiple VM ``engines'' for Guile. Only some of them Note that there are multiple VM ``engines'' for Guile. Only some of them
have support for hooks compiled in. Normally the deal is that you get have support for hooks compiled in. Normally the deal is that you get
hooks if you are running interactively, and otherwise they are disabled, hooks if you are running interactively, and otherwise they are disabled,
as they do have some overhead (about 10 or 20 percent). as they do have some overhead (about 10 or 20 percent).
@ -821,7 +821,7 @@ does a terrible thing: it allocates the frames on the C stack instead of
the garbage-collected heap. the garbage-collected heap.
The upshot here is that the frames are only valid within the dynamic The upshot here is that the frames are only valid within the dynamic
extent of the call to the hook. If a hook procedure keeps a reference to extent of the call to the hook. If a hook procedure keeps a reference to
the frame outside the extent of the hook, bad things will happen. the frame outside the extent of the hook, bad things will happen.
The interface to hooks is provided by the @code{(system vm vm)} module: The interface to hooks is provided by the @code{(system vm vm)} module:
@ -875,10 +875,10 @@ Remove @var{f} from the corresponding VM hook for the current thread.
@end deffn @end deffn
@cindex VM trace level @cindex VM trace level
These hooks do impose a performance penalty, if they are on. Obviously, These hooks do impose a performance penalty, if they are on. Obviously,
the @code{vm-next-hook} has quite an impact, performance-wise. Therefore the @code{vm-next-hook} has quite an impact, performance-wise. Therefore
Guile exposes a single, heavy-handed knob to turn hooks on or off, the Guile exposes a single, heavy-handed knob to turn hooks on or off, the
@dfn{VM trace level}. If the trace level is positive, hooks run; @dfn{VM trace level}. If the trace level is positive, hooks run;
otherwise they don't. otherwise they don't.
For convenience, when the VM fires a hook, it does so with the trap For convenience, when the VM fires a hook, it does so with the trap
@ -887,8 +887,8 @@ handling a hook. The trace level is restored to whatever it was once the hook
procedure finishes. procedure finishes.
@deffn {Scheme Procedure} vm-trace-level @deffn {Scheme Procedure} vm-trace-level
Retrieve the ``trace level'' of the VM. If positive, the trace hooks Retrieve the ``trace level'' of the VM. If positive, the trace hooks
associated with @var{vm} will be run. The initial trace level is 0. associated with @var{vm} will be run. The initial trace level is 0.
@end deffn @end deffn
@deffn {Scheme Procedure} set-vm-trace-level! level @deffn {Scheme Procedure} set-vm-trace-level! level
@ -907,7 +907,7 @@ correspond to what users want to do.
For example, if a user wants to break when and if control reaches a For example, if a user wants to break when and if control reaches a
certain source location, how do you do it? If you install a ``next'' certain source location, how do you do it? If you install a ``next''
hook, you get unacceptable overhead for the execution of the entire hook, you get unacceptable overhead for the execution of the entire
program. It would be possible to install an ``apply'' hook, then if the program. It would be possible to install an ``apply'' hook, then if the
procedure encompasses those source locations, install a ``next'' hook, procedure encompasses those source locations, install a ``next'' hook,
but already you're talking about one concept that might be implemented but already you're talking about one concept that might be implemented
by a varying number of lower-level concepts. by a varying number of lower-level concepts.
@ -916,27 +916,27 @@ It's best to be clear about things and define one abstraction for all
such conditions: the @dfn{trap}. such conditions: the @dfn{trap}.
Considering the myriad capabilities offered by the hooks though, there Considering the myriad capabilities offered by the hooks though, there
is only a minimum of functionality shared by all traps. Guile's current is only a minimum of functionality shared by all traps. Guile's current
take is to reduce this to the absolute minimum, and have the only take is to reduce this to the absolute minimum, and have the only
standard interface of a trap be ``turn yourself on'' or ``turn yourself standard interface of a trap be ``turn yourself on'' or ``turn yourself
off''. off''.
This interface sounds a bit strange, but it is useful to procedurally This interface sounds a bit strange, but it is useful to procedurally
compose higher-level traps from lower-level building blocks. For compose higher-level traps from lower-level building blocks. For
example, Guile defines a trap that calls one handler when control enters example, Guile defines a trap that calls one handler when control enters
a procedure, and another when control leaves the procedure. Given that a procedure, and another when control leaves the procedure. Given that
trap, one can define a trap that adds to the next-hook only when within trap, one can define a trap that adds to the next-hook only when within
a given procedure. Building further, one can define a trap that fires a given procedure. Building further, one can define a trap that fires
when control reaches particular instructions within a procedure. when control reaches particular instructions within a procedure.
Or of course you can stop at any of these intermediate levels. For Or of course you can stop at any of these intermediate levels. For
example, one might only be interested in calls to a given procedure. But example, one might only be interested in calls to a given procedure. But
the point is that a simple enable/disable interface is all the the point is that a simple enable/disable interface is all the
commonality that exists between the various kinds of traps, and commonality that exists between the various kinds of traps, and
furthermore that such an interface serves to allow ``higher-level'' furthermore that such an interface serves to allow ``higher-level''
traps to be composed from more primitive ones. traps to be composed from more primitive ones.
Specifically, a trap, in Guile, is a procedure. When a trap is created, Specifically, a trap, in Guile, is a procedure. When a trap is created,
by convention the trap is enabled; therefore, the procedure that is the by convention the trap is enabled; therefore, the procedure that is the
trap will, when called, disable the trap, and return a procedure that trap will, when called, disable the trap, and return a procedure that
will enable the trap, and so on. will enable the trap, and so on.
@ -945,10 +945,10 @@ Trap procedures take one optional argument: the current frame. (A trap
may want to add to different sets of hooks depending on the frame that may want to add to different sets of hooks depending on the frame that
is current at enable-time.) is current at enable-time.)
If this all sounds very complicated, it's because it is. Some of it is If this all sounds very complicated, it's because it is. Some of it is
essential, but probably most of it is not. The advantage of using this essential, but probably most of it is not. The advantage of using this
minimal interface is that composability is more lexically apparent than minimal interface is that composability is more lexically apparent than
when, for example, using a stateful interface based on GOOPS. But when, for example, using a stateful interface based on GOOPS. But
perhaps this reflects the cognitive limitations of the programmer who perhaps this reflects the cognitive limitations of the programmer who
made the current interface more than anything else. made the current interface more than anything else.
@ -958,20 +958,20 @@ made the current interface more than anything else.
To summarize the last sections, traps are enabled or disabled, and when To summarize the last sections, traps are enabled or disabled, and when
they are enabled, they add to various VM hooks. they are enabled, they add to various VM hooks.
Note, however, that @emph{traps do not increase the VM trace level}. So Note, however, that @emph{traps do not increase the VM trace level}. So
if you create a trap, it will be enabled, but unless something else if you create a trap, it will be enabled, but unless something else
increases the VM's trace level (@pxref{VM Hooks}), the trap will not increases the VM's trace level (@pxref{VM Hooks}), the trap will not
fire. It turns out that getting the VM trace level right is tricky fire. It turns out that getting the VM trace level right is tricky
without a global view of what traps are enabled. @xref{Trap States}, without a global view of what traps are enabled. @xref{Trap States},
for Guile's answer to this problem. for Guile's answer to this problem.
Traps are created by calling procedures. Most of these procedures share Traps are created by calling procedures. Most of these procedures share
a set of common keyword arguments, so rather than document them a set of common keyword arguments, so rather than document them
separately, we discuss them all together here: separately, we discuss them all together here:
@table @code @table @code
@item #:vm @item #:vm
The VM to instrument. Defaults to the current thread's VM. The VM to instrument. Defaults to the current thread's VM.
@item #:current-frame @item #:current-frame
For traps that enable more hooks depending on their dynamic context, For traps that enable more hooks depending on their dynamic context,
this argument gives the current frame that the trap is running in. this argument gives the current frame that the trap is running in.
@ -1028,7 +1028,7 @@ A trap that calls @var{next-handler} for every instruction executed in
handler [#:current-frame] [#:vm] handler [#:current-frame] [#:vm]
A trap that calls @var{handler} when execution enters a range of A trap that calls @var{handler} when execution enters a range of
instructions in @var{proc}. @var{range} is a simple of pairs, instructions in @var{proc}. @var{range} is a simple of pairs,
@code{((@var{start} . @var{end}) ...)}. The @var{start} addresses are @code{((@var{start} . @var{end}) ...)}. The @var{start} addresses are
inclusive, and @var{end} addresses are exclusive. inclusive, and @var{end} addresses are exclusive.
@end deffn @end deffn
@ -1146,13 +1146,13 @@ options:
@table @code @table @code
@item #:width @item #:width
The maximum width of trace output. Trace printouts will try not to The maximum width of trace output. Trace printouts will try not to
exceed this column, but for highly nested procedure calls, it may be exceed this column, but for highly nested procedure calls, it may be
unavoidable. Defaults to 80. unavoidable. Defaults to 80.
@item #:vm @item #:vm
The VM on which to add the traps. Defaults to the current thread's VM. The VM on which to add the traps. Defaults to the current thread's VM.
@item #:prefix @item #:prefix
A string to print out before each trace line. As seen above in the A string to print out before each trace line. As seen above in the
examples, defaults to @code{"trace: "}. examples, defaults to @code{"trace: "}.
@end table @end table

2
doc/ref/api-deprecated.texi
View file

@ -12,7 +12,7 @@ Guile's @dfn{deprecation} is a mechanism that can help you cope with
this. this.
When you use a feature that is deprecated, you will likely get a warning When you use a feature that is deprecated, you will likely get a warning
message at run-time. Also, if you have a new enough toolchain, using a message at run-time. Also, if you have a new enough toolchain, using a
deprecated function from @code{libguile} will cause a link-time warning. deprecated function from @code{libguile} will cause a link-time warning.
The primary source for information about just what interfaces are The primary source for information about just what interfaces are

30
doc/ref/api-evaluation.texi
View file

@ -59,7 +59,7 @@ x @result{} 123
@end example @end example
@item (@var{proc} @var{args}@dots{}) @item (@var{proc} @var{args}@dots{})
A parenthesised expression is a function call. @var{proc} and each A parenthesized expression is a function call. @var{proc} and each
argument are evaluated, then the function (which @var{proc} evaluated argument are evaluated, then the function (which @var{proc} evaluated
to) is called with those arguments. to) is called with those arguments.
@ -73,7 +73,7 @@ unspecified, so be careful when using expressions with side effects.
((get-some-proc) 1 2 3) @result{} 1 ((get-some-proc) 1 2 3) @result{} 1
@end example @end example
The same sort of parenthesised form is used for a macro invocation, The same sort of parenthesized form is used for a macro invocation,
but in that case the arguments are not evaluated. See the but in that case the arguments are not evaluated. See the
descriptions of macros for more on this (@pxref{Macros}, and descriptions of macros for more on this (@pxref{Macros}, and
@pxref{Syntax Rules}). @pxref{Syntax Rules}).
@ -318,7 +318,7 @@ the current input port if @var{port} is not specified.
Any whitespace before the next token is discarded. Any whitespace before the next token is discarded.
@end deffn @end deffn
The behaviour of Guile's Scheme reader can be modified by manipulating The behavior of Guile's Scheme reader can be modified by manipulating
its read options. its read options.
@cindex options - read @cindex options - read
@ -359,7 +359,7 @@ unsets @code{square-brackets} on the port (@pxref{SRFI-105}). There is
currently no other way to access or set the per-port read options. currently no other way to access or set the per-port read options.
The boolean options may be toggled with @code{read-enable} and The boolean options may be toggled with @code{read-enable} and
@code{read-disable}. The non-boolean @code{keywords} option must be set @code{read-disable}. The non-boolean @code{keywords} option must be set
using @code{read-set!}. using @code{read-set!}.
@deffn {Scheme Procedure} read-enable option-name @deffn {Scheme Procedure} read-enable option-name
@ -392,7 +392,7 @@ For more information on the @code{r7rs-symbols} option, see
When something goes wrong with a Scheme program, the user will want to When something goes wrong with a Scheme program, the user will want to
know how to fix it. This starts with identifying where the error know how to fix it. This starts with identifying where the error
occured: we want to associate a source location with each component part occurred: we want to associate a source location with each component part
of source code, and propagate that source location information through of source code, and propagate that source location information through
to the compiler or interpreter. to the compiler or interpreter.
@ -441,7 +441,7 @@ information.
@node Scheme Write @node Scheme Write
@subsection Writing Scheme Values @subsection Writing Scheme Values
Any scheme value may be written to a port. Not all values may be read Any scheme value may be written to a port. Not all values may be read
back in (@pxref{Scheme Read}), however. back in (@pxref{Scheme Read}), however.
@rnindex write @rnindex write
@ -475,7 +475,7 @@ affect the behavior of the Scheme printer.
@deffn {Scheme Procedure} print-options [setting] @deffn {Scheme Procedure} print-options [setting]
Display the current settings of the read options. If @var{setting} is Display the current settings of the read options. If @var{setting} is
omitted, only a short form of the current read options is omitted, only a short form of the current read options is
printed. Otherwise if @var{setting} is the symbol @code{help}, a printed. Otherwise if @var{setting} is the symbol @code{help}, a
complete options description is displayed. complete options description is displayed.
@end deffn @end deffn
@ -1044,7 +1044,7 @@ manipulation.
@deffn {Scheme Procedure} parse-path path [tail] @deffn {Scheme Procedure} parse-path path [tail]
@deffnx {C Function} scm_parse_path (path, tail) @deffnx {C Function} scm_parse_path (path, tail)
Parse @var{path}, which is expected to be a colon-separated string, into Parse @var{path}, which is expected to be a colon-separated string, into
a list and return the resulting list with @var{tail} appended. If a list and return the resulting list with @var{tail} appended. If
@var{path} is @code{#f}, @var{tail} is returned. @var{path} is @code{#f}, @var{tail} is returned.
@end deffn @end deffn
@ -1060,7 +1060,7 @@ returned.
@deffn {Scheme Procedure} search-path path filename [extensions [require-exts?]] @deffn {Scheme Procedure} search-path path filename [extensions [require-exts?]]
@deffnx {C Function} scm_search_path (path, filename, rest) @deffnx {C Function} scm_search_path (path, filename, rest)
Search @var{path} for a directory containing a file named Search @var{path} for a directory containing a file named
@var{filename}. The file must be readable, and not a directory. If we @var{filename}. The file must be readable, and not a directory. If we
find one, return its full filename; otherwise, return @code{#f}. If find one, return its full filename; otherwise, return @code{#f}. If
@var{filename} is absolute, return it unchanged. If given, @var{filename} is absolute, return it unchanged. If given,
@var{extensions} is a list of strings; for each directory in @var{path}, @var{extensions} is a list of strings; for each directory in @var{path},
@ -1136,7 +1136,7 @@ accomplish this in three steps. First, the character encoding of the
port should be set to ISO-8859-1 using @code{set-port-encoding!}. port should be set to ISO-8859-1 using @code{set-port-encoding!}.
Then, the procedure @code{file-encoding}, described below, is used to Then, the procedure @code{file-encoding}, described below, is used to
scan for a coding declaration when reading from the port. As a side scan for a coding declaration when reading from the port. As a side
effect, it rewinds the port after its scan is complete. After that, effect, it rewinds the port after its scan is complete. After that,
the port's character encoding should be set to the encoding returned the port's character encoding should be set to the encoding returned
by @code{file-encoding}, if any, again by using by @code{file-encoding}, if any, again by using
@code{set-port-encoding!}. Then the code can be read as normal. @code{set-port-encoding!}. Then the code can be read as normal.
@ -1339,14 +1339,14 @@ and space used by a piece of code.
@deffn {Scheme Procedure} call-with-time-limit limit thunk limit-reached @deffn {Scheme Procedure} call-with-time-limit limit thunk limit-reached
Call @var{thunk}, but cancel it if @var{limit} seconds of wall-clock Call @var{thunk}, but cancel it if @var{limit} seconds of wall-clock
time have elapsed. If the computation is cancelled, call time have elapsed. If the computation is canceled, call
@var{limit-reached} in tail position. @var{thunk} must not disable @var{limit-reached} in tail position. @var{thunk} must not disable
interrupts or prevent an abort via a @code{dynamic-wind} unwind handler. interrupts or prevent an abort via a @code{dynamic-wind} unwind handler.
@end deffn @end deffn
@deffn {Scheme Procedure} call-with-allocation-limit limit thunk limit-reached @deffn {Scheme Procedure} call-with-allocation-limit limit thunk limit-reached
Call @var{thunk}, but cancel it if @var{limit} bytes have been Call @var{thunk}, but cancel it if @var{limit} bytes have been
allocated. If the computation is cancelled, call @var{limit-reached} in allocated. If the computation is canceled, call @var{limit-reached} in
tail position. @var{thunk} must not disable interrupts or prevent an tail position. @var{thunk} must not disable interrupts or prevent an
abort via a @code{dynamic-wind} unwind handler. abort via a @code{dynamic-wind} unwind handler.
@ -1407,7 +1407,7 @@ defaults to @code{all-pure-bindings}. This is the core of the
sandbox: creating a scope for the expression that is @dfn{safe}. sandbox: creating a scope for the expression that is @dfn{safe}.
A safe sandbox module has two characteristics. Firstly, it will not A safe sandbox module has two characteristics. Firstly, it will not
allow the expression being evaluated to avoid being cancelled due to allow the expression being evaluated to avoid being canceled due to
time or allocation limits. This ensures that the expression terminates time or allocation limits. This ensures that the expression terminates
in a timely fashion. in a timely fashion.
@ -1604,7 +1604,7 @@ uses them internally to implement the @option{--listen} switch,
@deffn {Scheme Procedure} make-tcp-server-socket [#:host=#f] @ @deffn {Scheme Procedure} make-tcp-server-socket [#:host=#f] @
[#:addr] [#:port=37146] [#:addr] [#:port=37146]
Return a stream socket bound to a given address @var{addr} and port Return a stream socket bound to a given address @var{addr} and port
number @var{port}. If the @var{host} is given, and @var{addr} is not, number @var{port}. If the @var{host} is given, and @var{addr} is not,
then the @var{host} string is converted to an address. If neither is then the @var{host} string is converted to an address. If neither is
given, we use the loopback address. given, we use the loopback address.
@end deffn @end deffn
@ -1628,7 +1628,7 @@ with no arguments.
Closes the connection on all running server sockets. Closes the connection on all running server sockets.
Please note that in the current implementation, the REPL threads are Please note that in the current implementation, the REPL threads are
cancelled without unwinding their stacks. If any of them are holding canceled without unwinding their stacks. If any of them are holding
mutexes or are within a critical section, the results are unspecified. mutexes or are within a critical section, the results are unspecified.
@end deffn @end deffn

18
doc/ref/api-foreign.texi
View file

@ -108,7 +108,7 @@ Unless @var{library} denotes an absolute file name or otherwise contains
a directory separator (@code{/}, and also @code{\} on Windows), Guile a directory separator (@code{/}, and also @code{\} on Windows), Guile
will search for the library in the directories listed in will search for the library in the directories listed in
@var{search-paths}. The default search path has three components, which @var{search-paths}. The default search path has three components, which
can all be overriden by colon-delimited (semicolon on Windows) can all be overridden by colon-delimited (semicolon on Windows)
environment variables: environment variables:
@table @env @table @env
@ -146,7 +146,7 @@ We don't use libltdl now, essentially for flexibility and
error-reporting reasons. But, to keep this old use-case working, if error-reporting reasons. But, to keep this old use-case working, if
@var{search-ltdl-library-path?} is true, we add each entry of @var{search-ltdl-library-path?} is true, we add each entry of
@code{LTDL_LIBRARY_PATH} to the default extensions load path, @code{LTDL_LIBRARY_PATH} to the default extensions load path,
additionally adding the @file{.libs} subdirextories for each entry, in additionally adding the @file{.libs} subdirectories for each entry, in
case there are @file{.so} files there instead of alongside the case there are @file{.so} files there instead of alongside the
@file{.la} files. @file{.la} files.
@item GUILE_SYSTEM_EXTENSIONS_PATH @item GUILE_SYSTEM_EXTENSIONS_PATH
@ -305,7 +305,7 @@ Note that the new primitives that the extension adds to Guile with
@code{scm_c_define_gsubr} (@pxref{Primitive Procedures}) or with any of @code{scm_c_define_gsubr} (@pxref{Primitive Procedures}) or with any of
the other mechanisms are placed into the module that is current when the the other mechanisms are placed into the module that is current when the
@code{scm_c_define_gsubr} is executed, so to be clear about what goes @code{scm_c_define_gsubr} is executed, so to be clear about what goes
vwhere it's best to include the @code{load-extension} in a module, as where it's best to include the @code{load-extension} in a module, as
above. Alternately, the C code can use @code{scm_c_define_module} to above. Alternately, the C code can use @code{scm_c_define_module} to
specify which module is being created: specify which module is being created:
@ -326,7 +326,7 @@ init_math_bessel ()
And yet... if what we want is just the @code{j0} function, it seems like And yet... if what we want is just the @code{j0} function, it seems like
a lot of ceremony to have to compile a Guile-specific wrapper library a lot of ceremony to have to compile a Guile-specific wrapper library
complete with an initialization function and wraper module to allow complete with an initialization function and wrapper module to allow
Guile users to call it. There is another way, but to get there, we have Guile users to call it. There is another way, but to get there, we have
to talk about function pointers and function types first. @xref{Foreign to talk about function pointers and function types first. @xref{Foreign
Functions}, to skip to the good parts. Functions}, to skip to the good parts.
@ -427,7 +427,7 @@ will try to use ``pointer object'' to refer to Scheme objects, and
Create a pointer object from a pointer value. Create a pointer object from a pointer value.
If @var{finalizer} is non-null, Guile arranges to call it on the pointer If @var{finalizer} is non-null, Guile arranges to call it on the pointer
value at some point after the pointer object becomes collectable. value at some point after the pointer object becomes collectible.
@end deftypefn @end deftypefn
@deftypefn {C Function} void* scm_to_pointer (SCM obj) @deftypefn {C Function} void* scm_to_pointer (SCM obj)
@ -469,7 +469,7 @@ C types.
@defvrx {Scheme Variable} complex-float @defvrx {Scheme Variable} complex-float
These values represent the C numeric types of the specified sizes and These values represent the C numeric types of the specified sizes and
signednesses. @code{complex-float} and @code{complex-double} stand for signednesses. @code{complex-float} and @code{complex-double} stand for
C99 @code{float _Complex} and @code{double _Complex} respecively. C99 @code{float _Complex} and @code{double _Complex} respectively.
@end defvr @end defvr
In addition there are some convenience bindings for indicating types of In addition there are some convenience bindings for indicating types of
@ -533,7 +533,7 @@ return two values, with @code{errno} as the second value.
@end deffn @end deffn
Finally, in @code{(system foreign-library)} there is a convenient Finally, in @code{(system foreign-library)} there is a convenient
wrapper function, joining together @code{foreign-libary-pointer} and wrapper function, joining together @code{foreign-library-pointer} and
@code{procedure->pointer}: @code{procedure->pointer}:
@deffn {Scheme Procedure} foreign-library-function lib name @ @deffn {Scheme Procedure} foreign-library-function lib name @
@ -567,7 +567,7 @@ bessel)}:
#:arg-types (list double))) #:arg-types (list double)))
@end example @end example
That's it! No C at all. That's it! No C at all.
Before going on to more detailed examples, the next two sections discuss Before going on to more detailed examples, the next two sections discuss
how to deal with data that is more complex than, say, @code{int8}. how to deal with data that is more complex than, say, @code{int8}.
@ -704,7 +704,7 @@ In this example, @code{grab-bottle} is guaranteed to return a genuine
@end deffn @end deffn
As another example, currently Guile has a variable, @code{scm_numptob}, As another example, currently Guile has a variable, @code{scm_numptob},
as part of its API. It is declared as a C @code{long}. So, to read its as part of its API. It is declared as a C @code{long}. So, to read its
value, we can do: value, we can do:
@example @example

12
doc/ref/api-i18n.texi
View file

@ -482,7 +482,7 @@ message strings (@pxref{Introduction,,, gettext, GNU @code{gettext}
utilities}). utilities}).
Messages are collected in domains, so different libraries and programs Messages are collected in domains, so different libraries and programs
maintain different message catalogues. The @var{domain} parameter in maintain different message catalogs. The @var{domain} parameter in
the functions below is a string (it becomes part of the message the functions below is a string (it becomes part of the message
catalog filename). catalog filename).
@ -500,7 +500,7 @@ below. @var{category} is optional and defaults to @code{LC_MESSAGES}
Normal usage is for @var{msg} to be a literal string. Normal usage is for @var{msg} to be a literal string.
@command{xgettext} can extract those from the source to form a message @command{xgettext} can extract those from the source to form a message
catalogue ready for translators (@pxref{xgettext Invocation,, Invoking catalog ready for translators (@pxref{xgettext Invocation,, Invoking
the @command{xgettext} Program, gettext, GNU @code{gettext} the @command{xgettext} Program, gettext, GNU @code{gettext}
utilities}). utilities}).
@ -539,12 +539,12 @@ with a plural form chosen appropriately for the number @var{n}.
@var{msg} is the singular form, and @var{msgplural} the plural. When @var{msg} is the singular form, and @var{msgplural} the plural. When
no translation is available, @var{msg} is used if @math{@var{n} = 1}, no translation is available, @var{msg} is used if @math{@var{n} = 1},
or @var{msgplural} otherwise. When translated, the message catalogue or @var{msgplural} otherwise. When translated, the message catalog
can have a different rule, and can have more than two possible forms. can have a different rule, and can have more than two possible forms.
As per @code{gettext} above, normal usage is for @var{msg} and As per @code{gettext} above, normal usage is for @var{msg} and
@var{msgplural} to be literal strings, since @command{xgettext} can @var{msgplural} to be literal strings, since @command{xgettext} can
extract them from the source to build a message catalogue. For extract them from the source to build a message catalog. For
example, example,
@example @example
@ -593,7 +593,7 @@ For example,
When using Autoconf/Automake, an application should arrange for the When using Autoconf/Automake, an application should arrange for the
configured @code{localedir} to get into the program (by substituting, configured @code{localedir} to get into the program (by substituting,
or by generating a config file) and set that for its domain. This or by generating a config file) and set that for its domain. This
ensures the catalogue can be found even when installed in a ensures the catalog can be found even when installed in a
non-standard location. non-standard location.
@end deffn @end deffn
@ -622,7 +622,7 @@ without any recoding. For that reason source message strings are best
as plain ASCII. as plain ASCII.
Currently Guile has no understanding of multi-byte characters, and Currently Guile has no understanding of multi-byte characters, and
string functions won't recognise character boundaries in multi-byte string functions won't recognize character boundaries in multi-byte
strings. An application will at least be able to pass such strings strings. An application will at least be able to pass such strings
through to some output though. Perhaps this will change in the through to some output though. Perhaps this will change in the
future. future.

49
doc/ref/api-io.texi
View file

@ -18,7 +18,7 @@
* Line/Delimited:: Read and write lines or delimited text. * Line/Delimited:: Read and write lines or delimited text.
* Default Ports:: Defaults for input, output and errors. * Default Ports:: Defaults for input, output and errors.
* Port Types:: Types of port and how to make them. * Port Types:: Types of port and how to make them.
* Venerable Port Interfaces:: Procedures from the last millenium. * Venerable Port Interfaces:: Procedures from the last millennium.
* Using Ports from C:: Nice interfaces for C. * Using Ports from C:: Nice interfaces for C.
* Non-Blocking I/O:: How Guile deals with EWOULDBLOCK. * Non-Blocking I/O:: How Guile deals with EWOULDBLOCK.
* BOM Handling:: Handling of Unicode byte order marks. * BOM Handling:: Handling of Unicode byte order marks.
@ -89,6 +89,7 @@ on interfaces to control port buffering.
@deffn {Scheme Procedure} port? x @deffn {Scheme Procedure} port? x
@deffnx {C Function} scm_port_p (x) @deffnx {C Function} scm_port_p (x)
Return a boolean indicating whether @var{x} is a port. Return a boolean indicating whether @var{x} is a port.
Equivalent to @code{(or (input-port? @var{x}) (output-port? @var{x}))}.
@end deffn @end deffn
@rnindex input-port? @rnindex input-port?
@ -511,7 +512,7 @@ or until an end of file is reached.
If a complete character is available before the next end of file, If a complete character is available before the next end of file,
@code{get-char} returns that character and updates the input port to @code{get-char} returns that character and updates the input port to
point past the character. If an end of file is reached before any 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. character is read, @code{get-char} returns the end-of-file object.
@end deffn @end deffn
@ -548,10 +549,10 @@ integer, representing the number of characters to be read.
If @var{count} characters are available before end of file, If @var{count} characters are available before end of file,
@code{get-string-n} returns a string consisting of those @var{count} @code{get-string-n} returns a string consisting of those @var{count}
characters. If fewer characters are available before an end of file, but characters. If fewer characters are available before an end of file, but
one or more characters can be read, @code{get-string-n} returns a string one or more characters can be read, @code{get-string-n} returns a string
containing those characters. In either case, the input port is updated containing those characters. In either case, the input port is updated
to point just past the characters read. If no characters can be read 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. before an end of file, the end-of-file object is returned.
@end deffn @end deffn
@ -564,10 +565,10 @@ least $@var{start} + @var{count}$ characters.
If @var{count} characters are available before an end of file, they are If @var{count} characters are available before an end of file, they are
written into @var{string} starting at index @var{start}, and @var{count} written into @var{string} starting at index @var{start}, and @var{count}
is returned. If fewer characters are available before an end of file, is returned. If fewer characters are available before an end of file,
but one or more can be read, those characters are written into but one or more can be read, those characters are written into
@var{string} starting at index @var{start} and the number of characters @var{string} starting at index @var{start} and the number of characters
actually read is returned as an exact integer object. If no characters actually read is returned as an exact integer object. If no characters
can be read before an end of file, the end-of-file object is returned. can be read before an end of file, the end-of-file object is returned.
@end deffn @end deffn
@ -576,7 +577,7 @@ Reads from @var{input-port} until an end of file, decoding characters in
the same manner as @code{get-string-n} and @code{get-string-n!}. the same manner as @code{get-string-n} and @code{get-string-n!}.
If characters are available before the end of file, a string containing If characters are available before the end of file, a string containing
all the characters decoded from that data are returned. If no character all the characters decoded from that data are returned. If no character
precedes the end of file, the end-of-file object is returned. precedes the end of file, the end-of-file object is returned.
@end deffn @end deffn
@ -587,10 +588,10 @@ character or end of file, decoding characters in the same manner as
If a linefeed character is read, a string containing all of the text up If a linefeed character is read, a string containing all of the text up
to (but not including) the linefeed character is returned, and the port to (but not including) the linefeed character is returned, and the port
is updated to point just past the linefeed character. If an end of file is updated to point just past the linefeed character. If an end of file
is encountered before any linefeed character is read, but some is encountered before any linefeed character is read, but some
characters have been read and decoded as characters, a string containing characters have been read and decoded as characters, a string containing
those characters is returned. If an end of file is encountered before those characters is returned. If an end of file is encountered before
any characters are read, the end-of-file object is returned. any characters are read, the end-of-file object is returned.
@end deffn @end deffn
@ -598,7 +599,7 @@ Finally, there are just two core procedures to write characters to a
port. port.
@deffn {Scheme Procedure} put-char port char @deffn {Scheme Procedure} put-char port char
Writes @var{char} to the port. The @code{put-char} procedure returns Writes @var{char} to the port. The @code{put-char} procedure returns
an unspecified value. an unspecified value.
@end deffn @end deffn
@ -633,7 +634,7 @@ Return the current column number or line number of @var{port}.
@end deffn @end deffn
Port lines and positions are represented as 0-origin integers, which is Port lines and positions are represented as 0-origin integers, which is
to say that the the first character of the first line is line 0, column to say that the first character of the first line is line 0, column
0. However, when you display a line number, for example in an error 0. However, when you display a line number, for example in an error
message, we recommend you add 1 to get 1-origin integers. This is message, we recommend you add 1 to get 1-origin integers. This is
because lines numbers traditionally start with 1, and that is what because lines numbers traditionally start with 1, and that is what
@ -754,7 +755,7 @@ line-buffered ports, respectively. @xref{File Ports}, for more.
Any buffered output data will be written out when the port is closed. Any buffered output data will be written out when the port is closed.
To make sure to flush it at specific points in your program, use To make sure to flush it at specific points in your program, use
@code{force-otput}. @code{force-output}.
@findex fflush @findex fflush
@deffn {Scheme Procedure} force-output [port] @deffn {Scheme Procedure} force-output [port]
@ -996,15 +997,15 @@ Return the current input port. This is the default port used
by many input procedures. by many input procedures.
Initially this is the @dfn{standard input} in Unix and C terminology. Initially this is the @dfn{standard input} in Unix and C terminology.
When the standard input is a tty the port is unbuffered, otherwise When the standard input is a TTY the port is unbuffered, otherwise
it's fully buffered. it's fully buffered.
Unbuffered input is good if an application runs an interactive Unbuffered input is good if an application runs an interactive
subprocess, since any type-ahead input won't go into Guile's buffer subprocess, since any type-ahead input won't go into Guile's buffer
and be unavailable to the subprocess. and be unavailable to the subprocess.
Note that Guile buffering is completely separate from the tty ``line Note that Guile buffering is completely separate from the TTY ``line
discipline''. In the usual cooked mode on a tty Guile only sees a discipline''. In the usual cooked mode on a TTY Guile only sees a
line of input once the user presses @key{Return}. line of input once the user presses @key{Return}.
@end deffn @end deffn
@ -1016,10 +1017,10 @@ Return the current output port. This is the default port used
by many output procedures. by many output procedures.
Initially this is the @dfn{standard output} in Unix and C terminology. Initially this is the @dfn{standard output} in Unix and C terminology.
When the standard output is a tty this port is unbuffered, otherwise When the standard output is a TTY this port is unbuffered, otherwise
it's fully buffered. it's fully buffered.
Unbuffered output to a tty is good for ensuring progress output or a Unbuffered output to a TTY is good for ensuring progress output or a
prompt is seen. But an application which always prints whole lines prompt is seen. But an application which always prints whole lines
could change to line buffered, or an application with a lot of output could change to line buffered, or an application with a lot of output
could go fully buffered and perhaps make explicit @code{force-output} could go fully buffered and perhaps make explicit @code{force-output}
@ -1032,7 +1033,7 @@ calls (@pxref{Buffering}) at selected points.
Return the port to which errors and warnings should be sent. Return the port to which errors and warnings should be sent.
Initially this is the @dfn{standard error} in Unix and C terminology. Initially this is the @dfn{standard error} in Unix and C terminology.
When the standard error is a tty this port is unbuffered, otherwise When the standard error is a TTY this port is unbuffered, otherwise
it's fully buffered. it's fully buffered.
@end deffn @end deffn
@ -1095,7 +1096,7 @@ See also @ref{Ports and File Descriptors, open}, for an interface
to the Unix @code{open} system call. to the Unix @code{open} system call.
All file access uses the ``LFS'' large file support functions when All file access uses the ``LFS'' large file support functions when
available, so files bigger than 2 Gbytes (@math{2^31} bytes) can be available, so files bigger than 2 gibibytes (@math{2^31} bytes) can be
read and written on a 32-bit system. read and written on a 32-bit system.
Most systems have limits on how many files can be open, so it's Most systems have limits on how many files can be open, so it's
@ -1372,7 +1373,7 @@ port set temporarily to a string port opened on the specified
@deffn {Scheme Procedure} open-input-string str @deffn {Scheme Procedure} open-input-string str
@deffnx {C Function} scm_open_input_string (str) @deffnx {C Function} scm_open_input_string (str)
Take a string and return an input port that delivers characters Take a string and return an input port that delivers characters
from the string. The port can be closed by from the string. The port can be closed by
@code{close-input-port}, though its storage will be reclaimed @code{close-input-port}, though its storage will be reclaimed
by the garbage collector if it becomes inaccessible. by the garbage collector if it becomes inaccessible.
@end deffn @end deffn
@ -1380,7 +1381,7 @@ by the garbage collector if it becomes inaccessible.
@deffn {Scheme Procedure} open-output-string @deffn {Scheme Procedure} open-output-string
@deffnx {C Function} scm_open_output_string () @deffnx {C Function} scm_open_output_string ()
Return an output port that will accumulate characters for Return an output port that will accumulate characters for
retrieval by @code{get-output-string}. The port can be closed retrieval by @code{get-output-string}. The port can be closed
by the procedure @code{close-output-port}, though its storage by the procedure @code{close-output-port}, though its storage
will be reclaimed by the garbage collector if it becomes will be reclaimed by the garbage collector if it becomes
inaccessible. inaccessible.
@ -1735,7 +1736,7 @@ in-depth discussion.
These methods must be implemented if the @code{#:read} or @code{#:write} These methods must be implemented if the @code{#:read} or @code{#:write}
method can return @code{#f}, and should return a non-negative integer method can return @code{#f}, and should return a non-negative integer
file descriptor. However they may be called explicitly by a user, for file descriptor. However they may be called explicitly by a user, for
example to determine if a port may eventually be readable or writeable. example to determine if a port may eventually be readable or writable.
If there is no associated file descriptor with the port, they should If there is no associated file descriptor with the port, they should
return @code{#f}. The default implementation returns @code{#f}. return @code{#f}. The default implementation returns @code{#f}.
@end deffn @end deffn
@ -1937,7 +1938,7 @@ together. We document that set of primitives, design our internal
interfaces around them, and recommend them to users. As the R6RS I/O interfaces around them, and recommend them to users. As the R6RS I/O
system is the most capable standard that Scheme has yet produced in this system is the most capable standard that Scheme has yet produced in this
domain, we mostly recommend that; @code{(ice-9 binary-ports)} and domain, we mostly recommend that; @code{(ice-9 binary-ports)} and
@code{(ice-9 textual-ports)} are wholly modelled on @code{(rnrs io @code{(ice-9 textual-ports)} are wholly modeled on @code{(rnrs io
ports)}. Guile does not wholly copy R6RS, however; @xref{R6RS ports)}. Guile does not wholly copy R6RS, however; @xref{R6RS
Incompatibilities}. Incompatibilities}.

48
doc/ref/api-languages.texi
View file

@ -8,13 +8,13 @@
@section Support for Other Languages @section Support for Other Languages
In addition to Scheme, a user may write a Guile program in an increasing In addition to Scheme, a user may write a Guile program in an increasing
number of other languages. Currently supported languages include Emacs number of other languages. Currently supported languages include Emacs
Lisp and ECMAScript. Lisp and ECMAScript.
Guile is still fundamentally a Scheme, but it tries to support a wide Guile is still fundamentally a Scheme, but it tries to support a wide
variety of language building-blocks, so that other languages can be variety of language building-blocks, so that other languages can be
implemented on top of Guile. This allows users to write or extend implemented on top of Guile. This allows users to write or extend
applications in languages other than Scheme, too. This section describes applications in languages other than Scheme, too. This section describes
the languages that have been implemented. the languages that have been implemented.
(For details on how to implement a language, @xref{Compiling to the (For details on how to implement a language, @xref{Compiling to the
@ -36,7 +36,7 @@ Guile: at the REPL, and programmatically, via @code{compile},
The REPL is Guile's command prompt (@pxref{Using Guile Interactively}). The REPL is Guile's command prompt (@pxref{Using Guile Interactively}).
The REPL has a concept of the ``current language'', which defaults to The REPL has a concept of the ``current language'', which defaults to
Scheme. The user may change that language, via the meta-command Scheme. The user may change that language, via the meta-command
@code{,language}. @code{,language}.
For example, the following meta-command enables Emacs Lisp input: For example, the following meta-command enables Emacs Lisp input:
@ -64,9 +64,9 @@ Lispy languages, which have a straightforward datum representation.
Other languages that need more parsing are better dealt with as strings. Other languages that need more parsing are better dealt with as strings.
The easiest way to deal with syntax-heavy language is with files, via The easiest way to deal with syntax-heavy language is with files, via
@code{compile-file} and friends. However it is possible to invoke a @code{compile-file} and friends. However it is possible to invoke a
language's reader on a port, and then compile the resulting expression language's reader on a port, and then compile the resulting expression
(which is a datum at that point). For more information, (which is a datum at that point). For more information,
@xref{Compilation}. @xref{Compilation}.
For more details on introspecting aspects of different languages, For more details on introspecting aspects of different languages,
@ -76,16 +76,16 @@ For more details on introspecting aspects of different languages,
@subsection Emacs Lisp @subsection Emacs Lisp
Emacs Lisp (Elisp) is a dynamically-scoped Lisp dialect used in the Emacs Lisp (Elisp) is a dynamically-scoped Lisp dialect used in the
Emacs editor. @xref{top,,Overview,elisp,Emacs Lisp}, for more Emacs editor. @xref{top,,Overview,elisp,Emacs Lisp}, for more
information on Emacs Lisp. information on Emacs Lisp.
We hope that eventually Guile's implementation of Elisp will be good We hope that eventually Guile's implementation of Elisp will be good
enough to replace Emacs' own implementation of Elisp. For that reason, enough to replace Emacs' own implementation of Elisp. For that reason,
we have thought long and hard about how to support the various features we have thought long and hard about how to support the various features
of Elisp in a performant and compatible manner. of Elisp in a performant and compatible manner.
Readers familiar with Emacs Lisp might be curious about how exactly Readers familiar with Emacs Lisp might be curious about how exactly
these various Elisp features are supported in Guile. The rest of this these various Elisp features are supported in Guile. The rest of this
section focuses on addressing these concerns of the Elisp elect. section focuses on addressing these concerns of the Elisp elect.
@menu @menu
@ -103,8 +103,8 @@ It is false, and it is the end-of-list; thus it is a boolean, and a list
as well. as well.
Guile has chosen to support @code{nil} as a separate value, distinct Guile has chosen to support @code{nil} as a separate value, distinct
from @code{#f} and @code{'()}. This allows existing Scheme and Elisp from @code{#f} and @code{'()}. This allows existing Scheme and Elisp
code to maintain their current semantics. @code{nil}, which in Elisp code to maintain their current semantics. @code{nil}, which in Elisp
would just be written and read as @code{nil}, in Scheme has the external would just be written and read as @code{nil}, in Scheme has the external
representation @code{#nil}. representation @code{#nil}.
@ -127,7 +127,7 @@ Emacs Lisp code, else return @code{#f}.
@end deffn @end deffn
This decision to have @code{nil} as a low-level distinct value This decision to have @code{nil} as a low-level distinct value
facilitates interoperability between the two languages. Guile has chosen facilitates interoperability between the two languages. Guile has chosen
to have Scheme deal with @code{nil} as follows: to have Scheme deal with @code{nil} as follows:
@example @example
@ -146,14 +146,14 @@ scm_is_null (SCM_ELISP_NIL) @result{} 1
In this way, a version of @code{fold} written in Scheme can correctly In this way, a version of @code{fold} written in Scheme can correctly
fold a function written in Elisp (or in fact any other language) over a fold a function written in Elisp (or in fact any other language) over a
nil-terminated list, as Elisp makes. The converse holds as well; a nil-terminated list, as Elisp makes. The converse holds as well; a
version of @code{fold} written in Elisp can fold over a version of @code{fold} written in Elisp can fold over a
@code{'()}-terminated list, as made by Scheme. @code{'()}-terminated list, as made by Scheme.
On a low level, the bit representations for @code{#f}, @code{#t}, On a low level, the bit representations for @code{#f}, @code{#t},
@code{nil}, and @code{'()} are made in such a way that they differ by @code{nil}, and @code{'()} are made in such a way that they differ by
only one bit, and so a test for, for example, @code{#f}-or-@code{nil} only one bit, and so a test for, for example, @code{#f}-or-@code{nil}
may be made very efficiently. See @code{libguile/boolean.h}, for more may be made very efficiently. See @code{libguile/boolean.h}, for more
information. information.
@subsubheading Equality @subsubheading Equality
@ -189,8 +189,8 @@ However, in Elisp, @code{'()}, @code{#f}, and @code{nil} are all
@end example @end example
These choices facilitate interoperability between Elisp and Scheme code, These choices facilitate interoperability between Elisp and Scheme code,
but they are not perfect. Some code that is correct standard Scheme is but they are not perfect. Some code that is correct standard Scheme is
not correct in the presence of a second false and null value. For not correct in the presence of a second false and null value. For
example: example:
@example @example
@ -220,7 +220,7 @@ Here, @code{my-length} will raise an error if @var{l} is a
Both of these examples are correct standard Scheme, but, depending on Both of these examples are correct standard Scheme, but, depending on
what they really want to do, they are not correct Guile Scheme. what they really want to do, they are not correct Guile Scheme.
Correctly written, they would test the @emph{properties} of falsehood or Correctly written, they would test the @emph{properties} of falsehood or
nullity, not the individual members of that set. That is to say, they nullity, not the individual members of that set. That is to say, they
should use @code{not} or @code{null?} to test for falsehood or nullity, should use @code{not} or @code{null?} to test for falsehood or nullity,
not @code{eq?} or @code{memv} or the like. not @code{eq?} or @code{memv} or the like.
@ -254,14 +254,14 @@ This problem has a mirror-image case in Elisp:
@end example @end example
Guile can warn when compiling code that has equality comparisons with Guile can warn when compiling code that has equality comparisons with
@code{#f}, @code{'()}, or @code{nil}. @xref{Compilation}, for details. @code{#f}, @code{'()}, or @code{nil}. @xref{Compilation}, for details.
@node Dynamic Binding @node Dynamic Binding
@subsubsection Dynamic Binding @subsubsection Dynamic Binding
In contrast to Scheme, which uses ``lexical scoping'', Emacs Lisp scopes In contrast to Scheme, which uses ``lexical scoping'', Emacs Lisp scopes
its variables dynamically. Guile supports dynamic scoping with its its variables dynamically. Guile supports dynamic scoping with its
``fluids'' facility. @xref{Fluids and Dynamic States}, for more ``fluids'' facility. @xref{Fluids and Dynamic States}, for more
information. information.
@node Other Elisp Features @node Other Elisp Features
@ -269,7 +269,7 @@ information.
Buffer-local and mode-local variables should be mentioned here, along Buffer-local and mode-local variables should be mentioned here, along
with buckybits on characters, Emacs primitive data types, the with buckybits on characters, Emacs primitive data types, the
Lisp-2-ness of Elisp, and other things. Contributions to the Lisp-2-ness of Elisp, and other things. Contributions to the
documentation are most welcome! documentation are most welcome!
@node ECMAScript @node ECMAScript
@ -277,11 +277,11 @@ documentation are most welcome!
@url{http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-262.pdf,ECMAScript} @url{http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-262.pdf,ECMAScript}
was not the first non-Schemey language implemented by Guile, but it was was not the first non-Schemey language implemented by Guile, but it was
the first implemented for Guile's bytecode compiler. The goal was to the first implemented for Guile's bytecode compiler. The goal was to
support ECMAScript version 3.1, a relatively small language, but the support ECMAScript version 3.1, a relatively small language, but the
implementor was completely irresponsible and got distracted by other implementer was completely irresponsible and got distracted by other
things before finishing the standard library, and even some bits of the things before finishing the standard library, and even some bits of the
syntax. So, ECMAScript does deserve a mention in the manual, but it syntax. So, ECMAScript does deserve a mention in the manual, but it
doesn't deserve an endorsement until its implementation is completed, doesn't deserve an endorsement until its implementation is completed,
perhaps by some more responsible hacker. perhaps by some more responsible hacker.

85
doc/ref/api-macros.texi
View file

@ -9,13 +9,13 @@
At its best, programming in Lisp is an iterative process of building up a At its best, programming in Lisp is an iterative process of building up a
language appropriate to the problem at hand, and then solving the problem in language appropriate to the problem at hand, and then solving the problem in
that language. Defining new procedures is part of that, but Lisp also allows that language. Defining new procedures is part of that, but Lisp also allows
the user to extend its syntax, with its famous @dfn{macros}. the user to extend its syntax, with its famous @dfn{macros}.
@cindex macros @cindex macros
@cindex transformation @cindex transformation
Macros are syntactic extensions which cause the expression that they appear in Macros are syntactic extensions which cause the expression that they appear in
to be transformed in some way @emph{before} being evaluated. In expressions that to be transformed in some way @emph{before} being evaluated. In expressions that
are intended for macro transformation, the identifier that names the relevant are intended for macro transformation, the identifier that names the relevant
macro must appear as the first element, like this: macro must appear as the first element, like this:
@ -29,7 +29,7 @@ macro must appear as the first element, like this:
@cindex DSL @cindex DSL
@cindex EDSL @cindex EDSL
Macro expansion is a separate phase of evaluation, run before code is Macro expansion is a separate phase of evaluation, run before code is
interpreted or compiled. A macro is a program that runs on programs, translating interpreted or compiled. A macro is a program that runs on programs, translating
an embedded language into core Scheme@footnote{These days such embedded an embedded language into core Scheme@footnote{These days such embedded
languages are often referred to as @dfn{embedded domain-specific languages are often referred to as @dfn{embedded domain-specific
languages}, or EDSLs.}. languages}, or EDSLs.}.
@ -51,7 +51,7 @@ languages}, or EDSLs.}.
@node Defining Macros @node Defining Macros
@subsection Defining Macros @subsection Defining Macros
A macro is a binding between a keyword and a syntax transformer. Since it's A macro is a binding between a keyword and a syntax transformer. Since it's
difficult to discuss @code{define-syntax} without discussing the format of difficult to discuss @code{define-syntax} without discussing the format of
transformers, consider the following example macro definition: transformers, consider the following example macro definition:
@ -103,7 +103,7 @@ A @code{let-syntax} binding only exists at expansion-time.
@end deffn @end deffn
A @code{define-syntax} form is valid anywhere a definition may appear: at the A @code{define-syntax} form is valid anywhere a definition may appear: at the
top-level, or locally. Just as a local @code{define} expands out to an instance 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 of @code{letrec}, a local @code{define-syntax} expands out to
@code{letrec-syntax}. @code{letrec-syntax}.
@ -148,20 +148,21 @@ patterns, and as many templates as there are patterns.
When the syntax expander sees the invocation of a @code{syntax-rules} macro, it When the syntax expander sees the invocation of a @code{syntax-rules} macro, it
matches the expression against the patterns, in order, and rewrites the matches the expression against the patterns, in order, and rewrites the
expression using the template from the first matching pattern. If no pattern expression using the template from the first matching pattern. If no pattern
matches, a syntax error is signaled. matches, a syntax error is signaled.
@subsubsection Patterns @subsubsection Patterns
We have already seen some examples of patterns in the previous section: We have already seen some examples of patterns in the previous section:
@code{(unless condition exp ...)}, @code{(my-or exp)}, and so on. A pattern is @code{(unless condition exp ...)}, @code{(my-or exp)}, and so on. A pattern is
structured like the expression that it is to match. It can have nested structure structured like the expression that it is to match. It can have nested structure
as well, like @code{(let ((var val) ...) exp exp* ...)}. Broadly speaking, as well, like @code{(let ((var val) ...) exp exp* ...)}. Broadly speaking,
patterns are made of lists, improper lists, vectors, identifiers, and datums. patterns are made of lists, improper lists, vectors, identifiers, and datums.
Users can match a sequence of patterns using the ellipsis (@code{...}). Users can match a sequence of patterns using the ellipsis (@code{...}).
Identifiers in a pattern are called @dfn{literals} if they are present in the Identifiers in a pattern are called @dfn{literals} if they are present in the
@code{syntax-rules} literals list, and @dfn{pattern variables} otherwise. When @code{syntax-rules} literals list, and @dfn{pattern variables}
otherwise. When
building up the macro output, the expander replaces instances of a pattern building up the macro output, the expander replaces instances of a pattern
variable in the template with the matched subexpression. variable in the template with the matched subexpression.
@ -261,7 +262,7 @@ auxiliary syntax definitions, as specified by R6RS and R7RS:
@deffnx {Scheme Syntax} ... @deffnx {Scheme Syntax} ...
Auxiliary syntax definitions. Auxiliary syntax definitions.
These are defined as if with a macro that never matches, e.g.: These are defined with a macro that never matches, e.g.:
@example @example
(define-syntax else (syntax-rules ())) (define-syntax else (syntax-rules ()))
@ -437,14 +438,14 @@ Scheme}.
@code{syntax-rules} macros are simple and clean, but do they have limitations. @code{syntax-rules} macros are simple and clean, but do they have limitations.
They do not lend themselves to expressive error messages: patterns either match They do not lend themselves to expressive error messages: patterns either match
or they don't. Their ability to generate code is limited to template-driven or they don't. Their ability to generate code is limited to template-driven
expansion; often one needs to define a number of helper macros to get real work expansion; often one needs to define a number of helper macros to get real work
done. Sometimes one wants to introduce a binding into the lexical context of the done. Sometimes one wants to introduce a binding into the lexical context of the
generated code; this is impossible with @code{syntax-rules}. Relatedly, they generated code; this is impossible with @code{syntax-rules}. Relatedly, they
cannot programmatically generate identifiers. cannot programmatically generate identifiers.
The solution to all of these problems is to use @code{syntax-case} if you need The solution to all of these problems is to use @code{syntax-case} if you need
its features. But if for some reason you're stuck with @code{syntax-rules}, you its features. But if for some reason you're stuck with @code{syntax-rules}, you
might enjoy Joe Marshall's might enjoy Joe Marshall's
@uref{https://web.archive.org/web/20121111060531/@/ @uref{https://web.archive.org/web/20121111060531/@/
https://d655165b-a-62cb3a1a-s-sites.googlegroups.com/site/evalapply/@/ https://d655165b-a-62cb3a1a-s-sites.googlegroups.com/site/evalapply/@/
@ -463,8 +464,9 @@ Primer for the Merely Eccentric}.@footnote{Archived from
worthy of Scheme. worthy of Scheme.
@deffn {Syntax} syntax-case syntax literals (pattern [guard] exp) @dots{} @deffn {Syntax} syntax-case syntax literals (pattern [guard] exp) @dots{}
Match the syntax object @var{syntax} against the given patterns, in order. If a Match the syntax object @var{syntax} against the given patterns, in
@var{pattern} matches, return the result of evaluating the associated @var{exp}. order. If a @var{pattern} matches, return the result of evaluating the
associated @var{exp}.
@end deffn @end deffn
Compare the following definitions of @code{when}: Compare the following definitions of @code{when}:
@ -483,7 +485,7 @@ Compare the following definitions of @code{when}:
@end example @end example
Clearly, the @code{syntax-case} definition is similar to its @code{syntax-rules} Clearly, the @code{syntax-case} definition is similar to its @code{syntax-rules}
counterpart, and equally clearly there are some differences. The counterpart, and equally clearly there are some differences. The
@code{syntax-case} definition is wrapped in a @code{lambda}, a function of one @code{syntax-case} definition is wrapped in a @code{lambda}, a function of one
argument; that argument is passed to the @code{syntax-case} invocation; and the argument; that argument is passed to the @code{syntax-case} invocation; and the
``return value'' of the macro has a @code{#'} prefix. ``return value'' of the macro has a @code{#'} prefix.
@ -494,14 +496,14 @@ provide a way to destructure a @dfn{syntax object}, and to rebuild syntax
objects as output. objects as output.
So the @code{lambda} wrapper is simply a leaky implementation detail, that So the @code{lambda} wrapper is simply a leaky implementation detail, that
syntax transformers are just functions that transform syntax to syntax. This syntax transformers are just functions that transform syntax to syntax. This
should not be surprising, given that we have already described macros as should not be surprising, given that we have already described macros as
``programs that write programs''. @code{syntax-case} is simply a way to take ``programs that write programs''. @code{syntax-case} is simply a way to take
apart and put together program text, and to be a valid syntax transformer it apart and put together program text, and to be a valid syntax transformer it
needs to be wrapped in a procedure. needs to be wrapped in a procedure.
Unlike traditional Lisp macros (@pxref{Defmacros}), @code{syntax-case} macros Unlike traditional Lisp macros (@pxref{Defmacros}), @code{syntax-case} macros
transform syntax objects, not raw Scheme forms. Recall the naive expansion of transform syntax objects, not raw Scheme forms. Recall the naive expansion of
@code{my-or} given in the previous section: @code{my-or} given in the previous section:
@example @example
@ -514,7 +516,7 @@ transform syntax objects, not raw Scheme forms. Recall the naive expansion of
@end example @end example
Raw Scheme forms simply don't have enough information to distinguish the first Raw Scheme forms simply don't have enough information to distinguish the first
two @code{t} instances in @code{(if t t t)} from the third @code{t}. So instead two @code{t} instances in @code{(if t t t)} from the third @code{t}. So instead
of representing identifiers as symbols, the syntax expander represents of representing identifiers as symbols, the syntax expander represents
identifiers as annotated syntax objects, attaching such information to those identifiers as annotated syntax objects, attaching such information to those
syntax objects as is needed to maintain referential transparency. syntax objects as is needed to maintain referential transparency.
@ -523,8 +525,9 @@ syntax objects as is needed to maintain referential transparency.
Create a syntax object wrapping @var{form} within the current lexical context. Create a syntax object wrapping @var{form} within the current lexical context.
@end deffn @end deffn
Syntax objects are typically created internally to the process of expansion, but Syntax objects are typically created internally to facilitate the
it is possible to create them outside of syntax expansion: process of expansion, but it is possible to create them outside of
syntax expansion:
@example @example
(syntax (foo bar baz)) (syntax (foo bar baz))
@ -545,18 +548,18 @@ output from a @code{syntax-case} expression.
It is not strictly necessary for a @code{syntax-case} expression to return a It is not strictly necessary for a @code{syntax-case} expression to return a
syntax object, because @code{syntax-case} expressions can be used in helper syntax object, because @code{syntax-case} expressions can be used in helper
functions, or otherwise used outside of syntax expansion itself. However a functions, or otherwise used outside of syntax expansion itself. However a
syntax transformer procedure must return a syntax object, so most uses of syntax transformer procedure must return a syntax object, so most uses of
@code{syntax-case} do end up returning syntax objects. @code{syntax-case} do end up returning syntax objects.
Here in this case, the form that built the return value was @code{(syntax (+ exp Here in this case, the form that built the return value was @code{(syntax (+ exp
1))}. The interesting thing about this is that within a @code{syntax} 1))}. The interesting thing about this is that within a @code{syntax}
expression, any appearance of a pattern variable is substituted into the expression, any appearance of a pattern variable is substituted into the
resulting syntax object, carrying with it all relevant metadata from the source resulting syntax object, carrying with it all relevant metadata from the source
expression, such as lexical identity and source location. expression, such as lexical identity and source location.
Indeed, a pattern variable may only be referenced from inside a @code{syntax} Indeed, a pattern variable may only be referenced from inside a @code{syntax}
form. The syntax expander would raise an error when defining @code{add1} if it form. The syntax expander would raise an error when defining @code{add1} if it
found @var{exp} referenced outside a @code{syntax} form. found @var{exp} referenced outside a @code{syntax} form.
Since @code{syntax} appears frequently in macro-heavy code, it has a special Since @code{syntax} appears frequently in macro-heavy code, it has a special
@ -564,7 +567,7 @@ reader macro: @code{#'}. @code{#'foo} is transformed by the reader into
@code{(syntax foo)}, just as @code{'foo} is transformed into @code{(quote foo)}. @code{(syntax foo)}, just as @code{'foo} is transformed into @code{(quote foo)}.
The pattern language used by @code{syntax-case} is conveniently the same The pattern language used by @code{syntax-case} is conveniently the same
language used by @code{syntax-rules}. Given this, Guile actually defines language used by @code{syntax-rules}. Given this, Guile actually defines
@code{syntax-rules} in terms of @code{syntax-case}: @code{syntax-rules} in terms of @code{syntax-case}:
@example @example
@ -584,13 +587,13 @@ And that's that.
The examples we have shown thus far could just as well have been expressed with The examples we have shown thus far could just as well have been expressed with
@code{syntax-rules}, and have just shown that @code{syntax-case} is more @code{syntax-rules}, and have just shown that @code{syntax-case} is more
verbose, which is true. But there is a difference: @code{syntax-case} creates verbose, which is true. But there is a difference: @code{syntax-case} creates
@emph{procedural} macros, giving the full power of Scheme to the macro expander. @emph{procedural} macros, giving the full power of Scheme to the macro expander.
This has many practical applications. This has many practical applications.
A common desire is to be able to match a form only if it is an identifier. This A common desire is to be able to match a form only if it is an
is impossible with @code{syntax-rules}, given the datum matching forms. But with identifier. This is impossible with @code{syntax-rules}, given the
@code{syntax-case} it is easy: datum matching forms. But with @code{syntax-case} it is easy:
@deffn {Scheme Procedure} identifier? syntax-object @deffn {Scheme Procedure} identifier? syntax-object
Returns @code{#t} if @var{syntax-object} is an identifier, or @code{#f} Returns @code{#t} if @var{syntax-object} is an identifier, or @code{#f}
@ -877,7 +880,7 @@ objects.
@end deffn @end deffn
@deffn {Scheme Procedure} syntax-local-binding id [#:resolve-syntax-parameters?=#t] @deffn {Scheme Procedure} syntax-local-binding id [#:resolve-syntax-parameters?=#t]
Resolve the identifer @var{id}, a syntax object, within the current Resolve the identifier @var{id}, a syntax object, within the current
lexical environment, and return two values, the binding type and a lexical environment, and return two values, the binding type and a
binding value. The binding type is a symbol, which may be one of the binding value. The binding type is a symbol, which may be one of the
following: following:
@ -1104,7 +1107,7 @@ written to discriminate on the form in the operator position.
@deffn {Scheme Procedure} make-variable-transformer transformer @deffn {Scheme Procedure} make-variable-transformer transformer
Mark the @var{transformer} procedure as being a ``variable Mark the @var{transformer} procedure as being a ``variable
transformer''. In practice this means that, when bound to a syntactic transformer''. In practice this means that, when bound to a syntactic
keyword, it may detect references to that keyword on the left-hand-side keyword, it may detect references to that keyword on the left-hand-side
of a @code{set!}. of a @code{set!}.
@ -1130,7 +1133,7 @@ There is an extension to identifier-syntax which allows it to handle the
@code{set!} case as well: @code{set!} case as well:
@deffn {Syntax} identifier-syntax (var exp1) ((set! var val) exp2) @deffn {Syntax} identifier-syntax (var exp1) ((set! var val) exp2)
Create a variable transformer. The first clause is used for references Create a variable transformer. The first clause is used for references
to the variable in operator or operand position, and the second for to the variable in operator or operand position, and the second for
appearances of the variable on the left-hand-side of an assignment. appearances of the variable on the left-hand-side of an assignment.
@ -1166,7 +1169,7 @@ With syntax parameters, instead of introducing the binding
unhygienically each time, we instead create one binding for the keyword, unhygienically each time, we instead create one binding for the keyword,
which we can then adjust later when we want the keyword to have a which we can then adjust later when we want the keyword to have a
different meaning. As no new bindings are introduced, hygiene is different meaning. As no new bindings are introduced, hygiene is
preserved. This is similar to the dynamic binding mechanisms we have at preserved. This is similar to the dynamic binding mechanisms we have at
run-time (@pxref{SRFI-39, parameters}), except that the dynamic binding run-time (@pxref{SRFI-39, parameters}), except that the dynamic binding
only occurs during macro expansion. The code after macro expansion only occurs during macro expansion. The code after macro expansion
remains lexically scoped. remains lexically scoped.
@ -1192,7 +1195,7 @@ their @var{transformer} @dots{}, in the expansion of the @var{exp}
@dots{} forms. Each @var{keyword} must be bound to a syntax-parameter. @dots{} forms. Each @var{keyword} must be bound to a syntax-parameter.
@code{syntax-parameterize} differs from @code{let-syntax}, in that the @code{syntax-parameterize} differs from @code{let-syntax}, in that the
binding is not shadowed, but adjusted, and so uses of the keyword in the binding is not shadowed, but adjusted, and so uses of the keyword in the
expansion of @var{exp} @dots{} use the new transformers. This is expansion of @var{exp} @dots{} use the new transformers. This is
somewhat similar to how @code{parameterize} adjusts the values of somewhat similar to how @code{parameterize} adjusts the values of
regular parameters, rather than creating new bindings. regular parameters, rather than creating new bindings.
@ -1234,13 +1237,13 @@ program are available for the macro to use?
The default answer to this question is that when you import a module (via The default answer to this question is that when you import a module (via
@code{define-module} or @code{use-modules}), that module will be loaded up at @code{define-module} or @code{use-modules}), that module will be loaded up at
expansion-time, as well as at run-time. Additionally, top-level syntactic expansion-time, as well as at run-time. Additionally, top-level syntactic
definitions within one compilation unit made by @code{define-syntax} are also definitions within one compilation unit made by @code{define-syntax} are also
evaluated at expansion time, in the order that they appear in the compilation evaluated at expansion time, in the order that they appear in the compilation
unit (file). unit (file).
But if a syntactic definition needs to call out to a normal procedure at But if a syntactic definition needs to call out to a normal procedure at
expansion-time, it might well need need special declarations to indicate that expansion-time, it might well need special declarations to indicate that
the procedure should be made available at expansion-time. the procedure should be made available at expansion-time.
For example, the following code tries to embed a compilation For example, the following code tries to embed a compilation
@ -1252,7 +1255,7 @@ not in a file, as it cannot be byte-compiled:
(use-modules (srfi srfi-19)) (use-modules (srfi srfi-19))
(define start-date (date->string (current-date))) (define start-date (date->string (current-date)))
(define-syntax *compilation-date* (define-syntax *compilation-date*
(lambda (sintax) (lambda (syntax)
start-date)) start-date))
(display *compilation-date*) (display *compilation-date*)
(newline) (newline)
@ -1269,7 +1272,7 @@ The fix is to use @code{eval-when}.
(eval-when (expand load eval) (eval-when (expand load eval)
(define start-date (date->string (current-date)))) (define start-date (date->string (current-date))))
(define-syntax *compilation-date* (define-syntax *compilation-date*
(lambda (sintax) (lambda (syntax)
start-date)) start-date))
(display *compilation-date*) (display *compilation-date*)
(newline) (newline)
@ -1369,7 +1372,7 @@ macro definition to be present at compile time as well, so you pass
Compiler}. Compiler}.
It's a terrible interface; we know. The macroexpander is somewhat It's a terrible interface; we know. The macroexpander is somewhat
tricksy regarding modes, so unless you are building a macro-expanding tricky regarding modes, so unless you are building a macro-expanding
tool, we suggest to avoid invoking it directly. tool, we suggest to avoid invoking it directly.

30
doc/ref/api-memory.texi
View file

@ -36,11 +36,11 @@ automatically as needed.
@deftypefn {C Function} SCM scm_gc_protect_object (SCM @var{obj}) @deftypefn {C Function} SCM scm_gc_protect_object (SCM @var{obj})
Protects @var{obj} from being freed by the garbage collector, when it Protects @var{obj} from being freed by the garbage collector, when it
otherwise might be. When you are done with the object, call otherwise might be. When you are done with the object, call
@code{scm_gc_unprotect_object} on the object. Calls to @code{scm_gc_unprotect_object} on the object. Calls to
@code{scm_gc_protect_object}/@code{scm_gc_unprotect_object} can be nested, and @code{scm_gc_protect_object}/@code{scm_gc_unprotect_object} can be nested, and
the object remains protected until it has been unprotected as many times the object remains protected until it has been unprotected as many times
as it was protected. It is an error to unprotect an object more times as it was protected. It is an error to unprotect an object more times
than it has been protected. Returns the SCM object it was passed. than it has been protected. Returns the SCM object it was passed.
Note that storing @var{obj} in a C global variable has the same Note that storing @var{obj} in a C global variable has the same
effect@footnote{In Guile up to version 1.8, C global variables were not effect@footnote{In Guile up to version 1.8, C global variables were not
@ -52,7 +52,7 @@ object from being freed.}.
@deftypefn {C Function} SCM scm_gc_unprotect_object (SCM @var{obj}) @deftypefn {C Function} SCM scm_gc_unprotect_object (SCM @var{obj})
Unprotects an object from the garbage collector which was protected by Unprotects an object from the garbage collector which was protected by
@code{scm_gc_unprotect_object}. Returns the SCM object it was passed. @code{scm_gc_unprotect_object}. Returns the SCM object it was passed.
@end deftypefn @end deftypefn
@deftypefn {C Function} SCM scm_permanent_object (SCM @var{obj}) @deftypefn {C Function} SCM scm_permanent_object (SCM @var{obj})
@ -60,8 +60,8 @@ Unprotects an object from the garbage collector which was protected by
Similar to @code{scm_gc_protect_object} in that it causes the Similar to @code{scm_gc_protect_object} in that it causes the
collector to always mark the object, except that it should not be collector to always mark the object, except that it should not be
nested (only call @code{scm_permanent_object} on an object once), and nested (only call @code{scm_permanent_object} on an object once), and
it has no corresponding unpermanent function. Once an object is it has no corresponding unpermanent function. Once an object is
declared permanent, it will never be freed. Returns the SCM object it declared permanent, it will never be freed. Returns the SCM object it
was passed. was passed.
@end deftypefn @end deftypefn
@ -261,14 +261,14 @@ preprocessor macro was defined when Guile was compiled.
@subsection Weak References @subsection Weak References
[FIXME: This chapter is based on Mikael Djurfeldt's answer to a [FIXME: This chapter is based on Mikael Djurfeldt's answer to a
question by Michael Livshin. Any mistakes are not theirs, of course. ] question by Michael Livshin. Any mistakes are not theirs, of course. ]
Weak references let you attach bookkeeping information to data so that Weak references let you attach bookkeeping information to data so that
the additional information automatically disappears when the original the additional information automatically disappears when the original
data is no longer in use and gets garbage collected. In a weak key hash, data is no longer in use and gets garbage collected. In a weak key hash,
the hash entry for that key disappears as soon as the key is no longer the hash entry for that key disappears as soon as the key is no longer
referenced from anywhere else. For weak value hashes, the same happens referenced from anywhere else. For weak value hashes, the same happens
as soon as the value is no longer in use. Entries in a doubly weak hash as soon as the value is no longer in use. Entries in a doubly weak hash
disappear when either the key or the value are not used anywhere else disappear when either the key or the value are not used anywhere else
anymore. anymore.
@ -311,7 +311,7 @@ they constitute a doubly-weak table has to be used.
@deffnx {C Function} scm_make_weak_key_hash_table (size) @deffnx {C Function} scm_make_weak_key_hash_table (size)
@deffnx {C Function} scm_make_weak_value_hash_table (size) @deffnx {C Function} scm_make_weak_value_hash_table (size)
@deffnx {C Function} scm_make_doubly_weak_hash_table (size) @deffnx {C Function} scm_make_doubly_weak_hash_table (size)
Return a weak hash table with @var{size} buckets. As with any Return a weak hash table with @var{size} buckets. As with any
hash table, choosing a good size for the table requires some hash table, choosing a good size for the table requires some
caution. caution.
@ -334,7 +334,7 @@ leak. The reverse is true for weak value tables.
@deffnx {C Function} scm_weak_value_hash_table_p (obj) @deffnx {C Function} scm_weak_value_hash_table_p (obj)
@deffnx {C Function} scm_doubly_weak_hash_table_p (obj) @deffnx {C Function} scm_doubly_weak_hash_table_p (obj)
Return @code{#t} if @var{obj} is the specified weak hash Return @code{#t} if @var{obj} is the specified weak hash
table. Note that a doubly weak hash table is neither a weak key table. Note that a doubly weak hash table is neither a weak key
nor a weak value hash table. nor a weak value hash table.
@end deffn @end deffn
@ -343,9 +343,9 @@ nor a weak value hash table.
@deffn {Scheme Procedure} make-weak-vector size [fill] @deffn {Scheme Procedure} make-weak-vector size [fill]
@deffnx {C Function} scm_make_weak_vector (size, fill) @deffnx {C Function} scm_make_weak_vector (size, fill)
Return a weak vector with @var{size} elements. If the optional Return a weak vector with @var{size} elements. If the optional
argument @var{fill} is given, all entries in the vector will be argument @var{fill} is given, all entries in the vector will be
set to @var{fill}. The default value for @var{fill} is the set to @var{fill}. The default value for @var{fill} is the
empty list. empty list.
@end deffn @end deffn
@ -419,7 +419,7 @@ keys, or a value in a hash table with weak values does not prevent an
object from being returned by a guardian. But as long as an object object from being returned by a guardian. But as long as an object
can be returned from a guardian it will not be removed from such a can be returned from a guardian it will not be removed from such a
weak vector or hash table. In other words, a weak link does not weak vector or hash table. In other words, a weak link does not
prevent an object from being considered collectable, but being inside prevent an object from being considered collectible, but being inside
a guardian prevents a weak link from being broken. a guardian prevents a weak link from being broken.
A key in a weak key hash table can be thought of as having a strong A key in a weak key hash table can be thought of as having a strong

6
doc/ref/api-modules.texi
View file

@ -360,7 +360,7 @@ in the sense of @code{#:replace}.
@item #:version @var{list} @item #:version @var{list}
@cindex module version @cindex module version
Specify a version for the module in the form of @var{list}, a list of Specify a version for the module in the form of @var{list}, a list of
zero or more exact, nonnegative integers. The corresponding zero or more exact, non-negative integers. The corresponding
@code{#:version} option in the @code{use-modules} form allows callers @code{#:version} option in the @code{use-modules} form allows callers
to restrict the value of this option in various ways. to restrict the value of this option in various ways.
@ -510,7 +510,7 @@ a declared version specifier of the same form as the one described in
R6RS (@pxref{Library form, R6RS Library Form,, r6rs, The Revised^6 R6RS (@pxref{Library form, R6RS Library Form,, r6rs, The Revised^6
Report on the Algorithmic Language Scheme}). By using the Report on the Algorithmic Language Scheme}). By using the
@code{#:version} keyword in a @code{define-module} form, a module may @code{#:version} keyword in a @code{define-module} form, a module may
specify a version as a list of zero or more exact, nonnegative integers. specify a version as a list of zero or more exact, non-negative integers.
This version can then be used to locate the module during the module This version can then be used to locate the module during the module
search process. Client modules and callers of the @code{use-modules} search process. Client modules and callers of the @code{use-modules}
@ -536,7 +536,7 @@ in which @var{sub-version-reference} is in turn one of:
(not @var{sub-version-reference}) (not @var{sub-version-reference})
@end lisp @end lisp
in which @var{sub-version} is an exact, nonnegative integer as above. A in which @var{sub-version} is an exact, non-negative integer as above. A
version reference matches a declared module version if each element of version reference matches a declared module version if each element of
the version reference matches a corresponding element of the module the version reference matches a corresponding element of the module
version, according to the following rules: version, according to the following rules:

10
doc/ref/api-options.texi
View file

@ -18,12 +18,12 @@ installation directories, configuration flags that control pieces of
functionality being included or left out, etc. functionality being included or left out, etc.
@item @item
differences in dynamically loaded code --- behaviour and features differences in dynamically loaded code --- behavior and features
provided by modules that can be dynamically loaded into a running Guile provided by modules that can be dynamically loaded into a running Guile
@item @item
different runtime options --- some of the options that are provided for different runtime options --- some of the options that are provided for
controlling Guile's behaviour may be set differently. controlling Guile's behavior may be set differently.
@end itemize @end itemize
Guile provides ``introspective'' variables and procedures to query all Guile provides ``introspective'' variables and procedures to query all
@ -34,7 +34,7 @@ documentation on what the options mean.
@menu @menu
* Build Config:: Build and installation configuration. * Build Config:: Build and installation configuration.
* Feature Tracking:: Available features in the Guile process. * Feature Tracking:: Available features in the Guile process.
* Runtime Options:: Controlling Guile's runtime behaviour. * Runtime Options:: Controlling Guile's runtime behavior.
@end menu @end menu
@ -349,7 +349,7 @@ and friends (@pxref{Records}).
Although these tables may seem exhaustive, it is probably unwise in Although these tables may seem exhaustive, it is probably unwise in
practice to rely on them, as the correspondences between feature symbols practice to rely on them, as the correspondences between feature symbols
and available procedures/behaviour are not strictly defined. If you are and available procedures/behavior are not strictly defined. If you are
writing code that needs to check for the existence of some procedure, it writing code that needs to check for the existence of some procedure, it
is probably safer to do so directly using the @code{defined?} procedure is probably safer to do so directly using the @code{defined?} procedure
than to test for the corresponding feature using @code{provided?}. than to test for the corresponding feature using @code{provided?}.
@ -358,7 +358,7 @@ than to test for the corresponding feature using @code{provided?}.
@node Runtime Options @node Runtime Options
@subsection Runtime Options @subsection Runtime Options
There are a number of runtime options available for paramaterizing There are a number of runtime options available for parameterizing
built-in procedures, like @code{read}, and built-in behavior, like what built-in procedures, like @code{read}, and built-in behavior, like what
happens on an uncaught error. happens on an uncaught error.

12
doc/ref/api-peg.texi
View file

@ -716,7 +716,7 @@ This produces rather pretty parse trees:
Notice that when there's no entry in a field (e.g. @code{nameORcomment} Notice that when there's no entry in a field (e.g. @code{nameORcomment}
for messagebus) the symbol is inserted. This is the ``don't throw away for messagebus) the symbol is inserted. This is the ``don't throw away
any information'' rule---we succesfully matched a @code{nameORcomment} any information'' rule---we successfully matched a @code{nameORcomment}
of 0 characters (since we used @code{*} when defining it). This is of 0 characters (since we used @code{*} when defining it). This is
usually what you want, because it allows you to e.g. use @code{list-ref} usually what you want, because it allows you to e.g. use @code{list-ref}
to pull out elements (since they all have known offsets). to pull out elements (since they all have known offsets).
@ -1013,19 +1013,19 @@ First, any string PEG is expanded into an s-expression PEG by the code
in the @code{(ice-9 peg string-peg)} module. in the @code{(ice-9 peg string-peg)} module.
Then, the s-expression PEG that results is compiled into a parsing Then, the s-expression PEG that results is compiled into a parsing
function by the @code{(ice-9 peg codegen)} module. In particular, the function by the @code{(ice-9 peg codegen)} module. In particular, the
function @code{compile-peg-pattern} is called on the s-expression. It then function @code{compile-peg-pattern} is called on the s-expression. It then
decides what to do based on the form it is passed. decides what to do based on the form it is passed.
The PEG syntax can be expanded by providing @code{compile-peg-pattern} more The PEG syntax can be expanded by providing @code{compile-peg-pattern} more
options for what to do with its forms. The extended syntax will be options for what to do with its forms. The extended syntax will be
associated with a symbol, for instance @code{my-parsing-form}, and will associated with a symbol, for instance @code{my-parsing-form}, and will
be called on all PEG expressions of the form be called on all PEG expressions of the form
@lisp @lisp
(my-parsing-form ...) (my-parsing-form ...)
@end lisp @end lisp
The parsing function should take two arguments. The first will be a The parsing function should take two arguments. The first will be a
syntax object containing a list with all of the arguments to the form syntax object containing a list with all of the arguments to the form
(but not the form's name), and the second will be the (but not the form's name), and the second will be the
@code{capture-type} argument that is passed to @code{define-peg-pattern}. @code{capture-type} argument that is passed to @code{define-peg-pattern}.
@ -1033,5 +1033,5 @@ syntax object containing a list with all of the arguments to the form
New functions can be registered by calling @code{(add-peg-compiler! New functions can be registered by calling @code{(add-peg-compiler!
symbol function)}, where @code{symbol} is the symbol that will indicate symbol function)}, where @code{symbol} is the symbol that will indicate
a form of this type and @code{function} is the code generating function a form of this type and @code{function} is the code generating function
described above. The function @code{add-peg-compiler!} is exported from described above. The function @code{add-peg-compiler!} is exported from
the @code{(ice-9 peg codegen)} module. the @code{(ice-9 peg codegen)} module.

36
doc/ref/api-procedures.texi
View file

@ -127,19 +127,19 @@ required.
@subsection Compiled Procedures @subsection Compiled Procedures
The evaluation strategy given in @ref{Lambda} describes how procedures The evaluation strategy given in @ref{Lambda} describes how procedures
are @dfn{interpreted}. Interpretation operates directly on expanded are @dfn{interpreted}. Interpretation operates directly on expanded
Scheme source code, recursively calling the evaluator to obtain the Scheme source code, recursively calling the evaluator to obtain the
value of nested expressions. value of nested expressions.
Most procedures are compiled, however. This means that Guile has done Most procedures are compiled, however. This means that Guile has done
some pre-computation on the procedure, to determine what it will need to some pre-computation on the procedure, to determine what it will need to
do each time the procedure runs. Compiled procedures run faster than do each time the procedure runs. Compiled procedures run faster than
interpreted procedures. interpreted procedures.
Loading files is the normal way that compiled procedures come to Loading files is the normal way that compiled procedures come to
being. If Guile sees that a file is uncompiled, or that its compiled being. If Guile sees that a file is uncompiled, or that its compiled
file is out of date, it will attempt to compile the file when it is file is out of date, it will attempt to compile the file when it is
loaded, and save the result to disk. Procedures can be compiled at loaded, and save the result to disk. Procedures can be compiled at
runtime as well. @xref{Read/Load/Eval/Compile}, for more information runtime as well. @xref{Read/Load/Eval/Compile}, for more information
on runtime compilation. on runtime compilation.
@ -150,7 +150,7 @@ Properties}). In addition, there are a few more accessors for low-level
details on programs. details on programs.
Most people won't need to use the routines described in this section, Most people won't need to use the routines described in this section,
but it's good to have them documented. You'll have to include the but it's good to have them documented. You'll have to include the
appropriate module first, though: appropriate module first, though:
@example @example
@ -194,9 +194,9 @@ really clever.
Source location annotations for programs, along with their accessors. Source location annotations for programs, along with their accessors.
Source location information propagates through the compiler and ends Source location information propagates through the compiler and ends
up being serialized to the program's metadata. This information is up being serialized to the program's metadata. This information is
keyed by the offset of the instruction pointer within the object code keyed by the offset of the instruction pointer within the object code
of the program. Specifically, it is keyed on the @code{ip} @emph{just of the program. Specifically, it is keyed on the @code{ip} @emph{just
following} an instruction, so that backtraces can find the source following} an instruction, so that backtraces can find the source
location of a call that is in progress. location of a call that is in progress.
@end deffn @end deffn
@ -213,24 +213,24 @@ location of a call that is in progress.
@deffnx {Scheme Procedure} arity:allow-other-keys? arity @deffnx {Scheme Procedure} arity:allow-other-keys? arity
Accessors for a representation of the ``arity'' of a program. Accessors for a representation of the ``arity'' of a program.
The normal case is that a procedure has one arity. For example, The normal case is that a procedure has one arity. For example,
@code{(lambda (x) x)}, takes one required argument, and that's it. One @code{(lambda (x) x)}, takes one required argument, and that's it. One
could access that number of required arguments via @code{(arity:nreq could access that number of required arguments via @code{(arity:nreq
(program-arities (lambda (x) x)))}. Similarly, @code{arity:nopt} gets (program-arities (lambda (x) x)))}. Similarly, @code{arity:nopt} gets
the number of optional arguments, and @code{arity:rest?} returns a true the number of optional arguments, and @code{arity:rest?} returns a true
value if the procedure has a rest arg. value if the procedure has a rest arg.
@code{arity:kw} returns a list of @code{(@var{kw} . @var{idx})} pairs, @code{arity:kw} returns a list of @code{(@var{kw} . @var{idx})} pairs,
if the procedure has keyword arguments. The @var{idx} refers to the if the procedure has keyword arguments. The @var{idx} refers to the
@var{idx}th local variable; @xref{Variables and the VM}, for more @var{idx}th local variable; @xref{Variables and the VM}, for more
information. Finally @code{arity:allow-other-keys?} returns a true information. Finally @code{arity:allow-other-keys?} returns a true
value if other keys are allowed. @xref{Optional Arguments}, for more value if other keys are allowed. @xref{Optional Arguments}, for more
information. information.
So what about @code{arity:start} and @code{arity:end}, then? They So what about @code{arity:start} and @code{arity:end}, then? They
return the range of bytes in the program's bytecode for which a given return the range of bytes in the program's bytecode for which a given
arity is valid. You see, a procedure can actually have more than one arity is valid. You see, a procedure can actually have more than one
arity. The question, ``what is a procedure's arity'' only really makes arity. The question, ``what is a procedure's arity'' only really makes
sense at certain points in the program, delimited by these sense at certain points in the program, delimited by these
@code{arity:start} and @code{arity:end} values. @code{arity:start} and @code{arity:end} values.
@end deffn @end deffn
@ -281,7 +281,7 @@ to give names to the fixed number of arguments, but the remaining
For this reason, Guile provides an extension to @code{lambda}, For this reason, Guile provides an extension to @code{lambda},
@code{lambda*}, which allows the user to define procedures with @code{lambda*}, which allows the user to define procedures with
optional and keyword arguments. In addition, Guile's virtual machine optional and keyword arguments. In addition, Guile's virtual machine
has low-level support for optional and keyword argument dispatch. has low-level support for optional and keyword argument dispatch.
Calls to procedures with optional and keyword arguments can be made Calls to procedures with optional and keyword arguments can be made
cheaply, without allocating a rest list. cheaply, without allocating a rest list.
@ -564,7 +564,7 @@ Rest lists can be useful with @code{case-lambda}:
@end lisp @end lisp
@fnindex case-lambda* @fnindex case-lambda*
Also, for completeness. Guile defines @code{case-lambda*} as well, Also, for completeness. Guile defines @code{case-lambda*} as well,
which is like @code{case-lambda}, except with @code{lambda*} clauses. which is like @code{case-lambda}, except with @code{lambda*} clauses.
A @code{case-lambda*} clause matches if the arguments fill the A @code{case-lambda*} clause matches if the arguments fill the
required arguments, but are not too many for the optional and/or rest required arguments, but are not too many for the optional and/or rest

16
doc/ref/api-scheduling.texi
View file

@ -107,7 +107,7 @@ Return @code{#t} if @var{thread} has exited, or @code{#f} otherwise.
@deffn {Scheme Procedure} yield @deffn {Scheme Procedure} yield
@deffnx {C Function} scm_yield (thread) @deffnx {C Function} scm_yield (thread)
If one or more threads are waiting to execute, calling yield forces an If one or more threads are waiting to execute, calling yield forces an
immediate context switch to one of them. Otherwise, yield has no effect. immediate context switch to one of them. Otherwise, yield has no effect.
@end deffn @end deffn
@deffn {Scheme Procedure} cancel-thread thread . values @deffn {Scheme Procedure} cancel-thread thread . values
@ -181,7 +181,7 @@ other threads, which might not be what you want. Or, it might escape
via explicit reification via @code{current-dynamic-state}. via explicit reification via @code{current-dynamic-state}.
Of course, this dynamic scoping might be exactly what you want; that's Of course, this dynamic scoping might be exactly what you want; that's
why fluids and parameters work this way, and is what you want for for why fluids and parameters work this way, and is what you want for
many common parameters such as the current input and output ports, the many common parameters such as the current input and output ports, the
current locale conversion parameters, and the like. Perhaps this is the current locale conversion parameters, and the like. Perhaps this is the
case for most parameters, even. If your use case for thread-local case for most parameters, even. If your use case for thread-local
@ -205,7 +205,7 @@ not inherit thread-local fluid values from the parent thread.
@deffn {Scheme Procedure} fluid-thread-local? fluid @deffn {Scheme Procedure} fluid-thread-local? fluid
@deffnx {C Function} scm_fluid_thread_local_p (fluid) @deffnx {C Function} scm_fluid_thread_local_p (fluid)
Return @code{#t} if the fluid @var{fluid} is is thread-local, or Return @code{#t} if the fluid @var{fluid} is thread-local, or
@code{#f} otherwise. @code{#f} otherwise.
@end deffn @end deffn
@ -258,11 +258,11 @@ C signal handlers.)
Though an interrupt procedure can have any side effect permitted to Though an interrupt procedure can have any side effect permitted to
Guile code, asynchronous interrupts are generally used either for Guile code, asynchronous interrupts are generally used either for
profiling or for prematurely cancelling a computation. The former case profiling or for prematurely canceling a computation. The former case
is mostly transparent to the program being run, by design, but the is mostly transparent to the program being run, by design, but the
latter case can introduce bugs. Like finalizers (@pxref{Foreign Object latter case can introduce bugs. Like finalizers (@pxref{Foreign Object
Memory Management}), asynchronous interrupts introduce concurrency in a Memory Management}), asynchronous interrupts introduce concurrency in a
program. An asyncronous interrupt can run in the middle of some program. An asynchronous interrupt can run in the middle of some
mutex-protected operation, for example, and potentially corrupt the mutex-protected operation, for example, and potentially corrupt the
program's state. program's state.
@ -338,7 +338,7 @@ and that it should avoid waiting.
@deftypefn {C Function} int scm_c_prepare_to_wait_on_cond (scm_i_pthread_mutex_t *mutex, scm_i_pthread_cond_t *cond) @deftypefn {C Function} int scm_c_prepare_to_wait_on_cond (scm_i_pthread_mutex_t *mutex, scm_i_pthread_cond_t *cond)
Inform Guile that the current thread is about to sleep, and that if an Inform Guile that the current thread is about to sleep, and that if an
asynchronous interrupt is signaled on this thread, Guile should wake up asynchronous interrupt is signaled on this thread, Guile should wake up
the thread by acquiring @var{mutex} and signalling @var{cond}. The the thread by acquiring @var{mutex} and signaling @var{cond}. The
caller must already hold @var{mutex} and only drop it as part of the caller must already hold @var{mutex} and only drop it as part of the
@code{pthread_cond_wait} call. Returns zero if the prepare succeeded, @code{pthread_cond_wait} call. Returns zero if the prepare succeeded,
or nonzero if the thread already has a pending async and that it should or nonzero if the thread already has a pending async and that it should
@ -492,7 +492,7 @@ re-entry, and you might not have to worry about early exit either.
However, do consider the possibility of asynchronous interrupts However, do consider the possibility of asynchronous interrupts
(@pxref{Asyncs}). If the user interrupts your code interactively, that (@pxref{Asyncs}). If the user interrupts your code interactively, that
can cause an exception; or your thread might be cancelled, which does can cause an exception; or your thread might be canceled, which does
the same; or the user could be running your code under some pre-emptive the same; or the user could be running your code under some pre-emptive
system that periodically causes lightweight task switching. (Guile does system that periodically causes lightweight task switching. (Guile does
not currently include such a system, but it's possible to implement as a not currently include such a system, but it's possible to implement as a
@ -526,7 +526,7 @@ Finally, calling @code{make-mutex} with the symbol
@code{allow-external-unlock} creates an unowned mutex. An unowned mutex @code{allow-external-unlock} creates an unowned mutex. An unowned mutex
is like a standard mutex, except that it can be unlocked by any thread. is like a standard mutex, except that it can be unlocked by any thread.
A corollary of this behavior is that a thread's attempt to lock a mutex A corollary of this behavior is that a thread's attempt to lock a mutex
that it already owns will block instead of signalling an error, as it that it already owns will block instead of signaling an error, as it
could be that some other thread unlocks the mutex, allowing the owner could be that some other thread unlocks the mutex, allowing the owner
thread to proceed. This kind of mutex is a bit strange and is here for thread to proceed. This kind of mutex is a bit strange and is here for
use by SRFI-18. use by SRFI-18.

12
doc/ref/api-undocumented.texi
View file

@ -171,7 +171,7 @@ Unmemoize the memoized expression @var{m},
@deffnx {Scheme Procedure} doubly-weak-alist-vector? obj @deffnx {Scheme Procedure} doubly-weak-alist-vector? obj
@deffnx {C Function} scm_weak_key_alist_vector_p (obj) @deffnx {C Function} scm_weak_key_alist_vector_p (obj)
Return @code{#t} if @var{obj} is the specified weak hash Return @code{#t} if @var{obj} is the specified weak hash
table. Note that a doubly weak hash table is neither a weak key table. Note that a doubly weak hash table is neither a weak key
nor a weak value hash table. nor a weak value hash table.
@end deffn @end deffn
@ -179,7 +179,7 @@ nor a weak value hash table.
@deffnx {Scheme Procedure} make-weak-value-alist-vector size @deffnx {Scheme Procedure} make-weak-value-alist-vector size
@deffnx {Scheme Procedure} make-doubly-weak-alist-vector size @deffnx {Scheme Procedure} make-doubly-weak-alist-vector size
@deffnx {C Function} scm_make_weak_key_alist_vector (size) @deffnx {C Function} scm_make_weak_key_alist_vector (size)
Return a weak hash table with @var{size} buckets. As with any Return a weak hash table with @var{size} buckets. As with any
hash table, choosing a good size for the table requires some hash table, choosing a good size for the table requires some
caution. caution.
@ -212,7 +212,7 @@ Return the obarray that is used for all new bindings before the module system is
@deffn {Scheme Procedure} standard-interface-eval-closure module @deffn {Scheme Procedure} standard-interface-eval-closure module
@deffnx {C Function} scm_standard_interface_eval_closure (module) @deffnx {C Function} scm_standard_interface_eval_closure (module)
Return a interface eval closure for the module @var{module}. Such a closure does not allow new bindings to be added. Return a interface eval closure for the module @var{module}. Such a closure does not allow new bindings to be added.
@end deffn @end deffn
@deffn {Scheme Procedure} env-module env @deffn {Scheme Procedure} env-module env
@ -226,7 +226,7 @@ implemented by the C function "scm_single_thread_p"
@deffn {Scheme Procedure} set-debug-cell-accesses! flag @deffn {Scheme Procedure} set-debug-cell-accesses! flag
@deffnx {C Function} scm_set_debug_cell_accesses_x (flag) @deffnx {C Function} scm_set_debug_cell_accesses_x (flag)
This function is used to turn on checking for a debug version of GUILE. This version does not support this functionality This function is used to turn on checking for a debug version of GUILE. This version does not support this functionality
@end deffn @end deffn
@ -237,12 +237,12 @@ Return an eval closure for the module @var{module}.
@deffn {Scheme Procedure} mask-signals @deffn {Scheme Procedure} mask-signals
@deffnx {C Function} scm_mask_signals () @deffnx {C Function} scm_mask_signals ()
Mask signals. The returned value is not specified. Mask signals. The returned value is not specified.
@end deffn @end deffn
@deffn {Scheme Procedure} unmask-signals @deffn {Scheme Procedure} unmask-signals
@deffnx {C Function} scm_unmask_signals () @deffnx {C Function} scm_unmask_signals ()
Unmask signals. The returned value is not specified. Unmask signals. The returned value is not specified.
@end deffn @end deffn
@deffn {Scheme Procedure} noop . args @deffn {Scheme Procedure} noop . args

2
doc/ref/api-utility.texi
View file

@ -501,7 +501,7 @@ Once the procedures have been added, we can invoke the hook using
@end lisp @end lisp
Note that the procedures are called in the reverse of the order with Note that the procedures are called in the reverse of the order with
which they were added. This is because the default behaviour of which they were added. This is because the default behavior of
@code{add-hook!} is to add its procedure to the @emph{front} of the @code{add-hook!} is to add its procedure to the @emph{front} of the
hook's procedure list. You can force @code{add-hook!} to add its hook's procedure list. You can force @code{add-hook!} to add its
procedure to the @emph{end} of the list instead by providing a third procedure to the @emph{end} of the list instead by providing a third

6
doc/ref/expect.texi
View file

@ -64,10 +64,10 @@ match. E.g.,
The order of the substrings corresponds to the order in which the The order of the substrings corresponds to the order in which the
opening brackets occur. opening brackets occur.
A number of variables can be used to control the behaviour A number of variables can be used to control the behavior
of @code{expect} (and @code{expect-strings}). of @code{expect} (and @code{expect-strings}).
Most have default top-level bindings to the value @code{#f}, Most have default top-level bindings to the value @code{#f},
which produces the default behaviour. which produces the default behavior.
They can be redefined at the They can be redefined at the
top level or locally bound in a form enclosing the expect expression. top level or locally bound in a form enclosing the expect expression.
@ -142,6 +142,6 @@ of the file:
@end lisp @end lisp
The control variables described for @code{expect-strings} also The control variables described for @code{expect-strings} also
influence the behaviour of @code{expect}, with the exception of influence the behavior of @code{expect}, with the exception of
variables whose names begin with @code{expect-strings-}. variables whose names begin with @code{expect-strings-}.
@end defmac @end defmac

38
doc/ref/goops.texi
View file

@ -1801,7 +1801,7 @@ instances of an application-defined class --- and an understanding of
the MOP makes it much easier to explain such customizations in a precise the MOP makes it much easier to explain such customizations in a precise
way. And at a deeper level, understanding the MOP is a key part of way. And at a deeper level, understanding the MOP is a key part of
understanding GOOPS, and of taking full advantage of GOOPS' power, by understanding GOOPS, and of taking full advantage of GOOPS' power, by
customizing the behaviour of GOOPS itself. customizing the behavior of GOOPS itself.
@menu @menu
* Metaobjects and the Metaobject Protocol:: * Metaobjects and the Metaobject Protocol::
@ -1833,18 +1833,18 @@ Of these entities, GOOPS represents classes, generic functions and
methods as ``metaobjects''. In other words, the values in a GOOPS methods as ``metaobjects''. In other words, the values in a GOOPS
program that describe classes, generic functions and methods, are program that describe classes, generic functions and methods, are
themselves instances (or ``objects'') of special GOOPS classes that themselves instances (or ``objects'') of special GOOPS classes that
encapsulate the behaviour, respectively, of classes, generic functions, encapsulate the behavior, respectively, of classes, generic functions,
and methods. and methods.
(The other two entities are slot definitions and instances. Slot (The other two entities are slot definitions and instances. Slot
definitions are not strictly instances, but every slot definition is definitions are not strictly instances, but every slot definition is
associated with a GOOPS class that specifies the behaviour of the slot associated with a GOOPS class that specifies the behavior of the slot
as regards accessibility and protection from garbage collection. as regards accessibility and protection from garbage collection.
Instances are of course objects in the usual sense, and there is no Instances are of course objects in the usual sense, and there is no
benefit from thinking of them as metaobjects.) benefit from thinking of them as metaobjects.)
The ``metaobject protocol'' (or ``MOP'') is the specification of the The ``metaobject protocol'' (or ``MOP'') is the specification of the
generic functions which determine the behaviour of these metaobjects and generic functions which determine the behavior of these metaobjects and
the circumstances in which these generic functions are invoked. the circumstances in which these generic functions are invoked.
For a concrete example of what this means, consider how GOOPS calculates For a concrete example of what this means, consider how GOOPS calculates
@ -1880,7 +1880,7 @@ performs the slot calculation.
@end itemize @end itemize
In other words, rather than being hardcoded in @code{define-class}, the In other words, rather than being hardcoded in @code{define-class}, the
default behaviour of class definition is encapsulated by generic default behavior of class definition is encapsulated by generic
function methods that are specialized for the class @code{<class>}. function methods that are specialized for the class @code{<class>}.
It is possible to create a new class that inherits from @code{<class>}, It is possible to create a new class that inherits from @code{<class>},
@ -1894,7 +1894,7 @@ with the new @code{initialize} method. Thus the default slot
calculation, as well as any other aspect of the new class's relationship calculation, as well as any other aspect of the new class's relationship
with its superclasses, can be modified or overridden. with its superclasses, can be modified or overridden.
In a similar way, the behaviour of generic functions can be modified or In a similar way, the behavior of generic functions can be modified or
overridden by creating a new class that inherits from the standard overridden by creating a new class that inherits from the standard
generic function class @code{<generic>}, writing appropriate methods generic function class @code{<generic>}, writing appropriate methods
that are specialized to the new class, and creating new generic that are specialized to the new class, and creating new generic
@ -1907,7 +1907,7 @@ of that class.
Such is the power of the MOP. Note that @code{initialize} is just one Such is the power of the MOP. Note that @code{initialize} is just one
of a large number of generic functions that can be customized to modify of a large number of generic functions that can be customized to modify
the behaviour of application objects and classes and of GOOPS itself. the behavior of application objects and classes and of GOOPS itself.
Each following section covers a particular area of GOOPS functionality, Each following section covers a particular area of GOOPS functionality,
and describes the generic functions that are relevant for customization and describes the generic functions that are relevant for customization
of that area. of that area.
@ -2419,7 +2419,7 @@ If the metaclass of the new class is something more specialized than the
default @code{<class>}, then the type of @var{class} in the calls above default @code{<class>}, then the type of @var{class} in the calls above
is more specialized than @code{<class>}, and hence it becomes possible is more specialized than @code{<class>}, and hence it becomes possible
to define generic function methods, specialized for the new class's to define generic function methods, specialized for the new class's
metaclass, that can modify or override the default behaviour of metaclass, that can modify or override the default behavior of
@code{initialize}, @code{compute-cpl} or @code{compute-get-n-set}. @code{initialize}, @code{compute-cpl} or @code{compute-get-n-set}.
@code{compute-cpl} computes the class precedence list (``CPL'') for the @code{compute-cpl} computes the class precedence list (``CPL'') for the
@ -2508,9 +2508,9 @@ standard @code{initialize} method for classes whose metaclass is
@code{<class>}. But @code{initialize} itself can also be modified, by @code{<class>}. But @code{initialize} itself can also be modified, by
defining an @code{initialize} method specialized to the new class's defining an @code{initialize} method specialized to the new class's
metaclass. Such a method could complete override the standard metaclass. Such a method could complete override the standard
behaviour, by not calling @code{(next-method)} at all, but more behavior, by not calling @code{(next-method)} at all, but more
typically it would perform additional class initialization steps before typically it would perform additional class initialization steps before
and/or after calling @code{(next-method)} for the standard behaviour. and/or after calling @code{(next-method)} for the standard behavior.
@node Method Definition @node Method Definition
@ -2759,7 +2759,7 @@ make}). What then happens if @code{<my-class>} is redefined by calling
@menu @menu
* Redefinable Classes:: * Redefinable Classes::
* Default Class Redefinition Behaviour:: * Default Class Redefinition Behavior::
* Customizing Class Redefinition:: * Customizing Class Redefinition::
@end menu @end menu
@ -2794,8 +2794,8 @@ theory. In practice, attempting to, for example, redefine
Still, redefinition is an interesting capability when building Still, redefinition is an interesting capability when building
long-lived resilient systems, so GOOPS does offer this facility. long-lived resilient systems, so GOOPS does offer this facility.
@node Default Class Redefinition Behaviour @node Default Class Redefinition Behavior
@subsection Default Class Redefinition Behaviour @subsection Default Class Redefinition Behavior
When a class is defined using @code{define-class} and the class name was When a class is defined using @code{define-class} and the class name was
previously defined, by default the new binding just replaces the old previously defined, by default the new binding just replaces the old
@ -2849,11 +2849,11 @@ updated when a class is redefined.)
@end itemize @end itemize
If this class redefinition strategy strikes you as rather counter-intuitive, If this class redefinition strategy strikes you as rather counter-intuitive,
bear in mind that it is derived from similar behaviour in other object bear in mind that it is derived from similar behavior in other object
systems such as CLOS, and that experience in those systems has shown it to be systems such as CLOS, and that experience in those systems has shown it to be
very useful in practice. very useful in practice.
Also bear in mind that, like most of GOOPS' default behaviour, it can Also bear in mind that, like most of GOOPS' default behavior, it can
be customized@dots{} be customized@dots{}
@node Customizing Class Redefinition @node Customizing Class Redefinition
@ -2864,7 +2864,7 @@ constructs the new class metaobject as usual, then invokes the
@code{class-redefinition} generic function with the old and new classes @code{class-redefinition} generic function with the old and new classes
as arguments. Therefore, if the old or new classes have metaclasses as arguments. Therefore, if the old or new classes have metaclasses
other than the default @code{<redefinable-class>}, class redefinition other than the default @code{<redefinable-class>}, class redefinition
behaviour can be customized by defining a @code{class-redefinition} behavior can be customized by defining a @code{class-redefinition}
method that is specialized for the relevant metaclasses. method that is specialized for the relevant metaclasses.
@deffn generic class-redefinition @deffn generic class-redefinition
@ -2880,8 +2880,8 @@ classes. @xref{Redefinable Classes}. This default method just returns
@end deffn @end deffn
@deffn method class-redefinition (old <redefinable-class>) (new <redefinable-class>) @deffn method class-redefinition (old <redefinable-class>) (new <redefinable-class>)
This method implements GOOPS' default class redefinition behaviour, as This method implements GOOPS' default class redefinition behavior, as
described in @ref{Default Class Redefinition Behaviour}. Returns the described in @ref{Default Class Redefinition Behavior}. Returns the
metaobject for the new class definition. metaobject for the new class definition.
@end deffn @end deffn
@ -2980,6 +2980,6 @@ instance whose class has just been changed. The default
@code{update-instance-for-different-class} method does nothing. @code{update-instance-for-different-class} method does nothing.
@end deffn @end deffn
Customized change of class behaviour can be implemented by defining Customized change of class behavior can be implemented by defining
@code{change-class} methods that are specialized either by the class @code{change-class} methods that are specialized either by the class
of the instances to be modified or by the metaclass of the new class. of the instances to be modified or by the metaclass of the new class.

2
doc/ref/misc-modules.texi
View file

@ -97,7 +97,7 @@ into @var{width} characters. By default, @var{obj} will be printed using
@code{write}, though that behavior can be overridden via the @code{write}, though that behavior can be overridden via the
@var{display?} keyword argument. @var{display?} keyword argument.
The default behaviour is to print depth-first, meaning that the entire The default behavior is to print depth-first, meaning that the entire
remaining width will be available to each sub-expression of @var{obj} -- 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 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 ``ration'' the available width, trying to allocate it equally to each

12
doc/ref/posix.texi
View file

@ -162,7 +162,7 @@ environment, setting the revealed count is not required provided the
port is kept open (i.e., is pointed to by a live Scheme binding) while port is kept open (i.e., is pointed to by a live Scheme binding) while
the file descriptor is in use. the file descriptor is in use.
To correspond with traditional Unix behaviour, three file descriptors To correspond with traditional Unix behavior, three file descriptors
(0, 1, and 2) are automatically imported when a program starts up and (0, 1, and 2) are automatically imported when a program starts up and
assigned to the initial values of the current/standard input, output, assigned to the initial values of the current/standard input, output,
and error ports, respectively. The revealed count for each is and error ports, respectively. The revealed count for each is
@ -414,7 +414,7 @@ descriptor underlying @var{port}, with mode string @var{modes}
as for @ref{File Ports, open-file}. The two ports as for @ref{File Ports, open-file}. The two ports
will share a file position and file status flags. will share a file position and file status flags.
Unexpected behaviour can result if both ports are subsequently used Unexpected behavior can result if both ports are subsequently used
and the original and/or duplicate ports are buffered. and the original and/or duplicate ports are buffered.
The mode string can include @code{0} to obtain an unbuffered duplicate The mode string can include @code{0} to obtain an unbuffered duplicate
port. port.
@ -432,7 +432,7 @@ and file status flags.
The return value is unspecified. The return value is unspecified.
Unexpected behaviour can result if both ports are subsequently used Unexpected behavior can result if both ports are subsequently used
and the original and/or duplicate ports are buffered. and the original and/or duplicate ports are buffered.
This procedure does not have any side effects on other ports or This procedure does not have any side effects on other ports or
@ -1293,7 +1293,7 @@ stream. Otherwise, close the stream. The @code{setpwent} and
@deffn {Scheme Procedure} getpw [user] @deffn {Scheme Procedure} getpw [user]
@deffnx {C Function} scm_getpwuid (user) @deffnx {C Function} scm_getpwuid (user)
Look up an entry in the user database. @var{user} 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 a string, or omitted, giving the behavior of getpwuid, getpwnam
or getpwent respectively. or getpwent respectively.
@end deffn @end deffn
@ -1348,7 +1348,7 @@ stream. Otherwise, close the stream. The @code{setgrent} and
@deffn {Scheme Procedure} getgr [group] @deffn {Scheme Procedure} getgr [group]
@deffnx {C Function} scm_getgrgid (group) @deffnx {C Function} scm_getgrgid (group)
Look up an entry in the group database. @var{group} can be an integer, Look up an entry in the group database. @var{group} can be an integer,
a string, or omitted, giving the behaviour of getgrgid, getgrnam a string, or omitted, giving the behavior of getgrgid, getgrnam
or getgrent respectively. or getgrent respectively.
@end deffn @end deffn
@ -1862,7 +1862,7 @@ has terminated or (optionally) stopped. Normally it will
suspend the calling process until this can be done. If more than one suspend the calling process until this can be done. If more than one
child process is eligible then one will be chosen by the operating system. child process is eligible then one will be chosen by the operating system.
The value of @var{pid} determines the behaviour: The value of @var{pid} determines the behavior:
@table @asis @table @asis
@item @var{pid} greater than 0 @item @var{pid} greater than 0

4
doc/ref/repl-modules.texi
View file

@ -21,7 +21,7 @@ history entries.
@menu @menu
* Loading Readline Support:: How to load readline support into Guile. * Loading Readline Support:: How to load readline support into Guile.
* Readline Options:: How to modify readline's behaviour. * Readline Options:: How to modify readline's behavior.
* Readline Functions:: Programming with readline. * Readline Functions:: Programming with readline.
@end menu @end menu
@ -44,7 +44,7 @@ activate readline's features for the REPL. If you plan to use this
module often, you should save these to lines to your @file{.guile} module often, you should save these to lines to your @file{.guile}
personal startup file. personal startup file.
You will notice that the REPL's behaviour changes a bit when you have You will notice that the REPL's behavior changes a bit when you have
loaded the readline module. For example, when you press Enter before loaded the readline module. For example, when you press Enter before
typing in the closing parentheses of a list, you will see the typing in the closing parentheses of a list, you will see the
@dfn{continuation} prompt, three dots: @code{...} This gives you a nice @dfn{continuation} prompt, three dots: @code{...} This gives you a nice

20
doc/ref/scheme-ideas.texi
View file

@ -260,7 +260,7 @@ value to the more convenient name @code{call/cc}.
Let's understand exactly how this works. The definition creates a new Let's understand exactly how this works. The definition creates a new
variable @code{call/cc}, and then sets its value to the value of the variable @code{call/cc}, and then sets its value to the value of the
variable @code{call-with-current-continuation}; the latter value is a variable @code{call-with-current-continuation}; the latter value is a
procedure that implements the behaviour that R5RS specifies under the procedure that implements the behavior that R5RS specifies under the
name ``call-with-current-continuation''. So @code{call/cc} ends up name ``call-with-current-continuation''. So @code{call/cc} ends up
holding this value as well. holding this value as well.
@ -293,7 +293,7 @@ value is a procedure. Most commonly, however, @var{procedure} is simply
the name of a variable whose value is a procedure. the name of a variable whose value is a procedure.
For example, @code{string-append} is a standard Scheme procedure whose For example, @code{string-append} is a standard Scheme procedure whose
behaviour is to concatenate together all the arguments, which are behavior is to concatenate together all the arguments, which are
expected to be strings, that it is given. So the expression expected to be strings, that it is given. So the expression
@lisp @lisp
@ -359,7 +359,7 @@ For example, the value of the following Scheme expression
@noindent @noindent
is a newly created procedure that takes two arguments: @code{name} and is a newly created procedure that takes two arguments: @code{name} and
@code{address}. The behaviour of the new procedure is determined by the @code{address}. The behavior of the new procedure is determined by the
sequence of expressions and definitions in the @var{body} of the sequence of expressions and definitions in the @var{body} of the
procedure definition. (Typically, @var{body} would use the arguments in procedure definition. (Typically, @var{body} would use the arguments in
some way, or else there wouldn't be any point in giving them to the some way, or else there wouldn't be any point in giving them to the
@ -511,7 +511,7 @@ program as a whole.
This section clarifies what we mean by an expression's value, by This section clarifies what we mean by an expression's value, by
introducing the idea of @dfn{evaluation}. It discusses the side effects introducing the idea of @dfn{evaluation}. It discusses the side effects
that evaluation can have, explains how each of the various types of that evaluation can have, explains how each of the various types of
Scheme expression is evaluated, and describes the behaviour and use of Scheme expression is evaluated, and describes the behavior and use of
the Guile REPL as a mechanism for exploring evaluation. The section the Guile REPL as a mechanism for exploring evaluation. The section
concludes with a very brief summary of Scheme's common syntactic concludes with a very brief summary of Scheme's common syntactic
expressions. expressions.
@ -549,7 +549,7 @@ values, or side effects, or both.
It is tempting to try to define more intuitively what we mean by It is tempting to try to define more intuitively what we mean by
``value'' and ``side effects'', and what the difference between them is. ``value'' and ``side effects'', and what the difference between them is.
In general, though, this is extremely difficult. It is also In general, though, this is extremely difficult. It is also
unnecessary; instead, we can quite happily define the behaviour of a unnecessary; instead, we can quite happily define the behavior of a
Scheme program by specifying how Scheme executes a program as a whole, Scheme program by specifying how Scheme executes a program as a whole,
and then by describing the value and side effects of evaluation for each and then by describing the value and side effects of evaluation for each
type of expression individually. type of expression individually.
@ -718,7 +718,7 @@ In the outermost expression, @var{procedure} is @code{string-length} and
@itemize @bullet @itemize @bullet
@item @item
Evaluation of @code{string-length}, which is a variable, gives a Evaluation of @code{string-length}, which is a variable, gives a
procedure value that implements the expected behaviour for procedure value that implements the expected behavior for
``string-length''. ``string-length''.
@item @item
@ -728,7 +728,7 @@ another procedure invocation expression, means evaluating each of
@itemize @bullet @itemize @bullet
@item @item
@code{string-append}, which gives a procedure value that implements the @code{string-append}, which gives a procedure value that implements the
expected behaviour for ``string-append'' expected behavior for ``string-append''
@item @item
@code{"/home"}, which gives the string value @code{"/home"} @code{"/home"}, which gives the string value @code{"/home"}
@ -920,7 +920,7 @@ execute, Guile enters its standard Read Evaluate Print Loop --- or
Scheme expression that the user types, evaluates it, and prints the Scheme expression that the user types, evaluates it, and prints the
resulting value. resulting value.
The REPL is a useful mechanism for exploring the evaluation behaviour The REPL is a useful mechanism for exploring the evaluation behavior
described in the previous subsection. If you type @code{string-append}, described in the previous subsection. If you type @code{string-append},
for example, the REPL replies @code{#<primitive-procedure for example, the REPL replies @code{#<primitive-procedure
string-append>}, illustrating the relationship between the variable string-append>}, illustrating the relationship between the variable
@ -1220,7 +1220,7 @@ of the code that calls @code{currency-string} rebinds the name
``currency-abbreviation'' in the meanwhile. ``currency-abbreviation'' in the meanwhile.
The second function @code{french-currency-string} works precisely by The second function @code{french-currency-string} works precisely by
taking advantage of this behaviour. It creates a new binding for the taking advantage of this behavior. It creates a new binding for the
name ``currency-abbreviation'' which overrides the one established by name ``currency-abbreviation'' which overrides the one established by
the @code{defvar} form. the @code{defvar} form.
@ -1267,7 +1267,7 @@ the name ``currency-abbreviation'' at all, the binding is pointless.
"USD33.44" "USD33.44"
@end lisp @end lisp
This begs the question of how the Emacs Lisp behaviour can be This begs the question of how the Emacs Lisp behavior can be
implemented in Scheme. In general, this is a design question whose implemented in Scheme. In general, this is a design question whose
answer depends upon the problem that is being addressed. In this case, answer depends upon the problem that is being addressed. In this case,
the best answer may be that @code{currency-string} should be the best answer may be that @code{currency-string} should be

2
doc/ref/scheme-scripts.texi
View file

@ -225,7 +225,7 @@ procedure to call after loading the script, Guile will call that
procedure with @code{(command-line)} as its argument. So a script that procedure with @code{(command-line)} as its argument. So a script that
uses @code{-e} doesn't need to refer explicitly to @code{command-line} uses @code{-e} doesn't need to refer explicitly to @code{command-line}
in its code. For example, the script above would have identical in its code. For example, the script above would have identical
behaviour if it was written instead like this: behavior if it was written instead like this:
@example @example
#! /usr/local/bin/guile \ #! /usr/local/bin/guile \

6
doc/ref/srfi-modules.texi
View file

@ -2139,7 +2139,7 @@ Guile provides a set of primitives and SRFI-18 is one of the systems built in te
* SRFI-18 Mutexes:: Mutual exclusion devices * SRFI-18 Mutexes:: Mutual exclusion devices
* SRFI-18 Condition variables:: Synchronizing of groups of threads * SRFI-18 Condition variables:: Synchronizing of groups of threads
* SRFI-18 Time:: Representation of times and durations * SRFI-18 Time:: Representation of times and durations
* SRFI-18 Exceptions:: Signalling and handling errors * SRFI-18 Exceptions:: Signaling and handling errors
@end menu @end menu
@node SRFI-18 Threads @node SRFI-18 Threads
@ -3065,7 +3065,7 @@ specialization of @code{write}, sending output to
The special symbol @code{<>} indicates a slot to be filled by an The special symbol @code{<>} indicates a slot to be filled by an
argument to the new procedure. @code{my-output-port} on the other argument to the new procedure. @code{my-output-port} on the other
hand is an expression to be evaluated and passed, ie.@: it specializes hand is an expression to be evaluated and passed, ie.@: it specializes
the behaviour of @code{write}. the behavior of @code{write}.
@table @nicode @table @nicode
@item <> @item <>
@ -6094,7 +6094,7 @@ These functions are in the @code{(srfi srfi-171 meta)} module and are only
usable when you want to write your own transducers. usable when you want to write your own transducers.
@deffn {Scheme Procedure} reduced value @deffn {Scheme Procedure} reduced value
Wraps a value in a @code{<reduced>} container, signalling that the Wraps a value in a @code{<reduced>} container, signaling that the
reduction should stop. reduction should stop.
@end deffn @end deffn

2
gc-benchmarks/larceny/dynamic.sch
View file

@ -884,7 +884,7 @@
; uses union/find elements with two info fields ; uses union/find elements with two info fields
; a type variable has exactly four fields: ; a type variable has exactly four fields:
; car: TVar (the parent field; initially null) ; car: TVar (the parent field; initially null)
; cadr: Number (the rank field; is always nonnegative) ; cadr: Number (the rank field; is always non-negative)
; caddr: Symbol (the type variable identifier; used only for printing) ; caddr: Symbol (the type variable identifier; used only for printing)
; cdddr: Type (the leq field; initially null) ; cdddr: Type (the leq field; initially null)
(gen-element (cons (gen-id) '()))) (gen-element (cons (gen-id) '())))

16
gc-benchmarks/larceny/twobit-input-long.sch
View file

@ -16067,7 +16067,7 @@
; Returns a length-4 bytevector. ; Returns a length-4 bytevector.
; ;
; M may be an exact integer or a length-4 bytevector. ; M may be an exact integer or a length-4 bytevector.
; N must be an exact nonnegative integer; it's interpreted modulo 33. ; N must be an exact non-negative integer; it's interpreted modulo 33.
(define (asm:lsh m n) (define (asm:lsh m n)
(if (not (bytevector? m)) (if (not (bytevector? m))
@ -16098,7 +16098,7 @@
; Returns a length-4 bytevector. ; Returns a length-4 bytevector.
; ;
; M may be an exact integer or a length-4 bytevector. ; M may be an exact integer or a length-4 bytevector.
; N must be an exact nonnegative integer; it's interpreted modulo 33. ; N must be an exact non-negative integer; it's interpreted modulo 33.
(define (asm:rshl m n) (define (asm:rshl m n)
(if (not (bytevector? m)) (if (not (bytevector? m))
@ -16129,7 +16129,7 @@
; high end. Returns a length-4 bytevector. ; high end. Returns a length-4 bytevector.
; ;
; M may be an exact integer or a length-4 bytevector. ; M may be an exact integer or a length-4 bytevector.
; N must be an exact nonnegative integer; it's interpreted modulo 33. ; N must be an exact non-negative integer; it's interpreted modulo 33.
(define asm:rsha (define asm:rsha
(let ((ones (asm:bv #xff #xff #xff #xff))) (let ((ones (asm:bv #xff #xff #xff #xff)))
@ -16240,7 +16240,7 @@
; Extract the n low-order bits of m. ; Extract the n low-order bits of m.
; m may be an exact integer or a length-4 bytevector. ; m may be an exact integer or a length-4 bytevector.
; n must be an exact nonnegative integer, interpreted modulo 32. ; n must be an exact non-negative integer, interpreted modulo 32.
; Returns length-4 bytevector. ; Returns length-4 bytevector.
; ;
; Does not depend on endian-ness. ; Does not depend on endian-ness.
@ -16255,7 +16255,7 @@
; Extract the n high-order bits of m. ; Extract the n high-order bits of m.
; m may be an exact integer or a length-4 bytevector. ; m may be an exact integer or a length-4 bytevector.
; n must be an exact nonnegative integer, interpreted modulo 33. ; n must be an exact non-negative integer, interpreted modulo 33.
; Returns length-4 bytevector with the high-order bits of m at low end. ; Returns length-4 bytevector with the high-order bits of m at low end.
; ;
; Does not depend on endian-ness. ; Does not depend on endian-ness.
@ -16553,7 +16553,7 @@
; ;
; version a fixnum (constant) - heap type version number ; version a fixnum (constant) - heap type version number
; roots an assoc list that maps root names to values ; roots an assoc list that maps root names to values
; top an exact nonnegative integer: the address of the ; top an exact non-negative integer: the address of the
; next byte to be emitted ; next byte to be emitted
; symbol-table a symbol table abstract data type ; symbol-table a symbol table abstract data type
; extra any value - a client-extension field ; extra any value - a client-extension field
@ -20735,7 +20735,7 @@
; Strings ; Strings
; RESULT must have nonnegative fixnum. ; RESULT must have non-negative fixnum.
; RS2 must have character. ; RS2 must have character.
(define-primop 'make-string (define-primop 'make-string
@ -23056,7 +23056,7 @@
; A `decoded-instruction' is a list where the car is a mnemonic and ; A `decoded-instruction' is a list where the car is a mnemonic and
; the operands are appropriate for that mnemonic. ; the operands are appropriate for that mnemonic.
; ;
; A `mnemonic' is an exact nonnegative integer. It encodes the name of ; A `mnemonic' is an exact non-negative integer. It encodes the name of
; the instruction as well as its attributes (operand pattern and instruction ; the instruction as well as its attributes (operand pattern and instruction
; type). See below for specific operations on mnemonics. ; type). See below for specific operations on mnemonics.

16
gc-benchmarks/larceny/twobit.sch
View file

@ -16067,7 +16067,7 @@
; Returns a length-4 bytevector. ; Returns a length-4 bytevector.
; ;
; M may be an exact integer or a length-4 bytevector. ; M may be an exact integer or a length-4 bytevector.
; N must be an exact nonnegative integer; it's interpreted modulo 33. ; N must be an exact non-negative integer; it's interpreted modulo 33.
(define (asm:lsh m n) (define (asm:lsh m n)
(if (not (bytevector? m)) (if (not (bytevector? m))
@ -16098,7 +16098,7 @@
; Returns a length-4 bytevector. ; Returns a length-4 bytevector.
; ;
; M may be an exact integer or a length-4 bytevector. ; M may be an exact integer or a length-4 bytevector.
; N must be an exact nonnegative integer; it's interpreted modulo 33. ; N must be an exact non-negative integer; it's interpreted modulo 33.
(define (asm:rshl m n) (define (asm:rshl m n)
(if (not (bytevector? m)) (if (not (bytevector? m))
@ -16129,7 +16129,7 @@
; high end. Returns a length-4 bytevector. ; high end. Returns a length-4 bytevector.
; ;
; M may be an exact integer or a length-4 bytevector. ; M may be an exact integer or a length-4 bytevector.
; N must be an exact nonnegative integer; it's interpreted modulo 33. ; N must be an exact non-negative integer; it's interpreted modulo 33.
(define asm:rsha (define asm:rsha
(let ((ones (asm:bv #xff #xff #xff #xff))) (let ((ones (asm:bv #xff #xff #xff #xff)))
@ -16240,7 +16240,7 @@
; Extract the n low-order bits of m. ; Extract the n low-order bits of m.
; m may be an exact integer or a length-4 bytevector. ; m may be an exact integer or a length-4 bytevector.
; n must be an exact nonnegative integer, interpreted modulo 32. ; n must be an exact non-negative integer, interpreted modulo 32.
; Returns length-4 bytevector. ; Returns length-4 bytevector.
; ;
; Does not depend on endian-ness. ; Does not depend on endian-ness.
@ -16255,7 +16255,7 @@
; Extract the n high-order bits of m. ; Extract the n high-order bits of m.
; m may be an exact integer or a length-4 bytevector. ; m may be an exact integer or a length-4 bytevector.
; n must be an exact nonnegative integer, interpreted modulo 33. ; n must be an exact non-negative integer, interpreted modulo 33.
; Returns length-4 bytevector with the high-order bits of m at low end. ; Returns length-4 bytevector with the high-order bits of m at low end.
; ;
; Does not depend on endian-ness. ; Does not depend on endian-ness.
@ -16553,7 +16553,7 @@
; ;
; version a fixnum (constant) - heap type version number ; version a fixnum (constant) - heap type version number
; roots an assoc list that maps root names to values ; roots an assoc list that maps root names to values
; top an exact nonnegative integer: the address of the ; top an exact non-negative integer: the address of the
; next byte to be emitted ; next byte to be emitted
; symbol-table a symbol table abstract data type ; symbol-table a symbol table abstract data type
; extra any value - a client-extension field ; extra any value - a client-extension field
@ -20735,7 +20735,7 @@
; Strings ; Strings
; RESULT must have nonnegative fixnum. ; RESULT must have non-negative fixnum.
; RS2 must have character. ; RS2 must have character.
(define-primop 'make-string (define-primop 'make-string
@ -23056,7 +23056,7 @@
; A `decoded-instruction' is a list where the car is a mnemonic and ; A `decoded-instruction' is a list where the car is a mnemonic and
; the operands are appropriate for that mnemonic. ; the operands are appropriate for that mnemonic.
; ;
; A `mnemonic' is an exact nonnegative integer. It encodes the name of ; A `mnemonic' is an exact non-negative integer. It encodes the name of
; the instruction as well as its attributes (operand pattern and instruction ; the instruction as well as its attributes (operand pattern and instruction
; type). See below for specific operations on mnemonics. ; type). See below for specific operations on mnemonics.

4
libguile/gc.h
View file

@ -194,7 +194,7 @@ scm_double_cell (scm_t_bits car, scm_t_bits cbr,
advantage of strict C aliasing rules which say that it's OK to advantage of strict C aliasing rules which say that it's OK to
interchange the initialization above and the one below when the interchange the initialization above and the one below when the
pointer types appear to differ sufficiently. We don't want that, pointer types appear to differ sufficiently. We don't want that,
of course. GCC allows this behaviour to be disabled with the of course. GCC allows this behavior to be disabled with the
-fno-strict-aliasing option, but would also need to be supplied -fno-strict-aliasing option, but would also need to be supplied
by Guile users. Instead, the following statements prevent the by Guile users. Instead, the following statements prevent the
reordering. reordering.
@ -227,7 +227,7 @@ scm_words (scm_t_bits car, uint32_t n_words)
advantage of strict C aliasing rules which say that it's OK to advantage of strict C aliasing rules which say that it's OK to
interchange the initialization above and the one below when the interchange the initialization above and the one below when the
pointer types appear to differ sufficiently. We don't want that, pointer types appear to differ sufficiently. We don't want that,
of course. GCC allows this behaviour to be disabled with the of course. GCC allows this behavior to be disabled with the
-fno-strict-aliasing option, but would also need to be supplied -fno-strict-aliasing option, but would also need to be supplied
by Guile users. Instead, the following statements prevent the by Guile users. Instead, the following statements prevent the
reordering. reordering.

2
libguile/ioext.c
View file

@ -77,7 +77,7 @@ SCM_DEFINE (scm_redirect_port, "redirect-port", 2, 0, 0,
"After the redirection the two ports will share a file position\n" "After the redirection the two ports will share a file position\n"
"and file status flags.\n\n" "and file status flags.\n\n"
"The return value is unspecified.\n\n" "The return value is unspecified.\n\n"
"Unexpected behaviour can result if both ports are subsequently used\n" "Unexpected behavior can result if both ports are subsequently used\n"
"and the original and/or duplicate ports are buffered.\n\n" "and the original and/or duplicate ports are buffered.\n\n"
"This procedure does not have any side effects on other ports or\n" "This procedure does not have any side effects on other ports or\n"
"revealed counts.") "revealed counts.")

2
libguile/list.c
View file

@ -308,7 +308,7 @@ SCM_DEFINE (scm_append_x, "append!", 0, 0, 1,
SCM_DEFINE (scm_last_pair, "last-pair", 1, 0, 0, SCM_DEFINE (scm_last_pair, "last-pair", 1, 0, 0,
(SCM lst), (SCM lst),
"Return the last pair in @var{lst}, signalling an error if\n" "Return the last pair in @var{lst}, signaling an error if\n"
"@var{lst} is circular.") "@var{lst} is circular.")
#define FUNC_NAME s_scm_last_pair #define FUNC_NAME s_scm_last_pair
{ {

2
libguile/options.c
View file

@ -55,7 +55,7 @@
* Some definitions: * Some definitions:
* *
* Run time options in Guile are arranged in groups. Each group * Run time options in Guile are arranged in groups. Each group
* affects a certain aspect of the behaviour of the library. * affects a certain aspect of the behavior of the library.
* *
* An "options interface procedure" manages one group of options. It * An "options interface procedure" manages one group of options. It
* can be used to check or set options, or to get documentation for * can be used to check or set options, or to get documentation for

6
libguile/posix.c
View file

@ -389,7 +389,7 @@ SCM_DEFINE (scm_setgroups, "setgroups", 1, 0, 0,
SCM_DEFINE (scm_getpwuid, "getpw", 0, 1, 0, SCM_DEFINE (scm_getpwuid, "getpw", 0, 1, 0,
(SCM user), (SCM user),
"Look up an entry in the user database. @var{user} can be an\n" "Look up an entry in the user database. @var{user} can be an\n"
"integer, a string, or omitted, giving the behaviour of\n" "integer, a string, or omitted, giving the behavior of\n"
"@code{getpwuid}, @code{getpwnam} or @code{getpwent}\n" "@code{getpwuid}, @code{getpwnam} or @code{getpwent}\n"
"respectively.") "respectively.")
#define FUNC_NAME s_scm_getpwuid #define FUNC_NAME s_scm_getpwuid
@ -459,7 +459,7 @@ SCM_DEFINE (scm_setpwent, "setpw", 0, 1, 0,
SCM_DEFINE (scm_getgrgid, "getgr", 0, 1, 0, SCM_DEFINE (scm_getgrgid, "getgr", 0, 1, 0,
(SCM name), (SCM name),
"Look up an entry in the group database. @var{name} can be an\n" "Look up an entry in the group database. @var{name} can be an\n"
"integer, a string, or omitted, giving the behaviour of\n" "integer, a string, or omitted, giving the behavior of\n"
"@code{getgrgid}, @code{getgrnam} or @code{getgrent}\n" "@code{getgrgid}, @code{getgrnam} or @code{getgrent}\n"
"respectively.") "respectively.")
#define FUNC_NAME s_scm_getgrgid #define FUNC_NAME s_scm_getgrgid
@ -725,7 +725,7 @@ SCM_DEFINE (scm_waitpid, "waitpid", 1, 1, 0,
"has terminated or (optionally) stopped. Normally it will\n" "has terminated or (optionally) stopped. Normally it will\n"
"suspend the calling process until this can be done. If more than one\n" "suspend the calling process until this can be done. If more than one\n"
"child process is eligible then one will be chosen by the operating system.\n\n" "child process is eligible then one will be chosen by the operating system.\n\n"
"The value of @var{pid} determines the behaviour:\n\n" "The value of @var{pid} determines the behavior:\n\n"
"@table @r\n" "@table @r\n"
"@item @var{pid} greater than 0\n" "@item @var{pid} greater than 0\n"
"Request status information from the specified child process.\n" "Request status information from the specified child process.\n"

2
libguile/threads.c
View file

@ -902,7 +902,7 @@ enum scm_mutex_kind {
/* An unowned mutex is like a standard mutex, except that it can be /* An unowned mutex is like a standard mutex, except that it can be
unlocked by any thread. A corrolary of this behavior is that a unlocked by any thread. A corrolary of this behavior is that a
thread's attempt to lock a mutex that it already owns will block thread's attempt to lock a mutex that it already owns will block
instead of signalling an error, as it could be that some other instead of signaling an error, as it could be that some other
thread unlocks the mutex, allowing the owner thread to proceed. thread unlocks the mutex, allowing the owner thread to proceed.
This kind of mutex is a bit strange and is here for use by This kind of mutex is a bit strange and is here for use by
SRFI-18. */ SRFI-18. */

10
module/ice-9/boot-9.scm
View file

@ -2750,8 +2750,8 @@ are not themselves bound to a defined value."
(define (module-symbol-local-binding m v . opt-val) (define (module-symbol-local-binding m v . opt-val)
"Return the binding of variable V specified by name within module M, "Return the binding of variable V specified by name within module M,
signalling an error if the variable is unbound. If the OPT-VALUE is signaling an error if the variable is unbound. If the OPT-VALUE is
passed, then instead of signalling an error, return OPT-VALUE." passed, then instead of signaling an error, return OPT-VALUE."
(let ((var (module-local-variable m v))) (let ((var (module-local-variable m v)))
(if (and var (variable-bound? var)) (if (and var (variable-bound? var))
(variable-ref var) (variable-ref var)
@ -2761,8 +2761,8 @@ passed, then instead of signalling an error, return OPT-VALUE."
(define (module-symbol-binding m v . opt-val) (define (module-symbol-binding m v . opt-val)
"Return the binding of variable V specified by name within module M, "Return the binding of variable V specified by name within module M,
signalling an error if the variable is unbound. If the OPT-VALUE is signaling an error if the variable is unbound. If the OPT-VALUE is
passed, then instead of signalling an error, return OPT-VALUE." passed, then instead of signaling an error, return OPT-VALUE."
(let ((var (module-variable m v))) (let ((var (module-variable m v)))
(if (and var (variable-bound? var)) (if (and var (variable-bound? var))
(variable-ref var) (variable-ref var)
@ -3452,7 +3452,7 @@ error if selected binding does not exist in the used module."
;; FIXME: Avoid use of `apply'. ;; FIXME: Avoid use of `apply'.
(apply module-autoload! module autoloads) (apply module-autoload! module autoloads)
(let ((duplicates (or duplicates (let ((duplicates (or duplicates
;; Avoid stompling a previously installed ;; Avoid stomping a previously installed
;; duplicates handlers if possible. ;; duplicates handlers if possible.
(and (not (module-duplicates-handlers module)) (and (not (module-duplicates-handlers module))
;; Note: If you change this default, ;; Note: If you change this default,

2
module/ice-9/optargs.scm
View file

@ -196,7 +196,7 @@
;; ;;
;; lambda* creates a procedure that takes optional arguments. These ;; lambda* creates a procedure that takes optional arguments. These
;; are specified by putting them inside brackets at the end of the ;; are specified by putting them inside brackets at the end of the
;; paramater list, but before any dotted rest argument. For example, ;; parameter list, but before any dotted rest argument. For example,
;; (lambda* (a b #:optional c d . e) '()) ;; (lambda* (a b #:optional c d . e) '())
;; creates a procedure with fixed arguments a and b, optional arguments c ;; creates a procedure with fixed arguments a and b, optional arguments c
;; and d, and rest argument e. If the optional arguments are omitted ;; and d, and rest argument e. If the optional arguments are omitted

2
module/ice-9/ports.scm
View file

@ -461,7 +461,7 @@ never again be used for a read or write operation."
(define* (call-with-output-file file proc #:key (binary #f) (encoding #f)) (define* (call-with-output-file file proc #:key (binary #f) (encoding #f))
"PROC should be a procedure of one argument, and FILE should be a "PROC should be a procedure of one argument, and FILE should be a
string naming a file. The behaviour is unspecified if the file string naming a file. The behavior is unspecified if the file
already exists. These procedures call PROC already exists. These procedures call PROC
with one argument: the port obtained by opening the named file for with one argument: the port obtained by opening the named file for
input or output. If the file cannot be opened, an error is input or output. If the file cannot be opened, an error is

2
module/ice-9/pretty-print.scm
View file

@ -320,7 +320,7 @@ into @var{width} characters. By default, @var{x} will be printed using
@code{write}, though that behavior can be overriden via the @code{write}, though that behavior can be overriden via the
@var{display?} keyword argument. @var{display?} keyword argument.
The default behaviour is to print depth-first, meaning that the entire The default behavior is to print depth-first, meaning that the entire
remaining width will be available to each sub-expression of @var{x} -- 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 e.g., if @var{x} is a vector, each member of @var{x}. One can attempt to
\"ration\" the available width, trying to allocate it equally to each \"ration\" the available width, trying to allocate it equally to each

2
module/ice-9/psyntax.scm
View file

@ -481,7 +481,7 @@
;; (lexical . <var>) lexical variables ;; (lexical . <var>) lexical variables
;; (ellipsis . <identifier>) custom ellipsis ;; (ellipsis . <identifier>) custom ellipsis
;; (displaced-lexical) displaced lexicals ;; (displaced-lexical) displaced lexicals
;; <level> ::= <nonnegative integer> ;; <level> ::= <non-negative integer>
;; <var> ::= variable returned by build-lexical-var ;; <var> ::= variable returned by build-lexical-var
;; a macro is a user-defined syntactic-form. a core is a ;; a macro is a user-defined syntactic-form. a core is a

2
module/language/elisp/parser.scm
View file

@ -37,7 +37,7 @@
;;; For parsing circular structures, we keep track of definitions in a ;;; For parsing circular structures, we keep track of definitions in a
;;; hash-map that maps the id's to their values. When defining a new ;;; hash-map that maps the id's to their values. When defining a new
;;; id, though, we immediatly fill the slot with a promise before ;;; id, though, we immediately fill the slot with a promise before
;;; parsing and setting the real value, because it must already be ;;; parsing and setting the real value, because it must already be
;;; available at that time in case of a circular reference. The promise ;;; available at that time in case of a circular reference. The promise
;;; refers to a local variable that will be set when the real value is ;;; refers to a local variable that will be set when the real value is

4
module/language/tree-il/compile-bytecode.scm
View file

@ -1124,7 +1124,7 @@ in the frame with for the lambda-case clause @var{clause}."
(0 (0
(emit-load-static-procedure asm dst label)) (emit-load-static-procedure asm dst label))
(nfree (nfree
;; Stage closure in 0 to avoid stompling captured free ;; Stage closure in 0 to avoid stomping captured free
;; vars. ;; vars.
(emit-allocate-closure asm 0 nfree label 1) (emit-allocate-closure asm 0 nfree label 1)
(init-free-vars 0 free-vars env 1 2) (init-free-vars 0 free-vars env 1 2)
@ -1148,7 +1148,7 @@ in the frame with for the lambda-case clause @var{clause}."
frame-size))) frame-size)))
(($ <primcall> src (? variadic-constructor? name) args) (($ <primcall> src (? variadic-constructor? name) args)
;; Stage result in 0 to avoid stompling args. ;; Stage result in 0 to avoid stomping args.
(let ((args (for-args args env))) (let ((args (for-args args env)))
(maybe-emit-source src) (maybe-emit-source src)
(match name (match name

2
module/srfi/srfi-37.scm
View file

@ -84,7 +84,7 @@
(define (build-options-lookup options) (define (build-options-lookup options)
"Answer an `equal?' Guile hash-table that maps OPTIONS' names back "Answer an `equal?' Guile hash-table that maps OPTIONS' names back
to the containing options, signalling an error if a name is to the containing options, signaling an error if a name is
encountered more than once." encountered more than once."
(let ((lookup (make-hash-table (* 2 (length options))))) (let ((lookup (make-hash-table (* 2 (length options)))))
(for-each (for-each

12
module/srfi/srfi-43.scm
View file

@ -546,7 +546,7 @@ left-to-right."
(define vector-count (define vector-count
(case-lambda (case-lambda
"(vector-count pred? vec1 vec2 ...) -> exact nonnegative integer "(vector-count pred? vec1 vec2 ...) -> exact non-negative integer
Count the number of indices i for which (PRED? VEC1[i] VEC2[i] ...) Count the number of indices i for which (PRED? VEC1[i] VEC2[i] ...)
returns true, where i is less than the length of the shortest vector returns true, where i is less than the length of the shortest vector
@ -586,7 +586,7 @@ passed."
(define vector-index (define vector-index
(case-lambda (case-lambda
"(vector-index pred? vec1 vec2 ...) -> exact nonnegative integer or #f "(vector-index pred? vec1 vec2 ...) -> exact non-negative integer or #f
Find and return the index of the first elements in VEC1 VEC2 ... that Find and return the index of the first elements in VEC1 VEC2 ... that
satisfy PRED?. If no matching element is found by the end of the satisfy PRED?. If no matching element is found by the end of the
@ -624,7 +624,7 @@ shortest vector, return #f."
(define vector-index-right (define vector-index-right
(case-lambda (case-lambda
"(vector-index-right pred? vec1 vec2 ...) -> exact nonnegative integer or #f "(vector-index-right pred? vec1 vec2 ...) -> exact non-negative integer or #f
Find and return the index of the last elements in VEC1 VEC2 ... that Find and return the index of the last elements in VEC1 VEC2 ... that
satisfy PRED?, searching from right-to-left. If no matching element satisfy PRED?, searching from right-to-left. If no matching element
@ -662,7 +662,7 @@ is found before the end of the shortest vector, return #f."
(define vector-skip (define vector-skip
(case-lambda (case-lambda
"(vector-skip pred? vec1 vec2 ...) -> exact nonnegative integer or #f "(vector-skip pred? vec1 vec2 ...) -> exact non-negative integer or #f
Find and return the index of the first elements in VEC1 VEC2 ... that Find and return the index of the first elements in VEC1 VEC2 ... that
do not satisfy PRED?. If no matching element is found by the end of do not satisfy PRED?. If no matching element is found by the end of
@ -700,7 +700,7 @@ the shortest vector, return #f."
(define vector-skip-right (define vector-skip-right
(case-lambda (case-lambda
"(vector-skip-right pred? vec1 vec2 ...) -> exact nonnegative integer or #f "(vector-skip-right pred? vec1 vec2 ...) -> exact non-negative integer or #f
Find and return the index of the last elements in VEC1 VEC2 ... that Find and return the index of the last elements in VEC1 VEC2 ... that
do not satisfy PRED?, searching from right-to-left. If no matching do not satisfy PRED?, searching from right-to-left. If no matching
@ -748,7 +748,7 @@ element is found before the end of the shortest vector, return #f."
((positive? c) (loop lo i)) ((positive? c) (loop lo i))
((negative? c) (loop (+ i 1) hi))))))) ((negative? c) (loop (+ i 1) hi)))))))
(case-lambda (case-lambda
"(vector-binary-search vec value cmp [start [end]]) -> exact nonnegative integer or #f "(vector-binary-search vec value cmp [start [end]]) -> exact non-negative integer or #f
Find and return an index of VEC between START and END whose value is Find and return an index of VEC between START and END whose value is
VALUE using a binary search. If no matching element is found, return VALUE using a binary search. If no matching element is found, return

2
module/statprof.scm
View file

@ -319,7 +319,7 @@ than @code{statprof-stop}, @code{#f} otherwise."
;; Do not call this from statprof internal functions -- user only. ;; Do not call this from statprof internal functions -- user only.
(define* (statprof-stop #:optional (state (ensure-profiler-state))) (define* (statprof-stop #:optional (state (ensure-profiler-state)))
"Stop the profiler.@code{}" "Stop the profiler."
;; After some head-scratching, I don't *think* I need to mask/unmask ;; After some head-scratching, I don't *think* I need to mask/unmask
;; signals here, but if I'm wrong, please let me know. ;; signals here, but if I'm wrong, please let me know.
(set-profile-level! state (- (profile-level state) 1)) (set-profile-level! state (- (profile-level state) 1))

2
module/texinfo/reflection.scm
View file

@ -20,7 +20,7 @@
;;; Commentary: ;;; Commentary:
;; ;;
;;Routines to generare @code{stexi} documentation for objects and ;;Routines to generate @code{stexi} documentation for objects and
;;modules. ;;modules.
;; ;;
;;Note that in this context, an @dfn{object} is just a value associated ;;Note that in this context, an @dfn{object} is just a value associated

4
test-suite/tests/eval.test
View file

@ -476,7 +476,7 @@
(call-with-stack-overflow-handler 2.0 (call-with-stack-overflow-handler 2.0
trigger-overflow trigger-overflow)) trigger-overflow trigger-overflow))
(pass-if-exception "limit should be nonnegative" (pass-if-exception "limit should be non-negative"
exception:out-of-range exception:out-of-range
(call-with-stack-overflow-handler -1 (call-with-stack-overflow-handler -1
trigger-overflow trigger-overflow)) trigger-overflow trigger-overflow))
@ -517,7 +517,7 @@
(call-with-stack-overflow-handler 1000 (call-with-stack-overflow-handler 1000
trigger-overflow trigger-overflow
(lambda () 2.0))) (lambda () 2.0)))
(pass-if-exception "overflow handler should be nonnegative" (pass-if-exception "overflow handler should be non-negative"
exception:out-of-range exception:out-of-range
(call-with-stack-overflow-handler 1000 (call-with-stack-overflow-handler 1000
trigger-overflow trigger-overflow

2
test-suite/tests/fluids.test
View file

@ -140,7 +140,7 @@
(gc) (gc)
(fluid? (g)))) (fluid? (g))))
(pass-if-exception "fluid-ref* depth must be nonnegative" (pass-if-exception "fluid-ref* depth must be non-negative"
exception:out-of-range exception:out-of-range
(fluid-ref* (make-fluid) -1)) (fluid-ref* (make-fluid) -1))