Getting Started

antsy provides a number of methods for including ANSI Select Graphics Rendition (SGR) display aspects in strings intended for terminal output. These include:

• string escape sequences for most SGR display aspects;
• functions for each SGR display aspect; and
• a render function for applying multiple display aspects at once.

For more details on ANSI SGR display aspects, see the ECMA 48 Standard Document

Requiring antsy

antsy can be required with:

(require '[antsy.core :as antsy])

Using display aspect escape sequences

The antsy.core namespace includes escape sequence constants for each supported display aspect, with name <aspect>-escape-sequence as well as a reset-escape-sequence constant to reset display to the default.

Changing the display aspect for a string is a case of concatenating together the display aspect escape sequence with the string and then resetting back to the default using the reset escape sequence.

For example, to construct a bold string:

(str antsy/bold-escape-sequence "Hello!" antsy/reset-escape-sequence)
; => "Hello!"

or to construct a string with a red background:

(str antsy/red-bg-escape-sequence "Hello!" antsy/reset-escape-sequence)
; => "Hello!"

or to construct a string with a blue foreground:

(str antsy/blue-fg-escape-sequence "Hello!" antsy/reset-escape-sequence)
; => "Hello!"

Escape sequences can be combined as follows:

(str 
  antsy/red-bg-escape-sequence 
  antsy/blue-fg-escape-sequence
  antsy/bold-escape-sequence 
  "Hello!" 
  antsy/reset-escape-sequence)
; => "Hello!"

Using display aspect functions

To simplify applying and resetting display aspects, functions are also provided for each display aspect with the name of the aspect which wrap the provided text in the relevant escape sequences and reset at the end of the text.

For example, to construct a bold string:

(antsy/bold "Hello!")
; => "Hello!"

Many such functions can be applied as follows:

(antsy/bold (antsy/blue-fg "Hello!"))
; => "Hello!"

Using the render function

To simplify applying many display aspects to text, the render function allows a variable number of display aspect names to be provided:

(antsy/render "Hello!" :bold :red-bg :blue-fg)
; => "Hello!"

The render function is also aliased as -> since in effect it threads the text through each of the provided display aspects left to right:

(antsy/-> "Hello!" :bold :red-bg :blue-fg)
; => "Hello!"

Details of all supported display aspects can be found in Supported Display Aspects.