terminal-printer

This module allows you to turn your terminal screen info a canvas where you can simply print text in all imaginable colors. You can also do pixel-art and finally create those fancy stuff you always imagined!

Installation

Just install the package as dependency with npm or yarn:

npm install --save terminal-printer

# or

yarn add terminal-printer

Getting started

The module exports one class called Printer which you can use to create awesomeness.

import { Printer } from "terminal-printer";

const printer = new Printer();

Usually you want to get the cursor out of the way while printing. Nothing more easy that that!

printer.hideCursor();

First, let's print a blank canvas:

printer.print();

Per default the canvas spans accross the full width of your termial.

Now let's write some text:

printer.writeCenteredText("Hello world!");

Well, you might be sad until now, because there is nothing visible on the screen. Thats because the printer does not automatically update, you have to explicitly tell it to do so. (The reason for this simply is performance. You often want to write multiple things. The printer collects all updates and prints them in one go.)

So let's update the printer to see the result:

printer.update();

Horray! You should now see the following:

In the end, don't forget to get your cursor back!

printer.showCursor();

Documentation

Constructor

The constructor accepts one optional argument config, which is an object that can be used to configure the printer:

const printer = new Printer(config);

typeof config = {
  /*
   * `height` and `width` can be used to controll the rows and columns
   * of the canvas where the printer should work on. Per default the
   * value from the node process stdout (`process.stdout.rows` and
   * `process.stdout.columns`) are used.
   */
  height?: number;
  width?: number;
  /*
   * You can optionally specify colors for background and foreground.
   * The type `Color` represents valid CSS color names as strings
   * (see https://www.w3schools.com/cssref/css_colors.asp for a list).
   */
  backgroundColor?: RgbColor | Color;
  foregroundColor?: RgbColor | Color;
};

/* This object type represents a color by its RGB values. */
type RgbColor = { r: number; g: number; b: number; };

Properties

Here are the available properties of a Printer object.

height

printer.height; // returns the height of the canvas, i.e. the number of rows

width

printer.width; // returns the width of the canvas, i.e. the number of columns

Methods

Here are the available methods of a Printer object.

clear

This method clears all content from the canvas. You can optionally specify the back- and foreground color after the reset. The method does not return anything.

printer.clear(colors);

typeof colors = {
  backgroundColor?: RgbColor | Color;
  foregroundColor?: RgbColor | Color;
}

getPixel

This method returns the data for a specific pixel in your canvas. You have to specify the row and the column for the pixel you want to get.

The response will be an object containing backgroundColor, foregroundColor and value for the pixel.

printer.getPixel(17, 42);
/*
 * returns for example
 * {
 *   backgroundColor: "Black",
 *   foregroundColor: { r: 235, g: 255, b: 195 },
 *   value: "*"
 * }
 */

hideCursor

This method hides the cursor in the terimal. It does not return anything:

printer.hideCursor();

print

This method prints the complete canvas. This means that also those pixels will be re-printed where the values have actually not changed. The method does not return anything.

printer.print();

setPixel

This method allows you to set the value and the colors for a single pixel. With the first two arguments you have to specify the row and column of the pixel. The third parameter and its properties are all optional, so you could e.g. only set the value and leave the colors unchanged. The value (if specified) has to be a string of length one. The method does not return anything.

printer.setPixel(1, 2, {
  backgroundColor: "Black",
  foregroundColor: { r: 235, g: 255, b: 195 },
  value: "*",
});
printer.setPixel(17, 42, {
  value: "X",
});

showCursor

This method shows the cursor in the terimal. It does not return anything:

printer.showCursor();

update

This method prints all pixels of the canvas that have changes since the last print or update. This means that only those pixels will be re-printed where the values have actually changed. It is therefore much more efficient to use update in comparison to print. The method does not return anything.

printer.update();

writeCenteredRow

This method writes some text into a specific row of the canvas and automatically centeres the text. The first argument is the number of the row, the second is the text. In an optional third argument you can specify back- and foreground colors. It does not return anyting:

printer.writeCenteredRow(1, "Hello world!", {
  backgroundColor: "Black",
  foregroundColor: { r: 235, g: 255, b: 195 },
});
printer.writeCenteredRow(2, "Here is some random text.");

writeCenteredText

This method writes some text on the canvas and automatically centeres the text vertically and horizontally. The first argument is the text. It will be automatically splitted by newline-characters. In an optional second argument you can specify back- and foreground colors. It does not return anyting:

printer.writeCenteredText("Hello world!\nThis is the next row...", {
  backgroundColor: "Black",
  foregroundColor: { r: 235, g: 255, b: 195 },
});
printer.writeCenteredText("Only one row in the end...works just as well!");

writeRow

This method writes some text into a specific row of the canvas. You can also choose in which column to start writing. The first argument is the number of the row, the second the column number and the third is the text. In an optional fourth argument you can specify back- and foreground colors. It does not return anyting:

printer.writeRow(7, 9, "Hello world!", {
  backgroundColor: "Black",
  foregroundColor: { r: 235, g: 255, b: 195 },
});
printer.writedRow(9, 0, "This text starts right in the first column.");