diff options
-rw-r--r-- | doc/ChangeLog | 12 | ||||
-rwxr-xr-x | doc/scheme-data.texi | 263 | ||||
-rw-r--r-- | doc/scheme-procedures.texi | 178 |
3 files changed, 364 insertions, 89 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog index 7efd2b31e..3f4fe3d83 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,15 @@ +2001-04-11 Martin Grabmueller <mgrabmue@cs.tu-berlin.de> + + * scheme-procedures.texi (Lambda): Documented the lambda form. + (Procedure Properties): Concept and usage explanation added. + (Procedures with Setters): Explain by example, introduce + definitions. + + * scheme-data.texi (Symbols and Variables): Split and reorganized + this section. + (Symbols): New introductory text. + (Characters): Added char-ci* procedures to rn index. + 2001-04-10 Neil Jerram <neil@ossau.uklinux.net> * scm.texi (Handling Errors): Improve Texinfo markup. Thanks to diff --git a/doc/scheme-data.texi b/doc/scheme-data.texi index cd982ab34..a332dace7 100755 --- a/doc/scheme-data.texi +++ b/doc/scheme-data.texi @@ -53,9 +53,9 @@ sections of this manual that cover them. * Lists:: Special list functions supported by Guile. * Records:: * Structures:: -* Arrays:: -* Association Lists and Hash Tables:: -* Vectors:: +* Arrays:: Arrays of values. +* Association Lists and Hash Tables:: Dictionary data types. +* Vectors:: One-dimensional arrays of Scheme objects. * Hooks:: User-customizable event lists. * Other Data Types:: Data types that are documented elsewhere. @end menu @@ -1135,21 +1135,6 @@ Return a new random state using @var{seed}. @node Characters @section Characters -@rnindex char? -@rnindex char=? -@rnindex char<? -@rnindex char>? -@rnindex char<=? -@rnindex char>=? -@rnindex char-alphabetic? -@rnindex char-numeric? -@rnindex char-whitespace? -@rnindex char-upper-case? -@rnindex char-lower-case? -@rnindex char->integer -@rnindex integer->char -@rnindex char-upcase -@rnindex char-downcase Most of the characters in the ASCII character set may be referred to by @@ -1214,79 +1199,95 @@ Several characters have more than one name: #\null, #\nul @end itemize +@rnindex char? @deffn primitive char? x Return @code{#t} iff @var{x} is a character, else @code{#f}. @end deffn +@rnindex char=? @deffn primitive char=? x y Return @code{#t} iff @var{x} is the same character as @var{y}, else @code{#f}. @end deffn +@rnindex char<? @deffn primitive char<? x y Return @code{#t} iff @var{x} is less than @var{y} in the ASCII sequence, else @code{#f}. @end deffn +@rnindex char<=? @deffn primitive char<=? x y Return @code{#t} iff @var{x} is less than or equal to @var{y} in the ASCII sequence, else @code{#f}. @end deffn +@rnindex char>? @deffn primitive char>? x y Return @code{#t} iff @var{x} is greater than @var{y} in the ASCII sequence, else @code{#f}. @end deffn +@rnindex char>=? @deffn primitive char>=? x y Return @code{#t} iff @var{x} is greater than or equal to @var{y} in the ASCII sequence, else @code{#f}. @end deffn +@rnindex char-ci=? @deffn primitive char-ci=? x y Return @code{#t} iff @var{x} is the same character as @var{y} ignoring case, else @code{#f}. @end deffn +@rnindex char-ci<? @deffn primitive char-ci<? x y Return @code{#t} iff @var{x} is less than @var{y} in the ASCII sequence ignoring case, else @code{#f}. @end deffn +@rnindex char-ci<=? @deffn primitive char-ci<=? x y Return @code{#t} iff @var{x} is less than or equal to @var{y} in the ASCII sequence ignoring case, else @code{#f}. @end deffn +@rnindex char-ci>? @deffn primitive char-ci>? x y Return @code{#t} iff @var{x} is greater than @var{y} in the ASCII sequence ignoring case, else @code{#f}. @end deffn +@rnindex char-ci>=? @deffn primitive char-ci>=? x y Return @code{#t} iff @var{x} is greater than or equal to @var{y} in the ASCII sequence ignoring case, else @code{#f}. @end deffn +@rnindex char-alphabetic? @deffn primitive char-alphabetic? chr Return @code{#t} iff @var{chr} is alphabetic, else @code{#f}. Alphabetic means the same thing as the isalpha C library function. @end deffn +@rnindex char-numeric? @deffn primitive char-numeric? chr Return @code{#t} iff @var{chr} is numeric, else @code{#f}. Numeric means the same thing as the isdigit C library function. @end deffn +@rnindex char-whitespace? @deffn primitive char-whitespace? chr Return @code{#t} iff @var{chr} is whitespace, else @code{#f}. Whitespace means the same thing as the isspace C library function. @end deffn +@rnindex char-upper-case? @deffn primitive char-upper-case? chr Return @code{#t} iff @var{chr} is uppercase, else @code{#f}. Uppercase means the same thing as the isupper C library function. @end deffn +@rnindex char-lower-case? @deffn primitive char-lower-case? chr Return @code{#t} iff @var{chr} is lowercase, else @code{#f}. Lowercase means the same thing as the islower C library function. @@ -1298,19 +1299,23 @@ Uppercase and lowercase are as defined by the isupper and islower C library functions. @end deffn +@rnindex char->integer @deffn primitive char->integer chr Return the number corresponding to ordinal position of @var{chr} in the ASCII sequence. @end deffn +@rnindex integer->char @deffn primitive integer->char n Return the character at position @var{n} in the ASCII sequence. @end deffn +@rnindex char-upcase @deffn primitive char-upcase chr Return the uppercase character version of @var{chr}. @end deffn +@rnindex char-downcase @deffn primitive char-downcase chr Return the lowercase character version of @var{chr}. @end deffn @@ -2090,6 +2095,10 @@ to this cumbersome escape syntax. @node Rx Interface @subsection Rx Interface +@c FIXME::martin: Shouldn't this be removed or moved to the +@c ``Guile Modules'' chapter? The functions are not available in +@c plain Guile... + [FIXME: this is taken from Gary and Mark's quick summaries and should be reviewed and expanded. Rx is pretty stable, so could already be done!] @@ -2233,60 +2242,82 @@ Test whether obj is a compiled regular expression. @node Symbols and Variables @section Symbols and Variables +@c FIXME::martin: Review me! -Guile symbol tables are hash tables. Each hash table, also called an -@dfn{obarray} (for `object array'), is a vector of association lists. -Each entry in the alists is a pair (@var{SYMBOL} . @var{VALUE}). To -@dfn{intern} a symbol in a symbol table means to return its -(@var{SYMBOL} . @var{VALUE}) pair, adding a new entry to the symbol -table (with an undefined value) if none is yet present. +Symbols are a data type with a special property. On the one hand, +symbols are used for denoting variables in a Scheme program, on the +other they can be used as literal data as well. -@c FIXME::martin: According to NEWS, removed. Remove here too, or -@c leave for compatibility? -@c @c docstring begin (texi-doc-string "guile" "builtin-bindings") -@c @deffn primitive builtin-bindings -@c Create and return a copy of the global symbol table, removing all -@c unbound symbols. -@c @end deffn +The association between symbols and values is maintained in special data +structures, the symbol tables. -@deffn primitive gensym [prefix] -Create a new symbol with a name constructed from a prefix and -a counter value. The string @var{prefix} can be specified as -an optional argument. Default prefix is @code{g}. The counter -is increased by 1 at each call. There is no provision for -resetting the counter. -@end deffn +In addition, Guile offers variables as first--class objects. They can +be used for interacting with the module system. -@deffn primitive gentemp [prefix [obarray]] -Create a new symbol with a name unique in an obarray. -The name is constructed from an optional string @var{prefix} -and a counter value. The default prefix is @code{t}. The -@var{obarray} is specified as a second optional argument. -Default is the system obarray where all normal symbols are -interned. The counter is increased by 1 at each -call. There is no provision for resetting the counter. -@end deffn +@menu +* Symbols:: All about symbols as a data type. +* Symbol Tables:: Tables for mapping symbols to values. +* Variables:: First--class variables. +@end menu -@deffn primitive intern-symbol obarray string -Add a new symbol to @var{obarray} with name @var{string}, bound to an -unspecified initial value. The symbol table is not modified if a symbol -with this name is already present. -@end deffn +@node Symbols +@subsection Symbols -@deffn primitive string->obarray-symbol obarray string [soft?] -Intern a new symbol in @var{obarray}, a symbol table, with name -@var{string}. +@c FIXME::martin: Review me! + +Symbols are especially useful because two symbols which are spelled the +same way are equivalent in the sense of @code{eq?}. That means that +they are actually the same Scheme object. The advantage is that symbols +can be compared extremely efficiently, although they carry more +information for the human reader than, say, numbers. + +It is very common in Scheme programs to use symbols as keys in +association lists (REFFIXME) or hash tables (REFFIXME), because this +usage improves the readability a lot, and does not cause any performance +loss. -If @var{obarray} is @code{#f}, use the default system symbol table. If -@var{obarray} is @code{#t}, the symbol should not be interned in any -symbol table; merely return the pair (@var{symbol} -. @var{#<undefined>}). +The read syntax for symbols is a sequence of letters, digits, and +@emph{extended alphabetic characters} that begins with a character that +cannot begin a number is an identifier. In addition, @code{+}, +@code{-}, and @code{...} are identifiers. -The @var{soft?} argument determines whether new symbol table entries -should be created when the specified symbol is not already present in -@var{obarray}. If @var{soft?} is specified and is a true value, then -new entries should not be added for symbols not already present in the -table; instead, simply return @code{#f}. +Extended alphabetic characters may be used within identifiers as if +they were letters. The following are extended alphabetic characters: + +@example +! $ % & * + - . / : < = > ? @@ ^ _ ~ +@end example + +In addition to the read syntax defined above (which is taken from R5RS +(REFFIXME)), Guile provides a method for writing symbols with unusual +characters, such as space characters. If you (for whatever reason) need +to write a symbol containing characters not mentioned above, you write +symbols as follows: + +@itemize @bullet +@item Begin the symbol with the two character @code{#@{}, +@item write the characters of the symbol and +@item finish the symbol with the characters @code{@}#}. +@end itemize + +Here are a few examples of this form of read syntax; the first +containing a space character, the second containing a line break and the +last one looks like a number. + +@lisp +#@{foo bar@}# +#@{what +ever@}# +#@{4242@}# +@end lisp + +Usage of this form of read syntax is discouraged, because it is not +portable at all, and is not very readable. + +@rnindex symbol? +@deffn primitive symbol? obj +Return @code{#t} if @var{obj} is a symbol, otherwise return +@code{#f}. @end deffn @rnindex string->symbol @@ -2336,6 +2367,57 @@ standard case is lower case: @end lisp @end deffn +@node Symbol Tables +@subsection Symbol Tables + +@c FIXME::martin: Review me! + +@c FIXME::martin: Are all these procedures still relevant? + +Guile symbol tables are hash tables. Each hash table, also called an +@dfn{obarray} (for `object array'), is a vector of association lists. +Each entry in the alists is a pair (@var{SYMBOL} . @var{VALUE}). To +@dfn{intern} a symbol in a symbol table means to return its +(@var{SYMBOL} . @var{VALUE}) pair, adding a new entry to the symbol +table (with an undefined value) if none is yet present. + +@c FIXME::martin: According to NEWS, removed. Remove here too, or +@c leave for compatibility? +@c @c docstring begin (texi-doc-string "guile" "builtin-bindings") +@c @deffn primitive builtin-bindings +@c Create and return a copy of the global symbol table, removing all +@c unbound symbols. +@c @end deffn + +@deffn primitive gensym [prefix] +Create a new symbol with a name constructed from a prefix and +a counter value. The string @var{prefix} can be specified as +an optional argument. Default prefix is @code{g}. The counter +is increased by 1 at each call. There is no provision for +resetting the counter. +@end deffn + +@deffn primitive gentemp [prefix [obarray]] +Create a new symbol with a name unique in an obarray. +The name is constructed from an optional string @var{prefix} +and a counter value. The default prefix is @code{t}. The +@var{obarray} is specified as a second optional argument. +Default is the system obarray where all normal symbols are +interned. The counter is increased by 1 at each +call. There is no provision for resetting the counter. +@end deffn + +@deffn primitive intern-symbol obarray string +Add a new symbol to @var{obarray} with name @var{string}, bound to an +unspecified initial value. The symbol table is not modified if a symbol +with this name is already present. +@end deffn + +@deffn primitive string->obarray-symbol obarray string [soft?] +Intern a new symbol in @var{obarray}, a symbol table, with name +@var{string}. +@end deffn + @deffn primitive symbol-binding obarray string Look up in @var{obarray} the symbol whose name is @var{string}, and return the value to which it is bound. If @var{obarray} is @code{#f}, @@ -2383,18 +2465,29 @@ it to @var{value}. An error is signalled if @var{string} is not present in @var{obarray}. @end deffn -@rnindex symbol? -@deffn primitive symbol? obj -Return @code{#t} if @var{obj} is a symbol, otherwise return -@code{#f}. -@end deffn - @deffn primitive unintern-symbol obarray string Remove the symbol with name @var{string} from @var{obarray}. This function returns @code{#t} if the symbol was present and @code{#f} otherwise. @end deffn +@node Variables +@subsection Variables + +@c FIXME::martin: Review me! + +Variables are objects with two fields. They contain a value and they +can contain a symbol, which is the name of the variable. A variable is +said to be bound if it does not contain the object denoting unbound +variables in the value slot. + +Variables do not have a read syntax, they have to be created by calling +one of the constructor procedures @code{make-variable} or +@code{make-undefined-variable} or retrieved by @code{builtin-variable}. + +First--class variables are especially useful for interacting with the +current module system (REFFIXME). + @deffn primitive builtin-variable name Return the built-in variable with the name @var{name}. @var{name} must be a symbol (not a string). @@ -2755,10 +2848,12 @@ by @code{set-cdr!} is unspecified. @node Lists @section Lists -A very important datatype in Scheme---as well as in all other Lisp +@c FIXME::martin: Review me! + +A very important data type in Scheme---as well as in all other Lisp dialects---is the data type @dfn{list}.@footnote{Strictly speaking, Scheme does not have a real datatype @emph{list}. Lists are made up of -chained @emph{pairs}, and only exist by definition --- A list is a chain +chained @emph{pairs}, and only exist by definition---a list is a chain of pairs which looks like a list.} This is the short definition of what a list is: @@ -2790,6 +2885,8 @@ This is the short definition of what a list is: @node List Syntax @subsection List Read Syntax +@c FIXME::martin: Review me! + The syntax for lists is an opening parentheses, then all the elements of the list (separated by whitespace) and finally a closing parentheses.@footnote{Note that there is no separation character between @@ -2823,6 +2920,8 @@ applications (REFFIXME). @node List Predicates @subsection List Predicates +@c FIXME::martin: Review me! + Often it is useful to test whether a given Scheme object is a list or not. List--processing procedures could use this information to test whether their input is valid, or they could do different things @@ -2881,6 +2980,8 @@ use the procedure @code{copy-tree} (REFFIXME). @node List Selection @subsection List Selection +@c FIXME::martin: Review me! + These procedures are used to get some information about a list, or to retrieve one or more elements of a list. @@ -2918,6 +3019,8 @@ return it. @node Append/Reverse @subsection Append and Reverse +@c FIXME::martin: Review me! + @code{append} and @code{append!} are used to concatenate two or more lists in order to form a new list. @code{reverse} and @code{reverse!} return lists with the same elements as their arguments, but in reverse @@ -2977,6 +3080,8 @@ of the modified list is not lost, it is wise to save the return value of @node List Modifification @subsection List Modification +@c FIXME::martin: Review me! + The following procedures modify existing list. @code{list-set!} and @code{list-cdr-set!} change which elements a list contains, the various deletion procedures @code{delq}, @code{delv} etc. @@ -3042,6 +3147,8 @@ Like @code{delete!}, but only deletes the first occurrence of @node List Searching @subsection List Searching +@c FIXME::martin: Review me! + The following procedures search lists for particular elements. They use different comparison predicates for comparing list elements with the object to be seached. When they fail, they return @code{#f}, otherwise @@ -3103,6 +3210,8 @@ not for high-level Scheme programs. @node List Mapping @subsection List Mapping +@c FIXME::martin: Review me! + List processing is very convenient in Scheme because the process of iterating over the elements of a list can be highly abstracted. The procedures in this section are the most basic iterating procedures for @@ -4835,8 +4944,8 @@ using @code{run-hook}. (display (* x y)) (newline))) (run-hook hook 3 4) -Bar: 12 -Foo: 7 +@print{} Bar: 12 +@print{} Foo: 7 @end lisp Note that the procedures are called in reverse order than they were @@ -4852,10 +4961,10 @@ on the second call to @code{add-hook!}. (display "Bar: ") (display (* x y)) (newline)) - #t) ; <- Change here! + #t) ; @r{<- Change here!} (run-hook hook 3 4) -Foo: 7 -Bar: 12 +@print{} Foo: 7 +@print{} Bar: 12 @end lisp @node Hook Reference diff --git a/doc/scheme-procedures.texi b/doc/scheme-procedures.texi index cbb405fde..c67f4556c 100644 --- a/doc/scheme-procedures.texi +++ b/doc/scheme-procedures.texi @@ -14,6 +14,69 @@ @node Lambda @section Lambda: Basic Procedure Creation +@c FIXME::martin: Review me! + +A @code{lambda} expression evaluates to a procedure. The environment +which is in effect when a @code{lambda} expression is evaluated is +enclosed in the newly created procedure, this is referred to as a +@dfn{closure} (@pxref{About Closure}). + +When a procedure created by @code{lambda} is called with some actual +arguments, the environment enclosed in the procedure is extended by +binding the variables named in the formal argument list to new locations +and storing the actual arguments into these locations. Then the body of +the @code{lambda} expression is evaluation sequentially. The result of +the last expression in the procedure body is then the result of the +procedure invocation. + +The following examples will show how procedures can be created using +@code{lambda}, and what you can do with these procedures. + +@lisp +(lambda (x) (+ x x)) @result{} @r{a procedure} +((lambda (x) (+ x x)) 4) @result{} 8 +@end lisp + +The fact that the environment in effect when creating a procedure is +enclosed in the procedure is shown with this example: + +@lisp +(define add4 + (let ((x 4)) + (lambda (y) (+ x y)))) +(add4 6) @result{} 10 +@end lisp + + +@deffn syntax lambda formals body +@var{formals} should be a formal argument list as described in the +following table. + +@table @code +@item (@var{variable1} @dots{}) +The procedure takes a fixed number of arguments; when the procedure is +called, the arguments will be stored into the newly created location for +the formal variables. +@item @var{variable} +The procedure takes any number of arguments; when the procedure is +called, the sequence of actual arguments will converted into a list and +stored into the newly created location for the formal variable. +@item (@var{variable1} @dots{} @var{variablen} . @var{variablen+1}) +If a space--delimited period precedes the last variable, then the +procedure takes @var{n} or more variablesm where @var{n} is the number +of formal arguments before the period. There must be at least one +argument before the period. The first @var{n} actual arguments will be +stored into the newly allocated locations for the first @var{n} formal +arguments and the sequence of the remaining actual arguments is +converted into a list and the stored into the location for the last +formal argument. If there are exactly @var{n} actual arguments, the +empty list is stored into the location of the last formal argument. +@end table + +@var{body} is a sequence of Scheme expressions which are evaluated in +order when the procedure is invoked. +@end deffn + @node Optional Arguments @section Optional Arguments @@ -22,6 +85,42 @@ @node Procedure Properties @section Procedure Properties and Metainformation +@c FIXME::martin: Review me! + +Procedures always have attached the environment in which they were +created and information about how to apply them to actual arguments. In +addition to that, properties and metainformation can be stored with +procedures. The procedures in this section can be used to test whether +a given procedure satisfies a condition; and to access and set a +procedure's property. + +The first group of procedures are predicates to test whether a Scheme +object is a procedure, or a special procedure, respectively. +@code{procedure?} is the most general predicates, it returns @code{#t} +for any kind of procedure. @code{closure?} does not return @code{#t} +for primitive procedures, and @code{thunk?} only returns @code{#t} for +procedures which do not accept any arguments. +@c FIXME::martin: thunk? returns true for `id'. What's wrong here? + +@rnindex procedure? +@deffn primitive procedure? obj +Return @code{#t} if @var{obj} is a procedure. +@end deffn + +@deffn primitive closure? obj +Return @code{#t} if @var{obj} is a closure. +@end deffn + +@deffn primitive thunk? obj +Return @code{#t} if @var{obj} is a thunk. +@end deffn + +@c FIXME::martin: Is that true? +@cindex procedure properties +Procedure properties are general properties to be attached to +procedures. These can be the name of a procedure or other relevant +information, such as debug hints. + @deffn primitive procedure-properties proc Return @var{obj}'s property list. @end deffn @@ -39,6 +138,10 @@ In @var{obj}'s property list, set the property named @var{key} to @var{value}. @end deffn +@cindex procedure documentation +Documentation for a procedure can be accessed with the procedure +@code{procedure-documentation}. + @deffn primitive procedure-documentation proc Return the documentation string associated with @code{proc}. By convention, if a procedure contains more than one expression and the @@ -46,18 +149,10 @@ first expression is a string constant, that string is assumed to contain documentation for that procedure. @end deffn -@deffn primitive closure? obj -Return @code{#t} if @var{obj} is a closure. -@end deffn - -@rnindex procedure? -@deffn primitive procedure? obj -Return @code{#t} if @var{obj} is a procedure. -@end deffn - -@deffn primitive thunk? obj -Return @code{#t} if @var{obj} is a thunk. -@end deffn +@cindex source properties +@c FIXME::martin: Is the following true? +Source properties are properties which are related to the source code of +a procedure, such as the line and column numbers, the file name etc. @deffn primitive set-source-properties! obj plist Install the association list @var{plist} as the source property @@ -83,6 +178,63 @@ Return the source property specified by @var{key} from @node Procedures with Setters @section Procedures with Setters +@c FIXME::martin: Review me! + +@c FIXME::martin: Document `operator struct'. + +@cindex procedure with setter +@cindex setter +A @dfn{procedure with setter} is a special kind of procedure which +normally behaves like any accesor procedure, that is a procedure which +accesses a data structure. The difference is that this kind of +procedure has a so--called @dfn{setter} attached, which is a procedure +for storing something into a data structure. + +Procedures with setters are treated specially when the procedure appears +in the special form @code{set!} (REFFIXME). How it works is best shown +by example. + +Suppose we have a procedure called @code{foo-ref}, which accepts two +arguments, a value of type @code{foo} and an integer. The procedure +returns the value stored at the given index in the @code{foo} object. +Let @code{f} be a variable containing such a @code{foo} data +structure.@footnote{Working definitions would be: +@lisp +(define foo-ref vector-ref) +(define foo-set! vector-set!) +(define f (make-vector 2 #f)) +@end lisp} + +@lisp +(foo-ref f 0) @result{} bar +(foo-ref f 1) @result{} braz +@end lisp + +Also suppose that a corresponding setter procedure called +@code{foo-set!} does exist. + +@lisp +(foo-set! f 0 'bla) +(foo-ref f 0) @result{} bla +@end lisp + +Now we could create a new procedure called @code{foo}, which is a +procedure with setter, by calling @code{make-procedure-with-setter} with +the accessor and setter procedures @code{foo-ref} and @code{foo-set!}. +Let us call this new procedure @code{foo}. + +@lisp +(define foo (make-procedure-with-setter foo-ref foo-set!)) +@end lisp + +@code{foo} can from now an be used to either read from the data +structure stored in @code{f}, or to write into the structure. + +@lisp +(set! (foo f 0) 'dum) +(foo f 0) @result{} dum +@end lisp + @deffn primitive make-procedure-with-setter procedure setter Create a new procedure which behaves like @var{procedure}, but with the associated setter @var{setter}. @@ -99,6 +251,8 @@ procedure with setter, or an operator struct. @end deffn @deffn primitive setter proc +Return the setter of @var{proc}, which must be either a procedure with +setter or an operator struct. @end deffn |