4 Graphics

4 Graphics🔗ℹ

(require ansi-terminal/graphics)

package: ansi-terminal

4.1 Graphics Predicates🔗ℹ

value
color-name? : flat-contract?

The set of 8 major colors specified by name.

value
rgb-color/c : contract?

An RGB color specification represented as a three-member list of bytes.

value
color/c : contract?

TBD

color-name? – One of 16 predefined colors, 8 standard and 8 bright.
code-param/c – Specification of a 256 color.
rgb-color/c – Specification of a color as an RGB value.

If one of the 256 colors are selected, the meaning is as follows:

0..7 – standard 8 colors
8..15 – standard 8 bright colors
16..231 – 6×6×6 color cube
232..252 – 24 greyscale shades from dark to light

value
attribute-name? : flat-contract?

The set of text attribute names; note that this includes both enable and disable names.

4.2 Simple Styling🔗ℹ

The following functions are intended to provide a very direct style approach for both text attributes and colors. The core functions are with-attribute, text-color and on-background which are then simplified further by attribute- and color-specific functions. In all cases the function will take an optional parameter return-to which will specify an attribute or color to set once the provided string has been formatted. In the case of attributes the value 'auto will use a corresponding code to turn off the attribute. For colors the value 'default will use a specific code for either the default foreground or default background color.

