Styles

The styles module handles text styling. It provides functions and classes that can be used to customize the display of text in terminals that support escape sequences .

Style

The Style type represents a Select Graphic Rendition (SGR ) sequence. It consists of a list of styling attributes and can be used in any part of the API that expects this type.

Styles are cumulative, i.e., they can be combined depending on the kind of styling attribute. For instance, tf.bold can be combined with fg.green to render text in bold intensity with green foreground color.

Styling attribute

In the next sections we present the various styling attributes available.

Typeface

The tf enumeration declares text typefaces that can be combined. They are listed below.

• Font attributes:
  • bold — bold or increased intensity
  • faint — faint, decreased intensity, or dim (lower opacity)
  • italic — italic type
  • underlined — underlined
  • slowlyBlinking — slowly blinking
  • rapidlyBlinking — rapidly blinking
  • inverse — reverse video or inverse (flips foreground and background color)
  • invisible — invisible, concealed or hidden
  • crossedOut — crossed-out or strikethrough
  • doublyUnderlined — doubly underlined
  • proportionallySpaced — enable proportional spacing
  • alternative[1-9] — alternative font (1 through 9)
  • fraktur — black-letter font
• Ideogram attributes:
  • ideogramUnderline — ideogram underline or right side line
  • ideogramDoubleUnderline — ideogram double underline, or double line on the right side
  • ideogramOverline — ideogram overline or left side line
  • ideogramDoubleOverline — ideogram double overline, or double line on the left side
  • ideogramStressMarking — ideogram stress marking
• Miscellaneous attributes:
  • framed — framed
  • encircled — encircled
  • overlined — overlined
  • superscript — superscript
  • subscript — subscript

Resetting

The rs enumeration declares attributes that can be used to “cancel” other preceding attributes. They are intended for internal use, so are not exposed in the API. They are listed below.

• clear — resets any other preceding attribute
• primaryFont — primary font
• notBoldOrFaint — normal intensity (neither bold nor faint)
• notItalicOrFraktur — regular type (neither italic nor black-letter)
• notUnderlined — not underlined
• notBlinking — steady (not blinking)
• notInverse — positive (not inverse)
• notInvisible — visible (reveal, or not hidden)
• notCrossedOut — not crossed out (no strikethrough)
• defaultForeground — default foreground color
• defaultBackground — default background color
• notProportionallySpaced — disable proportional spacing
• notFramedOrEncircled — neither framed nor encircled
• notOverlined — not overlined
• defaultUnderline — default underline color
• noIdeogram — no ideogram attributes
• notSuperscriptOrSubscript — neither superscript nor subscript

Predefined color

The fg and bg enumerations declare foreground and background colors, respectively. They both have the same set of predefined colors, which are listed below.

• Standard colors:
  • black — black
  • red — red
  • green — green
  • yellow — yellow
  • blue — blue
  • magenta — magenta
  • cyan — cyan
  • white — white
• High-intensity colors:
  • brightBlack — bright “black” (i.e., gray)
  • brightRed — bright red
  • brightGreen — bright green
  • brightYellow — bright yellow
  • brightBlue — bright blue
  • brightMagenta — bright magenta
  • brightCyan — bright cyan
  • brightWhite — bright white

Extended color

In addition to predefined colors, fg and bg have a special enumerator called extended. It must be followed by additional attributes, which can be obtained through one of the auxiliary functions below:

• ext8 — creates an 8-bit indexed color
• rgb — creates a 24-bit RGB color

