_  _                       _
                  (_)(_)                     | |
  __ _  ___   ___  _  _  ______   __ _  _ __ | |_
 / _` |/ __| / __|| || ||______| / _` || '__|| __|
| (_| |\__ \| (__ | || |        | (_| || |   | |_
 \__,_||___/ \___||_||_|         \__,_||_|    \__|

ascii-art-ansi.js

This module allows you to work with ansi strings in a style aware way, so you aren't constantly doing string manipulation and scanning when working with terminal strings. It offers a clean abstraction to build ascii-art utilities on top of.

Installation

npm install ascii-art-ansi

Usage

require('ascii-art-ansii')

To do anything with it, you'll need to include the library:

    const ansi = require('ascii-art-ansi');
    const color = require('ascii-art-ansi/color');

• ascii-art-ansi
  • .map(ansi_string, handler) ⇒ string
  • .length(ansi_string) ⇒ int
  • .strip(ansi_string) ⇒ string
  • .toArray(ansi_string) ⇒ Array
  • .substring(ansi_string, start, stop) ⇒ string
  • .charAt(ansi_string, position) ⇒ string (length:1)
  • .intersect(string1, .. stingN, callback) ⇒ Promise (if callback not present)
  • .interstyle(string1, .. stingN, callback) ⇒ Promise (if callback not present)
• ascii-art-ansi/color
  • Color.code(value) ⇒ string
  • Color.name(value) ⇒ string
  • Color.is256 ⇒ boolean
  • Color.isTrueColor ⇒ boolean

.map(ansiString, handler)

Map through an ansi string one character at a time, without any of those characters being styles.

Kind: static property of ascii-art-ansi

| Param | Type | Description | | --- | --- | --- | | ansiString | string | input string to map across | | handler | function | the function to map through the string |

Example

    var result = ansi.map(
        ansiString,
        function(chr, codes, rowcol, pos, shortcircuit){
            // chr : the character
            // codes : a list of the active ansi codes as strings
            // rowcol: array of the 2D position of chr in a multiline string
            // pos : the position of the character
            // shortcircuit : function which stops processing after return
        }
    );

.length(ansiString)

The number of non ansi code characters in the string

Kind: static property of ascii-art-ansi

| Param | Type | Description | | --- | --- | --- | | ansiString | string | input string to measure |

Example

    var result = ansi.length(ansiString);

.strip(ansiString)

Remove any ansi codes from the string

Kind: static property of ascii-art-ansi

| Param | Type | Description | | --- | --- | --- | | ansiString | string | input string to measure |

Example

    var result = ansi.strip(ansiString);

.length(ansiString)

convert this string to an array of characters

Kind: static property of ascii-art-ansi

| Param | Type | Description | | --- | --- | --- | | ansiString | string | input string to measure |

Example

    var result = ansi.toArray(ansiString);

.charAt(ansiString)

Extract a specific character from the string, by position Kind: static property of ascii-art-ansi

| Param | Type | Description | | --- | --- | --- | | ansiString | string | input string to measure |

Example

    var chr = ansi.charAt(ansiString, 4);

.substring(ansiString, start, stop)

Like the javascript built-in substring, but ansi aware

Kind: static property of ascii-art-ansi

| Param | Type | Description | | --- | --- | --- | | ansiString | string | input string to measure |

Example

    var chr = ansi.trimTo(ansiString, 4);

.intersect(ansiString)

Intersect/overlay any number of strings

Kind: static property of ascii-art-ansi

| Param | Type | Description | | --- | --- | --- | | inputString(N) | string | input string to measure | | callback | function | callback to handle asynchronous return, if omitted, a promise is returned |

Example

    var chr = ansi.intersect(s1, s2, s3, function(err, result){
        // ['A  ', ' B ', '  C'] -> 'ABC'
    });

.interstyle(ansiString)

Intersect/overlay any number of strings and include their styles

Kind: static property of ascii-art-ansi

| Param | Type | Description | | --- | --- | --- | | inputString(N) | string | input string to measure | | callback | function | callback to handle asynchronous return, if omitted, a promise is returned |

Example

    var chr = ansi.interstyle(s1, s2, s3, function(err, result){
        // ['A  ', ' B ', '  C'] -> 'ABC'
    });

.Color(options)

Intersect/overlay any number of strings and include their styles

Kind: static property of ascii-art-ansi

| Param | Type | Description | | --- | --- | --- | | options | Object | options |

Example

    var color = new Color('#FFFFFF')

.Color.code(value)

Compute the code for the given hex color (closest within the active palette)

Kind: static property of ascii-art-ansi/color

| Param | Type | Description | | --- | --- | --- | | value | string | the hex value color of the color |

Example

    var ansiCode = Color.code('#FF0000');

.Color.name(value)

Compute the code for the given named color (closest within the active palette)

Kind: static property of ascii-art-ansi/color

| Param | Type | Description | | --- | --- | --- | | value | string | the name of the color |

Example

    var ansiCode = Color.name('red');

.Color.is256

If set colors will be computed using 256 colors instead of 16. Colors are averaged according to a color averaging scheme which can be changed with Color.useDistance(name); where name is one of euclideanDistance, classic, ratioDistance, classicByValue, CIE76Difference, closestByIntensity, rankedChannel, simple, original

Kind: static property of ascii-art-ansi/color

Example

    Color.is256 = true;

.Color.isTrueColor

If set colors will be computed using millions of colors

Kind: static property of ascii-art-ansi/color

Example

    Color.isTrueColor = true;

Roadmap

Goals

• color reducer
• streaming
• pluggable colorsets/encodings

Testing

In the root directory run:

npm run test

Please make sure to run the tests before submitting a patch and report any rough edges. Thanks!

Enjoy,

-Abbey Hawk Sparrow