charm

What is charm?

The 'charm' npm package is a library for manipulating terminal output, allowing you to create dynamic and interactive text-based user interfaces. It provides functionalities for cursor movement, text styling, and screen manipulation.

What are charm's main functionalities?

Cursor Movement

This feature allows you to move the cursor to specific positions on the terminal screen. The code sample demonstrates how to position the cursor at (0, 0) and (10, 10) and write text at those positions.

const charm = require('charm')();
charm.pipe(process.stdout);
charm.position(0, 0);
charm.write('Hello, World!');
charm.position(10, 10);
charm.write('Moved to (10, 10)');

Text Styling

This feature allows you to style text with different colors and attributes. The code sample shows how to change the text color to red and the background color to blue.

const charm = require('charm')();
charm.pipe(process.stdout);
charm.foreground('red');
charm.write('This is red text');
charm.display('reset');
charm.background('blue');
charm.write('This is text with a blue background');
charm.display('reset');

Screen Manipulation

This feature allows you to manipulate the terminal screen, such as clearing it. The code sample demonstrates how to clear the screen and reset the cursor position.

const charm = require('charm')();
charm.pipe(process.stdout);
charm.erase('screen');
charm.position(0, 0);
charm.write('Screen cleared and cursor reset');

Other packages similar to charm

blessed

Blessed is a comprehensive library for creating interactive command-line interfaces. It offers more advanced features compared to charm, such as support for widgets, forms, and event handling. It is suitable for building complex terminal applications.

ink

Ink is a React-like library for building command-line interfaces. It allows you to use React components to create interactive terminal applications. Ink provides a higher-level abstraction compared to charm, making it easier to build complex UIs.

ansi-escapes

Ansi-escapes is a library for generating ANSI escape codes for manipulating terminal output. It provides a lower-level API compared to charm, focusing on generating escape codes for cursor movement, text styling, and screen manipulation.

README

charm

Use ansi terminal characters to write colors and cursor positions.

example

lucky

var charm = require('charm')();
charm.pipe(process.stdout);
charm.reset();

var colors = [ 'red', 'cyan', 'yellow', 'green', 'blue' ];
var text = 'Always after me lucky charms.';

var offset = 0;
var iv = setInterval(function () {
    var y = 0, dy = 1;
    for (var i = 0; i < 40; i++) {
        var color = colors[(i + offset) % colors.length];
        var c = text[(i + offset) % text.length];
        charm
            .move(1, dy)
            .foreground(color)
            .write(c)
        ;
        y += dy;
        if (y <= 0 || y >= 5) dy *= -1;
    }
    charm.position(0, 1);
    offset ++;
}, 150);

events

Charm objects pass along the data events from their input stream except for events generated from querying the terminal device.

Because charm puts stdin into raw mode, charm emits two special events: "^C" and "^D" when the user types those combos. It's super convenient with these events to do:

charm.on('^C', process.exit)

The above is set on all charm streams. If you want to add your own handling for these special events simply:

charm.removeAllListeners('^C')
charm.on('^C', function () {
  // Don't exit. Do some mad science instead.
})

methods

var charm = require('charm')(param or stream, ...)

Create a new readable/writable charm stream.

You can pass in readable or writable streams as parameters and they will be piped to or from accordingly. You can also pass process in which case process.stdin and process.stdout will be used.

You can pipe() to and from the charm object you get back.

charm.reset()

Reset the entire screen, like the /usr/bin/reset command.

charm.destroy(), charm.end()

Emit an "end" event downstream.

charm.write(msg)

Pass along msg to the output stream.

charm.position(x, y)

Set the cursor position to the absolute coordinates x, y.

charm.position(cb)

Query the absolute cursor position from the input stream through the output stream (the shell does this automatically) and get the response back as cb(x, y).

charm.move(x, y)

Move the cursor position by the relative coordinates x, y.

charm.up(y)

Move the cursor up by y rows.

charm.down(y)

Move the cursor down by y rows.

charm.left(x)

Move the cursor left by x columns.

charm.right(x)

Move the cursor right by x columns.

charm.push(withAttributes=false)

Push the cursor state and optionally the attribute state.

charm.pop(withAttributes=false)

Pop the cursor state and optionally the attribute state.

charm.erase(s)

Erase a region defined by the string s.

s can be:

• end - erase from the cursor to the end of the line
• start - erase from the cursor to the start of the line
• line - erase the current line
• down - erase everything below the current line
• up - erase everything above the current line
• screen - erase the entire screen

charm.delete(mode, n)

Delete 'line' or 'char's. delete differs from erase because it does not write over the deleted characters with whitesapce, but instead removes the deleted space.

mode can be 'line' or 'char'. n is the number of items to be deleted. n must be a positive integer.

The cursor position is not updated.

charm.insert(mode, n)

Insert space into the terminal. insert is the opposite of delete, and the arguments are the same.

charm.display(attr)

Set the display mode with the string attr.

attr can be:

• reset
• bright
• dim
• underscore
• blink
• reverse
• hidden

charm.foreground(color)

Set the foreground color with the string color, which can be:

• red
• yellow
• green
• blue
• cyan
• magenta
• black
• white

or color can be an integer from 0 to 255, inclusive.

charm.background(color)

Set the background color with the string color, which can be:

• red
• yellow
• green
• blue
• cyan
• magenta
• black
• white

or color can be an integer from 0 to 255, inclusive.

charm.cursor(visible)

Set the cursor visibility with a boolean visible.

install

With npm do:

npm install charm