1 | CLI Table [![NPM Version](http://badge.fury.io/js/cli-table.svg)](http://badge.fury.io/js/cli-table) [![Build Status](https://secure.travis-ci.org/Automattic/cli-table.svg)](http://travis-ci.org/Automattic/cli-table)
|
2 | =========
|
3 |
|
4 | This utility allows you to render unicode-aided tables on the command line from
|
5 | your node.js scripts.
|
6 |
|
7 | ![Screenshot](http://i.imgur.com/sYq4T.png)
|
8 |
|
9 | ## Features
|
10 |
|
11 | - Customizable characters that constitute the table.
|
12 | - Color/background styling in the header through
|
13 | [colors.js](http://github.com/marak/colors.js)
|
14 | - Column width customization
|
15 | - Text truncation based on predefined widths
|
16 | - Text alignment (left, right, center)
|
17 | - Padding (left, right)
|
18 | - Easy-to-use API
|
19 |
|
20 | ## Installation
|
21 |
|
22 | ```bash
|
23 | npm install cli-table
|
24 | ```
|
25 |
|
26 | ## How to use
|
27 |
|
28 | ### Horizontal Tables
|
29 | ```javascript
|
30 | var Table = require('cli-table');
|
31 |
|
32 | // instantiate
|
33 | var table = new Table({
|
34 | head: ['TH 1 label', 'TH 2 label']
|
35 | , colWidths: [100, 200]
|
36 | });
|
37 |
|
38 | // table is an Array, so you can `push`, `unshift`, `splice` and friends
|
39 | table.push(
|
40 | ['First value', 'Second value']
|
41 | , ['First value', 'Second value']
|
42 | );
|
43 |
|
44 | console.log(table.toString());
|
45 | ```
|
46 |
|
47 | ### Vertical Tables
|
48 | ```javascript
|
49 | var Table = require('cli-table');
|
50 | var table = new Table();
|
51 |
|
52 | table.push(
|
53 | { 'Some key': 'Some value' }
|
54 | , { 'Another key': 'Another value' }
|
55 | );
|
56 |
|
57 | console.log(table.toString());
|
58 | ```
|
59 | ### Cross Tables
|
60 | Cross tables are very similar to vertical tables, with two key differences:
|
61 |
|
62 | 1. They require a `head` setting when instantiated that has an empty string as the first header
|
63 | 2. The individual rows take the general form of { "Header": ["Row", "Values"] }
|
64 |
|
65 | ```javascript
|
66 | var Table = require('cli-table');
|
67 | var table = new Table({ head: ["", "Top Header 1", "Top Header 2"] });
|
68 |
|
69 | table.push(
|
70 | { 'Left Header 1': ['Value Row 1 Col 1', 'Value Row 1 Col 2'] }
|
71 | , { 'Left Header 2': ['Value Row 2 Col 1', 'Value Row 2 Col 2'] }
|
72 | );
|
73 |
|
74 | console.log(table.toString());
|
75 | ```
|
76 |
|
77 | ### Custom styles
|
78 | The ```chars``` property controls how the table is drawn:
|
79 | ```javascript
|
80 | var table = new Table({
|
81 | chars: { 'top': '═' , 'top-mid': '╤' , 'top-left': '╔' , 'top-right': '╗'
|
82 | , 'bottom': '═' , 'bottom-mid': '╧' , 'bottom-left': '╚' , 'bottom-right': '╝'
|
83 | , 'left': '║' , 'left-mid': '╟' , 'mid': '─' , 'mid-mid': '┼'
|
84 | , 'right': '║' , 'right-mid': '╢' , 'middle': '│' }
|
85 | });
|
86 |
|
87 | table.push(
|
88 | ['foo', 'bar', 'baz']
|
89 | , ['frob', 'bar', 'quuz']
|
90 | );
|
91 |
|
92 | console.log(table.toString());
|
93 | // Outputs:
|
94 | //
|
95 | //╔══════╤═════╤══════╗
|
96 | //║ foo │ bar │ baz ║
|
97 | //╟──────┼─────┼──────╢
|
98 | //║ frob │ bar │ quuz ║
|
99 | //╚══════╧═════╧══════╝
|
100 | ```
|
101 |
|
102 | Empty decoration lines will be skipped, to avoid vertical separator rows just
|
103 | set the 'mid', 'left-mid', 'mid-mid', 'right-mid' to the empty string:
|
104 | ```javascript
|
105 | var table = new Table({ chars: {'mid': '', 'left-mid': '', 'mid-mid': '', 'right-mid': ''} });
|
106 | table.push(
|
107 | ['foo', 'bar', 'baz']
|
108 | , ['frobnicate', 'bar', 'quuz']
|
109 | );
|
110 |
|
111 | console.log(table.toString());
|
112 | // Outputs: (note the lack of the horizontal line between rows)
|
113 | //┌────────────┬─────┬──────┐
|
114 | //│ foo │ bar │ baz │
|
115 | //│ frobnicate │ bar │ quuz │
|
116 | //└────────────┴─────┴──────┘
|
117 | ```
|
118 |
|
119 | By setting all chars to empty with the exception of 'middle' being set to a
|
120 | single space and by setting padding to zero, it's possible to get the most
|
121 | compact layout with no decorations:
|
122 | ```javascript
|
123 | var table = new Table({
|
124 | chars: { 'top': '' , 'top-mid': '' , 'top-left': '' , 'top-right': ''
|
125 | , 'bottom': '' , 'bottom-mid': '' , 'bottom-left': '' , 'bottom-right': ''
|
126 | , 'left': '' , 'left-mid': '' , 'mid': '' , 'mid-mid': ''
|
127 | , 'right': '' , 'right-mid': '' , 'middle': ' ' },
|
128 | style: { 'padding-left': 0, 'padding-right': 0 }
|
129 | });
|
130 |
|
131 | table.push(
|
132 | ['foo', 'bar', 'baz']
|
133 | , ['frobnicate', 'bar', 'quuz']
|
134 | );
|
135 |
|
136 | console.log(table.toString());
|
137 | // Outputs:
|
138 | //foo bar baz
|
139 | //frobnicate bar quuz
|
140 | ```
|
141 |
|
142 | ## Running tests
|
143 |
|
144 | Clone the repository with all its submodules and run:
|
145 |
|
146 | ```bash
|
147 | $ make test
|
148 | ```
|
149 |
|
150 | ## Credits
|
151 |
|
152 | - Guillermo Rauch <guillermo@learnboost.com> ([Guille](http://github.com/guille))
|
153 |
|
154 | ## License
|
155 |
|
156 | (The MIT License)
|
157 |
|
158 | Copyright (c) 2010 LearnBoost <dev@learnboost.com>
|
159 |
|
160 | Permission is hereby granted, free of charge, to any person obtaining
|
161 | a copy of this software and associated documentation files (the
|
162 | 'Software'), to deal in the Software without restriction, including
|
163 | without limitation the rights to use, copy, modify, merge, publish,
|
164 | distribute, sublicense, and/or sell copies of the Software, and to
|
165 | permit persons to whom the Software is furnished to do so, subject to
|
166 | the following conditions:
|
167 |
|
168 | The above copyright notice and this permission notice shall be
|
169 | included in all copies or substantial portions of the Software.
|
170 |
|
171 | THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
|
172 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
173 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
174 | IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
|
175 | CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
|
176 | TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
|
177 | SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|