@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, 2009, 2010
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
-@page
@node Pretty Printing
@section Pretty Printing
objects. This is especially useful for deeply nested or complex data
structures, such as lists and vectors.
-The module is loaded by simply saying.
+The module is loaded by entering the following:
@lisp
(use-modules (ice-9 pretty-print))
@end deffn
-@page
+@cindex truncated printing
+Also exported by the @code{(ice-9 pretty-print)} module is
+@code{truncated-print}, a procedure to print Scheme datums, truncating
+the output to a certain number of characters. This is useful when you
+need to present an arbitrary datum to the user, but you only have one
+line in which to do so.
+
+@lisp
+(define exp '(a b #(c d e) f . g))
+(truncated-print exp #:width 10) (newline)
+@print{} (a b . #)
+(truncated-print exp #:width 15) (newline)
+@print{} (a b # f . g)
+(truncated-print exp #:width 18) (newline)
+@print{} (a b #(c ...) . #)
+(truncated-print exp #:width 20) (newline)
+@print{} (a b #(c d e) f . g)
+(truncated-print "The quick brown fox" #:width 20) (newline)
+@print{} "The quick brown..."
+(truncated-print (current-module) #:width 20) (newline)
+@print{} #<directory (gui...>
+@end lisp
+
+@code{truncated-print} will not output a trailing newline. If an expression does
+not fit in the given width, it will be truncated -- possibly
+ellipsized@footnote{On Unicode-capable ports, the ellipsis is represented by
+character `HORIZONTAL ELLIPSIS' (U+2026), otherwise it is represented by three
+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
+into @var{width} characters. By default, @var{x} will be printed using
+@code{write}, though that behavior can be overriden 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-expressoin of @var{x} --
+e.g., if @var{x} is a vector, each member of @var{x}. One can attempt to
+``ration'' the available width, trying to allocate it equally to each
+sub-expression, via the @var{breadth-first?} keyword argument.
+
+The further @var{keyword-options} are keywords and parameters as
+follows,
+
+@table @asis
+@item @nicode{#:display?} @var{flag}
+If @var{flag} is true then print using @code{display}. The default is
+@code{#f} which means use @code{write} style. (@pxref{Writing})
+
+@item @nicode{#:width} @var{columns}
+Print within the given @var{columns}. The default is 79.
+
+@item @nicode{#:breadth-first?} @var{flag}
+If @var{flag} is true, then allocate the available width breadth-first
+among elements of a compound data structure (list, vector, pair,
+etc.). The default is @code{#f} which means that any element is
+allowed to consume all of the available width.
+@end table
+@end deffn
+
+
@node Formatted Output
@section Formatted Output
@cindex formatted output
@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
@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
@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
(@pxref{Internationalization}).
@item @nicode{~y}
-Pretty print. No parameters.
+Structured printing. Parameters: @var{width}.
-Output an argument with @code{pretty-print} (@pxref{Pretty Printing}).
+@nicode{~y} outputs an argument using @code{pretty-print}
+(@pxref{Pretty Printing}). The result will be formatted to fit within
+@var{width} columns (79 by default), consuming multiple lines if
+necessary.
+
+@nicode{~@@y} outputs an argument using @code{truncated-print}
+(@pxref{Pretty Printing}). The resulting code will be formatted to fit
+within @var{width} columns (79 by default), on a single line. The
+output will be truncated if necessary.
+
+@nicode{~:@@y} is like @nicode{~@@y}, except the @var{width} parameter
+is interpreted to be the maximum column to which to output. That is to
+say, if you are at column 10, and @nicode{~60:@@y} is seen, the datum
+will be truncated to 50 columns.
@item @nicode{~?}
@itemx @nicode{~k}
(format #t "~#*~2:*~a" 'a 'b 'c 'd) @print{} c
@end example
-At the end of the format string the current argument postion doesn't
+At the end of the format string the current argument position doesn't
matter, any further arguments are ignored.
@item @nicode{~t}
@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{@@}
@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
(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
@sp 1
@defun ftw startname proc ['hash-size n]
-Walk the filesystem tree descending from @var{startname}, calling
+Walk the file system tree descending from @var{startname}, calling
@var{proc} for each file and directory.
Hard links and symbolic links are followed. A file or directory is
@defun nftw startname proc ['chdir] ['depth] ['hash-size n] ['mount] ['physical]
-Walk the filesystem tree starting at @var{startname}, calling
+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.
-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.
@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
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
@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}.)
+file system 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
designed for efficient first-in / first-out operations.
@code{make-q} creates a queue, and objects are entered and removed
-with @code{enq!} and @code{deq!}. @code{q-push!} and @code{q-pop!}
+with @code{enq!} and @code{deq!}. @code{q-push!} and @code{q-pop!}
can be used too, treating the front of the queue like a stack.
@sp 1
@end deffn
@deffn {Scheme Procedure} q-remove! q obj
-Remove all occurences of @var{obj} from @var{q}, and return @var{q}.
+Remove all occurrences of @var{obj} from @var{q}, and return @var{q}.
@var{obj} is compared to queue elements using @code{eq?}.
@end deffn
@end defun
@defun stream->list&length stream
-Return two values (@pxref{Multiple Values}) being a list which is the
-entire contents of @var{stream}, and 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
@defun stream->reversed-list&length stream
-Return two values (@pxref{Multiple Values}) being a list which is the
-entire contents of @var{stream}, but in reverse order, and 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
@defun stream->vector stream
Each call is @code{(@var{proc} elem0 @dots{} elemN)}, where each
@var{elem} is from the corresponding @var{stream}. The new stream
-ends when the end of teh shortest given @var{stream} is reached.
+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
HCoop / bpt / guile.git / blobdiff