Commit | Line | Data |
---|---|---|
2da09c3f MV |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004 | |
4 | @c Free Software Foundation, Inc. | |
5 | @c See the file guile.texi for copying conditions. | |
6 | ||
a0e07ba4 NJ |
7 | @page |
8 | @node Pretty Printing | |
9 | @chapter Pretty Printing | |
10 | ||
11 | @c FIXME::martin: Review me! | |
12 | ||
13 | @cindex pretty printing | |
14 | The module @code{(ice-9 pretty-print)} provides the procedure | |
15 | @code{pretty-print}, which provides nicely formatted output of Scheme | |
16 | objects. This is especially useful for deeply nested or complex data | |
17 | structures, such as lists and vectors. | |
18 | ||
19 | The module is loaded by simply saying. | |
20 | ||
21 | @lisp | |
22 | (use-modules (ice-9 pretty-print)) | |
23 | @end lisp | |
24 | ||
25 | This makes the procedure @code{pretty-print} available. As an example | |
26 | how @code{pretty-print} will format the output, see the following: | |
27 | ||
28 | @lisp | |
29 | (pretty-print '(define (foo) (lambda (x) | |
385dbc8b KR |
30 | (cond ((zero? x) #t) ((negative? x) -x) (else |
31 | (if (= x 1) 2 (* x x x))))))) | |
a0e07ba4 NJ |
32 | @print{} |
33 | (define (foo) | |
34 | (lambda (x) | |
35 | (cond ((zero? x) #t) | |
36 | ((negative? x) -x) | |
37 | (else (if (= x 1) 2 (* x x x)))))) | |
38 | @end lisp | |
39 | ||
385dbc8b | 40 | @deffn {Scheme Procedure} pretty-print obj [port] [keyword-options] |
a0e07ba4 NJ |
41 | Print the textual representation of the Scheme object @var{obj} to |
42 | @var{port}. @var{port} defaults to the current output port, if not | |
43 | given. | |
385dbc8b KR |
44 | |
45 | The further @var{keyword-options} are keywords and parameters as | |
46 | follows, | |
47 | ||
48 | @table @asis | |
49 | @item @nicode{#:display?} @var{flag} | |
50 | If @var{flag} is true then print using @code{display}. The default is | |
51 | @code{#f} which means use @code{write} style. (@pxref{Writing}) | |
52 | ||
53 | @item @nicode{#:per-line-prefix} @var{string} | |
54 | Print the given @var{string} as a prefix on each line. The default is | |
55 | no prefix. | |
56 | ||
57 | @item @nicode{#:width} @var{columns} | |
58 | Print within the given @var{columns}. The default is 79. | |
59 | @end table | |
a0e07ba4 NJ |
60 | @end deffn |
61 | ||
62 | Beware: Since @code{pretty-print} uses it's own write procedure, it's | |
63 | output will not be the same as for example the output of @code{write}. | |
64 | Consider the following example. | |
65 | ||
66 | @lisp | |
67 | (write (lambda (x) x)) | |
68 | @print{} | |
69 | #<procedure #f (x)> | |
70 | ||
71 | (pretty-print (lambda (x) x)) | |
72 | @print{} | |
73 | #[procedure] | |
74 | @end lisp | |
75 | ||
76 | The reason is that @code{pretty-print} does not know as much about | |
77 | Guile's object types as the builtin procedures. This is particularly | |
78 | important for smobs, for which a write procedure can be defined and be | |
79 | used by @code{write}, but not by @code{pretty-print}. | |
80 | ||
2a946b44 | 81 | |
a0e07ba4 NJ |
82 | @page |
83 | @node Formatted Output | |
84 | @chapter Formatted Output | |
85 | ||
86 | @c FIXME::martin: Review me! | |
87 | ||
88 | @cindex format | |
89 | @cindex formatted output | |
90 | Outputting messages or other texts which are composed of literal | |
91 | strings, variable contents, newlines and other formatting can be | |
92 | cumbersome, when only the standard procedures like @code{display}, | |
93 | @code{write} and @code{newline} are available. Additionally, one | |
94 | often wants to collect the output in strings. With the standard | |
95 | routines, the user is required to set up a string port, add this port | |
96 | as a parameter to the output procedure calls and then retrieve the | |
97 | resulting string from the string port. | |
98 | ||
99 | The @code{format} procedure, to be found in module @code{(ice-9 | |
100 | format)}, can do all this, and even more. If you are a C programmer, | |
101 | you can think of this procedure as Guile's @code{fprintf}. | |
102 | ||
8f85c0c6 | 103 | @deffn {Scheme Procedure} format destination format-string args @dots{} |
a0e07ba4 NJ |
104 | The first parameter is the @var{destination}, it determines where the |
105 | output of @code{format} will go. | |
106 | ||
107 | @table @asis | |
108 | @item @code{#t} | |
109 | Send the formatted output to the current output port and return | |
110 | @code{#t}. | |
111 | ||
112 | @item @code{#f} | |
113 | Return the formatted output as a string. | |
114 | ||
115 | @item Any number value | |
116 | Send the formatted output to the current error port and return | |
117 | @code{#t}. | |
118 | ||
119 | @item A valid output port | |
120 | Send the formatted output to the port @var{destination} and return | |
121 | @code{#t}. | |
122 | @end table | |
123 | ||
124 | The second parameter is the format string. It has a similar function | |
125 | to the format string in calls to @code{printf} or @code{fprintf} in C. | |
126 | It is output to the specified destination, but all escape sequences | |
127 | are replaced by the results of formatting the corresponding sequence. | |
128 | ||
129 | Note that escape sequences are marked with the character @code{~} | |
130 | (tilde), and not with a @code{%} (percent sign), as in C. | |
131 | ||
132 | The escape sequences in the following table are supported. When there | |
133 | appears ``corresponding @var{arg}', that means any of the additional | |
134 | arguments, after dropping all arguments which have been used up by | |
135 | escape sequences which have been processed earlier. Some of the | |
136 | format characters (the characters following the tilde) can be prefixed | |
137 | by @code{:}, @code{@@}, or @code{:@@}, to modify the behaviour of the | |
138 | format character. How the modified behaviour differs from the default | |
139 | behaviour is described for every character in the table where | |
140 | appropriate. | |
141 | ||
142 | @table @code | |
143 | @item ~~ | |
144 | Output a single @code{~} (tilde) character. | |
145 | ||
146 | @item ~% | |
147 | Output a newline character, thus advancing to the next output line. | |
148 | ||
149 | @item ~& | |
150 | Start a new line, that is, output a newline character if not already | |
40f316d0 | 151 | at the start of a line. |
a0e07ba4 NJ |
152 | |
153 | @item ~_ | |
154 | Output a single space character. | |
155 | ||
156 | @item ~/ | |
157 | Output a single tabulator character. | |
158 | ||
159 | @item ~| | |
160 | Output a page separator (formfeed) character. | |
161 | ||
162 | @item ~t | |
163 | Advance to the next tabulator position. | |
164 | ||
165 | @item ~y | |
85a9b4ed | 166 | Pretty-print the corresponding @var{arg}. |
a0e07ba4 NJ |
167 | |
168 | @item ~a | |
169 | Output the corresponding @var{arg} like @code{display}. | |
170 | ||
171 | @item ~s | |
172 | Output the corresponding @var{arg} like @code{write}. | |
173 | ||
174 | @item ~d | |
175 | Output the corresponding @var{arg} as a decimal number. | |
176 | ||
177 | @item ~x | |
178 | Output the corresponding @var{arg} as a hexadecimal number. | |
179 | ||
180 | @item ~o | |
181 | Output the corresponding @var{arg} as an octal number. | |
182 | ||
183 | @item ~b | |
184 | Output the corresponding @var{arg} as a binary number. | |
185 | ||
186 | @item ~r | |
187 | Output the corresponding @var{arg} as a number word, e.g. 10 prints as | |
188 | @code{ten}. If prefixed with @code{:}, @code{tenth} is printed, if | |
85a9b4ed | 189 | prefixed with @code{:@@}, Roman numbers are printed. |
a0e07ba4 NJ |
190 | |
191 | @item ~f | |
192 | Output the corresponding @var{arg} as a fixed format floating point | |
193 | number, such as @code{1.34}. | |
194 | ||
195 | @item ~e | |
196 | Output the corresponding @var{arg} in exponential notation, such as | |
197 | @code{1.34E+0}. | |
198 | ||
199 | @item ~g | |
40f316d0 MG |
200 | This works either like @code{~f} or like @code{~e}, whichever produces |
201 | less characters to be written. | |
a0e07ba4 NJ |
202 | |
203 | @item ~$ | |
204 | Like @code{~f}, but only with two digits after the decimal point. | |
205 | ||
206 | @item ~i | |
207 | Output the corresponding @var{arg} as a complex number. | |
208 | ||
209 | @item ~c | |
210 | Output the corresponding @var{arg} as a character. If prefixed with | |
211 | @code{@@}, it is printed like with @code{write}. If prefixed with | |
212 | @code{:}, control characters are treated specially, for example | |
213 | @code{#\newline} will be printed as @code{^J}. | |
214 | ||
215 | @item ~p | |
216 | ``Plural''. If the corresponding @var{arg} is 1, nothing is printed | |
217 | (or @code{y} if prefixed with @code{@@} or @code{:@@}), otherwise | |
218 | @code{s} is printed (or @code{ies} if prefixed with @code{@@} or | |
219 | @code{:@@}). | |
220 | ||
221 | @item ~?, ~k | |
222 | Take the corresponding argument as a format string, and the following | |
223 | argument as a list of values. Then format the values with respect to | |
224 | the format string. | |
225 | ||
226 | @item ~! | |
227 | Flush the output to the output port. | |
228 | ||
229 | @item ~#\newline (tilde-newline) | |
230 | @c FIXME::martin: I don't understand this from the source. | |
231 | Continuation lines. | |
232 | ||
233 | @item ~* | |
234 | Argument jumping. Navigate in the argument list as specified by the | |
235 | corresponding argument. If prefixed with @code{:}, jump backwards in | |
236 | the argument list, if prefixed by @code{:@@}, jump to the parameter | |
237 | with the absolute index, otherwise jump forward in the argument list. | |
238 | ||
239 | @item ~( | |
240 | Case conversion begin. If prefixed by @code{:}, the following output | |
241 | string will be capitalized, if prefixed by @code{@@}, the first | |
242 | character will be capitalized, if prefixed by @code{:@@} it will be | |
243 | upcased and otherwise it will be downcased. Conversion stops when the | |
244 | ``Case conversion end'' @code{~)}sequence is encountered. | |
245 | ||
246 | @item ~) | |
247 | Case conversion end. Stop any case conversion currently in effect. | |
248 | ||
249 | @item ~[ | |
250 | @c FIXME::martin: I don't understand this from the source. | |
251 | Conditional begin. | |
252 | ||
253 | @item ~; | |
254 | @c FIXME::martin: I don't understand this from the source. | |
255 | Conditional separator. | |
256 | ||
257 | @item ~] | |
258 | @c FIXME::martin: I don't understand this from the source. | |
259 | Conditional end. | |
260 | ||
261 | @item ~@{ | |
262 | @c FIXME::martin: I don't understand this from the source. | |
263 | Iteration begin. | |
264 | ||
265 | @item ~@} | |
266 | @c FIXME::martin: I don't understand this from the source. | |
267 | Iteration end. | |
268 | ||
269 | @item ~^ | |
270 | @c FIXME::martin: I don't understand this from the source. | |
271 | Up and out. | |
272 | ||
273 | @item ~' | |
274 | @c FIXME::martin: I don't understand this from the source. | |
275 | Character parameter. | |
276 | ||
277 | @item ~0 @dots{} ~9, ~-, ~+ | |
278 | @c FIXME::martin: I don't understand this from the source. | |
279 | Numeric parameter. | |
280 | ||
281 | @item ~v | |
282 | @c FIXME::martin: I don't understand this from the source. | |
283 | Variable parameter from next argument. | |
284 | ||
285 | @item ~# | |
286 | Parameter is number of remaining args. The number of the remaining | |
287 | arguments is prepended to the list of unprocessed arguments. | |
288 | ||
289 | @item ~, | |
290 | @c FIXME::martin: I don't understand this from the source. | |
291 | Parameter separators. | |
292 | ||
293 | @item ~q | |
294 | Inquiry message. Insert a copyright message into the output. | |
295 | @end table | |
296 | ||
297 | If any type conversions should fail (for example when using an escape | |
298 | sequence for number output, but the argument is a string), an error | |
299 | will be signalled. | |
300 | @end deffn | |
301 | ||
302 | You may have noticed that Guile contains a @code{format} procedure | |
303 | even when the module @code{(ice-9 format)} is not loaded. The default | |
304 | @code{format} procedure does not support all escape sequences | |
305 | documented in this chapter, and will signal an error if you try to use | |
306 | one of them. The reason for providing two versions of @code{format} | |
307 | is that the full-featured module is fairly large and requires some | |
308 | time to get loaded. So the Guile maintainers decided not to load the | |
309 | large version of @code{format} by default, so that the start-up time | |
310 | of the interpreter is not unnecessarily increased. | |
311 | ||
312 | ||
2a946b44 NJ |
313 | @page |
314 | @node Rx Regexps | |
315 | @chapter The Rx Regular Expression Library | |
316 | ||
317 | [FIXME: this is taken from Gary and Mark's quick summaries and should be | |
318 | reviewed and expanded. Rx is pretty stable, so could already be done!] | |
319 | ||
320 | @cindex rx | |
321 | @cindex finite automaton | |
322 | ||
323 | The @file{guile-lang-allover} package provides an interface to Tom | |
324 | Lord's Rx library (currently only to POSIX regular expressions). Use of | |
325 | the library requires a two step process: compile a regular expression | |
326 | into an efficient structure, then use the structure in any number of | |
327 | string comparisons. | |
328 | ||
329 | For example, given the regular expression @samp{abc.} (which matches any | |
330 | string containing @samp{abc} followed by any single character): | |
331 | ||
332 | @smalllisp | |
333 | guile> @kbd{(define r (regcomp "abc."))} | |
334 | guile> @kbd{r} | |
335 | #<rgx abc.> | |
336 | guile> @kbd{(regexec r "abc")} | |
337 | #f | |
338 | guile> @kbd{(regexec r "abcd")} | |
339 | #((0 . 4)) | |
340 | guile> | |
341 | @end smalllisp | |
342 | ||
343 | The definitions of @code{regcomp} and @code{regexec} are as follows: | |
344 | ||
345 | @deffn {Scheme Procedure} regcomp pattern [flags] | |
346 | Compile the regular expression pattern using POSIX rules. Flags is | |
347 | optional and should be specified using symbolic names: | |
348 | @defvar REG_EXTENDED | |
349 | use extended POSIX syntax | |
350 | @end defvar | |
351 | @defvar REG_ICASE | |
352 | use case-insensitive matching | |
353 | @end defvar | |
354 | @defvar REG_NEWLINE | |
355 | allow anchors to match after newline characters in the | |
356 | string and prevents @code{.} or @code{[^...]} from matching newlines. | |
357 | @end defvar | |
358 | ||
359 | The @code{logior} procedure can be used to combine multiple flags. | |
360 | The default is to use | |
361 | POSIX basic syntax, which makes @code{+} and @code{?} literals and @code{\+} | |
362 | and @code{\?} | |
363 | operators. Backslashes in @var{pattern} must be escaped if specified in a | |
364 | literal string e.g., @code{"\\(a\\)\\?"}. | |
365 | @end deffn | |
366 | ||
367 | @deffn {Scheme Procedure} regexec regex string [match-pick] [flags] | |
368 | Match @var{string} against the compiled POSIX regular expression | |
369 | @var{regex}. | |
370 | @var{match-pick} and @var{flags} are optional. Possible flags (which can be | |
371 | combined using the logior procedure) are: | |
372 | ||
373 | @defvar REG_NOTBOL | |
374 | The beginning of line operator won't match the beginning of | |
375 | @var{string} (presumably because it's not the beginning of a line) | |
376 | @end defvar | |
377 | ||
378 | @defvar REG_NOTEOL | |
379 | Similar to REG_NOTBOL, but prevents the end of line operator | |
380 | from matching the end of @var{string}. | |
381 | @end defvar | |
382 | ||
383 | If no match is possible, regexec returns #f. Otherwise @var{match-pick} | |
384 | determines the return value: | |
385 | ||
386 | @code{#t} or unspecified: a newly-allocated vector is returned, | |
387 | containing pairs with the indices of the matched part of @var{string} and any | |
388 | substrings. | |
389 | ||
390 | @code{""}: a list is returned: the first element contains a nested list | |
391 | with the matched part of @var{string} surrounded by the the unmatched parts. | |
392 | Remaining elements are matched substrings (if any). All returned | |
393 | substrings share memory with @var{string}. | |
394 | ||
395 | @code{#f}: regexec returns #t if a match is made, otherwise #f. | |
396 | ||
397 | vector: the supplied vector is returned, with the first element replaced | |
398 | by a pair containing the indices of the matched portion of @var{string} and | |
399 | further elements replaced by pairs containing the indices of matched | |
400 | substrings (if any). | |
401 | ||
402 | list: a list will be returned, with each member of the list | |
403 | specified by a code in the corresponding position of the supplied list: | |
404 | ||
405 | a number: the numbered matching substring (0 for the entire match). | |
406 | ||
407 | @code{#\<}: the beginning of @var{string} to the beginning of the part matched | |
408 | by regex. | |
409 | ||
410 | @code{#\>}: the end of the matched part of @var{string} to the end of | |
411 | @var{string}. | |
412 | ||
413 | @code{#\c}: the "final tag", which seems to be associated with the "cut | |
414 | operator", which doesn't seem to be available through the posix | |
415 | interface. | |
416 | ||
417 | e.g., @code{(list #\< 0 1 #\>)}. The returned substrings share memory with | |
418 | @var{string}. | |
419 | @end deffn | |
420 | ||
421 | Here are some other procedures that might be used when using regular | |
422 | expressions: | |
423 | ||
424 | @deffn {Scheme Procedure} compiled-regexp? obj | |
425 | Test whether obj is a compiled regular expression. | |
426 | @end deffn | |
427 | ||
428 | @deffn {Scheme Procedure} regexp->dfa regex [flags] | |
429 | @end deffn | |
430 | ||
431 | @deffn {Scheme Procedure} dfa-fork dfa | |
432 | @end deffn | |
433 | ||
434 | @deffn {Scheme Procedure} reset-dfa! dfa | |
435 | @end deffn | |
436 | ||
437 | @deffn {Scheme Procedure} dfa-final-tag dfa | |
438 | @end deffn | |
439 | ||
440 | @deffn {Scheme Procedure} dfa-continuable? dfa | |
441 | @end deffn | |
442 | ||
443 | @deffn {Scheme Procedure} advance-dfa! dfa string | |
444 | @end deffn | |
445 | ||
446 | ||
6da1534c KR |
447 | @node File Tree Walk |
448 | @chapter File Tree Walk | |
449 | @cindex file tree walk | |
450 | ||
451 | The functions in this section traverse a tree of files and | |
452 | directories, in a fashion similar to the C @code{ftw} and @code{nftw} | |
453 | routines (@pxref{Working with Directory Trees,,, libc, GNU C Library | |
454 | Reference Manual}). | |
455 | ||
456 | @example | |
457 | (use-modules (ice-9 ftw)) | |
458 | @end example | |
459 | @sp 1 | |
460 | ||
461 | @defun ftw startname proc ['hash-size n] | |
462 | Walk the filesystem tree descending from @var{startname}, calling | |
463 | @var{proc} for each file and directory. | |
464 | ||
465 | Hard links and symbolic links are followed. A file or directory is | |
466 | reported to @var{proc} only once, and skipped if seen again in another | |
467 | place. One consequence of this is that @code{ftw} is safe against | |
468 | circularly linked directory structures. | |
469 | ||
470 | Each @var{proc} call is @code{(@var{proc} filename statinfo flag)} and | |
471 | it should return @code{#t} to continue, or any other value to stop. | |
472 | ||
473 | @var{filename} is the item visited, being @var{startname} plus a | |
474 | further path and the name of the item. @var{statinfo} is the return | |
475 | from @code{stat} (@pxref{File System}) on @var{filename}. @var{flag} | |
476 | is one of the following symbols, | |
477 | ||
478 | @table @code | |
479 | @item regular | |
480 | @var{filename} is a file, this includes special files like devices, | |
481 | named pipes, etc. | |
482 | ||
483 | @item directory | |
484 | @var{filename} is a directory. | |
485 | ||
486 | @item invalid-stat | |
487 | An error occurred when calling @code{stat}, so nothing is known. | |
488 | @var{statinfo} is @code{#f} in this case. | |
489 | ||
490 | @item directory-not-readable | |
491 | @var{filename} is a directory, but one which cannot be read and hence | |
492 | won't be recursed into. | |
493 | ||
494 | @item symlink | |
495 | @var{filename} is a dangling symbolic link. Symbolic links are | |
496 | normally followed and their target reported, the link itself is | |
497 | reported if the target does not exist. | |
498 | @end table | |
499 | ||
500 | The return value from @code{ftw} is @code{#t} if it ran to completion, | |
501 | or otherwise the non-@code{#t} value from @var{proc} which caused the | |
502 | stop. | |
503 | ||
504 | Optional argument symbol @code{hash-size} and an integer can be given | |
505 | to set the size of the hash table used to track items already visited. | |
506 | (@pxref{Hash Table Reference}) | |
507 | ||
508 | @c Actually, it's probably safe to escape from ftw, just need to | |
509 | @c check it. | |
510 | @c | |
511 | In the current implementation, returning non-@code{#t} from @var{proc} | |
512 | is the only valid way to terminate @code{ftw}. @var{proc} must not | |
513 | use @code{throw} or similar to escape. | |
514 | @end defun | |
515 | ||
516 | ||
517 | @defun nftw startname proc ['chdir] ['depth] ['hash-size n] ['mount] ['physical] | |
518 | Walk the filesystem tree starting at @var{startname}, calling | |
519 | @var{proc} for each file and directory. @code{nftw} has extra | |
520 | features over the basic @code{ftw} described above. | |
521 | ||
522 | Hard links and symbolic links are followed, but a file or directory is | |
523 | reported to @var{proc} only once, and skipped if seen again in another | |
524 | place. One consequence of this is that @code{nftw} is safe against | |
525 | circular linked directory structures. | |
526 | ||
527 | Each @var{proc} call is @code{(@var{proc} filename statinfo flag | |
528 | basename level)} and it should return @code{#t} to continue, or any | |
529 | other value to stop. | |
530 | ||
531 | @var{filename} is the item visited, being @var{startname} plus a | |
532 | further path and the name of the item. @var{statinfo} is the return | |
533 | from @code{stat} on @var{filename} (@pxref{File System}). | |
534 | @var{basename} it the item name without any path. @var{level} is an | |
535 | integer giving the directory nesting level, starting from 0 for the | |
536 | contents of @var{startname} (or that item itself if it's a file). | |
537 | @var{flag} is one of the following symbols, | |
538 | ||
539 | @table @code | |
540 | @item regular | |
541 | @var{filename} is a file, this includes special files like devices, | |
542 | named pipes, etc. | |
543 | ||
544 | @item directory | |
545 | @var{filename} is a directory. | |
546 | ||
547 | @item directory-processed | |
548 | @var{filename} is a directory, and its contents have all been visited. | |
549 | This flag is given instead of @code{directory} when the @code{depth} | |
550 | option below is used. | |
551 | ||
552 | @item invalid-stat | |
553 | An error occurred when applying @code{stat} to @var{filename}, so | |
554 | nothing is known about it. @var{statinfo} is @code{#f} in this case. | |
555 | ||
556 | @item directory-not-readable | |
557 | @var{filename} is a directory, but one which cannot be read and hence | |
558 | won't be recursed into. | |
559 | ||
560 | @item symlink | |
561 | @var{filename} is a dangling symbolic link. Symbolic links are | |
562 | normally followed and their target reported, the link itself is | |
563 | reported if the target does not exist. | |
564 | ||
565 | Under the @code{physical} option described below, @code{symlink} is | |
566 | instead given for symbolic links whose target does exist. | |
567 | ||
568 | @item stale-symlink | |
569 | Under the @code{physical} option described below, this indicates | |
570 | @var{filename} is a dangling symbolic link, meaning its target does | |
571 | not exist. Without the @code{physical} option plain @code{symlink} | |
572 | indicates this. | |
573 | @end table | |
574 | ||
575 | The following optional arguments can be given to modify the way | |
576 | @code{nftw} works. Each is passed as a symbol (and @code{hash-size} | |
577 | takes a following integer value). | |
578 | ||
579 | @table @asis | |
580 | @item @code{chdir} | |
581 | Change to the directory containing the item before calling @var{proc}. | |
582 | When @code{nftw} returns the original current directory is restored. | |
583 | ||
584 | Under this option, generally the @var{basename} parameter should be | |
585 | used to access the item in each @var{proc} call. The @var{filename} | |
586 | parameter still has a path as normal and this will only be valid if | |
587 | the @var{startname} directory was absolute. | |
588 | ||
589 | @item @code{depth} | |
590 | Visit files ``depth first'', meaning @var{proc} is called for the | |
591 | contents of each directory before it's called for the directory | |
592 | itself. Normally a directory is reported first, then its contents. | |
593 | ||
594 | Under this option, the @var{flag} to @var{proc} for a directory is | |
595 | @code{directory-processed} instead of @code{directory}. | |
596 | ||
597 | @item @code{hash-size @var{n}} | |
598 | Set the size of the hash table used to track items already visited. | |
599 | (@pxref{Hash Table Reference}) | |
600 | ||
601 | @item @code{mount} | |
602 | Don't cross a mount point, meaning only visit items on the same | |
603 | filesystem as @var{startname}. (Ie.@: the same @code{stat:dev}.) | |
604 | ||
605 | @item @code{physical} | |
606 | Don't follow symbolic links, instead report them to @var{proc} as | |
607 | @code{symlink}, and report dangling links as @code{stale-symlink}. | |
608 | @end table | |
609 | ||
610 | The return value from @code{nftw} is @code{#t} if it ran to | |
611 | completion, or otherwise the non-@code{#t} value from @var{proc} which | |
612 | caused the stop. | |
613 | ||
614 | @c For reference, one reason not to esacpe is that the current | |
615 | @c directory is not saved and restored with dynamic-wind. Maybe | |
616 | @c changing that would be enough to allow escaping. | |
617 | @c | |
618 | In the current implementation, returning non-@code{#t} from @var{proc} | |
619 | is the only valid way to terminate @code{ftw}. @var{proc} must not | |
620 | use @code{throw} or similar to escape. | |
621 | @end defun | |
622 | ||
623 | ||
2370f809 KR |
624 | @node Queues |
625 | @chapter Queues | |
626 | @cindex Queues | |
627 | @tindex Queues | |
628 | ||
629 | @noindent | |
630 | The functions in this section are provided by | |
631 | ||
632 | @example | |
633 | (use-modules (ice-9 q)) | |
634 | @end example | |
635 | ||
636 | This module implements queues holding arbitrary scheme objects and | |
637 | designed for efficient first-in / first-out operations. | |
638 | ||
639 | @code{make-q} creates a queue, and objects are entered and removed | |
640 | with @code{enq!} and @code{deq!}. @code{q-push!} and @code{q-pop!} | |
641 | can be used too, treating the front of the queue like a stack. | |
642 | ||
643 | @sp 1 | |
644 | ||
645 | @deffn {Scheme Procedure} make-q | |
646 | Return a new queue. | |
647 | @end deffn | |
648 | ||
649 | @deffn {Scheme Procedure} q? obj | |
650 | Return @code{#t} if @var{obj} is a queue, or @code{#f} if not. | |
651 | ||
652 | Note that queues are not a distinct class of objects but are | |
653 | implemented with cons cells. For that reason certain list structures | |
654 | can get @code{#t} from @code{q?}. | |
655 | @end deffn | |
656 | ||
657 | @deffn {Scheme Procedure} enq! q obj | |
658 | Add @var{obj} to the rear of @var{q}, and return @var{q}. | |
659 | @end deffn | |
660 | ||
661 | @deffn {Scheme Procedure} deq! q | |
662 | @deffnx {Scheme Procedure} q-pop! q | |
663 | Remove and return the front element from @var{q}. If @var{q} is | |
664 | empty, a @code{q-empty} exception is thrown. | |
665 | ||
666 | @code{deq!} and @code{q-pop!} are the same operation, the two names | |
667 | just let an application match @code{enq!} with @code{deq!}, or | |
668 | @code{q-push!} with @code{q-pop!}. | |
669 | @end deffn | |
670 | ||
671 | @deffn {Scheme Procedure} q-push! q obj | |
672 | Add @var{obj} to the front of @var{q}, and return @var{q}. | |
673 | @end deffn | |
674 | ||
675 | @deffn {Scheme Procedure} q-length q | |
676 | Return the number of elements in @var{q}. | |
677 | @end deffn | |
678 | ||
679 | @deffn {Scheme Procedure} q-empty? q | |
680 | Return true if @var{q} is empty. | |
681 | @end deffn | |
682 | ||
683 | @deffn {Scheme Procedure} q-empty-check q | |
684 | Throw a @code{q-empty} exception if @var{q} is empty. | |
685 | @end deffn | |
686 | ||
687 | @deffn {Scheme Procedure} q-front q | |
688 | Return the first element of @var{q} (without removing it). If @var{q} | |
689 | is empty, a @code{q-empty} exception is thrown. | |
690 | @end deffn | |
691 | ||
692 | @deffn {Scheme Procedure} q-rear q | |
693 | Return the last element of @var{q} (without removing it). If @var{q} | |
694 | is empty, a @code{q-empty} exception is thrown. | |
695 | @end deffn | |
696 | ||
697 | @deffn {Scheme Procedure} q-remove! q obj | |
698 | Remove all occurences of @var{obj} from @var{q}, and return @var{q}. | |
699 | @var{obj} is compared to queue elements using @code{eq?}. | |
700 | @end deffn | |
701 | ||
702 | @sp 1 | |
703 | @cindex @code{q-empty} | |
704 | The @code{q-empty} exceptions described above are thrown just as | |
705 | @code{(throw 'q-empty)}, there's no message etc like an error throw. | |
706 | ||
707 | A queue is implemented as a cons cell, the @code{car} containing a | |
708 | list of queued elements, and the @code{cdr} being the last cell in | |
709 | that list (for ease of enqueuing). | |
710 | ||
711 | @example | |
712 | (@var{list} . @var{last-cell}) | |
713 | @end example | |
714 | ||
715 | @noindent | |
716 | If the queue is empty, @var{list} is the empty list and | |
717 | @var{last-cell} is @code{#f}. | |
718 | ||
719 | An application can directly access the queue list if desired, for | |
720 | instance to search the elements or to insert at a specific point. | |
721 | ||
722 | @deffn {Scheme Procedure} sync-q! q | |
723 | Recompute the @var{last-cell} field in @var{q}. | |
724 | ||
725 | All the operations above maintain @var{last-cell} as described, so | |
726 | normally there's no need for @code{sync-q!}. But if an application | |
727 | modifies the queue @var{list} then it must either maintain | |
728 | @var{last-cell} similarly, or call @code{sync-q!} to recompute it. | |
729 | @end deffn | |
730 | ||
731 | ||
a0e07ba4 NJ |
732 | @c Local Variables: |
733 | @c TeX-master: "guile.texi" | |
734 | @c End: |