There is also a ul enumeration with this enumerator, for underline colors. For example, to set the underline color to orange (#FFA500):

const style: Style = [ul.extended, rgb(255, 165, 0)];

ANSI string

The AnsiString component handles the construction of strings that can be printed in a terminal. It has methods for splitting, appending, and wrapping strings with or without control sequences. The main logic implemented in this class is divided into splitting and wrapping, as is explained in the next subsections.

Text splitting

Text is split into paragraphs, list items and words using a combination of simple regular expressions. The features supported in text splitting are described below.

Placeholders

Both the split and format methods of a ANSI string accept a phrase to be split. During splitting, numeric placeholders prefixed with a hashtag # may be extracted from the text and processed by a formatting callback.

This is used by the library in different places:

• by both the parser and validator, to produce error messages based on configured error phrases
• by the formatter, to assemble help items from configured help phrases

Placeholders are meant to be replaced with a value. The number on the placeholder indicates the index of the argument that was passed to the formatting function. The resulting format depends on the type of the value, which is denoted internally by a single character. The available ones are:

• b — a boolean value
• s — a string value (enclosed by the value of the stringQuote connective word)
• n — a number value
• r — a RegExp value
• m — a symbol value (e.g., option name)
• t — another ANSI string instance
• u — a URL value
• a — an array or tuple (elements are enclosed by the values of the arrayOpen and arrayClose connective words)
• o — an object (entries are enclosed by the values of the objectOpen and objectClose connective words)
• v — an unknown value (enclosed by the values of the valueOpen and valueClose connective words)

When a phrase includes placeholders, they indicate where in the phrase to place the corresponding value. The same placeholder may be repeated multiple times. If a phrase has multiple alternatives (depending on the context), different pieces of text may be specified separated by a vertical bar and grouped in parentheses, e.g. '(...|...)'.

Formatting flags

The format method accepts an optional parameter of type FormattingFlags with the following optional properties:

• alt — the phrase alternative, if any
• sep — the element delimiter for array and object values (overrides connective words)
• open — the opening delimiter for array and object values (overrides connective words)
• close — the closing delimiter for array and object values (overrides connective words)
• mergePrev — whether the separator should be merged with the previous element (defaults to true)
• mergeNext — whether the separator should be merged with the next element (defaults to false)
• custom — a custom callback to format the arguments

Paragraphs and lists

Although Markdown  syntax is not fully supported, paragraphs and itemized/numbered lists are formatted in a Markdown-ish fashion. For example, the following text

A paragraph with
  single line breaks,  redundant  spacing  and:
    - itemized; or
  1. numbered lists
 
  Another paragraph

Would be rendered as:

A paragraph with single line breaks, redundant spacing and:
- itemized; or
1. numbered lists
 
Another paragraph

Template literal

You can easily create ANSI strings with the ansi tag function for template literals . The latter can be used in any part of the API that expects a styled string, such as option synopsis, deprecation notice, parameter name and text block. It also has a convenient style method, which accepts a list of styling attributes as parameters, e.g.:

ansi`A text with ${ansi.style(ul.extended, rgb(255, 165, 0))`orange underline`}.`;

You can freely nest template literals with or without style. Just be aware that arguments inside the template will be treated as placeholders. So, for example, a traditional (non-ANSI) template literal will be treated as plain string and thus subject to the formatting of a string placeholder.

Text wrapping

Splitted text is always wrapped according to a configured width, i.e., the number of terminal columns by which to limit each line of text. When a width of zero or NaN is provided, the ANSI string will by default avoid wrapping and instead suppress control sequences that would otherwise be used to render the text in a terminal.

The following features are supported in text wrapping.

Indentation level

The ANSI string has an optional indentation level, i.e., the starting terminal column of each new line of text. When wrapping text to the desired width, the instance will attempt to respect this setting, but if the desired width does not accommodate the length of the largest word, it will disregard the indentation level.

Text alignment

The ANSI string has an optional flag that indicates whether the text should be aligned to the terminal’s right boundary (or according to the instance’s width property). This feature is used by the formatter in help messages.

Line-wise wrapping

The ANSI string can be chained with another instance for the purpose of multi-column wrapping. We call this mode “line-wise”, because it allows the lines of each instance to be wrapped independently of other instances. This feature is used by the formatter when rendering a groups section configured with non-responsive layout.

The first instance in a chain serves as the “head”, and it drives the procedure until all lines of all instances are wrapped. The final instance in a chain serves as the “tail”, and should be empty (i.e., have no internal strings). Line feeds from child instances are ignored, because it is he head who appends them to the result.

In this mode, the terminal width is ignored, as it makes no sense. Instead, each instance should be configured with its own width. For this to work, the length of the longest word in any instance must not exceed the instance’s width. Otherwise, an error will be raised to alert the developer of this issue.

Messages

There are different kinds of content that an application might want to print in the terminal. We denote them “messages” and provide a specific class for each kind of message that the library can produce.

For convenience, all message classes have a toString method and a message property, both of which can be used to obtain a plain string. However, each class uses its own default terminal width to render the resulting string. The various classes are described below.

ANSI message

The AnsiMessage class wraps a list of ANSI strings and is the type used for help messages and version info. It provides a wrap method to get a plain string, accepting the following optional parameters:

• width — the desired terminal width (0 means no wrapping)
• emitStyles — whether styles should be emitted
• emitSpaces — whether spaces should be emitted instead of move sequences

The default values of these parameters depend on a few environment variables:

• FORCE_WIDTH — force the terminal width to a specific value (otherwise, see below)
• FORCE_COLOR — force emission of styles regardless of the terminal width
• NO_COLOR — force omission of styles regardless of the terminal width
• TERM — set to 'dumb' to achieve the same behavior as NO_COLOR
• FORCE_SPACES — force emission of spaces when the terminal width is non-zero

When FORCE_WIDTH is not set, the default width used by this class is the columns property of the standard output stream (i.e., process.stdout). Therefore, this kind of message should be printed with console.log or equivalent.

Generally, you should refrain from altering the returned string after being wrapped, as this would mess up the disposition of text in the terminal. If you must, you can either prepend text ending with line feeds, or append text starting with line feeds, as this will preserve the disposition of wrapped text.

Error message

The ErrorMessage class is a specialization of the ANSI message, used for errors and warnings. It also has a utility method add, which appends a ANSI string formatted from either one of the error phrases or a custom phrase.

When FORCE_WIDTH is not set, the default width used by this class is the columns property of the standard error stream (i.e., process.stderr). Therefore, this kind of message should be printed with console.error or equivalent.

Text message

The TextMessage class represents a list of text lines with no wrapping and is the type used for completion words. It produces a string delimited by line feeds, and should be printed with console.log or equivalent.

JSON message

The JsonMessage class represents a list of opaque objects and is the type used for completion suggestions. It produces a serialized JSON string, and should be printed with console.log or equivalent.

Message configuration

ANSI-based messages produced by the library can be customized via the global config object, which is a singleton instance of the MessageConfig type, containing the properties described below.

Message styles

The styles property specifies the styles of text elements in ANSI messages. It has the following settings:

Connective words

The connectives property specifies words used to format some text elements that cannot be customized with phrases, such as option requirements, element separators and string quoting. It has the following settings:

Error phrases

The errorPhrases property specifies the phrases to use for error messages. It has the following settings, whose keys are enumerators from ErrorItem:

Help phrases

The helpPhrases property specifies the phrases to use for help items. It has the following settings, whose keys are enumerators from HelpItem: