terminal-color

0.5-dev

terminal-color

Richard Hopkins

A Racket library to output colored text to the terminal on any platform, including Windows.

1 Introduction

Racket provides several procedures for outputting data, namely display, displayln, print and write. This library provides a corresponding procedure for each of them with the ability to specify what foreground and background color to use.

The signature for these procedures is compatible with the standard ones, as the foreground and background colors are specified using optional keyword arguments. This means any existing call to the standard procedures can easily be modified to use this library as only the name changes.

See the API section for what is provided and further usage instructions.

2 Requirements

This library is compatible with Racket 5.3.6, 6.x and can be installed using the normal raco pkg commands on any platform.

3 Examples

Examples:

> (require racket/port
           terminal-color)
> (define (display-test-output title)
    (displayln title)
    (displayln-color "1: Default colors")
    (displayln-color "2: Green" #:fg 'green)
    (displayln-color "3: White on red" #:fg 'white #:bg 'red)
    (newline))
> (display-test-output "(guess-output-color-mode)")
(guess-output-color-mode)
1: Default colors
2: Green
3: White on red
> (parameterize ([current-output-color-mode 'off])
    (display-test-output "'off"))
'off
1: Default colors
2: Green
3: White on red
> (parameterize ([current-output-color-mode 'ansi])
    (display-test-output "'ansi"))
'ansi
[49;39m1: Default colors[0m
[49;32m2: Green[0m
[41;37m3: White on red[0m
> (when (equal? (system-type 'os) 'windows)
    (parameterize ([current-output-color-mode 'windows])
      (display-test-output "'windows")))
> (void (call-with-output-string
         (λ (out)
           (displayln-color "(current-output-port) and (current-output-color-mode)" #:fg 'cyan)
           (displayln-color "to output string and (current-output-color-mode)" out #:fg 'cyan))))
(current-output-port) and (current-output-color-mode)

4 API

(require terminal-color)

package: terminal-color

procedure
(output-color-mode? v) → boolean?
v : any/c

Returns #t if v is a valid output color mode, #f otherwise.

Valid modes are

'off
'ansi
'win32
NOTE: This ’win32 is deprecated; use ’windows, instead.
'windows

parameter
(current-output-color-mode) → output-color-mode?
(current-output-color-mode mode) → void?
mode : output-color-mode?
= (guess-output-color-mode)

A parameter that defines the current output color mode used by display-color, displayln-color, print-color, write-color. Default value is the result of guess-output-color-mode.

parameter
(current-display-color-mode) → output-color-mode?
(current-display-color-mode mode) → void?
mode : output-color-mode?
= (guess-output-color-mode)

NOTE: This current-display-color-mode is deprecated; use current-output-color-mode, instead.

parameter
(current-output-color-fg) → terminal-color?
(current-output-color-fg mode) → void?
mode : terminal-color?
= 'default

A parameter that defines the current foreground color used by display-color, displayln-color, print-color, write-color unless one is explicitly specified. Default value is 'default.

parameter
(current-output-color-bg) → terminal-color?
(current-output-color-bg mode) → void?
mode : terminal-color?
= 'default

A parameter that defines the current background color used by display-color, displayln-color, print-color, write-color unless one is explicitly specified. Default value is 'default.

procedure
(guess-output-color-mode) → output-color-mode?

A helper to provide a sane value for current-output-color-mode.

If the output is to a terminal then the operating system is checked: unix-like will use ANSI codes ('ansi) and Windows will use Win32 API calls ('windows). Everything else will do nothing ('off).

procedure
(guess-display-color-mode) → output-color-mode?

NOTE: This guess-display-color-mode is deprecated; use guess-output-color-mode, instead.

procedure
(terminal-color? v) → boolean?
v : any/c

Returns #t if v is a valid color, #f otherwise.

Valid colors are

'default
'black
'white
'red
'green
'blue
'cyan
'magenta
'yellow

procedure
(display-color datum [out #:fg fg #:bg bg]) → void?
  datum : any/c
  out : output-port? = (current-output-port)
  fg : terminal-color? = (current-output-color-fg)
  bg : terminal-color? = (current-output-color-bg)

A wrapper for the standard display procedure that will output datum in the requested color if possible followed by resetting the terminal color.

procedure
(displayln-color datum [out #:fg fg #:bg bg]) → void?
  datum : any/c
  out : output-port? = (current-output-port)
  fg : terminal-color? = (current-output-color-fg)
  bg : terminal-color? = (current-output-color-bg)

A wrapper for the standard displayln procedure that will output datum in the requested color if possible followed by resetting the terminal color.

It’s recommended to use this instead of display-color for strings that end with a new line. This is because it will reset the terminal color before the new line as it can be significant on some terminals.

procedure
(print-color datum
[ out
quote-depth
#:fg fg
#:bg bg]) → void?
  datum : any/c
  out : output-port? = (current-output-port)
  quote-depth : (or/c 0 1) = 0
  fg : terminal-color? = (current-output-color-fg)
  bg : terminal-color? = (current-output-color-bg)

A wrapper for the standard print procedure that will output datum in the requested color if possible followed by resetting the terminal color.

procedure
(write-color datum [out #:fg fg #:bg bg]) → void?
  datum : any/c
  out : output-port? = (current-output-port)
  fg : terminal-color? = (current-output-color-fg)
  bg : terminal-color? = (current-output-color-bg)

A wrapper for the standard write procedure that will output datum in the requested color if possible followed by resetting the terminal color.