146 lines
4.9 KiB
Racket
146 lines
4.9 KiB
Racket
#lang scribble/manual
|
|
@(require (for-label raart
|
|
lux/chaos
|
|
ansi
|
|
racket/contract
|
|
racket/base))
|
|
|
|
@title{raart: Racket ASCII Art and Interfaces}
|
|
@author{Jay McCarthy}
|
|
|
|
@defmodule[raart]
|
|
|
|
The @racketmodname[raart] module provides an algebraic model of ASCII
|
|
that can be used for art, user interfaces, and diagrams. It is
|
|
comparable to @racketmodname[2htdp/image].
|
|
|
|
Check out some examples in the
|
|
@link["https://github.com/jeapostrophe/raart/tree/master/t"]{test}
|
|
directory in the source.
|
|
|
|
@local-table-of-contents[]
|
|
|
|
@section{Buffers}
|
|
@defmodule[raart/buffer]
|
|
|
|
When drawing, @racketmodname[raart] renders to a @deftech{buffer}. In
|
|
almost all circumstances, you should use @racket[make-cached-buffer].
|
|
|
|
@defproc[(buffer? [x any/c]) boolean?]{Identifiers @tech{buffer}s.}
|
|
|
|
@defproc[(make-output-buffer [#:output output output-port? (current-output-port)])
|
|
buffer?]{
|
|
|
|
A @tech{buffer} that displays to @racket[output].
|
|
|
|
}
|
|
|
|
@defproc[(make-terminal-buffer [rows exact-nonnegative-integer?]
|
|
[cols exact-nonnegative-integer?]
|
|
[#:clear? clear? boolean? #t]
|
|
[#:output output output-port? (current-output-port)])
|
|
buffer?]{
|
|
|
|
A @tech{buffer} that displays to a terminal of @racket[rows] rows and
|
|
@racket[cols] columns via the port @racket[output]. If @racket[clear?]
|
|
is non-false, then the terminal will be cleared before display.
|
|
|
|
}
|
|
|
|
@defproc[(make-cached-buffer [rows exact-nonnegative-integer?]
|
|
[cols exact-nonnegative-integer?]
|
|
[#:output output output-port? (current-output-port)])
|
|
buffer?]{
|
|
|
|
A @tech{buffer} that displays to a terminal of @racket[rows] rows and
|
|
@racket[cols] columns via the port @racket[output], with minimal
|
|
output to the terminal implemented via client-side caching of the
|
|
screen content so only updates are output. }
|
|
|
|
@defthing[color/c contract?]{
|
|
|
|
A contract that recognizes the ASCII colors from the list
|
|
@racket['(black red green yellow blue magenta cyan white brblack brred
|
|
brgreen bryellow brblue brmagenta brcyan brwhite)]. The actual color
|
|
display depends on the terminal configuration. }
|
|
|
|
@defthing[style/c contract?]{
|
|
|
|
A contract that recognizes the ASCII styles from the list
|
|
@racket['(normal bold inverse underline)]. The actual font displayed
|
|
may depend on the terminal configuration. }
|
|
|
|
@section{Drawing}
|
|
@defmodule[raart/draw]
|
|
|
|
@racketmodname[raart] represents ASCII art algebraically as an
|
|
abstract @racket[raart?] object.
|
|
|
|
@defproc[(raart? [x any/c]) boolean?]{Identifies ASCII art.}
|
|
|
|
@defproc[(raart-w [x raart?]) exact-nonnegative-integer?]{Returns the
|
|
width of the art.}
|
|
|
|
@defproc[(raart-h [x raart?]) exact-nonnegative-integer?]{Returns the
|
|
height of the art.}
|
|
|
|
@defproc[(draw [b buffer?] [r raart?]) void?]{Displays @racket[r] to
|
|
the @racket[b] buffer.}
|
|
|
|
@defproc[(draw-here [r raart?]) void?]{Displays @racket[r] with a
|
|
freshly created buffer made with @racket[make-output-buffer].}
|
|
|
|
@defproc[(style [s style/c] [r raart?]) raart?]{@racket[r], except
|
|
with the style given by @racket[s].}
|
|
|
|
@defproc[(fg [c color/c] [r raart?]) raart?]{@racket[r], except with
|
|
the foreground color given by @racket[c].}
|
|
|
|
@defproc[(bg [c color/c] [r raart?]) raart?]{@racket[r], except with
|
|
the background color given by @racket[c].}
|
|
|
|
@defproc[(with-drawing [s (or/c style/c #f)] [fc (or/c color/c #f)]
|
|
[bc (or/c color/c #f)] [r raart?]) raart?]{Wraps @racket[r] in calls
|
|
to @racket[style], @racket[fg], and @racket[bg] if @racket[s],
|
|
@racket[fc], or @racket[bc] (respectively) are provided as non-false.}
|
|
|
|
@defproc[(blank [w exact-nonnegative-integer? 0] [h
|
|
exact-nonnegative-integer? 0]) raart?]{A blank art of width @racket[w]
|
|
and height @racket[h].}
|
|
|
|
@defproc[(char [c (and/c char? (not/c char-iso-control?))]) raart?]{An
|
|
art displaying @racket[c].}
|
|
|
|
@defproc[(text [s string?]) raart?]{An art displaying @racket[s],
|
|
which must not contain any @racket[char-iso-control?] characters.}
|
|
|
|
@defproc[(hline [w exact-nonnegative-integer?]) raart?]{A horizontal
|
|
line of @litchar{-} characters of width @racket[w].}
|
|
|
|
@defproc[(vline [h exact-nonnegative-integer?]) raart?]{A vertical
|
|
line of @litchar{|} characters of height @racket[h].}
|
|
|
|
XXX
|
|
|
|
@section{lux integration}
|
|
@defmodule[raart/lux-chaos]
|
|
|
|
@racketmodname[raart] provides integration with @racketmodname[lux]
|
|
via the @racketmodname[ansi] module.
|
|
|
|
@defproc[(make-raart [#:mouse? mouse? boolean? #f]) chaos?]{
|
|
|
|
Returns a @tech[#:doc '(lib "lux/scribblings/lux.scrbl")]{chaos} that
|
|
manages the terminal.
|
|
|
|
The values that @racket[word-event] is called with are characters or
|
|
@racket[screen-size-report] structures. If @racket[mouse?] is
|
|
non-false, then @racket[any-mouse-event], @racket[mouse-focus-event],
|
|
or @racket[mouse-event] structures may also be provided.
|
|
|
|
The values that @racket[word-output] should return are @racket[raart?]
|
|
objects. The drawing will use @racket[make-cached-buffer] to optimize
|
|
the display process.
|
|
|
|
}
|