Debian Codegraph @

lib/srfi-159/internal/util.scm

raw
1 ;; show.scm -- additional combinator formatters
2 ;; Copyright (c) 2013-2017 Alex Shinn. All rights reserved.
3 ;; BSD-style license: http://synthcode.com/license.txt
4
5 ;;> A library of procedures for formatting Scheme objects to text in
6 ;;> various ways, and for easily concatenating, composing and
7 ;;> extending these formatters.
8
9 ;;> \section{Background}
10 ;;>
11 ;;> There are several approaches to text formatting. Building strings
12 ;;> to \scheme{display} is not acceptable, since it doesn't scale to
13 ;;> very large output. The simplest realistic idea, and what people
14 ;;> resort to in typical portable Scheme, is to interleave
15 ;;> \scheme{display} and \scheme{write} and manual loops, but this is
16 ;;> both extremely verbose and doesn't compose well. A simple concept
17 ;;> such as padding space can't be achieved directly without somehow
18 ;;> capturing intermediate output.
19 ;;>
20 ;;> The traditional approach is to use templates - typically strings,
21 ;;> though in theory any object could be used and indeed Emacs'
22 ;;> mode-line format templates allow arbitrary sexps. Templates can
23 ;;> use either escape sequences (as in C's \cfun{printf} and
24 ;;> \hyperlink["http://en.wikipedia.org/wiki/Format_(Common_Lisp)"]{CL's}
25 ;;> \scheme{format}) or pattern matching (as in Visual Basic's
26 ;;> \cfun{Format},
27 ;;> \hyperlink["http://search.cpan.org/~dconway/Perl6-Form-0.04/Form.pm"}{Perl6's}
28 ;;> \cfun{form}, and SQL date formats). The primary disadvantage of
29 ;;> templates is the relative difficulty (usually impossibility) of
30 ;;> extending them, their opaqueness, and the unreadability that
31 ;;> arises with complex formats. Templates are not without their
32 ;;> advantages, but they are already addressed by other libraries such
33 ;;> as
34 ;;> \hyperlink["http://srfi.schemers.org/srfi-28/srfi-28.html"]{SRFI-28}
35 ;;> and
36 ;;> \hyperlink["http://srfi.schemers.org/srfi-48/srfi-48.html"]{SRFI-48}.
37 ;;>
38 ;;> This library takes a combinator approach. Formats are nested chains
39 ;;> of closures, which are called to produce their output as needed.
40 ;;> The primary goal of this library is to have, first and foremost, a
41 ;;> maximally expressive and extensible formatting library. The next
42 ;;> most important goal is scalability - to be able to handle
43 ;;> arbitrarily large output and not build intermediate results except
44 ;;> where necessary. The third goal is brevity and ease of use.
45
46 ;;> \section{Interface}
47
48 ;;> \procedure{(show out [args ...])}
49 ;;>
50 ;;> The primary interface. Analogous to CL's \scheme{format}, the first
51 ;;> argument is either an output port or a boolean, with \scheme{#t}
52 ;;> indicating \scheme{current-output-port} and \scheme{#f} indicating a
53 ;;> string port. The remaining arguments are formatters, combined as with
54 ;;> \scheme{each}, run with output to the given destination. If \var{out}
55 ;;> is \scheme{#f} then the accumulated output is returned, otherwise
56 ;;> the result is unspecified.
57
58 ;;> \section{Formatters}
59
60 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
61 ;; Spacing
62
63 ;;> Output a single newline.
64 (define nl (displayed "\n"))
65
66 ;;> "Fresh line" - output a newline iff we're not at the start of a
67 ;;> fresh line.
68 (define fl
69 (fn (col) (if (zero? col) nothing nl)))
70
71 ;;> Move to a given tab-stop (using spaces, not tabs).
72 (define (tab-to . o)
73 (fn (col pad-char)
74 (let* ((tab-width (if (pair? o) (car o) 8))
75 (rem (modulo col tab-width)))
76 (if (positive? rem)
77 (displayed (make-string (- tab-width rem) pad-char))
78 nothing))))
79
80 ;;> Move to an explicit column.
81 (define (space-to where)
82 (fn (col pad-char)
83 (displayed (make-string (max 0 (- where col)) pad-char))))
84
85 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
86 ;;; String transformations
87
88 (define (with-string-transformer proc . ls)
89 (fn (output)
90 (let ((output* (lambda (str) (fn () (output (proc str))))))
91 (with ((output output*)) (each-in-list ls)))))
92
93 ;;> Show each of \var{ls}, uppercasing all generated text.
94 (define (upcased . ls) (apply with-string-transformer string-upcase ls))
95
96 ;;> Show each of \var{ls}, lowercasing all generated text.
97 (define (downcased . ls) (apply with-string-transformer string-downcase ls))
98
99 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
100 ;; Padding and trimming
101
102 ;;> Pad the result of \scheme{(each-in-list ls)} to at least
103 ;;> \var{width} characters, equally applied to the left and right,
104 ;;> with any extra odd padding applied to the right. Uses the value
105 ;;> of \scheme{pad-char} for padding, defaulting to \scheme{#\\space}.
106 (define (padded/both width . ls)
107 (call-with-output
108 (each-in-list ls)
109 (lambda (str)
110 (fn (string-width pad-char)
111 (let ((diff (- width (string-width str))))
112 (if (positive? diff)
113 (let* ((diff/2 (quotient diff 2))
114 (left (make-string diff/2 pad-char))
115 (right (if (even? diff)
116 left
117 (make-string (+ 1 diff/2) pad-char))))
118 (each left str right))
119 (displayed str)))))))
120
121 ;;> As \scheme{padded/both} but only applies padding on the right.
122 (define (padded/right width . ls)
123 (fn ((col1 col))
124 (each (each-in-list ls)
125 (fn ((col2 col) pad-char)
126 (displayed (make-string (max 0 (- width (- col2 col1)))
127 pad-char))))))
128
129 ;;> As \scheme{padded/both} but only applies padding on the left.
130 (define (padded/left width . ls)
131 (call-with-output
132 (each-in-list ls)
133 (lambda (str)
134 (fn (string-width pad-char)
135 (let ((diff (- width (string-width str))))
136 (each (make-string (max 0 diff) pad-char) str))))))
137
138 ;;> An alias for \scheme{padded/left}.
139 (define padded padded/left)
140
141 ;; General buffered trim - capture the output apply a trimmer.
142 (define (trimmed/buffered width producer proc)
143 (call-with-output
144 producer
145 (lambda (str)
146 (fn (string-width)
147 (let* ((str-width (string-width str))
148 (diff (- str-width width)))
149 (displayed (if (positive? diff)
150 (proc str str-width diff)
151 str)))))))
152
153 ;;> Trims the result of \scheme{(each-in-list ls)} to at most
154 ;;> \var{width} characters, removed from the right. If any characters
155 ;;> are removed, then the value of \scheme{ellipsis} (default empty)
156 ;;> is used in its place (trimming additional characters as needed to
157 ;;> be sure the final output doesn't exceed \var{width}).
158 (define (trimmed/right width . ls)
159 (trimmed/buffered
160 width
161 (each-in-list ls)
162 (lambda (str str-width diff)
163 (fn (ellipsis string-width col)
164 (let* ((ell (if (char? ellipsis) (string ellipsis) (or ellipsis "")))
165 (ell-len (string-width ell))
166 (diff (- (+ str-width ell-len) width)))
167 (each (if (negative? diff)
168 nothing
169 (substring str 0 (- width ell-len)))
170 ell))))))
171
172 ;;> As \scheme{trimmed} but removes from the left.
173 (define (trimmed/left width . ls)
174 (trimmed/buffered
175 width
176 (each-in-list ls)
177 (lambda (str str-width diff)
178 (fn (ellipsis string-width)
179 (let* ((ell (if (char? ellipsis) (string ellipsis) (or ellipsis "")))
180 (ell-len (string-width ell))
181 (diff (- (+ str-width ell-len) width)))
182 (each ell
183 (if (negative? diff)
184 nothing
185 (string-copy str diff))))))))
186
187 ;;> An alias for \scheme{trimmed/left}.
188 (define trimmed trimmed/left)
189
190 ;;> As \scheme{trimmed} but removes equally from both the left and the
191 ;;> right, removing extra odd characters from the right, and inserting
192 ;;> \scheme{ellipsis} on both sides.
193 (define (trimmed/both width . ls)
194 (trimmed/buffered
195 width
196 (each-in-list ls)
197 (lambda (str str-width diff)
198 (fn (ellipsis string-width)
199 (let* ((ell (if (char? ellipsis) (string ellipsis) (or ellipsis "")))
200 (ell-len (string-width ell))
201 (diff (- (+ str-width ell-len ell-len) width))
202 (left (quotient diff 2))
203 (right (- (string-width str) (quotient (+ diff 1) 2))))
204 (if (negative? diff)
205 ell
206 (each ell (substring str left right) ell)))))))
207
208 ;;> A \scheme{trimmed}, but truncates and terminates immediately if
209 ;;> more than \var{width} characters are generated by \var{ls}. Thus
210 ;;> \var{ls} may lazily generate an infinite amount of output safely
211 ;;> (e.g. \scheme{write-simple} on an infinite list). The nature of
212 ;;> this procedure means only truncating on the right is meaningful.
213 (define (trimmed/lazy width . ls)
214 (fn ((orig-output output) string-width)
215 (call-with-current-continuation
216 (lambda (return)
217 (let ((chars-written 0)
218 (output (or orig-output output-default)))
219 (define (output* str)
220 (let ((len (string-width str)))
221 (set! chars-written (+ chars-written len))
222 (if (> chars-written width)
223 (let* ((end (max 0 (- len (- chars-written width))))
224 (s (substring str 0 end)))
225 (each (output s)
226 (with! (output orig-output))
227 (fn () (return nothing))))
228 (output str))))
229 (with ((output output*))
230 (each-in-list ls)))))))
231
232 ;;> Fits the result of \scheme{(each-in-list ls)} to exactly
233 ;;> \var{width} characters, padding or trimming on the right as
234 ;;> needed.
235 (define (fitted/right width . ls)
236 (padded/right width (trimmed/right width (each-in-list ls))))
237
238 ;;> As \scheme{fitted} but pads/trims from the left.
239 (define (fitted/left width . ls)
240 (padded/left width (trimmed/left width (each-in-list ls))))
241
242 ;;> An alias for \scheme{fitted/left}.
243 (define fitted fitted/left)
244
245 ;;> As \scheme{fitted} but pads/trims equally from both the left and
246 ;;> the right.
247 (define (fitted/both width . ls)
248 (padded/both width (trimmed/both width (each-in-list ls))))
249
250 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
251 ;; Joining and interspersing
252
253 (define (joined/general elt-f last-f dot-f init-ls sep)
254 (fn ()
255 (let lp ((ls init-ls))
256 (cond
257 ((pair? ls)
258 (each (if (eq? ls init-ls) nothing sep)
259 ((if (and last-f (null? (cdr ls))) last-f elt-f) (car ls))
260 (lp (cdr ls))))
261 ((and dot-f (not (null? ls)))
262 (each (if (eq? ls init-ls) nothing sep) (dot-f ls)))
263 (else
264 nothing)))))
265
266 ;;> \procedure{(joined elt-f ls [sep])}
267 ;;>
268 ;;> Joins the result of applying \var{elt-f} to each element of the
269 ;;> list \var{ls} together with \var{sep}, which defaults to the empty
270 ;;> string.
271 (define (joined elt-f ls . o)
272 (joined/general elt-f #f #f ls (if (pair? o) (car o) "")))
273
274 ;;> As \scheme{joined} but treats the separator as a prefix, inserting
275 ;;> before every element instead of between.
276 (define (joined/prefix elt-f ls . o)
277 (if (null? ls)
278 nothing
279 (let ((sep (if (pair? o) (car o) "")))
280 (each sep (joined elt-f ls sep)))))
281
282 ;;> As \scheme{joined} but treats the separator as a suffix, inserting
283 ;;> after every element instead of between.
284 (define (joined/suffix elt-f ls . o)
285 (if (null? ls)
286 nothing
287 (let ((sep (if (pair? o) (car o) "")))
288 (each (joined elt-f ls sep) sep))))
289
290 ;;> As \scheme{joined} but applies \var{last-f}, instead of
291 ;;> \var{elt-f}, to the last element of \var{ls}, useful for
292 ;;> e.g. commas separating a list with "and" before the final element.
293 (define (joined/last elt-f last-f ls . o)
294 (joined/general elt-f last-f #f ls (if (pair? o) (car o) "")))
295
296 ;;> As \scheme{joined} but if \var{ls} is a dotted list applies
297 ;;> \var{dot-f} to the dotted tail as a final element.
298 (define (joined/dot elt-f dot-f ls . o)
299 (joined/general elt-f #f dot-f ls (if (pair? o) (car o) "")))
300
301 ;;> As \scheme{joined} but counts from \var{start} to \var{end}
302 ;;> (exclusive), formatting each integer in the range. If \var{end}
303 ;;> is \scheme{#f} or unspecified, produces an infinite stream of
304 ;;> output.
305 (define (joined/range elt-f start . o)
306 (let ((end (and (pair? o) (car o)))
307 (sep (if (and (pair? o) (pair? (cdr o))) (cadr o) "")))
308 (let lp ((i start))
309 (if (and end (>= i end))
310 nothing
311 (each (if (> i start) sep nothing)
312 (elt-f i)
313 (fn () (lp (+ i 1))))))))