diff options
author | Ludovic Courtès <ludo@gnu.org> | 2008-09-10 22:33:40 +0200 |
---|---|---|
committer | Ludovic Courtès <ludo@gnu.org> | 2008-09-10 22:33:40 +0200 |
commit | 4a4849dbe0ae1b731b408167f90222e05d1ca2bd (patch) | |
tree | caa909b99ffb221e43408a3d19ad3e8209e3a96b /doc/ref | |
parent | 3ec17f28b8f96fa43218db83656c0d85b4f69d7c (diff) | |
parent | 032913739218c756f673bfb9c8f66ef9f8f02330 (diff) | |
download | guile-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/ChangeLog | 52 | ||||
-rw-r--r-- | doc/ref/api-control.texi | 2 | ||||
-rwxr-xr-x | doc/ref/api-data.texi | 8 | ||||
-rw-r--r-- | doc/ref/api-debug.texi | 23 | ||||
-rw-r--r-- | doc/ref/api-evaluation.texi | 3 | ||||
-rw-r--r-- | doc/ref/api-i18n.texi | 443 | ||||
-rw-r--r-- | doc/ref/api-init.texi | 6 | ||||
-rw-r--r-- | doc/ref/api-options.texi | 15 | ||||
-rw-r--r-- | doc/ref/api-procedures.texi | 90 | ||||
-rw-r--r-- | doc/ref/posix.texi | 76 | ||||
-rw-r--r-- | doc/ref/srfi-modules.texi | 86 |
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 |