mirror of
https://git.savannah.gnu.org/git/guile.git
synced 2025-07-02 07:40:30 +02:00
* scripts.texi (Invoking Guile): Added docs for --use-srfi.
* expect.texi, repl-modules.texi: Start the chapters with a new page. * srfi-modules.texi (SRFI-0): Added note about supported feature identifiers and an example. Start the chapter with a new page. * srfi-modules.texi, scheme-data.texi, scheme-control.texi, scheme-binding.texi, repl-modules.texi, posix.texi, intro.texi, scheme-utility.texi: Change `--' to `-' throughout.
This commit is contained in:
Martin Grabmüller
parent
5f5850b38c
commit
fb02eb66f6
12 changed files with 91 additions and 484 deletions
|
|
@ -1,3 +1,17 @@
|
|||
2001-05-15 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
|
||||
|
||||
* scripts.texi (Invoking Guile): Added docs for --use-srfi.
|
||||
|
||||
* expect.texi, repl-modules.texi: Start the chapters with a new
|
||||
page.
|
||||
|
||||
* srfi-modules.texi (SRFI-0): Added note about supported feature
|
||||
identifiers and an example. Start the chapter with a new page.
|
||||
|
||||
* srfi-modules.texi, scheme-data.texi, scheme-control.texi,
|
||||
scheme-binding.texi, repl-modules.texi, posix.texi, intro.texi,
|
||||
scheme-utility.texi: Change `--' to `-' throughout.
|
||||
|
||||
2001-05-14 Martin Grabmueller <mgrabmue@cs.tu-berlin.de>
|
||||
|
||||
* srfi-13-14.texi: Removed.
|
||||
|
|
|
|||
141
doc/expect.texi
141
doc/expect.texi
|
|
@ -1,141 +0,0 @@
|
|||
@node Expect
|
||||
@chapter Expect
|
||||
|
||||
The macros in this section are made available with:
|
||||
|
||||
@smalllisp
|
||||
(use-modules (ice-9 expect))
|
||||
@end smalllisp
|
||||
|
||||
@code{expect} is a macro for selecting actions based on the output from
|
||||
a port. The name comes from a tool of similar functionality by Don Libes.
|
||||
Actions can be taken when a particular string is matched, when a timeout
|
||||
occurs, or when end-of-file is seen on the port. The @code{expect} macro
|
||||
is described below; @code{expect-strings} is a front-end to @code{expect}
|
||||
based on regexec (see the regular expression documentation).
|
||||
|
||||
@defmac expect-strings clause @dots{}
|
||||
By default, @code{expect-strings} will read from the current input port.
|
||||
The first term in each clause consists of an expression evaluating to
|
||||
a string pattern (regular expression). As characters
|
||||
are read one-by-one from the port, they are accumulated in a buffer string
|
||||
which is matched against each of the patterns. When a
|
||||
pattern matches, the remaining expression(s) in
|
||||
the clause are evaluated and the value of the last is returned. For example:
|
||||
|
||||
@smalllisp
|
||||
(with-input-from-file "/etc/passwd"
|
||||
(lambda ()
|
||||
(expect-strings
|
||||
("^nobody" (display "Got a nobody user.\n")
|
||||
(display "That's no problem.\n"))
|
||||
("^daemon" (display "Got a daemon user.\n")))))
|
||||
@end smalllisp
|
||||
|
||||
The regular expression is compiled with the @code{REG_NEWLINE} flag, so
|
||||
that the ^ and $ anchors will match at any newline, not just at the start
|
||||
and end of the string.
|
||||
|
||||
There are two other ways to write a clause:
|
||||
|
||||
The expression(s) to evaluate
|
||||
can be omitted, in which case the result of the regular expression match
|
||||
(converted to strings, as obtained from regexec with match-pick set to "")
|
||||
will be returned if the pattern matches.
|
||||
|
||||
The symbol @code{=>} can be used to indicate that the expression is a
|
||||
procedure which will accept the result of a successful regular expression
|
||||
match. E.g.,
|
||||
|
||||
@smalllisp
|
||||
("^daemon" => write)
|
||||
("^d\\(aemon\\)" => (lambda args (for-each write args)))
|
||||
("^da\\(em\\)on" => (lambda (all sub)
|
||||
(write all) (newline)
|
||||
(write sub) (newline)))
|
||||
@end smalllisp
|
||||
|
||||
The order of the substrings corresponds to the order in which the
|
||||
opening brackets occur.
|
||||
|
||||
A number of variables can be used to control the behaviour
|
||||
of @code{expect} (and @code{expect-strings}).
|
||||
Most have default top-level bindings to the value @code{#f},
|
||||
which produces the default behaviour.
|
||||
They can be redefined at the
|
||||
top level or locally bound in a form enclosing the expect expression.
|
||||
|
||||
@table @code
|
||||
@item expect-port
|
||||
A port to read characters from, instead of the current input port.
|
||||
@item expect-timeout
|
||||
@code{expect} will terminate after this number of
|
||||
seconds, returning @code{#f} or the value returned by expect-timeout-proc.
|
||||
@item expect-timeout-proc
|
||||
A procedure called if timeout occurs. The procedure takes a single argument:
|
||||
the accumulated string.
|
||||
@item expect-eof-proc
|
||||
A procedure called if end-of-file is detected on the input port. The
|
||||
procedure takes a single argument: the accumulated string.
|
||||
@item expect-char-proc
|
||||
A procedure to be called every time a character is read from the
|
||||
port. The procedure takes a single argument: the character which was read.
|
||||
@item expect-strings-compile-flags
|
||||
Flags to be used when compiling a regular expression, which are passed
|
||||
to @code{make-regexp} @xref{Regexp Functions}. The default value
|
||||
is @code{regexp/newline}.
|
||||
@item expect-strings-exec-flags
|
||||
Flags to be used when executing a regular expression, which are
|
||||
passed to regexp-exec @xref{Regexp Functions}.
|
||||
The default value is @code{regexp/noteol}, which prevents @code{$}
|
||||
from matching the end of the string while it is still accumulating,
|
||||
but still allows it to match after a line break or at the end of file.
|
||||
@end table
|
||||
|
||||
Here's an example using all of the variables:
|
||||
|
||||
@smalllisp
|
||||
(let ((expect-port (open-input-file "/etc/passwd"))
|
||||
(expect-timeout 1)
|
||||
(expect-timeout-proc
|
||||
(lambda (s) (display "Times up!\n")))
|
||||
(expect-eof-proc
|
||||
(lambda (s) (display "Reached the end of the file!\n")))
|
||||
(expect-char-proc display)
|
||||
(expect-strings-compile-flags (logior regexp/newline regexp/icase))
|
||||
(expect-strings-exec-flags 0))
|
||||
(expect-strings
|
||||
("^nobody" (display "Got a nobody user\n"))))
|
||||
@end smalllisp
|
||||
@end defmac
|
||||
|
||||
@defmac expect clause @dots{}
|
||||
@code{expect} is used in the same way as @code{expect-strings},
|
||||
but tests are specified not as patterns, but as procedures. The
|
||||
procedures are called in turn after each character is read from the
|
||||
port, with two arguments: the value of the accumulated string and
|
||||
a flag to indicate whether end-of-file has been reached. The flag
|
||||
will usually be @code{#f}, but if end-of-file is reached, the procedures
|
||||
are called an additional time with the final accumulated string and
|
||||
@code{#t}.
|
||||
|
||||
The test is successful if the procedure returns a non-false value.
|
||||
|
||||
If the @code{=>} syntax is used, then if the test succeeds it must return
|
||||
a list containing the arguments to be provided to the corresponding
|
||||
expression.
|
||||
|
||||
In the following example, a string will only be matched at the beginning
|
||||
of the file:
|
||||
|
||||
@smalllisp
|
||||
(let ((expect-port (open-input-file "/etc/passwd")))
|
||||
(expect
|
||||
((lambda (s eof?) (string=? s "fnord!"))
|
||||
(display "Got a nobody user!\n"))))
|
||||
@end smalllisp
|
||||
|
||||
The control variables described for @code{expect-strings} also
|
||||
influence the behaviour of @code{expect}, with the exception of
|
||||
variables whose names begin with @code{expect-strings-}.
|
||||
@end defmac
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
@c $Id: intro.texi,v 1.8 2001-05-13 19:14:41 ttn Exp $
|
||||
@c $Id: intro.texi,v 1.9 2001-05-16 18:08:12 mgrabmue Exp $
|
||||
|
||||
@page
|
||||
@node What is Guile?
|
||||
|
|
@ -869,7 +869,7 @@ be a bug, unless this is explicitly documented.
|
|||
|
||||
@item
|
||||
When some part of the documentation is not clear and does not make sense
|
||||
to you even after re--reading the section, it is a bug.
|
||||
to you even after re-reading the section, it is a bug.
|
||||
@end itemize
|
||||
|
||||
When you write a bug report, please make sure to include as much of the
|
||||
|
|
@ -915,7 +915,7 @@ unmodified Guile. But if you've made modifications and you don't tell
|
|||
us, you are sending us on a wild goose chase.)
|
||||
|
||||
Be precise about these changes. A description in English is not
|
||||
enough--send a context diff for them.
|
||||
enough---send a context diff for them.
|
||||
|
||||
Adding files of your own, or porting to another machine, is a
|
||||
modification of the source.
|
||||
|
|
@ -979,7 +979,7 @@ certain.
|
|||
@item
|
||||
Additional information from a C debugger such as GDB might enable
|
||||
someone to find a problem on a machine which he does not have available.
|
||||
If you don't know how to use GDB, please read the GDB manual--it is not
|
||||
If you don't know how to use GDB, please read the GDB manual---it is not
|
||||
very long, and using GDB is easy. You can find the GDB distribution,
|
||||
including the GDB manual in online form, in most of the same places you
|
||||
can find the Guile distribution. To run Guile under GDB, you should
|
||||
|
|
|
|||
|
|
@ -2278,7 +2278,7 @@ the locale will be set using envirionment variables.
|
|||
@section Encryption
|
||||
|
||||
Please note that the procedures in this section are not suited for
|
||||
strong encryption, they are only interfaces to the well--known and
|
||||
strong encryption, they are only interfaces to the well-known and
|
||||
common system library functions of the same name. They are just as good
|
||||
(or bad) as the underlying functions, so you should refer to your system
|
||||
documentation before using them.
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
@page
|
||||
@node Readline Support
|
||||
@chapter Readline Support
|
||||
|
||||
|
|
@ -6,7 +7,7 @@
|
|||
@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
|
||||
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
|
||||
|
|
@ -43,10 +44,11 @@ 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
|
||||
new Guile session and still have the (probably long-winded) definition
|
||||
expressions available.
|
||||
|
||||
|
||||
@page
|
||||
@node Value History
|
||||
@chapter Value History
|
||||
|
||||
|
|
|
|||
|
|
@ -62,7 +62,7 @@ Bindings}) act differently (@pxref{Internal Definitions}).
|
|||
As opposed to definitions at the top level, which are visible in the
|
||||
whole program (or current module, when Guile modules are used), it is
|
||||
also possible to define variables which are only visible in a
|
||||
well--defined part of the program. Normally, this part of a program
|
||||
well-defined part of the program. Normally, this part of a program
|
||||
will be a procedure or a subexpression of a procedure.
|
||||
|
||||
With the constructs for local binding (@code{let}, @code{let*} and
|
||||
|
|
@ -83,7 +83,7 @@ using plain @code{let} is a bit inconvenient.
|
|||
((@var{variable1} @var{init1}) @dots{})
|
||||
@end lisp
|
||||
|
||||
that is zero or more two--element lists of a variable and an arbitrary
|
||||
that is zero or more two-element lists of a variable and an arbitrary
|
||||
expression each. All @var{variable} names must be distinct.
|
||||
|
||||
A @code{let} expression is evaluated as follows.
|
||||
|
|
@ -179,9 +179,9 @@ peach
|
|||
@end lisp
|
||||
|
||||
Here the enclosing form is a @code{let}, so the @code{define}s in the
|
||||
@code{let}--body are internal definitions. Because the scope of the
|
||||
@code{let}-body are internal definitions. Because the scope of the
|
||||
internal definitions is the @strong{complete} body of the
|
||||
@code{let}--expression, the @code{lambda}--expression which gets bound
|
||||
@code{let}-expression, the @code{lambda}-expression which gets bound
|
||||
to the variable @code{banana} may refer to the variable @code{apple},
|
||||
even thogh it's definition appears lexically @emph{after} the definition
|
||||
of @code{banana}. This is because a sequence of internal definition
|
||||
|
|
|
|||
|
|
@ -39,13 +39,13 @@ expression below:
|
|||
@end lisp
|
||||
|
||||
If the two calls to @code{display} and @code{newline} were not embedded
|
||||
in a @code{begin}--statement, the call to @code{newline} would get
|
||||
misinterpreted as the else--branch of the @code{if}--expression.
|
||||
in a @code{begin}-statement, the call to @code{newline} would get
|
||||
misinterpreted as the else-branch of the @code{if}-expression.
|
||||
|
||||
@deffn syntax begin expr1 expr2 @dots{}
|
||||
The expression(s) are evaluated in left--to--right order and the value
|
||||
The expression(s) are evaluated in left-to-right order and the value
|
||||
of the last expression is returned as the value of the
|
||||
@code{begin}--expression. This expression type is used when the
|
||||
@code{begin}-expression. This expression type is used when the
|
||||
expressions before the last one are evaluated for their side effects.
|
||||
@end deffn
|
||||
|
||||
|
|
@ -62,7 +62,7 @@ expressions before the last one are evaluated for their side effects.
|
|||
@cindex cond
|
||||
|
||||
Guile provides three syntactic constructs for conditional evaluation.
|
||||
@code{if} is the normal if--then--else expression (with an optional else
|
||||
@code{if} is the normal if-then-else expression (with an optional else
|
||||
branch), @code{cond} is a conditional expression with multiple branches
|
||||
and @code{case} branches if an expression has one of a set of constant
|
||||
values.
|
||||
|
|
@ -98,13 +98,13 @@ where @var{expression} must evaluate to a procedure.
|
|||
The @var{test}s of the clauses are evaluated in order and as soon as one
|
||||
of them evaluates to a true values, the corresponding @var{expression}s
|
||||
are evaluated in order and the last value is returned as the value of
|
||||
the @code{cond}--expression. For the @code{=>} clause type,
|
||||
the @code{cond}-expression. For the @code{=>} clause type,
|
||||
@var{expression} is evaluated and the resulting procedure is applied to
|
||||
the value of @var{test}. The result of this procedure application is
|
||||
then the result of the @code{cond}--expression.
|
||||
then the result of the @code{cond}-expression.
|
||||
|
||||
The @var{test} of the last @var{clause} may be the keyword @code{else}.
|
||||
Then, if none of the preceding @var{test}s is true, the @var{expression}s following the @code{else} are evaluated to produce the result of the @code{cond}--expression.
|
||||
Then, if none of the preceding @var{test}s is true, the @var{expression}s following the @code{else} are evaluated to produce the result of the @code{cond}-expression.
|
||||
@end deffn
|
||||
|
||||
@deffn syntax case key clause1 clause2 @dots{}
|
||||
|
|
@ -127,7 +127,7 @@ the @var{datum} are evaluated from left to right, returning the value of
|
|||
the last expression as the result of the @code{case} expression.
|
||||
|
||||
If the @var{key} matches no @var{datum} and there is an
|
||||
@code{else}--clause, the expressions following the @code{else} are
|
||||
@code{else}-clause, the expressions following the @code{else} are
|
||||
evaluated. If there is no such clause, the result of the expression is
|
||||
unspecified.
|
||||
@end deffn
|
||||
|
|
@ -204,11 +204,11 @@ is @code{#f} right from the start.
|
|||
|
||||
@cindex named let
|
||||
Another very common way of expressing iteration in Scheme programs is
|
||||
the use of the so--called @dfn{named let}.
|
||||
the use of the so-called @dfn{named let}.
|
||||
|
||||
Named let is a variant of @code{let} which creates a procedure and calls
|
||||
it in one step. Because of the newly created procedure, named let is
|
||||
more powerful than @code{do}---it can be used for iteration, but also
|
||||
more powerful than @code{do}--it can be used for iteration, but also
|
||||
for arbitrary recursion.
|
||||
|
||||
@deffn syntax let variable bindings body
|
||||
|
|
@ -310,7 +310,7 @@ called only one time. This can be confusing at times.
|
|||
|
||||
Scheme allows a procedure to return more than one value to its caller.
|
||||
This is quite different to other languages which only allow
|
||||
single--value returns. Returning multiple values is different from
|
||||
single-value returns. Returning multiple values is different from
|
||||
returning a list (or pair or vector) of values to the caller, because
|
||||
conceptionally not @emph{one} compound object is returned, but several
|
||||
distinct values.
|
||||
|
|
|
|||
|
|
@ -1337,7 +1337,7 @@ Return the lowercase character version of @var{chr}.
|
|||
@node Strings
|
||||
@section Strings
|
||||
|
||||
Strings are fixed--length sequences of characters. They can be created
|
||||
Strings are fixed-length sequences of characters. They can be created
|
||||
by calling constructor procedures, but they can also literally get
|
||||
entered at the REPL or in Scheme source files.
|
||||
|
||||
|
|
@ -1345,11 +1345,11 @@ Guile provides a rich set of string processing procedures, because text
|
|||
handling is very important when Guile is used as a scripting language.
|
||||
|
||||
Strings always carry the information about how many characters they are
|
||||
composed of with them, so there is no special end--of--string character,
|
||||
composed of with them, so there is no special end-of-string character,
|
||||
like in C. That means that Scheme strings can contain any character,
|
||||
even the NUL character @code{'\0'}. But note: Since most operating
|
||||
system calls dealing with strings (such as for file operations) expect
|
||||
strings to be zero--terminated, they might do unexpected things when
|
||||
strings to be zero-terminated, they might do unexpected things when
|
||||
called with string containing unusal characters.
|
||||
|
||||
@menu
|
||||
|
|
@ -1507,7 +1507,7 @@ exact integers satisfying:
|
|||
@node String Modification
|
||||
@subsection String Modification
|
||||
|
||||
These procedures are for modifying strings in--place. That means, that
|
||||
These procedures are for modifying strings in-place. That means, that
|
||||
not a new string is the result of a string operation, but that the
|
||||
actual memory representation of a string is modified.
|
||||
|
||||
|
|
@ -1738,7 +1738,7 @@ the C library.
|
|||
@node Alphabetic Case Mapping
|
||||
@subsection Alphabetic Case Mapping
|
||||
|
||||
These are procedures for mapping strings to their upper-- or lower--case
|
||||
These are procedures for mapping strings to their upper- or lower-case
|
||||
equivalents, respectively, or for capitalizing strings.
|
||||
|
||||
@deffn primitive string-upcase str
|
||||
|
|
@ -1810,7 +1810,7 @@ This section contains several remaining string procedures.
|
|||
@deffn primitive string-ci->symbol str
|
||||
Return the symbol whose name is @var{str}. @var{str} is
|
||||
converted to lowercase before the conversion is done, if Guile
|
||||
is currently reading symbols case--insensitively.
|
||||
is currently reading symbols case-insensitively.
|
||||
@end deffn
|
||||
|
||||
|
||||
|
|
@ -2292,13 +2292,13 @@ other they can be used as literal data as well.
|
|||
The association between symbols and values is maintained in special data
|
||||
structures, the symbol tables.
|
||||
|
||||
In addition, Guile offers variables as first--class objects. They can
|
||||
In addition, Guile offers variables as first-class objects. They can
|
||||
be used for interacting with the module system.
|
||||
|
||||
@menu
|
||||
* Symbols:: All about symbols as a data type.
|
||||
* Symbol Tables:: Tables for mapping symbols to values.
|
||||
* Variables:: First--class variables.
|
||||
* Variables:: First-class variables.
|
||||
@end menu
|
||||
|
||||
@node Symbols
|
||||
|
|
@ -2398,7 +2398,7 @@ part of an object returned as the value of a literal expression
|
|||
Report on Scheme}) or by a call to the @code{read} procedure,
|
||||
and its name contains alphabetic characters, then the string
|
||||
returned will contain characters in the implementation's
|
||||
preferred standard case---some implementations will prefer
|
||||
preferred standard case--some implementations will prefer
|
||||
upper case, others lower case. If the symbol was returned by
|
||||
@code{string->symbol}, the case of characters in the string
|
||||
returned will be the same as the case in the string that was
|
||||
|
|
@ -2535,7 +2535,7 @@ 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
|
||||
First-class variables are especially useful for interacting with the
|
||||
current module system (REFFIXME).
|
||||
|
||||
@deffn primitive builtin-variable name
|
||||
|
|
@ -2976,7 +2976,7 @@ applications (REFFIXME).
|
|||
@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
|
||||
not. List-processing procedures could use this information to test
|
||||
whether their input is valid, or they could do different things
|
||||
depending on the datatype of their arguments.
|
||||
|
||||
|
|
@ -2985,7 +2985,7 @@ depending on the datatype of their arguments.
|
|||
Return @code{#t} iff @var{x} is a proper list, else @code{#f}.
|
||||
@end deffn
|
||||
|
||||
The predicate @code{null?} is often used in list--processing code to
|
||||
The predicate @code{null?} is often used in list-processing code to
|
||||
tell whether a given list has run out of elements. That is, a loop
|
||||
somehow deals with the elements of a list until the list satisfies
|
||||
@code{null?}. Then, teh algorithm terminates.
|
||||
|
|
@ -3079,7 +3079,7 @@ 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
|
||||
order. The procedure variants with an @code{!} directly modify the
|
||||
pairs which form the list, whereas the other procedures create new
|
||||
pairs. This is why you should be careful when using the side--effecting
|
||||
pairs. This is why you should be careful when using the side-effecting
|
||||
variants.
|
||||
|
||||
@rnindex append
|
||||
|
|
@ -4978,7 +4978,7 @@ a hook with @code{add-hook!} or removed with @code{remove-hook!} or
|
|||
@subsection Hook Examples
|
||||
|
||||
Hook usage is shown by some examples in this section. First, we will
|
||||
define a hook of arity 2---that is, the procedures stored in the hook
|
||||
define a hook of arity 2 --- that is, the procedures stored in the hook
|
||||
will have to accept two arguments.
|
||||
|
||||
@lisp
|
||||
|
|
|
|||
|
|
@ -65,7 +65,7 @@ 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
|
||||
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
|
||||
|
|
@ -432,7 +432,7 @@ Return the source property specified by @var{key} from
|
|||
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
|
||||
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
|
||||
|
|
|
|||
|
|
@ -1,295 +0,0 @@
|
|||
@page
|
||||
@node Utility Functions
|
||||
@chapter General Utility Functions
|
||||
|
||||
@c FIXME::martin: Review me!
|
||||
|
||||
This chapter contains information about procedures which are not cleanly
|
||||
tied to a specific data type. Because of their wide range of
|
||||
applications, they are collected in a @dfn{utlity} chapter.
|
||||
|
||||
@menu
|
||||
* Equality:: When are two values `the same'?
|
||||
* Property Lists:: Managing metainformation about Scheme objects.
|
||||
* Primitive Properties:: A modern low-level interface to object properties.
|
||||
* Sorting:: Sort utility procedures.
|
||||
* Copying:: Copying deep structures.
|
||||
* General Conversion:: Converting objects to strings.
|
||||
@end menu
|
||||
|
||||
|
||||
@node Equality
|
||||
@section Equality
|
||||
|
||||
@c FIXME::martin: Review me!
|
||||
|
||||
@cindex sameness
|
||||
@cindex equality
|
||||
|
||||
Three different kinds of @dfn{sameness} are defined in Scheme.
|
||||
|
||||
@itemize @bullet
|
||||
@item
|
||||
Two values can refer to exactly the same object.
|
||||
|
||||
@item
|
||||
Two objects can have the same @dfn{value}.
|
||||
|
||||
@item
|
||||
Two objects can be structurally equivalent.
|
||||
@end itemize
|
||||
|
||||
The differentiation between these three kinds is important, because
|
||||
determining whether two values are the same objects is very efficient,
|
||||
while determining structural equivalence can be quite expensive
|
||||
(consider comparing two very long lists). Therefore, three different
|
||||
procedures for testing for equality are provided, which correspond to
|
||||
the three kinds of @dfn{sameness} defined above.
|
||||
|
||||
@rnindex eq?
|
||||
@deffn primitive eq? x y
|
||||
Return @code{#t} iff @var{x} references the same object as @var{y}.
|
||||
@code{eq?} is similar to @code{eqv?} except that in some cases it is
|
||||
capable of discerning distinctions finer than those detectable by
|
||||
@code{eqv?}.
|
||||
@end deffn
|
||||
|
||||
@rnindex eqv?
|
||||
@deffn primitive eqv? x y
|
||||
The @code{eqv?} procedure defines a useful equivalence relation on objects.
|
||||
Briefly, it returns @code{#t} if @var{x} and @var{y} should normally be
|
||||
regarded as the same object. This relation is left slightly open to
|
||||
interpretation, but works for comparing immediate integers, characters,
|
||||
and inexact numbers.
|
||||
@end deffn
|
||||
|
||||
@rnindex equal?
|
||||
@deffn primitive equal? x y
|
||||
Return @code{#t} iff @var{x} and @var{y} are recursively @code{eqv?} equivalent.
|
||||
@code{equal?} recursively compares the contents of pairs,
|
||||
vectors, and strings, applying @code{eqv?} on other objects such as
|
||||
numbers and symbols. A rule of thumb is that objects are generally
|
||||
@code{equal?} if they print the same. @code{equal?} may fail to
|
||||
terminate if its arguments are circular data structures.
|
||||
@end deffn
|
||||
|
||||
|
||||
@node Property Lists
|
||||
@section Property Lists
|
||||
|
||||
Every object in the system can have a @dfn{property list} that may
|
||||
be used for information about that object. For example, a
|
||||
function may have a property list that includes information about
|
||||
the source file in which it is defined.
|
||||
|
||||
Property lists are implemented as assq lists (@pxref{Association Lists}).
|
||||
|
||||
Currently, property lists are implemented differently for procedures and
|
||||
closures than for other kinds of objects. Therefore, when manipulating
|
||||
a property list associated with a procedure object, use the
|
||||
@code{procedure} functions; otherwise, use the @code{object} functions.
|
||||
|
||||
@deffn primitive object-properties obj
|
||||
@deffnx primitive procedure-properties obj
|
||||
Return @var{obj}'s property list.
|
||||
@end deffn
|
||||
|
||||
@deffn primitive set-object-properties! obj alist
|
||||
@deffnx primitive set-procedure-properties! obj alist
|
||||
Set @var{obj}'s property list to @var{alist}.
|
||||
@end deffn
|
||||
|
||||
@deffn primitive object-property obj key
|
||||
@deffnx primitive procedure-property obj key
|
||||
Return the property of @var{obj} with name @var{key}.
|
||||
@end deffn
|
||||
|
||||
@deffn primitive set-object-property! obj key value
|
||||
@deffnx primitive set-procedure-property! obj key value
|
||||
In @var{obj}'s property list, set the property named @var{key}
|
||||
to @var{value}.
|
||||
@end deffn
|
||||
|
||||
[Interface bug: there should be a second level of interface in which
|
||||
the user provides a "property table" that is possibly private.]
|
||||
|
||||
|
||||
@node Primitive Properties
|
||||
@section Primitive Properties
|
||||
|
||||
@deffn primitive primitive-make-property not_found_proc
|
||||
Create a @dfn{property token} that can be used with
|
||||
@code{primitive-property-ref} and @code{primitive-property-set!}.
|
||||
See @code{primitive-property-ref} for the significance of
|
||||
@var{not_found_proc}.
|
||||
@end deffn
|
||||
|
||||
@deffn primitive primitive-property-ref prop obj
|
||||
Return the property @var{prop} of @var{obj}. When no value
|
||||
has yet been associated with @var{prop} and @var{obj}, call
|
||||
@var{not-found-proc} instead (see @code{primitive-make-property})
|
||||
and use its return value. That value is also associated with
|
||||
@var{obj} via @code{primitive-property-set!}. When
|
||||
@var{not-found-proc} is @code{#f}, use @code{#f} as the
|
||||
default value of @var{prop}.
|
||||
@end deffn
|
||||
|
||||
@deffn primitive primitive-property-set! prop obj val
|
||||
Associate @var{code} with @var{prop} and @var{obj}.
|
||||
@end deffn
|
||||
|
||||
@deffn primitive primitive-property-del! prop obj
|
||||
Remove any value associated with @var{prop} and @var{obj}.
|
||||
@end deffn
|
||||
|
||||
|
||||
@node Sorting
|
||||
@section Sorting
|
||||
|
||||
@c FIXME::martin: Review me!
|
||||
|
||||
@cindex sorting
|
||||
@cindex sorting lists
|
||||
@cindex sorting vectors
|
||||
|
||||
Sorting is very important in computer programs. Therefore, Guile comes
|
||||
with several sorting procedures built--in. As always, procedures with
|
||||
names ending in @code{!} are side--effecting, that means that they may
|
||||
modify their parameters in order to produce their results.
|
||||
|
||||
The first group of procedures can be used to merge two lists (which must
|
||||
be already sorted on their own) and produce sorted lists containing
|
||||
all elements of the input lists.
|
||||
|
||||
@deffn primitive merge alist blist less
|
||||
Take two lists @var{alist} and @var{blist} such that
|
||||
@code{(sorted? alist less?)} and @code{(sorted? blist less?)} and
|
||||
returns a new list in which the elements of @var{alist} and
|
||||
@var{blist} have been stably interleaved so that
|
||||
@code{(sorted? (merge alist blist less?) less?)}.
|
||||
@end deffn
|
||||
|
||||
@deffn primitive merge! alist blist less
|
||||
Takes two lists @var{alist} and @var{blist} such that
|
||||
@code{(sorted? alist less?)} and @code{(sorted? blist less?)} and
|
||||
returns a new list in which the elements of @var{alist} and
|
||||
@var{blist} have been stably interleaved so that
|
||||
@code{(sorted? (merge alist blist less?) less?)}.
|
||||
This is the destructive variant of @code{merge}
|
||||
Note: this does _not_ accept vectors.
|
||||
@end deffn
|
||||
|
||||
The following procedures can operate on sequences which are either
|
||||
vectors or list. According to the given arguments, they return sorted
|
||||
vectors or lists, respectively. The first of the following procedures
|
||||
determines whether a sequence is already sorted, the other sort a given
|
||||
sequence. The variants with names starting with @code{stable-} are
|
||||
special in that they maintain a special property of the input sequences:
|
||||
If two or more elements are the same according to the comparison
|
||||
predicate, they are left in the same order as they appeared in the
|
||||
input.
|
||||
|
||||
@deffn primitive sorted? items less
|
||||
Return @code{#t} iff @var{items} is a list or a vector such that
|
||||
for all 1 <= i <= m, the predicate @var{less} returns true when
|
||||
applied to all elements i - 1 and i
|
||||
@end deffn
|
||||
|
||||
@deffn primitive sort items less
|
||||
Sort the sequence @var{items}, which may be a list or a
|
||||
vector. @var{less} is used for comparing the sequence
|
||||
elements. This is not a stable sort.
|
||||
@end deffn
|
||||
|
||||
@deffn primitive sort! items less
|
||||
Sort the sequence @var{items}, which may be a list or a
|
||||
vector. @var{less} is used for comparing the sequence
|
||||
elements. The sorting is destructive, that means that the
|
||||
input sequence is modified to produce the sorted result.
|
||||
This is not a stable sort.
|
||||
@end deffn
|
||||
|
||||
@deffn primitive stable-sort items less
|
||||
Sort the sequence @var{items}, which may be a list or a
|
||||
vector. @var{less} is used for comparing the sequence elements.
|
||||
This is a stable sort.
|
||||
@end deffn
|
||||
|
||||
@deffn primitive stable-sort! items less
|
||||
Sort the sequence @var{items}, which may be a list or a
|
||||
vector. @var{less} is used for comparing the sequence elements.
|
||||
The sorting is destructive, that means that the input sequence
|
||||
is modified to produce the sorted result.
|
||||
This is a stable sort.
|
||||
@end deffn
|
||||
|
||||
The procedures in the last group only accept lists or vectors as input,
|
||||
as their names indicate.
|
||||
|
||||
@deffn primitive sort-list items less
|
||||
Sort the list @var{items}, using @var{less} for comparing the
|
||||
list elements. This is a stable sort.
|
||||
@end deffn
|
||||
|
||||
@deffn primitive sort-list! items less
|
||||
Sort the list @var{items}, using @var{less} for comparing the
|
||||
list elements. The sorting is destructive, that means that the
|
||||
input list is modified to produce the sorted result.
|
||||
This is a stable sort.
|
||||
@end deffn
|
||||
|
||||
@deffn primitive restricted-vector-sort! vec less startpos endpos
|
||||
Sort the vector @var{vec}, using @var{less} for comparing
|
||||
the vector elements. @var{startpos} and @var{endpos} delimit
|
||||
the range of the vector which gets sorted. The return value
|
||||
is not specified.
|
||||
@end deffn
|
||||
|
||||
|
||||
@node Copying
|
||||
@section Copying Deep Structures
|
||||
|
||||
@c FIXME::martin: Review me!
|
||||
|
||||
The procedures for copying lists (@pxref{Lists}) only produce a flat
|
||||
copy of the input list, and currently Guile does not even contain
|
||||
procedures for copying vectors. @code{copy-tree} can be used for these
|
||||
application, as it does not only copy the spine of a list, but also
|
||||
copies any pairs in the cars of the input lists.
|
||||
|
||||
@deffn primitive copy-tree obj
|
||||
Recursively copy the data tree that is bound to @var{obj}, and return a
|
||||
pointer to the new data structure. @code{copy-tree} recurses down the
|
||||
contents of both pairs and vectors (since both cons cells and vector
|
||||
cells may point to arbitrary objects), and stops recursing when it hits
|
||||
any other object.
|
||||
@end deffn
|
||||
|
||||
|
||||
@node General Conversion
|
||||
@section General String Conversion
|
||||
|
||||
@c FIXME::martin: Review me!
|
||||
|
||||
When debugging Scheme programs, but also for providing a human--friendly
|
||||
interface, a procedure for converting any Scheme object into string
|
||||
format is very useful. Conversion from/to strings can of course be done
|
||||
with specialized procedures when the data type of the object to convert
|
||||
is known, but with this procedure, it is often more comfortable.
|
||||
|
||||
@code{object->string} converts an object by using a print procedure for
|
||||
writing to a string port, and then returning the resulting string.
|
||||
Converting an object back from the string is only possible if the object
|
||||
type has a read syntax and the read syntax is preserved by the printing
|
||||
procedure.
|
||||
|
||||
@deffn primitive object->string obj [printer]
|
||||
Return a Scheme string obtained by printing @var{obj}.
|
||||
Printing function can be specified by the optional second
|
||||
argument @var{printer} (default: @code{write}).
|
||||
@end deffn
|
||||
|
||||
|
||||
@c Local Variables:
|
||||
@c TeX-master: "guile.texi"
|
||||
@c End:
|
||||
|
|
@ -83,6 +83,17 @@ This switch sets the global variable use-emacs-interface to @code{#t}.
|
|||
|
||||
This switch is still experimental.
|
||||
|
||||
@item --use-srfi=@var{list}
|
||||
The option @code{--use-srfi} expects a comma-separated list of numbers,
|
||||
each representing a SRFI number to be loaded into the interpreter
|
||||
before starting evaluating a script file or the REPL. Additionally,
|
||||
the feature identifier for the loaded SRFIs is recognized by
|
||||
`cond-expand' when using this option.
|
||||
|
||||
@example
|
||||
guile --use-srfi=8,13
|
||||
@end example
|
||||
|
||||
@item -h@r{, }--help
|
||||
Display help on invoking Guile, and then exit.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
@page
|
||||
@node SRFI Support
|
||||
@chapter Various SRFI Support Modules
|
||||
|
||||
|
|
@ -5,11 +6,10 @@ SRFI is an acronym for Scheme Request For Implementation. The SRFI
|
|||
documents define a lot of syntactic and procedure extensions to standard
|
||||
Scheme as defined in R5RS.
|
||||
|
||||
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, design rationales and further examples, we
|
||||
advise you to get the relevant SRFI documents from the SRFI home page
|
||||
Guile has support for a number of SRFIs. This chapter gives an overview
|
||||
over the available SRFIs and some usage hints. For complete
|
||||
documentation, design rationales and further examples, we advise you to
|
||||
get the relevant SRFI documents from the SRFI home page
|
||||
@url{http://srfi.schemers.org}.
|
||||
|
||||
@menu
|
||||
|
|
@ -84,6 +84,22 @@ implementation-dependant operations, such as @code{use-modules} in
|
|||
Guile. Thus, it is not necessary to use any module to get access to
|
||||
this form.
|
||||
|
||||
Currently, the feature identifiers @code{guile}, @code{r5rs} and
|
||||
@code{srfi-0} are supported. The other SRFIs are not in that list,
|
||||
because the SRFI modules must be explicitly used before their exported
|
||||
bindings can be used. So if a Scheme program wishes to detect whether
|
||||
SRFI-8 is supported in the running implementation, code similar to this
|
||||
may be needed:
|
||||
|
||||
@lisp
|
||||
(cond-expand
|
||||
(guile
|
||||
(use-modules (srfi srfi-8)))
|
||||
(srfi-8
|
||||
#t))
|
||||
;; otherwise fail.
|
||||
@end lisp
|
||||
|
||||
|
||||
@node SRFI-2
|
||||
@section SRFI-2 - and-let*
|
||||
|
|
@ -1160,7 +1176,7 @@ Return a true value if any character in the character set
|
|||
|
||||
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
|
||||
provide side-effecting variants, which modify their character set
|
||||
argument(s).
|
||||
|
||||
@deffn primitive char-set-adjoin cs char1 @dots{}
|
||||
|
|
@ -1197,7 +1213,7 @@ Return the difference of all argument character sets.
|
|||
|
||||
@deffn primitive char-set-xor cs1 @dots{}
|
||||
@deffnx primitive char-set-xor! cs1 @dots{}
|
||||
Return the exclusive--or of all argument character sets.
|
||||
Return the exclusive-or of all argument character sets.
|
||||
@end deffn
|
||||
|
||||
@deffn primitive char-set-diff+intersection cs1 @dots{}
|
||||
|
|
@ -1216,11 +1232,11 @@ 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.
|
||||
All lower-case characters.
|
||||
@end defvar
|
||||
|
||||
@defvar char-set:upper-case
|
||||
All upper--case characters.
|
||||
All upper-case characters.
|
||||
@end defvar
|
||||
|
||||
@defvar char-set:title-case
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue