From fc8529c7668ad32dc83048e77b8bd7ed0af81b8e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Martin=20Grabm=C3=BCller?= Date: Wed, 2 May 2001 21:50:15 +0000 Subject: [PATCH] * srfi-13-14.texi: Added @bullet to various @itemize lists. * srfi-modules.texi (SRFI Support): New file and chapter. * Makefile.am (guile_TEXINFOS): Added repl-modules.texi and srfi-modules.texi. * guile.texi (Top): New menu entries for the new chapters. (Top): @includes for the new chapters. (Top): New menu entry for `SRFI Support', @include for `srfi-modules.texi'. * repl-modules.texi: New file. (Readline Support): New chapter for (ice-9 readline). (Value History): New chapter for (ice-9 history). --- doc/ChangeLog | 18 + doc/Makefile.am | 3 +- doc/guile.texi | 7 +- doc/repl-modules.texi | 79 +++ doc/srfi-13-14.texi | 1093 ----------------------------------------- doc/srfi-modules.texi | 183 +++++++ 6 files changed, 288 insertions(+), 1095 deletions(-) create mode 100644 doc/repl-modules.texi create mode 100644 doc/srfi-modules.texi diff --git a/doc/ChangeLog b/doc/ChangeLog index b136680b9..d097ace4a 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,21 @@ +2001-05-02 Martin Grabmueller + + * srfi-13-14.texi: Added @bullet to various @itemize lists. + + * srfi-modules.texi (SRFI Support): New file and chapter. + + * Makefile.am (guile_TEXINFOS): Added repl-modules.texi and + srfi-modules.texi. + + * guile.texi (Top): New menu entries for the new chapters. + (Top): @includes for the new chapters. + (Top): New menu entry for `SRFI Support', @include for + `srfi-modules.texi'. + + * repl-modules.texi: New file. + (Readline Support): New chapter for (ice-9 readline). + (Value History): New chapter for (ice-9 history). + 2001-05-02 Martin Grabmueller * scheme-modules.texi (Dynamic Libraries): Renamed from `Dynamic diff --git a/doc/Makefile.am b/doc/Makefile.am index 9975477f7..c51cf392f 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -35,7 +35,8 @@ guile_TEXINFOS = preface.texi intro.texi scheme-intro.texi \ scheme-reading.texi scheme-indices.texi slib.texi posix.texi \ expect.texi scsh.texi tcltk.texi scripts.texi gh.texi scm.texi \ appendices.texi indices.texi script-getopt.texi data-rep.texi \ - extend.texi srfi-13-14.texi AUTHORS + extend.texi srfi-13-14.texi repl-modules.texi srfi-modules.texi \ + AUTHORS guile_tut_TEXINFOS = guile-tut.texi AUTHORS diff --git a/doc/guile.texi b/doc/guile.texi index a163dfaad..6c8c57338 100644 --- a/doc/guile.texi +++ b/doc/guile.texi @@ -80,7 +80,7 @@ by the Free Software Foundation. @sp 10 @comment The title is printed in a large font. @title Guile Reference Manual -@subtitle $Id: guile.texi,v 1.7 2001-04-28 23:38:52 ossau Exp $ +@subtitle $Id: guile.texi,v 1.8 2001-05-02 21:50:15 mgrabmue Exp $ @subtitle For use with Guile @value{VERSION} @include AUTHORS @@ -168,7 +168,10 @@ Part III: Guile Modules * SLIB:: Using the SLIB Scheme library. * POSIX:: POSIX system calls and networking. +* SRFI Support:: Support for various SRFIs. * SRFI-13/14:: String library and character set library. +* Readline Support:: Module for using the readline library. +* Value History:: Maintaining a value history in the REPL. * Expect:: Controlling interactive programs with Guile. * The Scheme shell (scsh):: The SCSH compatibility module has been made an @@ -249,7 +252,9 @@ Indices @include slib.texi @include posix.texi +@include srfi-modules.texi @include srfi-13-14.texi +@include repl-modules.texi @include expect.texi @include scsh.texi @include tcltk.texi diff --git a/doc/repl-modules.texi b/doc/repl-modules.texi new file mode 100644 index 000000000..3bf68ffc8 --- /dev/null +++ b/doc/repl-modules.texi @@ -0,0 +1,79 @@ +@node Readline Support +@chapter Readline Support + +@c FIXME::martin: Review me! + +@cindex readline +@cindex command line history +Guile comes with an interface module to the readline library. This +makes interactive use much more convenient, because of the command--line +editing features of readline. Using @code{(ice-9 readline)}, you can +navigate through the current input line with the cursor keys, retrieve +older command lines from the input history and even search through the +history entries. + +The module is not loaded by default and so has to be loaded and +activated explicitly. This is done with two simple lines of code: + +@lisp +(use-modules (ice-9 readline)) +(activate-readline) +@end lisp + +The first line will load the necessary code, and the second will +activate readline's features for the REPL. If you plan to use this +module often, you should save these to lines to your @file{.guile} +personal startup file. + +You will notice that the REPL's behaviour changes a bit when you have +loaded the readline module. For examle, when you press Enter before +typing in the closing parentheses of a list, you will see the +@dfn{continuation} prompt, three dots: @code{...} This gives you a nice +visual feedback when trying to match parentheses. To make this even +easier, @dfn{bouncing parentheses} are implemented. That means that +when you type in a closing parentheses, the cursor will jump to the +corresponding opening paren for a short time, making it trivial to make +them match. + +Once the readline module is activated, all lines entered interactively +will be stored in a history and can be recalled later using the +cursor-up and -down keys. Readline also understands the Emacs keys for +navigating through the command line and history. + +When you quit your Guile session by evaluating @code{(quit)} or pressing +Ctrl-D, the history will be saved to the file @file{.guile_history} and +read in when you start Guile for the next time. Thus you can start a +new Guile session and still have the (probably long--winded) definition +expressions available. + + +@node Value History +@chapter Value History + +@c FIXME::martin: Review me! + +@cindex value history +Another module which makes command line usage more convenient is +@code{(ice-9 history)}. This module will change the REPL so that each +value which is evaluated and printed will be remembered under a name +constructed from the dollar character (@code{$}) and the number of the +evaluated expression. + +Consider an example session. + +@example +guile> (use-modules (ice-9 history)) +guile> 1 +$1 = 1 +guile> (+ $1 $1) +$2 = 2 +guile> (* $2 $2) +$3 = 4 +@end example + +After loading the value history module @code{(ice-9 history)}, one +(trivial) expression is evaluated. The result is stored into the +variable @code{$1}. This fact is indicated by the output @code{$1 = }, +which is also caused by @code{(ice-9 history)}. In the next line, this +variable is used two times, to produce the value @code{$2}, which in +turn is used in the calculation for @code{$3}. diff --git a/doc/srfi-13-14.texi b/doc/srfi-13-14.texi index 8d96b9618..e69de29bb 100644 --- a/doc/srfi-13-14.texi +++ b/doc/srfi-13-14.texi @@ -1,1093 +0,0 @@ -@node SRFI-13/14 -@chapter SRFI-13 and SRFI-14 - -This chapter documents the SRFI-13/14 library, which provides the string -utility procedures defined in SRFI-13 and the character-set procedures -defined in SRFI-14 for Guile. - -@menu -* Introduction:: What is this all about? -* Loading SRFI-13/14:: Loading the module into a running Guile. -* String Functions:: Available string processing procedures. -* Character-set Procedures:: Procedures for manipulating character sets. -@end menu - - -@c =================================================================== - -@node Introduction -@section Introduction - -The SRFI-13/14 library is a shared library which provides the procedures -defined in SRFI-13 (string library) and the procedures defined in -SRFI-14 (character-set library). You should also refer to the SRFI -documents, which provide some details I will not document here. - -If you don't know what SRFI means, and what all the numbers are about, -you may want to refer to the SRFI home page at -@url{http://srfi.schemers.org}. - -Note that only the procedures from SRFI-13 are documented here which are -not already contained in Guile. For procedures not documented here -please refer to the relevant chapters in the Guile Reference Manual, for -example the documentation of strings and string procedures (REFFIXME). - -The SRFI-14 procedures are documented completely. - -@menu -* What can be done:: What is possible with SRFI-13/14 -* What cannot be done:: and what is not? -@end menu - - -@c =================================================================== - -@node What can be done -@subsection What can be done - -All of the procedures defined in SRFI-13, which are not already included -in the Guile core library, are implemented in the module @code{(srfi -srfi-13)}. The procedures which are both in Guile and in SRFI-13, but -which are slightly extended, have been implemented in this module, and -the bindings overwrite those in the Guile core. - -All procedures from SRFI-14 (character-set library) are implemented in -the module @code{(srfi srfi-14)}, as well as the standard variables -@code{char-set:letter}, @code{char-set:digit} etc. - - -@c =================================================================== - -@node What cannot be done -@subsection What cannot be done - -The procedures which are defined in the section @emph{Low-level -procedures} of SRFI-13 for parsing optional string indices, substring -specification checking and Knuth-Morris-Pratt-Searching are not -implemented. - -The procedures @code{string-contains} and @code{string-contains-ci} are -not implemented very efficiently at the moment. This will be changed as -soon as possible. - - -@c =================================================================== - -@node Loading SRFI-13/14 -@section Loading SRFI-13/14 - -When Guile is properly installed, it can be loaded into a running Guile -by using the @code{(srfi srfi-13)} module. - -@example -$ guile -guile> (use-modules (srfi srfi-13)) -guile> -@end example - -When this step causes any errors, Guile is not properly installed. - -One possible reason is that Guile cannot find either the Scheme module -file @file{srfi-13.scm}, or it cannot find the shared object file -@file{libguile-srfi-srfi-13-14.so}. Make sure that the former is in the -Guile load path and that the latter is either installed in some default -location like @file{/usr/local/lib} or that the directory it was -installed to is in your @code{LTDL_LIBRARY_PATH}. The same applies to -@file{srfi-14.scm}. - -Now you can test whether the SRFI-13 procedures are working by calling -the @code{string-concatenate} procedure. - -@example -guile> (string-concatenate '("Hello" " " "World!")) -"Hello World!" -@end example - -The same goes for the SRFI-14 module, of course. - -@example -$ guile -guile> (use-modules (srfi srfi-14)) -guile> (char-set-union (char-set #\f #\o #\o) (string->char-set "bar")) -# -guile> -@end example - - -@c =================================================================== - -@node String Functions -@section String Functions - -In this section, we will describe all procedures defined in SRFI-13 -(string library) and implemented by the module @code{(srfi srfi-13)}. - -Except for the procedures in the section @emph{Low-level procedures} of -SRFI-13, all string procedures defined there are implemented completely. - -@menu -* Predicates:: Testing strings. -* SRFI-13 Constructors:: Constructing strings. -* SRFI-13 List/String Conversion:: Converstion from/to character lists. -* SRFI-13 Selection:: Selecting portions from strings. -* SRFI-13 Modification:: Modifying string in--place. -* SRFI-13 Comparison:: Comparing strings. -* Prefixes/Suffixes:: Checking for common pre-/suffixes. -* Searching:: Searching in strings. -* Case Mapping:: Changing the case of strings. -* Reverse/Append:: Append, concatenate and reverse strings. -* Fold/Unfold/Map:: Fold/Unfold/Map over strings. -* Replicate/Rotate:: String replication and rotation. -* Miscellaneous:: Miscellaneous string procedures. -* Filtering/Deleting:: Deleting characters from strings. -@end menu - - -@c =================================================================== - -@node Predicates -@subsection Predicates - -In addition to the primitives @code{string?} and @code{string-null?}, -which are already in the Guile core, the string predicates -@code{string-any} and @code{string-every} are defined by SRFI-13. - -@deffn primitive string-any pred s [start end] -Check if the predicate @var{pred} is true for any character in -the string @var{s}, proceeding from left (index @var{start}) to -right (index @var{end}). If @code{string-any} returns true, -the returned true value is the one produced by the first -successful application of @var{pred}. -@end deffn - -@deffn primitive string-every pred s [start end] -Check if the predicate @var{pred} is true for every character -in the string @var{s}, proceeding from left (index @var{start}) -to right (index @var{end}). If @code{string-every} returns -true, the returned true value is the one produced by the final -application of @var{pred} to the last character of @var{s}. -@end deffn - - -@c =================================================================== - -@node SRFI-13 Constructors -@subsection Constructors - -SRFI-13 defines several procedures for constructing new strings. In -addition to @code{make-string} and @code{string} (available in the Guile -core library), the procedure @code{string-tabulate} does exist. - -@deffn primitive string-tabulate proc len -@var{proc} is an integer->char procedure. Construct a string -of size @var{len} by applying @var{proc} to each index to -produce the corresponding string element. The order in which -@var{proc} is applied to the indices is not specified. -@end deffn - - -@c =================================================================== - -@node SRFI-13 List/String Conversion -@subsection List/String Conversion - -The procedure @code{string->list} is extended by SRFI-13, that is why it -is included in @code{(srfi srfi-13)}. The other procedures are new. -The Guile core already contains the procedure @code{list->string} for -converting a list of characters into a string (REFFIXME). - -@deffn primitive string->list str [start end] -Convert the string @var{str} into a list of characters. -@end deffn - -@deffn primitive reverse-list->string chrs -An efficient implementation of @code{(compose string->list -reverse)}: - -@smalllisp -(reverse-list->string '(#\a #\B #\c)) @result{} "cBa" -@end smalllisp -@end deffn - -@deffn primitive string-join ls [delimiter grammar] -Append the string in the string list @var{ls}, using the string -@var{delim} as a delimiter between the elements of @var{ls}. -@var{grammar} is a symbol which specifies how the delimiter is -placed between the strings, and defaults to the symbol -@code{infix}. - -@table @code -@item infix -Insert the separator between list elements. An empty string -will produce an empty list. - -@item string-infix -Like @code{infix}, but will raise an error if given the empty -list. - -@item suffix -Insert the separator after every list element. - -@item prefix -Insert the separator before each list element. -@end table -@end deffn - - -@c =================================================================== - -@node SRFI-13 Selection -@subsection Selection - -These procedures are called @dfn{selectors}, because they access -information about the string or select pieces of a given string. - -Additional selector procedures are documented in the Strings section -(REFFIXME), like @code{string-length} or @code{string-ref}. - -@code{string-copy} is also available in core Guile, but this version -accepts additional start/end indices. - -@deffn primitive string-copy str [start end] -Return a freshly allocated copy of the string @var{str}. If -given, @var{start} and @var{end} delimit the portion of -@var{str} which is copied. -@end deffn - -@deffn primitive substring/shared str start [end] -Like @code{substring}, but the result may share memory with the -argument @var{str}. -@end deffn - -@deffn primitive string-copy! target tstart s [start end] -Copy the sequence of characters from index range [@var{start}, -@var{end}) in string @var{s} to string @var{target}, beginning -at index @var{tstart}. The characters are copied left-to-right -or right-to-left as needed -- the copy is guaranteed to work, -even if @var{target} and @var{s} are the same string. It is an -error if the copy operation runs off the end of the target -string. -@end deffn - -@deffn primitive string-take s n -@deffnx primitive string-take-right s n -Return the @var{n} first/last characters of @var{s}. -@end deffn - -@deffn primitive string-drop s n -@deffnx primitive string-drop-right s n -Return all but the first/last @var{n} characters of @var{s}. -@end deffn - -@deffn primitive string-pad s len [chr start end] -@deffnx primitive string-pad-right s len [chr start end] -Take that characters from @var{start} to @var{end} from the -string @var{s} and return a new string, right(left)-padded by the -character @var{chr} to length @var{len}. If the resulting -string is longer than @var{len}, it is truncated on the right (left). -@end deffn - -@deffn primitive string-trim s [char_pred start end] -@deffnx primitive string-trim-right s [char_pred start end] -@deffnx primitive string-trim-both s [char_pred start end] -Trim @var{s} by skipping over all characters on the left/right/both -sides of the string that satisfy the parameter @var{char_pred}: - -@itemize @bullet -@item -if it is the character @var{ch}, characters equal to -@var{ch} are trimmed, - -@item -if it is a procedure @var{pred} characters that -satisfy @var{pred} are trimmed, - -@item -if it is a character set, characters in that set are trimmed. -@end itemize - -If called without a @var{char_pred} argument, all whitespace is -trimmed. -@end deffn - - -@c =================================================================== - -@node SRFI-13 Modification -@subsection Modification - -The procedure @code{string-fill!} is extended from R5RS because it -accepts optional start/end indices. This bindings shadows the procedure -of the same name in the Guile core. The second modification procedure -@code{string-set!} is documented in the Strings section (REFFIXME). - -@deffn primitive string-fill! str chr [start end] -Stores @var{chr} in every element of the given @var{str} and -returns an unspecified value. -@end deffn - - -@c =================================================================== - -@node SRFI-13 Comparison -@subsection Comparison - -The procedures in this section are used for comparing strings in -different ways. The comparison predicates differ from those in R5RS in -that they do not only return @code{#t} or @code{#f}, but the mismatch -index in the case of a true return value. - -@code{string-hash} and @code{string-hash-ci} are for calculating hash -values for strings, useful for implementing fast lookup mechanisms. - -@deffn primitive string-compare s1 s2 proc_lt proc_eq proc_gt [start1 end1 start2 end2] -@deffnx primitive string-compare-ci s1 s2 proc_lt proc_eq proc_gt [start1 end1 start2 end2] -Apply @var{proc_lt}, @var{proc_eq}, @var{proc_gt} to the -mismatch index, depending upon whether @var{s1} is less than, -equal to, or greater than @var{s2}. The mismatch index is the -largest index @var{i} such that for every 0 <= @var{j} < -@var{i}, @var{s1}[@var{j}] = @var{s2}[@var{j}] -- that is, -@var{i} is the first position that does not match. The -character comparison is done case-insensitively. -@end deffn - -@deffn primitive string= s1 s2 [start1 end1 start2 end2] -@deffnx primitive string<> s1 s2 [start1 end1 start2 end2] -@deffnx primitive string< s1 s2 [start1 end1 start2 end2] -@deffnx primitive string> s1 s2 [start1 end1 start2 end2] -@deffnx primitive string<= s1 s2 [start1 end1 start2 end2] -@deffnx primitive string>= s1 s2 [start1 end1 start2 end2] -Compare @var{s1} and @var{s2} and return @code{#f} if the predicate -fails. Otherwise, the mismatch index is returned (or @var{end1} in the -case of @code{string=}. -@end deffn - -@deffn primitive string-ci= s1 s2 [start1 end1 start2 end2] -@deffnx primitive string-ci<> s1 s2 [start1 end1 start2 end2] -@deffnx primitive string-ci< s1 s2 [start1 end1 start2 end2] -@deffnx primitive string-ci> s1 s2 [start1 end1 start2 end2] -@deffnx primitive string-ci<= s1 s2 [start1 end1 start2 end2] -@deffnx primitive string-ci>= s1 s2 [start1 end1 start2 end2] -Compare @var{s1} and @var{s2} and return @code{#f} if the predicate -fails. Otherwise, the mismatch index is returned (or @var{end1} in the -case of @code{string=}. These are the case-insensitive variants. -@end deffn - -@deffn primitive string-hash s [bound start end] -@deffnx primitive string-hash-ci s [bound start end] -Return a hash value of the string @var{s} in the range 0 @dots{} -@var{bound} - 1. @code{string-hash-ci} is the case-insensitive variant. -@end deffn - - -@c =================================================================== - -@node Prefixes/Suffixes -@subsection Prefixes/Suffixes - -Using these procedures you can determine whether a given string is a -prefix or suffix of another string or how long a common prefix/suffix -is. - -@deffn primitive string-prefix-length s1 s2 [start1 end1 start2 end2] -@deffnx primitive string-prefix-length-ci s1 s2 [start1 end1 start2 end2] -@deffnx primitive string-suffix-length s1 s2 [start1 end1 start2 end2] -@deffnx primitive string-suffix-length-ci s1 s2 [start1 end1 start2 end2] -Return the length of the longest common prefix/suffix of the two -strings. @code{string-prefix-length-ci} and -@code{string-suffix-length-ci} are the case-insensitive variants. -@end deffn - -@deffn primitive string-prefix? s1 s2 [start1 end1 start2 end2] -@deffnx primitive string-prefix-ci? s1 s2 [start1 end1 start2 end2] -@deffnx primitive string-suffix? s1 s2 [start1 end1 start2 end2] -@deffnx primitive string-suffix-ci? s1 s2 [start1 end1 start2 end2] -Is @var{s1} a prefix/suffix of @var{s2}. @code{string-prefix-ci?} and -@code{string-suffix-ci?} are the case-insensitive variants. -@end deffn - - -@c =================================================================== - -@node Searching -@subsection Searching - -Use these procedures to find out whether a string contains a given -character or a given substring, or a character from a set of characters. - -@deffn primitive string-index s char_pred [start end] -@deffnx primitive string-index-right s char_pred [start end] -Search through the string @var{s} from left to right (right to left), -returning the index of the first (last) occurence of a character which - -@itemize -@item -equals @var{char_pred}, if it is character, - -@item -satisifies the predicate @var{char_pred}, if it is a -procedure, - -@item -is in the set @var{char_pred}, if it is a character set. -@end itemize -@end deffn - -@deffn primitive string-skip s char_pred [start end] -@deffnx primitive string-skip-right s char_pred [start end] -Search through the string @var{s} from left to right (right to left), -returning the index of the first (last) occurence of a character which - -@itemize -@item -does not equal @var{char_pred}, if it is character, - -@item -does not satisify the predicate @var{char_pred}, if it is -a procedure. - -@item -is not in the set if @var{char_pred} is a character set. -@end itemize -@end deffn - -@deffn primitive string-count s char_pred [start end] -Return the count of the number of characters in the string -@var{s} which - -@itemize @bullet -@item -equals @var{char_pred}, if it is character, - -@item -satisifies the predicate @var{char_pred}, if it is a procedure. - -@item -is in the set @var{char_pred}, if it is a character set. -@end itemize -@end deffn - -@deffn primitive string-contains s1 s2 [start1 end1 start2 end2] -@deffnx primitive string-contains-ci s1 s2 [start1 end1 start2 end2] -Does string @var{s1} contain string @var{s2}? Return the index -in @var{s1} where @var{s2} occurs as a substring, or false. -The optional start/end indices restrict the operation to the -indicated substrings. - -@code{string-contains-ci} is the case-insensitive variant. -@end deffn - - -@c =================================================================== - -@node Case Mapping -@subsection Alphabetic Case Mapping - -These procedures convert the alphabetic case of strings. They are -similar to the procedures in the Guile core, but are extended to handle -optional start/end indices. - -@deffn primitive string-upcase s [start end] -@deffnx primitive string-upcase! s [start end] -Upcase every character in @var{s}. @code{string-upcase!} is the -side-effecting variant. -@end deffn - -@deffn primitive string-downcase s [start end] -@deffnx primitive string-downcase! s [start end] -Downcase every character in @var{s}. @code{string-downcase!} is the -side--effecting variant. -@end deffn - -@deffn primitive string-titlecase s [start end] -@deffnx primitive string-titlecase! s [start end] -Upcase every first character in every word in @var{s}, downcase the -other characters. @code{string-titlecase!} is the side--effecting -variant. -@end deffn - - -@c =================================================================== - -@node Reverse/Append -@subsection Reverse/Append - -One appending procedure, @code{string-append} is the same in R5RS and in -SRFI-13, so it is not redefined. - -@deffn primitive string-reverse str [start end] -@deffnx primitive string-reverse! str [start end] -Reverse the string @var{str}. The optional arguments -@var{start} and @var{end} delimit the region of @var{str} to -operate on. - -@code{string-reverse!} modifies the argument string and returns an -unspecified value. -@end deffn - -@deffn primitive string-append/shared ls @dots{} -Like @code{string-append}, but the result may share memory -with the argument strings. -@end deffn - -@deffn primitive string-concatenate ls -Append the elements of @var{ls} (which must be strings) -together into a single string. Guaranteed to return a freshly -allocated string. -@end deffn - -@deffn primitive string-concatenate/shared ls -Like @code{string-concatenate}, but the result may share memory -with the strings in the list @var{ls}. -@end deffn - -@deffn primitive string-concatenate-reverse ls final_string end -Without optional arguments, this procedure is equivalent to - -@smalllisp -(string-concatenate (reverse ls)) -@end smalllisp - -If the optional argument @var{final_string} is specified, it is -consed onto the beginning to @var{ls} before performing the -list-reverse and string-concatenate operations. If @var{end} -is given, only the characters of @var{final_string} up to index -@var{end} are used. - -Guaranteed to return a freshly allocated string. -@end deffn - -@deffn primitive string-concatenate-reverse/shared ls final_string end -Like @code{string-concatenate-reverse}, but the result may -share memory with the the strings in the @var{ls} arguments. -@end deffn - - -@c =================================================================== - -@node Fold/Unfold/Map -@subsection Fold/Unfold/Map - -@code{string-map}, @code{string-for-each} etc. are for iterating over -the characters a string is composed of. The fold and unfold procedures -are list iterators and constructors. - -@deffn primitive string-map proc s [start end] -@var{proc} is a char->char procedure, it is mapped over -@var{s}. The order in which the procedure is applied to the -string elements is not specified. -@end deffn - -@deffn primitive string-map! proc s [start end] -@var{proc} is a char->char procedure, it is mapped over -@var{s}. The order in which the procedure is applied to the -string elements is not specified. The string @var{s} is -modified in-place, the return value is not specified. -@end deffn - -@deffn primitive string-fold kons knil s [start end] -@deffnx primitive string-fold-right kons knil s [start end] -Fold @var{kons} over the characters of @var{s}, with @var{knil} as the -terminating element, from left to right (or right to left, for -@code{string-fold-right}). @var{kons} must expect two arguments: The -actual character and the last result of @var{kons}' application. -@end deffn - -@deffn primitive string-unfold p f g seed [base make_final] -@deffnx primitive string-unfold-right p f g seed [base make_final] -These are the fundamental string constructors. -@itemize -@item @var{g} is used to generate a series of @emph{seed} -values from the initial @var{seed}: @var{seed}, (@var{g} -@var{seed}), (@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}), -@dots{} -@item @var{p} tells us when to stop -- when it returns true -when applied to one of these seed values. -@item @var{f} maps each seed value to the corresponding -character in the result string. These chars are assembled into the -string in a left-to-right (right-to-left) order. -@item @var{base} is the optional initial/leftmost (rightmost) - portion of the constructed string; it default to the empty string. -@item @var{make_final} is applied to the terminal seed -value (on which @var{p} returns true) to produce the final/rightmost -(leftmost) portion of the constructed string. It defaults to -@code{(lambda (x) "")}. -@end itemize -@end deffn - -@deffn primitive string-for-each proc s [start end] -@var{proc} is mapped over @var{s} in left-to-right order. The -return value is not specified. -@end deffn - - -@c =================================================================== - -@node Replicate/Rotate -@subsection Replicate/Rotate - -These procedures are special substring procedures, which can also be -used for replicating strings. They are a bit tricky to use, but -consider this code fragment, which replicates the input string -@code{"foo"} so often that the resulting string has a length of six. - -@lisp -(xsubstring "foo" 0 6) -@result{} -"foofoo" -@end lisp - -@deffn primitive xsubstring s from [to start end] -This is the @emph{extended substring} procedure that implements -replicated copying of a substring of some string. - -@var{s} is a string, @var{start} and @var{end} are optional -arguments that demarcate a substring of @var{s}, defaulting to -0 and the length of @var{s}. Replicate this substring up and -down index space, in both the positive and negative directions. -@code{xsubstring} returns the substring of this string -beginning at index @var{from}, and ending at @var{to}, which -defaults to @var{from} + (@var{end} - @var{start}). -@end deffn - -@deffn primitive string-xcopy! target tstart s sfrom [sto start end] -Exactly the same as @code{xsubstring}, but the extracted text -is written into the string @var{target} starting at index -@var{tstart}. The operation is not defined if @code{(eq? -@var{target} @var{s})} or these arguments share storage -- you -cannot copy a string on top of itself. -@end deffn - - -@c =================================================================== - -@node Miscellaneous -@subsection Miscellaneous - -@code{string-replace} is for replacing a portion of a string with -another string and @code{string-tokenize} splits a string into a list of -strings, breaking it up at a specified character. - -@deffn primitive string-replace s1 s2 [start1 end1 start2 end2] -Return the string @var{s1}, but with the characters -@var{start1} @dots{} @var{end1} replaced by the characters -@var{start2} @dots{} @var{end2} from @var{s2}. -@end deffn - -@deffn primitive string-tokenize s [token_char start end] -Split the string @var{s} into a list of substrings, where each -substring is a maximal non-empty contiguous sequence of -characters equal to the character @var{token_char}, or -whitespace, if @var{token_char} is not given. If -@var{token_char} is a character set, it is used for finding the -token borders. -@end deffn - - -@c =================================================================== - -@node Filtering/Deleting -@subsection Filtering/Deleting - -@dfn{Filtering} means to remove all characters from a string which do -not match a given criteria, @dfn{deleting} means the opposite. - -@deffn primitive string-filter s char_pred [start end] -Filter the string @var{s}, retaining only those characters that -satisfy the @var{char_pred} argument. If the argument is a -procedure, it is applied to each character as a predicate, if -it is a character, it is tested for equality and if it is a -character set, it is tested for membership. -@end deffn - -@deffn primitive string-delete s char_pred [start end] -Filter the string @var{s}, retaining only those characters that -do not satisfy the @var{char_pred} argument. If the argument -is a procedure, it is applied to each character as a predicate, -if it is a character, it is tested for equality and if it is a -character set, it is tested for membership. -@end deffn - - -@c =================================================================== - -@node Character-set Procedures -@section Character-set Procedures - -SRFI-14 defines the data type @dfn{character set}, and also defines a -lot of procedures for handling this character type, and a few standard -character sets like whitespace, alphabetic characters and others. - -@menu -* Character Set Data Type:: Description of the character set data type. -* Predicates/Comparison:: Testing character sets. -* Iterating Over Character Sets:: Iterating over the members of a set. -* Creating Character Sets:: Creating new character sets. -* Querying Character Sets:: Extracting information from character sets. -* Character-Set Algebra:: Set-algebra on character sets. -* Standard Character Sets:: Variables containg standard character sets. -@end menu - - -@c =================================================================== - -@node Character Set Data Type -@subsection Character Set Data Type - -The data type @dfn{charset} implements sets of characters (REFFIXME). -Because the internal representation of character sets is not visible to -the user, a lot of procedures for handling them are provided. - -Character sets can be created, extended, tested for the membership of a -characters and be compared to other character sets. - -The Guile implementation of character sets deals with 8-bit characters. -In the standard variables, only the ASCII part of the character range is -really used, so that for example @dfn{Umlaute} and other accented -characters are not considered to be letters. In the future, as Guile -may get support for international character sets, this will change, so -don't rely on these ``features''. - - -@c =================================================================== - -@node Predicates/Comparison -@subsection Predicates/Comparison - -Use these procedures for testing whether an object is a character set, -or whether several character sets are equal or subsets of each other. -@code{char-set-hash} can be used for calculating a hash value, maybe for -usage in fast lookup procedures. - -@deffn primitive char-set? obj -Return @code{#t} if @var{obj} is a character set, @code{#f} -otherwise. -@end deffn - -@deffn primitive char-set= cs1 @dots{} -Return @code{#t} if all given character sets are equal. -@end deffn - -@deffn primitive char-set<= cs1 @dots{} -Return @code{#t} if every character set @var{cs}i is a subset -of character set @var{cs}i+1. -@end deffn - -@deffn primitive char-set-hash cs [bound] -Compute a hash value for the character set @var{cs}. If -@var{bound} is given and not @code{#f}, it restricts the -returned value to the range 0 @dots{} @var{bound - 1}. -@end deffn - - -@c =================================================================== - -@node Iterating Over Character Sets -@subsection Iterating Over Character Sets - -Character set cursors are a means for iterating over the members of a -character sets. After creating a character set cursor with -@code{char-set-cursor}, a cursor can be dereferenced with -@code{char-set-ref}, advanced to the next member with -@code{char-set-cursor-next}. Whether a cursor has passed past the last -element of the set can be checked with @code{end-of-char-set?}. - -Additionally, mapping and (un-)folding procedures for character sets are -provided. - -@deffn primitive char-set-cursor cs -Return a cursor into the character set @var{cs}. -@end deffn - -@deffn primitive char-set-ref cs cursor -Return the character at the current cursor position -@var{cursor} in the character set @var{cs}. It is an error to -pass a cursor for which @code{end-of-char-set?} returns true. -@end deffn - -@deffn primitive char-set-cursor-next cs cursor -Advance the character set cursor @var{cursor} to the next -character in the character set @var{cs}. It is an error if the -cursor given satisfies @code{end-of-char-set?}. -@end deffn - -@deffn primitive end-of-char-set? cursor -Return @code{#t} if @var{cursor} has reached the end of a -character set, @code{#f} otherwise. -@end deffn - -@deffn primitive char-set-fold kons knil cs -Fold the procedure @var{kons} over the character set @var{cs}, -initializing it with @var{knil}. -@end deffn - -@deffn primitive char-set-unfold p f g seed [base_cs] -@deffnx primitive char-set-unfold! p f g seed base_cs -This is a fundamental constructor for character sets. -@itemize -@item @var{g} is used to generate a series of ``seed'' values -from the initial seed: @var{seed}, (@var{g} @var{seed}), -(@var{g}^2 @var{seed}), (@var{g}^3 @var{seed}), @dots{} -@item @var{p} tells us when to stop -- when it returns true -when applied to one of the seed values. -@item @var{f} maps each seed value to a character. These -characters are added to the base character set @var{base_cs} to -form the result; @var{base_cs} defaults to the empty set. -@end itemize - -@code{char-set-unfold!} is the side-effecting variant. -@end deffn - -@deffn primitive char-set-for-each proc cs -Apply @var{proc} to every character in the character set -@var{cs}. The return value is not specified. -@end deffn - -@deffn primitive char-set-map proc cs -Map the procedure @var{proc} over every character in @var{cs}. -@var{proc} must be a character -> character procedure. -@end deffn - - -@c =================================================================== - -@node Creating Character Sets -@subsection Creating Character Sets - -New character sets are produced with these procedures. - -@deffn primitive char-set-copy cs -Return a newly allocated character set containing all -characters in @var{cs}. -@end deffn - -@deffn primitive char-set char1 @dots{} -Return a character set containing all given characters. -@end deffn - -@deffn primitive list->char-set char_list [base_cs] -@deffnx primitive list->char-set! char_list base_cs -Convert the character list @var{list} to a character set. If -the character set @var{base_cs} is given, the character in this -set are also included in the result. - -@code{list->char-set!} is the side-effecting variant. -@end deffn - -@deffn primitive string->char-set s [base_cs] -@deffnx primitive string->char-set! s base_cs -Convert the string @var{str} to a character set. If the -character set @var{base_cs} is given, the characters in this -set are also included in the result. - -@code{string->char-set!} is the side-effecting variant. -@end deffn - -@deffn primitive char-set-filter pred cs [base_cs] -@deffnx primitive char-set-filter! pred cs base_cs -Return a character set containing every character from @var{cs} -so that it satisfies @var{pred}. If provided, the characters -from @var{base_cs} are added to the result. - -@code{char-set-filter!} is the side-effecting variant. -@end deffn - -@deffn primitive ucs-range->char-set lower upper [error? base_cs] -@deffnx primitive uce-range->char-set! lower upper error? base_cs -Return a character set containing all characters whose -character codes lie in the half-open range -[@var{lower},@var{upper}). - -If @var{error} is a true value, an error is signalled if the -specified range contains characters which are not contained in -the implemented character range. If @var{error} is @code{#f}, -these characters are silently left out of the resultung -character set. - -The characters in @var{base_cs} are added to the result, if -given. - -@code{ucs-range->char-set!} is the side-effecting variant. -@end deffn - -@deffn procedure ->char-set x -Coerce @var{x} into a character set. @var{x} may be a string, a -character or a character set. -@end deffn - - -@c =================================================================== - -@node Querying Character Sets -@subsection Querying Character Sets - -Access the elements and other information of a character set with these -procedures. - -@deffn primitive char-set-size cs -Return the number of elements in character set @var{cs}. -@end deffn - -@deffn primitive char-set-count pred cs -Return the number of the elements int the character set -@var{cs} which satisfy the predicate @var{pred}. -@end deffn - -@deffn primitive char-set->list cs -Return a list containing the elements of the character set -@var{cs}. -@end deffn - -@deffn primitive char-set->string cs -Return a string containing the elements of the character set -@var{cs}. The order in which the characters are placed in the -string is not defined. -@end deffn - -@deffn primitive char-set-contains? cs char -Return @code{#t} iff the character @var{ch} is contained in the -character set @var{cs}. -@end deffn - -@deffn primitive char-set-every pred cs -Return a true value if every character in the character set -@var{cs} satisfies the predicate @var{pred}. -@end deffn - -@deffn primitive char-set-any pred cs -Return a true value if any character in the character set -@var{cs} satisfies the predicate @var{pred}. -@end deffn - - -@c =================================================================== - -@node Character-Set Algebra -@subsection Character-Set Algebra - -Character sets can be manipulated with the common set algebra operation, -such as union, complement, intersection etc. All of these procedures -provide side--effecting variants, which modify their character set -argument(s). - -@deffn primitive char-set-adjoin cs char1 @dots{} -@deffnx primitive char-set-adjoin! cs char1 @dots{} -Add all character arguments to the first argument, which must -be a character set. -@end deffn - -@deffn primitive char-set-delete cs char1 @dots{} -@deffnx primitive char-set-delete! cs char1 @dots{} -Delete all character arguments from the first argument, which -must be a character set. -@end deffn - -@deffn primitive char-set-complement cs -@deffnx primitive char-set-complement! cs -Return the complement of the character set @var{cs}. -@end deffn - -@deffn primitive char-set-union cs1 @dots{} -@deffnx primitive char-set-union! cs1 @dots{} -Return the union of all argument character sets. -@end deffn - -@deffn primitive char-set-intersection cs1 @dots{} -@deffnx primitive char-set-intersection! cs1 @dots{} -Return the intersection of all argument character sets. -@end deffn - -@deffn primitive char-set-difference cs1 @dots{} -@deffnx primitive char-set-difference! cs1 @dots{} -Return the difference of all argument character sets. -@end deffn - -@deffn primitive char-set-xor cs1 @dots{} -@deffnx primitive char-set-xor! cs1 @dots{} -Return the exclusive--or of all argument character sets. -@end deffn - -@deffn primitive char-set-diff+intersection cs1 @dots{} -@deffnx primitive char-set-diff+intersection! cs1 @dots{} -Return the difference and the intersection of all argument -character sets. -@end deffn - - -@c =================================================================== - -@node Standard Character Sets -@subsection Standard Character Sets - -In order to make the use of the character set data type and procedures -useful, several predefined character set variables exist. - -@defvar char-set:lower-case -All lower--case characters. -@end defvar - -@defvar char-set:upper-case -All upper--case characters. -@end defvar - -@defvar char-set:title-case -This is empty, because ASCII has no titlecase characters. -@end defvar - -@defvar char-set:letter -All letters, e.g. the union of @code{char-set:lower-case} and -@code{char-set:upper-case}. -@end defvar - -@defvar char-set:digit -All digits. -@end defvar - -@defvar char-set:letter+digit -The union of @code{char-set:letter} and @code{char-set:digit}. -@end defvar - -@defvar char-set:graphic -All characters which would put ink on the paper. -@end defvar - -@defvar char-set:printing -The union of @code{char-set:graphic} and @code{char-set:whitespace}. -@end defvar - -@defvar char-set:whitespace -All whitespace characters. -@end defvar - -@defvar char-set:blank -All horizontal whitespace characters, that is @code{#\space} and -@code{#\tab}. -@end defvar - -@defvar char-set:iso-control -The ISO control characters with the codes 0--31 and 127. -@end defvar - -@defvar char-set:punctuation -The characters @code{!"#%&'()*,-./:;?@@[\\]_@{@}} -@end defvar - -@defvar char-set:symbol -The characters @code{$+<=>^`|~}. -@end defvar - -@defvar char-set:hex-digit -The hexadecimal digits @code{0123456789abcdefABCDEF}. -@end defvar - -@defvar char-set:ascii -All ASCII characters. -@end defvar - -@defvar char-set:empty -The empty character set. -@end defvar - -@defvar char-set:full -This character set contains all possible characters. -@end defvar diff --git a/doc/srfi-modules.texi b/doc/srfi-modules.texi new file mode 100644 index 000000000..e611414c9 --- /dev/null +++ b/doc/srfi-modules.texi @@ -0,0 +1,183 @@ +@node SRFI Support +@chapter Various SRFI Support Modules + +In addition to the string and character--set libraries --- documented in +the next chapter --- Guile has support for a number of SRFIs. This +chapter gives an overview over the available SRFIs and some usage hints. +For complete documentation, we advise you to get the relevant SRFI +documents from the SRFI home page @url{http://srfi.schemers.org}. + +@menu +* SRFI-2:: and-let*. +* SRFI-6:: Basic String Ports. +* SRFI-8:: receive. +* SRFI-9:: define-record-type. +* SRFI-10:: Hash--Comma Reader Extension. +* SRFI-11:: let-values and let-values*. +* SRFI-17:: Generalized set! +@end menu + + +@node SRFI-2 +@section SRFI-2 -- and-let* + +The syntactic form @code{and-let*} combines the conditional evaluation +form @code{and} with the binding form @var{let*}. Each argument +expression will be evaluated sequentially, bound to a variable (if a +variable name is given), but only as long as no expression returns +the false value @code{#f}. + +Use @code{(use-modules (srfi srfi-2)} to access this syntax form. + + +@node SRFI-6 +@section SRFI-6 -- Basic String Ports + +SRFI-6 defines the procedures @code{open-input-string}, +@code{open-output-string} and @code{get-output-string}. These +procedures are included in the Guile core, so using this module does not +make any difference at the moment. But it is possible that support for +SRFI-6 will be factored out of the core library in the future, so using +this module does not hurt, after all. + +@node SRFI-8 +@section SRFI-8 -- receive + +@code{receive} is a syntax for making the handling of multiple--value +procedures easier. It is documented in @xref{Multiple Values}. + + +@node SRFI-9 +@section SRFI-9 -- define-record-type + +This is the SRFI way for defining record types. The Guile +implementation is a layer above Guile's normal record construction +procedures (REFFIXME). The nice thing about this kind of record +definition method is that no new names are implicitly created, all +constructor, accessor and predicates are explicitly given. This reduces +the risk of variable capture. + +The syntax of a record type definition is: + +@example + + -> (define-record-type + ( ...) + + ...) + -> ( ) + -> ( ) + -> +<... name> -> +@end example + +Usage example: + +@example +guile> (use-modules (srfi srfi-9)) +guile> (define-record-type :foo (make-foo x) foo? + (x get-x) (y get-y set-y!)) +guile> (define f (make-foo 1)) +guile> f +#<:foo x: 1 y: #f> +guile> (get-x f) +1 +guile> (set-y! f 2) +2 +guile> (get-y f) +2 +guile> f +#<:foo x: 1 y: 2> +guile> (foo? f) +#t +guile> (foo? 1) +#f +@end example + + +@node SRFI-10 +@section SRFI-10 -- Hash--Comma Reader Extension + +@cindex hash--comma +@cindex #,() +The module @code{(srfi srfi-10)} implements the syntax extension +@code{#,()}, also called hash-comma, which is defined in SRFI-10. + +The support for SRFI-10 consists of the procedure +@code{define-reader-ctor} for defining new reader constructors and the +read syntax form + +@example +#,(@var{ctor} @var{datum} ...) +@end example + +where @var{ctor} must be a symbol for which a read constructor was +defined previouly, using @code{define-reader-ctor}. + +Example: + +@lisp +(define-reader-ctor 'file open-input-file) +(define f '#,(file "/etc/passwd")) +(read-line f) +@result{} +"root:x:0:0:root:/root:/bin/bash" +@end lisp + +Please note the quote before the @code{#,(file ...)} expression. This +is necessary because ports are not self-evaluating in Guile. + +@deffn procedure define-reader-ctor symbol proc +Define @var{proc} as the reader constructor for hash--comma forms with a +tag @var{symbol}. @var{proc} will be applied to the datum(s) following +the tag in the hash--comma expression after the complete form has been +read in. The result of @var{proc} is returned by the Scheme reader. +@end deffn + + +@node SRFI-11 +@section SRFI-11 -- let-values + +This module implements the binding forms for multiple values +@code{let-values} and @code{let-values*}. These forms are similar to +@code{let} and @code{let*} (REFFIXME), but they support binding of the +values returned by multiple--valued expressions. + +Write @code{(use-modules (srfi srfi-11))} to make the bindings +available. + +@lisp +(let-values (((x y) (values 1 2)) + ((z f) (values 3 4))) + (+ x y z f)) +@result{} +10 +@end lisp + +@code{let-values} performs all bindings simultaneously, which means that +no expression in the binding clauses may refer to variables bound in the +same clause list. @code{let-values*}, on the other hand, performs the +bindings sequentially, just like @code{let*} does for single--valued +expressions. + + +@node SRFI-17 +@section SRFI-17 -- Generalized set! + +This is an implementation of SRFI-17: Generalized set! + +It exports the Guile procedure @code{make-procedure-with-setter} under +the SRFI name @code{getter-with-setter} and exports the standard +procedures @code{car}, @code{cdr}, @dots{}, @code{cdddr}, +@code{string-ref} and @code{vector-ref} as procedures with setters, as +required by the SRFI. + +SRFI-17 was heavily criticized during its discussion period but it was +finalized anyway. One issue was its concept of globally associating +setter @dfn{properties} with (procedure) values, which is non-Schemy. +For this reason, this implementation chooses not to provide a way to set +the setter of a procedure. In fact, @code{(set! (setter @var{proc}) +@var{setter})} signals an error. The only way to attach a setter to a +procedure is to create a new object (a @dfn{procedure with setter}) via +the @code{getter-with-setter} procedure. This procedure is also +specified in the SRFI. Using it avoids the described problems.