command-line-draw
Advanced tools
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.
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.
$ npm i command-line-draw
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.
Terminal
new Terminal([config])Terminal.BORDERSTerminal.BOTTOMTerminal.FULLTerminal.LEFTTerminal.RIGHTTerminal.TOPTerminal.bitmapPresets
Terminal.sevenSegmentPresets
'<keyName>''resize'terminal.addSprite(sprite)terminal.bitmap(x, y[, color], ...matrixes)terminal.borderCharsterminal.borderStyleterminal.clear()terminal.colorterminal.devterminal.drawBox(x, y, width, height[, color])terminal.drawLine(x1, y1, x2, y2[, color][, thickness][, dashed][, dashThickness][, spaceColor])terminal.hasBorderterminal.heightterminal.interminal.largestBorderterminal.log([data][, ...args])terminal.marginterminal.outterminal.sevenSegment(x, y, a, b, c, d, e, f, g[, color])terminal.sevenSegmentToBitmap(a, b, c, d, e, f, g)terminal.timeterminal.tooBigterminal.widthterminal.write(text, x, y[, color])terminal.writeLarge(text, x, y[, color])Sprite
Box
Menu
Color Not Exported
Margin Not Exported
Terminal<EventEmitter>The terminal object represents the drawing space.
const { Terminal } = require('command-line-draw');
new Terminal([config])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>
dev <boolean> Determines behavior of terminal.log(). Default: false.Creates a new Terminal object.
const { Terminal } = require('command-line-draw');
const terminal = new Terminal();
Terminal.BORDERSAn object containing several unicode box drawing characters, sorted into different border types
Terminal.BOTTOMA constant equal to the unicode character U+2584 (Lower half block).
Terminal.FULLA constant equal to the unicode character U+2588 (Full block).
Terminal.LEFTA constant equal to the unicode character U+258C (Left half block)
Terminal.RIGHTA constant equal to the unicode character U+2590 (Right half block)
Terminal.TOPA constant equal to the unicode character U+2580 (Upper half block).
Terminal.bitmapPresetsAn 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);
Terminal.bitmapPresets.lettersAn 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
Terminal.bitmapPresets.punctuationAn 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
Terminal.sevenSegmentPresetsAn 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
Terminal.sevenSegmentPresets.numbersAn 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]);
'<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.
'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 printPrints 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.borderCharsThe characters the border is made up of. Equal to Terminal.BORDERS[terminal.borderStyle]
terminal.borderStyleA 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.colorA Color object containing information about the terminal's color
terminal.devWhen 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.hasBordertrue if terminal.borderStyle === 'none'. Otherwise it is false.
terminal.heightThe height of the terminal.
terminal.inThe input for the terminal.
terminal.largestBorderThe 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])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.marginA Margin object containing information about the terminal's margin
terminal.out.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 displayy <number> The y coordinate at at which to write the seven segment displaya-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.<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.timeReturns 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.tooBigReturns 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.widthThe 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');
Sprite<EventEmitter>new Sprite(callback[, config])callback <Function> This callback is called to draw the shape
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.callbackThe 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.preciseAxisThe precise axis passed into the config in the constructor.
sprite.showingA boolean indicating if the sprite is currently viable.
sprite.speedThe 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.xThe current x position of the sprite
sprite.xRounderThe 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.yThe current y position of the sprite
sprite.yRounderThe 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()
Box<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.heightThe 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.widthThe width passed into the constructor. It is readonly, meaning it cannot be set.
Menu<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 selectedoptions <string[]> A list of menu optionsstyle <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.borderCharsThe 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.heightThe height of the menu. Always set to 3.
menu.optionsThe list of options passed into the constructor.
menu.styleThe 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.widthThe width of the menu.
Color Not Exported<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
Color.getBackgroundColor(color)color <string> The name of a color. See here for a list of valid colors.<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'
Color.getForegroundColor(color)color <string> The name of a color. See here for a list of valid colors.<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'
Color.RESETThe node.js escape code that clears all formatting from the console ('\x1b[0m').
'change'The 'change' event is emitted whenever color.reset() is run or color.foreground or color.background are set
color.backgroundThe name of the current background color of the terminal. Is settable. See a list of valid color names here.
color.foregroundThe 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
Margin Not ExportedThe 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.lrThe 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.tbThe 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
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.
'light' (Default)'heavy''double''round''solid''none'blackredgreenyellowbluemagentacyanwhiteFAQs
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.
The npm package command-line-draw receives a total of 15 weekly downloads. As such, command-line-draw popularity was classified as not popular.
We found that command-line-draw demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
OpenAI rotated macOS signing certificates after a malicious Axios package reached its CI pipeline in a broader software supply chain attack.
Security News
Open source is under attack because of how much value it creates. It has been the foundation of every major software innovation for the last three decades. This is not the time to walk away from it.
Security News
Socket CEO Feross Aboukhadijeh breaks down how North Korea hijacked Axios and what it means for the future of software supply chain security.