►Shrubbery Notation
▼5 Shrubbery APIs
On this page:
write-shrubbery
pretty-shrubbery
8.17.0.6
  top  contents    up   

5.4 Writing Shrubbery Notation🔗ℹ

 (require shrubbery/write) package: shrubbery-lib
Unlike the functions of shrubbery/print, functions from shrubbery/write output a shrubbery representation without using raw-text properties or other metadata.

procedure

(write-shrubbery v    
  [port    
  #:pretty? pretty?    
  #:width width    
  #:armor? armor?    
  #:prefer-multiline? prefer-multiline?]) → void?
  v : any/c
  port : output-port? = (current-output-port)
  pretty? : any/c = #f
  width : (or/c exact-nonnegative-integer?) = #f
  armor? : any/c = #f
  prefer-multiline? : any/c = #f
Prints v, which must be a valid S-expression representation of a shrubbery (see Parsed Representation). Reading the printed form back in with parse-all produces the same S-expression representation as v. Raw text properties are not used.

The default mode with pretty? as #false prints in a simple and relatively fast way (compared to pretty-shrubbery). When pretty? is a true value, single-line output is preferred if width is #false, otherwise it is preferred only when the line fits with width columns. Use pretty-shrubbery to gain more control over line choices when printing.

If pretty? is #false or armor? is a true value, then the printed form is line- and column-insensitive. If pretty? is a true value, armor? is #f, and prefer-multiline? is a true value, then line breaks are used instead of « and ».

Note that write-shrubbery expects an S-expression, not a syntax object, so it cannot use raw text properties. See also shrubbery-syntax->string.

procedure

(pretty-shrubbery v 
  [#:armor? armor? 
  #:prefer-multiline? prefer-multiline?]) 
 → any/c
  v : any/c
  armor? : any/c = #f
  prefer-multiline? : any/c = #f
Produces a description of how to print v with newlines and indentation. The printed form is line- and column-insensitive if armor? is a true value. If armor? is #f and prefer-multiline? is a true value, then line breaks are used instead of « and ».

The description is an S-expression DAG (directed acyclic graph) that represents pretty-printing instructions and alternatives:

  • string or bytes: print literally.

  • 'nl: print a newline followed by spaces corresponding to the current indentation.

  • `(seq ,doc ...): print each doc in sequence, each with the same indentation.

  • `(nest ,n ,doc): print doc with the current indentation increased by n.

  • `(align ,doc): print doc with the current indentation set to the current output column.

  • `(or ,doc ,doc): print either doc; always taking the first doc in an 'or will produce single-line output if prefer-multiline? is #f, while always taking the second doc will print a maximal number of lines.

The description can be a DAG because 'or alternatives might have components in common. In the worst case, a tree view of the instructions can be exponentially larger than the DAG representation.

  top  contents    up