mirror of
https://git.savannah.gnu.org/git/guile.git
synced 2025-04-30 03:40:34 +02:00
merge from 1.8 branch
This commit is contained in:
Kevin Ryde
parent
aeb9d8e054
commit
40296bab81
11 changed files with 398 additions and 95 deletions
|
|
@ -1,4 +1,4 @@
|
|||
2006-09-27 Neil Jerram <neil@ossau.uklinux.net>
|
||||
2006-09-28 Neil Jerram <neil@ossau.uklinux.net>
|
||||
|
||||
* goops.texi (Slot Options): Added example from Ludovic Courtès
|
||||
about difference between init-value, -form and -thunk.
|
||||
|
|
|
|||
|
|
@ -18,6 +18,19 @@
|
|||
(Setting and Managing Breakpoints): Update text on how to set
|
||||
breakpoints.
|
||||
|
||||
2006-10-05 Kevin Ryde <user42@zip.com.au>
|
||||
|
||||
* misc-modules.texi (File Tree Walk): Corrections to BASE parameter
|
||||
and symlink vs stale-symlink types in nftw.
|
||||
* misc-modules.texi, guile.texi (Buffered Input): New section,
|
||||
describing (ice-9 buffered-input).
|
||||
|
||||
* posix.texi (User Information): Clarify getpwent returns #f at end of
|
||||
file.
|
||||
|
||||
* repl-modules.texi (Readline Functions): New section on how to call
|
||||
readline from scheme code.
|
||||
|
||||
2006-10-03 Neil Jerram <neil@ossau.uklinux.net>
|
||||
|
||||
* scheme-using.texi (GDS Getting Started): Editorial updates.
|
||||
|
|
@ -39,6 +52,12 @@
|
|||
(GDS Getting Started, How to Use GDS): Merged; editorial updates;
|
||||
subsections reordered.
|
||||
|
||||
2006-09-26 Kevin Ryde <user42@zip.com.au>
|
||||
|
||||
* api-io.texi (Random Access): In truncate-file, tweak wording for
|
||||
clarity, note cannot always extend file this way.
|
||||
(Ports): File access uses LFS.
|
||||
|
||||
2006-09-25 Neil Jerram <neil@ossau.uklinux.net>
|
||||
|
||||
* scheme-using.texi (Error Handling, Interactive Debugger): Minor
|
||||
|
|
@ -51,11 +70,31 @@
|
|||
minor improvements. Removed doc for `trace-finish', which no
|
||||
longer exists.
|
||||
|
||||
2006-09-22 Kevin Ryde <user42@zip.com.au>
|
||||
|
||||
* api-data.texi (Scientific): In sqrt, note it's the positive root
|
||||
which is returned (as per R5RS).
|
||||
|
||||
2006-09-20 Ludovic Courtès <ludovic.courtes@laas.fr>
|
||||
|
||||
* api-data.texi (Standard Character Sets): Documented the
|
||||
charset recomputation upon successful `setlocale'.
|
||||
|
||||
2006-09-08 Kevin Ryde <user42@zip.com.au>
|
||||
|
||||
* misc-modules.texi (Formatted Output): Show ":@" rather than "@:",
|
||||
because ":@" is traditional common lisp, though either way works.
|
||||
Break a couple of example lines to avoid overflowing DVI page width.
|
||||
|
||||
* scheme-debugging.texi (Debug Last Error): Line break in "Type
|
||||
(backtrace) to get ..." which overflowed the line in both info and
|
||||
DVI. Reported by Percy Tiglao.
|
||||
|
||||
2006-09-05 Kevin Ryde <user42@zip.com.au>
|
||||
|
||||
* posix.texi (Network Sockets and Communication): Tweak description,
|
||||
note not multi-threading.
|
||||
|
||||
2006-09-04 Neil Jerram <neil@ossau.uklinux.net>
|
||||
|
||||
* api-control.texi (Dynamic Wind): Doc for scm_dynwind_free.
|
||||
|
|
@ -69,6 +108,11 @@
|
|||
* api-debug.texi (Debug on Error): Added paragraph on need to use
|
||||
debugging evaluator. Added text on what the Guile REPL code does.
|
||||
|
||||
2006-08-29 Kevin Ryde <user42@zip.com.au>
|
||||
|
||||
* api-control.texi (Dynamic Wind): Reformat example a bit to avoid
|
||||
going off the right edge of the paper. Reported by Percy Tiglao.
|
||||
|
||||
2006-08-28 Neil Jerram <neil@ossau.uklinux.net>
|
||||
|
||||
* api-debug.texi (Examining the Stack): Minor improvements to
|
||||
|
|
@ -87,6 +131,11 @@
|
|||
(GDS Introduction): New node, containing GDS-specific introductory
|
||||
text.
|
||||
|
||||
2006-08-22 Kevin Ryde <user42@zip.com.au>
|
||||
|
||||
* api-i18n.texi (Internationalization): Cross reference gettext manual
|
||||
on plural forms.
|
||||
|
||||
2006-08-18 Neil Jerram <neil@ossau.uklinux.net>
|
||||
|
||||
* scheme-using.texi (Using Guile in Emacs): Unignore extra GDS
|
||||
|
|
@ -142,6 +191,17 @@
|
|||
* Makefile.am (guile_TEXINFOS): Include new scheme-using.texi
|
||||
file.
|
||||
|
||||
2006-07-24 Kevin Ryde <user42@zip.com.au>
|
||||
|
||||
* api-evaluation.texi (Fly Evaluation): Add scm_c_eval_string.
|
||||
(Loading): Add scm_c_primitive_load.
|
||||
Reported by Jon Wilson.
|
||||
|
||||
2006-06-25 Kevin Ryde <user42@zip.com.au>
|
||||
|
||||
* posix.texi (Time): In tm:gmtoff, give example values, note not the
|
||||
same as C tm_gmtoff.
|
||||
|
||||
2006-06-16 Ludovic Courtès <ludovic.courtes@laas.fr>
|
||||
|
||||
* api-utility.texi (Equality): Mentioned the behavior of `equal?'
|
||||
|
|
|
|||
|
|
@ -1234,28 +1234,29 @@ non-locally, @var{out_guard} is called. If the dynamic extent of
|
|||
the dynamic-wind is re-entered, @var{in_guard} is called. Thus
|
||||
@var{in_guard} and @var{out_guard} may be called any number of
|
||||
times.
|
||||
|
||||
@lisp
|
||||
(define x 'normal-binding)
|
||||
@result{} x
|
||||
(define a-cont (call-with-current-continuation
|
||||
(lambda (escape)
|
||||
(let ((old-x x))
|
||||
(dynamic-wind
|
||||
;; in-guard:
|
||||
;;
|
||||
(lambda () (set! x 'special-binding))
|
||||
(define a-cont
|
||||
(call-with-current-continuation
|
||||
(lambda (escape)
|
||||
(let ((old-x x))
|
||||
(dynamic-wind
|
||||
;; in-guard:
|
||||
;;
|
||||
(lambda () (set! x 'special-binding))
|
||||
|
||||
;; thunk
|
||||
;;
|
||||
(lambda () (display x) (newline)
|
||||
(call-with-current-continuation escape)
|
||||
(display x) (newline)
|
||||
x)
|
||||
|
||||
;; out-guard:
|
||||
;;
|
||||
(lambda () (set! x old-x)))))))
|
||||
;; thunk
|
||||
;;
|
||||
(lambda () (display x) (newline)
|
||||
(call-with-current-continuation escape)
|
||||
(display x) (newline)
|
||||
x)
|
||||
|
||||
;; out-guard:
|
||||
;;
|
||||
(lambda () (set! x old-x)))))))
|
||||
;; Prints:
|
||||
special-binding
|
||||
;; Evaluates to:
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
@c -*-texinfo-*-
|
||||
@c This is part of the GNU Guile Reference Manual.
|
||||
@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
|
||||
@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006
|
||||
@c Free Software Foundation, Inc.
|
||||
@c See the file guile.texi for copying conditions.
|
||||
|
||||
|
|
@ -1214,7 +1214,16 @@ including complex numbers.
|
|||
@rnindex sqrt
|
||||
@c begin (texi-doc-string "guile" "sqrt")
|
||||
@deffn {Scheme Procedure} sqrt z
|
||||
Return the square root of @var{z}.
|
||||
Return the square root of @var{z}. Of the two possible roots
|
||||
(positive and negative), the one with the a positive real part is
|
||||
returned, or if that's zero then a positive imaginary part. Thus,
|
||||
|
||||
@example
|
||||
(sqrt 9.0) @result{} 3.0
|
||||
(sqrt -9.0) @result{} 0.0+3.0i
|
||||
(sqrt 1.0+1.0i) @result{} 1.09868411346781+0.455089860562227i
|
||||
(sqrt -1.0-1.0i) @result{} 0.455089860562227-1.09868411346781i
|
||||
@end example
|
||||
@end deffn
|
||||
|
||||
@rnindex expt
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
@c -*-texinfo-*-
|
||||
@c This is part of the GNU Guile Reference Manual.
|
||||
@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
|
||||
@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006
|
||||
@c Free Software Foundation, Inc.
|
||||
@c See the file guile.texi for copying conditions.
|
||||
|
||||
|
|
@ -357,6 +357,11 @@ While the code is evaluated, the given module is made the current one.
|
|||
The current module is restored when this procedure returns.
|
||||
@end deffn
|
||||
|
||||
@deftypefn {C Function} SCM scm_c_eval_string (const char *string)
|
||||
@code{scm_eval_string}, but taking a C string instead of an
|
||||
@code{SCM}.
|
||||
@end deftypefn
|
||||
|
||||
@deffn {Scheme Procedure} apply proc arg1 @dots{} argN arglst
|
||||
@deffnx {C Function} scm_apply_0 (proc, arglst)
|
||||
@deffnx {C Function} scm_apply_1 (proc, arg1, arglst)
|
||||
|
|
@ -446,6 +451,11 @@ that will be called before any code is loaded. See the
|
|||
documentation for @code{%load-hook} later in this section.
|
||||
@end deffn
|
||||
|
||||
@deftypefn {C Function} SCM scm_c_primitive_load (const char *filename)
|
||||
@code{scm_primitive_load}, but taking a C string instead of an
|
||||
@code{SCM}.
|
||||
@end deftypefn
|
||||
|
||||
@deffn {Scheme Procedure} primitive-load-path filename
|
||||
@deffnx {C Function} scm_primitive_load_path (filename)
|
||||
Search @code{%load-path} for the file named @var{filename} and
|
||||
|
|
|
|||
|
|
@ -85,7 +85,8 @@ example,
|
|||
It's important to use @code{ngettext} rather than plain @code{gettext}
|
||||
for plurals, since the rules for singular and plural forms in English
|
||||
are not the same in other languages. Only @code{ngettext} will allow
|
||||
translators to give correct forms.
|
||||
translators to give correct forms (@pxref{Plural forms,, Additional
|
||||
functions for plural forms, gettext, GNU @code{gettext} utilities}).
|
||||
@end deffn
|
||||
|
||||
@deffn {Scheme Procedure} textdomain [domain]
|
||||
|
|
|
|||
|
|
@ -64,6 +64,10 @@ rely on that to keep it away from system limits. An explicit call to
|
|||
If program flow makes it hard to be certain when to close then this
|
||||
may be an acceptable way to control resource usage.
|
||||
|
||||
All file access uses the ``LFS'' large file support functions when
|
||||
available, so files bigger than 2 Gbytes (@math{2^31} bytes) can be
|
||||
read and written on a 32-bit system.
|
||||
|
||||
@rnindex input-port?
|
||||
@deffn {Scheme Procedure} input-port? x
|
||||
@deffnx {C Function} scm_input_port_p (x)
|
||||
|
|
@ -390,14 +394,18 @@ Return an integer representing the current position of
|
|||
|
||||
@findex truncate
|
||||
@findex ftruncate
|
||||
@deffn {Scheme Procedure} truncate-file object [length]
|
||||
@deffnx {C Function} scm_truncate_file (object, length)
|
||||
Truncates the object referred to by @var{object} to at most
|
||||
@var{length} bytes. @var{object} can be a string containing a
|
||||
file name or an integer file descriptor or a port.
|
||||
@var{length} may be omitted if @var{object} is not a file name,
|
||||
in which case the truncation occurs at the current port
|
||||
position. The return value is unspecified.
|
||||
@deffn {Scheme Procedure} truncate-file file [length]
|
||||
@deffnx {C Function} scm_truncate_file (file, length)
|
||||
Truncate @var{file} to @var{length} bytes. @var{file} can be a
|
||||
filename string, a port object, or an integer file descriptor. The
|
||||
return value is unspecified.
|
||||
|
||||
For a port or file descriptor @var{length} can be omitted, in which
|
||||
case the file is truncated at the current position (per @code{ftell}
|
||||
above).
|
||||
|
||||
On most systems a file can be extended by giving a length greater than
|
||||
the current size, but this is not mandatory in the POSIX standard.
|
||||
@end deffn
|
||||
|
||||
@node Line/Delimited
|
||||
|
|
|
|||
|
|
@ -137,7 +137,7 @@ x
|
|||
@comment The title is printed in a large font.
|
||||
@title Guile Reference Manual
|
||||
@subtitle Edition @value{MANUAL-EDITION}, for use with Guile @value{VERSION}
|
||||
@c @subtitle $Id: guile.texi,v 1.46 2006-08-01 21:51:12 ossau Exp $
|
||||
@c @subtitle $Id: guile.texi,v 1.47 2006-10-09 22:45:02 kryde Exp $
|
||||
|
||||
@c See preface.texi for the list of authors
|
||||
@author The Guile Developers
|
||||
|
|
@ -347,6 +347,7 @@ available through both Scheme and C interfaces.
|
|||
* File Tree Walk:: Traversing the file system.
|
||||
* Queues:: First-in first-out queuing.
|
||||
* Streams:: Sequences of values.
|
||||
* Buffered Input:: Ports made from a reader function.
|
||||
* Expect:: Controlling interactive programs with Guile.
|
||||
* The Scheme shell (scsh):: Using scsh interfaces in Guile.
|
||||
@end menu
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
@c -*-texinfo-*-
|
||||
@c This is part of the GNU Guile Reference Manual.
|
||||
@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004
|
||||
@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006
|
||||
@c Free Software Foundation, Inc.
|
||||
@c See the file guile.texi for copying conditions.
|
||||
|
||||
|
|
@ -270,13 +270,13 @@ With no parameters output is in words as a cardinal like ``ten'', or
|
|||
@end example
|
||||
|
||||
And also with no parameters, @nicode{~@@r} gives roman numerals and
|
||||
@nicode{~@@:r} gives old roman numerals. In old roman numerals
|
||||
@nicode{~:@@r} gives old roman numerals. In old roman numerals
|
||||
there's no ``subtraction'', so 9 is @nicode{VIIII} instead of
|
||||
@nicode{IX}. In both cases only positive numbers can be output.
|
||||
|
||||
@example
|
||||
(format #t "~@@r" 89) @print{} LXXXIX ;; roman
|
||||
(format #t "~@@:r" 89) @print{} LXXXVIIII ;; old roman
|
||||
(format #t "~:@@r" 89) @print{} LXXXVIIII ;; old roman
|
||||
@end example
|
||||
|
||||
When a parameter is given it means numeric output in the specified
|
||||
|
|
@ -507,7 +507,7 @@ puts the padding after the sign.
|
|||
@example
|
||||
(format #f "~,,8$" -1.5) @result{} " -1.50"
|
||||
(format #f "~,,8:$" -1.5) @result{} "- 1.50"
|
||||
(format #f "~,,8,'.@@:$" 3) @result{} "+...3.00"
|
||||
(format #f "~,,8,'.:@@$" 3) @result{} "+...3.00"
|
||||
@end example
|
||||
|
||||
Note that floating point for dollar amounts is generally not a good
|
||||
|
|
@ -567,7 +567,7 @@ one, which can be convenient when printing some sort of count.
|
|||
|
||||
@example
|
||||
(format #t "~d cat~:p" 9) @print{} 9 cats
|
||||
(format #t "~d pupp~@@:p" 5) @print{} 5 puppies
|
||||
(format #t "~d pupp~:@@p" 5) @print{} 5 puppies
|
||||
@end example
|
||||
|
||||
@nicode{~p} is designed for English plurals and there's no attempt to
|
||||
|
|
@ -777,14 +777,14 @@ The modifiers on @nicode{~(} control the conversion.
|
|||
@c rest lower case.
|
||||
@c
|
||||
@item
|
||||
@nicode{~@@:(} --- upper case.
|
||||
@nicode{~:@@(} --- upper case.
|
||||
@end itemize
|
||||
|
||||
For example,
|
||||
|
||||
@example
|
||||
(format #t "~(Hello~)") @print{} hello
|
||||
(format #t "~@@:(Hello~)") @print{} HELLO
|
||||
(format #t "~:@@(Hello~)") @print{} HELLO
|
||||
@end example
|
||||
|
||||
In the future it's intended the modifiers @nicode{:} and @nicode{@@}
|
||||
|
|
@ -813,8 +813,10 @@ elements from it. This is a convenient way to output a whole list.
|
|||
@nicode{~:@{} takes a single argument which is a list of lists, each
|
||||
of those contained lists gives the arguments for the iterated format.
|
||||
|
||||
@c @print{} on a new line here to avoid overflowing page width in DVI
|
||||
@example
|
||||
(format #t "~:@{~dx~d ~@}" '((1 2) (3 4) (5 6))) @print{} 1x2 3x4 5x6
|
||||
(format #t "~:@{~dx~d ~@}" '((1 2) (3 4) (5 6)))
|
||||
@print{} 1x2 3x4 5x6
|
||||
@end example
|
||||
|
||||
@nicode{~@@@{} takes arguments directly, with each iteration
|
||||
|
|
@ -825,11 +827,13 @@ successively consuming arguments.
|
|||
(format #t "~@@@{~s=~d ~@}" "x" 1 "y" 2) @print{} "x"=1 "y"=2
|
||||
@end example
|
||||
|
||||
@nicode{~@@:@{} takes list arguments, one argument for each iteration,
|
||||
@nicode{~:@@@{} takes list arguments, one argument for each iteration,
|
||||
using that list for the format.
|
||||
|
||||
@c @print{} on a new line here to avoid overflowing page width in DVI
|
||||
@example
|
||||
(format #t "~@@:@{~dx~d ~@}" '(1 2) '(3 4) '(5 6)) @print{} 1x2 3x4 5x6
|
||||
(format #t "~:@@@{~dx~d ~@}" '(1 2) '(3 4) '(5 6))
|
||||
@print{} 1x2 3x4 5x6
|
||||
@end example
|
||||
|
||||
Iterating stops when there are no more arguments or when the
|
||||
|
|
@ -1094,27 +1098,28 @@ Walk the filesystem tree starting at @var{startname}, calling
|
|||
@var{proc} for each file and directory. @code{nftw} has extra
|
||||
features over the basic @code{ftw} described above.
|
||||
|
||||
Hard links and symbolic links are followed, but a file or directory is
|
||||
reported to @var{proc} only once, and skipped if seen again in another
|
||||
place. One consequence of this is that @code{nftw} is safe against
|
||||
circular linked directory structures.
|
||||
Like @code{ftw}, hard links and symbolic links are followed. A file
|
||||
or directory is reported to @var{proc} only once, and skipped if seen
|
||||
again in another place. One consequence of this is that @code{nftw}
|
||||
is safe against circular linked directory structures.
|
||||
|
||||
Each @var{proc} call is @code{(@var{proc} filename statinfo flag
|
||||
basename level)} and it should return @code{#t} to continue, or any
|
||||
base level)} and it should return @code{#t} to continue, or any
|
||||
other value to stop.
|
||||
|
||||
@var{filename} is the item visited, being @var{startname} plus a
|
||||
further path and the name of the item. @var{statinfo} is the return
|
||||
from @code{stat} on @var{filename} (@pxref{File System}).
|
||||
@var{basename} it the item name without any path. @var{level} is an
|
||||
integer giving the directory nesting level, starting from 0 for the
|
||||
contents of @var{startname} (or that item itself if it's a file).
|
||||
@var{flag} is one of the following symbols,
|
||||
from @code{stat} on @var{filename} (@pxref{File System}). @var{base}
|
||||
is an integer offset into @var{filename} which is where the basename
|
||||
for this item begins. @var{level} is an integer giving the directory
|
||||
nesting level, starting from 0 for the contents of @var{startname} (or
|
||||
that item itself if it's a file). @var{flag} is one of the following
|
||||
symbols,
|
||||
|
||||
@table @code
|
||||
@item regular
|
||||
@var{filename} is a file, this includes special files like devices,
|
||||
named pipes, etc.
|
||||
@var{filename} is a file, including special files like devices, named
|
||||
pipes, etc.
|
||||
|
||||
@item directory
|
||||
@var{filename} is a directory.
|
||||
|
|
@ -1132,19 +1137,15 @@ nothing is known about it. @var{statinfo} is @code{#f} in this case.
|
|||
@var{filename} is a directory, but one which cannot be read and hence
|
||||
won't be recursed into.
|
||||
|
||||
@item symlink
|
||||
@var{filename} is a dangling symbolic link. Symbolic links are
|
||||
normally followed and their target reported, the link itself is
|
||||
reported if the target does not exist.
|
||||
|
||||
Under the @code{physical} option described below, @code{symlink} is
|
||||
instead given for symbolic links whose target does exist.
|
||||
|
||||
@item stale-symlink
|
||||
Under the @code{physical} option described below, this indicates
|
||||
@var{filename} is a dangling symbolic link, meaning its target does
|
||||
not exist. Without the @code{physical} option plain @code{symlink}
|
||||
indicates this.
|
||||
@var{filename} is a dangling symbolic link. Links are normally
|
||||
followed and their target reported, the link itself is reported if its
|
||||
target does not exist.
|
||||
|
||||
@item symlink
|
||||
When the @code{physical} option described below is used, this
|
||||
indicates @var{filename} is a symbolic link whose target exists (and
|
||||
is not being followed).
|
||||
@end table
|
||||
|
||||
The following optional arguments can be given to modify the way
|
||||
|
|
@ -1156,10 +1157,11 @@ takes a following integer value).
|
|||
Change to the directory containing the item before calling @var{proc}.
|
||||
When @code{nftw} returns the original current directory is restored.
|
||||
|
||||
Under this option, generally the @var{basename} parameter should be
|
||||
used to access the item in each @var{proc} call. The @var{filename}
|
||||
parameter still has a path as normal and this will only be valid if
|
||||
the @var{startname} directory was absolute.
|
||||
Under this option, generally the @var{base} parameter to each
|
||||
@var{proc} call should be used to pick out the base part of the
|
||||
@var{filename}. The @var{filename} is still a path but with a changed
|
||||
directory it won't be valid (unless the @var{startname} directory was
|
||||
absolute).
|
||||
|
||||
@item @code{depth}
|
||||
Visit files ``depth first'', meaning @var{proc} is called for the
|
||||
|
|
@ -1175,11 +1177,12 @@ Set the size of the hash table used to track items already visited.
|
|||
|
||||
@item @code{mount}
|
||||
Don't cross a mount point, meaning only visit items on the same
|
||||
filesystem as @var{startname}. (Ie.@: the same @code{stat:dev}.)
|
||||
filesystem as @var{startname} (ie.@: the same @code{stat:dev}).
|
||||
|
||||
@item @code{physical}
|
||||
Don't follow symbolic links, instead report them to @var{proc} as
|
||||
@code{symlink}, and report dangling links as @code{stale-symlink}.
|
||||
@code{symlink}. Dangling links (those whose target doesn't exist) are
|
||||
still reported as @code{stale-symlink}.
|
||||
@end table
|
||||
|
||||
The return value from @code{nftw} is @code{#t} if it ran to
|
||||
|
|
@ -1461,6 +1464,69 @@ ends when the end of the shortest given @var{stream} is reached.
|
|||
@end defun
|
||||
|
||||
|
||||
@node Buffered Input
|
||||
@section Buffered Input
|
||||
@cindex Buffered input
|
||||
@cindex Line continuation
|
||||
|
||||
The following functions are provided by
|
||||
|
||||
@example
|
||||
(use-modules (ice-9 buffered-input))
|
||||
@end example
|
||||
|
||||
A buffered input port allows a reader function to return chunks of
|
||||
characters which are to be handed out on reading the port. A notion
|
||||
of further input for an application level logical expression is
|
||||
maintained too, and passed through to the reader.
|
||||
|
||||
@defun make-buffered-input-port reader
|
||||
Create an input port which returns characters obtained from the given
|
||||
@var{reader} function. @var{reader} is called (@var{reader} cont),
|
||||
and should return a string or an EOF object.
|
||||
|
||||
The new port gives precisely the characters returned by @var{reader},
|
||||
nothing is added, so if any newline characters or other separators are
|
||||
desired they must come from the reader function.
|
||||
|
||||
The @var{cont} parameter to @var{reader} is @code{#f} for initial
|
||||
input, or @code{#t} when continuing an expression. This is an
|
||||
application level notion, set with
|
||||
@code{set-buffered-input-continuation?!} below. If the user has
|
||||
entered a partial expression then it allows @var{reader} for instance
|
||||
to give a different prompt to show more is required.
|
||||
@end defun
|
||||
|
||||
@defun make-line-buffered-input-port reader
|
||||
@cindex Line buffered input
|
||||
Create an input port which returns characters obtained from the
|
||||
specified @var{reader} function, similar to
|
||||
@code{make-buffered-input-port} above, but where @var{reader} is
|
||||
expected to be a line-oriented.
|
||||
|
||||
@var{reader} is called (@var{reader} cont), and should return a string
|
||||
or an EOF object as above. Each string is a line of input without a
|
||||
newline character, the port code inserts a newline after each string.
|
||||
@end defun
|
||||
|
||||
@defun set-buffered-input-continuation?! port cont
|
||||
Set the input continuation flag for a given buffered input
|
||||
@var{port}.
|
||||
|
||||
An application uses this by calling with a @var{cont} flag of
|
||||
@code{#f} when beginning to read a new logical expression. For
|
||||
example with the Scheme @code{read} function (@pxref{Scheme Read}),
|
||||
|
||||
@example
|
||||
(define my-port (make-buffered-input-port my-reader))
|
||||
|
||||
(set-buffered-input-continuation?! my-port #f)
|
||||
(let ((obj (read my-port)))
|
||||
...
|
||||
@end example
|
||||
@end defun
|
||||
|
||||
|
||||
@c Local Variables:
|
||||
@c TeX-master: "guile.texi"
|
||||
@c End:
|
||||
|
|
|
|||
|
|
@ -1008,8 +1008,8 @@ return value is unspecified.
|
|||
@end deffn
|
||||
|
||||
@deffn {Scheme Procedure} getpwent
|
||||
Return the next entry in the user database, using the stream set by
|
||||
@code{setpwent}.
|
||||
Read the next entry in the user database stream. The return is a
|
||||
passwd user object as above, or @code{#f} when no more entries.
|
||||
@end deffn
|
||||
|
||||
@deffn {Scheme Procedure} endpwent
|
||||
|
|
@ -1170,6 +1170,13 @@ Daylight saving indicator (0 for ``no'', greater than 0 for ``yes'', less than
|
|||
@deffn {Scheme Procedure} tm:gmtoff tm
|
||||
@deffnx {Scheme Procedure} set-tm:gmtoff tm val
|
||||
Time zone offset in seconds west of @acronym{UTC} (-46800 to 43200).
|
||||
For example on East coast USA (zone @samp{EST+5}) this would be 18000
|
||||
(ie.@: @m{5\times60\times60,5*60*60}) in winter, or 14400
|
||||
(ie.@: @m{4\times60\times60,4*60*60}) during daylight savings.
|
||||
|
||||
Note @code{tm:gmtoff} is not the same as @code{tm_gmtoff} in the C
|
||||
@code{tm} structure. @code{tm_gmtoff} is seconds east and hence the
|
||||
negative of the value here.
|
||||
@end deffn
|
||||
@deffn {Scheme Procedure} tm:zone tm
|
||||
@deffnx {Scheme Procedure} set-tm:zone tm val
|
||||
|
|
@ -2909,32 +2916,37 @@ any unflushed buffered port data is ignored.
|
|||
|
||||
@deffn {Scheme Procedure} recvfrom! sock str [flags [start [end]]]
|
||||
@deffnx {C Function} scm_recvfrom (sock, str, flags, start, end)
|
||||
Return data from the socket port @var{sock} and also
|
||||
information about where the data was received from.
|
||||
@var{sock} must already be bound to the address from which
|
||||
data is to be received. @code{str}, is a string into which the
|
||||
data will be written. The size of @var{str} limits the amount
|
||||
of data which can be received: in the case of packet protocols,
|
||||
if a packet larger than this limit is encountered then some
|
||||
data will be irrevocably lost.
|
||||
Receive data from socket port @var{sock}, returning the originating
|
||||
address as well as the data. This function is usually for datagram
|
||||
sockets, but can be used on stream-oriented sockets too.
|
||||
|
||||
The data received is stored in the given @var{str}, the whole string
|
||||
or just the region between the optional @var{start} and @var{end}
|
||||
positions. The size of @var{str} limits the amount of data which can
|
||||
be received. For datagram protocols if a packet larger than this is
|
||||
received then excess bytes are irrevocably lost.
|
||||
|
||||
The return value is a pair. The @code{car} is the number of bytes
|
||||
read. The @code{cdr} is a socket address object (@pxref{Network
|
||||
Socket Address}) which is where the data came from, or @code{#f} if
|
||||
the origin is unknown.
|
||||
|
||||
@vindex MSG_OOB
|
||||
@vindex MSG_PEEK
|
||||
@vindex MSG_DONTROUTE
|
||||
The optional @var{flags} argument is a value or bitwise OR of
|
||||
@code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
|
||||
The optional @var{flags} argument is a or bitwise-OR (@code{logior})
|
||||
of @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
|
||||
|
||||
The value returned is a pair: the @acronym{CAR} is the number of
|
||||
bytes read from the socket and the @acronym{CDR} an address object
|
||||
in the same form as returned by @code{accept}. The address
|
||||
will given as @code{#f} if not available, as is usually the
|
||||
case for stream sockets.
|
||||
Data is read directly from the socket file descriptor, any buffered
|
||||
port data is ignored.
|
||||
|
||||
The @var{start} and @var{end} arguments specify a substring of
|
||||
@var{str} to which the data should be written.
|
||||
|
||||
Note that the data is read directly from the socket file
|
||||
descriptor: any unread buffered port data is ignored.
|
||||
@c This was linux kernel 2.6.15 and glibc 2.3.6, not sure what any
|
||||
@c specs are supposed to say about recvfrom threading.
|
||||
@c
|
||||
On a GNU/Linux system @code{recvfrom!} is not multi-threading, all
|
||||
threads stop while a @code{recvfrom!} call is in progress. An
|
||||
application may need to use @code{select}, @code{O_NONBLOCK} or
|
||||
@code{MSG_DONTWAIT} to avoid this.
|
||||
@end deffn
|
||||
|
||||
@deffn {Scheme Procedure} sendto sock message sockaddr [flags]
|
||||
|
|
|
|||
|
|
@ -23,6 +23,7 @@ history entries.
|
|||
@menu
|
||||
* Loading Readline Support:: How to load readline support into Guile.
|
||||
* Readline Options:: How to modify readline's behaviour.
|
||||
* Readline Functions:: Programming with readline.
|
||||
@end menu
|
||||
|
||||
|
||||
|
|
@ -32,7 +33,6 @@ 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:
|
||||
|
||||
@findex activate-readline
|
||||
@lisp
|
||||
(use-modules (ice-9 readline))
|
||||
(activate-readline)
|
||||
|
|
@ -91,7 +91,7 @@ $endif
|
|||
The readline interface module can be configured in several ways to
|
||||
better suit the user's needs. Configuration is done via the readline
|
||||
module's options interface, in a similar way to the evaluator and
|
||||
debugging options (@pxref{User level options interfaces}.)
|
||||
debugging options (@pxref{Runtime Options}).
|
||||
|
||||
@findex readline-options
|
||||
@findex readline-enable
|
||||
|
|
@ -119,6 +119,141 @@ usage of the history file using the following call.
|
|||
The readline options interface can only be used @emph{after} loading
|
||||
the readline module, because it is defined in that module.
|
||||
|
||||
@node Readline Functions
|
||||
@subsection Readline Functions
|
||||
|
||||
The following functions are provided by
|
||||
|
||||
@example
|
||||
(use-modules (ice-9 readline))
|
||||
@end example
|
||||
|
||||
There are two ways to use readline from Scheme code, either make calls
|
||||
to @code{readline} directly to get line by line input, or use the
|
||||
readline port below with all the usual reading functions.
|
||||
|
||||
@defun readline [prompt]
|
||||
Read a line of input from the user and return it as a string (without
|
||||
a newline at the end). @var{prompt} is the prompt to show, or the
|
||||
default is the string set in @code{set-readline-prompt!} below.
|
||||
|
||||
@example
|
||||
(readline "Type something: ") @result{} "hello"
|
||||
@end example
|
||||
@end defun
|
||||
|
||||
@defun set-readline-input-port! port
|
||||
@defunx set-readline-output-port! port
|
||||
Set the input and output port the readline function should read from
|
||||
and write to. @var{port} must be a file port (@pxref{File Ports}),
|
||||
and should usually be a terminal.
|
||||
|
||||
The default is the @code{current-input-port} and
|
||||
@code{current-output-port} (@pxref{Default Ports}) when @code{(ice-9
|
||||
readline)} loads, which in an interactive user session means the Unix
|
||||
``standard input'' and ``standard output''.
|
||||
@end defun
|
||||
|
||||
@subsubsection Readline Port
|
||||
|
||||
@defun readline-port
|
||||
Return a buffered input port (@pxref{Buffered Input}) which calls the
|
||||
@code{readline} function above to get input. This port can be used
|
||||
with all the usual reading functions (@code{read}, @code{read-char},
|
||||
etc), and the user gets the interactive editing features of readline.
|
||||
|
||||
There's only a single readline port created. @code{readline-port}
|
||||
creates it when first called, and on subsequent calls just returns
|
||||
what it previously made.
|
||||
@end defun
|
||||
|
||||
@defun activate-readline
|
||||
If the @code{current-input-port} is a terminal (@pxref{Terminals and
|
||||
Ptys,, @code{isatty?}}) then enable readline for all reading from
|
||||
@code{current-input-port} (@pxref{Default Ports}) and enable readline
|
||||
features in the interactive REPL (@pxref{The REPL}).
|
||||
|
||||
@example
|
||||
(activate-readline)
|
||||
(read-char)
|
||||
@end example
|
||||
|
||||
@code{activate-readline} enables readline on @code{current-input-port}
|
||||
simply by a @code{set-current-input-port} to the @code{readline-port}
|
||||
above. An application can do that directly if the extra REPL features
|
||||
that @code{activate-readline} adds are not wanted.
|
||||
@end defun
|
||||
|
||||
@defun set-readline-prompt! prompt1 [prompt2]
|
||||
Set the prompt string to print when reading input. This is used when
|
||||
reading through @code{readline-port}, and is also the default prompt
|
||||
for the @code{readline} function above.
|
||||
|
||||
@var{prompt1} is the initial prompt shown. If a user might enter an
|
||||
expression across multiple lines, then @var{prompt2} is a different
|
||||
prompt to show further input required. In the Guile REPL for instance
|
||||
this is an ellipsis (@samp{...}).
|
||||
|
||||
See @code{set-buffered-input-continuation?!} (@pxref{Buffered Input})
|
||||
for an application to indicate the boundaries of logical expressions
|
||||
(assuming of course an application has such a notion).
|
||||
@end defun
|
||||
|
||||
@subsubsection Completion
|
||||
|
||||
@defun with-readline-completion-function completer thunk
|
||||
Call @code{(@var{thunk})} with @var{completer} as the readline tab
|
||||
completion function to be used in any readline calls within that
|
||||
@var{thunk}. @var{completer} can be @code{#f} for no completion.
|
||||
|
||||
@var{completer} will be called as @code{(@var{completer} text state)},
|
||||
as described in (@pxref{How Completing Works,,, readline, GNU Readline
|
||||
Library}). @var{text} is a partial word to be completed, and each
|
||||
@var{completer} call should return a possible completion string or
|
||||
@code{#f} when no more. @var{state} is @code{#f} for the first call
|
||||
asking about a new @var{text} then @code{#t} while getting further
|
||||
completions of that @var{text}.
|
||||
|
||||
Here's an example @var{completer} for user login names from the
|
||||
password file (@pxref{User Information}), much like readline's own
|
||||
@code{rl_username_completion_function},
|
||||
|
||||
@example
|
||||
(define (username-completer-function text state)
|
||||
(if (not state)
|
||||
(setpwent)) ;; new, go to start of database
|
||||
(let more ((pw (getpwent)))
|
||||
(if pw
|
||||
(if (string-prefix? text (passwd:name pw))
|
||||
(passwd:name pw) ;; this name matches, return it
|
||||
(more (getpwent))) ;; doesn't match, look at next
|
||||
(begin
|
||||
;; end of database, close it and return #f
|
||||
(endpwent)
|
||||
#f))))
|
||||
@end example
|
||||
@end defun
|
||||
|
||||
@defun apropos-completion-function text state
|
||||
A completion function offering completions for Guile functions and
|
||||
variables (all @code{define}s). This is the default completion
|
||||
function.
|
||||
@c
|
||||
@c FIXME: Cross reference the ``apropos'' stuff when it's documented.
|
||||
@c
|
||||
@end defun
|
||||
|
||||
@defun filename-completion-function text state
|
||||
A completion function offering filename completions. This is
|
||||
readline's @code{rl_filename_completion_function} (@pxref{Completion
|
||||
Functions,,, readline, GNU Readline Library}).
|
||||
@end defun
|
||||
|
||||
@defun make-completion-function string-list
|
||||
Return a completion function which offers completions from the
|
||||
possibilities in @var{string-list}. Matching is case-sensitive.
|
||||
@end defun
|
||||
|
||||
|
||||
@page
|
||||
@node Value History
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue