tty-strings


A one stop shop for working with text displayed in the terminal.

About

The goal of this project is to alleviate the headache of working with Javascript's internal representation of unicode characters, particularly within the context of displaying text in the terminal for command line applications.

Features

* Implements the Unicode grapheme cluster breaking algorithm outlined in UAX #29 to split strings into user perceived characters (graphemes).
* Accurately measures of the visual width of strings when they are displayed in the terminal, with support for emoji characters and ZWJ sequences. For more details see the descriptions of the codePointWidth, stringWidth, and charWidths functions below.
* Provides methods for slicing and wrapping strings that contain ANSI escape codes.
* Lightweight with zero dependencies.

Everything in this module is up to date with the latest version of Unicode (currently version 16.0.0).

Check out the acknowledgements section below for a look at the other Javascript projects that inspired this module.

Installation

Install with npm:

``bash
npm install tty-strings
`

Or with yarn:

`bash
yarn add tty-strings
`

Then import one or more of the functions detailed in the section below.

API

$3

Get the visual width of a unicode code point, this project's equivalent of wcwidth. Using this function alone to accurately measure the visual width of strings is insufficient, instead use the stringWidth or charWidths functions as they take into account the context of each code point.

* code - Unicode code point (must be a number).

Returns number - 2 for a full width code point, 0 for a zero width code point, and 1 for everything else.

Code points

Full width code points are all unicode code points whose East_Asian_Width property value is F or W, which are derived from the EastAsianWidth.txt data file associated with UAX #11: East Asian Width.

Zero width code points include all unicode code points whose General_Category property value is Mn, Me, or Cc (derived from the DerivedGeneralCategory.txt data file), as well as all code points with the Default_Ignorable_Code_Point property, (derived from the DerivedCoreProperties.txt data file). Check out UAX #44: Unicode Character Database for more information about these properties.

Example

`js
const { codePointWidth } = require('tty-strings');

// The numerical code point for '古' is 53E4

codePointWidth(0x53E4);
// > 2
`

$3

Get the length of a string in grapheme clusters. ANSI escape codes will be ignored.

* string - Input string to measure.

Returns number - the length of the string in graphemes.

Example

`js
const { stringLength } = require('tty-strings');

'🏳️‍🌈'.length;
// > 6

stringLength('🏳️‍🌈');
// > 1
`

$3

Measure the visual width of a string. ANSI escape codes will be ignored. This function endeavors to be more accurate than an implementation of wcswidth, as it takes into account the context of each code point within a grapheme cluster.

* string - Input string to measure.

Returns number - the visual width of the string.

Example

`js
const { stringWidth } = require('tty-strings');

stringWidth('🧑🏻‍🤝‍🧑🏼');
// > 2
`

$3

Word wrap text to a specified column width.

Input string may contain ANSI escape codes. Style and hyperlink sequences will be wrapped, while all other types of control sequences will be ignored and will not be included in the output string.

* string - Text to word wrap.
* columns - Column width to wrap text to.
* options - Optional options object specifying the properties detailed below.

Returns string - the word wrapped string.

#### options.hard

Type: boolean\
Default: false

By default, words that are longer than the specified column width will not be broken and will therefore extend past the specified column width. Setting this to true will enable hard wrapping, in which words longer than the column width will be broken and wrapped across multiple rows.

#### options.trimLeft

Type: boolean\
Default: true

Trim leading whitespace from the beginning of each line. Setting this to false will preserve any leading whitespace found before each line in the input string.

Example

`js
const { wordWrap } = require('tty-strings'),
chalk = require('chalk');

const text = 'The ' + chalk.bgGreen.magenta('quick brown 🦊 jumps over') + ' the 😴 🐶.';

console.log(wordWrap(text, 20));
`

$3

Slice a string by character index. Behaves like the native String.slice(), except that indexes refer to grapheme clusters within the string.

Input string may contain ANSI escape sequences. Style and hyperlink sequences that apply to the sliced portion of the string will be preserved, while all other types of control sequences will be ignored and will not be included in the output slice.

* string - Input string to slice.
* beginIndex - Character index (defaults to 0) at which to begin the slice. Negative values specify a position measured from the character length of the string.
* endIndex - Character index before which to end the slice. Negative values specify a position measured from the character length of the string. If omitted, the slice will extend to the end of the string.

Returns string - the sliced string.

Example

`js
const { sliceChars } = require('tty-strings');

sliceChars('🙈🙉🙊', 0, 2);
// > '🙈🙉';
`

$3

Slice a string by column index. Behaves like the native String.slice(), except that indexes account for the visual width of each character.

Input string may contain ANSI escape sequences. Style and hyperlink sequences that apply to the sliced portion of the string will be preserved, while all other types of control sequences will be ignored and will not be included in the output slice.

* string - Input string to slice.
* beginIndex - Column index (defaults to 0) at which to begin the slice. Negative values specify a position measured from the visual width of the string.
* endIndex - Column index before which to end the slice. Negative values specify a position measured from the visual width of the string. If omitted, the slice will extend to the end of the string.

Returns string - the sliced string.

Example

`js
const { sliceColumns } = require('tty-strings');

// '🙈', '🙉', and '🙊' are all full width characters

sliceColumns('🙈🙉🙊', 0, 2);
// > '🙈'
`

$3

Insert, remove or replace characters from a string, similar to the native Array.splice() method, except that the start index and delete count refer to grapheme clusters within the string.

String may contain ANSI escape codes; inserted content will adopt any ANSI styling applied to the character immediately preceding the insert point. ANSI control sequences that are not style or hyperlink sequences will be preserved in the output string.

* string - Input string to remove, insert, or replace characters from.
* start - Character index at which to begin splicing. Negative values specify a position measured from the character length of the string.
* deleteCount - The number of characters to remove from the string. If 0, no characters will be removed from the string.
* insert - Optional string to be inserted at the index specified by the start parameter. If omitted, nothing will be inserted into the string.

Returns string - the modified input string.

Example

`js
const { spliceChars } = require('tty-strings');

spliceChars('à̰ b̸ ĉ̥', 2, 1, 'x͎͛ÿz̯̆');
// > 'à̰ x͎͛ÿz̯̆ ĉ̥'
`

$3

Split a string with ANSI escape codes into an array of lines. Supports both CRLF and LF newlines.

ANSI escape codes that are style and hyperlink sequences will be wrapped across the output lines, while all other types of control sequences will be ignored but preserved in the output.

* string - Input string to split.

Returns string[] - lines in the input string.

Example

`js
const { splitLines } = require('tty-strings'),
chalk = require('chalk');

splitLines(chalk.green('foo\nbar'));
// > ['\x1b[32mfoo\x1b[39m', '\x1b[32mbar\x1b[39m']
`

$3

A generator function that splits a string into its component graphemes. Does not handle ANSI escape codes, so make sure to use stripAnsi on any input string before calling this generator.

* string - Input string to split.

Yields - a string for each grapheme.

Example

`js
const { splitChars } = require('tty-strings');

[...'à̰ḇ́ĉ̥'];
// > ['a', '\u0300', '\u0330', 'b', '\u0341', '\u0331', 'c', '\u0302', '\u0325']

[...splitChars('à̰ḇ́ĉ̥')];
// > ['à̰', 'ḇ́', 'ĉ̥']
`

$3

A generator function that splits a string into measured graphemes. Does not handle ANSI escape codes, so make sure to use stripAnsi on any input string before calling this generator. This function endeavors to be more accurate than an implementation of wcswidth, as it takes into account the context of each code point within a grapheme cluster.

* string - Input string to split.

Yields - a [char, width] pair for each grapheme in the string.

Example

`js
const { charWidths } = require('tty-strings');

// Basic latin characters

[...charWidths('abc')]
// > [['a', 1], ['b', 1], ['c', 1]]

// Full width emoji characters

[...charWidths('🙈🙉🙊')]
// > [['🙈', 2], ['🙉', 2], ['🙊', 2]]
`

$3

Remove ANSI escape codes from a string. This method is adapted from chalk's strip-ansi package, but uses a more comprehensive regular expression to match escape sequences.

* string - Input string to strip.

Returns string - the input string with all ANSI escape codes removed.

Example

`js
const { stripAnsi } = require('tty-strings');

stripAnsi('\x1b32mfoo\x1b[39m');
// > 'foo'
`

$3

Creates a regular expression that matches ANSI escape codes. This method is modeled off chalk's [ansi-regex package, but matches a more comprehensive range of escape sequences.

* options - Optional options object to specify the global property detailed below.

Returns RegExp - a regular expression object.

#### options.global

Type: boolean\
Default: true

Whether to include the global flag in the returned regular expression. Set this to false to only match the first escape code in the string.

Example

`js
const { ansiRegex } = require('tty-strings');

'\x1b[32mfoo\x1b[39m'.match(ansiRegex());
// > ['\x1b[32m', '\x1b[39m']
`

Development

Contributions are welcome!

To report a bug or request a feature, please open a new issue.

$3

Install project dependencies and run the test suite with the following command:

`bash
yarn && yarn test
`

To generate coverage reports, run:

`bash
yarn test --coverage
`

Acknowledgements

This project was conceived of as a single module offering improved implementations of the following Javascript packages, all of which are great projects that served as inspiration:

* string-width
* string-length
* is-fullwidth-code-point
* wrap-ansi
* slice-ansi
* ansi-regex
* strip-ansi

This project's internal implementation of the Unicode grapheme cluster breaking algorithm is inspired by Devon Govett's grapheme-breaker and Orlin Georgiev's grapheme-splitter`.

License

MIT