diff options
Diffstat (limited to 'doc/ref')
-rw-r--r-- | doc/ref/ChangeLog | 143 | ||||
-rw-r--r-- | doc/ref/Makefile.am | 9 | ||||
-rw-r--r-- | doc/ref/api-control.texi | 39 | ||||
-rwxr-xr-x | doc/ref/api-data.texi | 28 | ||||
-rw-r--r-- | doc/ref/api-evaluation.texi | 12 | ||||
-rw-r--r-- | doc/ref/api-i18n.texi | 295 | ||||
-rw-r--r-- | doc/ref/api-io.texi | 24 | ||||
-rw-r--r-- | doc/ref/guile.texi | 4 | ||||
-rw-r--r-- | doc/ref/intro.texi | 3 | ||||
-rw-r--r-- | doc/ref/misc-modules.texi | 146 | ||||
-rw-r--r-- | doc/ref/posix.texi | 71 | ||||
-rw-r--r-- | doc/ref/repl-modules.texi | 139 | ||||
-rw-r--r-- | doc/ref/scheme-debugging.texi | 7 | ||||
-rw-r--r-- | doc/ref/scheme-using.texi | 399 |
14 files changed, 1051 insertions, 268 deletions
diff --git a/doc/ref/ChangeLog b/doc/ref/ChangeLog index 0768f1d8d..8b8e0befe 100644 --- a/doc/ref/ChangeLog +++ b/doc/ref/ChangeLog @@ -1,3 +1,80 @@ +2006-11-18 Ludovic Courtès <ludovic.courtes@laas.fr> + + * Makefile.am (BUILT_SOURCES): New variable. + (lib-version.texi): New target. + + * guile.texi: Include `lib-version.texi'. + + * api-data.texi (Conversion): Link to `The ice-9 i18n Module' when + describing `string->number'. + (String Comparison): Likewise. + + * api-i18n.texi (Internationalization)[The ice-9 i18n Module]: New + node. + [Gettext Support]: New node; contains text formerly in + `Internationalization'. + + * posix.texi (Locales): Added a link to the glibc manual + describing the various locale categories. Mention locale objects + and link to `The ice-9 i18n Module' when describing `setlocale'. + +2006-11-17 Neil Jerram <neil@ossau.uklinux.net> + + * intro.texi (Reporting Bugs): Note need for subscription to + bug-guile@gnu.org. + +2006-10-10 Neil Jerram <neil@ossau.uklinux.net> + + * scheme-using.texi (Setting and Managing Breakpoints): New text + about what happens when a breakpoint is created. + (Listing and Deleting Breakpoints, Moving and Losing Breakpoints): + New. + +2006-10-08 Neil Jerram <neil@ossau.uklinux.net> + + * scheme-using.texi (Working with GDS in Scheme Buffers): New + subsection, to group (Access to Guile Help and Completion, Setting + and Managing Breakpoints, Evaluating Scheme Code) together. + (GDS Getting Started): Editorial updates. + +2006-10-06 Neil Jerram <neil@ossau.uklinux.net> + + * scheme-using.texi (Using Guile in Emacs): Subnodes reordered, + from (Displaying the Scheme Stack, Continuing Execution, + Evaluating Scheme Code, Setting and Managing Breakpoints, Access + to Guile Help and Completion) to (Access to Guile Help and + Completion, Setting and Managing Breakpoints, Evaluating Scheme + Code, Displaying the Scheme Stack, Continuing Execution). + (Access to Guile Help and Completion): Mention where keys are + defined. + (Setting and Managing Breakpoints): Update text on how to set + breakpoints. + +2006-10-05 Kevin Ryde <user42@zip.com.au> + + * misc-modules.texi (File Tree Walk): Corrections to BASE parameter + and symlink vs stale-symlink types in nftw. + * misc-modules.texi, guile.texi (Buffered Input): New section, + describing (ice-9 buffered-input). + + * posix.texi (User Information): Clarify getpwent returns #f at end of + file. + + * repl-modules.texi (Readline Functions): New section on how to call + readline from scheme code. + +2006-10-03 Neil Jerram <neil@ossau.uklinux.net> + + * scheme-using.texi (GDS Getting Started): Editorial updates. + +2006-09-28 Neil Jerram <neil@ossau.uklinux.net> + + * scheme-using.texi (GDS Introduction, GDS Getting Started): Minor + edits. + + * api-data.texi (Symbol Props): Remove unnecessarily specific + parenthesis about Guile 1.6's use of extra symbol slots. + 2006-09-26 Neil Jerram <neil@ossau.uklinux.net> * scheme-using.texi (Using Guile in Emacs, GDS Introduction): @@ -7,6 +84,12 @@ (GDS Getting Started, How to Use GDS): Merged; editorial updates; subsections reordered. +2006-09-26 Kevin Ryde <user42@zip.com.au> + + * api-io.texi (Random Access): In truncate-file, tweak wording for + clarity, note cannot always extend file this way. + (Ports): File access uses LFS. + 2006-09-25 Neil Jerram <neil@ossau.uklinux.net> * scheme-using.texi (Error Handling, Interactive Debugger): Minor @@ -19,11 +102,31 @@ minor improvements. Removed doc for `trace-finish', which no longer exists. -2006-09-20 Ludovic Courtès <ludovic.courtes@laas.fr> +2006-09-22 Kevin Ryde <user42@zip.com.au> + + * api-data.texi (Scientific): In sqrt, note it's the positive root + which is returned (as per R5RS). + +2006-09-20 Ludovic Courtès <ludovic.courtes@laas.fr> * api-data.texi (Standard Character Sets): Documented the charset recomputation upon successful `setlocale'. +2006-09-08 Kevin Ryde <user42@zip.com.au> + + * misc-modules.texi (Formatted Output): Show ":@" rather than "@:", + because ":@" is traditional common lisp, though either way works. + Break a couple of example lines to avoid overflowing DVI page width. + + * scheme-debugging.texi (Debug Last Error): Line break in "Type + (backtrace) to get ..." which overflowed the line in both info and + DVI. Reported by Percy Tiglao. + +2006-09-05 Kevin Ryde <user42@zip.com.au> + + * posix.texi (Network Sockets and Communication): Tweak description, + note not multi-threading. + 2006-09-04 Neil Jerram <neil@ossau.uklinux.net> * api-control.texi (Dynamic Wind): Doc for scm_dynwind_free. @@ -37,6 +140,11 @@ * api-debug.texi (Debug on Error): Added paragraph on need to use debugging evaluator. Added text on what the Guile REPL code does. +2006-08-29 Kevin Ryde <user42@zip.com.au> + + * api-control.texi (Dynamic Wind): Reformat example a bit to avoid + going off the right edge of the paper. Reported by Percy Tiglao. + 2006-08-28 Neil Jerram <neil@ossau.uklinux.net> * api-debug.texi (Examining the Stack): Minor improvements to @@ -55,6 +163,11 @@ (GDS Introduction): New node, containing GDS-specific introductory text. +2006-08-22 Kevin Ryde <user42@zip.com.au> + + * api-i18n.texi (Internationalization): Cross reference gettext manual + on plural forms. + 2006-08-18 Neil Jerram <neil@ossau.uklinux.net> * scheme-using.texi (Using Guile in Emacs): Unignore extra GDS @@ -110,12 +223,23 @@ * Makefile.am (guile_TEXINFOS): Include new scheme-using.texi file. -2006-06-16 Ludovic Courtès <ludovic.courtes@laas.fr> +2006-07-24 Kevin Ryde <user42@zip.com.au> + + * api-evaluation.texi (Fly Evaluation): Add scm_c_eval_string. + (Loading): Add scm_c_primitive_load. + Reported by Jon Wilson. + +2006-06-25 Kevin Ryde <user42@zip.com.au> + + * posix.texi (Time): In tm:gmtoff, give example values, note not the + same as C tm_gmtoff. + +2006-06-16 Ludovic Courtès <ludovic.courtes@laas.fr> * api-utility.texi (Equality): Mentioned the behavior of `equal?' for structures (as suggested by Kevin Ryde). -2006-06-13 Ludovic Courtès <ludovic.courtes@laas.fr> +2006-06-13 Ludovic Courtès <ludovic.courtes@laas.fr> * api-compound.texi (Structure Concepts): Mentioned the behavior of `equal?' for structures. @@ -182,7 +306,7 @@ SCM_SIMPLE_VECTOR_SET not SCM_SIMPLE_VECTOR_SET_X, the former is what's in vector.h. -2006-03-21 Ludovic Courtès <ludovic.courtes@laas.fr> +2006-03-21 Ludovic Courtès <ludovic.courtes@laas.fr> * api-data.texi (Conversion): Add scm_c_locale_stringn_to_number. @@ -234,7 +358,7 @@ contexts. Renamed all functions from scm_frame_ to scm_dynwind_. Updated documentation. -2005-12-19 Ludovic Courtès <ludovic.courtes@laas.fr> +2005-12-19 Ludovic Courtès <ludovic.courtes@laas.fr> * api-data.texi (Operations Related to Symbols): Documented `scm_take_locale_symbol ()'. @@ -276,7 +400,7 @@ 2005-11-06 Kevin Ryde <user42@zip.com.au> - From Ludovic Courtès, partial rework by me: + From Ludovic Courtès, partial rework by me: * doc/ref/api-modules.texi (Creating Guile Modules): In define-module, describe #:re-export, #:export-syntax, #:re-export-syntax, #:replace and #:duplicates. Add re-export. @@ -289,7 +413,7 @@ * posix.texi (Network Socket Address): Add scm_make_socket_address, scm_c_make_socket_address, scm_from_sockaddr, scm_to_sockaddr. This - change by Ludovic Courtès and revised a bit by me. + change by Ludovic Courtès and revised a bit by me. 2005-10-27 Kevin Ryde <user42@zip.com.au> @@ -2395,3 +2519,8 @@ The change log for files in this directory continues backwards from 2001-08-27 in ../ChangeLog, as all the Guile documentation prior to this date was contained in a single directory. + + +;; Local Variables: +;; coding: utf-8 +;; End: diff --git a/doc/ref/Makefile.am b/doc/ref/Makefile.am index 76a66f0c9..7d009ff52 100644 --- a/doc/ref/Makefile.am +++ b/doc/ref/Makefile.am @@ -21,6 +21,9 @@ AUTOMAKE_OPTIONS = gnu +BUILT_SOURCES = lib-version.texi + + info_TEXINFOS = guile.texi guile_TEXINFOS = preface.texi \ @@ -86,4 +89,10 @@ autoconf.texi: autoconf-macros.texi autoconf-macros.texi: $(top_srcdir)/guile-config/guile.m4 $(preinstguiletool)/snarf-guile-m4-docs $< > $(srcdir)/$@ +lib-version.texi: $(top_srcdir)/GUILE-VERSION + cat "$^" | grep '^LIBGUILE_.*_MAJOR' | \ + sed 's/^LIBGUILE_\([A-Z0-9_]*\)_MAJOR=\([0-9]\+\)/@set LIBGUILE_\1_MAJOR \2/' \ + > "$@" + + MAINTAINERCLEANFILES = autoconf-macros.texi diff --git a/doc/ref/api-control.texi b/doc/ref/api-control.texi index dbb51cf6f..11a276a13 100644 --- a/doc/ref/api-control.texi +++ b/doc/ref/api-control.texi @@ -1234,28 +1234,29 @@ non-locally, @var{out_guard} is called. If the dynamic extent of the dynamic-wind is re-entered, @var{in_guard} is called. Thus @var{in_guard} and @var{out_guard} may be called any number of times. + @lisp (define x 'normal-binding) @result{} x -(define a-cont (call-with-current-continuation - (lambda (escape) - (let ((old-x x)) - (dynamic-wind - ;; in-guard: - ;; - (lambda () (set! x 'special-binding)) - - ;; thunk - ;; - (lambda () (display x) (newline) - (call-with-current-continuation escape) - (display x) (newline) - x) - - ;; out-guard: - ;; - (lambda () (set! x old-x))))))) - +(define a-cont + (call-with-current-continuation + (lambda (escape) + (let ((old-x x)) + (dynamic-wind + ;; in-guard: + ;; + (lambda () (set! x 'special-binding)) + + ;; thunk + ;; + (lambda () (display x) (newline) + (call-with-current-continuation escape) + (display x) (newline) + x) + + ;; out-guard: + ;; + (lambda () (set! x old-x))))))) ;; Prints: special-binding ;; Evaluates to: diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi index 15eac2e4b..abcb28de1 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 +@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006 @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. @@ -1012,6 +1012,12 @@ zero. @rnindex number->string @rnindex string->number +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 +i18n)} module}, for locale-dependent number parsing. + @deffn {Scheme Procedure} number->string n [radix] @deffnx {C Function} scm_number_to_string (n, radix) Return a string holding the external representation of the @@ -1214,7 +1220,16 @@ including complex numbers. @rnindex sqrt @c begin (texi-doc-string "guile" "sqrt") @deffn {Scheme Procedure} sqrt z -Return the square root of @var{z}. +Return the square root of @var{z}. Of the two possible roots +(positive and negative), the one with the a positive real part is +returned, or if that's zero then a positive imaginary part. Thus, + +@example +(sqrt 9.0) @result{} 3.0 +(sqrt -9.0) @result{} 0.0+3.0i +(sqrt 1.0+1.0i) @result{} 1.09868411346781+0.455089860562227i +(sqrt -1.0-1.0i) @result{} 0.455089860562227-1.09868411346781i +@end example @end deffn @rnindex expt @@ -2934,7 +2949,8 @@ 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. +when comparing strings. @xref{The ice-9 i18n Module, the @code{(ice-9 +i18n)} module}, for locale-dependent string comparison. @rnindex string=? @deffn {Scheme Procedure} string=? s1 s2 @@ -4674,10 +4690,8 @@ see @code{symbol-property}. @end deffn Support for these extra slots may be removed in a future release, and it -is probably better to avoid using them. (In release 1.6, Guile itself -uses the property list slot sparingly, and the function slot not at -all.) For a more modern and Schemely approach to properties, see -@ref{Object Properties}. +is probably better to avoid using them. For a more modern and Schemely +approach to properties, see @ref{Object Properties}. @node Symbol Read Syntax diff --git a/doc/ref/api-evaluation.texi b/doc/ref/api-evaluation.texi index 6f29f1d7c..1da13de43 100644 --- a/doc/ref/api-evaluation.texi +++ b/doc/ref/api-evaluation.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, 2005, 2006 @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. @@ -357,6 +357,11 @@ While the code is evaluated, the given module is made the current one. The current module is restored when this procedure returns. @end deffn +@deftypefn {C Function} SCM scm_c_eval_string (const char *string) +@code{scm_eval_string}, but taking a C string instead of an +@code{SCM}. +@end deftypefn + @deffn {Scheme Procedure} apply proc arg1 @dots{} argN arglst @deffnx {C Function} scm_apply_0 (proc, arglst) @deffnx {C Function} scm_apply_1 (proc, arg1, arglst) @@ -446,6 +451,11 @@ that will be called before any code is loaded. See the documentation for @code{%load-hook} later in this section. @end deffn +@deftypefn {C Function} SCM scm_c_primitive_load (const char *filename) +@code{scm_primitive_load}, but taking a C string instead of an +@code{SCM}. +@end deftypefn + @deffn {Scheme Procedure} primitive-load-path filename @deffnx {C Function} scm_primitive_load_path (filename) Search @code{%load-path} for the file named @var{filename} and diff --git a/doc/ref/api-i18n.texi b/doc/ref/api-i18n.texi index 995e27e90..1927a755b 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 +@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006 @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. @@ -8,6 +8,292 @@ @node Internationalization @section Support for Internationalization +@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. + +@menu +* The ice-9 i18n Module:: Honoring cultural conventions. +* Gettext Support:: Translating message strings. +@end menu + + +@node The ice-9 i18n Module +@subsection The @code{(ice-9 i18n)} Module + +In order to make use of the following functions, one must import the +@code{(ice-9 i18n)} module in the usual way: + +@example +(use-modules (ice-9 i18n)) +@end example + +@cindex libguile-i18n-v-@value{LIBGUILE_I18N_MAJOR} + +C programs can use the C functions corresponding to the procedures of +this module by including @code{<libguile/i18n.h>} and by linking +against @code{libguile-i18n-v-@value{LIBGUILE_I18N_MAJOR}}. + +@cindex cultural conventions + +The @code{(ice-9 i18n)} module provides procedures to manipulate text +and other data in a way that conforms to the cultural conventions +chosen by the user. Each region of the world or language has its own +customs to, for instance, represent real numbers, classify characters, +collate text, etc. All these aspects comprise the so-called +``cultural conventions'' of that region or language. + +@cindex locale +@cindex locale category + +Computer systems typically refer to a set of cultural conventions as a +@dfn{locale}. For each particular aspect that comprise those cultural +conventions, a @dfn{locale category} is defined. For instance, the +way characters are classified is defined by the @code{LC_CTYPE} +category, while the language in which program messages are issued to +the user is defined by the @code{LC_MESSAGES} category +(@pxref{Locales, General Locale Information} for details). + +@cindex locale object + +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}}). + +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) +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): + +@example +(make-locale (logior LC_MESSAGE_MASK LC_CTYPE_MASK) "eo_EO") +@end example + +The following example combines the use of Swedish conventions with +monetary conventions from Croatia: + +@example +(make-locale LC_MONETARY_MASK "hr_HR" + (make-locale LC_ALL_MASK "sv_SE")) +@end example + +A @code{system-error} exception (@pxref{Handling Errors}) is raised by +@code{make-locale} when @var{locale-name} does not match any of the +locales compiled on the system. Note that on non-GNU systems, this +error may be raised later, when the locale object is actually used. + +@end deffn + +@deffn {Scheme Procedure} locale? obj +@deffnx {C Function} scm_locale_p (obj) +Return true if @var{obj} is a locale object. +@end deffn + +The following procedures provide support for text collation. + +@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 {C Function} scm_string_locale_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. +@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 +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 {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 {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 {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. +@end deffn + +@deffn {Scheme Procedure} char-locale-ci=? c1 c2 [locale] +@deffnx {C Function} scm_char_locale_ci_eq (c1, c2, locale) +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 + +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 +look similar (@pxref{Alphabetic Case Mapping}). However, the SRFI-13 +procedures are locale-independent. Therefore, they do not take into +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. + +@deffn {Scheme Procedure} char-locale-downcase chr [locale] +@deffnx {C Function} scm_char_locale_upcase (chr, locale) +Return the lowercase character that corresponds to @var{chr} according +to either @var{locale} or the current locale. +@end deffn + +@deffn {Scheme Procedure} char-locale-upcase chr [locale] +@deffnx {C Function} scm_char_locale_downcase (chr, locale) +Return the uppercase character that corresponds to @var{chr} according +to either @var{locale} or the current locale. +@end deffn + +@deffn {Scheme Procedure} string-locale-upcase str [locale] +@deffnx {C Function} scm_string_locale_upcase (str, locale) +Return a new string that is the uppercase version of @var{str} +according to either @var{locale} or the current locale. +@end deffn + +@deffn {Scheme Procedure} string-locale-downcase str [locale] +@deffnx {C Function} scm_string_locale_downcase (str, locale) +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 +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. + +@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 +@var{locale} (a locale object as returned by @code{make-locale}) or +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). +@end deffn + +@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). +@end deffn + + +@node Gettext Support +@subsection Gettext Support + Guile provides an interface to GNU @code{gettext} for translating message strings (@pxref{Introduction,,, gettext, GNU @code{gettext} utilities}). @@ -19,7 +305,8 @@ catalog filename). When @code{gettext} is not available, or if Guile was configured @samp{--without-nls}, dummy functions doing no translation are -provided. +provided. When @code{gettext} support is available in Guile, the +@code{i18n} feature is provided (@pxref{Feature Tracking}). @deffn {Scheme Procedure} gettext msg [domain [category]] @deffnx {C Function} scm_gettext (msg, domain, category) @@ -85,7 +372,8 @@ example, It's important to use @code{ngettext} rather than plain @code{gettext} for plurals, since the rules for singular and plural forms in English are not the same in other languages. Only @code{ngettext} will allow -translators to give correct forms. +translators to give correct forms (@pxref{Plural forms,, Additional +functions for plural forms, gettext, GNU @code{gettext} utilities}). @end deffn @deffn {Scheme Procedure} textdomain [domain] @@ -154,4 +442,5 @@ future. @c Local Variables: @c TeX-master: "guile.texi" +@c ispell-local-dictionary: "american" @c End: diff --git a/doc/ref/api-io.texi b/doc/ref/api-io.texi index 6eb95db3d..0d30c4d2a 100644 --- a/doc/ref/api-io.texi +++ b/doc/ref/api-io.texi @@ -64,6 +64,10 @@ rely on that to keep it away from system limits. An explicit call to If program flow makes it hard to be certain when to close then this may be an acceptable way to control resource usage. +All file access uses the ``LFS'' large file support functions when +available, so files bigger than 2 Gbytes (@math{2^31} bytes) can be +read and written on a 32-bit system. + @rnindex input-port? @deffn {Scheme Procedure} input-port? x @deffnx {C Function} scm_input_port_p (x) @@ -390,14 +394,18 @@ Return an integer representing the current position of @findex truncate @findex ftruncate -@deffn {Scheme Procedure} truncate-file object [length] -@deffnx {C Function} scm_truncate_file (object, length) -Truncates the object referred to by @var{object} to at most -@var{length} bytes. @var{object} can be a string containing a -file name or an integer file descriptor or a port. -@var{length} may be omitted if @var{object} is not a file name, -in which case the truncation occurs at the current port -position. The return value is unspecified. +@deffn {Scheme Procedure} truncate-file file [length] +@deffnx {C Function} scm_truncate_file (file, length) +Truncate @var{file} to @var{length} bytes. @var{file} can be a +filename string, a port object, or an integer file descriptor. The +return value is unspecified. + +For a port or file descriptor @var{length} can be omitted, in which +case the file is truncated at the current position (per @code{ftell} +above). + +On most systems a file can be extended by giving a length greater than +the current size, but this is not mandatory in the POSIX standard. @end deffn @node Line/Delimited diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi index 627c8cbb2..109a50b7f 100644 --- a/doc/ref/guile.texi +++ b/doc/ref/guile.texi @@ -7,6 +7,7 @@ @set MANUAL-EDITION 1.1 @c %**end of header @include version.texi +@include lib-version.texi @copying This reference manual documents Guile, GNU's Ubiquitous Intelligent @@ -137,7 +138,7 @@ x @comment The title is printed in a large font. @title Guile Reference Manual @subtitle Edition @value{MANUAL-EDITION}, for use with Guile @value{VERSION} -@c @subtitle $Id: guile.texi,v 1.46 2006-08-01 21:51:12 ossau Exp $ +@c @subtitle $Id: guile.texi,v 1.48 2006-11-18 18:14:55 civodul Exp $ @c See preface.texi for the list of authors @author The Guile Developers @@ -347,6 +348,7 @@ available through both Scheme and C interfaces. * File Tree Walk:: Traversing the file system. * Queues:: First-in first-out queuing. * Streams:: Sequences of values. +* Buffered Input:: Ports made from a reader function. * Expect:: Controlling interactive programs with Guile. * The Scheme shell (scsh):: Using scsh interfaces in Guile. @end menu diff --git a/doc/ref/intro.texi b/doc/ref/intro.texi index a31fe30f8..1494b81ee 100644 --- a/doc/ref/intro.texi +++ b/doc/ref/intro.texi @@ -420,7 +420,8 @@ purpose to check whether your code still relies on them. @section Reporting Bugs Any problems with the installation should be reported to -@email{bug-guile@@gnu.org}. +@email{bug-guile@@gnu.org}. Please note that you must be subscribed to +this list first, in order to successfully send a report to it. Whenever you have found a bug in Guile you are encouraged to report it to the Guile developers, so they can fix it. They may also be able to diff --git a/doc/ref/misc-modules.texi b/doc/ref/misc-modules.texi index f3a3c4093..db90c419a 100644 --- a/doc/ref/misc-modules.texi +++ b/doc/ref/misc-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 @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. @@ -270,13 +270,13 @@ With no parameters output is in words as a cardinal like ``ten'', or @end example And also with no parameters, @nicode{~@@r} gives roman numerals and -@nicode{~@@:r} gives old roman numerals. In old roman numerals +@nicode{~:@@r} gives old roman numerals. In old roman numerals there's no ``subtraction'', so 9 is @nicode{VIIII} instead of @nicode{IX}. In both cases only positive numbers can be output. @example (format #t "~@@r" 89) @print{} LXXXIX ;; roman -(format #t "~@@:r" 89) @print{} LXXXVIIII ;; old roman +(format #t "~:@@r" 89) @print{} LXXXVIIII ;; old roman @end example When a parameter is given it means numeric output in the specified @@ -507,7 +507,7 @@ puts the padding after the sign. @example (format #f "~,,8$" -1.5) @result{} " -1.50" (format #f "~,,8:$" -1.5) @result{} "- 1.50" -(format #f "~,,8,'.@@:$" 3) @result{} "+...3.00" +(format #f "~,,8,'.:@@$" 3) @result{} "+...3.00" @end example Note that floating point for dollar amounts is generally not a good @@ -567,7 +567,7 @@ one, which can be convenient when printing some sort of count. @example (format #t "~d cat~:p" 9) @print{} 9 cats -(format #t "~d pupp~@@:p" 5) @print{} 5 puppies +(format #t "~d pupp~:@@p" 5) @print{} 5 puppies @end example @nicode{~p} is designed for English plurals and there's no attempt to @@ -777,14 +777,14 @@ The modifiers on @nicode{~(} control the conversion. @c rest lower case. @c @item -@nicode{~@@:(} --- upper case. +@nicode{~:@@(} --- upper case. @end itemize For example, @example (format #t "~(Hello~)") @print{} hello -(format #t "~@@:(Hello~)") @print{} HELLO +(format #t "~:@@(Hello~)") @print{} HELLO @end example In the future it's intended the modifiers @nicode{:} and @nicode{@@} @@ -813,8 +813,10 @@ elements from it. This is a convenient way to output a whole list. @nicode{~:@{} takes a single argument which is a list of lists, each of those contained lists gives the arguments for the iterated format. +@c @print{} on a new line here to avoid overflowing page width in DVI @example -(format #t "~:@{~dx~d ~@}" '((1 2) (3 4) (5 6))) @print{} 1x2 3x4 5x6 +(format #t "~:@{~dx~d ~@}" '((1 2) (3 4) (5 6))) +@print{} 1x2 3x4 5x6 @end example @nicode{~@@@{} takes arguments directly, with each iteration @@ -825,11 +827,13 @@ successively consuming arguments. (format #t "~@@@{~s=~d ~@}" "x" 1 "y" 2) @print{} "x"=1 "y"=2 @end example -@nicode{~@@:@{} takes list arguments, one argument for each iteration, +@nicode{~:@@@{} takes list arguments, one argument for each iteration, using that list for the format. +@c @print{} on a new line here to avoid overflowing page width in DVI @example -(format #t "~@@:@{~dx~d ~@}" '(1 2) '(3 4) '(5 6)) @print{} 1x2 3x4 5x6 +(format #t "~:@@@{~dx~d ~@}" '(1 2) '(3 4) '(5 6)) +@print{} 1x2 3x4 5x6 @end example Iterating stops when there are no more arguments or when the @@ -1094,27 +1098,28 @@ Walk the filesystem tree starting at @var{startname}, calling @var{proc} for each file and directory. @code{nftw} has extra features over the basic @code{ftw} described above. -Hard links and symbolic links are followed, but a file or directory is -reported to @var{proc} only once, and skipped if seen again in another -place. One consequence of this is that @code{nftw} is safe against -circular linked directory structures. +Like @code{ftw}, hard links and symbolic links are followed. A file +or directory is reported to @var{proc} only once, and skipped if seen +again in another place. One consequence of this is that @code{nftw} +is safe against circular linked directory structures. Each @var{proc} call is @code{(@var{proc} filename statinfo flag -basename level)} and it should return @code{#t} to continue, or any +base level)} and it should return @code{#t} to continue, or any other value to stop. @var{filename} is the item visited, being @var{startname} plus a further path and the name of the item. @var{statinfo} is the return -from @code{stat} on @var{filename} (@pxref{File System}). -@var{basename} it the item name without any path. @var{level} is an -integer giving the directory nesting level, starting from 0 for the -contents of @var{startname} (or that item itself if it's a file). -@var{flag} is one of the following symbols, +from @code{stat} on @var{filename} (@pxref{File System}). @var{base} +is an integer offset into @var{filename} which is where the basename +for this item begins. @var{level} is an integer giving the directory +nesting level, starting from 0 for the contents of @var{startname} (or +that item itself if it's a file). @var{flag} is one of the following +symbols, @table @code @item regular -@var{filename} is a file, this includes special files like devices, -named pipes, etc. +@var{filename} is a file, including special files like devices, named +pipes, etc. @item directory @var{filename} is a directory. @@ -1132,19 +1137,15 @@ nothing is known about it. @var{statinfo} is @code{#f} in this case. @var{filename} is a directory, but one which cannot be read and hence won't be recursed into. -@item symlink -@var{filename} is a dangling symbolic link. Symbolic links are -normally followed and their target reported, the link itself is -reported if the target does not exist. - -Under the @code{physical} option described below, @code{symlink} is -instead given for symbolic links whose target does exist. - @item stale-symlink -Under the @code{physical} option described below, this indicates -@var{filename} is a dangling symbolic link, meaning its target does -not exist. Without the @code{physical} option plain @code{symlink} -indicates this. +@var{filename} is a dangling symbolic link. Links are normally +followed and their target reported, the link itself is reported if its +target does not exist. + +@item symlink +When the @code{physical} option described below is used, this +indicates @var{filename} is a symbolic link whose target exists (and +is not being followed). @end table The following optional arguments can be given to modify the way @@ -1156,10 +1157,11 @@ takes a following integer value). Change to the directory containing the item before calling @var{proc}. When @code{nftw} returns the original current directory is restored. -Under this option, generally the @var{basename} parameter should be -used to access the item in each @var{proc} call. The @var{filename} -parameter still has a path as normal and this will only be valid if -the @var{startname} directory was absolute. +Under this option, generally the @var{base} parameter to each +@var{proc} call should be used to pick out the base part of the +@var{filename}. The @var{filename} is still a path but with a changed +directory it won't be valid (unless the @var{startname} directory was +absolute). @item @code{depth} Visit files ``depth first'', meaning @var{proc} is called for the @@ -1175,11 +1177,12 @@ Set the size of the hash table used to track items already visited. @item @code{mount} Don't cross a mount point, meaning only visit items on the same -filesystem as @var{startname}. (Ie.@: the same @code{stat:dev}.) +filesystem as @var{startname} (ie.@: the same @code{stat:dev}). @item @code{physical} Don't follow symbolic links, instead report them to @var{proc} as -@code{symlink}, and report dangling links as @code{stale-symlink}. +@code{symlink}. Dangling links (those whose target doesn't exist) are +still reported as @code{stale-symlink}. @end table The return value from @code{nftw} is @code{#t} if it ran to @@ -1461,6 +1464,69 @@ ends when the end of the shortest given @var{stream} is reached. @end defun +@node Buffered Input +@section Buffered Input +@cindex Buffered input +@cindex Line continuation + +The following functions are provided by + +@example +(use-modules (ice-9 buffered-input)) +@end example + +A buffered input port allows a reader function to return chunks of +characters which are to be handed out on reading the port. A notion +of further input for an application level logical expression is +maintained too, and passed through to the reader. + +@defun make-buffered-input-port reader +Create an input port which returns characters obtained from the given +@var{reader} function. @var{reader} is called (@var{reader} cont), +and should return a string or an EOF object. + +The new port gives precisely the characters returned by @var{reader}, +nothing is added, so if any newline characters or other separators are +desired they must come from the reader function. + +The @var{cont} parameter to @var{reader} is @code{#f} for initial +input, or @code{#t} when continuing an expression. This is an +application level notion, set with +@code{set-buffered-input-continuation?!} below. If the user has +entered a partial expression then it allows @var{reader} for instance +to give a different prompt to show more is required. +@end defun + +@defun make-line-buffered-input-port reader +@cindex Line buffered input +Create an input port which returns characters obtained from the +specified @var{reader} function, similar to +@code{make-buffered-input-port} above, but where @var{reader} is +expected to be a line-oriented. + +@var{reader} is called (@var{reader} cont), and should return a string +or an EOF object as above. Each string is a line of input without a +newline character, the port code inserts a newline after each string. +@end defun + +@defun set-buffered-input-continuation?! port cont +Set the input continuation flag for a given buffered input +@var{port}. + +An application uses this by calling with a @var{cont} flag of +@code{#f} when beginning to read a new logical expression. For +example with the Scheme @code{read} function (@pxref{Scheme Read}), + +@example +(define my-port (make-buffered-input-port my-reader)) + +(set-buffered-input-continuation?! my-port #f) +(let ((obj (read my-port))) + ... +@end example +@end defun + + @c Local Variables: @c TeX-master: "guile.texi" @c End: diff --git a/doc/ref/posix.texi b/doc/ref/posix.texi index 6a1d0f1b2..6f496fe8d 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 +@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006 @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. @@ -1008,8 +1008,8 @@ return value is unspecified. @end deffn @deffn {Scheme Procedure} getpwent -Return the next entry in the user database, using the stream set by -@code{setpwent}. +Read the next entry in the user database stream. The return is a +passwd user object as above, or @code{#f} when no more entries. @end deffn @deffn {Scheme Procedure} endpwent @@ -1170,6 +1170,13 @@ Daylight saving indicator (0 for ``no'', greater than 0 for ``yes'', less than @deffn {Scheme Procedure} tm:gmtoff tm @deffnx {Scheme Procedure} set-tm:gmtoff tm val Time zone offset in seconds west of @acronym{UTC} (-46800 to 43200). +For example on East coast USA (zone @samp{EST+5}) this would be 18000 +(ie.@: @m{5\times60\times60,5*60*60}) in winter, or 14400 +(ie.@: @m{4\times60\times60,4*60*60}) during daylight savings. + +Note @code{tm:gmtoff} is not the same as @code{tm_gmtoff} in the C +@code{tm} structure. @code{tm_gmtoff} is seconds east and hence the +negative of the value here. @end deffn @deffn {Scheme Procedure} tm:zone tm @deffnx {Scheme Procedure} set-tm:zone tm val @@ -2909,32 +2916,37 @@ any unflushed buffered port data is ignored. @deffn {Scheme Procedure} recvfrom! sock str [flags [start [end]]] @deffnx {C Function} scm_recvfrom (sock, str, flags, start, end) -Return data from the socket port @var{sock} and also -information about where the data was received from. -@var{sock} must already be bound to the address from which -data is to be received. @code{str}, is a string into which the -data will be written. The size of @var{str} limits the amount -of data which can be received: in the case of packet protocols, -if a packet larger than this limit is encountered then some -data will be irrevocably lost. +Receive data from socket port @var{sock}, returning the originating +address as well as the data. This function is usually for datagram +sockets, but can be used on stream-oriented sockets too. + +The data received is stored in the given @var{str}, the whole string +or just the region between the optional @var{start} and @var{end} +positions. The size of @var{str} limits the amount of data which can +be received. For datagram protocols if a packet larger than this is +received then excess bytes are irrevocably lost. + +The return value is a pair. The @code{car} is the number of bytes +read. The @code{cdr} is a socket address object (@pxref{Network +Socket Address}) which is where the data came from, or @code{#f} if +the origin is unknown. @vindex MSG_OOB @vindex MSG_PEEK @vindex MSG_DONTROUTE -The optional @var{flags} argument is a value or bitwise OR of -@code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc. +The optional @var{flags} argument is a or bitwise-OR (@code{logior}) +of @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc. -The value returned is a pair: the @acronym{CAR} is the number of -bytes read from the socket and the @acronym{CDR} an address object -in the same form as returned by @code{accept}. The address -will given as @code{#f} if not available, as is usually the -case for stream sockets. +Data is read directly from the socket file descriptor, any buffered +port data is ignored. -The @var{start} and @var{end} arguments specify a substring of -@var{str} to which the data should be written. - -Note that the data is read directly from the socket file -descriptor: any unread buffered port data is ignored. +@c This was linux kernel 2.6.15 and glibc 2.3.6, not sure what any +@c specs are supposed to say about recvfrom threading. +@c +On a GNU/Linux system @code{recvfrom!} is not multi-threading, all +threads stop while a @code{recvfrom!} call is in progress. An +application may need to use @code{select}, @code{O_NONBLOCK} or +@code{MSG_DONTWAIT} to avoid this. @end deffn @deffn {Scheme Procedure} sendto sock message sockaddr [flags] @@ -3127,10 +3139,11 @@ specified. Get or set the current locale, used for various internationalizations. Locales are strings, such as @samp{sv_SE}. -If @var{locale} is given then the locale for the given @var{category} is set -and the new value returned. If @var{locale} is not given then the -current value is returned. @var{category} should be one of the -following values +If @var{locale} is given then the locale for the given @var{category} +is set and the new value returned. If @var{locale} is not given then +the current value is returned. @var{category} should be one of the +following values (@pxref{Locale Categories, Categories of Activities +that Locales Affect,, libc, The GNU C Library Reference Manual}): @defvar LC_ALL @defvarx LC_COLLATE @@ -3147,6 +3160,10 @@ categories based on standard environment variables (@code{LANG} etc). For full details on categories and locale names @pxref{Locales,, 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 +@code{make-locale}}, for a thread-safe alternative. @end deffn @node Encryption diff --git a/doc/ref/repl-modules.texi b/doc/ref/repl-modules.texi index 45f410c3a..5f274e253 100644 --- a/doc/ref/repl-modules.texi +++ b/doc/ref/repl-modules.texi @@ -23,6 +23,7 @@ history entries. @menu * Loading Readline Support:: How to load readline support into Guile. * Readline Options:: How to modify readline's behaviour. +* Readline Functions:: Programming with readline. @end menu @@ -32,7 +33,6 @@ history entries. The module is not loaded by default and so has to be loaded and activated explicitly. This is done with two simple lines of code: -@findex activate-readline @lisp (use-modules (ice-9 readline)) (activate-readline) @@ -91,7 +91,7 @@ $endif The readline interface module can be configured in several ways to better suit the user's needs. Configuration is done via the readline module's options interface, in a similar way to the evaluator and -debugging options (@pxref{User level options interfaces}.) +debugging options (@pxref{Runtime Options}). @findex readline-options @findex readline-enable @@ -119,6 +119,141 @@ usage of the history file using the following call. The readline options interface can only be used @emph{after} loading the readline module, because it is defined in that module. +@node Readline Functions +@subsection Readline Functions + +The following functions are provided by + +@example +(use-modules (ice-9 readline)) +@end example + +There are two ways to use readline from Scheme code, either make calls +to @code{readline} directly to get line by line input, or use the +readline port below with all the usual reading functions. + +@defun readline [prompt] +Read a line of input from the user and return it as a string (without +a newline at the end). @var{prompt} is the prompt to show, or the +default is the string set in @code{set-readline-prompt!} below. + +@example +(readline "Type something: ") @result{} "hello" +@end example +@end defun + +@defun set-readline-input-port! port +@defunx set-readline-output-port! port +Set the input and output port the readline function should read from +and write to. @var{port} must be a file port (@pxref{File Ports}), +and should usually be a terminal. + +The default is the @code{current-input-port} and +@code{current-output-port} (@pxref{Default Ports}) when @code{(ice-9 +readline)} loads, which in an interactive user session means the Unix +``standard input'' and ``standard output''. +@end defun + +@subsubsection Readline Port + +@defun readline-port +Return a buffered input port (@pxref{Buffered Input}) which calls the +@code{readline} function above to get input. This port can be used +with all the usual reading functions (@code{read}, @code{read-char}, +etc), and the user gets the interactive editing features of readline. + +There's only a single readline port created. @code{readline-port} +creates it when first called, and on subsequent calls just returns +what it previously made. +@end defun + +@defun activate-readline +If the @code{current-input-port} is a terminal (@pxref{Terminals and +Ptys,, @code{isatty?}}) then enable readline for all reading from +@code{current-input-port} (@pxref{Default Ports}) and enable readline +features in the interactive REPL (@pxref{The REPL}). + +@example +(activate-readline) +(read-char) +@end example + +@code{activate-readline} enables readline on @code{current-input-port} +simply by a @code{set-current-input-port} to the @code{readline-port} +above. An application can do that directly if the extra REPL features +that @code{activate-readline} adds are not wanted. +@end defun + +@defun set-readline-prompt! prompt1 [prompt2] +Set the prompt string to print when reading input. This is used when +reading through @code{readline-port}, and is also the default prompt +for the @code{readline} function above. + +@var{prompt1} is the initial prompt shown. If a user might enter an +expression across multiple lines, then @var{prompt2} is a different +prompt to show further input required. In the Guile REPL for instance +this is an ellipsis (@samp{...}). + +See @code{set-buffered-input-continuation?!} (@pxref{Buffered Input}) +for an application to indicate the boundaries of logical expressions +(assuming of course an application has such a notion). +@end defun + +@subsubsection Completion + +@defun with-readline-completion-function completer thunk +Call @code{(@var{thunk})} with @var{completer} as the readline tab +completion function to be used in any readline calls within that +@var{thunk}. @var{completer} can be @code{#f} for no completion. + +@var{completer} will be called as @code{(@var{completer} text state)}, +as described in (@pxref{How Completing Works,,, readline, GNU Readline +Library}). @var{text} is a partial word to be completed, and each +@var{completer} call should return a possible completion string or +@code{#f} when no more. @var{state} is @code{#f} for the first call +asking about a new @var{text} then @code{#t} while getting further +completions of that @var{text}. + +Here's an example @var{completer} for user login names from the +password file (@pxref{User Information}), much like readline's own +@code{rl_username_completion_function}, + +@example +(define (username-completer-function text state) + (if (not state) + (setpwent)) ;; new, go to start of database + (let more ((pw (getpwent))) + (if pw + (if (string-prefix? text (passwd:name pw)) + (passwd:name pw) ;; this name matches, return it + (more (getpwent))) ;; doesn't match, look at next + (begin + ;; end of database, close it and return #f + (endpwent) + #f)))) +@end example +@end defun + +@defun apropos-completion-function text state +A completion function offering completions for Guile functions and +variables (all @code{define}s). This is the default completion +function. +@c +@c FIXME: Cross reference the ``apropos'' stuff when it's documented. +@c +@end defun + +@defun filename-completion-function text state +A completion function offering filename completions. This is +readline's @code{rl_filename_completion_function} (@pxref{Completion +Functions,,, readline, GNU Readline Library}). +@end defun + +@defun make-completion-function string-list +Return a completion function which offers completions from the +possibilities in @var{string-list}. Matching is case-sensitive. +@end defun + @page @node Value History diff --git a/doc/ref/scheme-debugging.texi b/doc/ref/scheme-debugging.texi index a9d1691d1..32a6a46bd 100644 --- a/doc/ref/scheme-debugging.texi +++ b/doc/ref/scheme-debugging.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 @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. @@ -511,3 +511,8 @@ behaviour as well as the more traditional @code{trace-here}. The older mechanism will probably become obsolete eventually, but it's worth keeping it around for a while until we are sure that the new mechanism is correct and does what programmers need. + + +@c Local Variables: +@c TeX-master: "guile.texi" +@c End: diff --git a/doc/ref/scheme-using.texi b/doc/ref/scheme-using.texi index c19823683..93d0949f8 100644 --- a/doc/ref/scheme-using.texi +++ b/doc/ref/scheme-using.texi @@ -449,11 +449,9 @@ section. * GDS Introduction:: * GDS Architecture:: * GDS Getting Started:: +* Working with GDS in Scheme Buffers:: * Displaying the Scheme Stack:: * Continuing Execution:: -* Evaluating Scheme Code:: -* Setting and Managing Breakpoints:: -* Access to Guile Help and Completion:: * Associating Buffers with Clients:: * An Example GDS Session:: @end menu @@ -501,7 +499,6 @@ existing ones @item continue execution, either normally or step by step. @end itemize -@end enumerate The presentation makes it very easy to move up and down the stack, showing whenever possible the source code for each frame in another @@ -509,11 +506,12 @@ Emacs buffer. It also provides convenient keystrokes for telling Guile what to do next; for example, you can select a stack frame and tell Guile to run until that frame completes, at which point GDS will display the frame's return value. +@end enumerate -Combinations of the above work well too. You can evaluate a fragment of -code (in a Scheme buffer) that contains a breakpoint, then use the -debugging interface to step through the code at the breakpoint. You can -also run a program until it hits a breakpoint, then examine, modify and +Combinations of these well too. You can evaluate a fragment of code (in +a Scheme buffer) that contains a breakpoint, then use the debugging +interface to step through the code at the breakpoint. You can also run +a program until it hits a breakpoint, then examine, modify and reevaluate some of the relevant code, and then tell the program to continue running. @@ -642,7 +640,6 @@ files or modules by sending it @code{load} or @code{use-modules} expressions. You can set breakpoints and evaluate code which hits those breakpoints, and GDS will pop up the stack at the breakpoint so you can explore your code by single-stepping and evaluating test expressions. - For a hands-on, tutorial introduction to using GDS in this way, use Emacs to open the file @file{gds-tutorial.txt} (which should have been installed as part of Guile, perhaps under @file{/usr/share/doc/guile}), @@ -655,21 +652,33 @@ following subsections describe the various ways of doing this. @subsubsection Setting Specific Breakpoints +The first option is to use @code{break-in} or @code{break-at} to set +specific breakpoints in the application's code. This requires code like +the following. + @lisp (use-modules (ice-9 debugging breakpoints) (ice-9 gds-client)) (break-in 'fact2 "ice-9/debugging/example-fns" #:behaviour gds-debug-trap) +(break-in 'facti "ice-9/debugging/example-fns" + #:behaviour gds-debug-trap) @end lisp -In this example, the program chooses to define its breakpoint explicitly -in its code, rather than downloading definitions from GDS, but it still -uses GDS to control what happens when the breakpoint is hit, by -specifying @code{gds-debug-trap} as the breakpoint behaviour. +@noindent +The @code{#:behaviour gds-debug-trap} clauses mean to use GDS to display +the stack when one of these breakpoints is hit. For more on +breakpoints, @code{break-in} and @code{break-at}, see @ref{Intro to +Breakpoints}. @subsubsection Setting GDS-managed Breakpoints +Instead of listing specific breakpoints in application code, you can use +GDS to manage the set of breakpoints that you want from Emacs, and tell +the application to download the breakpoints that it should set from +GDS. The code for this is: + @lisp (use-modules (ice-9 gds-client)) (set-gds-breakpoints) @@ -680,11 +689,52 @@ a set of breakpoint definitions. The program sets those breakpoints in its code, then continues running. When the program later hits one of the breakpoints, it will use GDS to -display the stack and wait for instruction on what to do next, as -described above. +display the stack and wait for instruction on what to do next. @subsubsection Invoking GDS when an Exception Occurs +Another option is to use GDS to catch and display any exceptions that +are thrown by the application's code. If you already have a +@code{lazy-catch} or @code{with-throw-handler} around the area of code +that you want to monitor, you just need to add the following to the +handler code: + +@lisp +(gds-debug-trap (throw->trap-context key args)) +@end lisp + +@noindent +where @code{key} and @code{args} are the first and rest arguments that +Guile passes to the handler. (In other words, they assume the handler +signature @code{(lambda (key . args) @dots{})}.) With Guile 1.8 or +later, you can also do this with a @code{catch}, by adding this same +code to the catch's pre-unwind handler. + +If you don't already have any of these, insert a whole +@code{with-throw-handler} expression (or @code{lazy-catch} if your Guile +is pre-1.8) around the code of interest like this: + +@lisp +(with-throw-handler #t + (lambda () + ;; Protected code here. + ) + (lambda (key . args) + (gds-debug-trap (throw->trap-context key args)))) +@end lisp + +In all cases you will need to use the @code{(ice-9 gds-client)} and +@code{(ice-9 debugging traps)} modules. + +Two special cases of this are the lazy-catch that the Guile REPL code +uses to catch exceptions in user code, and the lazy-catch inside the +@code{stack-catch} utility procedure that is provided by the +@code{(ice-9 stack-catch)} module. Both of these use a handler called +@code{lazy-handler-dispatch} (defined in @file{boot-9.scm}), which you +can hook into such that it calls GDS to display the stack when an +exception occurs. To do this, use the @code{on-lazy-handler-dispatch} +procedure as follows. + @lisp (use-modules (ice-9 gds-client) (ice-9 debugging traps)) @@ -692,18 +742,10 @@ described above. (on-lazy-handler-dispatch gds-debug-trap) @end lisp -This means that the program will use GDS to display the stack whenever -it hits an exception that is protected by a @code{lazy-catch} using -Guile's standard @code{lazy-catch-handler} (defined in -@file{boot-9.scm}). - -@code{lazy-catch-handler} is used by the @code{stack-catch} procedure, -provided by the @code{(ice-9 stack-catch)} module, so this will include -exceptions within a @code{stack-catch}. @code{lazy-catch-handler} is -also used by the standard Guile REPL, when you run Guile interactively, -so you can add the above lines to your @file{.guile} file if you want to -use GDS whenever something that you type into the REPL throws an -exception. +@noindent +After this the program will use GDS to display the stack whenever it +hits an exception that is protected by a @code{lazy-catch} using +@code{lazy-handler-dispatch}. @subsubsection Accepting GDS Instructions at Any Time @@ -745,14 +787,11 @@ This approach is not yet implemented, though. @subsubsection Utility Guile Implementation -We bring this subsection full circle by noting that the ``utility'' Guile -client, which GDS starts automatically when you use GDS as described -under approach 1 above, is really just a special case of ``a Guile -program or script which is started independently'' (approach 2), and -provides the services that the GDS front end needs by a simple -combination of some of the code fragments just described. +We conclude this subsection with an aside, by noting that the +``utility'' Guile client described above is nothing more than a +combination of the previous options. -To be precise, the code for the utility Guile client is essentially +To be precise, the code for the utility Guile client is essentially just this: @lisp @@ -765,12 +804,11 @@ this: @code{set-gds-breakpoints} works as already described. The @code{named-module-use!} line ensures that the client can process -@code{help} and @code{apropos} expressions, which is what the front end -sends to implement lookups in Guile's online help. The @code{#f} -parameter to @code{gds-accept-input} means that the @code{continue} -instruction will not cause the instruction loop to exit, which makes -sense here because the utility client has nothing to do except to -process GDS instructions. +@code{help} and @code{apropos} expressions, to implement lookups in +Guile's online help. The @code{#f} parameter to @code{gds-accept-input} +means that the @code{continue} instruction will not cause the +instruction loop to exit, which makes sense here because the utility +client has nothing to do except to process GDS instructions. (The utility client does not use @code{on-lazy-handler-dispatch}, because it has its own mechanism for catching and reporting exceptions @@ -780,6 +818,176 @@ stack, so the end result is very similar to what @code{on-lazy-handler-dispatch} provides.) +@node Working with GDS in Scheme Buffers +@subsection Working with GDS in Scheme Buffers + +The following subsections describe the facilities and key sequences that +GDS provides for working on code in @code{scheme-mode} buffers. + +@menu +* Access to Guile Help and Completion:: +* Setting and Managing Breakpoints:: +* Listing and Deleting Breakpoints:: +* Moving and Losing Breakpoints:: +* Evaluating Scheme Code:: +@end menu + + +@node Access to Guile Help and Completion +@subsubsection Access to Guile Help and Completion + +The following keystrokes provide fast and convenient access to Guile's +built in help, and to completion with respect to the set of defined and +accessible symbols. + +@table @kbd +@item C-h g +@findex gds-help-symbol +Get Guile help for a particular symbol, with the same results as if +you had typed @code{(help SYMBOL)} into the Guile REPL +(@code{gds-help-symbol}). The symbol to query defaults to the word at +or before the cursor but can also be entered or edited in the +minibuffer. The available help is popped up in a temporary Emacs +window. + +@item C-h C-g +@findex gds-apropos +List all accessible Guile symbols matching a given regular expression, +with the same results as if you had typed @code{(apropos REGEXP)} into +the Guile REPL (@code{gds-apropos}). The regexp to query defaults to +the word at or before the cursor but can also be entered or edited in +the minibuffer. The list of matching symbols is popped up in a +temporary Emacs window. + +@item M-@key{TAB} +@findex gds-complete-symbol +Try to complete the symbol at the cursor by matching it against the +set of all defined and accessible bindings in the associated Guile +process (@code{gds-complete-symbol}). If there are any extra +characters that can be definitively added to the symbol at point, they +are inserted. Otherwise, if there are any completions available, they +are popped up in a temporary Emacs window, where one of them can be +selected using either @kbd{@key{RET}} or the mouse. +@end table + + +@node Setting and Managing Breakpoints +@subsubsection Setting and Managing Breakpoints + +You can create a breakpoint in GDS by typing @kbd{C-x @key{SPC}} in a +Scheme mode buffer. To create a breakpoint on calls to a procedure --- +i.e. the equivalent of calling @code{break-in} --- place the cursor +anywhere within the procedure's definition, make sure that the region is +unset, and type @kbd{C-x @key{SPC}}. To create breakpoints on a +particular expression, or on the series of expressions in a particular +region --- i.e. as with @code{break-at} --- select a region containing +the open parentheses of the expressions where you want breakpoints, and +type @kbd{C-x @key{SPC}}. In other words, GDS assumes that you want a +@code{break-at} breakpoint if there is an active region, and a +@code{break-in} breakpoint otherwise. + +There are three supported breakpoint behaviours, known as @code{debug}, +@code{trace} and @code{trace-subtree}. @code{debug} means that GDS will +display the stack and wait for instruction when the breakpoint is hit. +@code{trace} means that a line will be written to the trace output +buffer (@code{*GDS Trace*}) when the breakpoint is hit, and when the +relevant expression or procedure call returns. @code{trace-subtree} +means that a line is written to the trace output buffer for every +evaluation step between when the breakpoint is hit and when the +expression or procedure returns. + +@kbd{C-x @key{SPC}} creates a breakpoint with behaviour according to the +@code{gds-default-breakpoint-type} variable, which by default is +@code{debug}; you can customize this if you prefer a different default. +You can also create a breakpoint with behaviour other than the current +default by using the alternative key sequences @kbd{C-c C-b d} (for +@code{debug}), @kbd{C-c C-b t} (for @code{trace}) and @kbd{C-c C-b T} +(for @code{trace-subtree}). + +GDS keeps all the breakpoints that you create in a single list, and +tries to set them in every Guile program that connects to GDS and calls +@code{set-gds-breakpoints}. That may sound surprising, because you are +probably thinking of one particular program when you create a +breakpoint; but GDS assumes that you would want the breakpoint to continue +taking effect if you stop and restart that program, and this is +currently achieved by giving all breakpoints to every program that asks +for them. In practice it doesn't matter if a program gets a breakpoint +definition --- such as ``break in procedure @code{foo}'' --- that it +can't actually map to any of its code. + +If there are already Guile programs connected to GDS when you create a +new breakpoint, GDS also tries to set the new breakpoint in each of +those programs at the earliest opportunity, which is usually when they +decide to stop and talk to GDS for some other reason. + + +@node Listing and Deleting Breakpoints +@subsubsection Listing and Deleting Breakpoints + +To see a list of all breakpoints, type @kbd{C-c C-b ?} (or @kbd{M-x +gds-describe-breakpoints}). GDS will then pop up a buffer that +describes each breakpoint and reports whether it is actually set in each +of the Guile programs connected to GDS. + +To delete a breakpoint, type @kbd{C-c C-b @key{backspace}}. If the +region is active when you do this, GDS will delete all of the +breakpoints in the region. If the region is not active, GDS tries to +delete a ``break-in'' breakpoint for the procedure whose definition +contains point (the Emacs cursor). In either case, deletion means that +the breakpoint is removed both from GDS's global list and from all of +the connected Guile programs that had previously managed to set it. + + +@node Moving and Losing Breakpoints +@subsubsection Moving and Losing Breakpoints + +Imagine that you set a breakpoint at line 80 of a Scheme code file, and +execute some code that hits this breakpoint; then you add some new code +at line 40, or delete some code that is no longer needed, and save the +file. Now the breakpoint will have moved up or down from line 80, and +any attached Guile program needs to be told about the new line number. +Otherwise, when a program loads this file again, it will try incorrectly +to set a breakpoint on whatever code is now at line 80, and will +@emph{not} set a breakpoint on the code where you want it. + +For this reason, GDS checks all breakpoint positions whenever you save a +Scheme file, and sends the new position to connected Guile programs for +any breakpoints that have moved. @dots{} [to be continued] + + +@node Evaluating Scheme Code +@subsubsection Evaluating Scheme Code + +The following keystrokes and commands provide various ways of sending +code to a Guile client process for evaluation. + +@table @kbd +@item M-C-x +@findex gds-eval-defun +Evaluate the ``top level defun'' that the cursor is in, in other words +the smallest balanced expression which includes the cursor and whose +opening parenthesis is in column 0 (@code{gds-eval-defun}). + +@item C-x C-e +@findex gds-eval-last-sexp +Evaluate the expression that ends just before the cursor +(@code{gds-eval-last-sexp}). This is designed so that it is easy to +evaluate an expression that you have just finished typing. + +@item C-c C-e +@findex gds-eval-expression +Read a Scheme expression using the minibuffer, and evaluate that +expression (@code{gds-eval-expression}). + +@item C-c C-r +@findex gds-eval-region +Evaluate the Scheme code in the marked region of the current buffer +(@code{gds-eval-region}). Note that GDS does not check whether the +region contains a balanced expression, or try to expand the region so +that it does; it uses the region exactly as it is. +@end table + + @node Displaying the Scheme Stack @subsection Displaying the Scheme Stack @@ -902,117 +1110,6 @@ remains in place and so will still fire at the appropriate point. @end table -@node Evaluating Scheme Code -@subsection Evaluating Scheme Code - -The following keystrokes and commands provide various ways of sending -code to a Guile client process for evaluation. - -@table @kbd -@item M-C-x -@findex gds-eval-defun -Evaluate the ``top level defun'' that the cursor is in, in other words -the smallest balanced expression which includes the cursor and whose -opening parenthesis is in column 0 (@code{gds-eval-defun}). - -@item C-x C-e -@findex gds-eval-last-sexp -Evaluate the expression that ends just before the cursor -(@code{gds-eval-last-sexp}). This is designed so that it is easy to -evaluate an expression that you have just finished typing. - -@item C-c C-e -@findex gds-eval-expression -Read a Scheme expression using the minibuffer, and evaluate that -expression (@code{gds-eval-expression}). - -@item C-c C-r -@findex gds-eval-region -Evaluate the Scheme code in the marked region of the current buffer -(@code{gds-eval-region}). Note that GDS does not check whether the -region contains a balanced expression, or try to expand the region so -that it does; it uses the region exactly as it is. -@end table - - -@node Setting and Managing Breakpoints -@subsection Setting and Managing Breakpoints - -You can create a breakpoint in GDS by typing @kbd{C-x @key{SPC}} in a -Scheme mode buffer. To create a breakpoint on calls to a procedure ---- i.e. the equivalent of calling @code{break-in} --- place the -cursor on the procedure's name and type @kbd{C-x @key{SPC}}. To -create breakpoints on a particular expression, or on the series of -expressions in a particular region --- i.e. as with @code{break-at} ---- select the expression or region in the usual way and type @kbd{C-x -@key{SPC}}. In general, GDS assumes that you want a @code{break-at} -breakpoint if there is an active region, and a @code{break-in} -breakpoint otherwise. - -When you create a breakpoint like this, two things happen. Firstly, -if the current buffer is associated with a Guile client program, the -new breakpoint definition is immediately sent to that client (or, if -the client cannot accept input immediately, it is held in readiness to -pass to the client at the next possible opportunity). This allows the -new breakpoint to take effect as soon as possible in the relevant -client program. - -Secondly, it is added to GDS's @emph{global} list of all breakpoints. -This list holds the breakpoint information that will be given to any -client program that asks for it by calling @code{set-gds-breakpoints}. -The fact that this list is global, rather than client-specific, means -that the breakpoints you have set will automatically be recreated if -the program you are debugging has to be stopped and restarted --- -which in my experience happens often.@footnote{An important point here -is that there is nothing that unambiguously relates two subsequent -runs of the same client program, which might allow GDS to pass on -breakpoint settings more precisely.} - -(The only possible downside of this last point is that if you are -debugging two programs in parallel, which have some code in common, -you might not want a common code breakpoint in one program to be set -in the other program as well. But this feels like a small concern in -comparison to the benefit of breakpoints persisting as just described.) - - -@node Access to Guile Help and Completion -@subsection Access to Guile Help and Completion - -The following keystrokes provide fast and convenient access to Guile's -built in help, and to completion with respect to the set of defined and -accessible symbols. - -@table @kbd -@item C-h g -@findex gds-help-symbol -Get Guile help for a particular symbol, with the same results as if -you had typed @code{(help SYMBOL)} into the Guile REPL -(@code{gds-help-symbol}). The symbol to query defaults to the word at -or before the cursor but can also be entered or edited in the -minibuffer. The available help is popped up in a temporary Emacs -window. - -@item C-h C-g -@findex gds-apropos -List all accessible Guile symbols matching a given regular expression, -with the same results as if you had typed @code{(apropos REGEXP)} into -the Guile REPL (@code{gds-apropos}). The regexp to query defaults to -the word at or before the cursor but can also be entered or edited in -the minibuffer. The list of matching symbols is popped up in a -temporary Emacs window. - -@item M-@key{TAB} -@findex gds-complete-symbol -Try to complete the symbol at the cursor by matching it against the -set of all defined and accessible bindings in the associated Guile -process (@code{gds-complete-symbol}). If there are any extra -characters that can be definitively added to the symbol at point, they -are inserted. Otherwise, if there are any completions available, they -are popped up in a temporary Emacs window, where one of them can be -selected using either @kbd{@key{RET}} or the mouse. -@end table - - @node Associating Buffers with Clients @subsection Associating Buffers with Clients |