diff options
author | Neil Jerram <neil@ossau.uklinux.net> | 2001-08-24 09:40:29 +0000 |
---|---|---|
committer | Neil Jerram <neil@ossau.uklinux.net> | 2001-08-24 09:40:29 +0000 |
commit | a0e07ba4ec86e4df014fee0666f18ece5a4d2471 (patch) | |
tree | ebe6546fc93fdcb3e2e1fdfbe55d809914b94ad8 /doc/ref/misc-modules.texi | |
parent | 80fdeb4e5a869726da90c88ddce377f599515ee8 (diff) | |
download | guile-a0e07ba4ec86e4df014fee0666f18ece5a4d2471.tar.gz |
* Organize documentation into per-manual directories (halfway point commit).
Diffstat (limited to 'doc/ref/misc-modules.texi')
-rw-r--r-- | doc/ref/misc-modules.texi | 291 |
1 files changed, 291 insertions, 0 deletions
diff --git a/doc/ref/misc-modules.texi b/doc/ref/misc-modules.texi new file mode 100644 index 000000000..30f821937 --- /dev/null +++ b/doc/ref/misc-modules.texi @@ -0,0 +1,291 @@ +@page +@node Pretty Printing +@chapter Pretty Printing + +@c FIXME::martin: Review me! + +@cindex pretty printing +The module @code{(ice-9 pretty-print)} provides the procedure +@code{pretty-print}, which provides nicely formatted output of Scheme +objects. This is especially useful for deeply nested or complex data +structures, such as lists and vectors. + +The module is loaded by simply saying. + +@lisp +(use-modules (ice-9 pretty-print)) +@end lisp + +This makes the procedure @code{pretty-print} available. As an example +how @code{pretty-print} will format the output, see the following: + +@lisp +(pretty-print '(define (foo) (lambda (x) +(cond ((zero? x) #t) ((negative? x) -x) (else (if (= x 1) 2 (* x x x))))))) +@print{} +(define (foo) + (lambda (x) + (cond ((zero? x) #t) + ((negative? x) -x) + (else (if (= x 1) 2 (* x x x)))))) +@end lisp + +@deffn procedure pretty-print obj [port] +Print the textual representation of the Scheme object @var{obj} to +@var{port}. @var{port} defaults to the current output port, if not +given. +@end deffn + +Beware: Since @code{pretty-print} uses it's own write procedure, it's +output will not be the same as for example the output of @code{write}. +Consider the following example. + +@lisp +(write (lambda (x) x)) +@print{} +#<procedure #f (x)> + +(pretty-print (lambda (x) x)) +@print{} +#[procedure] +@end lisp + +The reason is that @code{pretty-print} does not know as much about +Guile's object types as the builtin procedures. This is particularly +important for smobs, for which a write procedure can be defined and be +used by @code{write}, but not by @code{pretty-print}. + +@page +@node Formatted Output +@chapter Formatted Output + +@c FIXME::martin: Review me! + +@cindex format +@cindex formatted output +Outputting messages or other texts which are composed of literal +strings, variable contents, newlines and other formatting can be +cumbersome, when only the standard procedures like @code{display}, +@code{write} and @code{newline} are available. Additionally, one +often wants to collect the output in strings. With the standard +routines, the user is required to set up a string port, add this port +as a parameter to the output procedure calls and then retrieve the +resulting string from the string port. + +The @code{format} procedure, to be found in module @code{(ice-9 +format)}, can do all this, and even more. If you are a C programmer, +you can think of this procedure as Guile's @code{fprintf}. + +@deffn procedure format destination format-string args @dots{} +The first parameter is the @var{destination}, it determines where the +output of @code{format} will go. + +@table @asis +@item @code{#t} +Send the formatted output to the current output port and return +@code{#t}. + +@item @code{#f} +Return the formatted output as a string. + +@item Any number value +Send the formatted output to the current error port and return +@code{#t}. + +@item A valid output port +Send the formatted output to the port @var{destination} and return +@code{#t}. +@end table + +The second parameter is the format string. It has a similar function +to the format string in calls to @code{printf} or @code{fprintf} in C. +It is output to the specified destination, but all escape sequences +are replaced by the results of formatting the corresponding sequence. + +Note that escape sequences are marked with the character @code{~} +(tilde), and not with a @code{%} (percent sign), as in C. + +The escape sequences in the following table are supported. When there +appears ``corresponding @var{arg}', that means any of the additional +arguments, after dropping all arguments which have been used up by +escape sequences which have been processed earlier. Some of the +format characters (the characters following the tilde) can be prefixed +by @code{:}, @code{@@}, or @code{:@@}, to modify the behaviour of the +format character. How the modified behaviour differs from the default +behaviour is described for every character in the table where +appropriate. + +@table @code +@item ~~ +Output a single @code{~} (tilde) character. + +@item ~% +Output a newline character, thus advancing to the next output line. + +@item ~& +Start a new line, that is, output a newline character if not already +at the statr of a line. + +@item ~_ +Output a single space character. + +@item ~/ +Output a single tabulator character. + +@item ~| +Output a page separator (formfeed) character. + +@item ~t +Advance to the next tabulator position. + +@item ~y +Pretty-print the correspinding @var{arg}. + +@item ~a +Output the corresponding @var{arg} like @code{display}. + +@item ~s +Output the corresponding @var{arg} like @code{write}. + +@item ~d +Output the corresponding @var{arg} as a decimal number. + +@item ~x +Output the corresponding @var{arg} as a hexadecimal number. + +@item ~o +Output the corresponding @var{arg} as an octal number. + +@item ~b +Output the corresponding @var{arg} as a binary number. + +@item ~r +Output the corresponding @var{arg} as a number word, e.g. 10 prints as +@code{ten}. If prefixed with @code{:}, @code{tenth} is printed, if +prefixed with @code{:@@}, roman numbers are printed. + +@item ~f +Output the corresponding @var{arg} as a fixed format floating point +number, such as @code{1.34}. + +@item ~e +Output the corresponding @var{arg} in exponential notation, such as +@code{1.34E+0}. + +@item ~g +%% FIXME::martin: There must be a difference. Does anybody know? +Like @code{~f}. + +@item ~$ +Like @code{~f}, but only with two digits after the decimal point. + +@item ~i +Output the corresponding @var{arg} as a complex number. + +@item ~c +Output the corresponding @var{arg} as a character. If prefixed with +@code{@@}, it is printed like with @code{write}. If prefixed with +@code{:}, control characters are treated specially, for example +@code{#\newline} will be printed as @code{^J}. + +@item ~p +``Plural''. If the corresponding @var{arg} is 1, nothing is printed +(or @code{y} if prefixed with @code{@@} or @code{:@@}), otherwise +@code{s} is printed (or @code{ies} if prefixed with @code{@@} or +@code{:@@}). + +@item ~?, ~k +Take the corresponding argument as a format string, and the following +argument as a list of values. Then format the values with respect to +the format string. + +@item ~! +Flush the output to the output port. + +@item ~#\newline (tilde-newline) +@c FIXME::martin: I don't understand this from the source. +Continuation lines. + +@item ~* +Argument jumping. Navigate in the argument list as specified by the +corresponding argument. If prefixed with @code{:}, jump backwards in +the argument list, if prefixed by @code{:@@}, jump to the parameter +with the absolute index, otherwise jump forward in the argument list. + +@item ~( +Case conversion begin. If prefixed by @code{:}, the following output +string will be capitalized, if prefixed by @code{@@}, the first +character will be capitalized, if prefixed by @code{:@@} it will be +upcased and otherwise it will be downcased. Conversion stops when the +``Case conversion end'' @code{~)}sequence is encountered. + +@item ~) +Case conversion end. Stop any case conversion currently in effect. + +@item ~[ +@c FIXME::martin: I don't understand this from the source. +Conditional begin. + +@item ~; +@c FIXME::martin: I don't understand this from the source. +Conditional separator. + +@item ~] +@c FIXME::martin: I don't understand this from the source. +Conditional end. + +@item ~@{ +@c FIXME::martin: I don't understand this from the source. +Iteration begin. + +@item ~@} +@c FIXME::martin: I don't understand this from the source. +Iteration end. + +@item ~^ +@c FIXME::martin: I don't understand this from the source. +Up and out. + +@item ~' +@c FIXME::martin: I don't understand this from the source. +Character parameter. + +@item ~0 @dots{} ~9, ~-, ~+ +@c FIXME::martin: I don't understand this from the source. +Numeric parameter. + +@item ~v +@c FIXME::martin: I don't understand this from the source. +Variable parameter from next argument. + +@item ~# +Parameter is number of remaining args. The number of the remaining +arguments is prepended to the list of unprocessed arguments. + +@item ~, +@c FIXME::martin: I don't understand this from the source. +Parameter separators. + +@item ~q +Inquiry message. Insert a copyright message into the output. +@end table + +If any type conversions should fail (for example when using an escape +sequence for number output, but the argument is a string), an error +will be signalled. +@end deffn + +You may have noticed that Guile contains a @code{format} procedure +even when the module @code{(ice-9 format)} is not loaded. The default +@code{format} procedure does not support all escape sequences +documented in this chapter, and will signal an error if you try to use +one of them. The reason for providing two versions of @code{format} +is that the full-featured module is fairly large and requires some +time to get loaded. So the Guile maintainers decided not to load the +large version of @code{format} by default, so that the start-up time +of the interpreter is not unnecessarily increased. + + +@c Local Variables: +@c TeX-master: "guile.texi" +@c End: |