2.1 mischief/stylish: Stylish Printing, an Alternative to Pretty Printing

6.3.90.900

2.1 mischief/stylish: Stylish Printing, an Alternative to Pretty Printing

package: mischief

The mischief/stylish collection defines "stylish" printing as an alternative to "pretty" printing from racket/pretty. Stylish printing uses more uniform formatting by default, is easier to customize, and supports printf-style formatted printing.

Examples:

> (define x
    (list
      (list 1 2 3)
      (vector 4 5 6)
      (quote-syntax (7 8 9))))
> (stylish-printf #:columns 20
    "We can print inputs as values [~v] and expressions [~s]."
    x
    x)
We
can
print
inputs
as
values
[(list
   '(1 2 3)
   (vector 4 5 6)
   #'(7 8 9)
   #| eval:1.0 |#)]
and
expressions
[((1 2 3)
   #[4 5 6]
   #<syntax:1:0 (7 8 9)>)].
> (stylish-print x #:columns 20)
(list
'(1 2 3)
(vector 4 5 6)
#'(7 8 9)
#| eval:1.0 |#)
> (stylish-write x #:columns 20)
((1 2 3)
#[4 5 6]
#<syntax:1:0 (7 8 9)>)
> (stylish-value->expr x)
(list 'list ''(1 2 3) '(vector 4 5 6) (stylish-comment-expr "eval:1.0" '#'(7 8 9)))

2.1.1 Rendering Values Converted to Expressions

procedure
(stylish-print x
[ port
#:expr-style est
#:print-style pst
#:left left
#:right right
#:columns cols]) → void?
  x : any/c
  port : output-port? = (current-output-port)
  est : expr-style? = (current-expr-style)
  pst : print-style? = (current-print-style)
  left : exact-nonnegative-integer? = 0
  right : exact-nonnegative-integer? = 0
   cols : (or/c exact-nonnegative-integer? 'infinity)
= (current-stylish-print-columns)

Prints an expression representing x to port. Converts x to an expression according to est and renders the expression as text according to pst. Formats the result to fit in cols columns, assuming the output is preceded by left characters on the first line and will be followed by right characters on the final line.

procedure
(stylish-println x
[ port
#:expr-style est
#:print-style pst
#:left left
#:right right
#:columns cols]) → void?
  x : any/c
  port : output-port? = (current-output-port)
  est : expr-style? = (current-expr-style)
  pst : print-style? = (current-print-style)
  left : exact-nonnegative-integer? = 0
  right : exact-nonnegative-integer? = 0
   cols : (or/c exact-nonnegative-integer? 'infinity)
= (current-stylish-print-columns)

Prints an expression representing x to port followed by a newline. Equivalent to calling stylish-print followed by (newline port).

procedure
(stylish-print-as-string x
[ #:expr-style est
#:print-style pst
#:left left
#:right right
#:columns cols]) → string?
  x : any/c
  est : expr-style? = (current-expr-style)
  pst : print-style? = (current-print-style)
  left : exact-nonnegative-integer? = 0
  right : exact-nonnegative-integer? = 0
   cols : (or/c exact-nonnegative-integer? 'infinity)
= (current-stylish-print-columns)

Renders an expression representing x as a string. Equivalent to combining get-output-string, stylish-print, and open-output-string.

procedure
(stylish-print-handler x) → void?
x : any/c

Intended for use with current-print. Calls (stylish-println x) unless x is (void).

2.1.2 Rendering Values Without Conversion

procedure
(stylish-write x
[ port
pst
#:left left
#:right right
#:columns cols]) → void?
  x : any/c
  port : output-port? = (current-output-port)
  pst : print-style? = (current-print-style)
  left : exact-nonnegative-integer? = 0
  right : exact-nonnegative-integer? = 0
   cols : (or/c exact-nonnegative-integer? 'infinity)
= (current-stylish-print-columns)

Prints x to port. As stylish-print, assuming x has already been converted to an expression.

procedure
(stylish-writeln x
[ port
pst
#:left left
#:right right
#:columns cols]) → void?
  x : any/c
  port : output-port? = (current-output-port)
  pst : print-style? = (current-print-style)
  left : exact-nonnegative-integer? = 0
  right : exact-nonnegative-integer? = 0
   cols : (or/c exact-nonnegative-integer? 'infinity)
= (current-stylish-print-columns)

Prints x to port, followed by a newline. As stylish-println, assuming x has already been converted to an expression.

procedure
(stylish-write-as-string x
[ pst
#:left left
#:right right
#:columns cols]) → string?
  x : any/c
  pst : print-style? = (current-print-style)
  left : exact-nonnegative-integer? = 0
  right : exact-nonnegative-integer? = 0
   cols : (or/c exact-nonnegative-integer? 'infinity)
= (current-stylish-print-columns)

Renders x as a string. As stylish-print-as-string, assuming x has already been converted to an expression.

2.1.3 Converting Values to Expressions

procedure
(stylish-value->expr x [est]) → any/c
x : any/c
est : expr-style? = (current-expr-style)

Converts the value x to an expression according to est.

procedure
(stylish-quotable-value? x [est]) → boolean?
x : any/c
est : expr-style? = (current-expr-style)

Reports whether x can be quoted to convert it to an expression according to est.

2.1.4 Rendering Values Using Format Strings

procedure
(stylish-printf fmt
arg ...
[ #:port port
#:expr-style est
#:print-style pst
#:left left
#:right right
#:columns cols]) → void?
  fmt : string?
  arg : any/c
  port : output-port? = (current-output-port)
  est : expr-style? = (current-expr-style)
  pst : print-style? = (current-print-style)
  left : exact-nonnegative-integer? = 0
  right : exact-nonnegative-integer? = 0
   cols : (or/c exact-nonnegative-integer? 'infinity)
= (current-stylish-print-columns)

Similar to fprintf, prints fmt, substituting a printed representation of each arg for formatting sequences. The sequence ~a prints an arg using display; ~s uses stylish-write; and ~v uses stylish-print. The sequence ~f expects the corresponding arg to have the form (list fmt arg ...), and prints recursively using stylish-printf.

procedure
(stylish-format fmt
arg ...
[ #:expr-style est
#:print-style pst
#:left left
#:right right
#:columns cols]) → string?
  fmt : string?
  arg : any/c
  est : expr-style? = (current-expr-style)
  pst : print-style? = (current-print-style)
  left : exact-nonnegative-integer? = 0
  right : exact-nonnegative-integer? = 0
   cols : (or/c exact-nonnegative-integer? 'infinity)
= (current-stylish-print-columns)

In the same way that format renders the output of fprintf as a string, stylish-format renders the output of stylish-printf as a string.

2.1.5 Custom Stylish Printing

parameter
(current-stylish-print-columns)
→ (or/c exact-nonnegative-integer? 'infinity)
(current-stylish-print-columns cols) → void?
cols : (or/c exact-nonnegative-integer? 'infinity)

Controls the number of columns used for breaking lines and indenting by stylish-print and related procedures, when no explicit number of columns is given.

procedure
(call-with-stylish-port port
proc
[ #:left left
#:right right
#:columns cols]) → any
  port : output-port?
  proc : (-> output-port? any)
  left : exact-nonnegative-integer? = 0
  right : exact-nonnegative-integer? = 0
   cols : (or/c exact-nonnegative-integer? 'infinity)
= (current-stylish-print-columns)

Used for recursive stylish-printing; calls proc with an output port that records the structure of printed values, breaks lines and indents them appropriately, and prints the final rendered form on port when proc returns.

procedure
(stylish-print-separator port
[ #:indent indent
#:wide? wide?]) → void?
  port : output-port?
  indent : exact-nonnegative-integer? = 0
  wide? : boolean? = #t

Prints whitespace to port. If port is created by call-with-stylish-port, then the separator may be used to break lines by printing a newline and indenting to indent spaces beyond the start of the current line at the current level of recursive stylish-printing. Otherwise, the separator prints a single space if wide? is true and prints nothing if wide? is false.

2.1.5.1 Print Styles

procedure
(print-style? x) → boolean?
x : any/c

Recognizes print styles, which control the way stylish-printing renders values that represent expressions as text.

value
empty-print-style : print-style?

A degenerate style that will not print; extend this to build new print styles from scratch.

value
simple-print-style : print-style?

A basic print style that uses write for all values.

value
default-print-style : print-style?

A print style that renders most readable Racket types in a form that will read as the same thing.

procedure
(print-style-extension? x) → boolean?
x : any/c

Recognizes print style extensions, which control the way stylish-printing renders some specific type of values representing expressions as text.

procedure
(print-style-extension pred proc) → print-style-extension?
pred : predicate/c
proc : (-> pred output-port? print-style? void?)

Creates a print style extension that prints values satisfying pred using proc, given the current output port and print style.

procedure
(extend-print-style pst
ext ...
[ #:after? after?]) → print-style?
  pst : print-style?
  ext : print-style-extension?
  after? : boolean? = #false

Adds the given extensions to pst. Checks the new extensions before any existing extensions, unless after? is true.

procedure
(set-print-style-default-printer pst proc) → print-style?
pst : print-style?
proc : (or/c (-> any/c output-port? void?) #false)

Updates pst to use proc to print any value that has no specific extension.

parameter
(current-print-style) → print-style?
(current-print-style pst) → void?
pst : print-style?

Controls the print style used by stylish-print and related procedures if none is given explicitly. Defaults to default-print-style.

2.1.5.2 Expression Styles

procedure
(expr-style? x) → boolean?
x : any/c

Recognizes expression styles, which control the way values are converted to expressions.

value
empty-expr-style : expr-style?

A degenerate expression style that cannot convert any values; extend this to build new expression styles from scratch.

value
simple-expr-style : expr-style?

A basic expression style that uses print-convert for all values.

value
default-expr-style : expr-style?

An expression style that converts most built-in Racket types to an expression that will eval to the same thing.

procedure
(expr-style-extension? x) → boolean?
x : any/c

Recognizes expression style extensions, which control the way that specific types of values are converted to expressions.

procedure
(expr-style-extension pred
convert
[ quotable?
try-quote?]) → expr-style-extension?
  pred : predicate/c
  convert : (-> pred expr-style? any/c)
   quotable? : (-> pred expr-style? boolean?)
= (lambda {x est} #false)
  try-quote? : boolean? = #true

Produces an extension that converts values satisfying pred to expressions using convert, given the current expression style. The predicate quotable? controls whether values of this type can be included in quote expressions; generally opaque values such as procedures should not be considered quotable. The flag try-quote? controls whether the conversion function prefers to use quote for values of this type; generally self-quoting values can use #false for try-quote?.

procedure
(extend-expr-style est
ext ...
[ #:after? after?]) → expr-style?
  est : expr-style?
  ext : expr-style-extension?
  after? : boolean? = #false

Adds the given extensions to est. Checks the new extensions before any existing extensions, unless after? is true.

procedure
(set-expr-style-default-convert est proc) → expr-style?
est : expr-style?
proc : (or/c (-> any/c any/c) #false)

Updates est to use proc to convert any value that has no specific extension.

parameter
(current-expr-style) → expr-style?
(current-expr-style pst) → void?
pst : expr-style?

Controls the expression style used by stylish-expr and related procedures if none is given explicitly. Defaults to default-expr-style.

syntax
(with-stylish-port body ...+)

Equivalent to:

(call-with-stylish-port (current-output-port)
  (lambda (port)
    (parameterize {[current-output-port port]}
      body ...)))

2.1.5.3 Generic Stylish Printing

syntax
gen:stylish-printable

A generic interface containing the methods generic-stylish-quotable? and generic-stylish-value->expr.

procedure
(stylish-printable? x) → boolean?
x : any/c

Returns #true if x is an instance of gen:stylish-printable; returns false otherwise.

procedure
(generic-stylish-quotable? x) → boolean?
x : stylish-printable?

Used by default-print-style to compute the result of stylish-quotable-value? for instances of gen:stylish-printable.

procedure
(generic-stylish-value->expr x) → boolean?
x : stylish-printable?

Used by default-print-style to compute the result of stylish-value->expr for instances of gen:stylish-printable.

syntax
gen:stylish-writable

A generic interface containing the method generic-stylish-write.

procedure
(stylish-writable? x) → boolean?
x : any/c

Returns #true if x is an instance of gen:stylish-writable; returns false otherwise.

procedure
(generic-stylish-write x) → boolean?
x : stylish-printable?

Used by default-expr-style to perform stylish-write for instances of gen:stylish-writable.

2.1.5.4 Special Expression Types

struct
(struct stylish-comment-expr (comment expr))
comment : string?
expr : any/c

Represents an expression annotated with a comment. In default-print-style, prints as expr #|comment|#.

struct
(struct stylish-unprintable-expr (name))
name : symbol?

Represents a value without a readable/writable representation. In default-print-style, prints as #<name>.

top ← prev up next →

1	Structured Debugging
2	Printing and Error Messages
3	Macros and Syntax Transformers
4	Modules
5	Definitions and Binding Forms
6	First-Order Datatypes
7	Functions and Flow Control
8	Typesetting Formats

2.1	mischief/ stylish: Stylish Printing, an Alternative to Pretty Printing
2.2	mischief/ phrase: Converting Values to Readable Phrases
2.3	mischief/ error: Reporting Errors

2.1.1	Rendering Values Converted to Expressions
2.1.2	Rendering Values Without Conversion
2.1.3	Converting Values to Expressions
2.1.4	Rendering Values Using Format Strings
2.1.5	Custom Stylish Printing