tty-table

A terminal table widget for nodejs and the browser.

Installation

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?

Drop-in replacement for the unmaintained Automattic/cli-table:

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

Fixes these known issues with Automattic/cli-table:
- Automatic text wrapping
- Supports Asian characters
- Automatically resizes to terminal width
See the docs here.

Beyond that, 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

(npm i -g tty-table)

Browser & Browser Console

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 Usage

var Table = require('tty-table');
var chalk = require('chalk');

var header = [
	{
		value : "item",
		headerColor : "cyan",
		color: "white",
		align : "left",
		paddingLeft : 5,
		width : 30
	},
	{
		value : "price",
		color : "red", 
		width : 10,
		formatter : function(value){
			var str = "$" + value.toFixed(2);
			if(value > 5){
				str = chalk.underline.green(str);
			}
			return str;
		}
	},
	{
		alias : "Is organic?",	
		value : "organic",
		width : 15,
		formatter : function(value){
			
			//will convert an empty string to 0	
			//value = value * 1;
			
			if(value === 'yes'){
				value = chalk.black.bgGreen(value);
			}
			else{
				value = chalk.white.bgRed(value);
			}
			return value;
		}
	}
];

//Example with arrays as rows 
var rows = [
	["hamburger",2.50,"no"],
	["el jefe's special cream sauce",0.10,"yes"],
	["two tacos, rice and beans topped with cheddar cheese",9.80,"no"],
	["apple slices",1.00,"yes"],
	["ham sandwich",1.50,"no"],
	["macaroni, ham and peruvian mozzarella",3.75,"no"]
];

var footer = [
	"TOTAL",
	(function(){
		return rows.reduce(function(prev,curr){
			return prev+curr[1]
		},0)
	}()),
	(function(){
		var total = rows.reduce(function(prev,curr){
			return prev+((curr[2]==='yes') ? 1 : 0);
		},0);
		return (total/rows.length*100).toFixed(2) + "%";
	}())];

var t1 = Table(header,rows,footer,{
	borderStyle : 1,
	borderColor : "blue",
	paddingBottom : 0,
	headerAlign : "center",
	align : "center",
	color : "white"
});

str1 = t1.render();
console.log(str1);


//Example with objects as rows 
var rows = [
	{
		item : "hamburger",
		price : 2.50,
		organic : "no"
	},
	{
		item : "el jefe's special cream sauce",
		price : 0.10,
		organic : "yes"
	},
	{
		item : "two tacos, rice and beans topped with cheddar cheese",
		price : 9.80,
		organic : "no"
	},
	{
		item : "apple slices",
		price : 1.00,
		organic : "yes"	
	},	
	{
		item : "ham sandwich",
		price : 1.50,
		organic : "no"
	},
	{
		item : "macaroni, ham and peruvian mozzarella",
		price : 3.75,
		organic : "no"
	}
];

var t2 = Table(header,rows,{
	borderStyle : 1,
	paddingBottom : 0,
	headerAlign : "center",
	align : "center",
	color : "white"
});

var str2 = t2.render();
console.log(str2);

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 Cell values are truncated when 'truncate' set to a string, length > 0

Example

var Table = require('tty-table');
var 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

var 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

oini / tty-table Goto Github PK

tty-table's Introduction