doc/ref/misc-modules.texi

   1 @page
   2 @node Pretty Printing
   3 @chapter Pretty Printing
   4
   5 @c FIXME::martin: Review me!
   6
   7 @cindex pretty printing
   8 The module @code{(ice-9 pretty-print)} provides the procedure
   9 @code{pretty-print}, which provides nicely formatted output of Scheme
  10 objects.  This is especially useful for deeply nested or complex data
  11 structures, such as lists and vectors.
  12
  13 The module is loaded by simply saying.
  14
  15 @lisp
  16 (use-modules (ice-9 pretty-print))
  17 @end lisp
  18
  19 This makes the procedure @code{pretty-print} available.  As an example
  20 how @code{pretty-print} will format the output, see the following:
  21
  22 @lisp
  23 (pretty-print '(define (foo) (lambda (x)
  24 (cond ((zero? x) #t) ((negative? x) -x) (else (if (= x 1) 2 (* x x x)))))))
  25 @print{}
  26 (define (foo)
  27   (lambda (x)
  28     (cond ((zero? x) #t)
  29           ((negative? x) -x)
  30           (else (if (= x 1) 2 (* x x x))))))
  31 @end lisp
  32
  33 @deffn {Scheme Procedure} pretty-print obj [port]
  34 Print the textual representation of the Scheme object @var{obj} to
  35 @var{port}.  @var{port} defaults to the current output port, if not
  36 given.
  37 @end deffn
  38
  39 Beware: Since @code{pretty-print} uses it's own write procedure, it's
  40 output will not be the same as for example the output of @code{write}.
  41 Consider the following example.
  42
  43 @lisp
  44 (write (lambda (x) x))
  45 @print{}
  46 #<procedure #f (x)>
  47
  48 (pretty-print (lambda (x) x))
  49 @print{}
  50 #[procedure]
  51 @end lisp
  52
  53 The reason is that @code{pretty-print} does not know as much about
  54 Guile's object types as the builtin procedures.  This is particularly
  55 important for smobs, for which a write procedure can be defined and be
  56 used by @code{write}, but not by @code{pretty-print}.
  57
  58 @page
  59 @node Formatted Output
  60 @chapter Formatted Output
  61
  62 @c FIXME::martin: Review me!
  63
  64 @cindex format
  65 @cindex formatted output
  66 Outputting messages or other texts which are composed of literal
  67 strings, variable contents, newlines and other formatting can be
  68 cumbersome, when only the standard procedures like @code{display},
  69 @code{write} and @code{newline} are available.  Additionally, one
  70 often wants to collect the output in strings.  With the standard
  71 routines, the user is required to set up a string port, add this port
  72 as a parameter to the output procedure calls and then retrieve the
  73 resulting string from the string port.
  74
  75 The @code{format} procedure, to be found in module @code{(ice-9
  76 format)}, can do all this, and even more.  If you are a C programmer,
  77 you can think of this procedure as Guile's @code{fprintf}.
  78
  79 @deffn {Scheme Procedure} format destination format-string args @dots{}
  80 The first parameter is the @var{destination}, it determines where the
  81 output of @code{format} will go.
  82
  83 @table @asis
  84 @item @code{#t}
  85 Send the formatted output to the current output port and return
  86 @code{#t}.
  87
  88 @item @code{#f}
  89 Return the formatted output as a string.
  90
  91 @item Any number value
  92 Send the formatted output to the current error port and return
  93 @code{#t}.
  94
  95 @item A valid output port
  96 Send the formatted output to the port @var{destination} and return
  97 @code{#t}.
  98 @end table
  99
 100 The second parameter is the format string.  It has a similar function
 101 to the format string in calls to @code{printf} or @code{fprintf} in C.
 102 It is output to the specified destination, but all escape sequences
 103 are replaced by the results of formatting the corresponding sequence.
 104
 105 Note that escape sequences are marked with the character @code{~}
 106 (tilde), and not with a @code{%} (percent sign), as in C.
 107
 108 The escape sequences in the following table are supported.  When there
 109 appears ``corresponding @var{arg}', that means any of the additional
 110 arguments, after dropping all arguments which have been used up by
 111 escape sequences which have been processed earlier.  Some of the
 112 format characters (the characters following the tilde) can be prefixed
 113 by @code{:}, @code{@@}, or @code{:@@}, to modify the behaviour of the
 114 format character.  How the modified behaviour differs from the default
 115 behaviour is described for every character in the table where
 116 appropriate.
 117
 118 @table @code
 119 @item ~~
 120 Output a single @code{~} (tilde) character.
 121
 122 @item ~%
 123 Output a newline character, thus advancing to the next output line.
 124
 125 @item ~&
 126 Start a new line, that is, output a newline character if not already
 127 at the start of a line.
 128
 129 @item ~_
 130 Output a single space character.
 131
 132 @item ~/
 133 Output a single tabulator character.
 134
 135 @item ~|
 136 Output a page separator (formfeed) character.
 137
 138 @item ~t
 139 Advance to the next tabulator position.
 140
 141 @item ~y
 142 Pretty-print the correspinding @var{arg}.
 143
 144 @item ~a
 145 Output the corresponding @var{arg} like @code{display}.
 146
 147 @item ~s
 148 Output the corresponding @var{arg} like @code{write}.
 149
 150 @item ~d
 151 Output the corresponding @var{arg} as a decimal number.
 152
 153 @item ~x
 154 Output the corresponding @var{arg} as a hexadecimal number.
 155
 156 @item ~o
 157 Output the corresponding @var{arg} as an octal number.
 158
 159 @item ~b
 160 Output the corresponding @var{arg} as a binary number.
 161
 162 @item ~r
 163 Output the corresponding @var{arg} as a number word, e.g. 10 prints as
 164 @code{ten}.  If prefixed with @code{:}, @code{tenth} is printed, if
 165 prefixed with @code{:@@}, roman numbers are printed.
 166
 167 @item ~f
 168 Output the corresponding @var{arg} as a fixed format floating point
 169 number, such as @code{1.34}.
 170
 171 @item ~e
 172 Output the corresponding @var{arg} in exponential notation, such as
 173 @code{1.34E+0}.
 174
 175 @item ~g
 176 This works either like @code{~f} or like @code{~e}, whichever produces
 177 less characters to be written.
 178
 179 @item ~$
 180 Like @code{~f}, but only with two digits after the decimal point.
 181
 182 @item ~i
 183 Output the corresponding @var{arg} as a complex number.
 184
 185 @item ~c
 186 Output the corresponding @var{arg} as a character.  If prefixed with
 187 @code{@@}, it is printed like with @code{write}.  If prefixed with
 188 @code{:}, control characters are treated specially, for example
 189 @code{#\newline} will be printed as @code{^J}.
 190
 191 @item ~p
 192 ``Plural''.  If the corresponding @var{arg} is 1, nothing is printed
 193 (or @code{y} if prefixed with @code{@@} or @code{:@@}), otherwise
 194 @code{s} is printed (or @code{ies} if prefixed with @code{@@} or
 195 @code{:@@}).
 196
 197 @item ~?, ~k
 198 Take the corresponding argument as a format string, and the following
 199 argument as a list of values.  Then format the values with respect to
 200 the format string.
 201
 202 @item ~!
 203 Flush the output to the output port.
 204
 205 @item ~#\newline (tilde-newline)
 206 @c FIXME::martin: I don't understand this from the source.
 207 Continuation lines.
 208
 209 @item ~*
 210 Argument jumping. Navigate in the argument list as specified by the
 211 corresponding argument.  If prefixed with @code{:}, jump backwards in
 212 the argument list, if prefixed by @code{:@@}, jump to the parameter
 213 with the absolute index, otherwise jump forward in the argument list.
 214
 215 @item ~(
 216 Case conversion begin.  If prefixed by @code{:}, the following output
 217 string will be capitalized, if prefixed by @code{@@}, the first
 218 character will be capitalized, if prefixed by @code{:@@} it will be
 219 upcased and otherwise it will be downcased.  Conversion stops when the
 220 ``Case conversion end'' @code{~)}sequence is encountered.
 221
 222 @item ~)
 223 Case conversion end.  Stop any case conversion currently in effect.
 224
 225 @item ~[
 226 @c FIXME::martin: I don't understand this from the source.
 227 Conditional begin.
 228
 229 @item ~;
 230 @c FIXME::martin: I don't understand this from the source.
 231 Conditional separator.
 232
 233 @item ~]
 234 @c FIXME::martin: I don't understand this from the source.
 235 Conditional end.
 236
 237 @item ~@{
 238 @c FIXME::martin: I don't understand this from the source.
 239 Iteration begin.
 240
 241 @item ~@}
 242 @c FIXME::martin: I don't understand this from the source.
 243 Iteration end.
 244
 245 @item ~^
 246 @c FIXME::martin: I don't understand this from the source.
 247 Up and out.
 248
 249 @item ~'
 250 @c FIXME::martin: I don't understand this from the source.
 251 Character parameter.
 252
 253 @item ~0 @dots{} ~9, ~-, ~+
 254 @c FIXME::martin: I don't understand this from the source.
 255 Numeric parameter.
 256
 257 @item ~v
 258 @c FIXME::martin: I don't understand this from the source.
 259 Variable parameter from next argument.
 260
 261 @item ~#
 262 Parameter is number of remaining args.  The number of the remaining
 263 arguments is prepended to the list of unprocessed arguments.
 264
 265 @item ~,
 266 @c FIXME::martin: I don't understand this from the source.
 267 Parameter separators.
 268
 269 @item ~q
 270 Inquiry message.  Insert a copyright message into the output.
 271 @end table
 272
 273 If any type conversions should fail (for example when using an escape
 274 sequence for number output, but the argument is a string), an error
 275 will be signalled.
 276 @end deffn
 277
 278 You may have noticed that Guile contains a @code{format} procedure
 279 even when the module @code{(ice-9 format)} is not loaded.  The default
 280 @code{format} procedure does not support all escape sequences
 281 documented in this chapter, and will signal an error if you try to use
 282 one of them.  The reason for providing two versions of @code{format}
 283 is that the full-featured module is fairly large and requires some
 284 time to get loaded.  So the Guile maintainers decided not to load the
 285 large version of @code{format} by default, so that the start-up time
 286 of the interpreter is not unnecessarily increased.
 287
 288
 289 @c Local Variables:
 290 @c TeX-master: "guile.texi"
 291 @c End: