tty-table

What is tty-table?

The tty-table npm package is used to create and display tables in the terminal. It provides a simple and flexible way to format and present tabular data in a visually appealing manner.

What are tty-table's main functionalities?

Basic Table Creation

This feature allows you to create a basic table with specified headers and rows. The table is then rendered and displayed in the terminal.

const ttyTable = require('tty-table');
const header = [
  { value: 'Name', width: 30, headerColor: 'cyan' },
  { value: 'Age', width: 10, headerColor: 'cyan' }
];
const rows = [
  ['Alice', 30],
  ['Bob', 25]
];
const table = ttyTable(header, rows);
console.log(table.render());

Customizing Table Appearance

This feature allows you to customize the appearance of the table, including border style, border color, padding, alignment, and text color.

const ttyTable = require('tty-table');
const header = [
  { value: 'Name', width: 30, headerColor: 'cyan', color: 'white', align: 'left' },
  { value: 'Age', width: 10, headerColor: 'cyan', color: 'white', align: 'right' }
];
const rows = [
  ['Alice', 30],
  ['Bob', 25]
];
const options = {
  borderStyle: 'solid',
  borderColor: 'blue',
  paddingBottom: 0,
  headerAlign: 'center',
  align: 'center',
  color: 'white'
};
const table = ttyTable(header, rows, options);
console.log(table.render());

Adding Footers

This feature allows you to add footers to the table, which can be used to display summary information or totals.

const ttyTable = require('tty-table');
const header = [
  { value: 'Name', width: 30, headerColor: 'cyan' },
  { value: 'Age', width: 10, headerColor: 'cyan' }
];
const rows = [
  ['Alice', 30],
  ['Bob', 25]
];
const footer = [
  { value: 'Total', colspan: 1, align: 'right' },
  { value: '2', align: 'right' }
];
const table = ttyTable(header, rows, { footer });
console.log(table.render());

Other packages similar to tty-table

cli-table

cli-table is another npm package for creating tables in the terminal. It offers similar functionality to tty-table but with a different API. cli-table is known for its simplicity and ease of use, making it a popular choice for basic table creation.

table

The table package provides a more advanced and flexible way to create tables in the terminal. It supports a wide range of customization options and is suitable for more complex table layouts. Compared to tty-table, the table package offers more features but may have a steeper learning curve.

easy-table

easy-table is a lightweight package for creating tables in the terminal. It focuses on simplicity and ease of use, making it a good choice for quick and straightforward table creation. While it may not offer as many customization options as tty-table, it is very easy to get started with.

README

tty-table

Display yout data in a table using a terminal, browser, or browser console.

Installation

• To install as a terminal application:

$ sudo apt-get install nodejs 
$ npm install tty-table -g

• As a Nodejs module:

$ npm install tty-table

• Browser (via browserify)

<script src="tty-table.bundle.min.js"></script>
<script>
 var Table = require('tty-table');
 ...
</script>

Why would someone do such a thing?

• Can be used as a bugfixed, drop-in replacement for the unmaintained, but popular Automattic/cli-table:

var Table = require('tty-table')('automattic-cli-table');
//now runs with same syntax as Automattic/cli-table
...

• Fixes these open issues with Automattic/cli-table:
  • Text alignment
  • Alternative table character sets
  • Automatic text wrapping
  • Wide character support
  • Chokes on null values
  • Automatically resize to terminal width

In addition to the fixes listed above, the native API also supports:

• Optional callbacks on column values
• Header, body column alignment
• Padding
• Passing of rows as either arrays or objects
• Colors (not supported in browser)
• Footer
• Works in the browser as well as nodejs
• Can be run as a standalone terminal application

Output Examples

Terminal (Static)

examples/styles-and-formatting.js

Terminal (Streaming)

$ node examples/data/fake-stream.js | tty-table --format=json

• *See the built-in help for the terminal version of tty-table with:

$ tty-table -h

Browser & Browser Console

• examples/browser-example.html

Working Example in Browser

Note that neither ASCI colors nor default borders are rendered in the browser. An alternative border style, as shown below, should be used by setting the following option:

borderStyle : 2

Default API Reference

Table

Kind: global class
Note: Default border character sets:

[
[
 {v: " ", l: " ", j: " ", h: " ", r: " "},
 {v: " ", l: " ", j: " ", h: " ", r: " "},
 {v: " ", l: " ", j: " ", h: " ", r: " "}
],
[
 {v: "│", l: "┌", j: "┬", h: "─", r: "┐"},
 {v: "│", l: "├", j: "┼", h: "─", r: "┤"},
 {v: "│", l: "└", j: "┴", h: "─", r: "┘"}
],
[
 {v: "|", l: "+", j: "+", h: "-", r: "+"},
 {v: "|", l: "+", j: "+", h: "-", r: "+"},
 {v: "|", l: "+", j: "+", h: "-", r: "+"}
]
]

• Table
  • Table(header, rows, options)
  • .Cls.render() ⇒ String

Table(header, rows, options)

Param	Type	Description
header	array	See example
header.column	object	Column options
header.column.alias	string	Alernate header column name
header.column.align	string	default: "center"
header.column.color	string	default: terminal default color
header.column.footerAlign	string	default: "center"
header.column.footerColor	string	default: terminal default color
header.column.formatter	function	Runs a callback on each cell value in the parent column
header.column.headerAlign	string	default: "center"
header.column.headerColor	string	default: terminal's default color
header.column.marginLeft	number	default: 0
header.column.marginTop	number	default: 0
header.column.maxWidth	number	default: 20
header.column.paddingBottom	number	default: 0
header.column.paddingLeft	number	default: 0
header.column.paddingRight	number	default: 0
header.column.paddingTop	number	default: 0
rows	array	See example
options	object	Table options
options.borderStyle	number	default: 1 (0 = no border) Refers to the index of the desired character set.
options.borderCharacters	array	See @note
options.borderColor	string	default: terminal's default color
options.compact	boolean	default: false Removes horizontal lines when true.
options.defaultErrorValue	mixed	default: 'ERROR!'
options.defaultValue	mixed	default: '?'
options.errorOnNull	boolean	default: false
options.truncate	mixed	default: false When this property is set to a string, cell contents will be truncated by that string instead of wrapped when they extend beyond of the width of the cell. For example if: "truncate":"..." the cell will be truncated with "..."

Example

let Table = require('tty-table');
let t1 = Table(header,rows,options);
console.log(t1.render()); 

Table.Cls.render() ⇒ String

Renders a table to a string

Kind: static method of Table
Example

let str = t1.render(); 
console.log(str); //outputs table

Running tests

$ grunt test

Saving the output of new unit tests

$ grunt st

• Because:

node script.js --color=always

Dev Tips

• To generate vim tags (make sure jsctags is installed globally)

$ grunt tags

• To generate vim tags on file save

$ grunt watch

Packaging as a distributable

License

GPLv3 License

Copyright 2015-2017, Tecfu.