raart:   Racket ASCII Art and Interfaces
1 Buffers
buffer?
make-output-buffer
make-terminal-buffer
make-cached-buffer
color/  c
style/  c
2 Drawing
raart?
raart-w
raart-h
draw
draw-here
style
fg
bg
with-drawing
blank
char
text
hline
vline
halign/  c
valign/  c
vappend2
vappend
vappend*
happend2
happend
happend*
para
para*
place-at
place-at*
frame
matte-at
translate
matte
inset
mask
crop
table
text-rows
if-drawn
place-cursor-after
without-cursor
3 lux integration
make-raart
7.7

raart: Racket ASCII Art and Interfaces

Jay McCarthy

 (require raart) package: raart

The raart module provides an algebraic model of ASCII that can be used for art, user interfaces, and diagrams. It is comparable to 2htdp/image.

Check out some examples in the test directory in the source.

    1 Buffers

    2 Drawing

    3 lux integration

1 Buffers

 (require raart/buffer) package: raart

When drawing, raart renders to a buffer. In almost all circumstances, you should use make-cached-buffer.

procedure

(buffer? x)  boolean?

  x : any/c
Identifiers buffers.

procedure

(make-output-buffer [#:output output])  buffer?

  output : output-port? = (current-output-port)
A buffer that displays to output.

procedure

(make-terminal-buffer rows    
  cols    
  [#:clear? clear?    
  #:output output])  buffer?
  rows : exact-nonnegative-integer?
  cols : exact-nonnegative-integer?
  clear? : boolean? = #t
  output : output-port? = (current-output-port)
A buffer that displays to a terminal of rows rows and cols columns via the port output. If clear? is non-false, then the terminal will be cleared before display.

procedure

(make-cached-buffer rows    
  cols    
  [#:output output])  buffer?
  rows : exact-nonnegative-integer?
  cols : exact-nonnegative-integer?
  output : output-port? = (current-output-port)
A buffer that displays to a terminal of rows rows and cols columns via the port output, with minimal output to the terminal implemented via client-side caching of the screen content so only updates are output.

A contract that recognizes the ASCII colors from the list '(black red green yellow blue magenta cyan white brblack brred brgreen bryellow brblue brmagenta brcyan brwhite), as well as any byte? value. The actual color display depends on the terminal configuration.

A contract that recognizes the ASCII styles from the list '(normal bold inverse underline). The actual font displayed may depend on the terminal configuration.

2 Drawing

 (require raart/draw) package: raart

raart represents ASCII art algebraically as an abstract raart? object.

procedure

(raart? x)  boolean?

  x : any/c
Identifies ASCII art.

procedure

(raart-w x)  exact-nonnegative-integer?

  x : raart?
Returns the width of the art.

procedure

(raart-h x)  exact-nonnegative-integer?

  x : raart?
Returns the height of the art.

procedure

(draw b r)  void?

  b : buffer?
  r : raart?
Displays r to the b buffer.

procedure

(draw-here r)  void?

  r : raart?
Displays r with a freshly created buffer made with make-output-buffer.

procedure

(style s r)  raart?

  s : style/c
  r : raart?
r, except with the style given by s.

procedure

(fg c r)  raart?

  c : color/c
  r : raart?
r, except with the foreground color given by c.

procedure

(bg c r)  raart?

  c : color/c
  r : raart?
r, except with the background color given by c.

procedure

(with-drawing s fc bc r)  raart?

  s : (or/c style/c #f)
  fc : (or/c color/c #f)
  bc : (or/c color/c #f)
  r : raart?
Wraps r in calls to style, fg, and bg if s, fc, or bc (respectively) are provided as non-false.

procedure

(blank [w h])  raart?

  w : exact-nonnegative-integer? = 0
  h : exact-nonnegative-integer? = 0
A blank art of width w and height h.

Examples:
> (draw-here (blank 2 2))

  

  

> (draw-here (blank 5 5))

     

     

     

     

     

procedure

(char c)  raart?

  c : (and/c char? (not/c char-iso-control?))
An art displaying c.

Examples:
> (draw-here (char #\a))

a

> (draw-here (char #\b))

b

procedure

(text s)  raart?

  s : string?
An art displaying s, which must not contain any char-iso-control? characters.

Example:
> (draw-here (text "Hello World!"))

Hello World!

procedure

(hline w)  raart?

  w : exact-nonnegative-integer?
A horizontal line of - characters of width w.

Example:
> (draw-here (hline 5))

─────

procedure

(vline h)  raart?

  h : exact-nonnegative-integer?
A vertical line of | characters of height h.

Example:
> (draw-here (vline 3))

│

A contract for the horizontal alignment modes '(left center right). 'left means that the art will be extended with blanks to the right; 'center places the blanks equally on both sides; and 'right places the blanks to the left.

A contract for the vertical alignment modes '(top center bottom). 'top means that the art will be extended with blanks below";" 'center places the blanks equally on both sides; and 'bottom places the blanks above.

procedure

(vappend2 y    
  x    
  [#:halign halign    
  #:reverse? reverse?])  raart?
  y : raart?
  x : raart?
  halign : 
(or/c
halign/c #f)
 = #f
  reverse? : boolean? = #f
Renders y vertically above x. (If reverse? is true, then the effects are evaluated in the opposite order.) Uses halign to determine the horizontal alignment. If halign is #f, then the arts must have the same width.

Examples:
> (draw-here (vappend2 (text "Hello") (text "World")))

World

Hello

> (draw-here (vappend2 (text "Short") (text "Very Very Long")))

*vappend2: Widths must be equal: 14 vs 5

> (draw-here (vappend2 (text "Short") (text "Very Very Long") #:halign 'left))

Very Very Long

Short         

> (draw-here (vappend2 (text "Short") (text "Very Very Long") #:halign 'right))

Very Very Long

         Short

> (draw-here (vappend2 (text "Short") (text "Very Very Long") #:halign 'center))

Very Very Long

    Short     

procedure

(vappend y    
  x ...    
  [#:halign halign    
  #:reverse? reverse?])  raart?
  y : raart?
  x : raart?
  halign : 
(or/c
halign/c #f)
 = #f
  reverse? : boolean? = #f
Like vappend2, but for many arguments.

Example:
> (draw-here (vappend (text "Short") (text "A Little Medium") (text "Very Very Long") #:halign 'right))

          Short

A Little Medium

 Very Very Long

procedure

(vappend* y-and-xs    
  [#:halign halign    
  #:reverse? reverse?])  raart?
  y-and-xs : (non-empty-listof raart?)
  halign : (or/c halign/c #f) = #f
  reverse? : boolean? = #f
Like vappend, but accepts arguments as a list.

Example:
> (draw-here (vappend* (list (text "Short") (text "A Little Medium") (text "Very Very Long")) #:halign 'right))

          Short

A Little Medium

 Very Very Long

procedure

(happend2 y    
  x    
  [#:valign valign    
  #:reverse? reverse?])  raart?
  y : raart?
  x : raart?
  valign : 
(or/c
valign/c #f)
 = #f
  reverse? : boolean? = #f
Renders y horizontally to the left of x. (If reverse? is true, then the effects are evaluated in the opposite order.) Uses valign to determine the vertical alignment. If valign is #f, then the arts must have the same height.

Examples:
> (draw-here (happend2 (vline 2) (vline 2)))

││

││

> (draw-here (happend2 (vline 2) (vline 4)))

*happend2: Heights must be equal: 4 vs 2

> (draw-here (happend2 (vline 2) (vline 4) #:valign 'top))

││

││

> (draw-here (happend2 (vline 2) (vline 4) #:valign 'center))

│

││

││

> (draw-here (happend2 (vline 2) (vline 4) #:valign 'bottom))

│

││

││

procedure

(happend y    
  x ...    
  [#:valign valign    
  #:reverse? reverse?])  raart?
  y : raart?
  x : raart?
  valign : 
(or/c
valign/c #f)
 = #f
  reverse? : boolean? = #f
Like happend2, but for many arguments.

Example:
> (draw-here (happend (vline 2) (vline 3) (vline 4) #:valign 'top))

│││

│││

 ││

  

procedure

(happend* y-and-xs    
  [#:valign valign    
  #:reverse? reverse?])  raart?
  y-and-xs : (non-empty-listof raart?)
  valign : (or/c valign/c #f) = #f
  reverse? : boolean? = #f
Like happend, but accepts arguments as a list.

Example:
> (draw-here (happend* (list (vline 2) (vline 3) (vline 4)) #:valign 'top))

│││

│││

 ││

  

procedure

(para max-width s [#:halign halign])  raart?

  max-width : exact-nonnegative-integer?
  s : string?
  halign : halign/c = 'left
An art displaying s, that is at most max-width wide, taking multiple lines if necessary.

Example:
> (draw-here (para 45 "And it came to pass that I, Nephi, said unto my father: I will go and do the things which the Lord hath commanded, for I know that the Lord giveth no commandments unto the children of men, save he shall prepare a way for them that they may accomplish the thing which he commandeth them."))

 And it came to pass that I, Nephi, said unto

my father: I will go and do the things which

the Lord hath commanded, for I know that the

Lord giveth no commandments unto the children

of men, save he shall prepare a way for them

that they may accomplish the thing which he  

commandeth them.                             

procedure

(para* max-width    
  rs    
  [#:halign halign    
  #:gap gap])  raart?
  max-width : exact-nonnegative-integer?
  rs : (listof raart?)
  halign : halign/c = 'left
  gap : raart? = (blank)
Like happend*, but limits the total width and uses vappend when things get too long. para uses this after splitting the input string into words and supplies (text " ") as the gap.

procedure

(place-at back dr dh front)  raart?

  back : raart?
  dr : exact-nonnegative-integer?
  dh : exact-nonnegative-integer?
  front : raart?
Renders front on top of back offset by dr rows and dh columns.

syntax

(place-at* back [dr dc fore] ...)

 
  back : raart?
  dr : exact-nonnegative-integer?
  dc : exact-nonnegative-integer?
  fore : raart?
Calls place-at on a sequence of art objects from back on the left to front on the right.

procedure

(frame [#:style s] #:fg fc #:bg bc x)  raart?

  s : (or/c style/c #f) = #f
  fc : 
(or/c
color/c #f)
  bc : (or/c color/c #f)
  x : raart?
Renders x with a frame where the frame character’s style is controlled by s, fc, and bc.

procedure

(matte-at mw mh c r x)  raart?

  mw : exact-nonnegative-integer?
  mh : exact-nonnegative-integer?
  c : exact-nonnegative-integer?
  r : exact-nonnegative-integer?
  x : raart?
Mattes x inside a blank of size mw columns and mh rows at row r and column c.

procedure

(translate dr dc x)  raart?

  dr : exact-nonnegative-integer?
  dc : exact-nonnegative-integer?
  x : raart?
Translates x by dr rows and dc columns.

procedure

(matte w h [#:halign halign #:valign valign] x)  raart?

  w : exact-nonnegative-integer?
  h : exact-nonnegative-integer?
  halign : halign/c = 'center
  valign : valign/c = 'center
  x : raart?
Mattes x inside a blank of size wxh with the given alignment.

procedure

(inset dw dh x)  raart?

  dw : exact-nonnegative-integer?
  dh : exact-nonnegative-integer?
  x : raart?
Insets x with dw columns and dh rows of blanks.

procedure

(mask mc mw mr mh x)  raart?

  mc : exact-nonnegative-integer?
  mw : exact-nonnegative-integer?
  mr : exact-nonnegative-integer?
  mh : exact-nonnegative-integer?
  x : raart?
Renders the portion of x inside the rectangle (mc,mr) to ((+ mc mw),(+ mr mh)).

procedure

(crop cc cw cr ch x)  raart?

  cc : exact-nonnegative-integer?
  cw : exact-nonnegative-integer?
  cr : exact-nonnegative-integer?
  ch : exact-nonnegative-integer?
  x : raart?
Renders the portion of x inside the rectangle (cc,cr) to ((+ cc cw),(+ cr ch)) and removes the surrounding blanks.

procedure

(table cells    
  [#:frames? frames?    
  #:style s    
  #:fg f    
  #:bg b    
  #:inset-dw dw    
  #:inset-dh dh    
  #:valign row-valign    
  #:halign halign])  raart?
  cells : (listof (listof raart?))
  frames? : boolean? = #t
  s : (or/c style/c #f) = #f
  f : 
(or/c color/c
#f)
 = #f
  b : (or/c color/c #f) = #f
  dw : exact-nonnegative-integer? = 0
  dh : exact-nonnegative-integer? = 0
  row-valign : valign/c = 'top
  halign : 
(or/c halign/c (list*of halign/c (or/c halign/c
'())))
   = 'left
Renders a table of cells where frames are added if frames? is non-false with style and color given by the arguments. Cells are inset by inset-dh rows and inset-dw columns. Cells are horizontally aligned with halign. Rows are vertically aligned with row-valign.

procedure

(text-rows cells)  
(listof (listof
raart?))
  cells : (listof (listof any/c))
Transforms a matrix of content into a matrix of art objects, using ~a composed with text if they are not already art objects.

Renders x and if it ends up being displayed, then calls f with the actual bounding box, given as a row, column, width, and height.

procedure

(place-cursor-after x cr ch)  raart?

  x : raart?
  cr : exact-nonnegative-integer?
  ch : exact-nonnegative-integer?
Renders x but places the cursor at row cr and column ch afterwards.

procedure

(without-cursor x)  raart?

  x : raart?
Renders x, but signals to draw to not display the cursor, if this is the art object given to it. (That is, this has no effect if composed with other drawing operations.)

3 lux integration

 (require raart/lux-chaos) package: raart

raart provides integration with lux via the ansi module.

procedure

(make-raart [#:mouse? mouse?])  chaos?

  mouse? : boolean? = #f
Returns a chaos that manages the terminal.

The values that word-event is called with are characters or screen-size-report structures. If mouse? is non-false, then any-mouse-event, mouse-focus-event, or mouse-event structures may also be provided.

The values that word-output should return are raart? objects. The drawing will use make-cached-buffer to optimize the display process.