tty-table

Terminal table for Windows, Linux, and MacOS. Written in nodejs. Also works in browser console. Word wrap, padding, alignment, colors, Asian character support, per-column callbacks, and you can pass rows as objects or arrays. Backwards compatible with Automattic/cli-table.

Description

Pipe JSON or CSV to tty-table and get a table output to your terminal, import tty-table as a module for your own cli application, or use it in the browser.

Code Quality Rank: L4

Monthly Downloads: 0

Programming language: JavaScript

License: MIT License

Tags: Table     Command Line Apps     Terminal Table     Cli Table     Json To Table     Csv To Table     Ascii Table     Console.table     Table In Bash    

Latest version: v4.1.3

README

tty-table 端子台

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

---

[Examples](examples/)

[See here for complete example list](examples/)

To view all example output:

$ git clone https://github.com/tecfu/tty-table && cd tty-table && npm i
$ npm run view-examples

Terminal (Static)

[examples/styles-and-formatting.js](examples/styles-and-formatting.js)

Terminal (Streaming)

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

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

Browser & Browser Console

• View in Chrome or Chromium at http://localhost:8070/examples/browser-example.html using a dockerized apache instance:

  git clone https://github.com/tecfu/tty-table
  cd tty-table
  docker run -dit --name tty-table-in-browser -p 8070:80 -v "$PWD":/usr/local/apache2/htdocs/ httpd:2.4
  

• live demo (chrome only): jsfiddle

• live demo (chrome only): plnkr

• [source: examples/browser-example.html](examples/browser-example.html)

API Reference

<!--API-REF-->

Table(header array, rows array, options object)

Param	Type	Description
header	array	Per-column configuration. An array of objects, one object for each column. Each object contains properties you can use to configure that particular column. See available properties
rows	array	Your data. An array of arrays or objects. See examples
options	object	Global table configuration. See available properties

header array of objects

Param	Type	Description
alias	string	Text to display in column header cell
align	string	default: "center"
color	string	default: terminal default color
footerAlign	string	default: "center"
footerColor	string	default: terminal default color
formatter	function(cellValue, columnIndex, rowIndex, rowData, inputData	Runs a callback on each cell value in the parent column. Please note that fat arrow functions () => {} don't support scope overrides, and this feature won't work correctly within them.
@formatter configure	function(object)	Configure cell properties. For example: this.configure({ truncate: false, align: "left" }) More here.
@formatter resetStyle	function(cellValue)	Removes ANSI escape sequences. For example: this.resetStyle(" myText") // "myText"
@formatter style	function(cellValue, effect)	Style cell value. For example: this.style("mytext", "bold", "green", "underline")For a full list of options in the terminal: chalk. For a full list of options in the browser: kleur
headerAlign	string	default: "center"
headerColor	string	default: terminal's default color
marginLeft	integer	default: 0
marginTop	integer	default: 0
paddingBottom	integer	default: 0
paddingLeft	integer	default: 1
paddingRight	integer	default: 1
paddingTop	integer	default: 0
value	string	Name of the property to display in each cell when data passed as an array of objects
width	string \	\

Example

let header = [{
  value: "item",
  headerColor: "cyan",
  color: "white",
  align: "left",
  width: 20
},
{
  value: "price",
  color: "red",
  width: 10,
  formatter: function (value) {
    let str = `$${value.toFixed(2)}`
    return (value > 5) ? this.style(str, "green", "bold") : 
      this.style(str, "red", "underline")
  }
}]

rows array

Example

• each row an array js const rows = [ ["hamburger",2.50], ]
• each row an object js const rows = [ { item: "hamburger", price: 2.50 } ]

footer array

• Footer is optional

Example

const footer = [
  "TOTAL",
  function (cellValue, columnIndex, rowIndex, rowData) {
    let total = rowData.reduce((prev, curr) => {
      return prev + curr[1]
    }, 0)
    .toFixed(2)

    return this.style(`$${total}`, "italic")
  }
]

options object

Param	Type	Description
borderStyle	string	default: "solid". options: "solid", "dashed", "none"
borderColor	string	default: terminal default color
color	string	default: terminal default color
compact	boolean	default: false Removes horizontal borders when true.
defaultErrorValue	mixed	default: '�'
defaultValue	mixed	default: '?'
errorOnNull	boolean	default: false
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 "..." Note: tty-table wraps overflowing cell text into multiple lines by default, so you would likely only utilize truncate for extremely long values.
width	string	default: "100%" Width of the table. Can be a percentage of i.e. "50%" or a fixed number of columns in the terminal viewport i.e. "100". Note: When you use a percentage, your table will be "responsive".

Example

const options = {
  borderStyle: "solid",
  borderColor: "blue",
  headerAlign: "center",
  align: "left",
  color: "white",
  truncate: "...",
  width: "90%"
}

Table.render() ⇒ String

Add method to render table to a string

Example

const out = Table(header,rows,options).render()
console.log(out); //prints output

<!--END-API-REF-->

Installation

• [Terminal](docs/terminal.md):

$ npm install tty-table -g

• Node Module

$ npm install tty-table

• Browser

import Table from 'https://cdn.jsdelivr.net/gh/tecfu/tty-table/dist/tty-table.esm.js'
let Table = require('tty-table')   // https://cdn.jsdelivr.net/gh/tecfu/tty-table/dist/tty-table.cjs.js
let Table = TTY_Table;             // https://cdn.jsdelivr.net/gh/tecfu/tty-table/dist/tty-table.umd.js

Version Compatibility

Node Version	tty-table Version
8	>= 2.0
0.11	>= 0.0

Running tests

$ npm test

$ npm run coverage

Saving the output of new unit tests

$ npm run save-tests

Dev Tips

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

$ npm run tags

• To generate vim tags on file save

$ npm run watch-tags

Pull Requests

Pull requests are encouraged!

• Please remember to add a unit test when necessary
• Please format your commit messages according to the "Conventional Commits" specification

If you aren't familiar with Conventional Commits, here's a good article on the topic

TL/DR:

• feat: a feature that is visible for end users.
• fix: a bugfix that is visible for end users.
• chore: a change that doesn't impact end users (e.g. chances to CI pipeline)
• docs: a change in the README or documentation
• refactor: a change in production code focused on readability, style and/or performance.

[Packaging as a distributable](packaging.md)

License

MIT License

Copyright 2015-2020, Tecfu.