diff --git a/doc/ref/ChangeLog b/doc/ref/ChangeLog index b541a74d6..bbd18a228 100644 --- a/doc/ref/ChangeLog +++ b/doc/ref/ChangeLog @@ -1,3 +1,36 @@ +2002-09-25 Neil Jerram + + * scheme-debug.texi (Debugging): Make sections into nodes. + (Debugging Options): Node removed. + + * scheme-options.texi (Feature Tracking): Brought forward before + sections on options. + (Runtime Options): New section, to group options-related nodes. + +2002-09-24 Neil Jerram + + * scheme-options.texi (Options and Config): Chapter name changed, + and intro text improved. + (Install Config): Brought forward, and renamed Build + Configuration. + + The following doc updates are from Ian Sheldon - thanks! + + * scheme-data.texi (Appending Strings, Regexp Functions, Match + Structures): Add examples. + (Regular Expressions): Add instruction to use (ice-9 regex) + module. + + * slib.texi (SLIB): Remove duplicate `the'. + +2002-09-22 Neil Jerram + + * scheme-options.texi (General option interface): Mention + eval-options-interface and debug-options-interface. + + * scheme-debug.texi (Debugging): New node describing source + properties. + 2002-09-19 Neil Jerram * scheme-utility.texi (Hook Reference): Improvements to hook docs. diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi index c819fb53d..22b308757 100644 --- a/doc/ref/guile.texi +++ b/doc/ref/guile.texi @@ -101,7 +101,7 @@ by the Free Software Foundation. @comment The title is printed in a large font. @title Guile Reference Manual @subtitle Edition @value{MANUAL_EDITION}, for use with Guile @value{VERSION} -@subtitle $Id: guile.texi,v 1.18 2002-04-20 19:26:40 ossau Exp $ +@subtitle $Id: guile.texi,v 1.19 2002-09-25 00:06:38 ossau Exp $ @c AUTHORS @@ -253,7 +253,7 @@ Part IV: Guile API Reference * Objects:: Low level object orientation support. * Modules:: Designing reusable code libraries. * Scheduling:: Threads, mutexes, asyncs and dynamic roots. -* Options and Config:: Runtime options and configuration. +* Options and Config:: Configuration, features and runtime options. * Translation:: Support for translating other languages. * Debugging:: Internal debugging interface. * Deprecated:: Features that are planned to disappear. diff --git a/doc/ref/repl-modules.texi b/doc/ref/repl-modules.texi index b136bd865..ea57e365b 100644 --- a/doc/ref/repl-modules.texi +++ b/doc/ref/repl-modules.texi @@ -68,7 +68,7 @@ expressions available. 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{General option interface}.) +debugging options (@pxref{User level options interfaces}.) Here is the list of readline options generated by typing @code{(readline-options 'full)} in Guile. You can also see the diff --git a/doc/ref/scheme-data.texi b/doc/ref/scheme-data.texi index b34a969a1..e557ecd6b 100755 --- a/doc/ref/scheme-data.texi +++ b/doc/ref/scheme-data.texi @@ -1901,6 +1901,12 @@ form a longer result string. @deffnx {C Function} scm_string_append (args) Return a newly allocated string whose characters form the concatenation of the given strings, @var{args}. + +@example +(let ((h "hello ")) + (string-append h "world")) +@result{} "hello world" +@end example @end deffn @@ -1925,6 +1931,11 @@ as Rx, these functions will not be available. You can tell whether your Guile installation includes regular expression support by checking whether @code{(provided? 'regex)} returns true. +The following regexp and string matching features are provided by the +@code{(ice-9 regex)} module. Before using the described functions, +you should load this module by executing @code{(use-modules (ice-9 +regex))}. + @menu * Regexp Functions:: Functions that create and match regexps. * Match Structures:: Finding what was matched by a regexp. @@ -1932,8 +1943,6 @@ checking whether @code{(provided? 'regex)} returns true. meta-characters. @end menu -[FIXME: it may be useful to include an Examples section. Parts of this -interface are bewildering on first glance.] @node Regexp Functions @subsection Regexp Functions @@ -1947,7 +1956,6 @@ This regular expression interface was modeled after that implemented by SCSH, the Scheme Shell. It is intended to be upwardly compatible with SCSH regular expressions. -@c begin (scm-doc-string "regex.scm" "string-match") @deffn {Scheme Procedure} string-match pattern str [start] Compile the string @var{pattern} into a regular expression and compare it with @var{str}. The optional numeric argument @var{start} specifies @@ -1959,6 +1967,18 @@ expression. @xref{Match Structures}. If @var{str} does not match @var{pattern} at all, @code{string-match} returns @code{#f}. @end deffn +Two examples of a match follow. In the first example, the pattern +matches the four digits in the match string. In the second, the pattern +matches nothing. + +@example +(string-match "[0-9][0-9][0-9][0-9]" "blah2002") +@result{} #("blah2002" (4 . 8)) + +(string-match "[A-Za-z]" "123456") +@result{} #f +@end example + Each time @code{string-match} is called, it must compile its @var{pattern} argument into a regular expression structure. This operation is expensive, which makes @code{string-match} inefficient if @@ -2030,6 +2050,22 @@ considered the end of a line. @end table @end deffn +@lisp +;; Regexp to match uppercase letters +(define r (make-regexp "[A-Z]*")) + +;; Regexp to match letters, ignoring case +(define ri (make-regexp "[A-Z]*" regexp/icase)) + +;; Search for bob using regexp r +(match:substring (regexp-exec r "bob")) +@result{} "" ; no match + +;; Search for bob using regexp ri +(match:substring (regexp-exec ri "Bob")) +@result{} "Bob" ; matched case insensitive +@end lisp + @deffn {Scheme Procedure} regexp? obj @deffnx {C Function} scm_regexp_p (obj) Return @code{#t} if @var{obj} is a compiled regular expression, @@ -2061,11 +2097,25 @@ The symbol @samp{post}. The portion of the matched string following the regexp match is written. @end itemize -@var{port} may be @code{#f}, in which case nothing is written; instead, -@code{regexp-substitute} constructs a string from the specified -@var{item}s and returns that. +The @var{port} argument may be @code{#f}, in which case nothing is +written; instead, @code{regexp-substitute} constructs a string from the +specified @var{item}s and returns that. @end deffn +The following example takes a regular expression that matches a standard +YYYYMMDD-format date such as @code{"20020828"}. The +@code{regexp-substitute} call returns a string computed from the +information in the match structure, consisting of the fields and text +from the original string reordered and reformatted. + +@lisp +(define date-regex "([0-9][0-9][0-9][0-9])([0-9][0-9])([0-9][0-9])") +(define s "Date 20020429 12am.") +(define sm (string-match date-regex s)) +(regexp-substitute #f sm 'pre 2 "-" 3 "-" 1 'post " (" 0 ")") +@result{} "Date 04-29-2002 12am. (20020429)" +@end lisp + @c begin (scm-doc-string "regex.scm" "regexp-substitute") @deffn {Scheme Procedure} regexp-substitute/global port regexp target [item@dots{}] Similar to @code{regexp-substitute}, but can be used to perform global @@ -2092,6 +2142,18 @@ return after processing a single match. @end itemize @end deffn +The example above for @code{regexp-substitute} could be rewritten as +follows to remove the @code{string-match} stage: + +@lisp +(define date-regex "([0-9][0-9][0-9][0-9])([0-9][0-9])([0-9][0-9])") +(define s "Date 20020429 12am.") +(regexp-substitute/global #f date-regex s + 'pre 2 "-" 3 "-" 1 'post " (" 0 ")") +@result{} "Date 04-29-2002 12am. (20020429)" +@end lisp + + @node Match Structures @subsection Match Structures @@ -2126,19 +2188,54 @@ If the regular expression as a whole matched, but the subexpression number @var{n} did not match, return @code{#f}. @end deffn +@lisp +(define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo")) +(match:substring s) +@result{} "2002" + +;; match starting at offset 6 in the string +(match:substring + (string-match "[0-9][0-9][0-9][0-9]" "blah987654" 6)) +@result{} "7654" +@end lisp + @c begin (scm-doc-string "regex.scm" "match:start") @deffn {Scheme Procedure} match:start match [n] Return the starting position of submatch number @var{n}. @end deffn +In the following example, the result is 4, since the match starts at +character index 4: + +@lisp +(define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo")) +(match:start s) +@result{} 4 +@end lisp + @c begin (scm-doc-string "regex.scm" "match:end") @deffn {Scheme Procedure} match:end match [n] Return the ending position of submatch number @var{n}. @end deffn +In the following example, the result is 8, since the match runs between +characters 4 and 8 (i.e. the ``2002''). + +@lisp +(define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo")) +(match:end s) +@result{} 8 +@end lisp + @c begin (scm-doc-string "regex.scm" "match:prefix") @deffn {Scheme Procedure} match:prefix match Return the unmatched portion of @var{target} preceding the regexp match. + +@lisp +(define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo")) +(match:prefix s) +@result{} "blah" +@end lisp @end deffn @c begin (scm-doc-string "regex.scm" "match:suffix") @@ -2146,6 +2243,12 @@ Return the unmatched portion of @var{target} preceding the regexp match. Return the unmatched portion of @var{target} following the regexp match. @end deffn +@lisp +(define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo")) +(match:suffix s) +@result{} "foo" +@end lisp + @c begin (scm-doc-string "regex.scm" "match:count") @deffn {Scheme Procedure} match:count match Return the number of parenthesized subexpressions from @var{match}. @@ -2158,6 +2261,13 @@ subexpression, and failed submatches are included in the count. Return the original @var{target} string. @end deffn +@lisp +(define s (string-match "[0-9][0-9][0-9][0-9]" "blah2002foo")) +(match:string s) +@result{} "blah2002foo" +@end lisp + + @node Backslash Escapes @subsection Backslash Escapes @@ -2987,8 +3097,8 @@ recognizes the alternative read syntax @code{:NAME}. Otherwise, tokens of the form @code{:NAME} are read as symbols, as required by R5RS. To enable and disable the alternative non-R5RS keyword syntax, you use -the @code{read-options} procedure documented in @ref{General option -interface} and @ref{Reader options}. +the @code{read-set!} procedure documented in @ref{User level options +interfaces} and @ref{Reader options}. @smalllisp (read-set! keywords 'prefix) diff --git a/doc/ref/scheme-debug.texi b/doc/ref/scheme-debug.texi index 670bd0884..66526557f 100644 --- a/doc/ref/scheme-debug.texi +++ b/doc/ref/scheme-debug.texi @@ -2,14 +2,63 @@ @node Debugging @chapter Debugging Infrastructure -@deffn {Scheme Procedure} debug-options-interface [setting] -@deffnx {C Function} scm_debug_options (setting) -Option interface for the debug options. Instead of using -this procedure directly, use the procedures @code{debug-enable}, -@code{debug-disable}, @code{debug-set!} and @code{debug-options}. -@end deffn +@menu +* Source Properties:: Remembering the source of an expression. +* Using Traps:: +* Capturing the Stack or Innermost Stack Frame:: +* Examining the Stack:: +* Examining Stack Frames:: +* Decoding Memoized Source Expressions:: +* Starting a New Stack:: +@end menu +@node Source Properties +@section Source Properties + +@cindex source properties +As Guile reads in Scheme code from file or from standard input, it +remembers the file name, line number and column number where each +expression begins. These pieces of information are known as the +@dfn{source properties} of the expression. If an expression undergoes +transformation --- for example, if there is a syntax transformer in +effect, or the expression is a macro call --- the source properties are +copied from the untransformed to the transformed expression so that, if +an error occurs when evaluating the transformed expression, Guile's +debugger can point back to the file and location where the expression +originated. + +The way that source properties are stored means that Guile can only +associate source properties with parenthesized expressions, and not, for +example, with individual symbols, numbers or strings. The difference +can be seen by typing @code{(xxx)} and @code{xxx} at the Guile prompt +(where the variable @code{xxx} has not been defined): + +@example +guile> (xxx) +standard input:2:1: In expression (xxx): +standard input:2:1: Unbound variable: xxx +ABORT: (unbound-variable) +guile> xxx +: In expression xxx: +: Unbound variable: xxx +ABORT: (unbound-variable) +@end example + +@noindent +In the latter case, no source properties were stored, so the best that +Guile could say regarding the location of the problem was ``''. + +The recording of source properties is controlled by the read option +named ``positions'' (@pxref{Reader options}). This option is switched +@emph{on} by default, together with the debug options ``debug'' and +``backtrace'' (@pxref{Debugger options}), when Guile is run +interactively; all these options are @emph{off} by default when Guile +runs a script non-interactively. + + +@node Using Traps @section Using Traps @deffn {Scheme Procedure} with-traps thunk @@ -23,6 +72,7 @@ Return @code{#t} if @var{obj} is a debug object. @end deffn +@node Capturing the Stack or Innermost Stack Frame @section Capturing the Stack or Innermost Stack Frame When an error occurs in a running program, or the program hits a @@ -72,6 +122,7 @@ debug object or a continuation. @end deffn +@node Examining the Stack @section Examining the Stack @deffn {Scheme Procedure} stack? obj @@ -104,6 +155,7 @@ which means that default values will be used. @end deffn +@node Examining Stack Frames @section Examining Stack Frames @deffn {Scheme Procedure} frame? obj @@ -172,6 +224,7 @@ output. @end deffn +@node Decoding Memoized Source Expressions @section Decoding Memoized Source Expressions @deffn {Scheme Procedure} memoized? obj @@ -190,6 +243,7 @@ Return the environment of the memoized expression @var{m}. @end deffn +@node Starting a New Stack @section Starting a New Stack @deffn {Scheme Syntax} start-stack id exp diff --git a/doc/ref/scheme-evaluation.texi b/doc/ref/scheme-evaluation.texi index 6357c78cf..bb0f4b2e6 100644 --- a/doc/ref/scheme-evaluation.texi +++ b/doc/ref/scheme-evaluation.texi @@ -144,8 +144,8 @@ Any whitespace before the next token is discarded. @end deffn The behaviour of Guile's Scheme reader can be modified by manipulating -its read options. For more information about options, @xref{General -option interface}. If you want to know which reader options are +its read options. For more information about options, @xref{User level +options interfaces}. If you want to know which reader options are available, @xref{Reader options}. @c FIXME::martin: This is taken from libguile/options.c. Is there @@ -358,8 +358,8 @@ is implicit). @c `Evaluator options' under `Options and Config'. The behaviour of Guile's evaluator can be modified by manipulating the -evaluator options. For more information about options, @xref{General -option interface}. If you want to know which evaluator options are +evaluator options. For more information about options, @xref{User level +options interfaces}. If you want to know which evaluator options are available, @xref{Evaluator options}. @c FIXME::martin: This is taken from libguile/options.c. Is there diff --git a/doc/ref/scheme-modules.texi b/doc/ref/scheme-modules.texi index 460891060..5ff76c9b5 100644 --- a/doc/ref/scheme-modules.texi +++ b/doc/ref/scheme-modules.texi @@ -168,18 +168,18 @@ algorithmically @dfn{rename} bindings. In contrast, when using the providing module's public interface, the entire export list is available without renaming (@pxref{Using Guile Modules}). -To use a module, it must be found and loaded. All Guile modules have -a unique @dfn{module name}, which is a list of one or more symbols. -Examples are @code{(ice-9 popen)} or @code{(srfi srfi-11)}. When -Guile searches for the code of a module, it constructs the name of the -file to load by concatenating the name elements with slashes between -the elements and appending a number of file name extensions from the -list @code{%load-extensions} (@pxref{Loading}). The resulting file -name is then searched in all directories in the variable -@code{%load-path} (@pxref{Install Config}). For example, the -@code{(ice-9 popen)} module would result in the filename -@code{ice-9/popen.scm} and searched in the installation directories of -Guile and in all other directories in the load path. +To use a module, it must be found and loaded. All Guile modules have a +unique @dfn{module name}, which is a list of one or more symbols. +Examples are @code{(ice-9 popen)} or @code{(srfi srfi-11)}. When Guile +searches for the code of a module, it constructs the name of the file to +load by concatenating the name elements with slashes between the +elements and appending a number of file name extensions from the list +@code{%load-extensions} (@pxref{Loading}). The resulting file name is +then searched in all directories in the variable @code{%load-path} +(@pxref{Build Config}). For example, the @code{(ice-9 popen)} module +would result in the filename @code{ice-9/popen.scm} and searched in the +installation directories of Guile and in all other directories in the +load path. @c FIXME::martin: Not sure about this, maybe someone knows better? Every module has a so-called syntax transformer associated with it. @@ -200,11 +200,11 @@ address these eventually. To use a Guile module is to access either its public interface or a custom interface (@pxref{General Information about Modules}). Both types of access are handled by the syntactic form @code{use-modules}, -which accepts one or more interface specifications and, upon -evaluation, arranges for those interfaces to be available to the -current module. This process may include locating and loading code -for a given module if that code has not yet been loaded, following -%load-path (@pxref{Install Config}). +which accepts one or more interface specifications and, upon evaluation, +arranges for those interfaces to be available to the current module. +This process may include locating and loading code for a given module if +that code has not yet been loaded, following %load-path (@pxref{Build +Config}). An @dfn{interface specification} has one of two forms. The first variation is simply to name the module, in which case its public diff --git a/doc/ref/scheme-options.texi b/doc/ref/scheme-options.texi index 63b7a2c57..0492ce9ed 100644 --- a/doc/ref/scheme-options.texi +++ b/doc/ref/scheme-options.texi @@ -1,371 +1,42 @@ @page @node Options and Config -@chapter Runtime Options and Configuration +@chapter Configuration, Features and Runtime Options -Guile's behaviour can be modified by setting options. For example, is -the language that Guile accepts case sensitive, or should the debugger -automatically show a backtrace on error? +Why is my Guile different from your Guile? There are three kinds of +possible variation: -Guile has two levels of interface for managing options: a low-level -control interface, and a user-level interface which allows the enabling -or disabling of options. +@itemize @bullet +@item +build differences --- different versions of the Guile source code, +installation directories, configuration flags that control pieces of +functionality being included or left out, etc. -Moreover, the options are classified in groups according to whether they -configure @emph{reading}, @emph{printing}, @emph{debugging} or -@emph{evaluating}. +@item +differences in dynamically loaded code --- behaviour and features +provided by modules that can be dynamically loaded into a running Guile + +@item +different runtime options --- some of the options that are provided for +controlling Guile's behaviour may be set differently. +@end itemize + +Guile provides ``introspective'' variables and procedures to query all +of these possible variations at runtime. For runtime options, it also +provides procedures to change the settings of options and to obtain +documentation on what the options mean. @menu -* General option interface:: -* Reader options:: -* Printing options:: -* Debugger options:: -* Evaluator options:: -* Evaluator trap options:: -* Examples of option use:: -* Install Config:: Installation and configuration data. +* Build Config:: Build and installation configuration. * Feature Tracking:: Available features in the Guile process. +* Runtime Options:: Controlling Guile's runtime behaviour. @end menu -@node General option interface -@section General option interface -We will use the expression @code{} to represent @code{read}, -@code{print}, @code{debug} or @code{evaluator}. +@node Build Config +@section Configuration, Build and Installation -@subheading Low level - -@c NJFIXME -@deffn {Scheme Procedure} -options-interface -@deffnx {Scheme Procedure} read-options-interface [SOME-INT] -@deffnx {Scheme Procedure} print-options-interface [SOME-INT] -@deffnx {Scheme Procedure} evaluator-traps-interface [SOME-INT] -@deffnx {Scheme Procedure} read-options-interface [SOME-INT] -[FIXME: I have just taken the comments for C routine scm_options that -implements all of these. It needs to be presented better.] - -If scm_options is called without arguments, the current option setting -is returned. If the argument is an option setting, options are altered -and the old setting is returned. If the argument isn't a list, a list -of sublists is returned, where each sublist contains option name, value -and documentation string. -@end deffn - - -@subheading User level - -@c @deftp {Data type} scm_option -@c @code{scm_option} is used to represent run time options. It can be a -@c @emph{boolean} type, in which case the option will be set by the strings -@c @code{"yes"} and @code{"no"}. It can be a -@c @end deftp - -@c NJFIXME -@deffn {Scheme Procedure} -options [arg] -@deffnx {Scheme Procedure} read-options [arg] -@deffnx {Scheme Procedure} print-options [arg] -@deffnx {Scheme Procedure} debug-options [arg] -@deffnx {Scheme Procedure} traps [arg] -These functions list the options in their group. The optional argument -@var{arg} is a symbol which modifies the form in which the options are -presented. - -With no arguments, @code{-options} returns the values of the -options in that particular group. If @var{arg} is @code{'help}, a -description of each option is given. If @var{arg} is @code{'full}, -programmers' options are also shown. - -@var{arg} can also be a list representing the state of all options. In -this case, the list contains single symbols (for enabled boolean -options) and symbols followed by values. -@end deffn -[FIXME: I don't think 'full is ever any different from 'help. What's -up?] - -@c NJFIXME -@deffn {Scheme Procedure} -enable option-symbol -@deffnx {Scheme Procedure} read-enable option-symbol -@deffnx {Scheme Procedure} print-enable option-symbol -@deffnx {Scheme Procedure} debug-enable option-symbol -@deffnx {Scheme Procedure} trap-enable option-symbol -These functions set the specified @var{option-symbol} in their options -group. They only work if the option is boolean, and throw an error -otherwise. -@end deffn - -@c NJFIXME -@deffn {Scheme Procedure} -disable option-symbol -@deffnx {Scheme Procedure} read-disable option-symbol -@deffnx {Scheme Procedure} print-disable option-symbol -@deffnx {Scheme Procedure} debug-disable option-symbol -@deffnx {Scheme Procedure} trap-disable option-symbol -These functions turn off the specified @var{option-symbol} in their -options group. They only work if the option is boolean, and throw an -error otherwise. -@end deffn - -@c NJFIXME -@deffn syntax -set! option-symbol value -@deffnx syntax read-set! option-symbol value -@deffnx syntax print-set! option-symbol value -@deffnx syntax debug-set! option-symbol value -@deffnx syntax trap-set! option-symbol value -These functions set a non-boolean @var{option-symbol} to the specified -@var{value}. -@end deffn - - -@node Reader options -@section Reader options -@cindex options - read -@cindex read options - -Here is the list of reader options generated by typing -@code{(read-options 'full)} in Guile. You can also see the default -values. - -@smalllisp -keywords #f Style of keyword recognition: #f or 'prefix -case-insensitive no Convert symbols to lower case. -positions yes Record positions of source code expressions. -copy no Copy source code expressions. -@end smalllisp - -Notice that while Standard Scheme is case insensitive, to ease -translation of other Lisp dialects, notably Emacs Lisp, into Guile, -Guile is case-sensitive by default. - -To make Guile case insensitive, you can type - -@smalllisp -(read-enable 'case-insensitive) -@end smalllisp - -@node Printing options -@section Printing options - -Here is the list of print options generated by typing -@code{(print-options 'full)} in Guile. You can also see the default -values. - -@smallexample -source no Print closures with source. -closure-hook #f Hook for printing closures. -@end smallexample - - -@node Evaluator options -@section Evaluator options - -These are the evaluator options with their default values, as they are -printed by typing @code{(eval-options 'full)} in Guile. - -@smallexample -stack 22000 Size of thread stacks (in machine words). -@end smallexample - -@node Evaluator trap options -@section Evaluator trap options -[FIXME: These flags, together with their corresponding handlers, are not -user level options. Probably this entire section should be moved to the -documentation about the low-level programmer debugging interface.] - -Here is the list of evaluator trap options generated by typing -@code{(traps 'full)} in Guile. You can also see the default values. - -@smallexample -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. -traps yes Enable evaluator traps. -@end smallexample - -@deffn apply-frame-handler key cont tailp -Called when a procedure is being applied. - -Called if: - -@itemize @bullet -@item -evaluator traps are enabled [traps interface], and -@item -either -@itemize @minus -@item -@code{apply-frame} is enabled [traps interface], or -@item -trace mode is on [debug-options interface], and the procedure being -called has the trace property enabled. -@end itemize -@end itemize - -If cheap traps are enabled [debug-options interface], @var{cont} is a -debug object, otherwise it is a restartable continuation. - -@var{tailp} is true if this is a tail call -@end deffn - -@deffn exit-frame-handler key cont retval -Called when a value is returned from a procedure. - -Called if: - -@itemize @bullet -@item -evaluator traps are enabled [traps interface], and -@item -either -@itemize @minus -@item - @code{exit-frame} is enabled [traps interface], or -@item -trace mode is on [debug-options interface], and the procedure being -called has the trace property enabled. -@end itemize -@end itemize - -If cheap traps are enabled [debug-options interface], @var{cont} is a -debug object, otherwise it is a restartable continuation. - -@var{retval} is the return value. -@end deffn - -@node Debugger options -@section Debugger options - -Here is the list of print options generated by typing -@code{(debug-options 'full)} in Guile. You can also see the default -values. - -@smallexample -stack 20000 Stack size limit (0 = no check). -debug yes Use the debugging evaluator. -backtrace no Show backtrace on error. -depth 20 Maximal length of printed backtrace. -maxdepth 1000 Maximal number of stored backtrace frames. -frames 3 Maximum number of tail-recursive frames in backtrace. -indent 10 Maximal indentation in backtrace. -backwards no Display backtrace in anti-chronological order. -procnames yes Record procedure names at definition. -trace no *Trace mode. -breakpoints no *Check for breakpoints. -cheap yes *Flyweight representation of the stack at traps. -@end smallexample - -@subsection Stack overflow - -@cindex overflow, stack -@cindex stack overflow -Stack overflow errors are caused by a computation trying to use more -stack space than has been enabled by the @code{stack} option. They are -reported like this: - -@lisp -(non-tail-recursive-factorial 500) -@print{} -ERROR: Stack overflow -ABORT: (stack-overflow) -@end lisp - -If you get an error like this, you can either try rewriting your code to -use less stack space, or increase the maximum stack size. To increase -the maximum stack size, use @code{debug-set!}, for example: - -@lisp -(debug-set! stack 200000) -@result{} -(show-file-name #t stack 200000 debug backtrace depth 20 maxdepth 1000 frames 3 indent 10 width 79 procnames cheap) - -(non-tail-recursive-factorial 500) -@result{} -122013682599111006870123878542304692625357434@dots{} -@end lisp - -If you prefer to try rewriting your code, you may be able to save stack -space by making some of your procedures @dfn{tail recursive}. For a -description of what this means, see @ref{Proper tail -recursion,,,r5rs,The Revised^5 Report on Scheme}. - - -@node Examples of option use -@section Examples of option use - -Here is an example of a session in which some read and debug option -handling procedures are used. In this example, the user - -@enumerate -@item -Notices that the symbols @code{abc} and @code{aBc} are not the same -@item -Examines the @code{read-options}, and sees that @code{case-insensitive} -is set to ``no''. -@item -Enables @code{case-insensitive} -@item -Verifies that now @code{aBc} and @code{abc} are the same -@item -Disables @code{case-insensitive} and enables debugging @code{backtrace} -@item -Reproduces the error of displaying @code{aBc} with backtracing enabled -[FIXME: this last example is lame because there is no depth in the -backtrace. Need to give a better example, possibly putting debugging -option examples in a separate session.] -@end enumerate - - -@smalllisp -guile> (define abc "hello") -guile> abc -"hello" -guile> aBc -ERROR: In expression aBc: -ERROR: Unbound variable: aBc -ABORT: (misc-error) - -Type "(backtrace)" to get more information. -guile> (read-options 'help) -keywords #f Style of keyword recognition: #f or 'prefix -case-insensitive no Convert symbols to lower case. -positions yes Record positions of source code expressions. -copy no Copy source code expressions. -guile> (debug-options 'help) -stack 20000 Stack size limit (0 = no check). -debug yes Use the debugging evaluator. -backtrace no Show backtrace on error. -depth 20 Maximal length of printed backtrace. -maxdepth 1000 Maximal number of stored backtrace frames. -frames 3 Maximum number of tail-recursive frames in backtrace. -indent 10 Maximal indentation in backtrace. -backwards no Display backtrace in anti-chronological order. -procnames yes Record procedure names at definition. -trace no *Trace mode. -breakpoints no *Check for breakpoints. -cheap yes *Flyweight representation of the stack at traps. -guile> (read-enable 'case-insensitive) -(keywords #f case-insensitive positions) -guile> aBc -"hello" -guile> (read-disable 'case-insensitive) -(keywords #f positions) -guile> (debug-enable 'backtrace) -(stack 20000 debug backtrace depth 20 maxdepth 1000 frames 3 indent 10 procnames cheap) -guile> aBc - -Backtrace: -0* aBc - -ERROR: In expression aBc: -ERROR: Unbound variable: aBc -ABORT: (misc-error) -guile> -@end smalllisp - - -@node Install Config -@section Installation and Configuration Data - -It is often useful to have site-specific information about the current -Guile installation. This chapter describes how to find out about -Guile's configuration at run time. +The following procedures and variables provide information about how +Guile was configured, built and installed on your system. @deffn {Scheme Procedure} version @deffnx {Scheme Procedure} major-version @@ -386,33 +57,39 @@ or micro version number, respectively. @end lisp @end deffn -@c NJFIXME not in libguile! -@deffn {Scheme Procedure} libguile-config-stamp -Return a string describing the date on which @code{libguile} was -configured. This is used to determine whether the Guile core -interpreter and the ice-9 runtime have grown out of date with one -another. -@end deffn - @deffn {Scheme Procedure} %package-data-dir @deffnx {C Function} scm_sys_package_data_dir () -Return the name of the directory where Scheme packages, modules and -libraries are kept. On most Unix systems, this will be -@samp{/usr/local/share/guile}. +Return the name of the directory under which Guile Scheme files in +general are stored. On Unix-like systems, this is usually +@file{/usr/local/share/guile} or @file{/usr/share/guile}. @end deffn @deffn {Scheme Procedure} %library-dir @deffnx {C Function} scm_sys_library_dir () -Return the directory where the Guile Scheme library files are installed. -E.g., may return "/usr/share/guile/1.3.5". +Return the name of the directory where the Guile Scheme files that +belong to the core Guile installation (as opposed to files from a 3rd +party package) are installed. On Unix-like systems, this is usually +@file{/usr/local/share/guile/} or +@file{/usr/share/guile/}, for example: +@file{/usr/local/share/guile/1.6.0}. @end deffn @deffn {Scheme Procedure} %site-dir @deffnx {C Function} scm_sys_site_dir () -Return the directory where the Guile site files are installed. -E.g., may return "/usr/share/guile/site". +Return the name of the directory where Guile Scheme files specific to +your site should be installed. On Unix-like systems, this is usually +@file{/usr/local/share/guile/site} or @file{/usr/share/guile/site}. @end deffn +@cindex GUILE_LOAD_PATH +@defvar %load-path +List of directories which should be searched for Scheme modules and +libraries. @code{%load-path} is initialized when Guile starts up to +@code{(list (%site-dir) (%library-dir) (%package-data-dir) ".")}, +prepended with the contents of the GUILE_LOAD_PATH environment variable, +if it is set. +@end defvar + @deffn {Scheme Procedure} parse-path path [tail] @deffnx {C Function} scm_parse_path (path, tail) Parse @var{path}, which is expected to be a colon-separated @@ -432,34 +109,30 @@ directory in @var{path}, we search for @var{filename} concatenated with each @var{extension}. @end deffn -@defvar %load-path -List of directories which should be searched for Scheme -modules and libraries. -@end defvar - @defvar %guile-build-info Alist of information collected during the building of a particular -@code{guile} program. Entries can be grouped into one of several -categories: directories, env vars, and versioning info. +Guile. Entries can be grouped into one of several categories: +directories, env vars, and versioning info. Briefly, here are the keys in @code{%guile-build-info}, by group: -@itemize @bullet -@item directories + +@table @asis +@item directories srcdir, top_srcdir, prefix, exec_prefix, bindir, sbindir, libexecdir, datadir, sysconfdir, sharedstatedir, localstatedir, libdir, infodir, mandir, includedir, pkgdatadir, pkglibdir, pkgincludedir -@item env vars +@item env vars LIBS -@item versioning info +@item versioning info guileversion, libguileinterface, buildstamp -@end itemize +@end table -Values are all strings. The value for @code{LIBS} is typically found also as -a part of "guile-config link" output. The value for @code{guileversion} has -form X.Y.Z, and should be the same as returned by @code{version}. The value -for @code{libguileinterface} is libtool compatible and has form -CURRENT:REVISION:AGE. The value for @code{buildstamp} is the output of the -date(1) command. +Values are all strings. The value for @code{LIBS} is typically found +also as a part of "guile-config link" output. The value for +@code{guileversion} has form X.Y.Z, and should be the same as returned +by @code{(version)}. The value for @code{libguileinterface} is libtool +compatible and has form CURRENT:REVISION:AGE. The value for +@code{buildstamp} is the output of the date(1) command. In the source, @code{%guile-build-info} is initialized from libguile/libpath.h, which is completely generated, so deleting this file @@ -646,6 +319,377 @@ is probably safer to do so directly using the @code{defined?} procedure than to test for the corresponding feature using @code{feature?}. +@node Runtime Options +@section Runtime Options + +Guile's runtime behaviour can be modified by setting options. For +example, is the language that Guile accepts case sensitive, or should +the debugger automatically show a backtrace on error? + +Guile has two levels of interface for managing options: a low-level +control interface, and a user-level interface which allows the enabling +or disabling of options. + +Moreover, the options are classified in groups according to whether they +configure @emph{reading}, @emph{printing}, @emph{debugging} or +@emph{evaluating}. + +@menu +* Low level options interfaces:: +* User level options interfaces:: +* Reader options:: +* Printing options:: +* Debugger options:: +* Evaluator options:: +* Evaluator trap options:: +* Examples of option use:: +@end menu + + +@node Low level options interfaces +@subsection Low Level Options Interfaces + +@deffn {Scheme Procedure} read-options-interface [setting] +@deffnx {Scheme Procedure} eval-options-interface [setting] +@deffnx {Scheme Procedure} print-options-interface [setting] +@deffnx {Scheme Procedure} debug-options-interface [setting] +@deffnx {Scheme Procedure} evaluator-traps-interface [setting] +@deffnx {C Function} scm_read_options (setting) +@deffnx {C Function} scm_eval_options_interface (setting) +@deffnx {C Function} scm_print_options (setting) +@deffnx {C Function} scm_debug_options (setting) +@deffnx {C Function} scm_evaluator_traps (setting) +If one of these procedures is called with no arguments (or with +@code{setting == SCM_UNDEFINED} in C code), it returns a list describing +the current setting of the read, eval, print, debug or evaluator traps +options respectively. The setting of a boolean option is indicated +simply by the presence or absence of the option symbol in the list. The +setting of a non-boolean option is indicated by the presence of the +option symbol immediately followed by the option's current value. + +If called with a list argument, these procedures interpret the list as +an option setting and modify the relevant options accordingly. [FIXME +--- this glosses over a lot of details!] + +If called with any other argument, such as @code{'help}, these +procedures return a list of entries like @code{(@var{OPTION-SYMBOL} +@var{DEFAULT-VALUE} @var{DOC-STRING})}, with each entry giving the +default value and documentation for each option symbol in the relevant +set of options. +@end deffn + + +@node User level options interfaces +@subsection User Level Options Interfaces + +@c @deftp {Data type} scm_option +@c @code{scm_option} is used to represent run time options. It can be a +@c @emph{boolean} type, in which case the option will be set by the strings +@c @code{"yes"} and @code{"no"}. It can be a +@c @end deftp + +@c NJFIXME +@deffn {Scheme Procedure} -options [arg] +@deffnx {Scheme Procedure} read-options [arg] +@deffnx {Scheme Procedure} print-options [arg] +@deffnx {Scheme Procedure} debug-options [arg] +@deffnx {Scheme Procedure} traps [arg] +These functions list the options in their group. The optional argument +@var{arg} is a symbol which modifies the form in which the options are +presented. + +With no arguments, @code{-options} returns the values of the +options in that particular group. If @var{arg} is @code{'help}, a +description of each option is given. If @var{arg} is @code{'full}, +programmers' options are also shown. + +@var{arg} can also be a list representing the state of all options. In +this case, the list contains single symbols (for enabled boolean +options) and symbols followed by values. +@end deffn +[FIXME: I don't think 'full is ever any different from 'help. What's +up?] + +@c NJFIXME +@deffn {Scheme Procedure} -enable option-symbol +@deffnx {Scheme Procedure} read-enable option-symbol +@deffnx {Scheme Procedure} print-enable option-symbol +@deffnx {Scheme Procedure} debug-enable option-symbol +@deffnx {Scheme Procedure} trap-enable option-symbol +These functions set the specified @var{option-symbol} in their options +group. They only work if the option is boolean, and throw an error +otherwise. +@end deffn + +@c NJFIXME +@deffn {Scheme Procedure} -disable option-symbol +@deffnx {Scheme Procedure} read-disable option-symbol +@deffnx {Scheme Procedure} print-disable option-symbol +@deffnx {Scheme Procedure} debug-disable option-symbol +@deffnx {Scheme Procedure} trap-disable option-symbol +These functions turn off the specified @var{option-symbol} in their +options group. They only work if the option is boolean, and throw an +error otherwise. +@end deffn + +@c NJFIXME +@deffn syntax -set! option-symbol value +@deffnx syntax read-set! option-symbol value +@deffnx syntax print-set! option-symbol value +@deffnx syntax debug-set! option-symbol value +@deffnx syntax trap-set! option-symbol value +These functions set a non-boolean @var{option-symbol} to the specified +@var{value}. +@end deffn + + +@node Reader options +@subsection Reader options +@cindex options - read +@cindex read options + +Here is the list of reader options generated by typing +@code{(read-options 'full)} in Guile. You can also see the default +values. + +@smalllisp +keywords #f Style of keyword recognition: #f or 'prefix +case-insensitive no Convert symbols to lower case. +positions yes Record positions of source code expressions. +copy no Copy source code expressions. +@end smalllisp + +Notice that while Standard Scheme is case insensitive, to ease +translation of other Lisp dialects, notably Emacs Lisp, into Guile, +Guile is case-sensitive by default. + +To make Guile case insensitive, you can type + +@smalllisp +(read-enable 'case-insensitive) +@end smalllisp + +@node Printing options +@subsection Printing options + +Here is the list of print options generated by typing +@code{(print-options 'full)} in Guile. You can also see the default +values. + +@smallexample +source no Print closures with source. +closure-hook #f Hook for printing closures. +@end smallexample + + +@node Evaluator options +@subsection Evaluator options + +These are the evaluator options with their default values, as they are +printed by typing @code{(eval-options 'full)} in Guile. + +@smallexample +stack 22000 Size of thread stacks (in machine words). +@end smallexample + + +@node Evaluator trap options +@subsection Evaluator trap options +[FIXME: These flags, together with their corresponding handlers, are not +user level options. Probably this entire section should be moved to the +documentation about the low-level programmer debugging interface.] + +Here is the list of evaluator trap options generated by typing +@code{(traps 'full)} in Guile. You can also see the default values. + +@smallexample +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. +traps yes Enable evaluator traps. +@end smallexample + +@deffn apply-frame-handler key cont tailp +Called when a procedure is being applied. + +Called if: + +@itemize @bullet +@item +evaluator traps are enabled [traps interface], and +@item +either +@itemize @minus +@item +@code{apply-frame} is enabled [traps interface], or +@item +trace mode is on [debug-options interface], and the procedure being +called has the trace property enabled. +@end itemize +@end itemize + +If cheap traps are enabled [debug-options interface], @var{cont} is a +debug object, otherwise it is a restartable continuation. + +@var{tailp} is true if this is a tail call +@end deffn + +@deffn exit-frame-handler key cont retval +Called when a value is returned from a procedure. + +Called if: + +@itemize @bullet +@item +evaluator traps are enabled [traps interface], and +@item +either +@itemize @minus +@item + @code{exit-frame} is enabled [traps interface], or +@item +trace mode is on [debug-options interface], and the procedure being +called has the trace property enabled. +@end itemize +@end itemize + +If cheap traps are enabled [debug-options interface], @var{cont} is a +debug object, otherwise it is a restartable continuation. + +@var{retval} is the return value. +@end deffn + +@node Debugger options +@subsection Debugger options + +Here is the list of print options generated by typing +@code{(debug-options 'full)} in Guile. You can also see the default +values. + +@smallexample +stack 20000 Stack size limit (0 = no check). +debug yes Use the debugging evaluator. +backtrace no Show backtrace on error. +depth 20 Maximal length of printed backtrace. +maxdepth 1000 Maximal number of stored backtrace frames. +frames 3 Maximum number of tail-recursive frames in backtrace. +indent 10 Maximal indentation in backtrace. +backwards no Display backtrace in anti-chronological order. +procnames yes Record procedure names at definition. +trace no *Trace mode. +breakpoints no *Check for breakpoints. +cheap yes *Flyweight representation of the stack at traps. +@end smallexample + +@subsubsection Stack overflow + +@cindex overflow, stack +@cindex stack overflow +Stack overflow errors are caused by a computation trying to use more +stack space than has been enabled by the @code{stack} option. They are +reported like this: + +@lisp +(non-tail-recursive-factorial 500) +@print{} +ERROR: Stack overflow +ABORT: (stack-overflow) +@end lisp + +If you get an error like this, you can either try rewriting your code to +use less stack space, or increase the maximum stack size. To increase +the maximum stack size, use @code{debug-set!}, for example: + +@lisp +(debug-set! stack 200000) +@result{} +(show-file-name #t stack 200000 debug backtrace depth 20 maxdepth 1000 frames 3 indent 10 width 79 procnames cheap) + +(non-tail-recursive-factorial 500) +@result{} +122013682599111006870123878542304692625357434@dots{} +@end lisp + +If you prefer to try rewriting your code, you may be able to save stack +space by making some of your procedures @dfn{tail recursive}. For a +description of what this means, see @ref{Proper tail +recursion,,,r5rs,The Revised^5 Report on Scheme}. + + +@node Examples of option use +@subsection Examples of option use + +Here is an example of a session in which some read and debug option +handling procedures are used. In this example, the user + +@enumerate +@item +Notices that the symbols @code{abc} and @code{aBc} are not the same +@item +Examines the @code{read-options}, and sees that @code{case-insensitive} +is set to ``no''. +@item +Enables @code{case-insensitive} +@item +Verifies that now @code{aBc} and @code{abc} are the same +@item +Disables @code{case-insensitive} and enables debugging @code{backtrace} +@item +Reproduces the error of displaying @code{aBc} with backtracing enabled +[FIXME: this last example is lame because there is no depth in the +backtrace. Need to give a better example, possibly putting debugging +option examples in a separate session.] +@end enumerate + + +@smalllisp +guile> (define abc "hello") +guile> abc +"hello" +guile> aBc +ERROR: In expression aBc: +ERROR: Unbound variable: aBc +ABORT: (misc-error) + +Type "(backtrace)" to get more information. +guile> (read-options 'help) +keywords #f Style of keyword recognition: #f or 'prefix +case-insensitive no Convert symbols to lower case. +positions yes Record positions of source code expressions. +copy no Copy source code expressions. +guile> (debug-options 'help) +stack 20000 Stack size limit (0 = no check). +debug yes Use the debugging evaluator. +backtrace no Show backtrace on error. +depth 20 Maximal length of printed backtrace. +maxdepth 1000 Maximal number of stored backtrace frames. +frames 3 Maximum number of tail-recursive frames in backtrace. +indent 10 Maximal indentation in backtrace. +backwards no Display backtrace in anti-chronological order. +procnames yes Record procedure names at definition. +trace no *Trace mode. +breakpoints no *Check for breakpoints. +cheap yes *Flyweight representation of the stack at traps. +guile> (read-enable 'case-insensitive) +(keywords #f case-insensitive positions) +guile> aBc +"hello" +guile> (read-disable 'case-insensitive) +(keywords #f positions) +guile> (debug-enable 'backtrace) +(stack 20000 debug backtrace depth 20 maxdepth 1000 frames 3 indent 10 procnames cheap) +guile> aBc + +Backtrace: +0* aBc + +ERROR: In expression aBc: +ERROR: Unbound variable: aBc +ABORT: (misc-error) +guile> +@end smalllisp + + @c Local Variables: @c TeX-master: "guile.texi" @c End: diff --git a/doc/ref/slib.texi b/doc/ref/slib.texi index 4d9e8c14c..a4eea1c19 100644 --- a/doc/ref/slib.texi +++ b/doc/ref/slib.texi @@ -2,8 +2,8 @@ @node SLIB @chapter SLIB -Before the the SLIB facilities can be used, the following Scheme -expression must be executed: +Before the SLIB facilities can be used, the following Scheme expression +must be executed: @smalllisp (use-modules (ice-9 slib))