misc-modules.texi 60 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795
  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, 2006, 2009,
  4. @c 2010, 2011, 2012 Free Software Foundation, Inc.
  5. @c See the file guile.texi for copying conditions.
  6. @node Pretty Printing
  7. @section Pretty Printing
  8. @c FIXME::martin: Review me!
  9. @cindex pretty printing
  10. The module @code{(ice-9 pretty-print)} provides the procedure
  11. @code{pretty-print}, which provides nicely formatted output of Scheme
  12. objects. This is especially useful for deeply nested or complex data
  13. structures, such as lists and vectors.
  14. The module is loaded by entering the following:
  15. @lisp
  16. (use-modules (ice-9 pretty-print))
  17. @end lisp
  18. This makes the procedure @code{pretty-print} available. As an example
  19. how @code{pretty-print} will format the output, see the following:
  20. @lisp
  21. (pretty-print '(define (foo) (lambda (x)
  22. (cond ((zero? x) #t) ((negative? x) -x) (else
  23. (if (= x 1) 2 (* x x x)))))))
  24. @print{}
  25. (define (foo)
  26. (lambda (x)
  27. (cond ((zero? x) #t)
  28. ((negative? x) -x)
  29. (else (if (= x 1) 2 (* x x x))))))
  30. @end lisp
  31. @deffn {Scheme Procedure} pretty-print obj [port] [keyword-options]
  32. Print the textual representation of the Scheme object @var{obj} to
  33. @var{port}. @var{port} defaults to the current output port, if not
  34. given.
  35. The further @var{keyword-options} are keywords and parameters as
  36. follows,
  37. @table @asis
  38. @item @nicode{#:display?} @var{flag}
  39. If @var{flag} is true then print using @code{display}. The default is
  40. @code{#f} which means use @code{write} style. (@pxref{Writing})
  41. @item @nicode{#:per-line-prefix} @var{string}
  42. Print the given @var{string} as a prefix on each line. The default is
  43. no prefix.
  44. @item @nicode{#:width} @var{columns}
  45. Print within the given @var{columns}. The default is 79.
  46. @end table
  47. @end deffn
  48. @cindex truncated printing
  49. Also exported by the @code{(ice-9 pretty-print)} module is
  50. @code{truncated-print}, a procedure to print Scheme datums, truncating
  51. the output to a certain number of characters. This is useful when you
  52. need to present an arbitrary datum to the user, but you only have one
  53. line in which to do so.
  54. @lisp
  55. (define exp '(a b #(c d e) f . g))
  56. (truncated-print exp #:width 10) (newline)
  57. @print{} (a b . #)
  58. (truncated-print exp #:width 15) (newline)
  59. @print{} (a b # f . g)
  60. (truncated-print exp #:width 18) (newline)
  61. @print{} (a b #(c ...) . #)
  62. (truncated-print exp #:width 20) (newline)
  63. @print{} (a b #(c d e) f . g)
  64. (truncated-print "The quick brown fox" #:width 20) (newline)
  65. @print{} "The quick brown..."
  66. (truncated-print (current-module) #:width 20) (newline)
  67. @print{} #<directory (gui...>
  68. @end lisp
  69. @code{truncated-print} will not output a trailing newline. If an expression does
  70. not fit in the given width, it will be truncated -- possibly
  71. ellipsized@footnote{On Unicode-capable ports, the ellipsis is represented by
  72. character `HORIZONTAL ELLIPSIS' (U+2026), otherwise it is represented by three
  73. dots.}, or in the worst case, displayed as @nicode{#}.
  74. @deffn {Scheme Procedure} truncated-print obj [port] [keyword-options]
  75. Print @var{obj}, truncating the output, if necessary, to make it fit
  76. into @var{width} characters. By default, @var{obj} will be printed using
  77. @code{write}, though that behavior can be overridden via the
  78. @var{display?} keyword argument.
  79. The default behaviour is to print depth-first, meaning that the entire
  80. remaining width will be available to each sub-expression of @var{obj} --
  81. e.g., if @var{obj} is a vector, each member of @var{obj}. One can attempt to
  82. ``ration'' the available width, trying to allocate it equally to each
  83. sub-expression, via the @var{breadth-first?} keyword argument.
  84. The further @var{keyword-options} are keywords and parameters as
  85. follows,
  86. @table @asis
  87. @item @nicode{#:display?} @var{flag}
  88. If @var{flag} is true then print using @code{display}. The default is
  89. @code{#f} which means use @code{write} style. (@pxref{Writing})
  90. @item @nicode{#:width} @var{columns}
  91. Print within the given @var{columns}. The default is 79.
  92. @item @nicode{#:breadth-first?} @var{flag}
  93. If @var{flag} is true, then allocate the available width breadth-first
  94. among elements of a compound data structure (list, vector, pair,
  95. etc.). The default is @code{#f} which means that any element is
  96. allowed to consume all of the available width.
  97. @end table
  98. @end deffn
  99. @node Formatted Output
  100. @section Formatted Output
  101. @cindex formatted output
  102. @c For reference, in this section escapes like ~a are given in
  103. @c @nicode, to give code font in TeX etc, but leave them unadorned in
  104. @c Info.
  105. @c
  106. @c The idea is to reduce clutter around what's shown, and avoid any
  107. @c possible confusion over whether the ` ' quotes are part of what
  108. @c should be entered. (In particular for instance of course ' is
  109. @c meaningful in a format string, introducing a char parameter).
  110. The @code{format} function is a powerful way to print numbers, strings
  111. and other objects together with literal text under the control of a
  112. format string. This function is available from
  113. @example
  114. (use-modules (ice-9 format))
  115. @end example
  116. A format string is generally more compact and easier than using just
  117. the standard procedures like @code{display}, @code{write} and
  118. @code{newline}. Parameters in the output string allow various output
  119. styles, and parameters can be taken from the arguments for runtime
  120. flexibility.
  121. @code{format} is similar to the Common Lisp procedure of the same
  122. name, but it's not identical and doesn't have quite all the features
  123. found in Common Lisp.
  124. C programmers will note the similarity between @code{format} and
  125. @code{printf}, though escape sequences are marked with @nicode{~}
  126. instead of @nicode{%}, and are more powerful.
  127. @sp 1
  128. @deffn {Scheme Procedure} format dest fmt arg @dots{}
  129. Write output specified by the @var{fmt} string to @var{dest}.
  130. @var{dest} can be an output port, @code{#t} for
  131. @code{current-output-port} (@pxref{Default Ports}), or @code{#f} to
  132. return the output as a string.
  133. @var{fmt} can contain literal text to be output, and @nicode{~}
  134. escapes. Each escape has the form
  135. @example
  136. ~ [param [, param@dots{}] [:] [@@] code
  137. @end example
  138. @nicode{code} is a character determining the escape sequence. The
  139. @nicode{:} and @nicode{@@} characters are optional modifiers, one or
  140. both of which change the way various codes operate. Optional
  141. parameters are accepted by some codes too. Parameters have the
  142. following forms,
  143. @table @asis
  144. @item @nicode{[+/-]number}
  145. An integer, with optional @nicode{+} or @nicode{-}.
  146. @item @nicode{'} (apostrophe)
  147. The following character in the format string, for instance @nicode{'z}
  148. for @nicode{z}.
  149. @item @nicode{v}
  150. The next function argument as the parameter. @nicode{v} stands for
  151. ``variable'', a parameter can be calculated at runtime and included in
  152. the arguments. Upper case @nicode{V} can be used too.
  153. @item @nicode{#}
  154. The number of arguments remaining. (See @nicode{~*} below for some
  155. usages.)
  156. @end table
  157. Parameters are separated by commas (@nicode{,}). A parameter can be
  158. left empty to keep its default value when supplying later parameters.
  159. @sp 1
  160. The following escapes are available. The code letters are not
  161. case-sensitive, upper and lower case are the same.
  162. @table @asis
  163. @item @nicode{~a}
  164. @itemx @nicode{~s}
  165. Object output. Parameters: @var{minwidth}, @var{padinc},
  166. @var{minpad}, @var{padchar}.
  167. @nicode{~a} outputs an argument like @code{display}, @nicode{~s}
  168. outputs an argument like @code{write} (@pxref{Writing}).
  169. @example
  170. (format #t "~a" "foo") @print{} foo
  171. (format #t "~s" "foo") @print{} "foo"
  172. @end example
  173. @nicode{~:a} and @nicode{~:s} put objects that don't have an external
  174. representation in quotes like a string.
  175. @example
  176. (format #t "~:a" car) @print{} "#<primitive-procedure car>"
  177. @end example
  178. If the output is less than @var{minwidth} characters (default 0), it's
  179. padded on the right with @var{padchar} (default space). @nicode{~@@a}
  180. and @nicode{~@@s} put the padding on the left instead.
  181. @example
  182. (format #f "~5a" 'abc) @result{} "abc "
  183. (format #f "~5,,,'-@@a" 'abc) @result{} "--abc"
  184. @end example
  185. @var{minpad} is a minimum for the padding then plus a multiple of
  186. @var{padinc}. Ie.@: the padding is @math{@var{minpad} + @var{N} *
  187. @var{padinc}}, where @var{n} is the smallest integer making the total
  188. object plus padding greater than or equal to @var{minwidth}. The
  189. default @var{minpad} is 0 and the default @var{padinc} is 1 (imposing
  190. no minimum or multiple).
  191. @example
  192. (format #f "~5,1,4a" 'abc) @result{} "abc "
  193. @end example
  194. @item @nicode{~c}
  195. Character. Parameter: @var{charnum}.
  196. Output a character. The default is to simply output, as per
  197. @code{write-char} (@pxref{Writing}). @nicode{~@@c} prints in
  198. @code{write} style. @nicode{~:c} prints control characters (ASCII 0
  199. to 31) in @nicode{^X} form.
  200. @example
  201. (format #t "~c" #\z) @print{} z
  202. (format #t "~@@c" #\z) @print{} #\z
  203. (format #t "~:c" #\newline) @print{} ^J
  204. @end example
  205. If the @var{charnum} parameter is given then an argument is not taken
  206. but instead the character is @code{(integer->char @var{charnum})}
  207. (@pxref{Characters}). This can be used for instance to output
  208. characters given by their ASCII code.
  209. @example
  210. (format #t "~65c") @print{} A
  211. @end example
  212. @item @nicode{~d}
  213. @itemx @nicode{~x}
  214. @itemx @nicode{~o}
  215. @itemx @nicode{~b}
  216. Integer. Parameters: @var{minwidth}, @var{padchar}, @var{commachar},
  217. @var{commawidth}.
  218. Output an integer argument as a decimal, hexadecimal, octal or binary
  219. integer (respectively), in a locale-independent way.
  220. @example
  221. (format #t "~d" 123) @print{} 123
  222. @end example
  223. @nicode{~@@d} etc shows a @nicode{+} sign is shown on positive
  224. numbers.
  225. @c FIXME: "+" is not shown on zero, unlike in Common Lisp. Should
  226. @c that be changed in the code, or is it too late and should just be
  227. @c documented that way?
  228. @example
  229. (format #t "~@@b" 12) @print{} +1100
  230. @end example
  231. If the output is less than the @var{minwidth} parameter (default no
  232. minimum), it's padded on the left with the @var{padchar} parameter
  233. (default space).
  234. @example
  235. (format #t "~5,'*d" 12) @print{} ***12
  236. (format #t "~5,'0d" 12) @print{} 00012
  237. (format #t "~3d" 1234) @print{} 1234
  238. @end example
  239. @nicode{~:d} adds commas (or the @var{commachar} parameter) every
  240. three digits (or the @var{commawidth} parameter many). However, when
  241. your intent is to write numbers in a way that follows typographical
  242. conventions, using @nicode{~h} is recommended.
  243. @example
  244. (format #t "~:d" 1234567) @print{} 1,234,567
  245. (format #t "~10,'*,'/,2:d" 12345) @print{} ***1/23/45
  246. @end example
  247. Hexadecimal @nicode{~x} output is in lower case, but the @nicode{~(}
  248. and @nicode{~)} case conversion directives described below can be used
  249. to get upper case.
  250. @example
  251. (format #t "~x" 65261) @print{} feed
  252. (format #t "~:@@(~x~)" 65261) @print{} FEED
  253. @end example
  254. @item @nicode{~r}
  255. Integer in words, roman numerals, or a specified radix. Parameters:
  256. @var{radix}, @var{minwidth}, @var{padchar}, @var{commachar},
  257. @var{commawidth}.
  258. With no parameters output is in words as a cardinal like ``ten'', or
  259. @nicode{~:r} prints an ordinal like ``tenth''.
  260. @example
  261. (format #t "~r" 9) @print{} nine ;; cardinal
  262. (format #t "~r" -9) @print{} minus nine ;; cardinal
  263. (format #t "~:r" 9) @print{} ninth ;; ordinal
  264. @end example
  265. And also with no parameters, @nicode{~@@r} gives roman numerals and
  266. @nicode{~:@@r} gives old roman numerals. In old roman numerals
  267. there's no ``subtraction'', so 9 is @nicode{VIIII} instead of
  268. @nicode{IX}. In both cases only positive numbers can be output.
  269. @example
  270. (format #t "~@@r" 89) @print{} LXXXIX ;; roman
  271. (format #t "~:@@r" 89) @print{} LXXXVIIII ;; old roman
  272. @end example
  273. When a parameter is given it means numeric output in the specified
  274. @var{radix}. The modifiers and parameters following the radix are the
  275. same as described for @nicode{~d} etc above.
  276. @example
  277. (format #f "~3r" 27) @result{} "1000" ;; base 3
  278. (format #f "~3,5r" 26) @result{} " 222" ;; base 3 width 5
  279. @end example
  280. @item @nicode{~f}
  281. Fixed-point float. Parameters: @var{width}, @var{decimals},
  282. @var{scale}, @var{overflowchar}, @var{padchar}.
  283. Output a number or number string in fixed-point format, ie.@: with a
  284. decimal point.
  285. @example
  286. (format #t "~f" 5) @print{} 5.0
  287. (format #t "~f" "123") @print{} 123.0
  288. (format #t "~f" "1e-1") @print{} 0.1
  289. @end example
  290. @nicode{~@@f} prints a @nicode{+} sign on positive numbers (including
  291. zero).
  292. @example
  293. (format #t "~@@f" 0) @print{} +0.0
  294. @end example
  295. If the output is less than @var{width} characters it's padded on the
  296. left with @var{padchar} (space by default). If the output equals or
  297. exceeds @var{width} then there's no padding. The default for
  298. @var{width} is no padding.
  299. @example
  300. (format #f "~6f" -1.5) @result{} " -1.5"
  301. (format #f "~6,,,,'*f" 23) @result{} "**23.0"
  302. (format #f "~6f" 1234567.0) @result{} "1234567.0"
  303. @end example
  304. @var{decimals} is how many digits to print after the decimal point,
  305. with the value rounded or padded with zeros as necessary. (The
  306. default is to output as many decimals as required.)
  307. @example
  308. (format #t "~1,2f" 3.125) @print{} 3.13
  309. (format #t "~1,2f" 1.5) @print{} 1.50
  310. @end example
  311. @var{scale} is a power of 10 applied to the value, moving the decimal
  312. point that many places. A positive @var{scale} increases the value
  313. shown, a negative decreases it.
  314. @example
  315. (format #t "~,,2f" 1234) @print{} 123400.0
  316. (format #t "~,,-2f" 1234) @print{} 12.34
  317. @end example
  318. If @var{overflowchar} and @var{width} are both given and if the output
  319. would exceed @var{width}, then that many @var{overflowchar}s are
  320. printed instead of the value.
  321. @example
  322. (format #t "~6,,,'xf" 12345) @print{} 12345.
  323. (format #t "~5,,,'xf" 12345) @print{} xxxxx
  324. @end example
  325. @item @nicode{~h}
  326. Localized number@footnote{The @nicode{~h} format specifier first
  327. appeared in Guile version 2.0.6.}. Parameters: @var{width},
  328. @var{decimals}, @var{padchar}.
  329. Like @nicode{~f}, output an exact or floating point number, but do so
  330. according to the current locale, or according to the given locale object
  331. when the @code{:} modifier is used (@pxref{Number Input and Output,
  332. @code{number->locale-string}}).
  333. @example
  334. (format #t "~h" 12345.5678) ; with "C" as the current locale
  335. @print{} 12345.5678
  336. (format #t "~14,,'*:h" 12345.5678
  337. (make-locale LC_ALL "en_US"))
  338. @print{} ***12,345.5678
  339. (format #t "~,2:h" 12345.5678
  340. (make-locale LC_NUMERIC "fr_FR"))
  341. @print{} 12 345,56
  342. @end example
  343. @item @nicode{~e}
  344. Exponential float. Parameters: @var{width}, @var{mantdigits},
  345. @var{expdigits}, @var{intdigits}, @var{overflowchar}, @var{padchar},
  346. @var{expchar}.
  347. Output a number or number string in exponential notation.
  348. @example
  349. (format #t "~e" 5000.25) @print{} 5.00025E+3
  350. (format #t "~e" "123.4") @print{} 1.234E+2
  351. (format #t "~e" "1e4") @print{} 1.0E+4
  352. @end example
  353. @nicode{~@@e} prints a @nicode{+} sign on positive numbers (including
  354. zero). (This is for the mantissa, a @nicode{+} or @nicode{-} sign is
  355. always shown on the exponent.)
  356. @example
  357. (format #t "~@@e" 5000.0) @print{} +5.0E+3
  358. @end example
  359. If the output is less than @var{width} characters it's padded on the
  360. left with @var{padchar} (space by default). The default for
  361. @var{width} is to output with no padding.
  362. @example
  363. (format #f "~10e" 1234.0) @result{} " 1.234E+3"
  364. (format #f "~10,,,,,'*e" 0.5) @result{} "****5.0E-1"
  365. @end example
  366. @c FIXME: Describe what happens when the number is bigger than WIDTH.
  367. @c There seems to be a bit of dodginess about this, or some deviation
  368. @c from Common Lisp.
  369. @var{mantdigits} is the number of digits shown in the mantissa after
  370. the decimal point. The value is rounded or trailing zeros are added
  371. as necessary. The default @var{mantdigits} is to show as much as
  372. needed by the value.
  373. @example
  374. (format #f "~,3e" 11111.0) @result{} "1.111E+4"
  375. (format #f "~,8e" 123.0) @result{} "1.23000000E+2"
  376. @end example
  377. @var{expdigits} is the minimum number of digits shown for the
  378. exponent, with leading zeros added if necessary. The default for
  379. @var{expdigits} is to show only as many digits as required. At least
  380. 1 digit is always shown.
  381. @example
  382. (format #f "~,,1e" 1.0e99) @result{} "1.0E+99"
  383. (format #f "~,,6e" 1.0e99) @result{} "1.0E+000099"
  384. @end example
  385. @var{intdigits} (default 1) is the number of digits to show before the
  386. decimal point in the mantissa. @var{intdigits} can be zero, in which
  387. case the integer part is a single @nicode{0}, or it can be negative,
  388. in which case leading zeros are shown after the decimal point.
  389. @c FIXME: When INTDIGITS is 0, Common Lisp format apparently only
  390. @c shows the single 0 digit if it fits in WIDTH. format.scm seems to
  391. @c show it always. Is it meant to?
  392. @example
  393. (format #t "~,,,3e" 12345.0) @print{} 123.45E+2
  394. (format #t "~,,,0e" 12345.0) @print{} 0.12345E+5
  395. (format #t "~,,,-3e" 12345.0) @print{} 0.00012345E+8
  396. @end example
  397. @c FIXME: MANTDIGITS with negative INTDIGITS doesn't match CL spec,
  398. @c believe the spec says it ought to still show mantdigits+1 sig
  399. @c figures, i.e. leading zeros don't count towards MANTDIGITS, but it
  400. @c seems to just treat MANTDIGITS as how many digits after the
  401. @c decimal point.
  402. If @var{overflowchar} is given then @var{width} is a hard limit. If
  403. the output would exceed @var{width} then instead that many
  404. @var{overflowchar}s are printed.
  405. @example
  406. (format #f "~6,,,,'xe" 100.0) @result{} "1.0E+2"
  407. (format #f "~3,,,,'xe" 100.0) @result{} "xxx"
  408. @end example
  409. @var{expchar} is the exponent marker character (default @nicode{E}).
  410. @example
  411. (format #t "~,,,,,,'ee" 100.0) @print{} 1.0e+2
  412. @end example
  413. @item @nicode{~g}
  414. General float. Parameters: @var{width}, @var{mantdigits},
  415. @var{expdigits}, @var{intdigits}, @var{overflowchar}, @var{padchar},
  416. @var{expchar}.
  417. Output a number or number string in either exponential format the same
  418. as @nicode{~e}, or fixed-point format like @nicode{~f} but aligned
  419. where the mantissa would have been and followed by padding where the
  420. exponent would have been.
  421. @c FIXME: The default MANTDIGITS is apparently max(needed,min(n,7))
  422. @c where 10^(n-1)<=abs(x)<=10^n. But the Common Lisp spec seems to
  423. @c ask for "needed" to be without leading or trailing zeros, whereas
  424. @c format.scm seems to include trailing zeros, ending up with it
  425. @c using fixed format for bigger values than it should.
  426. Fixed-point is used when the absolute value is 0.1 or more and it
  427. takes no more space than the mantissa in exponential format, ie.@:
  428. basically up to @var{mantdigits} digits.
  429. @example
  430. (format #f "~12,4,2g" 999.0) @result{} " 999.0 "
  431. (format #f "~12,4,2g" "100000") @result{} " 1.0000E+05"
  432. @end example
  433. The parameters are interpreted as per @nicode{~e} above. When
  434. fixed-point is used, the @var{decimals} parameter to @nicode{~f} is
  435. established from @var{mantdigits}, so as to give a total
  436. @math{@var{mantdigits}+1} figures.
  437. @item @nicode{~$}
  438. Monetary style fixed-point float. Parameters: @var{decimals},
  439. @var{intdigits}, @var{width}, @var{padchar}.
  440. @c For reference, fmtdoc.txi from past versions of slib showed the
  441. @c INTDIGITS parameter as SCALE. That looks like a typo, in the code
  442. @c and in the Common Lisp spec it's a minimum digits for the integer
  443. @c part, it isn't a power of 10 like in ~f.
  444. Output a number or number string in fixed-point format, ie.@: with a
  445. decimal point. @var{decimals} is the number of decimal places to
  446. show, default 2.
  447. @example
  448. (format #t "~$" 5) @print{} 5.00
  449. (format #t "~4$" "2.25") @print{} 2.2500
  450. (format #t "~4$" "1e-2") @print{} 0.0100
  451. @end example
  452. @nicode{~@@$} prints a @nicode{+} sign on positive numbers (including
  453. zero).
  454. @example
  455. (format #t "~@@$" 0) @print{} +0.00
  456. @end example
  457. @var{intdigits} is a minimum number of digits to show in the integer
  458. part of the value (default 1).
  459. @example
  460. (format #t "~,3$" 9.5) @print{} 009.50
  461. (format #t "~,0$" 0.125) @print{} .13
  462. @end example
  463. If the output is less than @var{width} characters (default 0), it's
  464. padded on the left with @var{padchar} (default space). @nicode{~:$}
  465. puts the padding after the sign.
  466. @example
  467. (format #f "~,,8$" -1.5) @result{} " -1.50"
  468. (format #f "~,,8:$" -1.5) @result{} "- 1.50"
  469. (format #f "~,,8,'.:@@$" 3) @result{} "+...3.00"
  470. @end example
  471. Note that floating point for dollar amounts is generally not a good
  472. idea, because a cent @math{0.01} cannot be represented exactly in the
  473. binary floating point Guile uses, which leads to slowly accumulating
  474. rounding errors. Keeping values as cents (or fractions of a cent) in
  475. integers then printing with the scale option in @nicode{~f} may be a
  476. better approach.
  477. @c For reference, fractions don't work with ~$ (or any of the float
  478. @c conversions) currently. If they did work then we could perhaps
  479. @c suggest keeping dollar amounts as rationals, which would of course
  480. @c give exact cents. An integer as cents is probably still a better
  481. @c recommendation though, since it forces one to think about where
  482. @c and when rounding can or should occur.
  483. @item @nicode{~i}
  484. Complex fixed-point float. Parameters: @var{width}, @var{decimals},
  485. @var{scale}, @var{overflowchar}, @var{padchar}.
  486. @c For reference, in Common Lisp ~i is an indent, but slib fmtdoc.txi
  487. @c described it as complex number output, so we keep that.
  488. Output the argument as a complex number, with both real and imaginary
  489. part shown (even if one or both are zero).
  490. The parameters and modifiers are the same as for fixed-point
  491. @nicode{~f} described above. The real and imaginary parts are both
  492. output with the same given parameters and modifiers, except that for
  493. the imaginary part the @nicode{@@} modifier is always enabled, so as
  494. to print a @nicode{+} sign between the real and imaginary parts.
  495. @example
  496. (format #t "~i" 1) @print{} 1.0+0.0i
  497. @end example
  498. @item @nicode{~p}
  499. Plural. No parameters.
  500. Output nothing if the argument is 1, or @samp{s} for any other
  501. value.
  502. @example
  503. (format #t "enter name~p" 1) @print{} enter name
  504. (format #t "enter name~p" 2) @print{} enter names
  505. @end example
  506. @nicode{~@@p} prints @samp{y} for 1 or @samp{ies} otherwise.
  507. @example
  508. (format #t "pupp~@@p" 1) @print{} puppy
  509. (format #t "pupp~@@p" 2) @print{} puppies
  510. @end example
  511. @nicode{~:p} re-uses the preceding argument instead of taking a new
  512. one, which can be convenient when printing some sort of count.
  513. @example
  514. (format #t "~d cat~:p" 9) @print{} 9 cats
  515. (format #t "~d pupp~:@@p" 5) @print{} 5 puppies
  516. @end example
  517. @nicode{~p} is designed for English plurals and there's no attempt to
  518. support other languages. @nicode{~[} conditionals (below) may be able
  519. to help. When using @code{gettext} to translate messages
  520. @code{ngettext} is probably best though
  521. (@pxref{Internationalization}).
  522. @item @nicode{~y}
  523. Structured printing. Parameters: @var{width}.
  524. @nicode{~y} outputs an argument using @code{pretty-print}
  525. (@pxref{Pretty Printing}). The result will be formatted to fit within
  526. @var{width} columns (79 by default), consuming multiple lines if
  527. necessary.
  528. @nicode{~@@y} outputs an argument using @code{truncated-print}
  529. (@pxref{Pretty Printing}). The resulting code will be formatted to fit
  530. within @var{width} columns (79 by default), on a single line. The
  531. output will be truncated if necessary.
  532. @nicode{~:@@y} is like @nicode{~@@y}, except the @var{width} parameter
  533. is interpreted to be the maximum column to which to output. That is to
  534. say, if you are at column 10, and @nicode{~60:@@y} is seen, the datum
  535. will be truncated to 50 columns.
  536. @item @nicode{~?}
  537. @itemx @nicode{~k}
  538. Sub-format. No parameters.
  539. Take a format string argument and a second argument which is a list of
  540. arguments for that string, and output the result.
  541. @example
  542. (format #t "~?" "~d ~d" '(1 2)) @print{} 1 2
  543. @end example
  544. @nicode{~@@?} takes arguments for the sub-format directly rather than
  545. in a list.
  546. @example
  547. (format #t "~@@? ~s" "~d ~d" 1 2 "foo") @print{} 1 2 "foo"
  548. @end example
  549. @nicode{~?} and @nicode{~k} are the same, @nicode{~k} is provided for
  550. T-Scheme compatibility.
  551. @item @nicode{~*}
  552. Argument jumping. Parameter: @var{N}.
  553. Move forward @var{N} arguments (default 1) in the argument list.
  554. @nicode{~:*} moves backwards. (@var{N} cannot be negative.)
  555. @example
  556. (format #f "~d ~2*~d" 1 2 3 4) @result{} "1 4"
  557. (format #f "~d ~:*~d" 6) @result{} "6 6"
  558. @end example
  559. @nicode{~@@*} moves to argument number @var{N}. The first argument is
  560. number 0 (and that's the default for @var{N}).
  561. @example
  562. (format #f "~d~d again ~@@*~d~d" 1 2) @result{} "12 again 12"
  563. (format #f "~d~d~d ~1@@*~d~d" 1 2 3) @result{} "123 23"
  564. @end example
  565. A @nicode{#} move to the end followed by a @nicode{:} modifier move
  566. back can be used for an absolute position relative to the end of the
  567. argument list, a reverse of what the @nicode{@@} modifier does.
  568. @example
  569. (format #t "~#*~2:*~a" 'a 'b 'c 'd) @print{} c
  570. @end example
  571. At the end of the format string the current argument position doesn't
  572. matter, any further arguments are ignored.
  573. @item @nicode{~t}
  574. Advance to a column position. Parameters: @var{colnum}, @var{colinc},
  575. @var{padchar}.
  576. Output @var{padchar} (space by default) to move to the given
  577. @var{colnum} column. The start of the line is column 0, the default
  578. for @var{colnum} is 1.
  579. @example
  580. (format #f "~tX") @result{} " X"
  581. (format #f "~3tX") @result{} " X"
  582. @end example
  583. If the current column is already past @var{colnum}, then the move is
  584. to there plus a multiple of @var{colinc}, ie.@: column
  585. @math{@var{colnum} + @var{N} * @var{colinc}} for the smallest @var{N}
  586. which makes that value greater than or equal to the current column.
  587. The default @var{colinc} is 1 (which means no further move).
  588. @example
  589. (format #f "abcd~2,5,'.tx") @result{} "abcd...x"
  590. @end example
  591. @nicode{~@@t} takes @var{colnum} as an offset from the current column.
  592. @var{colnum} many pad characters are output, then further padding to
  593. make the current column a multiple of @var{colinc}, if it isn't
  594. already so.
  595. @example
  596. (format #f "a~3,5'*@@tx") @result{} "a****x"
  597. @end example
  598. @nicode{~t} is implemented using @code{port-column} (@pxref{Reading}),
  599. so it works even there has been other output before @code{format}.
  600. @item @nicode{~~}
  601. Tilde character. Parameter: @var{n}.
  602. Output a tilde character @nicode{~}, or @var{n} many if a parameter is
  603. given. Normally @nicode{~} introduces an escape sequence, @nicode{~~}
  604. is the way to output a literal tilde.
  605. @item @nicode{~%}
  606. Newline. Parameter: @var{n}.
  607. Output a newline character, or @var{n} many if a parameter is given.
  608. A newline (or a few newlines) can of course be output just by
  609. including them in the format string.
  610. @item @nicode{~&}
  611. Start a new line. Parameter: @var{n}.
  612. Output a newline if not already at the start of a line. With a
  613. parameter, output that many newlines, but with the first only if not
  614. already at the start of a line. So for instance 3 would be a newline
  615. if not already at the start of a line, and 2 further newlines.
  616. @item @nicode{~_}
  617. Space character. Parameter: @var{n}.
  618. @c For reference, in Common Lisp ~_ is a conditional newline, but
  619. @c slib fmtdoc.txi described it as a space, so we keep that.
  620. Output a space character, or @var{n} many if a parameter is given.
  621. With a variable parameter this is one way to insert runtime calculated
  622. padding (@nicode{~t} or the various field widths can do similar
  623. things).
  624. @example
  625. (format #f "~v_foo" 4) @result{} " foo"
  626. @end example
  627. @item @nicode{~/}
  628. Tab character. Parameter: @var{n}.
  629. Output a tab character, or @var{n} many if a parameter is given.
  630. @item @nicode{~|}
  631. Formfeed character. Parameter: @var{n}.
  632. Output a formfeed character, or @var{n} many if a parameter is given.
  633. @item @nicode{~!}
  634. Force output. No parameters.
  635. At the end of output, call @code{force-output} to flush any buffers on
  636. the destination (@pxref{Writing}). @nicode{~!} can occur anywhere in
  637. the format string, but the force is done at the end of output.
  638. When output is to a string (destination @code{#f}), @nicode{~!} does
  639. nothing.
  640. @item @nicode{~newline} (ie.@: newline character)
  641. Continuation line. No parameters.
  642. Skip this newline and any following whitespace in the format string,
  643. ie.@: don't send it to the output. This can be used to break up a
  644. long format string for readability, but not print the extra
  645. whitespace.
  646. @example
  647. (format #f "abc~
  648. ~d def~
  649. ~d" 1 2) @result{} "abc1 def2"
  650. @end example
  651. @nicode{~:newline} skips the newline but leaves any further whitespace
  652. to be printed normally.
  653. @nicode{~@@newline} prints the newline then skips following
  654. whitespace.
  655. @item @nicode{~(} @nicode{~)}
  656. Case conversion. No parameters.
  657. Between @nicode{~(} and @nicode{~)} the case of all output is changed.
  658. The modifiers on @nicode{~(} control the conversion.
  659. @itemize @w{}
  660. @item
  661. @nicode{~(} --- lower case.
  662. @c
  663. @c FIXME: The : and @ modifiers are not yet documented because the
  664. @c code applies string-capitalize and string-capitalize-first to each
  665. @c separate format:out-str call, which has various subtly doubtful
  666. @c effects. And worse they're applied to individual characters,
  667. @c including literal characters in the format string, which has the
  668. @c silly effect of being always an upcase.
  669. @c
  670. @c The Common Lisp spec is apparently for the capitalization to be
  671. @c applied in one hit to the whole of the output between ~( and ~).
  672. @c (This can no doubt be implemented without accumulating all that
  673. @c text, just by keeping a state or the previous char to tell whether
  674. @c within a word.)
  675. @c
  676. @c @item
  677. @c @nicode{:} --- first letter of each word upper case, the rest lower
  678. @c case, as per the @code{string-capitalize} function (@pxref{Alphabetic
  679. @c Case Mapping}).
  680. @c @item
  681. @c @nicode{@@} --- first letter of just the first word upper case, the
  682. @c rest lower case.
  683. @c
  684. @item
  685. @nicode{~:@@(} --- upper case.
  686. @end itemize
  687. For example,
  688. @example
  689. (format #t "~(Hello~)") @print{} hello
  690. (format #t "~:@@(Hello~)") @print{} HELLO
  691. @end example
  692. In the future it's intended the modifiers @nicode{:} and @nicode{@@}
  693. alone will capitalize the first letters of words, as per Common Lisp
  694. @code{format}, but the current implementation of this is flawed and
  695. not recommended for use.
  696. Case conversions do not nest, currently. This might change in the
  697. future, but if it does then it will be to Common Lisp style where the
  698. outermost conversion has priority, overriding inner ones (making those
  699. fairly pointless).
  700. @item @nicode{~@{} @nicode{~@}}
  701. Iteration. Parameter: @var{maxreps} (for @nicode{~@{}).
  702. The format between @nicode{~@{} and @nicode{~@}} is iterated. The
  703. modifiers to @nicode{~@{} determine how arguments are taken. The
  704. default is a list argument with each iteration successively consuming
  705. elements from it. This is a convenient way to output a whole list.
  706. @example
  707. (format #t "~@{~d~@}" '(1 2 3)) @print{} 123
  708. (format #t "~@{~s=~d ~@}" '("x" 1 "y" 2)) @print{} "x"=1 "y"=2
  709. @end example
  710. @nicode{~:@{} takes a single argument which is a list of lists, each
  711. of those contained lists gives the arguments for the iterated format.
  712. @c @print{} on a new line here to avoid overflowing page width in DVI
  713. @example
  714. (format #t "~:@{~dx~d ~@}" '((1 2) (3 4) (5 6)))
  715. @print{} 1x2 3x4 5x6
  716. @end example
  717. @nicode{~@@@{} takes arguments directly, with each iteration
  718. successively consuming arguments.
  719. @example
  720. (format #t "~@@@{~d~@}" 1 2 3) @print{} 123
  721. (format #t "~@@@{~s=~d ~@}" "x" 1 "y" 2) @print{} "x"=1 "y"=2
  722. @end example
  723. @nicode{~:@@@{} takes list arguments, one argument for each iteration,
  724. using that list for the format.
  725. @c @print{} on a new line here to avoid overflowing page width in DVI
  726. @example
  727. (format #t "~:@@@{~dx~d ~@}" '(1 2) '(3 4) '(5 6))
  728. @print{} 1x2 3x4 5x6
  729. @end example
  730. Iterating stops when there are no more arguments or when the
  731. @var{maxreps} parameter to @nicode{~@{} is reached (default no
  732. maximum).
  733. @example
  734. (format #t "~2@{~d~@}" '(1 2 3 4)) @print{} 12
  735. @end example
  736. If the format between @nicode{~@{} and @nicode{~@}} is empty, then a
  737. format string argument is taken (before iteration argument(s)) and
  738. used instead. This allows a sub-format (like @nicode{~?} above) to be
  739. iterated.
  740. @example
  741. (format #t "~@{~@}" "~d" '(1 2 3)) @print{} 123
  742. @end example
  743. @c FIXME: What is the @nicode{:} modifier to ~} meant to do? The
  744. @c Common Lisp spec says it's a minimum of 1 iteration, but the
  745. @c format.scm code seems to merely make it have MAXREPS default to 1.
  746. Iterations can be nested, an inner iteration operates in the same way
  747. as described, but of course on the arguments the outer iteration
  748. provides it. This can be used to work into nested list structures.
  749. For example in the following the inner @nicode{~@{~d~@}x} is applied
  750. to @code{(1 2)} then @code{(3 4 5)} etc.
  751. @example
  752. (format #t "~@{~@{~d~@}x~@}" '((1 2) (3 4 5))) @print{} 12x345x
  753. @end example
  754. See also @nicode{~^} below for escaping from iteration.
  755. @item @nicode{~[} @nicode{~;} @nicode{~]}
  756. Conditional. Parameter: @var{selector}.
  757. A conditional block is delimited by @nicode{~[} and @nicode{~]}, and
  758. @nicode{~;} separates clauses within the block. @nicode{~[} takes an
  759. integer argument and that number clause is used. The first clause is
  760. number 0.
  761. @example
  762. (format #f "~[peach~;banana~;mango~]" 1) @result{} "banana"
  763. @end example
  764. The @var{selector} parameter can be used for the clause number,
  765. instead of taking an argument.
  766. @example
  767. (format #f "~2[peach~;banana~;mango~]") @result{} "mango"
  768. @end example
  769. If the clause number is out of range then nothing is output. Or the
  770. last clause can be @nicode{~:;} to use that for a number out of range.
  771. @example
  772. (format #f "~[banana~;mango~]" 99) @result{} ""
  773. (format #f "~[banana~;mango~:;fruit~]" 99) @result{} "fruit"
  774. @end example
  775. @nicode{~:[} treats the argument as a flag, and expects two clauses.
  776. The first is used if the argument is @code{#f} or the second
  777. otherwise.
  778. @example
  779. (format #f "~:[false~;not false~]" #f) @result{} "false"
  780. (format #f "~:[false~;not false~]" 'abc) @result{} "not false"
  781. (let ((n 3))
  782. (format #t "~d gnu~:[s are~; is~] here" n (= 1 n)))
  783. @print{} 3 gnus are here
  784. @end example
  785. @nicode{~@@[} also treats the argument as a flag, and expects one
  786. clause. If the argument is @code{#f} then no output is produced and
  787. the argument is consumed, otherwise the clause is used and the
  788. argument is not consumed, it's left for the clause. This can be used
  789. for instance to suppress output if @code{#f} means something not
  790. available.
  791. @example
  792. (format #f "~@@[temperature=~d~]" 27) @result{} "temperature=27"
  793. (format #f "~@@[temperature=~d~]" #f) @result{} ""
  794. @end example
  795. @item @nicode{~^}
  796. Escape. Parameters: @var{val1}, @var{val2}, @var{val3}.
  797. Stop formatting if there are no more arguments. This can be used for
  798. instance to have a format string adapt to a variable number of
  799. arguments.
  800. @example
  801. (format #t "~d~^ ~d" 1) @print{} 1
  802. (format #t "~d~^ ~d" 1 2) @print{} 1 2
  803. @end example
  804. Within a @nicode{~@{} @nicode{~@}} iteration, @nicode{~^} stops the
  805. current iteration step if there are no more arguments to that step,
  806. but continuing with possible further steps and the rest of the format.
  807. This can be used for instance to avoid a separator on the last
  808. iteration, or to adapt to variable length argument lists.
  809. @example
  810. (format #f "~@{~d~^/~@} go" '(1 2 3)) @result{} "1/2/3 go"
  811. (format #f "~:@{ ~d~^~d~@} go" '((1) (2 3))) @result{} " 1 23 go"
  812. @end example
  813. @c For reference, format.scm doesn't implement that Common Lisp ~:^
  814. @c modifier which stops the entire iterating of ~:{ or ~@:{.
  815. @c FIXME: Believe the Common Lisp spec is for ~^ within ~[ ~]
  816. @c conditional to terminate the whole format (or iteration step if in
  817. @c an iteration). But format.scm seems to terminate just the
  818. @c conditional form.
  819. @c
  820. @c (format #f "~[abc~^def~;ghi~] blah" 0)
  821. @c @result{} "abc blah" ;; looks wrong
  822. @c FIXME: Believe the Common Lisp spec is for ~^ within ~( ~) to end
  823. @c that case conversion and then also terminate the whole format (or
  824. @c iteration step if in an iteration). But format.scm doesn't seem
  825. @c to do that quite right.
  826. @c
  827. @c (format #f "~d ~^ ~d" 1) @result{} "1 "
  828. @c (format #f "~(~d ~^ ~d~)" 1) @result{} ERROR
  829. Within a @nicode{~?} sub-format, @nicode{~^} operates just on that
  830. sub-format. If it terminates the sub-format then the originating
  831. format will still continue.
  832. @example
  833. (format #t "~? items" "~d~^ ~d" '(1)) @print{} 1 items
  834. (format #t "~? items" "~d~^ ~d" '(1 2)) @print{} 1 2 items
  835. @end example
  836. The parameters to @nicode{~^} (which are numbers) change the condition
  837. used to terminate. For a single parameter, termination is when that
  838. value is zero (notice this makes plain @nicode{~^} equivalent to
  839. @nicode{~#^}). For two parameters, termination is when those two are
  840. equal. For three parameters, termination is when @math{@var{val1}
  841. @le{} @var{val2}} and @math{@var{val2} @le{} @var{val3}}.
  842. @c FIXME: Good examples of these?
  843. @item @nicode{~q}
  844. Inquiry message. Insert a copyright message into the output.
  845. @nicode{~:q} inserts the format implementation version.
  846. @end table
  847. @sp 1
  848. It's an error if there are not enough arguments for the escapes in the
  849. format string, but any excess arguments are ignored.
  850. Iterations @nicode{~@{} @nicode{~@}} and conditionals @nicode{~[}
  851. @nicode{~;} @nicode{~]} can be nested, but must be properly nested,
  852. meaning the inner form must be entirely within the outer form. So
  853. it's not possible, for instance, to try to conditionalize the endpoint
  854. of an iteration.
  855. @example
  856. (format #t "~@{ ~[ ... ~] ~@}" ...) ;; good
  857. (format #t "~@{ ~[ ... ~@} ... ~]" ...) ;; bad
  858. @end example
  859. The same applies to case conversions @nicode{~(} @nicode{~)}, they
  860. must properly nest with respect to iterations and conditionals (though
  861. currently a case conversion cannot nest within another case
  862. conversion).
  863. When a sub-format (@nicode{~?}) is used, that sub-format string must
  864. be self-contained. It cannot for instance give a @nicode{~@{} to
  865. begin an iteration form and have the @nicode{~@}} up in the
  866. originating format, or similar.
  867. @end deffn
  868. @sp 1
  869. Guile contains a @code{format} procedure even when the module
  870. @code{(ice-9 format)} is not loaded. The default @code{format} is
  871. @code{simple-format} (@pxref{Writing}), it doesn't support all escape
  872. sequences documented in this section, and will signal an error if you
  873. try to use one of them. The reason for two versions is that the full
  874. @code{format} is fairly large and requires some time to load.
  875. @code{simple-format} is often adequate too.
  876. @node File Tree Walk
  877. @section File Tree Walk
  878. @cindex file tree walk
  879. @cindex file system traversal
  880. @cindex directory traversal
  881. The functions in this section traverse a tree of files and
  882. directories. They come in two flavors: the first one is a high-level
  883. functional interface, and the second one is similar to the C @code{ftw}
  884. and @code{nftw} routines (@pxref{Working with Directory Trees,,, libc,
  885. GNU C Library Reference Manual}).
  886. @example
  887. (use-modules (ice-9 ftw))
  888. @end example
  889. @sp 1
  890. @deffn {Scheme Procedure} file-system-tree file-name [enter? [stat]]
  891. Return a tree of the form @code{(@var{file-name} @var{stat}
  892. @var{children} ...)} where @var{stat} is the result of @code{(@var{stat}
  893. @var{file-name})} and @var{children} are similar structures for each
  894. file contained in @var{file-name} when it designates a directory.
  895. The optional @var{enter?} predicate is invoked as @code{(@var{enter?}
  896. @var{name} @var{stat})} and should return true to allow recursion into
  897. directory @var{name}; the default value is a procedure that always
  898. returns @code{#t}. When a directory does not match @var{enter?}, it
  899. nonetheless appears in the resulting tree, only with zero children.
  900. The @var{stat} argument is optional and defaults to @code{lstat}, as for
  901. @code{file-system-fold} (see below.)
  902. The example below shows how to obtain a hierarchical listing of the
  903. files under the @file{module/language} directory in the Guile source
  904. tree, discarding their @code{stat} info:
  905. @example
  906. (use-modules (ice-9 match))
  907. (define remove-stat
  908. ;; Remove the `stat' object the `file-system-tree' provides
  909. ;; for each file in the tree.
  910. (match-lambda
  911. ((name stat) ; flat file
  912. name)
  913. ((name stat children ...) ; directory
  914. (list name (map remove-stat children)))))
  915. (let ((dir (string-append (assq-ref %guile-build-info 'top_srcdir)
  916. "/module/language")))
  917. (remove-stat (file-system-tree dir)))
  918. @result{}
  919. ("language"
  920. (("value" ("spec.go" "spec.scm"))
  921. ("scheme"
  922. ("spec.go"
  923. "spec.scm"
  924. "compile-tree-il.scm"
  925. "decompile-tree-il.scm"
  926. "decompile-tree-il.go"
  927. "compile-tree-il.go"))
  928. ("tree-il"
  929. ("spec.go"
  930. "fix-letrec.go"
  931. "inline.go"
  932. "fix-letrec.scm"
  933. "compile-glil.go"
  934. "spec.scm"
  935. "optimize.scm"
  936. "primitives.scm"
  937. @dots{}))
  938. @dots{}))
  939. @end example
  940. @end deffn
  941. @cindex file system combinator
  942. It is often desirable to process directories entries directly, rather
  943. than building up a tree of entries in memory, like
  944. @code{file-system-tree} does. The following procedure, a
  945. @dfn{combinator}, is designed to allow directory entries to be processed
  946. directly as a directory tree is traversed; in fact,
  947. @code{file-system-tree} is implemented in terms of it.
  948. @deffn {Scheme Procedure} file-system-fold enter? leaf down up skip error init file-name [stat]
  949. Traverse the directory at @var{file-name}, recursively, and return the
  950. result of the successive applications of the @var{leaf}, @var{down},
  951. @var{up}, and @var{skip} procedures as described below.
  952. Enter sub-directories only when @code{(@var{enter?} @var{path}
  953. @var{stat} @var{result})} returns true. When a sub-directory is
  954. entered, call @code{(@var{down} @var{path} @var{stat} @var{result})},
  955. where @var{path} is the path of the sub-directory and @var{stat} the
  956. result of @code{(false-if-exception (@var{stat} @var{path}))}; when it is
  957. left, call @code{(@var{up} @var{path} @var{stat} @var{result})}.
  958. For each file in a directory, call @code{(@var{leaf} @var{path}
  959. @var{stat} @var{result})}.
  960. When @var{enter?} returns @code{#f}, or when an unreadable directory is
  961. encountered, call @code{(@var{skip} @var{path} @var{stat}
  962. @var{result})}.
  963. When @var{file-name} names a flat file, @code{(@var{leaf} @var{path}
  964. @var{stat} @var{init})} is returned.
  965. When an @code{opendir} or @var{stat} call fails, call @code{(@var{error}
  966. @var{path} @var{stat} @var{errno} @var{result})}, with @var{errno} being
  967. the operating system error number that was raised---e.g.,
  968. @code{EACCES}---and @var{stat} either @code{#f} or the result of the
  969. @var{stat} call for that entry, when available.
  970. The special @file{.} and @file{..} entries are not passed to these
  971. procedures. The @var{path} argument to the procedures is a full file
  972. name---e.g., @code{"../foo/bar/gnu"}; if @var{file-name} is an absolute
  973. file name, then @var{path} is also an absolute file name. Files and
  974. directories, as identified by their device/inode number pair, are
  975. traversed only once.
  976. The optional @var{stat} argument defaults to @code{lstat}, which means
  977. that symbolic links are not followed; the @code{stat} procedure can be
  978. used instead when symbolic links are to be followed (@pxref{File System,
  979. stat}).
  980. The example below illustrates the use of @code{file-system-fold}:
  981. @example
  982. (define (total-file-size file-name)
  983. "Return the size in bytes of the files under FILE-NAME (similar
  984. to `du --apparent-size' with GNU Coreutils.)"
  985. (define (enter? name stat result)
  986. ;; Skip version control directories.
  987. (not (member (basename name) '(".git" ".svn" "CVS"))))
  988. (define (leaf name stat result)
  989. ;; Return RESULT plus the size of the file at NAME.
  990. (+ result (stat:size stat)))
  991. ;; Count zero bytes for directories.
  992. (define (down name stat result) result)
  993. (define (up name stat result) result)
  994. ;; Likewise for skipped directories.
  995. (define (skip name stat result) result)
  996. ;; Ignore unreadable files/directories but warn the user.
  997. (define (error name stat errno result)
  998. (format (current-error-port) "warning: ~a: ~a~%"
  999. name (strerror errno))
  1000. result)
  1001. (file-system-fold enter? leaf down up skip error
  1002. 0 ; initial counter is zero bytes
  1003. file-name))
  1004. (total-file-size ".")
  1005. @result{} 8217554
  1006. (total-file-size "/dev/null")
  1007. @result{} 0
  1008. @end example
  1009. @end deffn
  1010. The alternative C-like functions are described below.
  1011. @deffn {Scheme Procedure} scandir name [select? [entry<?]]
  1012. Return the list of the names of files contained in directory @var{name}
  1013. that match predicate @var{select?} (by default, all files). The
  1014. returned list of file names is sorted according to @var{entry<?}, which
  1015. defaults to @code{string-locale<?} such that file names are sorted in
  1016. the locale's alphabetical order (@pxref{Text Collation}). Return
  1017. @code{#f} when @var{name} is unreadable or is not a directory.
  1018. This procedure is modeled after the C library function of the same name
  1019. (@pxref{Scanning Directory Content,,, libc, GNU C Library Reference
  1020. Manual}).
  1021. @end deffn
  1022. @deffn {Scheme Procedure} ftw startname proc ['hash-size n]
  1023. Walk the file system tree descending from @var{startname}, calling
  1024. @var{proc} for each file and directory.
  1025. Hard links and symbolic links are followed. A file or directory is
  1026. reported to @var{proc} only once, and skipped if seen again in another
  1027. place. One consequence of this is that @code{ftw} is safe against
  1028. circularly linked directory structures.
  1029. Each @var{proc} call is @code{(@var{proc} filename statinfo flag)} and
  1030. it should return @code{#t} to continue, or any other value to stop.
  1031. @var{filename} is the item visited, being @var{startname} plus a
  1032. further path and the name of the item. @var{statinfo} is the return
  1033. from @code{stat} (@pxref{File System}) on @var{filename}. @var{flag}
  1034. is one of the following symbols,
  1035. @table @code
  1036. @item regular
  1037. @var{filename} is a file, this includes special files like devices,
  1038. named pipes, etc.
  1039. @item directory
  1040. @var{filename} is a directory.
  1041. @item invalid-stat
  1042. An error occurred when calling @code{stat}, so nothing is known.
  1043. @var{statinfo} is @code{#f} in this case.
  1044. @item directory-not-readable
  1045. @var{filename} is a directory, but one which cannot be read and hence
  1046. won't be recursed into.
  1047. @item symlink
  1048. @var{filename} is a dangling symbolic link. Symbolic links are
  1049. normally followed and their target reported, the link itself is
  1050. reported if the target does not exist.
  1051. @end table
  1052. The return value from @code{ftw} is @code{#t} if it ran to completion,
  1053. or otherwise the non-@code{#t} value from @var{proc} which caused the
  1054. stop.
  1055. Optional argument symbol @code{hash-size} and an integer can be given
  1056. to set the size of the hash table used to track items already visited.
  1057. (@pxref{Hash Table Reference})
  1058. @c Actually, it's probably safe to escape from ftw, just need to
  1059. @c check it.
  1060. @c
  1061. In the current implementation, returning non-@code{#t} from @var{proc}
  1062. is the only valid way to terminate @code{ftw}. @var{proc} must not
  1063. use @code{throw} or similar to escape.
  1064. @end deffn
  1065. @deffn {Scheme Procedure} nftw startname proc ['chdir] ['depth] ['hash-size n] ['mount] ['physical]
  1066. Walk the file system tree starting at @var{startname}, calling
  1067. @var{proc} for each file and directory. @code{nftw} has extra
  1068. features over the basic @code{ftw} described above.
  1069. Like @code{ftw}, hard links and symbolic links are followed. A file
  1070. or directory is reported to @var{proc} only once, and skipped if seen
  1071. again in another place. One consequence of this is that @code{nftw}
  1072. is safe against circular linked directory structures.
  1073. Each @var{proc} call is @code{(@var{proc} filename statinfo flag
  1074. base level)} and it should return @code{#t} to continue, or any
  1075. other value to stop.
  1076. @var{filename} is the item visited, being @var{startname} plus a
  1077. further path and the name of the item. @var{statinfo} is the return
  1078. from @code{stat} on @var{filename} (@pxref{File System}). @var{base}
  1079. is an integer offset into @var{filename} which is where the basename
  1080. for this item begins. @var{level} is an integer giving the directory
  1081. nesting level, starting from 0 for the contents of @var{startname} (or
  1082. that item itself if it's a file). @var{flag} is one of the following
  1083. symbols,
  1084. @table @code
  1085. @item regular
  1086. @var{filename} is a file, including special files like devices, named
  1087. pipes, etc.
  1088. @item directory
  1089. @var{filename} is a directory.
  1090. @item directory-processed
  1091. @var{filename} is a directory, and its contents have all been visited.
  1092. This flag is given instead of @code{directory} when the @code{depth}
  1093. option below is used.
  1094. @item invalid-stat
  1095. An error occurred when applying @code{stat} to @var{filename}, so
  1096. nothing is known about it. @var{statinfo} is @code{#f} in this case.
  1097. @item directory-not-readable
  1098. @var{filename} is a directory, but one which cannot be read and hence
  1099. won't be recursed into.
  1100. @item stale-symlink
  1101. @var{filename} is a dangling symbolic link. Links are normally
  1102. followed and their target reported, the link itself is reported if its
  1103. target does not exist.
  1104. @item symlink
  1105. When the @code{physical} option described below is used, this
  1106. indicates @var{filename} is a symbolic link whose target exists (and
  1107. is not being followed).
  1108. @end table
  1109. The following optional arguments can be given to modify the way
  1110. @code{nftw} works. Each is passed as a symbol (and @code{hash-size}
  1111. takes a following integer value).
  1112. @table @asis
  1113. @item @code{chdir}
  1114. Change to the directory containing the item before calling @var{proc}.
  1115. When @code{nftw} returns the original current directory is restored.
  1116. Under this option, generally the @var{base} parameter to each
  1117. @var{proc} call should be used to pick out the base part of the
  1118. @var{filename}. The @var{filename} is still a path but with a changed
  1119. directory it won't be valid (unless the @var{startname} directory was
  1120. absolute).
  1121. @item @code{depth}
  1122. Visit files ``depth first'', meaning @var{proc} is called for the
  1123. contents of each directory before it's called for the directory
  1124. itself. Normally a directory is reported first, then its contents.
  1125. Under this option, the @var{flag} to @var{proc} for a directory is
  1126. @code{directory-processed} instead of @code{directory}.
  1127. @item @code{hash-size @var{n}}
  1128. Set the size of the hash table used to track items already visited.
  1129. (@pxref{Hash Table Reference})
  1130. @item @code{mount}
  1131. Don't cross a mount point, meaning only visit items on the same
  1132. file system as @var{startname} (ie.@: the same @code{stat:dev}).
  1133. @item @code{physical}
  1134. Don't follow symbolic links, instead report them to @var{proc} as
  1135. @code{symlink}. Dangling links (those whose target doesn't exist) are
  1136. still reported as @code{stale-symlink}.
  1137. @end table
  1138. The return value from @code{nftw} is @code{#t} if it ran to
  1139. completion, or otherwise the non-@code{#t} value from @var{proc} which
  1140. caused the stop.
  1141. @c For reference, one reason not to escape is that the current
  1142. @c directory is not saved and restored with dynamic-wind. Maybe
  1143. @c changing that would be enough to allow escaping.
  1144. @c
  1145. In the current implementation, returning non-@code{#t} from @var{proc}
  1146. is the only valid way to terminate @code{ftw}. @var{proc} must not
  1147. use @code{throw} or similar to escape.
  1148. @end deffn
  1149. @node Queues
  1150. @section Queues
  1151. @cindex queues
  1152. @tindex Queues
  1153. @noindent
  1154. The functions in this section are provided by
  1155. @example
  1156. (use-modules (ice-9 q))
  1157. @end example
  1158. This module implements queues holding arbitrary scheme objects and
  1159. designed for efficient first-in / first-out operations.
  1160. @code{make-q} creates a queue, and objects are entered and removed
  1161. with @code{enq!} and @code{deq!}. @code{q-push!} and @code{q-pop!}
  1162. can be used too, treating the front of the queue like a stack.
  1163. @sp 1
  1164. @deffn {Scheme Procedure} make-q
  1165. Return a new queue.
  1166. @end deffn
  1167. @deffn {Scheme Procedure} q? obj
  1168. Return @code{#t} if @var{obj} is a queue, or @code{#f} if not.
  1169. Note that queues are not a distinct class of objects but are
  1170. implemented with cons cells. For that reason certain list structures
  1171. can get @code{#t} from @code{q?}.
  1172. @end deffn
  1173. @deffn {Scheme Procedure} enq! q obj
  1174. Add @var{obj} to the rear of @var{q}, and return @var{q}.
  1175. @end deffn
  1176. @deffn {Scheme Procedure} deq! q
  1177. @deffnx {Scheme Procedure} q-pop! q
  1178. Remove and return the front element from @var{q}. If @var{q} is
  1179. empty, a @code{q-empty} exception is thrown.
  1180. @code{deq!} and @code{q-pop!} are the same operation, the two names
  1181. just let an application match @code{enq!} with @code{deq!}, or
  1182. @code{q-push!} with @code{q-pop!}.
  1183. @end deffn
  1184. @deffn {Scheme Procedure} q-push! q obj
  1185. Add @var{obj} to the front of @var{q}, and return @var{q}.
  1186. @end deffn
  1187. @deffn {Scheme Procedure} q-length q
  1188. Return the number of elements in @var{q}.
  1189. @end deffn
  1190. @deffn {Scheme Procedure} q-empty? q
  1191. Return true if @var{q} is empty.
  1192. @end deffn
  1193. @deffn {Scheme Procedure} q-empty-check q
  1194. Throw a @code{q-empty} exception if @var{q} is empty.
  1195. @end deffn
  1196. @deffn {Scheme Procedure} q-front q
  1197. Return the first element of @var{q} (without removing it). If @var{q}
  1198. is empty, a @code{q-empty} exception is thrown.
  1199. @end deffn
  1200. @deffn {Scheme Procedure} q-rear q
  1201. Return the last element of @var{q} (without removing it). If @var{q}
  1202. is empty, a @code{q-empty} exception is thrown.
  1203. @end deffn
  1204. @deffn {Scheme Procedure} q-remove! q obj
  1205. Remove all occurrences of @var{obj} from @var{q}, and return @var{q}.
  1206. @var{obj} is compared to queue elements using @code{eq?}.
  1207. @end deffn
  1208. @sp 1
  1209. @cindex @code{q-empty}
  1210. The @code{q-empty} exceptions described above are thrown just as
  1211. @code{(throw 'q-empty)}, there's no message etc like an error throw.
  1212. A queue is implemented as a cons cell, the @code{car} containing a
  1213. list of queued elements, and the @code{cdr} being the last cell in
  1214. that list (for ease of enqueuing).
  1215. @example
  1216. (@var{list} . @var{last-cell})
  1217. @end example
  1218. @noindent
  1219. If the queue is empty, @var{list} is the empty list and
  1220. @var{last-cell} is @code{#f}.
  1221. An application can directly access the queue list if desired, for
  1222. instance to search the elements or to insert at a specific point.
  1223. @deffn {Scheme Procedure} sync-q! q
  1224. Recompute the @var{last-cell} field in @var{q}.
  1225. All the operations above maintain @var{last-cell} as described, so
  1226. normally there's no need for @code{sync-q!}. But if an application
  1227. modifies the queue @var{list} then it must either maintain
  1228. @var{last-cell} similarly, or call @code{sync-q!} to recompute it.
  1229. @end deffn
  1230. @node Streams
  1231. @section Streams
  1232. @cindex streams
  1233. A stream represents a sequence of values, each of which is calculated
  1234. only when required. This allows large or even infinite sequences to
  1235. be represented and manipulated with familiar operations like ``car'',
  1236. ``cdr'', ``map'' or ``fold''. In such manipulations only as much as
  1237. needed is actually held in memory at any one time. The functions in
  1238. this section are available from
  1239. @example
  1240. (use-modules (ice-9 streams))
  1241. @end example
  1242. Streams are implemented using promises (@pxref{Delayed Evaluation}),
  1243. which is how the underlying calculation of values is made only when
  1244. needed, and the values then retained so the calculation is not
  1245. repeated.
  1246. @noindent
  1247. Here is a simple example producing a stream of all odd numbers,
  1248. @example
  1249. (define odds (make-stream (lambda (state)
  1250. (cons state (+ state 2)))
  1251. 1))
  1252. (stream-car odds) @result{} 1
  1253. (stream-car (stream-cdr odds)) @result{} 3
  1254. @end example
  1255. @noindent
  1256. @code{stream-map} could be used to derive a stream of odd squares,
  1257. @example
  1258. (define (square n) (* n n))
  1259. (define oddsquares (stream-map square odds))
  1260. @end example
  1261. These are infinite sequences, so it's not possible to convert them to
  1262. a list, but they could be printed (infinitely) with for example
  1263. @example
  1264. (stream-for-each (lambda (n sq)
  1265. (format #t "~a squared is ~a\n" n sq))
  1266. odds oddsquares)
  1267. @print{}
  1268. 1 squared is 1
  1269. 3 squared is 9
  1270. 5 squared is 25
  1271. 7 squared is 49
  1272. @dots{}
  1273. @end example
  1274. @sp 1
  1275. @deffn {Scheme Procedure} make-stream proc initial-state
  1276. Return a new stream, formed by calling @var{proc} successively.
  1277. Each call is @code{(@var{proc} @var{state})}, it should return a pair,
  1278. the @code{car} being the value for the stream, and the @code{cdr}
  1279. being the new @var{state} for the next call. For the first call
  1280. @var{state} is the given @var{initial-state}. At the end of the
  1281. stream, @var{proc} should return some non-pair object.
  1282. @end deffn
  1283. @deffn {Scheme Procedure} stream-car stream
  1284. Return the first element from @var{stream}. @var{stream} must not be
  1285. empty.
  1286. @end deffn
  1287. @deffn {Scheme Procedure} stream-cdr stream
  1288. Return a stream which is the second and subsequent elements of
  1289. @var{stream}. @var{stream} must not be empty.
  1290. @end deffn
  1291. @deffn {Scheme Procedure} stream-null? stream
  1292. Return true if @var{stream} is empty.
  1293. @end deffn
  1294. @deffn {Scheme Procedure} list->stream list
  1295. @deffnx {Scheme Procedure} vector->stream vector
  1296. Return a stream with the contents of @var{list} or @var{vector}.
  1297. @var{list} or @var{vector} should not be modified subsequently, since
  1298. it's unspecified whether changes there will be reflected in the stream
  1299. returned.
  1300. @end deffn
  1301. @deffn {Scheme Procedure} port->stream port readproc
  1302. Return a stream which is the values obtained by reading from
  1303. @var{port} using @var{readproc}. Each read call is
  1304. @code{(@var{readproc} @var{port})}, and it should return an EOF object
  1305. (@pxref{Reading}) at the end of input.
  1306. For example a stream of characters from a file,
  1307. @example
  1308. (port->stream (open-input-file "/foo/bar.txt") read-char)
  1309. @end example
  1310. @end deffn
  1311. @deffn {Scheme Procedure} stream->list stream
  1312. Return a list which is the entire contents of @var{stream}.
  1313. @end deffn
  1314. @deffn {Scheme Procedure} stream->reversed-list stream
  1315. Return a list which is the entire contents of @var{stream}, but in
  1316. reverse order.
  1317. @end deffn
  1318. @deffn {Scheme Procedure} stream->list&length stream
  1319. Return two values (@pxref{Multiple Values}), being firstly a list
  1320. which is the entire contents of @var{stream}, and secondly the number
  1321. of elements in that list.
  1322. @end deffn
  1323. @deffn {Scheme Procedure} stream->reversed-list&length stream
  1324. Return two values (@pxref{Multiple Values}) being firstly a list which
  1325. is the entire contents of @var{stream}, but in reverse order, and
  1326. secondly the number of elements in that list.
  1327. @end deffn
  1328. @deffn {Scheme Procedure} stream->vector stream
  1329. Return a vector which is the entire contents of @var{stream}.
  1330. @end deffn
  1331. @defun stream-fold proc init stream1 stream2 @dots{}
  1332. Apply @var{proc} successively over the elements of the given streams,
  1333. from first to last until the end of the shortest stream is reached.
  1334. Return the result from the last @var{proc} call.
  1335. Each call is @code{(@var{proc} elem1 elem2 @dots{} prev)}, where each
  1336. @var{elem} is from the corresponding @var{stream}. @var{prev} is the
  1337. return from the previous @var{proc} call, or the given @var{init} for
  1338. the first call.
  1339. @end defun
  1340. @defun stream-for-each proc stream1 stream2 @dots{}
  1341. Call @var{proc} on the elements from the given @var{stream}s. The
  1342. return value is unspecified.
  1343. Each call is @code{(@var{proc} elem1 elem2 @dots{})}, where each
  1344. @var{elem} is from the corresponding @var{stream}.
  1345. @code{stream-for-each} stops when it reaches the end of the shortest
  1346. @var{stream}.
  1347. @end defun
  1348. @defun stream-map proc stream1 stream2 @dots{}
  1349. Return a new stream which is the results of applying @var{proc} to the
  1350. elements of the given @var{stream}s.
  1351. Each call is @code{(@var{proc} elem1 elem2 @dots{})}, where each
  1352. @var{elem} is from the corresponding @var{stream}. The new stream
  1353. ends when the end of the shortest given @var{stream} is reached.
  1354. @end defun
  1355. @node Buffered Input
  1356. @section Buffered Input
  1357. @cindex Buffered input
  1358. @cindex Line continuation
  1359. The following functions are provided by
  1360. @example
  1361. (use-modules (ice-9 buffered-input))
  1362. @end example
  1363. A buffered input port allows a reader function to return chunks of
  1364. characters which are to be handed out on reading the port. A notion
  1365. of further input for an application level logical expression is
  1366. maintained too, and passed through to the reader.
  1367. @deffn {Scheme Procedure} make-buffered-input-port reader
  1368. Create an input port which returns characters obtained from the given
  1369. @var{reader} function. @var{reader} is called (@var{reader} cont),
  1370. and should return a string or an EOF object.
  1371. The new port gives precisely the characters returned by @var{reader},
  1372. nothing is added, so if any newline characters or other separators are
  1373. desired they must come from the reader function.
  1374. The @var{cont} parameter to @var{reader} is @code{#f} for initial
  1375. input, or @code{#t} when continuing an expression. This is an
  1376. application level notion, set with
  1377. @code{set-buffered-input-continuation?!} below. If the user has
  1378. entered a partial expression then it allows @var{reader} for instance
  1379. to give a different prompt to show more is required.
  1380. @end deffn
  1381. @deffn {Scheme Procedure} make-line-buffered-input-port reader
  1382. @cindex Line buffered input
  1383. Create an input port which returns characters obtained from the
  1384. specified @var{reader} function, similar to
  1385. @code{make-buffered-input-port} above, but where @var{reader} is
  1386. expected to be a line-oriented.
  1387. @var{reader} is called (@var{reader} cont), and should return a string
  1388. or an EOF object as above. Each string is a line of input without a
  1389. newline character, the port code inserts a newline after each string.
  1390. @end deffn
  1391. @deffn {Scheme Procedure} set-buffered-input-continuation?! port cont
  1392. Set the input continuation flag for a given buffered input
  1393. @var{port}.
  1394. An application uses this by calling with a @var{cont} flag of
  1395. @code{#f} when beginning to read a new logical expression. For
  1396. example with the Scheme @code{read} function (@pxref{Scheme Read}),
  1397. @example
  1398. (define my-port (make-buffered-input-port my-reader))
  1399. (set-buffered-input-continuation?! my-port #f)
  1400. (let ((obj (read my-port)))
  1401. ...
  1402. @end example
  1403. @end deffn
  1404. @c Local Variables:
  1405. @c TeX-master: "guile.texi"
  1406. @c End: