@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2009, 2010, 2011
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2009,
+@c 2010, 2011, 2012 Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@node Pretty Printing
@deffn {Scheme Procedure} truncated-print obj [port] [keyword-options]
Print @var{obj}, truncating the output, if necessary, to make it fit
-into @var{width} characters. By default, @var{x} will be printed using
+into @var{width} characters. By default, @var{obj} will be printed using
@code{write}, though that behavior can be overridden via the
@var{display?} keyword argument.
The default behaviour is to print depth-first, meaning that the entire
-remaining width will be available to each sub-expression of @var{x} --
-e.g., if @var{x} is a vector, each member of @var{x}. One can attempt to
+remaining width will be available to each sub-expression of @var{obj} --
+e.g., if @var{obj} is a vector, each member of @var{obj}. One can attempt to
``ration'' the available width, trying to allocate it equally to each
sub-expression, via the @var{breadth-first?} keyword argument.
instead of @nicode{%}, and are more powerful.
@sp 1
-@deffn {Scheme Procedure} format dest fmt [args@dots{}]
+@deffn {Scheme Procedure} format dest fmt arg @dots{}
Write output specified by the @var{fmt} string to @var{dest}.
@var{dest} can be an output port, @code{#t} for
@code{current-output-port} (@pxref{Default Ports}), or @code{#f} to
@var{commawidth}.
Output an integer argument as a decimal, hexadecimal, octal or binary
-integer (respectively).
+integer (respectively), in a locale-independent way.
@example
(format #t "~d" 123) @print{} 123
@end example
@nicode{~:d} adds commas (or the @var{commachar} parameter) every
-three digits (or the @var{commawidth} parameter many).
+three digits (or the @var{commawidth} parameter many). However, when
+your intent is to write numbers in a way that follows typographical
+conventions, using @nicode{~h} is recommended.
@example
(format #t "~:d" 1234567) @print{} 1,234,567
(format #t "~5,,,'xf" 12345) @print{} xxxxx
@end example
+@item @nicode{~h}
+Localized number@footnote{The @nicode{~h} format specifier first
+appeared in Guile version 2.0.6.}. Parameters: @var{width},
+@var{decimals}, @var{padchar}.
+
+Like @nicode{~f}, output an exact or floating point number, but do so
+according to the current locale, or according to the given locale object
+when the @code{:} modifier is used (@pxref{Number Input and Output,
+@code{number->locale-string}}).
+
+@example
+(format #t "~h" 12345.5678) ; with "C" as the current locale
+@print{} 12345.5678
+
+(format #t "~14,,'*:h" 12345.5678
+ (make-locale LC_ALL "en_US"))
+@print{} ***12,345.5678
+
+(format #t "~,2:h" 12345.5678
+ (make-locale LC_NUMERIC "fr_FR"))
+@print{} 12 345,56
+@end example
+
@item @nicode{~e}
Exponential float. Parameters: @var{width}, @var{mantdigits},
@var{expdigits}, @var{intdigits}, @var{overflowchar}, @var{padchar},
@end example
@sp 1
-@defun file-system-tree file-name [enter? [stat]]
+@deffn {Scheme Procedure} file-system-tree file-name [enter? [stat]]
Return a tree of the form @code{(@var{file-name} @var{stat}
@var{children} ...)} where @var{stat} is the result of @code{(@var{stat}
@var{file-name})} and @var{children} are similar structures for each
@dots{}))
@dots{}))
@end example
-@end defun
+@end deffn
@cindex file system combinator
directly as a directory tree is traversed; in fact,
@code{file-system-tree} is implemented in terms of it.
-@defun file-system-fold enter? leaf down up skip init file-name [stat]
+@deffn {Scheme Procedure} file-system-fold enter? leaf down up skip error init file-name [stat]
Traverse the directory at @var{file-name}, recursively, and return the
result of the successive applications of the @var{leaf}, @var{down},
@var{up}, and @var{skip} procedures as described below.
When @var{file-name} names a flat file, @code{(@var{leaf} @var{path}
@var{stat} @var{init})} is returned.
+When an @code{opendir} or @var{stat} call fails, call @code{(@var{error}
+@var{path} @var{stat} @var{errno} @var{result})}, with @var{errno} being
+the operating system error number that was raised---e.g.,
+@code{EACCES}---and @var{stat} either @code{#f} or the result of the
+@var{stat} call for that entry, when available.
+
The special @file{.} and @file{..} entries are not passed to these
procedures. The @var{path} argument to the procedures is a full file
name---e.g., @code{"../foo/bar/gnu"}; if @var{file-name} is an absolute
;; Likewise for skipped directories.
(define (skip name stat result) result)
- (file-system-fold enter? leaf down up skip
+ ;; Ignore unreadable files/directories but warn the user.
+ (define (error name stat errno result)
+ (format (current-error-port) "warning: ~a: ~a~%"
+ name (strerror errno))
+ result)
+
+ (file-system-fold enter? leaf down up skip error
0 ; initial counter is zero bytes
file-name))
(total-file-size "/dev/null")
@result{} 0
@end example
-@end defun
+@end deffn
The alternative C-like functions are described below.
-@defun ftw startname proc ['hash-size n]
+@deffn {Scheme Procedure} scandir name [select? [entry<?]]
+Return the list of the names of files contained in directory @var{name}
+that match predicate @var{select?} (by default, all files). The
+returned list of file names is sorted according to @var{entry<?}, which
+defaults to @code{string-locale<?} such that file names are sorted in
+the locale's alphabetical order (@pxref{Text Collation}). Return
+@code{#f} when @var{name} is unreadable or is not a directory.
+
+This procedure is modeled after the C library function of the same name
+(@pxref{Scanning Directory Content,,, libc, GNU C Library Reference
+Manual}).
+@end deffn
+
+@deffn {Scheme Procedure} ftw startname proc ['hash-size n]
Walk the file system tree descending from @var{startname}, calling
@var{proc} for each file and directory.
In the current implementation, returning non-@code{#t} from @var{proc}
is the only valid way to terminate @code{ftw}. @var{proc} must not
use @code{throw} or similar to escape.
-@end defun
+@end deffn
-@defun nftw startname proc ['chdir] ['depth] ['hash-size n] ['mount] ['physical]
+@deffn {Scheme Procedure} nftw startname proc ['chdir] ['depth] ['hash-size n] ['mount] ['physical]
Walk the file system 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.
In the current implementation, returning non-@code{#t} from @var{proc}
is the only valid way to terminate @code{ftw}. @var{proc} must not
use @code{throw} or similar to escape.
-@end defun
+@end deffn
@node Queues
@section Streams
@cindex streams
+This section documents Guile's legacy stream module. For a more
+complete and portable stream library, @pxref{SRFI-41}.
+
A stream represents a sequence of values, each of which is calculated
only when required. This allows large or even infinite sequences to
be represented and manipulated with familiar operations like ``car'',
@end example
@sp 1
-@defun make-stream proc initial-state
+@deffn {Scheme Procedure} make-stream proc initial-state
Return a new stream, formed by calling @var{proc} successively.
Each call is @code{(@var{proc} @var{state})}, it should return a pair,
being the new @var{state} for the next call. For the first call
@var{state} is the given @var{initial-state}. At the end of the
stream, @var{proc} should return some non-pair object.
-@end defun
+@end deffn
-@defun stream-car stream
+@deffn {Scheme Procedure} stream-car stream
Return the first element from @var{stream}. @var{stream} must not be
empty.
-@end defun
+@end deffn
-@defun stream-cdr stream
+@deffn {Scheme Procedure} stream-cdr stream
Return a stream which is the second and subsequent elements of
@var{stream}. @var{stream} must not be empty.
-@end defun
+@end deffn
-@defun stream-null? stream
+@deffn {Scheme Procedure} stream-null? stream
Return true if @var{stream} is empty.
-@end defun
+@end deffn
-@defun list->stream list
-@defunx vector->stream vector
+@deffn {Scheme Procedure} list->stream list
+@deffnx {Scheme Procedure} vector->stream vector
Return a stream with the contents of @var{list} or @var{vector}.
@var{list} or @var{vector} should not be modified subsequently, since
it's unspecified whether changes there will be reflected in the stream
returned.
-@end defun
+@end deffn
-@defun port->stream port readproc
+@deffn {Scheme Procedure} port->stream port readproc
Return a stream which is the values obtained by reading from
@var{port} using @var{readproc}. Each read call is
@code{(@var{readproc} @var{port})}, and it should return an EOF object
@example
(port->stream (open-input-file "/foo/bar.txt") read-char)
@end example
-@end defun
+@end deffn
-@defun stream->list stream
+@deffn {Scheme Procedure} stream->list stream
Return a list which is the entire contents of @var{stream}.
-@end defun
+@end deffn
-@defun stream->reversed-list stream
+@deffn {Scheme Procedure} stream->reversed-list stream
Return a list which is the entire contents of @var{stream}, but in
reverse order.
-@end defun
+@end deffn
-@defun stream->list&length stream
+@deffn {Scheme Procedure} stream->list&length stream
Return two values (@pxref{Multiple Values}), being firstly a list
which is the entire contents of @var{stream}, and secondly the number
of elements in that list.
-@end defun
+@end deffn
-@defun stream->reversed-list&length stream
+@deffn {Scheme Procedure} stream->reversed-list&length stream
Return two values (@pxref{Multiple Values}) being firstly a list which
is the entire contents of @var{stream}, but in reverse order, and
secondly the number of elements in that list.
-@end defun
+@end deffn
-@defun stream->vector stream
+@deffn {Scheme Procedure} stream->vector stream
Return a vector which is the entire contents of @var{stream}.
-@end defun
+@end deffn
-@defun stream-fold proc init stream0 @dots{} streamN
+@defun stream-fold proc init stream1 stream2 @dots{}
Apply @var{proc} successively over the elements of the given streams,
from first to last until the end of the shortest stream is reached.
Return the result from the last @var{proc} call.
-Each call is @code{(@var{proc} elem0 @dots{} elemN prev)}, where each
+Each call is @code{(@var{proc} elem1 elem2 @dots{} prev)}, where each
@var{elem} is from the corresponding @var{stream}. @var{prev} is the
return from the previous @var{proc} call, or the given @var{init} for
the first call.
@end defun
-@defun stream-for-each proc stream0 @dots{} streamN
+@defun stream-for-each proc stream1 stream2 @dots{}
Call @var{proc} on the elements from the given @var{stream}s. The
return value is unspecified.
-Each call is @code{(@var{proc} elem0 @dots{} elemN)}, where each
+Each call is @code{(@var{proc} elem1 elem2 @dots{})}, where each
@var{elem} is from the corresponding @var{stream}.
@code{stream-for-each} stops when it reaches the end of the shortest
@var{stream}.
@end defun
-@defun stream-map proc stream0 @dots{} streamN
+@defun stream-map proc stream1 stream2 @dots{}
Return a new stream which is the results of applying @var{proc} to the
elements of the given @var{stream}s.
-Each call is @code{(@var{proc} elem0 @dots{} elemN)}, where each
+Each call is @code{(@var{proc} elem1 elem2 @dots{})}, where each
@var{elem} is from the corresponding @var{stream}. The new stream
ends when the end of the shortest given @var{stream} is reached.
@end defun
of further input for an application level logical expression is
maintained too, and passed through to the reader.
-@defun make-buffered-input-port reader
+@deffn {Scheme Procedure} 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.
@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
+@end deffn
-@defun make-line-buffered-input-port reader
+@deffn {Scheme Procedure} 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
@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
+@end deffn
-@defun set-buffered-input-continuation?! port cont
+@deffn {Scheme Procedure} set-buffered-input-continuation?! port cont
Set the input continuation flag for a given buffered input
@var{port}.
(let ((obj (read my-port)))
...
@end example
-@end defun
+@end deffn
@c Local Variables:
HCoop / bpt / guile.git / blobdiff