1 | CLI Table 2 [![npm version](https://badge.fury.io/js/cli-table2.svg)](http://badge.fury.io/js/cli-table2) [![Build Status](https://travis-ci.org/jamestalmage/cli-table2.svg?branch=master)](https://travis-ci.org/jamestalmage/cli-table2) [![Coverage Status](https://coveralls.io/repos/jamestalmage/cli-table2/badge.png?branch=master)](https://coveralls.io/r/jamestalmage/cli-table2?branch=master)
|
2 | ===========
|
3 |
|
4 | This utility allows you to render unicode-aided tables on the command line from
|
5 | your node.js scripts. Based on (and api compatible with) the original [cli-table](https://github.com/Automattic/cli-table),
|
6 | `cli-table2` is nearly a complete rewrite to accommodate column and row spanning.
|
7 | It passes the entire original cli-table test suite, and should be a drop in
|
8 | replacement for nearly all users.
|
9 |
|
10 | ![Screenshot](http://i.imgur.com/sYq4T.png)
|
11 |
|
12 | ## Features not in the original cli-table
|
13 |
|
14 | - Ability to make cells span columns and/or rows.
|
15 | - Ability to set custom styles per cell (border characters/colors, padding, etc).
|
16 | - Vertical alignment (top, bottom, center).
|
17 | - More robust truncation of cell text that contains ansi color characters.
|
18 | - API compatible with the original cli-table.
|
19 | - Exhaustive test suite including the entire original cli-table test suite.
|
20 | - Lots of examples auto-generated from the tests ([basic](https://github.com/jamestalmage/cli-table2/blob/master/basic-usage.md), [advanced](https://github.com/jamestalmage/cli-table2/blob/master/advanced-usage.md)).
|
21 |
|
22 | ## Features
|
23 |
|
24 | - Customizable characters that constitute the table.
|
25 | - Color/background styling in the header through
|
26 | [colors.js](http://github.com/marak/colors.js)
|
27 | - Column width customization
|
28 | - Text truncation based on predefined widths
|
29 | - Text alignment (left, right, center)
|
30 | - Padding (left, right)
|
31 | - Easy-to-use API
|
32 |
|
33 | ## Installation
|
34 |
|
35 | ```bash
|
36 | npm install cli-table2
|
37 | ```
|
38 |
|
39 | ## How to use
|
40 |
|
41 | A portion of the unit test suite is used to generate examples:
|
42 | - [basic-usage](https://github.com/jamestalmage/cli-table2/blob/master/basic-usage.md) - covers basic uses.
|
43 | - [advanced](https://github.com/jamestalmage/cli-table2/blob/master/advanced-usage.md) - covers using the new column and row span features.
|
44 |
|
45 | This package is api compatible with the original [cli-table](https://github.com/Automattic/cli-table).
|
46 | So all the original documentation still applies (copied below).
|
47 |
|
48 | ### Horizontal Tables
|
49 | ```javascript
|
50 | var Table = require('cli-table2');
|
51 |
|
52 | // instantiate
|
53 | var table = new Table({
|
54 | head: ['TH 1 label', 'TH 2 label']
|
55 | , colWidths: [100, 200]
|
56 | });
|
57 |
|
58 | // table is an Array, so you can `push`, `unshift`, `splice` and friends
|
59 | table.push(
|
60 | ['First value', 'Second value']
|
61 | , ['First value', 'Second value']
|
62 | );
|
63 |
|
64 | console.log(table.toString());
|
65 | ```
|
66 |
|
67 | ### Vertical Tables
|
68 | ```javascript
|
69 | var Table = require('cli-table2');
|
70 | var table = new Table();
|
71 |
|
72 | table.push(
|
73 | { 'Some key': 'Some value' }
|
74 | , { 'Another key': 'Another value' }
|
75 | );
|
76 |
|
77 | console.log(table.toString());
|
78 | ```
|
79 | ### Cross Tables
|
80 | Cross tables are very similar to vertical tables, with two key differences:
|
81 |
|
82 | 1. They require a `head` setting when instantiated that has an empty string as the first header
|
83 | 2. The individual rows take the general form of { "Header": ["Row", "Values"] }
|
84 |
|
85 | ```javascript
|
86 | var Table = require('cli-table2');
|
87 | var table = new Table({ head: ["", "Top Header 1", "Top Header 2"] });
|
88 |
|
89 | table.push(
|
90 | { 'Left Header 1': ['Value Row 1 Col 1', 'Value Row 1 Col 2'] }
|
91 | , { 'Left Header 2': ['Value Row 2 Col 1', 'Value Row 2 Col 2'] }
|
92 | );
|
93 |
|
94 | console.log(table.toString());
|
95 | ```
|
96 |
|
97 | ### Custom styles
|
98 | The ```chars``` property controls how the table is drawn:
|
99 | ```javascript
|
100 | var table = new Table({
|
101 | chars: { 'top': '═' , 'top-mid': '╤' , 'top-left': '╔' , 'top-right': '╗'
|
102 | , 'bottom': '═' , 'bottom-mid': '╧' , 'bottom-left': '╚' , 'bottom-right': '╝'
|
103 | , 'left': '║' , 'left-mid': '╟' , 'mid': '─' , 'mid-mid': '┼'
|
104 | , 'right': '║' , 'right-mid': '╢' , 'middle': '│' }
|
105 | });
|
106 |
|
107 | table.push(
|
108 | ['foo', 'bar', 'baz']
|
109 | , ['frob', 'bar', 'quuz']
|
110 | );
|
111 |
|
112 | console.log(table.toString());
|
113 | // Outputs:
|
114 | //
|
115 | //╔══════╤═════╤══════╗
|
116 | //║ foo │ bar │ baz ║
|
117 | //╟──────┼─────┼──────╢
|
118 | //║ frob │ bar │ quuz ║
|
119 | //╚══════╧═════╧══════╝
|
120 | ```
|
121 |
|
122 | Empty decoration lines will be skipped, to avoid vertical separator rows just
|
123 | set the 'mid', 'left-mid', 'mid-mid', 'right-mid' to the empty string:
|
124 | ```javascript
|
125 | var table = new Table({ chars: {'mid': '', 'left-mid': '', 'mid-mid': '', 'right-mid': ''} });
|
126 | table.push(
|
127 | ['foo', 'bar', 'baz']
|
128 | , ['frobnicate', 'bar', 'quuz']
|
129 | );
|
130 |
|
131 | console.log(table.toString());
|
132 | // Outputs: (note the lack of the horizontal line between rows)
|
133 | //┌────────────┬─────┬──────┐
|
134 | //│ foo │ bar │ baz │
|
135 | //│ frobnicate │ bar │ quuz │
|
136 | //└────────────┴─────┴──────┘
|
137 | ```
|
138 |
|
139 | By setting all chars to empty with the exception of 'middle' being set to a
|
140 | single space and by setting padding to zero, it's possible to get the most
|
141 | compact layout with no decorations:
|
142 | ```javascript
|
143 | var table = new Table({
|
144 | chars: { 'top': '' , 'top-mid': '' , 'top-left': '' , 'top-right': ''
|
145 | , 'bottom': '' , 'bottom-mid': '' , 'bottom-left': '' , 'bottom-right': ''
|
146 | , 'left': '' , 'left-mid': '' , 'mid': '' , 'mid-mid': ''
|
147 | , 'right': '' , 'right-mid': '' , 'middle': ' ' },
|
148 | style: { 'padding-left': 0, 'padding-right': 0 }
|
149 | });
|
150 |
|
151 | table.push(
|
152 | ['foo', 'bar', 'baz']
|
153 | , ['frobnicate', 'bar', 'quuz']
|
154 | );
|
155 |
|
156 | console.log(table.toString());
|
157 | // Outputs:
|
158 | //foo bar baz
|
159 | //frobnicate bar quuz
|
160 | ```
|
161 |
|
162 | ## Build Targets
|
163 |
|
164 | Clone the repository and run `npm install` to install all its submodules, then run one of the following commands:
|
165 |
|
166 | ###### Run the tests with coverage reports.
|
167 | ```bash
|
168 | $ gulp coverage
|
169 | ```
|
170 |
|
171 | ###### Run the tests every time a file changes.
|
172 | ```bash
|
173 | $ gulp watch-test
|
174 | ```
|
175 |
|
176 | ###### Run the examples and print the output to the command line.
|
177 | ```bash
|
178 | $ gulp example
|
179 | ```
|
180 |
|
181 | Other build targets are available, check `gulpfile.js` for a comprehensive list.
|
182 |
|
183 | ## Credits
|
184 |
|
185 | - James Talmage - author <james.talmage@jrtechnical.com> ([jamestalmage](http://github.com/jamestalmage))
|
186 | - Guillermo Rauch - author of the original cli-table <guillermo@learnboost.com> ([Guille](http://github.com/guille))
|
187 |
|
188 | ## License
|
189 |
|
190 | (The MIT License)
|
191 |
|
192 | Copyright (c) 2014 James Talmage <james.talmage@jrtechnical.com>
|
193 |
|
194 | Original cli-table code/documentation: Copyright (c) 2010 LearnBoost <dev@learnboost.com>
|
195 |
|
196 | Permission is hereby granted, free of charge, to any person obtaining
|
197 | a copy of this software and associated documentation files (the
|
198 | 'Software'), to deal in the Software without restriction, including
|
199 | without limitation the rights to use, copy, modify, merge, publish,
|
200 | distribute, sublicense, and/or sell copies of the Software, and to
|
201 | permit persons to whom the Software is furnished to do so, subject to
|
202 | the following conditions:
|
203 |
|
204 | The above copyright notice and this permission notice shall be
|
205 | included in all copies or substantial portions of the Software.
|
206 |
|
207 | THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
|
208 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
209 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
210 | IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
|
211 | CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
|
212 | TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
|
213 | SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|