@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
-@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006
+@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2009, 2010, 2011
@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 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
+``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
@deffn {Scheme Procedure} format dest fmt [args@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}), a number for
-@code{current-error-port}, or @code{#f} to return the output as a
-string.
+@code{current-output-port} (@pxref{Default Ports}), or @code{#f} to
+return the output as a string.
@var{fmt} can contain literal text to be output, and @nicode{~}
escapes. Each escape has the form
printed instead of the value.
@example
-(format #t "~5,,,'xf" 12345) @print{} 12345
-(format #t "~4,,,'xf" 12345) @print{} xxxx
+(format #t "~6,,,'xf" 12345) @print{} 12345.
+(format #t "~5,,,'xf" 12345) @print{} xxxxx
@end example
@item @nicode{~e}
@c FIXME: MANTDIGITS with negative INTDIGITS doesn't match CL spec,
@c believe the spec says it ought to still show mantdigits+1 sig
-@c figures, ie. leading zeros don't count towards MANTDIGITS, but it
+@c figures, i.e. leading zeros don't count towards MANTDIGITS, but it
@c seems to just treat MANTDIGITS as how many digits after the
@c decimal point.
(@pxref{Internationalization}).
@item @nicode{~y}
-Pretty print. No parameters.
+Structured printing. Parameters: @var{width}.
+
+@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.
-Output an argument with @code{pretty-print} (@pxref{Pretty Printing}).
+@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}
@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.
@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
completion, or otherwise the non-@code{#t} value from @var{proc} which
caused the stop.
-@c For reference, one reason not to esacpe is that the current
+@c For reference, one reason not to escape is that the current
@c directory is not saved and restored with dynamic-wind. Maybe
@c changing that would be enough to allow escaping.
@c
@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
HCoop / bpt / guile.git / blobdiff