Narcoleptic Pasta Manufacturer

    ansi-state

    1.0.5 • Public • Published

    node-ansi-state

    Build Status

    Use this module to capture the state of your ANSI colors and styles, and restore them at another time and/or place.

    Sometimes you need to keep track of multiple ANSI style states, though you may not know what they are. This module provides:

    • Full ANSI style code capturing, including: foreground & background colour (xterm colours too!), intensity, italic, underline, blink, polarity, conceal, strikethrough, font, framed and overlined styles.
    • The ability to check all the state style attributes listed above.`
    • A streamable interface (pipe or write to update).
    • The ability to create multiple instances to save multiple style states.
    • Restore any state instance at any time.

    Installation

    npm install --save ansi-state

    Basic Usage

    Include

    var ANSIState = require('ansi-state')

    Create a New State

    Instantiate a new state with the constructor:

    var state = new ANSIState()

    Manually Save ANSI Style Codes

    You can update the state manually by calling the corresponding method on it and passing in a string or array that contains ansi style codes. Only the most recently received codes for various attributes will be kept (ie. you can only have one foreground colour at a time). This module keeps track of all of that for you!

    state.update('\033[32mHi there! \033[31mRed text')
    //current state becomes: \033[31m
     
    state.update('\033[1mBolding the text too')
    //current state becomes: \033[1;31m
     
    state.update('\033[34;38;5;211mxterm colors too!')
    //current state becomes: \033[1;38;5;211m

    Automatically Save by Writing/Piping

    Because states are streamable, they can be fixed in your pipeline or written to like any other writeable stream. This is handy if you want to automatically capture codes that are on their way to a particular stream (ie. stdout).

    state.write('\033[32mHi there! This is some \033[31mred text')
    // current state becomes: \033[31m
     
    state.write('\033')
    state.write('[3')
    state.write('7m')
    // current state becomes: \033[37m
     
    state.write('\033[1mBolded \033[2mFaint \033[22mNormal Intensity')
    // current state becomes: \033[22;37m

    Or piping from and to other streams:

    some_stream.pipe(state).pipe(process.stdout);
    some_stream.write('\033[33mHi there!')
    // current state becomes: \033[33m

    Check State Attributes

    You can check certain style attributes at any time, easily:

    var state = new ANSIState('\033[32mHi there! \033[31mRed text, \033[1;48;5;21m')
    console.log(state.foreground) // red
    console.log(state.background, state.xterm_background) // xterm color definition, [5, 21]
    console.log(state.intensity) // bold
    console.log(state.blink) // null

    The Current ANSI State Code

    Your ANSIState instance holds an efficient ansi style escape code for the current ansi state, accessible by its code property:

    var state = new ANSIState('\033[32mHi there! \033[31mRed text, \033[1;48;5;21m')
    console.log(state.code + 'This is logged in the current ansi state.');
    console.log('The current ansi state is:', JSON.stringify(state.code)); // "\033[1;31;48;5;21m"

    Restore ANSI State

    Great, so you've been able to keep tabs on the current ansi state, now what if you want to restore that state some place? Well you can output the state's ansi code simply:

    process.stdout.write(state.code) // outputs current state code to stdout

    Or if you've set a writeable stream to pipe to, you can just call the restore method.

    state.pipe(process.stdout)
    state.restore() // will push state.code to wherever it is piped (ie. stdout).

    Reset ANSI State

    You can reset the state by simply calling the reset method on the state.

    state.reset() // sets code to '\033[0m'

    You may want to then write to the terminal with the reset code:

    process.stdout.write(state.reset().code)

    And of course, if you are piping to another stream:

    state.pipe(process.stdout)
    state.reset().restore()

    Create a New ANSI State from an Old One

    Finally, you can fork your state from an existing one really easily:

    var new_state = new ANSIState(state)
    // OR
    var new_state = new ANSIState(state.code)

    API

    new ANSIState(legacy) Constructor

    Creates a new instace of ANSIState. data can be any of type String, Array or another ANSIState instance.

    var state = new ANSIState('\033[1;32m');

    state.update(data)

    Updates the ansi style state contained in the ANSIState instance. data can be any of type String, Array or another ANSIState instance. The array can be of the form ['\033[32m', '\033[1;22;34m'] (usually what is returned from a regex match) or [32, 1, 22, 34].

    state.update('\033[32mHi there! \033[31mRed text')
    //current state becomes: \033[31m
     
    state.update('\033[1mBolding the text too')
    //current state becomes: \033[1;31m
     
    state.update('\033[34;38;5;211mxterm colors too!')
    //current state becomes: \033[1;38;5;211m

    state.write(data)

    The stream class write method on the ANSIState instance. data must be of type String.

    state.write('\033[32mHi there! This is some \033[31mred text')
    // current state becomes: \033[31m
     
    state.write('\033')
    state.write('[3')
    state.write('7m')
    // current state becomes: \033[37m

    state.pipe(stream)

    Pipe any data passed into the ANSIState to the supplied stream. stream can be any writeable stream.

    some_stream.pipe(state).pipe(process.stdout);

    state.reset()

    Resets the current ANSIState instance to the ansi reset code \033[0m.

    state.reset()

    state.restore()

    Pushes to any piped streams the ANSIState instance's code.

    state.pipe(process.stdout)
    state.restore() // will push state.code to wherever it is piped (ie. stdout).

    state.code

    Returns the current ansi code for the ANSIState instance.

    state.update('\033[32mHi there! \033[31mRed text')
    console.log(JSON.stringfy(state.code)) // "\u001b[31m"

    state[attribute_name]

    Returns the human readable value of the attribute_name for the ANSIState instance. You can use any of the following attributes:

    • intensity
    • italic
    • underline
    • blink
    • polarity
    • conceal
    • strikethrough
    • font
    • foreground
    • background
    • framed
    • overlined

    The value of each will be null if not set. If the foreground or background is set to xterm color definition you can obtain the corresponding definition code by using state.xterm_foreground or state.xterm_background respectively.

    state.update('\033[32mHi there! \033[31mRed text, \033[1;48;5;21m')
    console.log(state['foreground']) // red
    console.log(state.background) // xterm color definition
    console.log(state.xterm_background) // [5, 21]
    console.log(state.intensity) // bold

    state.attributes

    Returns the current attribute set for the ANSIState instance.

    state.update('\033[32mHi there! \033[31mRed text, \033[1;48;5;21m')
    console.log(state.attributes)
    // {
    //     intensity: '1',
    //     italic: null,
    //     underline: null,
    //     blink: null,
    //     polarity: null,
    //     conceal: null,
    //     strikethrough: null,
    //     font: null,
    //     foreground: '31',
    //     background: '48',
    //     framed: null,
    //     overlined: null
    // }

    License

    The MIT License (MIT) Copyright (c) 2014 Arjun Mehta

    Install

    npm i ansi-state

    DownloadsWeekly Downloads

    647

    Version

    1.0.5

    License

    MIT

    Last publish

    Collaborators

    • arjunmehta