procedure
(with-attribute str attribute [return-to]) → string?
  str : string?
  attribute : attribute-name?
  return-to : (or/c #f 'auto attribute-name?) = 'auto

Returns a string with attribute turned into a control string before str and followed by return-to as a control string.

As mentioned above the value 'auto for return-to will use the control sequence to turn off attribute. In the following example the return-to value is the attribute 'not-underline.

Example:

> (with-attribute "text" 'underline 'auto)
"\e[4mtext\e[24m"

A value of #f for return-to will skip adding a return-to control sequence.

Example:

> (with-attribute "text" 'underline #f)
"\e[4mtext"

Alternatively it is possible to specify an entirely different attribute to end the sequence with.

Example:

> (with-attribute "text" 'underline 'bold)
"\e[4mtext\e[1m"

procedure
(bold str [return-to]) → string?
  str : string?
  return-to : (or/c #f 'auto attribute-name?) = 'auto
procedure
(faint str [return-to]) → string?
  str : string?
  return-to : (or/c #f 'auto attribute-name?) = 'auto
procedure
(italic str [return-to]) → string?
  str : string?
  return-to : (or/c #f 'auto attribute-name?) = 'auto
procedure
(underline str [return-to]) → string?
  str : string?
  return-to : (or/c #f 'auto attribute-name?) = 'auto
procedure
(blink-slow str [return-to]) → string?
  str : string?
  return-to : (or/c #f 'auto attribute-name?) = 'auto
procedure
(blink-rapid str [return-to]) → string?
  str : string?
  return-to : (or/c #f 'auto attribute-name?) = 'auto
procedure
(reversed str [return-to]) → string?
  str : string?
  return-to : (or/c #f 'auto attribute-name?) = 'auto
procedure
(conceal str [return-to]) → string?
  str : string?
  return-to : (or/c #f 'auto attribute-name?) = 'auto
procedure
(crossed-out str [return-to]) → string?
  str : string?
  return-to : (or/c #f 'auto attribute-name?) = 'auto
procedure
(font-alternate-1 str [return-to]) → string?
  str : string?
  return-to : (or/c #f 'auto attribute-name?) = 'auto
procedure
(font-alternate-2 str [return-to]) → string?
  str : string?
  return-to : (or/c #f 'auto attribute-name?) = 'auto
procedure
(font-alternate-3 str [return-to]) → string?
  str : string?
  return-to : (or/c #f 'auto attribute-name?) = 'auto
procedure
(font-alternate-4 str [return-to]) → string?
  str : string?
  return-to : (or/c #f 'auto attribute-name?) = 'auto
procedure
(font-alternate-5 str [return-to]) → string?
  str : string?
  return-to : (or/c #f 'auto attribute-name?) = 'auto
procedure
(font-alternate-6 str [return-to]) → string?
  str : string?
  return-to : (or/c #f 'auto attribute-name?) = 'auto
procedure
(font-alternate-7 str [return-to]) → string?
  str : string?
  return-to : (or/c #f 'auto attribute-name?) = 'auto
procedure
(font-alternate-8 str [return-to]) → string?
  str : string?
  return-to : (or/c #f 'auto attribute-name?) = 'auto
procedure
(font-alternate-9 str [return-to]) → string?
  str : string?
  return-to : (or/c #f 'auto attribute-name?) = 'auto
procedure
(font-fraktur str [return-to]) → string?
  str : string?
  return-to : (or/c #f 'auto attribute-name?) = 'auto
procedure
(underline-double str [return-to]) → string?
  str : string?
  return-to : (or/c #f 'auto attribute-name?) = 'auto
procedure
(proportional-spacing str [return-to]) → string?
  str : string?
  return-to : (or/c #f 'auto attribute-name?) = 'auto
procedure
(framed str [return-to]) → string?
  str : string?
  return-to : (or/c #f 'auto attribute-name?) = 'auto
procedure
(encircled str [return-to]) → string?
  str : string?
  return-to : (or/c #f 'auto attribute-name?) = 'auto
procedure
(overline str [return-to]) → string?
  str : string?
  return-to : (or/c #f 'auto attribute-name?) = 'auto
procedure
(ideogram-underline-or-right str [return-to]) → string?
  str : string?
  return-to : (or/c #f 'auto attribute-name?) = 'auto
procedure
(ideogram-double-underline-or-right str
[ return-to]) → string?
  str : string?
  return-to : (or/c #f 'auto attribute-name?) = 'auto
procedure
(ideogram-overline-or-left str [return-to]) → string?
  str : string?
  return-to : (or/c #f 'auto attribute-name?) = 'auto
procedure
(ideogram-double-overline-or-left str
[ return-to]) → string?
  str : string?
  return-to : (or/c #f 'auto attribute-name?) = 'auto
procedure
(ideogram-stress-marking str [return-to]) → string?
  str : string?
  return-to : (or/c #f 'auto attribute-name?) = 'auto
procedure
(superscript str [return-to]) → string?
  str : string?
  return-to : (or/c #f 'auto attribute-name?) = 'auto
procedure
(subscript str [return-to]) → string?
  str : string?
  return-to : (or/c #f 'auto attribute-name?) = 'auto

TBD

Example:

> (string-append "Hello from " (bold (underline "racket")) "!")
"Hello from \e[1m\e[4mracket\e[24m\e[22m!"

Examples:

> (require racket/string)
> (define table-column-line (faint "|"))
> (define table-column-start (string-append table-column-line " "))
> (define table-column-mid (string-append " " table-column-line " "))
> (define table-column-end (string-append " " table-column-line))
> (string-append table-column-start
                 (string-join '("Here" "There" "Everywhere")
                              table-column-mid)
                 table-column-end)
"\e[2m|\e[22m Here \e[2m|\e[22m There \e[2m|\e[22m Everywhere \e[2m|\e[22m"

The following example defines a formatting function ~f which formats numbers in an accounting fashion. For the purposes of this example note that negative amounts are rendered in red and totals have an overline, underline, and are bold.

Examples:

> (require racket/format)
> (define (~f v #:total? (total? #f)
                #:currency (currency "$")
                #:currency-position (position 'left)
                #:currency-separator (separator #f)
                #:zero (zero "-"))
    (let* ((number (if (= (abs v) 0)
                       (~a zero
                           #:min-width 12
                           #:pad-string " "
                           #:align 'right)
                       (~r v
                           #:notation 'positional
                           #:sign 'parens
                           #:precision 2
                           #:min-width 12
                           #:pad-string " "
                           #:groups '(3)
                           #:group-sep ","
                           #:decimal-sep ".")))
           (pad-string (if separator separator ""))
           (amount (cond
                    ((eq? position 'left)
                     (string-append currency pad-string number))
                    ((eq? position 'right)
                     (string-append number pad-string currency))
                    (else number)))
           (colored (if (< v 0) (red-text amount) amount))
           (styled (if total?
                       (bold (underline (overline colored)))
                       colored)))
    styled))
> (~f 19.99)
"$       19.99"
> (~f -19.99)
"\e[31m$(       19.99)\e[39m"
> (~f 0)
"$           -"
> (~f 19.99 #:currency "USD" #:currency-position 'right)
"       19.99USD"
> (~f 19.99 #:total? #t)
"\e[1m\e[4m\e[53m$       19.99\e[55m\e[24m\e[22m"

procedure
(text-color str color [return-to]) → string?
  str : string?
  color : color-name?
  return-to : (or/c #f color/c) = 'default

Returns a string with color turned into a control string before str and followed by return-to as a control string.

As mentioned above the value 'default for return-to will use the control sequence for the default foregound color.

Example:

> (text-color "text" 'red 'default)
"\e[31mtext\e[39m"

A value of #f for return-to will skip adding a return-to control sequence.

Example:

> (text-color "text" 'red #f)
"\e[31mtext"

Alternatively it is possible to specify an entirely different color to end the sequence with.

Example:

> (text-color "text" 'red 'green)
"\e[31mtext\e[32m"

procedure
(black-text str [return-to]) → string?
  str : string?
  return-to : (or/c #f color/c) = 'default
procedure
(red-text str [return-to]) → string?
  str : string?
  return-to : (or/c #f color/c) = 'default
procedure
(green-text str [return-to]) → string?
  str : string?
  return-to : (or/c #f color/c) = 'default
procedure
(yellow-text str [return-to]) → string?
  str : string?
  return-to : (or/c #f color/c) = 'default
procedure
(blue-text str [return-to]) → string?
  str : string?
  return-to : (or/c #f color/c) = 'default
procedure
(magenta-text str [return-to]) → string?
  str : string?
  return-to : (or/c #f color/c) = 'default
procedure
(cyan-text str [return-to]) → string?
  str : string?
  return-to : (or/c #f color/c) = 'default
procedure
(white-text str [return-to]) → string?
  str : string?
  return-to : (or/c #f color/c) = 'default
procedure
(bright-black-text str [return-to]) → string?
  str : string?
  return-to : (or/c #f color/c) = 'default
procedure
(bright-red-text str [return-to]) → string?
  str : string?
  return-to : (or/c #f color/c) = 'default
procedure
(bright-green-text str [return-to]) → string?
  str : string?
  return-to : (or/c #f color/c) = 'default
procedure
(bright-yellow-text str [return-to]) → string?
  str : string?
  return-to : (or/c #f color/c) = 'default
procedure
(bright-blue-text str [return-to]) → string?
  str : string?
  return-to : (or/c #f color/c) = 'default
procedure
(bright-magenta-text str [return-to]) → string?
  str : string?
  return-to : (or/c #f color/c) = 'default
procedure
(bright-cyan-text str [return-to]) → string?
  str : string?
  return-to : (or/c #f color/c) = 'default
procedure
(bright-white-text str [return-to]) → string?
  str : string?
  return-to : (or/c #f color/c) = 'default

TBD

Example:

> (string-append "Hello from " (blue-text "racket") "!")
"Hello from \e[34mracket\e[39m!"

procedure
(on-background str color [return-to]) → string?
  str : string?
  color : color-name?
  return-to : (or/c #f color/c) = 'default

Returns a string with color turned into a control string before str and followed by return-to as a control string.

As mentioned above the value 'default for return-to will use the control sequence for the default backgound color.

Example:

> (on-background "text" 'red 'default)
"\e[41mtext\e[49m"

A value of #f for return-to will skip adding a return-to control sequence.

Example:

> (on-background "text" 'red #f)
"\e[41mtext"

Alternatively it is possible to specify an entirely different color to end the sequence with.

Example:

> (on-background "text" 'red 'green)
"\e[41mtext\e[42m"

procedure
(on-black str [return-to]) → string?
  str : string?
  return-to : (or/c #f color/c) = 'default
procedure
(on-red str [return-to]) → string?
  str : string?
  return-to : (or/c #f color/c) = 'default
procedure
(on-green str [return-to]) → string?
  str : string?
  return-to : (or/c #f color/c) = 'default
procedure
(on-yellow str [return-to]) → string?
  str : string?
  return-to : (or/c #f color/c) = 'default
procedure
(on-blue str [return-to]) → string?
  str : string?
  return-to : (or/c #f color/c) = 'default
procedure
(on-magenta str [return-to]) → string?
  str : string?
  return-to : (or/c #f color/c) = 'default
procedure
(on-cyan str [return-to]) → string?
  str : string?
  return-to : (or/c #f color/c) = 'default
procedure
(on-white str [return-to]) → string?
  str : string?
  return-to : (or/c #f color/c) = 'default
procedure
(on-bright-black str [return-to]) → string?
  str : string?
  return-to : (or/c #f color/c) = 'default
procedure
(on-bright-red str [return-to]) → string?
  str : string?
  return-to : (or/c #f color/c) = 'default
procedure
(on-bright-green str [return-to]) → string?
  str : string?
  return-to : (or/c #f color/c) = 'default
procedure
(on-bright-yellow str [return-to]) → string?
  str : string?
  return-to : (or/c #f color/c) = 'default
procedure
(on-bright-blue str [return-to]) → string?
  str : string?
  return-to : (or/c #f color/c) = 'default
procedure
(on-bright-magenta str [return-to]) → string?
  str : string?
  return-to : (or/c #f color/c) = 'default
procedure
(on-bright-cyan str [return-to]) → string?
  str : string?
  return-to : (or/c #f color/c) = 'default
procedure
(on-bright-white str [return-to]) → string?
  str : string?
  return-to : (or/c #f color/c) = 'default

TBD

Example:

> (string-append "Hello from " (white-text (on-blue "racket")) "!")
"Hello from \e[37m\e[44mracket\e[49m\e[39m!"

4.3 Complex Styling🔗ℹ

This section allows for more complex styling in that styles can be more easily combined and also defined in a reusasable structure, the style?.

predicate
(style? val) → boolean?
val : any/c

Returns #t if val, is a style structure instance.

procedure
(style->list style) → (listof code-param-list/c)
style : style?

TBD

procedure
(style-append style-1 style-2) → style?
style-1 : style?
style-2 : style?

TBD

procedure
(style-push style-1 code-list) → style?
style-1 : style?
code-list : code-param-list/c

TBD

procedure
(style-pop style) → style?
style : style?

TBD

procedure
(style->string style) → string?
style : style?

TBD

value
reset : style?

TBD

value
make-style-param/c : contract?

TBD

'underline – Turns on the specified text attribute.
'(not bold) – Turns off the specified text attribute.
'blue – Sets the foreground color.
'(text blue) – Sets the foreground color, note that the first symbol may be also be 'fg or 'foreground.
'(on green) – Sets the background color, note that the first symbol may be also be 'bg or 'background.

procedure
(make-style st ...+) → style?
st : make-style-param/c

TBD

Examples:

> (define normal-style (make-style 'bright-white '(on bright-black)))
> (define success-style (make-style 'green))
> (define error-style (make-style 'red '(on black) 'blink-slow 'bold))
> (if (some-function)
(style-string "OK" success-style #:return-to normal-style)
(style-string "Oops" error-style #:return-to normal-style))
"\e[31;40;5;1mOops\e[97;100m"

procedure
(style-string str
style
[ #:return-to return-to]) → string?
  str : string?
  style : style?
  return-to : style? = reset

TBD

procedure
(~a/styled val style [#:return-to return-to]) → string?
  val : any/c
  style : style?
  return-to : style? = reset

TBD

procedure
(~s/styled val style [#:return-to return-to]) → string?
  val : any/c
  style : style?
  return-to : style? = reset

TBD

1	Common Predicates
2	Control Sequences
3	Terminal Control
4	Graphics
	Bibliography
	Index