summaryrefslogtreecommitdiff
path: root/doc/ref
diff options
context:
space:
mode:
authorLudovic Courtès <ludo@gnu.org>2008-09-10 22:33:40 +0200
committerLudovic Courtès <ludo@gnu.org>2008-09-10 22:33:40 +0200
commit4a4849dbe0ae1b731b408167f90222e05d1ca2bd (patch)
treecaa909b99ffb221e43408a3d19ad3e8209e3a96b /doc/ref
parent3ec17f28b8f96fa43218db83656c0d85b4f69d7c (diff)
parent032913739218c756f673bfb9c8f66ef9f8f02330 (diff)
downloadguile-4a4849dbe0ae1b731b408167f90222e05d1ca2bd.tar.gz
Merge commit '032913739218c756f673bfb9c8f66ef9f8f02330' into boehm-demers-weiser-gc
Conflicts: libguile/gc.c libguile/srcprop.c libguile/srcprop.h
Diffstat (limited to 'doc/ref')
-rw-r--r--doc/ref/ChangeLog52
-rw-r--r--doc/ref/api-control.texi2
-rwxr-xr-xdoc/ref/api-data.texi8
-rw-r--r--doc/ref/api-debug.texi23
-rw-r--r--doc/ref/api-evaluation.texi3
-rw-r--r--doc/ref/api-i18n.texi443
-rw-r--r--doc/ref/api-init.texi6
-rw-r--r--doc/ref/api-options.texi15
-rw-r--r--doc/ref/api-procedures.texi90
-rw-r--r--doc/ref/posix.texi76
-rw-r--r--doc/ref/srfi-modules.texi86
11 files changed, 599 insertions, 205 deletions
diff --git a/doc/ref/ChangeLog b/doc/ref/ChangeLog
index 8b8e0befe..c09bc96d0 100644
--- a/doc/ref/ChangeLog
+++ b/doc/ref/ChangeLog
@@ -1,3 +1,55 @@
+2007-01-31 Ludovic Courtès <ludovic.courtes@laas.fr>
+
+ * api-data.texi (Conversion): Made cross refs point to `Number
+ Input and Output' rather than `The ice-9 i18n Module'.
+ (String Comparison): Likewise for `Text Collation'.
+ * api-i18n.texi (Internationalization): Re-organized the whole
+ section, documented new i18n features. Added the following
+ subsections: `i18n Introduction', `Text Collation', `Character
+ Case Mapping', `Number Input and Output', `Accessing Locale
+ Information'. Removed `The ice-9 i18n Module'.
+ * posix.texi (Locales): Updated cross-ref formerly pointing to
+ `The ice-9 i18n Module'.
+ * srfi-modules.texi (SRFI-19 String to date): Mention the
+ internationalization of `string->date'.
+
+2007-01-19 Han-Wen Nienhuys <hanwen@lilypond.org>
+
+ * api-options.texi (Evaluator trap options): document
+ memoize-symbol-handler
+
+ * api-evaluation.texi (Evaluator Behaviour): link to the Evaluator
+ trap options node in trap-enable/trap-set! doco.
+
+2007-01-16 Kevin Ryde <user42@zip.com.au>
+
+ * api-data.texi (Mapping Folding and Unfolding): In string-unfold,
+ ssay make_final default is nothing extra. The `(lambda (x) )' shown
+ was not quite right, it would have been `(lambda (x) "")' if anything.
+
+ * api-init.texi (Initialization): Cross reference Runtime Environment
+ for scm_set_program_arguments.
+
+ * posix.texi (Runtime Environment): Expand program-arguments
+ description, add set-program-arguments, add scm_set_program_arguments,
+ note args are per-thread.
+
+2006-12-14 Kevin Ryde <user42@zip.com.au>
+
+ * api-procedures.texi (let-keywords Reference): Expand variously to
+ make it clear what's actually taken and done. Shortfalls reported by
+ Han-Wen Nienhuys.
+
+2006-12-13 Kevin Ryde <user42@zip.com.au>
+
+ * api-control.texi (Handling Errors): Cross reference "Error
+ Reporting" for `scm-error', not just "above".
+
+ * posix.texi (Encryption): Cross reference crypt in the glibc manual.
+ Clarify that key and salt are strings.
+
+ * srfi-modules.texi (SRFI-17): Expand variously.
+
2006-11-18 Ludovic Courtès <ludovic.courtes@laas.fr>
* Makefile.am (BUILT_SOURCES): New variable.
diff --git a/doc/ref/api-control.texi b/doc/ref/api-control.texi
index 11a276a13..512733cd5 100644
--- a/doc/ref/api-control.texi
+++ b/doc/ref/api-control.texi
@@ -1476,7 +1476,7 @@ In the following C functions, @var{SUBR} and @var{MESSAGE} parameters
can be @code{NULL} to give the effect of @code{#f} described above.
@deftypefn {C Function} SCM scm_error (SCM @var{key}, char *@var{subr}, char *@var{message}, SCM @var{args}, SCM @var{rest})
-Throw an error, as per @code{scm-error} above.
+Throw an error, as per @code{scm-error} (@pxref{Error Reporting}).
@end deftypefn
@deftypefn {C Function} void scm_syserror (char *@var{subr})
diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi
index abcb28de1..df913b2cd 100755
--- a/doc/ref/api-data.texi
+++ b/doc/ref/api-data.texi
@@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@@ -1015,7 +1015,7 @@ zero.
The following procedures read and write numbers according to their
external representation as defined by R5RS (@pxref{Lexical structure,
R5RS Lexical Structure,, r5rs, The Revised^5 Report on the Algorithmic
-Language Scheme}). @xref{The ice-9 i18n Module, the @code{(ice-9
+Language Scheme}). @xref{Number Input and Output, the @code{(ice-9
i18n)} module}, for locale-dependent number parsing.
@deffn {Scheme Procedure} number->string n [radix]
@@ -2949,7 +2949,7 @@ predicates (@pxref{Characters}), but are defined on character sequences.
The first set is specified in R5RS and has names that end in @code{?}.
The second set is specified in SRFI-13 and the names have no ending
@code{?}. The predicates ending in @code{-ci} ignore the character case
-when comparing strings. @xref{The ice-9 i18n Module, the @code{(ice-9
+when comparing strings. @xref{Text Collation, the @code{(ice-9
i18n)} module}, for locale-dependent string comparison.
@rnindex string=?
@@ -3525,7 +3525,7 @@ string.
@item @var{make_final} is applied to the terminal seed
value (on which @var{p} returns true) to produce
the final/rightmost portion of the constructed string.
-It defaults to @code{(lambda (x) )}.
+The default is nothing extra.
@end itemize
@end deffn
diff --git a/doc/ref/api-debug.texi b/doc/ref/api-debug.texi
index 5f816dc46..68c202266 100644
--- a/doc/ref/api-debug.texi
+++ b/doc/ref/api-debug.texi
@@ -615,14 +615,21 @@ Invoke the Guile debugger to explore the context of the last error.
@cindex Low level trap calls
@cindex Evaluator trap calls
-Guile's evaluator can be configured to call three user-specified
-procedures at various points in its operation: an
-@dfn{apply-frame-handler} procedure, an @dfn{enter-frame-handler}
-procedure, and an @dfn{exit-frame-handler} procedure. These procedures,
-and the circumstances under which the evaluator calls them, are
-configured by the ``evaluator trap options'' interface (@pxref{Evaluator
-trap options}), and by the @code{trace} and @code{breakpoints} fields of
-the ``debug options'' interface (@pxref{Debugger options}).
+Guile's evaluator can be configured to call the following four user-specified
+procedures at various points in its operation.
+
+@table @dfn
+@item apply-frame-handler
+@item enter-frame-handler
+@item exit-frame-handler
+@item memoize-symbol-handler
+@end table
+
+These procedures, and the circumstances under which the evaluator
+calls them, are configured by the ``evaluator trap options'' interface
+(@pxref{Evaluator trap options}), and by the @code{trace} and
+@code{breakpoints} fields of the ``debug options'' interface
+(@pxref{Debugger options}).
It is not necessary to understand the fine details of these low level
calls, and of the options which configure them, in order to use the
diff --git a/doc/ref/api-evaluation.texi b/doc/ref/api-evaluation.texi
index 1da13de43..6fd363df2 100644
--- a/doc/ref/api-evaluation.texi
+++ b/doc/ref/api-evaluation.texi
@@ -629,6 +629,9 @@ Like @code{help}, but also print programmer options.
Modify the evaluator options. @code{trap-enable} should be used with boolean
options and switches them on, @code{trap-disable} switches them off.
@code{trap-set!} can be used to set an option to a specific value.
+
+See @ref{Evaluator trap options} for more information on the available
+trap handlers.
@end deffn
@deffn {Scheme Procedure} evaluator-traps-interface [setting]
diff --git a/doc/ref/api-i18n.texi b/doc/ref/api-i18n.texi
index 1927a755b..be5afe4f9 100644
--- a/doc/ref/api-i18n.texi
+++ b/doc/ref/api-i18n.texi
@@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@@ -11,24 +11,29 @@
@cindex internationalization
@cindex i18n
-Guile provides internationalization support for Scheme programs in two
-ways. First, procedures to manipulate text and data in a way that
-conforms to particular cultural conventions (i.e., in a
-``locale-dependent'' way) are provided in the @code{(ice-9 i18n)}.
-Second, Guile allows the use of GNU @code{gettext} to translate
-program message strings.
+Guile provides internationalization@footnote{For concision and style,
+programmers often like to refer to internationalization as ``i18n''.}
+support for Scheme programs in two ways. First, procedures to
+manipulate text and data in a way that conforms to particular cultural
+conventions (i.e., in a ``locale-dependent'' way) are provided in the
+@code{(ice-9 i18n)}. Second, Guile allows the use of GNU
+@code{gettext} to translate program message strings.
@menu
-* The ice-9 i18n Module:: Honoring cultural conventions.
-* Gettext Support:: Translating message strings.
+* i18n Introduction:: Introduction to Guile's i18n support.
+* Text Collation:: Sorting strings and characters.
+* Character Case Mapping:: Case mapping.
+* Number Input and Output:: Parsing and printing numbers.
+* Accessing Locale Information:: Detailed locale information.
+* Gettext Support:: Translating message strings.
@end menu
-@node The ice-9 i18n Module
-@subsection The @code{(ice-9 i18n)} Module
+@node i18n Introduction, Text Collation, Internationalization, Internationalization
+@subsection Internationalization with Guile
-In order to make use of the following functions, one must import the
-@code{(ice-9 i18n)} module in the usual way:
+In order to make use of the functions described thereafter, the
+@code{(ice-9 i18n)} module must be imported in the usual way:
@example
(use-modules (ice-9 i18n))
@@ -64,83 +69,41 @@ the user is defined by the @code{LC_MESSAGES} category
The procedures provided by this module allow the development of
programs that adapt automatically to any locale setting. As we will
-see later, many of the locale-dependent procedures provided by this
-module can optionally take a @dfn{locale object} argument. This
-additional argument defines the locale settings that must be followed
-by the invoked procedure. When it is omitted, then the current locale
-settings of the process are followed (@pxref{Locales,
-@code{setlocale}}).
+see later, many of these procedures can optionally take a @dfn{locale
+object} argument. This additional argument defines the locale
+settings that must be followed by the invoked procedure. When it is
+omitted, then the current locale settings of the process are followed
+(@pxref{Locales, @code{setlocale}}).
The following procedures allow the manipulation of such locale
objects.
-@deffn {Scheme Procedure} make-locale category-mask locale-name [base-locale]
-@deffnx {C Function} scm_make_locale (category_mask, locale_name, base_locale)
+@deffn {Scheme Procedure} make-locale category-list locale-name [base-locale]
+@deffnx {C Function} scm_make_locale (category_list, locale_name, base_locale)
Return a reference to a data structure representing a set of locale
datasets. @var{locale-name} should be a string denoting a particular
-locale, e.g., @code{"aa_DJ"}. Unlike for the @var{category} parameter
-for @code{setlocale}, the @var{category-mask} parameter here uses a
-single bit for each category, made by OR'ing together @code{LC_*_MASK}
-bits. The optional @var{base-locale} argument can be used to specify
-a locale object whose settings are to be used as a basis for the
-locale object being returned.
-
-The available locale category masks are the following:
-
-@defvar LC_COLLATE_MASK
-Represents the collation locale category.
-@end defvar
-@defvar LC_CTYPE_MASK
-Represents the character classification locale category.
-@end defvar
-@defvar LC_MESSAGES_MASK
-Represents the messages locale category.
-@end defvar
-@defvar LC_MONETARY_MASK
-Represents the monetary locale category.
-@end defvar
-@defvar LC_NUMERIC_MASK
-Represents the way numbers are displayed.
-@end defvar
-@defvar LC_TIME_MASK
-Represents the way date and time are displayed
-@end defvar
-
-The following category masks are also available but will not have any
-effect on systems that do not support them:
-
-@defvar LC_PAPER_MASK
-@defvarx LC_NAME_MASK
-@defvarx LC_ADDRESS_MASK
-@defvarx LC_TELEPHONE_MASK
-@defvarx LC_MEASUREMENT_MASK
-@defvarx LC_IDENTIFICATION_MASK
-@end defvar
-
-Finally, there is also:
-
-@defvar LC_ALL_MASK
-This represents all the locale categories supported by the system.
-@end defvar
-
-The @code{LC_*_MASK} variables are bound to integers which may be OR'd
-together using @code{logior} (@pxref{Primitive Numerics,
-@code{logior}}). For instance, the following invocation creates a
-locale object that combines the use of Esperanto for messages and
-character classification with the default settings for the other
-categories (i.e., the settings of the default @code{C} locale which
-usually represents conventions in use in the USA):
+locale (e.g., @code{"aa_DJ"}) and @var{category-list} should be either
+a list of locale categories or a single category as used with
+@code{setlocale} (@pxref{Locales, @code{setlocale}}). Optionally, if
+@code{base-locale} is passed, it should be a locale object denoting
+settings for categories not listed in @var{category-list}.
+
+The following invocation creates a locale object that combines the use
+of Swedish for messages and character classification with the
+default settings for the other categories (i.e., the settings of the
+default @code{C} locale which usually represents conventions in use in
+the USA):
@example
-(make-locale (logior LC_MESSAGE_MASK LC_CTYPE_MASK) "eo_EO")
+(make-locale (list LC_MESSAGE LC_CTYPE) "sv_SE")
@end example
-The following example combines the use of Swedish conventions with
-monetary conventions from Croatia:
+The following example combines the use of Esperanto messages and
+conventions with monetary conventions from Croatia:
@example
-(make-locale LC_MONETARY_MASK "hr_HR"
- (make-locale LC_ALL_MASK "sv_SE"))
+(make-locale LC_MONETARY "hr_HR"
+ (make-locale LC_ALL "eo_EO"))
@end example
A @code{system-error} exception (@pxref{Handling Errors}) is raised by
@@ -155,70 +118,56 @@ error may be raised later, when the locale object is actually used.
Return true if @var{obj} is a locale object.
@end deffn
-The following procedures provide support for text collation.
+@defvr {Scheme Variable} %global-locale
+@defvrx {C Variable} scm_global_locale
+This variable is bound to a locale object denoting the current process
+locale as installed using @code{setlocale ()} (@pxref{Locales}). It
+may be used like any other locale object, including as a third
+argument to @code{make-locale}, for instance.
+@end defvr
+
+
+@node Text Collation, Character Case Mapping, i18n Introduction, Internationalization
+@subsection Text Collation
+
+The following procedures provide support for text collation, i.e.,
+locale-dependent string and character sorting.
@deffn {Scheme Procedure} string-locale<? s1 s2 [locale]
@deffnx {C Function} scm_string_locale_lt (s1, s2, locale)
-Compare strings @var{s1} and @var{s2} in a locale-dependent way. If
-@var{locale} is provided, it should be locale object (as returned by
-@code{make-locale}) and will be used to perform the comparison;
-otherwise, the current system locale is used.
-@end deffn
-
-@deffn {Scheme Procedure} string-locale>? s1 s2 [locale]
+@deffnx {Scheme Procedure} string-locale>? s1 s2 [locale]
@deffnx {C Function} scm_string_locale_gt (s1, s2, locale)
+@deffnx {Scheme Procedure} string-locale-ci<? s1 s2 [locale]
+@deffnx {C Function} scm_string_locale_ci_lt (s1, s2, locale)
+@deffnx {Scheme Procedure} string-locale-ci>? s1 s2 [locale]
+@deffnx {C Function} scm_string_locale_ci_gt (s1, s2, locale)
Compare strings @var{s1} and @var{s2} in a locale-dependent way. If
@var{locale} is provided, it should be locale object (as returned by
@code{make-locale}) and will be used to perform the comparison;
-otherwise, the current system locale is used.
-@end deffn
-
-@deffn {Scheme Procedure} string-locale-ci<? s1 s2 [locale]
-@deffnx {C Function} scm_string_locale_ci_lt (s1, s2, locale)
-Compare strings @var{s1} and @var{s2} in a case-insensitive, and
-locale-dependent way. If @var{locale} is provided, it should be
-locale object (as returned by @code{make-locale}) and will be used to
-perform the comparison; otherwise, the current system locale is used.
-@end deffn
-
-@deffn {Scheme Procedure} string-locale-ci>? s1 s2 [locale]
-@deffnx {C Function} scm_string_locale_ci_gt (s1, s2, locale)
-Compare strings @var{s1} and @var{s2} in a case-insensitive, and
-locale-dependent way. If @var{locale} is provided, it should be
-locale object (as returned by @code{make-locale}) and will be used to
-perform the comparison; otherwise, the current system locale is used.
+otherwise, the current system locale is used. For the @code{-ci}
+variants, the comparison is made in a case-insensitive way.
@end deffn
@deffn {Scheme Procedure} string-locale-ci=? s1 s2 [locale]
@deffnx {C Function} scm_string_locale_ci_eq (s1, s2, locale)
Compare strings @var{s1} and @var{s2} in a case-insensitive, and
locale-dependent way. If @var{locale} is provided, it should be
-locale object (as returned by @code{make-locale}) and will be used to
+a locale object (as returned by @code{make-locale}) and will be used to
perform the comparison; otherwise, the current system locale is used.
@end deffn
@deffn {Scheme Procedure} char-locale<? c1 c2 [locale]
@deffnx {C Function} scm_char_locale_lt (c1, c2, locale)
-Return true if character @var{c1} is lower than @var{c2} according to
-@var{locale} or to the current locale.
-@end deffn
-
-@deffn {Scheme Procedure} char-locale>? c1 c2 [locale]
+@deffnx {Scheme Procedure} char-locale>? c1 c2 [locale]
@deffnx {C Function} scm_char_locale_gt (c1, c2, locale)
-Return true if character @var{c1} is greater than @var{c2} according
-to @var{locale} or to the current locale.
-@end deffn
-
-@deffn {Scheme Procedure} char-locale-ci<? c1 c2 [locale]
+@deffnx {Scheme Procedure} char-locale-ci<? c1 c2 [locale]
@deffnx {C Function} scm_char_locale_ci_lt (c1, c2, locale)
-Return true if character @var{c1} is lower than @var{c2}, in a case
-insensitive way according to @var{locale} or to the current locale.
-@end deffn
-
-@deffn {Scheme Procedure} char-locale-ci>? c1 c2 [locale]
+@deffnx {Scheme Procedure} char-locale-ci>? c1 c2 [locale]
@deffnx {C Function} scm_char_locale_ci_gt (c1, c2, locale)
-Return true if character @var{c1} is greater than @var{c2}, in a case
-insensitive way according to @var{locale} or to the current locale.
+Compare characters @var{c1} and @var{c2} according to either
+@var{locale} (a locale object as returned by @code{make-locale}) or
+the current locale. For the @code{-ci} variants, the comparison is
+made in a case-insensitive way.
@end deffn
@deffn {Scheme Procedure} char-locale-ci=? c1 c2 [locale]
@@ -227,6 +176,9 @@ Return true if character @var{c1} is equal to @var{c2}, in a case
insensitive way according to @var{locale} or to the current locale.
@end deffn
+@node Character Case Mapping, Number Input and Output, Text Collation, Internationalization
+@subsection Character Case Mapping
+
The procedures below provide support for ``character case mapping'',
i.e., to convert characters or strings to their upper-case or
lower-case equivalent. Note that SRFI-13 provides procedures that
@@ -236,8 +188,8 @@ account specificities of the customs in use in a particular language
or region of the world. For instance, while most languages using the
Latin alphabet map lower-case letter ``i'' to upper-case letter ``I'',
Turkish maps lower-case ``i'' to ``Latin capital letter I with dot
-above''. The following procedures allow to provide idiomatic
-character mapping.
+above''. The following procedures allow programmers to provide
+idiomatic character mapping.
@deffn {Scheme Procedure} char-locale-downcase chr [locale]
@deffnx {C Function} scm_char_locale_upcase (chr, locale)
@@ -263,12 +215,20 @@ Return a new string that is the down-case version of @var{str}
according to either @var{locale} or the current locale.
@end deffn
-Finally, the following procedures allow programs to read numbers
+Note that in the current implementation Guile has no notion of
+multibyte characters and in a multibyte locale characters may not be
+converted correctly.
+
+@node Number Input and Output, Accessing Locale Information, Character Case Mapping, Internationalization
+@subsection Number Input and Output
+
+The following procedures allow programs to read and write numbers
written according to a particular locale. As an example, in English,
``ten thousand and a half'' is usually written @code{10,000.5} while
-in French it is written @code{10000,5}. These procedures allow to
-account for these differences.
+in French it is written @code{10 000,5}. These procedures allow such
+differences to be taken into account.
+@findex strtod
@deffn {Scheme Procedure} locale-string->integer str [base [locale]]
@deffnx {C Function} scm_locale_string_to_integer (str, base, locale)
Convert string @var{str} into an integer according to either
@@ -276,22 +236,239 @@ Convert string @var{str} into an integer according to either
the current process locale. If @var{base} is specified, then it
determines the base of the integer being read (e.g., @code{16} for an
hexadecimal number, @code{10} for a decimal number); by default,
-decimal numbers are read. Return two values: an integer (on success)
-or @code{#f}, and the number of characters read from @var{str}
-(@code{0} on failure).
+decimal numbers are read. Return two values (@pxref{Multiple
+Values}): an integer (on success) or @code{#f}, and the number of
+characters read from @var{str} (@code{0} on failure).
+
+This function is based on the C library's @code{strtol} function
+(@pxref{Parsing of Integers, @code{strtol},, libc, The GNU C Library
+Reference Manual}).
@end deffn
+@findex strtod
@deffn {Scheme Procedure} locale-string->inexact str [locale]
@deffnx {C Function} scm_locale_string_to_inexact (str, locale)
Convert string @var{str} into an inexact number according to either
@var{locale} (a locale object as returned by @code{make-locale}) or
-the current process locale. Return two values: an inexact number (on
-success) or @code{#f}, and the number of characters read from
-@var{str} (@code{0} on failure).
+the current process locale. Return two values (@pxref{Multiple
+Values}): an inexact number (on success) or @code{#f}, and the number
+of characters read from @var{str} (@code{0} on failure).
+
+This function is based on the C library's @code{strtod} function
+(@pxref{Parsing of Floats, @code{strtod},, libc, The GNU C Library
+Reference Manual}).
+@end deffn
+
+@deffn {Scheme Procedure} number->locale-string number [fraction-digits [locale]]
+Convert @var{number} (an inexact) into a string according to the
+cultural conventions of either @var{locale} (a locale object) or the
+current locale. Optionally, @var{fraction-digits} may be bound to an
+integer specifying the number of fractional digits to be displayed.
+@end deffn
+
+@deffn {Scheme Procedure} monetary-amount->locale-string amount intl? [locale]
+Convert @var{amount} (an inexact denoting a monetary amount) into a
+string according to the cultural conventions of either @var{locale} (a
+locale object) or the current locale. If @var{intl?} is true, then
+the international monetary format for the given locale is used
+(@pxref{Currency Symbol, international and locale monetary formats,,
+libc, The GNU C Library Reference Manual}).
+@end deffn
+
+
+@node Accessing Locale Information, Gettext Support, Number Input and Output, Internationalization
+@subsection Accessing Locale Information
+
+@findex nl_langinfo
+@cindex low-level locale information
+It is sometimes useful to obtain very specific information about a
+locale such as the word it uses for days or months, its format for
+representing floating-point figures, etc. The @code{(ice-9 i18n)}
+module provides support for this in a way that is similar to the libc
+functions @code{nl_langinfo ()} and @code{localeconv ()}
+(@pxref{Locale Information, accessing locale information from C,,
+libc, The GNU C Library Reference Manual}). The available functions
+are listed below.
+
+@deffn {Scheme Procedure} locale-encoding [locale]
+Return the name of the encoding (a string whose interpretation is
+system-dependent) of either @var{locale} or the current locale.
+@end deffn
+
+The following functions deal with dates and times.
+
+@deffn {Scheme Procedure} locale-day day [locale]
+@deffnx {Scheme Procedure} locale-day-short day [locale]
+@deffnx {Scheme Procedure} locale-month month [locale]
+@deffnx {Scheme Procedure} locale-month-short month [locale]
+Return the word (a string) used in either @var{locale} or the current
+locale to name the day (or month) denoted by @var{day} (or
+@var{month}), an integer between 1 and 7 (or 1 and 12). The
+@code{-short} variants provide an abbreviation instead of a full name.
+@end deffn
+
+@deffn {Scheme Procedure} locale-am-string [locale]
+@deffnx {Scheme Procedure} locale-pm-string [locale]
+Return a (potentially empty) string that is used to denote @i{ante
+meridiem} (or @i{post meridiem}) hours in 12-hour format.
+@end deffn
+
+@deffn {Scheme Procedure} locale-date+time-format [locale]
+@deffnx {Scheme Procedure} locale-date-format [locale]
+@deffnx {Scheme Procedure} locale-time-format [locale]
+@deffnx {Scheme Procedure} locale-time+am/pm-format [locale]
+@deffnx {Scheme Procedure} locale-era-date-format [locale]
+@deffnx {Scheme Procedure} locale-era-date+time-format [locale]
+@deffnx {Scheme Procedure} locale-era-time-format [locale]
+These procedures return format strings suitable to @code{strftime}
+(@pxref{Time}) that may be used to display (part of) a date/time
+according to certain constraints and to the conventions of either
+@var{locale} or the current locale (@pxref{The Elegant and Fast Way,
+the @code{nl_langinfo ()} items,, libc, The GNU C Library Reference
+Manual}).
+@end deffn
+
+@deffn {Scheme Procedure} locale-era [locale]
+@deffnx {Scheme Procedure} locale-era-year [locale]
+These functions return, respectively, the era and the year of the
+relevant era used in @var{locale} or the current locale. Most locales
+do not define this value. In this case, the empty string is returned.
+An example of a locale that does define this value is the Japanese
+one.
@end deffn
+The following procedures give information about number representation.
+
+@deffn {Scheme Procedure} locale-decimal-point [locale]
+@deffnx {Scheme Procedure} locale-thousands-separator [locale]
+These functions return a string denoting the representation of the
+decimal point or that of the thousand separator (respectively) for
+either @var{locale} or the current locale.
+@end deffn
+
+@deffn {Scheme Procedure} locale-digit-grouping [locale]
+Return a (potentially circular) list of integers denoting how digits
+of the integer part of a number are to be grouped, starting at the
+decimal point and going to the left. The list contains integers
+indicating the size of the successive groups, from right to left. If
+the list is non-circular, then no grouping occurs for digits beyond
+the last group.
+
+For instance, if the returned list is a circular list that contains
+only @code{3} and the thousand separator is @code{","} (as is the case
+with English locales), then the number @code{12345678} should be
+printed @code{12,345,678}.
+@end deffn
+
+The following procedures deal with the representation of monetary
+amounts. Some of them take an additional @var{intl?} argument (a
+boolean) that tells whether the international or local monetary
+conventions for the given locale are to be used.
+
+@deffn {Scheme Procedure} locale-monetary-decimal-point [locale]
+@deffnx {Scheme Procedure} locale-monetary-thousands-separator [locale]
+@deffnx {Scheme Procedure} locale-monetary-grouping [locale]
+These are the monetary counterparts of the above procedures. These
+procedures apply to monetary amounts.
+@end deffn
+
+@deffn {Scheme Procedure} locale-currency-symbol intl? [locale]
+Return the currency symbol (a string) of either @var{locale} or the
+current locale.
+
+The following example illustrates the difference between the local and
+international monetary formats:
+
+@example
+(define us (make-locale LC_MONETARY "en_US"))
+(locale-currency-symbol #f us)
+@result{} "-$"
+(locale-currency-symbol #t us)
+@result{} "USD "
+@end example
+@end deffn
+
+@deffn {Scheme Procedure} locale-monetary-fractional-digits intl? [locale]
+Return the number of fractional digits to be used when printing
+monetary amounts according to either @var{locale} or the current
+locale. If the locale does not specify it, then @code{#f} is
+returned.
+@end deffn
+
+@deffn {Scheme Procedure} locale-currency-symbol-precedes-positive? intl? [locale]
+@deffnx {Scheme Procedure} locale-currency-symbol-precedes-negative? intl? [locale]
+@deffnx {Scheme Procedure} locale-positive-separated-by-space? intl? [locale]
+@deffnx {Scheme Procedure} locale-negative-separated-by-space? intl? [locale]
+These procedures return a boolean indicating whether the currency
+symbol should precede a positive/negative number, and whether a
+whitespace should be inserted between the currency symbol and a
+positive/negative amount.
+@end deffn
+
+@deffn {Scheme Procedure} locale-monetary-positive-sign [locale]
+@deffnx {Scheme Procedure} locale-monetary-negative-sign [locale]
+Return a string denoting the positive (respectively negative) sign
+that should be used when printing a monetary amount.
+@end deffn
+
+@deffn {Scheme Procedure} locale-positive-sign-position
+@deffnx {Scheme Procedure} locale-negative-sign-position
+These functions return a symbol telling where a sign of a
+positive/negative monetary amount is to appear when printing it. The
+possible values are:
+
+@table @code
+@item parenthesize
+The currency symbol and quantity should be surrounded by parentheses.
+@item sign-before
+Print the sign string before the quantity and currency symbol.
+@item sign-after
+Print the sign string after the quantity and currency symbol.
+@item sign-before-currency-symbol
+Print the sign string right before the currency symbol.
+@item sign-after-currency-symbol
+Print the sign string right after the currency symbol.
+@item unspecified
+Unspecified. We recommend you print the sign after the currency
+symbol.
+@end table
+
+@end deffn
+
+Finally, the two following procedures may be helpful when programming
+user interfaces:
+
+@deffn {Scheme Procedure} locale-yes-regexp [locale]
+@deffnx {Scheme Procedure} locale-no-regexp [locale]
+Return a string that can be used as a regular expression to recognize
+a positive (respectively, negative) response to a yes/no question.
+For the C locale, the default values are typically @code{"^[yY]"} and
+@code{"^[nN]"}, respectively.
+
+Here is an example:
+
+@example
+(format #t "Does Guile rock?~%")
+(let ((answer (read-line)))
+ (cond ((string-match (locale-yes-regexp) answer)
+ "Yes it does.")
+ ((string-match (locale-no-regexp) answer)
+ "No it doesn't.")
+ (else
+ "What do you mean?")))
+@end example
+
+For an internationalized yes/no string output, @code{gettext} should
+be used (@pxref{Gettext Support}).
+@end deffn
+
+Example uses of some of these functions are the implementation of the
+@code{number->locale-string} and @code{monetary-amount->locale-string}
+procedures (@pxref{Number Input and Output}), as well as that the
+SRFI-19 date and time convertion to/from strings (@pxref{SRFI-19}).
+
-@node Gettext Support
+@node Gettext Support, , Accessing Locale Information, Internationalization
@subsection Gettext Support
Guile provides an interface to GNU @code{gettext} for translating
diff --git a/doc/ref/api-init.texi b/doc/ref/api-init.texi
index 26e6e71ef..0e4e8b8b7 100644
--- a/doc/ref/api-init.texi
+++ b/doc/ref/api-init.texi
@@ -1,12 +1,13 @@
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@node Initialization
@section Initializing Guile
+@cindex Initializing Guile
Each thread that wants to use functions from the Guile API needs to
put itself into guile mode with either @code{scm_with_guile} or
@@ -93,7 +94,8 @@ The function @code{scm_boot_guile} arranges for the Scheme
@code{command-line} function to return the strings given by @var{argc}
and @var{argv}. If @var{main_func} modifies @var{argc} or @var{argv},
it should call @code{scm_set_program_arguments} with the final list, so
-Scheme code will know which arguments have been processed.
+Scheme code will know which arguments have been processed
+(@pxref{Runtime Environment}).
@end deftypefn
@deftypefn {C Function} void scm_shell (int @var{argc}, char **@var{argv})
diff --git a/doc/ref/api-options.texi b/doc/ref/api-options.texi
index 6dbc37062..493e2385d 100644
--- a/doc/ref/api-options.texi
+++ b/doc/ref/api-options.texi
@@ -554,6 +554,7 @@ Here is the list of evaluator trap options generated by typing
exit-frame no Trap when exiting eval or apply.
apply-frame no Trap when entering apply.
enter-frame no Trap when eval enters new frame.
+memoize-symbol no Trap when eval memoizes a symbol's value
traps yes Enable evaluator traps.
@end smallexample
@@ -612,6 +613,20 @@ way.
@var{retval} is the return value.
@end deffn
+
+@deffn memoize-symbol-handler key cont expression env
+Called when the evaluator memoizes the value of a procedure symbol
+
+@var{cont} is a ``debug object'', which means that it can be passed to
+@code{make-stack} to discover the stack at the point of the trap. The
+exit frame handler's code can capture a restartable continuation if it
+wants to by using @code{call-with-current-continuation} in the usual
+way.
+
+@var{retval} is the return value.
+@end deffn
+
+
@node Debugger options
@subsubsection Debugger options
diff --git a/doc/ref/api-procedures.texi b/doc/ref/api-procedures.texi
index e6d520ddf..7fd0f4fa4 100644
--- a/doc/ref/api-procedures.texi
+++ b/doc/ref/api-procedures.texi
@@ -198,30 +198,72 @@ evaluated in order.
@node let-keywords Reference
@subsubsection let-keywords Reference
-@c FIXME::martin: Review me!
-
-@code{let-keywords} and @code{let-keywords*} are used for extracting
-values from argument lists which use keywords instead of argument
-position for binding local variables to argument values.
-
-@code{let-keywords} binds all variables simultaneously, while
-@code{let-keywords*} binds them sequentially, consistent with @code{let}
-and @code{let*} (@pxref{Local Bindings}).
-
-@deffn {library syntax} let-keywords rest-arg allow-other-keys? (binding @dots{}) expr @dots{}
-@deffnx {library syntax} let-keywords* rest-arg allow-other-keys? (binding @dots{}) expr @dots{}
-These macros pick out keyword arguments from @var{rest-arg}, but do not
-modify it. This is consistent at least with Common Lisp, which
-duplicates keyword arguments in the rest argument. More explanation of what
-keyword arguments in a lambda list look like can be found below in
-the documentation for @code{lambda*}
- (@pxref{lambda* Reference}). @var{binding}s can have the same form as
-for @code{let-optional}. If @var{allow-other-keys?} is false, an error
-will be thrown if anything that looks like a keyword argument but does
-not match a known keyword parameter will result in an error.
-
-After binding the variables, the expressions @var{expr} @dots{} are
-evaluated in order.
+@code{let-keywords} and @code{let-keywords*} extract values from
+keyword style argument lists, binding local variables to those values
+or to defaults.
+
+@deffn {library syntax} let-keywords args allow-other-keys? (binding @dots{}) body @dots{}
+@deffnx {library syntax} let-keywords* args allow-other-keys? (binding @dots{}) body @dots{}
+@var{args} is evaluated and should give a list of the form
+@code{(#:keyword1 value1 #:keyword2 value2 @dots{})}. The
+@var{binding}s are variables and default expressions, with the
+variables to be set (by name) from the keyword values. The @var{body}
+forms are then evaluated and the last is the result. An example will
+make the syntax clearest,
+
+@example
+(define args '(#:xyzzy "hello" #:foo "world"))
+
+(let-keywords args #t
+ ((foo "default for foo")
+ (bar (string-append "default" "for" "bar")))
+ (display foo)
+ (display ", ")
+ (display bar))
+@print{} world, defaultforbar
+@end example
+
+The binding for @code{foo} comes from the @code{#:foo} keyword in
+@code{args}. But the binding for @code{bar} is the default in the
+@code{let-keywords}, since there's no @code{#:bar} in the args.
+
+@var{allow-other-keys?} is evaluated and controls whether unknown
+keywords are allowed in the @var{args} list. When true other keys are
+ignored (such as @code{#:xyzzy} in the example), when @code{#f} an
+error is thrown for anything unknown.
+
+@code{let-keywords} is like @code{let} (@pxref{Local Bindings}) in
+that all bindings are made at once, the defaults expressions are
+evaluated (if needed) outside the scope of the @code{let-keywords}.
+
+@code{let-keywords*} is like @code{let*}, each binding is made
+successively, and the default expressions see the bindings previously
+made. This is the style used by @code{lambda*} keywords
+(@pxref{lambda* Reference}). For example,
+
+@example
+(define args '(#:foo 3))
+
+(let-keywords* args #f
+ ((foo 99)
+ (bar (+ foo 6)))
+ (display bar))
+@print{} 9
+@end example
+
+The expression for each default is only evaluated if it's needed,
+ie. if the keyword doesn't appear in @var{args}. So one way to make a
+keyword mandatory is to throw an error of some sort as the default.
+
+@example
+(define args '(#:start 7 #:finish 13))
+
+(let-keywords* args #t
+ ((start 0)
+ (stop (error "missing #:stop argument")))
+ ...)
+@result{} ERROR: missing #:stop argument
+@end example
@end deffn
diff --git a/doc/ref/posix.texi b/doc/ref/posix.texi
index 6f496fe8d..faf57d6b1 100644
--- a/doc/ref/posix.texi
+++ b/doc/ref/posix.texi
@@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@@ -1348,15 +1348,72 @@ included but subprocesses are not.
@deffn {Scheme Procedure} program-arguments
@deffnx {Scheme Procedure} command-line
+@deffnx {Scheme Procedure} set-program-arguments
@deffnx {C Function} scm_program_arguments ()
+@deffnx {C Function} scm_set_program_arguments_scm (lst)
@cindex command line
@cindex program arguments
-Return the list of command line arguments passed to Guile, as a list of
-strings. The list includes the invoked program name, which is usually
-@code{"guile"}, but excludes switches and parameters for command line
-options like @code{-e} and @code{-l}.
+Get the command line arguments passed to Guile, or set new arguments.
+
+The arguments are a list of strings, the first of which is the invoked
+program name. This is just @nicode{"guile"} (or the executable path)
+when run interactively, or it's the script name when running a script
+with @option{-s} (@pxref{Invoking Guile}).
+
+@example
+guile -L /my/extra/dir -s foo.scm abc def
+
+(program-arguments) @result{} ("foo.scm" "abc" "def")
+@end example
+
+@code{set-program-arguments} allows a library module or similar to
+modify the arguments, for example to strip options it recognises,
+leaving the rest for the mainline.
+
+The argument list is held in a fluid, which means it's separate for
+each thread. Neither the list nor the strings within it are copied at
+any point and normally should not be mutated.
+
+The two names @code{program-arguments} and @code{command-line} are an
+historical accident, they both do exactly the same thing. The name
+@code{scm_set_program_arguments_scm} has an extra @code{_scm} on the
+end to avoid clashing with the C function below.
@end deffn
+@deftypefn {C Function} void scm_set_program_arguments (int argc, char **argv, char *first)
+@cindex command line
+@cindex program arguments
+Set the list of command line arguments for @code{program-arguments}
+and @code{command-line} above.
+
+@var{argv} is an array of null-terminated strings, as in a C
+@code{main} function. @var{argc} is the number of strings in
+@var{argv}, or if it's negative then a @code{NULL} entry in @var{argv}
+marks its end.
+
+@var{first} is an extra string put at the start of the arguments, or
+@code{NULL} for no such extra. This is a convenient way to pass the
+program name after advancing @var{argv} to strip option arguments.
+
+@example
+@{
+ char *progname = argv[0];
+ int i;
+ for (argv++; argv[0] != NULL && argv[0][0] == '-'; argv++)
+ @{
+ /* munch option ... */
+ @}
+ /* remaining args for scheme level use */
+ scm_set_program_arguments (-1, argv, progname);
+@}
+@end example
+
+This sort of thing is often done at startup under
+@code{scm_boot_guile} with any options handled at the C level removed.
+The given strings are all copied, so the C data is not accessed again
+once @code{scm_set_program_arguments} returns.
+@end deftypefn
+
@deffn {Scheme Procedure} getenv nam
@deffnx {C Function} scm_getenv (nam)
@cindex environment
@@ -3162,7 +3219,7 @@ Locales and Internationalization, libc, The GNU C Library Reference
Manual}.
Note that @code{setlocale} affects locale settings for the whole
-process. @xref{The ice-9 i18n Module, locale objects and
+process. @xref{i18n Introduction, locale objects and
@code{make-locale}}, for a thread-safe alternative.
@end deffn
@@ -3174,12 +3231,13 @@ Please note that the procedures in this section are not suited for
strong encryption, they are only interfaces to the well-known and
common system library functions of the same name. They are just as good
(or bad) as the underlying functions, so you should refer to your system
-documentation before using them.
+documentation before using them (@pxref{crypt,, Encrypting Passwords,
+libc, The GNU C Library Reference Manual}).
@deffn {Scheme Procedure} crypt key salt
@deffnx {C Function} scm_crypt (key, salt)
-Encrypt @var{key} using @var{salt} as the salt value to the
-crypt(3) library call.
+Encrypt @var{key}, with the addition of @var{salt} (both strings),
+using the @code{crypt} C library call.
@end deffn
Although @code{getpass} is not an encryption procedure per se, it
diff --git a/doc/ref/srfi-modules.texi b/doc/ref/srfi-modules.texi
index 8a027c00b..df356cc58 100644
--- a/doc/ref/srfi-modules.texi
+++ b/doc/ref/srfi-modules.texi
@@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@@ -1616,24 +1616,61 @@ applied to zero arguments, yields 1.
@subsection SRFI-17 - Generalized set!
@cindex SRFI-17
-This is an implementation of SRFI-17: Generalized set!
+This SRFI implements a generalized @code{set!}, allowing some
+``referencing'' functions to be used as the target location of a
+@code{set!}. This feature is available from
-@findex getter-with-setter
-It exports the Guile procedure @code{make-procedure-with-setter} under
-the SRFI name @code{getter-with-setter} and exports the standard
-procedures @code{car}, @code{cdr}, @dots{}, @code{cdddr},
-@code{string-ref} and @code{vector-ref} as procedures with setters, as
-required by the SRFI.
+@example
+(use-modules (srfi srfi-17))
+@end example
+
+@noindent
+For example @code{vector-ref} is extended so that
+
+@example
+(set! (vector-ref vec idx) new-value)
+@end example
-SRFI-17 was heavily criticized during its discussion period but it was
-finalized anyway. One issue was its concept of globally associating
-setter @dfn{properties} with (procedure) values, which is non-Schemy.
-For this reason, this implementation chooses not to provide a way to set
-the setter of a procedure. In fact, @code{(set! (setter @var{proc})
-@var{setter})} signals an error. The only way to attach a setter to a
-procedure is to create a new object (a @dfn{procedure with setter}) via
-the @code{getter-with-setter} procedure. This procedure is also
-specified in the SRFI. Using it avoids the described problems.
+@noindent
+is equivalent to
+
+@example
+(vector-set! vec idx new-value)
+@end example
+
+The idea is that a @code{vector-ref} expression identifies a location,
+which may be either fetched or stored. The same form is used for the
+location in both cases, encouraging visual clarity. This is similar
+to the idea of an ``lvalue'' in C.
+
+The mechanism for this kind of @code{set!} is in the Guile core
+(@pxref{Procedures with Setters}). This module adds definitions of
+the following functions as procedures with setters, allowing them to
+be targets of a @code{set!},
+
+@quotation
+@nicode{car}, @nicode{cdr}, @nicode{caar}, @nicode{cadr},
+@nicode{cdar}, @nicode{cddr}, @nicode{caaar}, @nicode{caadr},
+@nicode{cadar}, @nicode{caddr}, @nicode{cdaar}, @nicode{cdadr},
+@nicode{cddar}, @nicode{cdddr}, @nicode{caaaar}, @nicode{caaadr},
+@nicode{caadar}, @nicode{caaddr}, @nicode{cadaar}, @nicode{cadadr},
+@nicode{caddar}, @nicode{cadddr}, @nicode{cdaaar}, @nicode{cdaadr},
+@nicode{cdadar}, @nicode{cdaddr}, @nicode{cddaar}, @nicode{cddadr},
+@nicode{cdddar}, @nicode{cddddr}
+
+@nicode{string-ref}, @nicode{vector-ref}
+@end quotation
+
+The SRFI specifies @code{setter} (@pxref{Procedures with Setters}) as
+a procedure with setter, allowing the setter for a procedure to be
+changed, eg.@: @code{(set! (setter foo) my-new-setter-handler)}.
+Currently Guile does not implement this, a setter can only be
+specified on creation (@code{getter-with-setter} below).
+
+@defun getter-with-setter
+The same as the Guile core @code{make-procedure-with-setter}
+(@pxref{Procedures with Setters}).
+@end defun
@node SRFI-19
@@ -2095,10 +2132,10 @@ Conversions @samp{~D}, @samp{~x} and @samp{~X} are not currently
described here, since the specification and reference implementation
differ.
-Currently Guile doesn't implement any localizations for the above, all
-outputs are in English, and the @samp{~c} conversion is POSIX
-@code{ctime} style @samp{~a ~b ~d ~H:~M:~S~z ~Y}. This may change in
-the future.
+Conversion is locale-dependent on systems that support it
+(@pxref{Accessing Locale Information}). @xref{Locales,
+@code{setlocale}}, for information on how to change the current
+locale.
@node SRFI-19 String to date
@@ -2219,9 +2256,10 @@ Notice that the weekday matching forms don't affect the date object
returned, instead the weekday will be derived from the day, month and
year.
-Currently Guile doesn't implement any localizations for the above,
-month and weekday names are always expected in English. This may
-change in the future.
+Conversion is locale-dependent on systems that support it
+(@pxref{Accessing Locale Information}). @xref{Locales,
+@code{setlocale}}, for information on how to change the current
+locale.
@end defun