1 | # Easy table
|
2 |
|
3 | Simple and nice utility for rendering text tables with javascript.
|
4 |
|
5 | ## Usage
|
6 |
|
7 | ``` javascript
|
8 | var Table = require('easy-table');
|
9 |
|
10 | var data = [
|
11 | { id: 123123, desc: 'Something awesome', price: 1000.00 },
|
12 | { id: 245452, desc: 'Very interesting book', price: 11.45},
|
13 | { id: 232323, desc: 'Yet another product', price: 555.55 }
|
14 | ]
|
15 |
|
16 | var t = new Table;
|
17 |
|
18 | data.forEach(function (product) {
|
19 | t.cell('Product Id', product.id);
|
20 | t.cell('Description', product.desc);
|
21 | t.cell('Price, USD', product.price, Table.Number(2));
|
22 | t.newRow();
|
23 | });
|
24 |
|
25 | console.log(t.toString());
|
26 | ```
|
27 |
|
28 | The script above will render:
|
29 |
|
30 | ```
|
31 | Product Id Description Price, USD
|
32 | ---------- --------------------- ----------
|
33 | 123123 Something awesome 1000.00
|
34 | 245452 Very interesting book 11.45
|
35 | 232323 Yet another product 555.55
|
36 |
|
37 | ```
|
38 |
|
39 | `t.printTransposed()` yields
|
40 |
|
41 | ```
|
42 | Product Id : 245452 : 232323 : 123123
|
43 | Description : Very interesting book : Yet another product : Something awesome
|
44 | Price, USD : 11.45 : 555.55 : 1000.00
|
45 |
|
46 | ```
|
47 |
|
48 | Finally `t.print()` shows just the rows you pushed and nothing more
|
49 |
|
50 | ```
|
51 | 245452 Very interesting book 11.45
|
52 | 232323 Yet another product 555.55
|
53 | 123123 Something awesome 1000.00
|
54 |
|
55 | ```
|
56 |
|
57 | ### How it works
|
58 |
|
59 | The full signature of `.cell()` method is:
|
60 |
|
61 | ``` javascript
|
62 | t.cell(column, value, printer, width)
|
63 | ```
|
64 |
|
65 | By default column's width is ajusted to fit the longest value, but if specified
|
66 | explicitly it is fixed and any non-fitting cell is truncated.
|
67 |
|
68 | Cell's value rendering occures in two phases. At the first phase `printer`
|
69 | function is called to get minimal width required to fit cell correctly, at the
|
70 | second phase `printer` function is called to get actual string to render with
|
71 | additional `width` parameter supplied.
|
72 |
|
73 | ``` javascript
|
74 | // Example: Coloring too big numbers in red
|
75 |
|
76 | function markTooBigs (val, width) {
|
77 | if (width == null) return Table.string(val)
|
78 | return val > 100
|
79 | ? '\033[31m' + String(val) + '\033[39m'
|
80 | : Table.string(val)
|
81 | }
|
82 | ...
|
83 | t.cell('foo', 300, markTooBigs)
|
84 | ```
|
85 |
|
86 | ### Table.printArray(), Table.printObject()
|
87 |
|
88 | Often you just want to print an array or a simple key-value map.
|
89 | `Table.printArray()` and `Table.printObject()` help to instantiate and fill a table for such use cases.
|
90 |
|
91 | ``` javascript
|
92 | var array = [
|
93 | {foo: 'foo1', bar: 'bar1'},
|
94 | {foo: 'foo2', bar: 'bar2'}
|
95 | ]
|
96 |
|
97 | console.log(Table.printArray(array))
|
98 | ```
|
99 |
|
100 | yields
|
101 |
|
102 | ```
|
103 | foo bar
|
104 | ---- ----
|
105 | foo1 bar1
|
106 | foo2 bar2
|
107 |
|
108 | ```
|
109 |
|
110 | we can pass options to override defaut behaviour
|
111 |
|
112 | ``` javascript
|
113 | Table.printArray(array, {
|
114 | bar: {
|
115 | name: 'Long field name',
|
116 | printer: Table.padLeft
|
117 | }
|
118 | })
|
119 | ```
|
120 |
|
121 | ```
|
122 | foo Long field name
|
123 | ---- ---------------
|
124 | foo1 bar1
|
125 | foo2 bar2
|
126 |
|
127 | ```
|
128 |
|
129 | or have a full control over rendering
|
130 |
|
131 | ``` javascript
|
132 | Table.printArray(array, function (obj, cell) {
|
133 | cell('foo', obj.foo)
|
134 | cell('field', obj.bar)
|
135 | }, function (table) {
|
136 | return table.print()
|
137 | })
|
138 | ```
|
139 |
|
140 | `Table.printObj()` works in the same manner
|
141 |
|
142 | ``` javascript
|
143 | var obj = {
|
144 | foo: 'foo',
|
145 | bar: 'bar'
|
146 | }
|
147 |
|
148 | Table.printObj(obj)
|
149 | ```
|
150 |
|
151 | yields
|
152 |
|
153 | ```
|
154 | foo : foo
|
155 | bar : bar
|
156 | ```
|
157 |
|
158 | ### Sorting
|
159 |
|
160 | You can sort a table by calling `.sort()`, and optionally passing in a list of
|
161 | column names to sort on (by default uses all columns), or a custom comparator
|
162 | function. It is also possible to specify the sort order. For example:
|
163 |
|
164 | ``` javascript
|
165 | t.sort(['Price, USD|des']) // will sort in descending order
|
166 | t.sort(['Price, USD|asc']) // will sort in ascending order
|
167 | t.sort(['Price, USD']) // sorts in ascending order by default
|
168 | ```
|
169 |
|
170 | ### Totaling
|
171 |
|
172 | Easy table can help you to calculate and render totals:
|
173 |
|
174 | ``` javascript
|
175 | t.total('Price, USD', function accumulator (sum, val, index, length) {
|
176 | sum = sum || 0
|
177 | sum += val
|
178 | return index + 1 == length
|
179 | ? sum / length
|
180 | : sum
|
181 | }, function print (val, width) {
|
182 | var s = 'Avg: ' + Table.Number(2)
|
183 | return width == null
|
184 | ? s
|
185 | : Table.padLeft(s, width)
|
186 | })
|
187 | ```
|
188 |
|
189 | yields
|
190 |
|
191 | ```
|
192 | Product Id Description Price, USD
|
193 | ---------- --------------------- -----------
|
194 | 245452 Very interesting book 11.45
|
195 | 232323 Yet another product 555.55
|
196 | 123123 Something awesome 1000.00
|
197 | ---------- --------------------- -----------
|
198 | Avg: 522.33
|
199 | ```
|
200 |
|
201 | `total()` function also accepts printer via `printer` property of
|
202 | accumulator, so it is possible to create reusable aggregations like:
|
203 |
|
204 | ``` javascript
|
205 | var priceAvg = // some accumulator
|
206 | priceAvg.printer = // some printer
|
207 | ...
|
208 | t.total('Price', 300.50, priceAvg)
|
209 | ```
|
210 |
|
211 | ## Installation
|
212 |
|
213 | Just install from the npm repository with:
|
214 |
|
215 | ```
|
216 | $ npm install easy-table
|
217 | ```
|
218 |
|
219 | ## Misc
|
220 |
|
221 | Easy table now has kind of stable api and exposes many of it's internals.
|
222 | But in any case it's better to specify strict version numbers in your modules
|
223 | especially if you use methods or properties not covered by this readme.
|
224 |
|
225 |
|
226 | ## License
|
227 |
|
228 | (The MIT License)
|
229 |
|
230 | Copyright (c) 2012 Eldar Gabdullin <eldargab@gmail.com>
|
231 |
|
232 | Permission is hereby granted, free of charge, to any person obtaining
|
233 | a copy of this software and associated documentation files (the
|
234 | 'Software'), to deal in the Software without restriction, including
|
235 | without limitation the rights to use, copy, modify, merge, publish,
|
236 | distribute, sublicense, and/or sell copies of the Software, and to
|
237 | permit persons to whom the Software is furnished to do so, subject to
|
238 | the following conditions:
|
239 |
|
240 | The above copyright notice and this permission notice shall be
|
241 | included in all copies or substantial portions of the Software.
|
242 |
|
243 | THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
|
244 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
245 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
246 | IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
|
247 | CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
|
248 | TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
|
249 | SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|