3 @chapter Pretty Printing
5 @c FIXME::martin: Review me!
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.
13 The module is loaded by simply saying.
16 (use-modules (ice-9 pretty-print))
19 This makes the procedure @code{pretty-print} available. As an example
20 how @code{pretty-print} will format the output, see the following:
23 (pretty-print '(define (foo) (lambda (x)
24 (cond ((zero? x) #t) ((negative? x) -x) (else
25 (if (= x 1) 2 (* x x x)))))))
31 (else (if (= x 1) 2 (* x x x))))))
34 @deffn {Scheme Procedure} pretty-print obj [port] [keyword-options]
35 Print the textual representation of the Scheme object @var{obj} to
36 @var{port}. @var{port} defaults to the current output port, if not
39 The further @var{keyword-options} are keywords and parameters as
43 @item @nicode{#:display?} @var{flag}
44 If @var{flag} is true then print using @code{display}. The default is
45 @code{#f} which means use @code{write} style. (@pxref{Writing})
47 @item @nicode{#:per-line-prefix} @var{string}
48 Print the given @var{string} as a prefix on each line. The default is
51 @item @nicode{#:width} @var{columns}
52 Print within the given @var{columns}. The default is 79.
56 Beware: Since @code{pretty-print} uses it's own write procedure, it's
57 output will not be the same as for example the output of @code{write}.
58 Consider the following example.
61 (write (lambda (x) x))
65 (pretty-print (lambda (x) x))
70 The reason is that @code{pretty-print} does not know as much about
71 Guile's object types as the builtin procedures. This is particularly
72 important for smobs, for which a write procedure can be defined and be
73 used by @code{write}, but not by @code{pretty-print}.
77 @node Formatted Output
78 @chapter Formatted Output
80 @c FIXME::martin: Review me!
83 @cindex formatted output
84 Outputting messages or other texts which are composed of literal
85 strings, variable contents, newlines and other formatting can be
86 cumbersome, when only the standard procedures like @code{display},
87 @code{write} and @code{newline} are available. Additionally, one
88 often wants to collect the output in strings. With the standard
89 routines, the user is required to set up a string port, add this port
90 as a parameter to the output procedure calls and then retrieve the
91 resulting string from the string port.
93 The @code{format} procedure, to be found in module @code{(ice-9
94 format)}, can do all this, and even more. If you are a C programmer,
95 you can think of this procedure as Guile's @code{fprintf}.
97 @deffn {Scheme Procedure} format destination format-string args @dots{}
98 The first parameter is the @var{destination}, it determines where the
99 output of @code{format} will go.
103 Send the formatted output to the current output port and return
107 Return the formatted output as a string.
109 @item Any number value
110 Send the formatted output to the current error port and return
113 @item A valid output port
114 Send the formatted output to the port @var{destination} and return
118 The second parameter is the format string. It has a similar function
119 to the format string in calls to @code{printf} or @code{fprintf} in C.
120 It is output to the specified destination, but all escape sequences
121 are replaced by the results of formatting the corresponding sequence.
123 Note that escape sequences are marked with the character @code{~}
124 (tilde), and not with a @code{%} (percent sign), as in C.
126 The escape sequences in the following table are supported. When there
127 appears ``corresponding @var{arg}', that means any of the additional
128 arguments, after dropping all arguments which have been used up by
129 escape sequences which have been processed earlier. Some of the
130 format characters (the characters following the tilde) can be prefixed
131 by @code{:}, @code{@@}, or @code{:@@}, to modify the behaviour of the
132 format character. How the modified behaviour differs from the default
133 behaviour is described for every character in the table where
138 Output a single @code{~} (tilde) character.
141 Output a newline character, thus advancing to the next output line.
144 Start a new line, that is, output a newline character if not already
145 at the start of a line.
148 Output a single space character.
151 Output a single tabulator character.
154 Output a page separator (formfeed) character.
157 Advance to the next tabulator position.
160 Pretty-print the corresponding @var{arg}.
163 Output the corresponding @var{arg} like @code{display}.
166 Output the corresponding @var{arg} like @code{write}.
169 Output the corresponding @var{arg} as a decimal number.
172 Output the corresponding @var{arg} as a hexadecimal number.
175 Output the corresponding @var{arg} as an octal number.
178 Output the corresponding @var{arg} as a binary number.
181 Output the corresponding @var{arg} as a number word, e.g. 10 prints as
182 @code{ten}. If prefixed with @code{:}, @code{tenth} is printed, if
183 prefixed with @code{:@@}, Roman numbers are printed.
186 Output the corresponding @var{arg} as a fixed format floating point
187 number, such as @code{1.34}.
190 Output the corresponding @var{arg} in exponential notation, such as
194 This works either like @code{~f} or like @code{~e}, whichever produces
195 less characters to be written.
198 Like @code{~f}, but only with two digits after the decimal point.
201 Output the corresponding @var{arg} as a complex number.
204 Output the corresponding @var{arg} as a character. If prefixed with
205 @code{@@}, it is printed like with @code{write}. If prefixed with
206 @code{:}, control characters are treated specially, for example
207 @code{#\newline} will be printed as @code{^J}.
210 ``Plural''. If the corresponding @var{arg} is 1, nothing is printed
211 (or @code{y} if prefixed with @code{@@} or @code{:@@}), otherwise
212 @code{s} is printed (or @code{ies} if prefixed with @code{@@} or
216 Take the corresponding argument as a format string, and the following
217 argument as a list of values. Then format the values with respect to
221 Flush the output to the output port.
223 @item ~#\newline (tilde-newline)
224 @c FIXME::martin: I don't understand this from the source.
228 Argument jumping. Navigate in the argument list as specified by the
229 corresponding argument. If prefixed with @code{:}, jump backwards in
230 the argument list, if prefixed by @code{:@@}, jump to the parameter
231 with the absolute index, otherwise jump forward in the argument list.
234 Case conversion begin. If prefixed by @code{:}, the following output
235 string will be capitalized, if prefixed by @code{@@}, the first
236 character will be capitalized, if prefixed by @code{:@@} it will be
237 upcased and otherwise it will be downcased. Conversion stops when the
238 ``Case conversion end'' @code{~)}sequence is encountered.
241 Case conversion end. Stop any case conversion currently in effect.
244 @c FIXME::martin: I don't understand this from the source.
248 @c FIXME::martin: I don't understand this from the source.
249 Conditional separator.
252 @c FIXME::martin: I don't understand this from the source.
256 @c FIXME::martin: I don't understand this from the source.
260 @c FIXME::martin: I don't understand this from the source.
264 @c FIXME::martin: I don't understand this from the source.
268 @c FIXME::martin: I don't understand this from the source.
271 @item ~0 @dots{} ~9, ~-, ~+
272 @c FIXME::martin: I don't understand this from the source.
276 @c FIXME::martin: I don't understand this from the source.
277 Variable parameter from next argument.
280 Parameter is number of remaining args. The number of the remaining
281 arguments is prepended to the list of unprocessed arguments.
284 @c FIXME::martin: I don't understand this from the source.
285 Parameter separators.
288 Inquiry message. Insert a copyright message into the output.
291 If any type conversions should fail (for example when using an escape
292 sequence for number output, but the argument is a string), an error
296 You may have noticed that Guile contains a @code{format} procedure
297 even when the module @code{(ice-9 format)} is not loaded. The default
298 @code{format} procedure does not support all escape sequences
299 documented in this chapter, and will signal an error if you try to use
300 one of them. The reason for providing two versions of @code{format}
301 is that the full-featured module is fairly large and requires some
302 time to get loaded. So the Guile maintainers decided not to load the
303 large version of @code{format} by default, so that the start-up time
304 of the interpreter is not unnecessarily increased.
309 @chapter The Rx Regular Expression Library
311 [FIXME: this is taken from Gary and Mark's quick summaries and should be
312 reviewed and expanded. Rx is pretty stable, so could already be done!]
315 @cindex finite automaton
317 The @file{guile-lang-allover} package provides an interface to Tom
318 Lord's Rx library (currently only to POSIX regular expressions). Use of
319 the library requires a two step process: compile a regular expression
320 into an efficient structure, then use the structure in any number of
323 For example, given the regular expression @samp{abc.} (which matches any
324 string containing @samp{abc} followed by any single character):
327 guile> @kbd{(define r (regcomp "abc."))}
330 guile> @kbd{(regexec r "abc")}
332 guile> @kbd{(regexec r "abcd")}
337 The definitions of @code{regcomp} and @code{regexec} are as follows:
339 @deffn {Scheme Procedure} regcomp pattern [flags]
340 Compile the regular expression pattern using POSIX rules. Flags is
341 optional and should be specified using symbolic names:
343 use extended POSIX syntax
346 use case-insensitive matching
349 allow anchors to match after newline characters in the
350 string and prevents @code{.} or @code{[^...]} from matching newlines.
353 The @code{logior} procedure can be used to combine multiple flags.
354 The default is to use
355 POSIX basic syntax, which makes @code{+} and @code{?} literals and @code{\+}
357 operators. Backslashes in @var{pattern} must be escaped if specified in a
358 literal string e.g., @code{"\\(a\\)\\?"}.
361 @deffn {Scheme Procedure} regexec regex string [match-pick] [flags]
362 Match @var{string} against the compiled POSIX regular expression
364 @var{match-pick} and @var{flags} are optional. Possible flags (which can be
365 combined using the logior procedure) are:
368 The beginning of line operator won't match the beginning of
369 @var{string} (presumably because it's not the beginning of a line)
373 Similar to REG_NOTBOL, but prevents the end of line operator
374 from matching the end of @var{string}.
377 If no match is possible, regexec returns #f. Otherwise @var{match-pick}
378 determines the return value:
380 @code{#t} or unspecified: a newly-allocated vector is returned,
381 containing pairs with the indices of the matched part of @var{string} and any
384 @code{""}: a list is returned: the first element contains a nested list
385 with the matched part of @var{string} surrounded by the the unmatched parts.
386 Remaining elements are matched substrings (if any). All returned
387 substrings share memory with @var{string}.
389 @code{#f}: regexec returns #t if a match is made, otherwise #f.
391 vector: the supplied vector is returned, with the first element replaced
392 by a pair containing the indices of the matched portion of @var{string} and
393 further elements replaced by pairs containing the indices of matched
396 list: a list will be returned, with each member of the list
397 specified by a code in the corresponding position of the supplied list:
399 a number: the numbered matching substring (0 for the entire match).
401 @code{#\<}: the beginning of @var{string} to the beginning of the part matched
404 @code{#\>}: the end of the matched part of @var{string} to the end of
407 @code{#\c}: the "final tag", which seems to be associated with the "cut
408 operator", which doesn't seem to be available through the posix
411 e.g., @code{(list #\< 0 1 #\>)}. The returned substrings share memory with
415 Here are some other procedures that might be used when using regular
418 @deffn {Scheme Procedure} compiled-regexp? obj
419 Test whether obj is a compiled regular expression.
422 @deffn {Scheme Procedure} regexp->dfa regex [flags]
425 @deffn {Scheme Procedure} dfa-fork dfa
428 @deffn {Scheme Procedure} reset-dfa! dfa
431 @deffn {Scheme Procedure} dfa-final-tag dfa
434 @deffn {Scheme Procedure} dfa-continuable? dfa
437 @deffn {Scheme Procedure} advance-dfa! dfa string
442 @chapter File Tree Walk
443 @cindex file tree walk
445 The functions in this section traverse a tree of files and
446 directories, in a fashion similar to the C @code{ftw} and @code{nftw}
447 routines (@pxref{Working with Directory Trees,,, libc, GNU C Library
451 (use-modules (ice-9 ftw))
455 @defun ftw startname proc ['hash-size n]
456 Walk the filesystem tree descending from @var{startname}, calling
457 @var{proc} for each file and directory.
459 Hard links and symbolic links are followed. A file or directory is
460 reported to @var{proc} only once, and skipped if seen again in another
461 place. One consequence of this is that @code{ftw} is safe against
462 circularly linked directory structures.
464 Each @var{proc} call is @code{(@var{proc} filename statinfo flag)} and
465 it should return @code{#t} to continue, or any other value to stop.
467 @var{filename} is the item visited, being @var{startname} plus a
468 further path and the name of the item. @var{statinfo} is the return
469 from @code{stat} (@pxref{File System}) on @var{filename}. @var{flag}
470 is one of the following symbols,
474 @var{filename} is a file, this includes special files like devices,
478 @var{filename} is a directory.
481 An error occurred when calling @code{stat}, so nothing is known.
482 @var{statinfo} is @code{#f} in this case.
484 @item directory-not-readable
485 @var{filename} is a directory, but one which cannot be read and hence
486 won't be recursed into.
489 @var{filename} is a dangling symbolic link. Symbolic links are
490 normally followed and their target reported, the link itself is
491 reported if the target does not exist.
494 The return value from @code{ftw} is @code{#t} if it ran to completion,
495 or otherwise the non-@code{#t} value from @var{proc} which caused the
498 Optional argument symbol @code{hash-size} and an integer can be given
499 to set the size of the hash table used to track items already visited.
500 (@pxref{Hash Table Reference})
502 @c Actually, it's probably safe to escape from ftw, just need to
505 In the current implementation, returning non-@code{#t} from @var{proc}
506 is the only valid way to terminate @code{ftw}. @var{proc} must not
507 use @code{throw} or similar to escape.
511 @defun nftw startname proc ['chdir] ['depth] ['hash-size n] ['mount] ['physical]
512 Walk the filesystem tree starting at @var{startname}, calling
513 @var{proc} for each file and directory. @code{nftw} has extra
514 features over the basic @code{ftw} described above.
516 Hard links and symbolic links are followed, but a file or directory is
517 reported to @var{proc} only once, and skipped if seen again in another
518 place. One consequence of this is that @code{nftw} is safe against
519 circular linked directory structures.
521 Each @var{proc} call is @code{(@var{proc} filename statinfo flag
522 basename level)} and it should return @code{#t} to continue, or any
525 @var{filename} is the item visited, being @var{startname} plus a
526 further path and the name of the item. @var{statinfo} is the return
527 from @code{stat} on @var{filename} (@pxref{File System}).
528 @var{basename} it the item name without any path. @var{level} is an
529 integer giving the directory nesting level, starting from 0 for the
530 contents of @var{startname} (or that item itself if it's a file).
531 @var{flag} is one of the following symbols,
535 @var{filename} is a file, this includes special files like devices,
539 @var{filename} is a directory.
541 @item directory-processed
542 @var{filename} is a directory, and its contents have all been visited.
543 This flag is given instead of @code{directory} when the @code{depth}
544 option below is used.
547 An error occurred when applying @code{stat} to @var{filename}, so
548 nothing is known about it. @var{statinfo} is @code{#f} in this case.
550 @item directory-not-readable
551 @var{filename} is a directory, but one which cannot be read and hence
552 won't be recursed into.
555 @var{filename} is a dangling symbolic link. Symbolic links are
556 normally followed and their target reported, the link itself is
557 reported if the target does not exist.
559 Under the @code{physical} option described below, @code{symlink} is
560 instead given for symbolic links whose target does exist.
563 Under the @code{physical} option described below, this indicates
564 @var{filename} is a dangling symbolic link, meaning its target does
565 not exist. Without the @code{physical} option plain @code{symlink}
569 The following optional arguments can be given to modify the way
570 @code{nftw} works. Each is passed as a symbol (and @code{hash-size}
571 takes a following integer value).
575 Change to the directory containing the item before calling @var{proc}.
576 When @code{nftw} returns the original current directory is restored.
578 Under this option, generally the @var{basename} parameter should be
579 used to access the item in each @var{proc} call. The @var{filename}
580 parameter still has a path as normal and this will only be valid if
581 the @var{startname} directory was absolute.
584 Visit files ``depth first'', meaning @var{proc} is called for the
585 contents of each directory before it's called for the directory
586 itself. Normally a directory is reported first, then its contents.
588 Under this option, the @var{flag} to @var{proc} for a directory is
589 @code{directory-processed} instead of @code{directory}.
591 @item @code{hash-size @var{n}}
592 Set the size of the hash table used to track items already visited.
593 (@pxref{Hash Table Reference})
596 Don't cross a mount point, meaning only visit items on the same
597 filesystem as @var{startname}. (Ie.@: the same @code{stat:dev}.)
599 @item @code{physical}
600 Don't follow symbolic links, instead report them to @var{proc} as
601 @code{symlink}, and report dangling links as @code{stale-symlink}.
604 The return value from @code{nftw} is @code{#t} if it ran to
605 completion, or otherwise the non-@code{#t} value from @var{proc} which
608 @c For reference, one reason not to esacpe is that the current
609 @c directory is not saved and restored with dynamic-wind. Maybe
610 @c changing that would be enough to allow escaping.
612 In the current implementation, returning non-@code{#t} from @var{proc}
613 is the only valid way to terminate @code{ftw}. @var{proc} must not
614 use @code{throw} or similar to escape.
624 The functions in this section are provided by
627 (use-modules (ice-9 q))
630 This module implements queues holding arbitrary scheme objects and
631 designed for efficient first-in / first-out operations.
633 @code{make-q} creates a queue, and objects are entered and removed
634 with @code{enq!} and @code{deq!}. @code{q-push!} and @code{q-pop!}
635 can be used too, treating the front of the queue like a stack.
639 @deffn {Scheme Procedure} make-q
643 @deffn {Scheme Procedure} q? obj
644 Return @code{#t} if @var{obj} is a queue, or @code{#f} if not.
646 Note that queues are not a distinct class of objects but are
647 implemented with cons cells. For that reason certain list structures
648 can get @code{#t} from @code{q?}.
651 @deffn {Scheme Procedure} enq! q obj
652 Add @var{obj} to the rear of @var{q}, and return @var{q}.
655 @deffn {Scheme Procedure} deq! q
656 @deffnx {Scheme Procedure} q-pop! q
657 Remove and return the front element from @var{q}. If @var{q} is
658 empty, a @code{q-empty} exception is thrown.
660 @code{deq!} and @code{q-pop!} are the same operation, the two names
661 just let an application match @code{enq!} with @code{deq!}, or
662 @code{q-push!} with @code{q-pop!}.
665 @deffn {Scheme Procedure} q-push! q obj
666 Add @var{obj} to the front of @var{q}, and return @var{q}.
669 @deffn {Scheme Procedure} q-length q
670 Return the number of elements in @var{q}.
673 @deffn {Scheme Procedure} q-empty? q
674 Return true if @var{q} is empty.
677 @deffn {Scheme Procedure} q-empty-check q
678 Throw a @code{q-empty} exception if @var{q} is empty.
681 @deffn {Scheme Procedure} q-front q
682 Return the first element of @var{q} (without removing it). If @var{q}
683 is empty, a @code{q-empty} exception is thrown.
686 @deffn {Scheme Procedure} q-rear q
687 Return the last element of @var{q} (without removing it). If @var{q}
688 is empty, a @code{q-empty} exception is thrown.
691 @deffn {Scheme Procedure} q-remove! q obj
692 Remove all occurences of @var{obj} from @var{q}, and return @var{q}.
693 @var{obj} is compared to queue elements using @code{eq?}.
697 @cindex @code{q-empty}
698 The @code{q-empty} exceptions described above are thrown just as
699 @code{(throw 'q-empty)}, there's no message etc like an error throw.
701 A queue is implemented as a cons cell, the @code{car} containing a
702 list of queued elements, and the @code{cdr} being the last cell in
703 that list (for ease of enqueuing).
706 (@var{list} . @var{last-cell})
710 If the queue is empty, @var{list} is the empty list and
711 @var{last-cell} is @code{#f}.
713 An application can directly access the queue list if desired, for
714 instance to search the elements or to insert at a specific point.
716 @deffn {Scheme Procedure} sync-q! q
717 Recompute the @var{last-cell} field in @var{q}.
719 All the operations above maintain @var{last-cell} as described, so
720 normally there's no need for @code{sync-q!}. But if an application
721 modifies the queue @var{list} then it must either maintain
722 @var{last-cell} similarly, or call @code{sync-q!} to recompute it.
727 @c TeX-master: "guile.texi"