command-line-draw

v1.2.3

Published

3 years ago

A library that allows you to draw and animate on the command line. I created it to make [this](https://www.npmjs.com/package/command-line-pong) version of pong for the command line.

Downloads

0High
0Medium
0Low

thelimabean

game command line terminal cli draw animation

CMD Draw

A library that allows you to draw and animate on the command line. I created it to make this version of pong for the command line.

Installation

$ npm i command-line-draw

Documentation

There are 4 classes exported by this module, and this section contains documentation for all 4.

A quick note: npm's styling makes this documentation somewhat difficult to read, it may be easier to read it on github.

Class: `Terminal`

Extends: <EventEmitter>

The terminal object represents the drawing space.

const { Terminal } = require('command-line-draw');

`new Terminal([config])`

Arguments

config <Object>
- in <tty.ReadStream> Where the Terminal reads user input from. Default: process.stdin.
- out <tty.WriteStream> Where the Terminal writes to. Default: process.stdout.
- width <number> The width of the Terminal. Default: terminal.out.columns - 2.
- height <number> The height of the Terminal. Default: terminal.out.rows - 2.
- border <string> The border style of the terminal. See here for a list of valid border styles. Default: 'light'.
- color <Object>
  - foreground <string> The foreground color of the Terminal. See here for a list of valid colors. Default: 'black'.
  - background <string> The background color of the Terminal. See here for a list of valid colors. Default: 'white'.
- dev <boolean> Determines behavior of terminal.log(). Default: false.

Creates a new Terminal object.

const { Terminal } = require('command-line-draw');

const terminal = new Terminal();

Static: `Terminal.BORDERS`

<Object>

An object containing several unicode box drawing characters, sorted into different border types

Static: `Terminal.BOTTOM`

<string>

A constant equal to the unicode character U+2584 (Lower half block).

Static: `Terminal.FULL`

<string>

A constant equal to the unicode character U+2588 (Full block).

Static: `Terminal.LEFT`

<string>

A constant equal to the unicode character U+258C (Left half block)

Static: `Terminal.RIGHT`

<string>

A constant equal to the unicode character U+2590 (Right half block)

Static: `Terminal.TOP`

<string>

A constant equal to the unicode character U+2580 (Upper half block).

Static: `Terminal.bitmapPresets`

<Object>

An object containing boolean[][]s that can be passed into terminal.bitmap() to print letters and punctuation.

const { Terminal } = require("command-line-draw");

const terminal = new Terminal();
terminal.bitmap(0, 0, ...Terminal.bitmapPresets.letters.A);

Static: `Terminal.bitmapPresets.letters`

<Object>

An object containing letters that can be passed into terminal.bitmap(). They are indexed "A"-"Z".

const { Terminal } = require("command-line-draw");

const terminal = new Terminal();
terminal.bitmap(0, 0, ...Terminal.bitmapPresets.letters.A); // Prints a large letter "A" to the terminal

Static: `Terminal.bitmapPresets.punctuation`

<Object>

An object containing punctuation that can be passed into terminal.bitmap(). Included punctuation is ".", "?", and "!".

const { Terminal } = require("command-line-draw");

const terminal = new Terminal();
terminal.bitmap(0, 0, ...Terminal.bitmapPresets.punctuation["!"]); // Prints a large exclamation point to the terminal

Static: `Terminal.sevenSegmentPresets`

<Object>

An object containing boolean[]s that, using the spread operator, can be passed into terminal.sevenSegment() or terminal.sevenSegmentToBitmap().

const { Terminal } = require("command-line-draw");

const terminal = new Terminal();
terminal.sevenSegment(0, 0, ...Terminal.sevenSegmentPresets.numbers[0]); // Prints a large number 0 to the terminal

Static: `Terminal.sevenSegmentPresets.numbers`

<Object>

An object containing boolean[]s that, using the spread operator, can be passed into terminal.sevenSegment() or terminal.sevenSegmentToBitmap(). They are indexed "0"-"9".

const { Terminal } = require("command-line-draw");

const terminal = new Terminal();
terminal.sevenSegment(0, 0, ...Terminal.sevenSegmentPresets.numbers[0]);

Event: `'<keyName>'`

On all key presses, with the exception of ctrl+c, an event is emitted. The implementation is as follows:

terminal.in.on("keypress", (chunk, key) => {
  if (key.ctrl && !key.meta && !key.shift && key.name === "c") process.exit();
  else if (!this.tooBig) {
    let eventName = "";
    if (key.ctrl) eventName += "ctrl+";
    if (key.meta) eventName += "alt+";
    if (key.shift) eventName += "shift+";
    eventName += key.name;
    this.emit(eventName, key);
  }
});

For example, if the user were to press the up arrow, the event 'up' would be emitted. If they held shift while pressing up, the event 'shift+up' would be emitted.

Event: `'resize'`

The 'resize' event is emitted whenever terminal.out is resized.

`terminal.addSprite(sprite)`

sprite <Sprite> Sprite to be added.

The Sprite cannot be used until it is added to a terminal. When the terminal is resized, sprites that were showing will automatically be redrawn. Has no affect if sprite is already on the terminal,

const { Terminal, Sprite } = require('command-line-draw');

const terminal = new Terminal();
const mySprite = new Sprite((x, y) => { // See the Sprite class for instructions on how to use this constructor
  terminal.drawBox(x, y, 10, 10);
});

terminal.addSprite(mySprite);
mySprite.draw(0, 0);

`terminal.bitmap(x, y[, color], ...matrixes)`

x <number> The x coordinate at which to print the bitmap.
y <number> The y coordinate at which to print the bitmap.
color <string> The color of the bitmap Default: terminal.color.foreground.
matrixes <boolean[][]> Matrix(es) that represent the bitmap you want to print

Prints a series of bitmaps at a particular position. The bitmaps are a matrix of booleans. true prints ██ in the foreground color, false prints two spaces in the background color.

const { Terminal } = require('command-line-draw');

const terminal = new Terminal();

terminal.bitmap(0, 0, [
  [true, true, true],
  [true, false, true],
  [true, false, true],
  [true, false, true],
  [true, true, true]
]); // Prints a large '0' in the command line

`terminal.borderChars`

<Object>

The characters the border is made up of. Equal to Terminal.BORDERS[terminal.borderStyle]

`terminal.borderStyle`

<string>

A string representing the type of border the terminal has. See here for a list of valid border styles.

`terminal.clear()`

Clears the entire terminal (including logged messages). The border remains visible. Any moving sprites also stop and are cleared.

`terminal.drawBox(x, y, width, height[, color])`

x <number> The x coordinate of the top-left corner of the box.
y <number> The y coordinate of the top-left corner of the box.
width <number> The width of the box.
height <number> The height of the box.
color <string> The color of the box Default: terminal.color.foreground.

Draws a box on the terminal.

`terminal.color`

<Color>

A Color object containing information about the terminal's color

`terminal.dev`

<boolean>

When false, terminal.log() has no affect.

`terminal.drawLine(x1, y1, x2, y2[, color][, thickness][, dashed][, dashThickness][, spaceColor])`

x1 <number> The x coordinate of the starting point on the line.
y1 <number> The y coordinate of the starting point on the line.
x2 <number> The x coordinate of the ending point on the line.
y2 <number> The y coordinate of the ending point on the line.
color <string> The color of the line. Default: terminal.color.foreground.
thickness <number> The thickness of the line. Default: 1.
dashed <boolean> When true, the line will be dashed (alternating between the foreground and background color). Default: false.
dashThickness <number> How thick the dash will be. (e.g, if this is 1, the dash will look like this: █ █ █ █.) Default: 0.5.
spaceColor <string> The color of the spaces between the dashes in a dashed line. Default: terminal.color.background.

Draws a line from point (x1, y1) to point (x2, y2). Currently, only vertical and horizontal lines are supported, but not diagonals. The coordinates can be decimals, they will be rounded to the nearest 0.5. Unfortunately, you can only have decimal coordinates on one axis.

const { Terminal } = require('command-line-draw');

const terminal = new Terminal();
terminal.drawLine(0, 1.5, 10, 1.5); // Draws a line from (0, 1.5) to (10, 1.5)

`terminal.hasBorder`

<boolean>

true if terminal.borderStyle === 'none'. Otherwise it is false.

`terminal.height`

<number>

The height of the terminal.

`terminal.in`

<tty.ReadStream>

The input for the terminal.

`terminal.largestBorder`

<number>

The widest of terminal.borderChars.vertical, terminal.borderChars.topLeft, terminal.borderChars.bottomLeft. If terminal.borderStyle === 'solid', it returns 2, if terminal.borderStyle === 'none', it returns 0, otherwise it returns 1.

`terminal.log([data][, ...args])`

data <any> The data to be printed
...args <any> Values to be added to the data

If terminal.dev === true, this method prints to terminal.out with a new line. If it is false, nothing is printed. Logged messages are not reprinted when the terminal is cleared. See console.log() for more details.

`terminal.margin`

<Margin>

A Margin object containing information about the terminal's margin

`terminal.out`.

<tty.WriteStream>

The output for the terminal

`terminal.sevenSegment(x, y, a, b, c, d, e, f, g[, color])`

x <number> The x coordinate at at which to write the seven segment display
y <number> The y coordinate at at which to write the seven segment display
a-g <boolean> Boolean values representing each segment of the a seven segment display.

Prints a a seven segment display to the terminal. It is 5 characters tall and 6 wide (each segment is 2 characters wide).

const { Terminal } = require('command-line-draw');

const terminal = new Terminal();
terminal.sevenSegment(0, 0, true, true, true, true, true, true, false); // Prints '0', although there multiple easier ways to do this

`terminal.sevenSegmentToBitmap(a, b, c, d, e, f, g)`

a-g <boolean> Boolean values representing each segment of the a seven segment display.
Returns: <boolean[][]>

Turns seven boolean values (representing the seven segments of a seven segment display) and returns a boolean matrix (2D <Array>) representing each pixel on a 5x3 grid to display the given values.

const { Terminal } = require('command-line-draw');

const terminal = new Terminal();

const myBooleanMatrix = terminal.sevenSegmentDisplay(true, true, true, true, true, true, false);
terminal.bitmap(0, 0, myBooleanMatrix); // Prints '0', although there multiple easier ways to do this

`terminal.time`

<number>

Returns a time (high resolution time in milliseconds, same as performance.now()). The time does not increase when terminal.tooBig === true. It is recommended that you use this to time any animations on the terminal.

`terminal.tooBig`

<boolean>

Returns true when the terminal's width and height exceed the actual size of the user's command line. Nothing will be drawn until the user's command line becomes larger.

`terminal.width`

<number>

The width of the terminal.

`terminal.write(text, x, y[, color][, backgroundColor])`

text <string> The text to be written to the terminal.
x <number> The x coordinate at which to print the text.
y <number> The y coordinate at which to print the text.
color <string> The color of the text Default: terminal.color.foreground.
backgroundColor <string> The background color of the text Default: terminal.color.background.

Writes text to the terminal at a particular position. If the text is too long and goes outside the terminal, it will not wrap, it will instead throw an error.

`terminal.writeLarge(text, x, y[, color])`

text <string> The text to be written to the terminal.
x <number> The x coordinate at which to print the text.
y <number> The y coordinate at which to print the text.
color <string> The color of the text Default: terminal.color.foreground.

Prints large text to the terminal at a particular position. Each character is a seven segment display with a 2 character space between characters and 6 character space between words. Allowed characters are letters, numbers, and basic punctuation (.!?).

const { Terminal } = require('command-line-draw');

const terminal = new Terminal({
  dev: true // Do not use this in production, as logging is a simple debugging tool and may not produce desireable results
});

terminal.log('Hello World');

Class: `Sprite`

Extends: <EventEmitter>

`new Sprite(callback[, config])`

callback <Function> This callback is called to draw the shape
- x <number> The x coordinate that the sprite should be drawn at.
- y <number> The y coordinate that the sprite should be drawn at.
- ...args <any> Any other arguments passed into the callback.
config <Object>
- preciseAxis <string> 'x', 'y', or 'neither'. The axis to use decimal coordinates on. Default: 'neither'.
- speed <number> | <undefined> The speed the sprite should move if a time is not provided in sprite.move().

`sprite.callback`

<Function>

The callback that was passed into the constructor

Creates a new sprite object.

const { Terminal, Sprite } = require("command-line-draw");

const terminal = new Terminal();
const mySprite = new Sprite((x, y) => {
  terminal.drawBox(x, y, 10, 10);
});

terminal.addSprite(mySprite);
sprite.draw(0, 0); // Draws a 10x10 box at (0, 0)

`sprite.clear()`

Clears the sprite from the terminal.

`sprite.draw(x, y[, ...args])`

x <number> The x coordinate to draw the sprite at. This is passed into sprite.callback.
y <number> The y coordinate to draw the sprite at. This is passed into sprite.callback.
...args <any> Other arguments to pass into sprite.callback.

Calls sprite.callback in order to draw the sprite.

`sprite.move(x1, y1, x2, y2[, t])`

x1 <number> The x position for the box to start at.
y1 <number> The y position for the box to start at.
x2 <number> The x position for the box to end at.
y2 <number> The y position for the box to end at.
t <number> The time (in seconds) that the movement should take. Default: distance / terminal.speed * 1000. Required if this.speed === undefined.

Moves the sprite from (x1, y1) to (x2, y2).

const { Terminal, Sprite } = require("command-line-draw");

const terminal = new Terminal();
const mySprite = new Sprite((x, y) => {
  terminal.drawBox(x, y, 10, 10);
});

terminal.addSprite(mySprite);
sprite.move(0, 0, 10, 10, 2); // Moves the sprite from (0, 0) to (10, 10) in 2 seconds

`sprite.moveRelative(dx, dy[, t])`

dx <number> The distance to move on the x axis (can be negative).
dy <number> The distance to move on the y axis (can be negative).
t <number> The time (in seconds) that the movement should take. Default: distance / terminal.speed * 1000. Required if this.speed === undefined.

Move the sprite to a new position relative to it's current position. Or, in simple english, moves it a certain distance from its current position.

`sprite.moveTo(x, y[, t])`

x <number> The x position to move to.
y <number> The y position to move to.
t <number> The time (in seconds) that the movement should take. Default: distance / terminal.speed * 1000. Required if this.speed === undefined.

Moves the sprite from its current position to the new (x, y) position.

`sprite.preciseAxis`

<string>

The precise axis passed into the config in the constructor.

`sprite.showing`

<boolean>

A boolean indicating if the sprite is currently viable.

`sprite.speed`

<number>

The current speed of the sprite. Is only used by sprite.move() if time is not provided.

`sprite.stop()`

Stops the sprite if it is moving. No effect if the sprite isn't currently moving.

`sprite.x`

<number>

The current x position of the sprite

`sprite.xRounder`

<Function>

The function that rounds the x position. If sprite.preciseAxis === 'x', this is a function that rounds to the nearest 0.5, otherwise it is equal to Math.round()

`sprite.y`

<number>

The current y position of the sprite

`sprite.yRounder`

<Function>

The function that rounds the y position. If sprite.preciseAxis === 'y', this is a function that rounds to the nearest 0.5, otherwise it is equal to Math.round()

Class: `Box`

Extends: <Sprite>

`new Box(width, height, config)`

width <number> The width of the box.
height <number> The height of the box.
config <Object>
- preciseAxis <string> 'x', 'y', or 'neither'. The axis to use decimal coordinates on. Default: 'y'.
- speed <number> | <undefined> The speed the sprite should move if a time is not provided in sprite.move().

Creates a new box object. A box is a sprite where the callback draws a box of a particular width and height on the canvas.

const { Terminal, Box } = require("command-line-draw");

const terminal = new Terminal();
const myBox = new Box(10, 10);

terminal.addSprite(myBox);
myBox.draw(0, 0); // Draws a 10x10 box at (0, 0)

`box.height`

<number>

The height passed into the constructor. It is readonly, meaning it cannot be set.

`box.touching(box)`

box <Box> The box to check the position against.

Checks if two boxes are touching.

const { Terminal, Box } = require("command-line-draw");

const terminal = new Terminal();
const box1 = new Box(5, 5);
const box2 = new Box(5, 5);

terminal.addSprite(box1);
terminal.addSprite(box2);

box1.draw(0, 0);
box2.draw(5, 0);

box1.touching(box2); // true, the boxes are touching

`box.width`

<number>

The width passed into the constructor. It is readonly, meaning it cannot be set.

Class: `Menu`

Extends: <Sprite>

`new Menu(callback, options[, style])`

callback <Function> The function called when a menu option is selected
- i <number> The index of the menu option selected
options <string[]> A list of menu options
style <string> The style of the border. It can be any style on this list except for 'none' or 'solid'. Default: terminal.borderStyle, or 'light' if that is invalid.

Creates a new menu object. A menu can be drawn and allows the user to select an option from your list of options. When the user selects an option, the menu is cleared and the callback is run with the argument i being the index of the selected option.

const { Terminal, Menu } = require("command-line-draw");

const terminal = new Terminal();
const myMenu = new Menu(i => {
  // Do something here
}, [
  "First option",
  "Option 2",
  "The 3rd option",
  "Option D"
]);

terminal.addSprite(myMenu);
myMenu.draw(0, 0);

/**
 * Prints:
 * ┌────────────────┬────────────┬──────────────────┬────────────┐
 * │ 1:First option │ 2:Option 2 │ 3:The 3rd option │ 4:Option D │
 * └────────────────┴────────────┴──────────────────┴────────────┘
 * 
 * When an option is selected, this is removed and callback is called.
 * For example, if the user presses 1, the first option, at index 0, was selected.
 * This means that callback(0) is called.
 */

`menu.borderChars`

<Object>

The characters the border is made up of. Equal to Terminal.BORDERS[menu.style]. If accessed before this is added to a terminal, it will throw and error if a style was not passed into the constructor.

`menu.height`

<number>

The height of the menu. Always set to 3.

`menu.options`

<string[]>

The list of options passed into the constructor.

`menu.style`

<string>

The style passed into the constructor. If no style was passed into the constructor, it will throw an error before it has been added to a terminal. After it has been added, it will default to terminal.borderStyle, and, if that is invalid, will default to 'light'.

`menu.width`

<number>

The width of the menu.

Class: `Color` Not Exported

Extends: <EventEmitter>

The class Color is not exported, however, terminal.color is an instance of it, so its properties and methods are still available to you.

`new Color(out)`

out <tty.WriteStream> The write stream to add colors to.

Creates a new Color object.

const { Terminal } = require('command-line-draw');

const terminal = new Terminal();

const Color = terminal.color.constructor
const color = new Color(process.stdout); // There is literally no reason ever to do this

Static: `Color.getBackgroundColor(color)`

color <string> The name of a color. See here for a list of valid colors.
Returns: <string> A node.js color escape code. You can find a list of those here.

Returns the color code associated width the color you enter.

const { Terminal } = require('command-line-draw');

const terminal = new Terminal();
terminal.color.constructor.getBackgroundColor('black'); // => '\x1b40m'

Static: `Color.getForegroundColor(color)`

color <string> The name of a color. See here for a list of valid colors.
Returns: <string> A node.js color escape code. You can find a list of those here.

Returns the color code associated width the color you enter.

const { Terminal } = require('command-line-draw');

const terminal = new Terminal();
terminal.color.constructor.getForegroundColor('black'); // => '\x1b30m'

Static: `Color.RESET`

<string>

The node.js escape code that clears all formatting from the console ('\x1b[0m').

Event: `'change'`

The 'change' event is emitted whenever color.reset() is run or color.foreground or color.background are set

`color.background`

<string> | <undefined>

The name of the current background color of the terminal. Is settable. See a list of valid color names here.

`color.foreground`

<string> | <undefined>

The name of the current foreground color of the terminal. Is settable. See a list of valid color names here.

`color.refresh()`

Clears formatting, then reapplies this.foreground and this.background colors.

`color.reset()`

Resets this.foreground and this.background to undefined

Class: `Margin` Not Exported

The class Color is not exported, however, terminal.margin is an instance of it, so its properties and methods are still available to you.

`new Margin(out, width, height)`

out <tty.WriteStream> The write stream that the terminal is on.
width <number> The width of the terminal.
height <number> The height of the terminal.

Creates a new Margin object. There is no reason for you to ever use this, I just included it for completion

const { Terminal } = require("command-line-draw");

const terminal = new Terminal();

const Margin = terminal.margin.constructor;
const myMargin = new Margin(process.stdout, terminal.width, terminal.height); // There is no reason for you to ever do this.

`margin.lr`

<number>

The left-right margin of the terminal. If this is less than terminal.largestBorder, then the terminal will disappear and terminal.tooBig will be set to true

`margin.tb`

<number>

The top-bottom margin of the terminal. If this is less than 1, then the terminal will disappear and terminal.tooBig will be set to true

Types

A type deceleration file has been included at ./lib/cmdDraw.d.ts. I tried, but I don't know typescript, so it likely has mistakes. If you find them, please report them to the github issues page.

More Info

Borders

'light' (Default)
'heavy'
'double'
'round'
'solid'
'none'

Colors

black
red
green
yellow
blue
magenta
cyan
white

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

CMD Draw

Installation

Documentation

Table of contents

Class: Terminal

new Terminal([config])

Arguments

Static: Terminal.BORDERS

Static: Terminal.BOTTOM

Static: Terminal.FULL

Static: Terminal.LEFT

Static: Terminal.RIGHT

Static: Terminal.TOP

Static: Terminal.bitmapPresets

Static: Terminal.bitmapPresets.letters

Static: Terminal.bitmapPresets.punctuation

Static: Terminal.sevenSegmentPresets

Static: Terminal.sevenSegmentPresets.numbers

Event: '<keyName>'

Event: 'resize'

terminal.addSprite(sprite)

terminal.bitmap(x, y[, color], ...matrixes)

terminal.borderChars

terminal.borderStyle

terminal.clear()

terminal.drawBox(x, y, width, height[, color])

terminal.color

terminal.dev

terminal.drawLine(x1, y1, x2, y2[, color][, thickness][, dashed][, dashThickness][, spaceColor])

terminal.hasBorder

terminal.height

terminal.in

terminal.largestBorder

terminal.log([data][, ...args])

terminal.margin

terminal.out.

terminal.sevenSegment(x, y, a, b, c, d, e, f, g[, color])

terminal.sevenSegmentToBitmap(a, b, c, d, e, f, g)

terminal.time

terminal.tooBig

terminal.width

terminal.write(text, x, y[, color][, backgroundColor])

terminal.writeLarge(text, x, y[, color])

Class: Sprite

new Sprite(callback[, config])

sprite.callback

sprite.clear()

sprite.draw(x, y[, ...args])

sprite.move(x1, y1, x2, y2[, t])

sprite.moveRelative(dx, dy[, t])

sprite.moveTo(x, y[, t])

sprite.preciseAxis

sprite.showing

sprite.speed

sprite.stop()

sprite.x

sprite.xRounder

sprite.y

sprite.yRounder

Class: Box

new Box(width, height, config)

box.height

box.touching(box)

box.width

Class: Menu

new Menu(callback, options[, style])

menu.borderChars

menu.height

menu.options

menu.style

menu.width

Class: Color Not Exported

new Color(out)

Static: Color.getBackgroundColor(color)