ansi-state
Version:
Save and restore your ANSI states.
248 lines (191 loc) • 7.72 kB
Markdown
# node-ansi-state
[](https://travis-ci.org/arjunmehta/node-ansi-state)
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
```bash
npm install --save ansi-state
```
## Basic Usage
### Include
```javascript
var ANSIState = require('ansi-state')
```
### Create a New State
Instantiate a new state with the constructor:
```javascript
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!
```javascript
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).
```javascript
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:
```javascript
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:
```javascript
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:
```javascript
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:
```javascript
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.
```javascript
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.
```javascript
state.reset() // sets code to '\033[0m'
```
You may want to then write to the terminal with the reset code:
```javascript
process.stdout.write(state.reset().code)
```
And of course, if you are piping to another stream:
```javascript
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:
```javascript
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.
```javascript
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]`.
```javascript
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`.
```javascript
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.
```javascript
some_stream.pipe(state).pipe(process.stdout);
```
### state.reset()
Resets the current `ANSIState` instance to the ansi reset code `\033[0m`.
```javascript
state.reset()
```
### state.restore()
Pushes to any piped streams the `ANSIState` instance's code.
```javascript
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.
```javascript
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.
```javascript
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.
```javascript
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`