diff options
-rw-r--r-- | doc/ref/ChangeLog | 33 | ||||
-rw-r--r-- | doc/ref/guile.texi | 4 | ||||
-rw-r--r-- | doc/ref/repl-modules.texi | 2 | ||||
-rwxr-xr-x | doc/ref/scheme-data.texi | 126 | ||||
-rw-r--r-- | doc/ref/scheme-debug.texi | 70 | ||||
-rw-r--r-- | doc/ref/scheme-evaluation.texi | 8 | ||||
-rw-r--r-- | doc/ref/scheme-modules.texi | 34 | ||||
-rw-r--r-- | doc/ref/scheme-options.texi | 688 | ||||
-rw-r--r-- | doc/ref/slib.texi | 4 |
9 files changed, 605 insertions, 364 deletions
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 <neil@ossau.uklinux.net> + + * 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 <neil@ossau.uklinux.net> + + * 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 <neil@ossau.uklinux.net> + + * 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 <neil@ossau.uklinux.net> * 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 +<unnamed port>: In expression xxx: +<unnamed port>: 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 ``<unnamed +port>''. + +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,10 +1,330 @@ @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: + +@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. + +@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 +* Build Config:: Build and installation configuration. +* Feature Tracking:: Available features in the Guile process. +* Runtime Options:: Controlling Guile's runtime behaviour. +@end menu + + +@node Build Config +@section Configuration, Build and Installation + +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 +@deffnx {Scheme Procedure} minor-version +@deffnx {Scheme Procedure} micro-version +@deffnx {C Function} scm_version () +@deffnx {C Function} scm_major_version () +@deffnx {C Function} scm_minor_version () +@deffnx {C Function} scm_micro_version () +Return a string describing Guile's version number, or its major, minor +or micro version number, respectively. + +@lisp +(version) @result{} "1.6.0" +(major-version) @result{} "1" +(minor-version) @result{} "6" +(micro-version) @result{} "0" +@end lisp +@end deffn + +@deffn {Scheme Procedure} %package-data-dir +@deffnx {C Function} scm_sys_package_data_dir () +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 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/<VERSION>} or +@file{/usr/share/guile/<VERSION>}, 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 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 +string, into a list and return the resulting list with +@var{tail} appended. If @var{path} is @code{#f}, @var{tail} +is returned. +@end deffn + +@deffn {Scheme Procedure} search-path path filename [extensions] +@deffnx {C Function} scm_search_path (path, filename, extensions) +Search @var{path} for a directory containing a file named +@var{filename}. The file must be readable, and not a directory. +If we find one, return its full filename; otherwise, return +@code{#f}. If @var{filename} is absolute, return it unchanged. +If given, @var{extensions} is a list of strings; for each +directory in @var{path}, we search for @var{filename} +concatenated with each @var{extension}. +@end deffn + +@defvar %guile-build-info +Alist of information collected during the building of a particular +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: + +@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 +LIBS +@item versioning info +guileversion, libguileinterface, buildstamp +@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. + +In the source, @code{%guile-build-info} is initialized from +libguile/libpath.h, which is completely generated, so deleting this file +before a build guarantees up-to-date values for that build. +@end defvar + + +@node Feature Tracking +@section Feature Tracking + +Guile has a Scheme level variable @code{*features*} that keeps track to +some extent of the features that are available in a running Guile. +@code{*features*} is a list of symbols, for example @code{threads}, each +of which describes a feature of the running Guile process. + +@defvar *features* +A list of symbols describing available features of the Guile process. +@end defvar + +You shouldn't modify the @code{*features*} variable directly using +@code{set!}. Instead, see the procedures that are provided for this +purpose in the following subsection. + +@menu +* Feature Manipulation:: Checking for and advertising features. +* Common Feature Symbols:: Commonly available features. +@end menu + + +@node Feature Manipulation +@subsection Feature Manipulation + +To check whether a particular feature is available, use the +@code{provided?} procedure: + +@deffn {Scheme Procedure} provided? feature +@deffnx {Deprecated Scheme Procedure} feature? feature +Return @code{#t} if the specified @var{feature} is available, otherwise +@code{#f}. +@end deffn + +To advertise a feature from your own Scheme code, you can use the +@code{provide} procedure: + +@deffn {Scheme Procedure} provide feature +Add @var{feature} to the list of available features in this Guile +process. +@end deffn + +For C code, the equivalent function takes its feature name as a +@code{char *} argument for convenience: + +@deftypefn {C Function} void scm_add_feature (const char *str) +Add a symbol with name @var{str} to the list of available features in +this Guile process. +@end deftypefn + + +@node Common Feature Symbols +@subsection Common Feature Symbols + +In general, a particular feature may be available for one of two +reasons. Either because the Guile library was configured and compiled +with that feature enabled --- i.e. the feature is built into the library +on your system. Or because some C or Scheme code that was dynamically +loaded by Guile has added that feature to the list. + +In the first category, here are the features that the current version of +Guile may define (depending on how it is built), and what they mean. + +@table @code +@item array +Indicates support for arrays (@pxref{Arrays}). + +@item array-for-each +Indicates availability of @code{array-for-each} and other array mapping +procedures (@pxref{Array Mapping}). + +@item char-ready? +Indicates that the @code{char-ready?} function is available +(@pxref{Reading}). + +@item complex +Indicates support for complex numbers. + +@item current-time +Indicates availability of time-related functions: @code{times}, +@code{get-internal-run-time} and so on (@pxref{Time}). + +@item debug-extensions +Indicates that the debugging evaluator is available, together with the +options for controlling it. + +@item delay +Indicates support for promises (@pxref{Delayed Evaluation}). + +@item EIDs +Indicates that the @code{geteuid} and @code{getegid} really return +effective user and group IDs (@pxref{Processes}). + +@item inexact +Indicates support for inexact numbers. + +@item i/o-extensions +Indicates availability of the following extended I/O procedures: +@code{ftell}, @code{redirect-port}, @code{dup->fdes}, @code{dup2}, +@code{fileno}, @code{isatty?}, @code{fdopen}, +@code{primitive-move->fdes} and @code{fdes->ports} (@pxref{Ports and +File Descriptors}). + +@item net-db +Indicates availability of network database functions: +@code{scm_gethost}, @code{scm_getnet}, @code{scm_getproto}, +@code{scm_getserv}, @code{scm_sethost}, @code{scm_setnet}, @code{scm_setproto}, +@code{scm_setserv}, and their `byXXX' variants (@pxref{Network +Databases}). + +@item posix +Indicates support for POSIX functions: @code{pipe}, @code{getgroups}, +@code{kill}, @code{execl} and so on (@pxref{POSIX}). + +@item random +Indicates availability of random number generation functions: +@code{random}, @code{copy-random-state}, @code{random-uniform} and so on +(@pxref{Random}). + +@item reckless +Indicates that Guile was built with important checks omitted --- you +should never see this! + +@item regex +Indicates support for POSIX regular expressions using +@code{make-regexp}, @code{regexp-exec} and friends (@pxref{Regexp +Functions}). + +@item socket +Indicates availability of socket-related functions: @code{socket}, +@code{bind}, @code{connect} and so on (@pxref{Network Sockets and +Communication}). + +@item sort +Indicates availability of sorting and merging functions +(@pxref{Sorting}). + +@item system +Indicates that the @code{system} function is available +(@pxref{Processes}). + +@item threads +Indicates support for multithreading (@pxref{Threads}). + +@item values +Indicates support for multiple return values using @code{values} and +@code{call-with-values} (@pxref{Multiple Values}). +@end table + +Available features in the second category depend, by definition, on what +additional code your Guile process has loaded in. The following table +lists features that you might encounter for this reason. + +@table @code +@item defmacro +Indicates that the @code{defmacro} macro is available (@pxref{Macros}). + +@item describe +Indicates that the @code{(oop goops describe)} module has been loaded, +which provides a procedure for describing the contents of GOOPS +instances. + +@item readline +Indicates that Guile has loaded in Readline support, for command line +editing (@pxref{Readline Support}). + +@item record +Indicates support for record definition using @code{make-record-type} +and friends (@pxref{Records}). +@end table + +Although these tables may seem exhaustive, it is probably unwise in +practice to rely on them, as the correspondences between feature symbols +and available procedures/behaviour are not strictly defined. If you are +writing code that needs to check for the existence of some procedure, it +is probably safer to do so directly using the @code{defined?} procedure +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 @@ -15,43 +335,52 @@ configure @emph{reading}, @emph{printing}, @emph{debugging} or @emph{evaluating}. @menu -* General option interface:: +* Low level options interfaces:: +* User level options interfaces:: * Reader options:: * Printing options:: * Debugger options:: * Evaluator options:: * Evaluator trap options:: * Examples of option use:: -* Install Config:: Installation and configuration data. -* Feature Tracking:: Available features in the Guile process. @end menu -@node General option interface -@section General option interface -We will use the expression @code{<group>} to represent @code{read}, -@code{print}, @code{debug} or @code{evaluator}. - -@subheading Low level - -@c NJFIXME -@deffn {Scheme Procedure} <group>-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. +@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 -@subheading User level +@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 @@ -115,7 +444,7 @@ These functions set a non-boolean @var{option-symbol} to the specified @node Reader options -@section Reader options +@subsection Reader options @cindex options - read @cindex read options @@ -141,7 +470,7 @@ To make Guile case insensitive, you can type @end smalllisp @node Printing options -@section 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 @@ -154,7 +483,7 @@ closure-hook #f Hook for printing closures. @node Evaluator options -@section 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. @@ -163,8 +492,9 @@ printed by typing @code{(eval-options 'full)} in Guile. stack 22000 Size of thread stacks (in machine words). @end smallexample + @node Evaluator trap options -@section 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.] @@ -230,7 +560,7 @@ debug object, otherwise it is a restartable continuation. @end deffn @node Debugger options -@section 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 @@ -251,7 +581,7 @@ breakpoints no *Check for breakpoints. cheap yes *Flyweight representation of the stack at traps. @end smallexample -@subsection Stack overflow +@subsubsection Stack overflow @cindex overflow, stack @cindex stack overflow @@ -287,7 +617,7 @@ recursion,,,r5rs,The Revised^5 Report on Scheme}. @node Examples of option use -@section 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 @@ -360,292 +690,6 @@ 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. - -@deffn {Scheme Procedure} version -@deffnx {Scheme Procedure} major-version -@deffnx {Scheme Procedure} minor-version -@deffnx {Scheme Procedure} micro-version -@deffnx {C Function} scm_version () -@deffnx {C Function} scm_major_version () -@deffnx {C Function} scm_minor_version () -@deffnx {C Function} scm_micro_version () -Return a string describing Guile's version number, or its major, minor -or micro version number, respectively. - -@lisp -(version) @result{} "1.6.0" -(major-version) @result{} "1" -(minor-version) @result{} "6" -(micro-version) @result{} "0" -@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}. -@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". -@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". -@end deffn - -@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 -string, into a list and return the resulting list with -@var{tail} appended. If @var{path} is @code{#f}, @var{tail} -is returned. -@end deffn - -@deffn {Scheme Procedure} search-path path filename [extensions] -@deffnx {C Function} scm_search_path (path, filename, extensions) -Search @var{path} for a directory containing a file named -@var{filename}. The file must be readable, and not a directory. -If we find one, return its full filename; otherwise, return -@code{#f}. If @var{filename} is absolute, return it unchanged. -If given, @var{extensions} is a list of strings; for each -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. - -Briefly, here are the keys in @code{%guile-build-info}, by group: -@itemize @bullet -@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 -LIBS -@item versioning info -guileversion, libguileinterface, buildstamp -@end itemize - -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 -before a build guarantees up-to-date values for that build. -@end defvar - - -@node Feature Tracking -@section Feature Tracking - -Guile has a Scheme level variable @code{*features*} that keeps track to -some extent of the features that are available in a running Guile. -@code{*features*} is a list of symbols, for example @code{threads}, each -of which describes a feature of the running Guile process. - -@defvar *features* -A list of symbols describing available features of the Guile process. -@end defvar - -You shouldn't modify the @code{*features*} variable directly using -@code{set!}. Instead, see the procedures that are provided for this -purpose in the following subsection. - -@menu -* Feature Manipulation:: Checking for and advertising features. -* Common Feature Symbols:: Commonly available features. -@end menu - - -@node Feature Manipulation -@subsection Feature Manipulation - -To check whether a particular feature is available, use the -@code{provided?} procedure: - -@deffn {Scheme Procedure} provided? feature -@deffnx {Deprecated Scheme Procedure} feature? feature -Return @code{#t} if the specified @var{feature} is available, otherwise -@code{#f}. -@end deffn - -To advertise a feature from your own Scheme code, you can use the -@code{provide} procedure: - -@deffn {Scheme Procedure} provide feature -Add @var{feature} to the list of available features in this Guile -process. -@end deffn - -For C code, the equivalent function takes its feature name as a -@code{char *} argument for convenience: - -@deftypefn {C Function} void scm_add_feature (const char *str) -Add a symbol with name @var{str} to the list of available features in -this Guile process. -@end deftypefn - - -@node Common Feature Symbols -@subsection Common Feature Symbols - -In general, a particular feature may be available for one of two -reasons. Either because the Guile library was configured and compiled -with that feature enabled --- i.e. the feature is built into the library -on your system. Or because some C or Scheme code that was dynamically -loaded by Guile has added that feature to the list. - -In the first category, here are the features that the current version of -Guile may define (depending on how it is built), and what they mean. - -@table @code -@item array -Indicates support for arrays (@pxref{Arrays}). - -@item array-for-each -Indicates availability of @code{array-for-each} and other array mapping -procedures (@pxref{Array Mapping}). - -@item char-ready? -Indicates that the @code{char-ready?} function is available -(@pxref{Reading}). - -@item complex -Indicates support for complex numbers. - -@item current-time -Indicates availability of time-related functions: @code{times}, -@code{get-internal-run-time} and so on (@pxref{Time}). - -@item debug-extensions -Indicates that the debugging evaluator is available, together with the -options for controlling it. - -@item delay -Indicates support for promises (@pxref{Delayed Evaluation}). - -@item EIDs -Indicates that the @code{geteuid} and @code{getegid} really return -effective user and group IDs (@pxref{Processes}). - -@item inexact -Indicates support for inexact numbers. - -@item i/o-extensions -Indicates availability of the following extended I/O procedures: -@code{ftell}, @code{redirect-port}, @code{dup->fdes}, @code{dup2}, -@code{fileno}, @code{isatty?}, @code{fdopen}, -@code{primitive-move->fdes} and @code{fdes->ports} (@pxref{Ports and -File Descriptors}). - -@item net-db -Indicates availability of network database functions: -@code{scm_gethost}, @code{scm_getnet}, @code{scm_getproto}, -@code{scm_getserv}, @code{scm_sethost}, @code{scm_setnet}, @code{scm_setproto}, -@code{scm_setserv}, and their `byXXX' variants (@pxref{Network -Databases}). - -@item posix -Indicates support for POSIX functions: @code{pipe}, @code{getgroups}, -@code{kill}, @code{execl} and so on (@pxref{POSIX}). - -@item random -Indicates availability of random number generation functions: -@code{random}, @code{copy-random-state}, @code{random-uniform} and so on -(@pxref{Random}). - -@item reckless -Indicates that Guile was built with important checks omitted --- you -should never see this! - -@item regex -Indicates support for POSIX regular expressions using -@code{make-regexp}, @code{regexp-exec} and friends (@pxref{Regexp -Functions}). - -@item socket -Indicates availability of socket-related functions: @code{socket}, -@code{bind}, @code{connect} and so on (@pxref{Network Sockets and -Communication}). - -@item sort -Indicates availability of sorting and merging functions -(@pxref{Sorting}). - -@item system -Indicates that the @code{system} function is available -(@pxref{Processes}). - -@item threads -Indicates support for multithreading (@pxref{Threads}). - -@item values -Indicates support for multiple return values using @code{values} and -@code{call-with-values} (@pxref{Multiple Values}). -@end table - -Available features in the second category depend, by definition, on what -additional code your Guile process has loaded in. The following table -lists features that you might encounter for this reason. - -@table @code -@item defmacro -Indicates that the @code{defmacro} macro is available (@pxref{Macros}). - -@item describe -Indicates that the @code{(oop goops describe)} module has been loaded, -which provides a procedure for describing the contents of GOOPS -instances. - -@item readline -Indicates that Guile has loaded in Readline support, for command line -editing (@pxref{Readline Support}). - -@item record -Indicates support for record definition using @code{make-record-type} -and friends (@pxref{Records}). -@end table - -Although these tables may seem exhaustive, it is probably unwise in -practice to rely on them, as the correspondences between feature symbols -and available procedures/behaviour are not strictly defined. If you are -writing code that needs to check for the existence of some procedure, it -is probably safer to do so directly using the @code{defined?} procedure -than to test for the corresponding feature using @code{feature?}. - - @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)) |