read: Support R7RS '#true' and '#false' syntax for booleans.

[bpt/guile.git] / doc / ref / misc-modules.texi

diff --git a/doc/ref/misc-modules.texi b/doc/ref/misc-modules.texi
index 6177624..c1e65d7 100644 (file)
--- a/doc/ref/misc-modules.texi
+++ b/doc/ref/misc-modules.texi
@@ -1,7 +1,7 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Guile Reference Manual.
 @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
 @c See the file guile.texi for copying conditions.
 
 @node Pretty Printing


@@ -90,13 +90,13 @@ dots.}, or in the worst case, displayed as @nicode{#}.
 
 @deffn {Scheme Procedure} truncated-print obj [port] [keyword-options]
 Print @var{obj}, truncating the output, if necessary, to make it fit
 
 @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
 @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.
 
 ``ration'' the available width, trying to allocate it equally to each
 sub-expression, via the @var{breadth-first?} keyword argument.
 


@@ -156,7 +156,7 @@ C programmers will note the similarity between @code{format} and
 instead of @nicode{%}, and are more powerful.
 
 @sp 1
 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
 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


@@ -269,7 +269,7 @@ Integer.  Parameters: @var{minwidth}, @var{padchar}, @var{commachar},
 @var{commawidth}.
 
 Output an integer argument as a decimal, hexadecimal, octal or binary
 @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
 
 @example
 (format #t "~d" 123) @print{} 123


@@ -297,7 +297,9 @@ minimum), it's padded on the left with the @var{padchar} parameter
 @end example
 
 @nicode{~:d} adds commas (or the @var{commachar} parameter) every
 @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
 
 @example
 (format #t "~:d" 1234567)         @print{} 1,234,567


@@ -404,6 +406,29 @@ printed instead of the value.
 (format #t "~5,,,'xf" 12345) @print{} xxxxx
 @end example
 
 (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},
 @item @nicode{~e}
 Exponential float.  Parameters: @var{width}, @var{mantdigits},
 @var{expdigits}, @var{intdigits}, @var{overflowchar}, @var{padchar},


@@ -1112,7 +1137,7 @@ GNU C Library Reference Manual}).
 @end example
 @sp 1
 
 @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
 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


@@ -1169,7 +1194,7 @@ tree, discarding their @code{stat} info:
     @dots{}))
   @dots{}))
 @end example
     @dots{}))
   @dots{}))
 @end example

-@end defun
+@end deffn

 
 @cindex file system combinator
 
 
 @cindex file system combinator
 


@@ -1180,7 +1205,7 @@ than building up a tree of entries in memory, like
 directly as a directory tree is traversed; in fact,
 @code{file-system-tree} is implemented in terms of it.
 
 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.
 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.


@@ -1202,6 +1227,12 @@ encountered, call @code{(@var{skip} @var{path} @var{stat}
 When @var{file-name} names a flat file, @code{(@var{leaf} @var{path}
 @var{stat} @var{init})} is returned.
 
 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
 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


@@ -1235,7 +1266,13 @@ to `du --apparent-size' with GNU Coreutils.)"
   ;; Likewise for skipped directories.
   (define (skip name stat result) result)
 
   ;; 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))
 
                            0  ; initial counter is zero bytes
                            file-name))
 


@@ -1245,11 +1282,24 @@ to `du --apparent-size' with GNU Coreutils.)"
 (total-file-size "/dev/null")
 @result{} 0
 @end example
 (total-file-size "/dev/null")
 @result{} 0
 @end example

-@end defun
+@end deffn

 
 The alternative C-like functions are described below.
 
 
 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.
 
 Walk the file system tree descending from @var{startname}, calling
 @var{proc} for each file and directory.
 


@@ -1302,10 +1352,10 @@ to set the size of the hash table used to track items already visited.
 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.
 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.
 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.


@@ -1408,7 +1458,7 @@ caused the stop.
 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.
 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
 
 
 @node Queues


@@ -1523,6 +1573,9 @@ modifies the queue @var{list} then it must either maintain
 @section Streams
 @cindex streams
 
 @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'',
 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'',


@@ -1574,7 +1627,7 @@ a list, but they could be printed (infinitely) with for example
 @end example
 
 @sp 1
 @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,
 Return a new stream, formed by calling @var{proc} successively.
 
 Each call is @code{(@var{proc} @var{state})}, it should return a pair,


@@ -1582,32 +1635,32 @@ the @code{car} being the value for the stream, and the @code{cdr}
 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.
 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.
 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.
 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.
 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.
 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
 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


@@ -1618,59 +1671,59 @@ For example a stream of characters from a file,
 @example
 (port->stream (open-input-file "/foo/bar.txt") read-char)
 @end example
 @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}.
 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.
 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.
 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.
 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}.
 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.
 
 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
 
 @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.
 
 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
 
 @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.
 
 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
 @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


@@ -1692,7 +1745,7 @@ 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.
 
 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.
 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.


@@ -1707,9 +1760,9 @@ 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.
 @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
 @cindex Line buffered input
 Create an input port which returns characters obtained from the
 specified @var{reader} function, similar to


@@ -1719,9 +1772,9 @@ 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.
 @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}.
 
 Set the input continuation flag for a given buffered input
 @var{port}.
 


@@ -1736,7 +1789,7 @@ example with the Scheme @code{read} function (@pxref{Scheme Read}),
 (let ((obj (read my-port)))
   ...
 @end example
 (let ((obj (read my-port)))
   ...
 @end example

-@end defun
+@end deffn

 
 
 @c Local Variables:
 
 
 @c Local Variables: