| 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)))))))) |