Styles

The styles module handles text styling. It provides a Style type that behaves like a string consisting of Select Graphic Rendition (SGR ) sequences, and can be used to customize the display of text in terminals that support them.

Styling attributes

A Style can be created with the style function, which accepts a list of styling attributes as parameters. The resulting object can be used in any part of the API that expects this type. It can also be concatenated and embedded in text attributes, such as:

• option synopsis and deprecation notice
• help section titles and texts
• error phrases and help phrases

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

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

Type faces

The tf enumeration declares text type faces that can be combined together. They are listed below.

• Enabling attributes:
  • bold - bold or increased intensity
  • faint - faint, decreased intensity, or dim
  • italic - italic
  • 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
  • proportionalSpacing - proportional spacing
• Font-changing attributes:
  • primaryFont - primary font
  • 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 attributes:
  • clear - resets any other preceding SGR attribute
  • notBoldOrFaint - normal intensity (neither bold nor faint)
  • notItalicNorFraktur - regular face (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)
  • notProportionalSpacing - disable proportional spacing
  • notFramedOrEncircled - neither framed nor encircled
  • notOverlined - not overlined
  • noIdeogram - no ideogram attributes
  • notSuperscriptOrSubscript - neither superscript nor subscript

Predefined colors

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

• default - the default color
• Standard colors:
  • black - black
  • red - red
  • green - green
  • yellow - yellow
  • blue - blue
  • magenta - magenta
  • cyan - cyan
  • white - white
• High-intensity colors:
  • brightBlack - bright black (gray)
  • brightRed - bright red
  • brightGreen - bright green
  • brightYellow - bright yellow
  • brightBlue - bright blue
  • brightMagenta - bright magenta
  • brightCyan - bright cyan
  • brightWhite - bright white

Extended colors

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):

style(ul.extended, rgb(255, 165, 0));

ANSI string

The AnsiString is an internal component that handles the construction of strings which are meant to be printed on a terminal. It has methods to split, append and wrap strings, with or without control sequences, and is used by the library in different places:

• by both the parser and validator, to create error and warning messages
• by the formatter, to build help messages

The main logic implemented in this class is divided into splitting and wrapping, as is explained in the next sections.

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

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/warning 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 (or values, in case of arrays). Their 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
• n - a number value
• r - a regular expression
• m - a symbol value (e.g., option name)
• t - another ANSI string
• u - a URL hyperlink
• a - an array value
• o - an object value
• v - an unknown value (enclosed in angle brackets, like the parameter column)

When a phrase includes placeholders, they indicate where in the phrase to place the corresponding value. 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. '(...|...)'.

Inline styles

Text can contain inline styles. This applies not only to phrases, but to text attributes as well, which the formatter splits into words before adding to the help message.

When splitting text, the ANSI string will try its best to preserve inline styles. However, if you find some corner case that is not currently covered by our unit tests, please submit a bug report .

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

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 undefined is provided (which may happen if the output is being redirected), the ANSI string will by default avoid wrapping and instead suppress some control sequences that would otherwise be used to render the text in a terminal.

The following features are supported in text wrapping.

Indentation level

A ANSI string optionally has an indentation level, i.e., the starting terminal column of each line of text.

When wrapping text to the desired width, the ANSI string will attempt to respect this setting, but if the desired width does not accommodate the length of the largest word, it will instead wrap lines to the first terminal column.

Text alignment

A ANSI string has an optional flag that indicates whether the text should be aligned to the terminal’s right boundary. This feature is used by the formatter in the help message’s description column.

Messages

There are different kinds of content that an application might want to print in a terminal. We call 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 traditional 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. It is the type used for help messages. This class provides a wrap method to get a traditional string, accepting the following optional parameters:

• width - the desired terminal width (use 0 to avoid 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 not alter the returned string after being wrapped, as this will mess up the disposition of text in the terminal. If you do need to, you can either prepend text ending with a line feed '\n', or append text starting with a line feed, as this will preserve the disposition of wrapped text. Alternatively, you can retrieve the underlying ANSI strings from the list and manipulate them before converting the message to string.

Warning message

The WarnMessage class is a specialization of the ANSI message, used for warnings.

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.

It also offers two methods that are used by the library:

• add - appends a ANSI message formatted from one of the error phrases
• addCustom - appends a ANSI message formatted from a custom phrase

Error message

The ErrorMessage class is a specialization of the standard Error class, used for errors. It has the same semantics as the warning message, so it should be printed with console.error or equivalent.

Similarly to the warning message, it offers two static methods that are used by the library:

• create - creates an error message formatted from one of the error phrases
• createCustom - creates an error message formatted from a custom phrase

Text message

The TextMessage class represents a list of plain text lines with no wrapping. It is the type used for completion words. It produces a string delimited by line feeds, 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. It is a singleton instance of the MessageConfig type, which contains the optional properties described below.

Message styles

The styles property specifies the styles of text elements in ANSI messages. It has the following optional 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 optional settings:

Error phrases

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

Help phrases

The helpPhrases property specifies custom phrases to use for each kind of help item that may appear in a help message. It has the following optional settings, whose keys are enumerators from HelpItem: