raart: Racket ASCII Art and Interfaces

7.7

top ← prev up next →

raart: Racket ASCII Art and Interfaces

Jay McCarthy

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.

value
color/c : contract?

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.

value
style/c : contract?

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))
[0m

> (draw-here (blank 5 5))
[0m

procedure
(char c) → raart?
c : (and/c char? (not/c char-iso-control?))

An art displaying c.

Examples:

> (draw-here (char #\a))
[0ma
> (draw-here (char #\b))
[0mb

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!"))
[0mHello World!

procedure
(hline w) → raart?
w : exact-nonnegative-integer?

A horizontal line of - characters of width w.

Example:

> (draw-here (hline 5))
[0m─────

procedure
(vline h) → raart?
h : exact-nonnegative-integer?

A vertical line of | characters of height h.

Example:

> (draw-here (vline 3))
[0m│
│
│

value
halign/c : contract?

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.

value
valign/c : contract?

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")))
[0mWorld
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))
[0mVery Very Long
Short
> (draw-here (vappend2 (text "Short") (text "Very Very Long") #:halign 'right))
[0mVery Very Long
         Short
> (draw-here (vappend2 (text "Short") (text "Very Very Long") #:halign 'center))
[0mVery 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))
[0m 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))
[0m 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)))
[0m││
││
> (draw-here (happend2 (vline 2) (vline 4)))
*happend2: Heights must be equal: 4 vs 2
> (draw-here (happend2 (vline 2) (vline 4) #:valign 'top))
[0m││
││
│
│
> (draw-here (happend2 (vline 2) (vline 4) #:valign 'center))
[0m│
││
││
│
> (draw-here (happend2 (vline 2) (vline 4) #:valign 'bottom))
[0m│
│
││
││

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))
[0m│││
│││
││
│

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))
[0m│││
│││
││
│

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."))
[0m 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.

procedure
(if-drawn f x) → raart?
f :
(-> exact-nonnegative-integer?
exact-nonnegative-integer? exact-nonnegative-integer?
exact-nonnegative-integer? any)
x : raart?

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.

top ← prev up next →