1 | Ascii Table
|
2 | ===========
|
3 |
|
4 | [![Build Status](https://secure.travis-ci.org/sorensen/ascii-table.png)](http://travis-ci.org/sorensen/ascii-table)
|
5 | [![devDependency Status](https://david-dm.org/sorensen/ascii-table.png)](https://david-dm.org/sorensen/ascii-table#info=dependencies)
|
6 | [![NPM version](https://badge.fury.io/js/ascii-table.png)](http://badge.fury.io/js/ascii-table)
|
7 |
|
8 | Easy table output for node debugging, but you could probably do more with it,
|
9 | since its just a string.
|
10 |
|
11 | Table of Contents
|
12 | -----------------
|
13 |
|
14 | * [Usage](#usage)
|
15 | * [Example](#usage)
|
16 | * [API](#api)
|
17 | - [Static Methods](#static-methods)
|
18 | * [factory([title])](#asciitablefactorytitle)
|
19 | * [align(direction, val, len, [pad])](#asciitablealigndirection-val-len-pad)
|
20 | * [alignLeft(val, len, [pad])](#asciitablealignleftval-len-pad)
|
21 | * [alignCenter(val, len, [pad])](#asciitablealigncenterval-len-pad)
|
22 | * [alignRight(val, len, [pad])](#asciitablealignrightval-len-pad)
|
23 | * [alignAuto(val, len, [pad])](#asciitablealignautoval-len-pad)
|
24 | * [arrayFill(len, [val])](#asciitablearrayfilllen-val)
|
25 | - [Instance Methods](#instance-methods)
|
26 | * [setBorder([edge], [fill], [top], [bottom])](#instancesetborderedge-fill-top-bottom)
|
27 | * [removeBorder()](#instanceremoveborder)
|
28 | * [setAlign(idx, direction)](#instancesetalignidx-direction)
|
29 | * [setAlignLeft(idx)](#instancesetalignleftidx)
|
30 | * [setAlignCenter(idx)](#instancesetaligncenteridx)
|
31 | * [setAlignRight(idx)](#instancesetalignrightidx)
|
32 | * [setTitle(title)](#instancesettitletitle)
|
33 | * [getTitle()](#instancegettitle)
|
34 | * [setTitleAlign(direction)](#instancesettitlealigndirection)
|
35 | * [setTitleAlignLeft()](#instancesettitlealignleft)
|
36 | * [setTitleAlignCenter()](#instancesettitlealigncenter)
|
37 | * [setTitleAlignRight()](#instancesettitlealignright)
|
38 | * [sort([iterator])](#instancesortiterator)
|
39 | * [sortColumn(idx, [iterator])](#instancesortcolumnidx-iterator)
|
40 | * [setHeading(heading, [...])](#instancesetheadingheading)
|
41 | * [setHeadingAlign(direction)](#instancesetheadingaligndirection)
|
42 | * [setHeadingAlignLeft()](#instancesetheadingalignleft)
|
43 | * [setHeadingAlignCenter()](#instancesetheadingaligncenter)
|
44 | * [setHeadingAlignRight()](#instancesetheadingalignright)
|
45 | * [addRow(row, [...])](#instanceaddrowrow)
|
46 | * [addRowMatrix(rows)](#instanceaddrowmatrixrows)
|
47 | * [setJustify([enabled])](#instancesetjustifyenabled)
|
48 | * [toString()](#instancetostring)
|
49 | * [toJSON()](#instancetojson)
|
50 | * [fromJSON(obj)](#instancefromjsonobj)
|
51 | * [clear()](#instanceclear)
|
52 | * [clearRows()](#instanceclearrows)
|
53 | * [Install](#install)
|
54 | * [License](#license)
|
55 |
|
56 | Usage
|
57 | -----
|
58 |
|
59 | Node.js
|
60 |
|
61 | ```js
|
62 | var AsciiTable = require('ascii-table')
|
63 | ```
|
64 |
|
65 | Browser
|
66 |
|
67 | ```html
|
68 | <script src="ascii-table.min.js"></script>
|
69 | ```
|
70 |
|
71 | *Note*: If using in the browser, it will be placed under `window.AsciiTable`
|
72 |
|
73 |
|
74 | Example
|
75 | -------
|
76 |
|
77 | Basic usage
|
78 |
|
79 | ```js
|
80 | var table = new AsciiTable('A Title')
|
81 | table
|
82 | .setHeading('', 'Name', 'Age')
|
83 | .addRow(1, 'Bob', 52)
|
84 | .addRow(2, 'John', 34)
|
85 | .addRow(3, 'Jim', 83)
|
86 |
|
87 | console.log(table.toString())
|
88 | ```
|
89 |
|
90 | ```
|
91 | .----------------.
|
92 | | A Title |
|
93 | |----------------|
|
94 | | | Name | Age |
|
95 | |---|------|-----|
|
96 | | 1 | Bob | 52 |
|
97 | | 2 | John | 34 |
|
98 | | 3 | Jim | 83 |
|
99 | '----------------'
|
100 | ```
|
101 |
|
102 | We can make a simple table without a title or headings as well.
|
103 |
|
104 | ```js
|
105 | var table = new AsciiTable()
|
106 |
|
107 | table
|
108 | .addRow('a', 'apple', 'Some longer string')
|
109 | .addRow('b', 'banana', 'hi')
|
110 | .addRow('c', 'carrot', 'meow')
|
111 | .addRow('e', 'elephants')
|
112 |
|
113 |
|
114 | console.log(table.toString())
|
115 | ```
|
116 |
|
117 | ```
|
118 | .------------------------------------.
|
119 | | a | apple | Some longer string |
|
120 | | b | banana | hi |
|
121 | | c | carrot | meow |
|
122 | | e | elephants | |
|
123 | '------------------------------------'
|
124 | ```
|
125 |
|
126 |
|
127 | API
|
128 | ---
|
129 |
|
130 | ### Static Methods
|
131 |
|
132 | #### AsciiTable
|
133 |
|
134 | See: `AsciiTable.factory` for details on instantiation
|
135 |
|
136 | #### AsciiTable.factory([title], [options])
|
137 |
|
138 | Table instance creator
|
139 |
|
140 | * `title` - table title (optional, default `null`)
|
141 | * `options` - table options (optional)
|
142 | - `prefix` - string prefix to add to each line on render
|
143 |
|
144 | ***Note:*** If an object is passed in place of the `title`, the `fromJSON`
|
145 | method will be used to populate the table.
|
146 |
|
147 | Example:
|
148 |
|
149 | ```js
|
150 | var table = AsciiTable.factory('title')
|
151 |
|
152 | var table = AsciiTable.factory({
|
153 | title: 'Title'
|
154 | , heading: [ 'id', 'name' ]
|
155 | , rows: [
|
156 | [ 1, 'Bob' ]
|
157 | , [ 2, 'Steve' ]
|
158 | ]
|
159 | })
|
160 | ```
|
161 |
|
162 |
|
163 | #### AsciiTable.align(direction, val, len, [pad])
|
164 |
|
165 | Shortcut to one of the three following methods
|
166 |
|
167 | * `direction` - alignment direction (`AsciiTable.LEFT`, `AsciiTable.CENTER`, `AsciiTable.RIGHT`)
|
168 | * `val` - string to align
|
169 | * `len` - total length of created string
|
170 | * `pad` - padding / fill char (optional, default `' '`)
|
171 |
|
172 | Example:
|
173 |
|
174 | ```js
|
175 | table.align(AsciiTable.LEFT, 'hey', 7) // 'hey '
|
176 | ```
|
177 |
|
178 |
|
179 | #### AsciiTable.alignLeft(val, len, [pad])
|
180 |
|
181 | * `val` - string to align
|
182 | * `len` - total length of created string
|
183 | * `pad` - padding / fill char (optional, default `' '`)
|
184 |
|
185 | Example:
|
186 |
|
187 | ```js
|
188 | table.alignLeft('hey', 7, '-') // 'hey----'
|
189 | ```
|
190 |
|
191 |
|
192 | #### AsciiTable.alignCenter(val, len, [pad])
|
193 |
|
194 | * `val` - string to align
|
195 | * `len` - total length of created string
|
196 | * `pad` - padding / fill char (optional, default `' '`)
|
197 |
|
198 | Example:
|
199 |
|
200 | ```js
|
201 | table.alignCenter('hey', 7) // ' hey '
|
202 | ```
|
203 |
|
204 |
|
205 | #### AsciiTable.alignRight(val, len, [pad])
|
206 |
|
207 | * `val` - string to align
|
208 | * `len` - total length of created string
|
209 | * `pad` - padding / fill char (optional, default `' '`)
|
210 |
|
211 | Example:
|
212 |
|
213 | ```js
|
214 | table.alignRight('hey', 7) // ' hey'
|
215 | ```
|
216 |
|
217 |
|
218 | #### AsciiTable.alignAuto(val, len, [pad])
|
219 |
|
220 | Attempt to do intelligent alignment of provided `val`, `String` input will
|
221 | be left aligned, `Number` types will be right aligned.
|
222 |
|
223 | * `val` - string to align
|
224 | * `len` - total length of created string
|
225 | * `pad` - padding / fill char (optional, default `' '`)
|
226 |
|
227 | Example:
|
228 |
|
229 | ```js
|
230 | table.align(AsciiTable.LEFT, 'hey', 7) // 'hey '
|
231 | ```
|
232 |
|
233 |
|
234 | #### AsciiTable.arrayFill(len, [val])
|
235 |
|
236 | Create a new array at the given len, filled with the given value, mainly used internally
|
237 |
|
238 | * `len` - length of array
|
239 | * `val` - fill value (optional)
|
240 |
|
241 | Example:
|
242 |
|
243 | ```js
|
244 | AsciiTable.arrayFill(4, 0) // [0, 0, 0, 0]
|
245 | ```
|
246 |
|
247 | ### Instance Methods
|
248 |
|
249 | #### instance.setBorder([edge], [fill], [top], [bottom])
|
250 |
|
251 | Set the border characters for rendering, if no arguments are passed it will be
|
252 | reset to defaults. If a single `edge` arg is passed, it will be used for all borders.
|
253 |
|
254 | * `edge` - horizontal edges (optional, default `|`)
|
255 | * `fill` - vertical edges (optional, default `-`)
|
256 | * `top` - top corners (optional, default `.`)
|
257 | * `bottom` - bottom corners (optional, default `'`)
|
258 |
|
259 | Example:
|
260 |
|
261 | ```js
|
262 | var table = new AsciiTable('Stars')
|
263 | table
|
264 | .setBorder('*')
|
265 | .setHeading('oh', 'look')
|
266 | .addRow('so much', 'star power')
|
267 |
|
268 | console.log(table.toString())
|
269 | ```
|
270 |
|
271 | ```
|
272 | ************************
|
273 | * Stars *
|
274 | ************************
|
275 | * oh * look *
|
276 | ************************
|
277 | * so much * star power *
|
278 | ************************
|
279 | ```
|
280 |
|
281 |
|
282 | #### instance.removeBorder()
|
283 |
|
284 | Example:
|
285 |
|
286 | ```js
|
287 | table.removeBorder()
|
288 |
|
289 | console.log('' + table)
|
290 | ```
|
291 |
|
292 | ```
|
293 | # Fruit Thing
|
294 | --- ----------- --------------------
|
295 | a apple Some longer string
|
296 | b banana hi
|
297 | c carrot meow
|
298 | e elephants
|
299 | ```
|
300 |
|
301 |
|
302 | #### instance.setAlign(idx, direction)
|
303 |
|
304 | * `idx` - column index to align
|
305 | * `direction` - alignment direction, (`AsciiTable.LEFT`, `AsciiTable.CENTER`, `AsciiTable.RIGHT`)
|
306 |
|
307 | Example:
|
308 |
|
309 | ```js
|
310 | table
|
311 | .setAlign(2, AsciiTable.RIGHT)
|
312 | .setAlign(1, AsciiTable.CENTER)
|
313 |
|
314 | console.log(table.toString())
|
315 | ```
|
316 |
|
317 | ```
|
318 | .-------------------------------------.
|
319 | | a | apple | Some longer string |
|
320 | | b | banana | hi |
|
321 | | c | carrot | meow |
|
322 | | e | elephants | |
|
323 | '-------------------------------------'
|
324 | ```
|
325 |
|
326 |
|
327 | #### instance.setAlignLeft(idx)
|
328 |
|
329 | Alias to `instance.setAlign(idx, AsciiTable.LEFT)`
|
330 |
|
331 |
|
332 | #### instance.setAlignCenter(idx)
|
333 |
|
334 | Alias to `instance.setAlign(idx, AsciiTable.CENTER)`
|
335 |
|
336 |
|
337 | #### instance.setAlignRight(idx)
|
338 |
|
339 | Alias to `instance.setAlign(idx, AsciiTable.RIGHT)`
|
340 |
|
341 |
|
342 | #### instance.setTitle(title)
|
343 |
|
344 | * `title` - table title
|
345 |
|
346 | Example:
|
347 |
|
348 | ```js
|
349 | var table = new AsciiTable('Old Title')
|
350 |
|
351 | table.setTitle('New Title')
|
352 | ```
|
353 |
|
354 | #### instance.getTitle()
|
355 |
|
356 | Get the current title of the table
|
357 |
|
358 | Example:
|
359 |
|
360 | ```js
|
361 | table.getTitle() // 'New Title'
|
362 | ```
|
363 |
|
364 |
|
365 | #### instance.setTitleAlign(direction)
|
366 |
|
367 | * `direction` - table alignment direction
|
368 |
|
369 | Example:
|
370 |
|
371 | ```js
|
372 | ```
|
373 |
|
374 |
|
375 | #### instance.setTitleAlignLeft()
|
376 |
|
377 | Alias to `instance.setTitleAlign(AsciiTable.LEFT)`
|
378 |
|
379 |
|
380 | #### instance.setTitleAlignCenter()
|
381 |
|
382 | Alias to `instance.setTitleAlign(AsciiTable.CENTER)`
|
383 |
|
384 |
|
385 | #### instance.setTitleAlignRight()
|
386 |
|
387 | Alias to `instance.setTitleAlign(AsciiTable.RIGHT)`
|
388 |
|
389 |
|
390 | #### instance.sort(iterator)
|
391 |
|
392 | * `iterator` - sorting method to run against the rows
|
393 |
|
394 | Example:
|
395 |
|
396 | ```js
|
397 | table.sort(function(a, b) {
|
398 | return a[2] - b[2]
|
399 | })
|
400 | console.log(table.toString())
|
401 | ```
|
402 |
|
403 | ```
|
404 | .----------------.
|
405 | | 2 | John | 34 |
|
406 | | 1 | Bob | 52 |
|
407 | | 3 | Jim | 83 |
|
408 | '----------------'
|
409 | ```
|
410 |
|
411 |
|
412 | #### instance.sortColumn(index, iterator)
|
413 |
|
414 | Sorting shortcut for targeting a specific column
|
415 |
|
416 | * `index` - column idx to sort
|
417 | * `iterator` - sorting method to run against column values
|
418 |
|
419 | Example:
|
420 |
|
421 | ```js
|
422 | // This is quivalent to the `sort` example above
|
423 | table.sortColumn(2, function(a, b) {
|
424 | return a - b
|
425 | })
|
426 | ```
|
427 |
|
428 |
|
429 | #### instance.setHeading(heading, [...])
|
430 |
|
431 | Set the column headings for the table, takes arguments the same way as `addRow`
|
432 |
|
433 | * `heading` - heading array or arguments
|
434 |
|
435 | Example:
|
436 |
|
437 | ```js
|
438 | table.setHeading('ID', 'Key', 'Value')
|
439 |
|
440 | // or:
|
441 |
|
442 | table.setHeading(['ID', 'Key', 'Value'])
|
443 | ```
|
444 |
|
445 |
|
446 | #### instance.setHeadingAlign(direction)
|
447 |
|
448 | * `direction` -
|
449 |
|
450 | Example:
|
451 |
|
452 | ```js
|
453 | ```
|
454 |
|
455 |
|
456 | #### instance.setHeadingAlignLeft()
|
457 |
|
458 | Alias to `instance.setHeadingAlignLeft(AsciiTable.LEFT)`
|
459 |
|
460 |
|
461 | #### instance.setHeadingAlignCenter()
|
462 |
|
463 | Alias to `instance.setHeadingAlignLeft(AsciiTable.CENTER)`
|
464 |
|
465 |
|
466 | #### instance.setHeadingAlignRight()
|
467 |
|
468 | Alias to `instance.setHeadingAlignLeft(AsciiTable.RIGHT)`
|
469 |
|
470 |
|
471 | #### instance.addRow(row, [...])
|
472 |
|
473 | Rows can be added using a single array argument, or the arguments if multiple
|
474 | args are used when calling the method.
|
475 |
|
476 | * `row` - array or arguments of column values
|
477 |
|
478 | Example:
|
479 |
|
480 | ```js
|
481 | var table = new AsciiTable()
|
482 |
|
483 | table
|
484 | .addRow(1, 'Bob', 52)
|
485 | .addRow([2, 'John', 34])
|
486 |
|
487 | console.log(table.render())
|
488 | ```
|
489 |
|
490 | ```
|
491 | .---------------.
|
492 | | 1 | Bob | 52 |
|
493 | | 2 | John | 34 |
|
494 | '---------------'
|
495 | ```
|
496 |
|
497 |
|
498 | #### instance.addRowMatrix(rows)
|
499 |
|
500 | Bulk `addRow` operation
|
501 |
|
502 | * `rows` - multidimentional array of rows
|
503 |
|
504 | Example:
|
505 |
|
506 | ```js
|
507 | table.addRowMatrix([
|
508 | [2, 'John', 34]
|
509 | , [3, 'Jim', 83]
|
510 | ])
|
511 |
|
512 | ```
|
513 |
|
514 |
|
515 | #### instance.setJustify(enabled)
|
516 |
|
517 | Justify all columns to be the same width
|
518 |
|
519 | * `enabled` - boolean for turning justify on or off, `undefined` considered true
|
520 |
|
521 | Example:
|
522 |
|
523 | ```js
|
524 | table
|
525 | .addRow('1', 'two', 'three')
|
526 | .setJustify()
|
527 |
|
528 | console.log(table.toString())
|
529 | ```
|
530 |
|
531 | ```
|
532 | .-----------------------.
|
533 | | 1 | two | three |
|
534 | '-----------------------'
|
535 | ```
|
536 |
|
537 |
|
538 | #### instance.toString()
|
539 |
|
540 | Render the instance as a string for output
|
541 |
|
542 | **Alias**: [`valueOf`, `render`]
|
543 |
|
544 |
|
545 | #### instance.toJSON()
|
546 |
|
547 | Return the JSON representation of the table, this also allows us to call
|
548 | `JSON.stringify` on the instance.
|
549 |
|
550 | Example:
|
551 |
|
552 | ```js
|
553 | var table = new AsciiTable('Title')
|
554 |
|
555 | table
|
556 | .setHeading('id', 'name')
|
557 | .addRow(1, 'Bob')
|
558 | .addRow(2, 'Steve')
|
559 |
|
560 | console.log(table.toJSON())
|
561 | console.log(JSON.stringify(table))
|
562 | ```
|
563 |
|
564 | ```js
|
565 | {
|
566 | title: 'Title'
|
567 | , heading: [ 'id', 'name' ]
|
568 | , rows: [
|
569 | [ 1, 'Bob' ]
|
570 | , [ 2, 'Steve' ]
|
571 | ]
|
572 | }
|
573 | ```
|
574 |
|
575 | ```
|
576 | {"title":"Title","heading":["id","name"],"rows":[[1,"Bob"],[2,"Steve"]]}
|
577 | ```
|
578 |
|
579 |
|
580 | #### instance.fromJSON(json)
|
581 |
|
582 | Populate the table from json, should match the `toJSON` output above.
|
583 |
|
584 | **Alias**: [`parse`]
|
585 |
|
586 | Example:
|
587 |
|
588 | ```js
|
589 | var table = new AsciiTable().fromJSON({
|
590 | title: 'Title'
|
591 | , heading: [ 'id', 'name' ]
|
592 | , rows: [
|
593 | [ 1, 'Bob' ]
|
594 | , [ 2, 'Steve' ]
|
595 | ]
|
596 | })
|
597 | ```
|
598 |
|
599 |
|
600 | #### instance.clear()
|
601 |
|
602 | Clear / reset all table data
|
603 |
|
604 | **Alias**: [`reset`]
|
605 |
|
606 |
|
607 | #### instance.clearRows()
|
608 |
|
609 | Reset all row data, maintains title and headings.
|
610 |
|
611 |
|
612 |
|
613 | Install
|
614 | -------
|
615 |
|
616 | With [npm](https://npmjs.org)
|
617 |
|
618 | ```
|
619 | npm install ascii-table
|
620 | ```
|
621 |
|
622 |
|
623 | License
|
624 | -------
|
625 |
|
626 | (The MIT License)
|
627 |
|
628 | Copyright (c) 2013 Beau Sorensen
|
629 |
|
630 | Permission is hereby granted, free of charge, to any person obtaining
|
631 | a copy of this software and associated documentation files (the
|
632 | 'Software'), to deal in the Software without restriction, including
|
633 | without limitation the rights to use, copy, modify, merge, publish,
|
634 | distribute, sublicense, and/or sell copies of the Software, and to
|
635 | permit persons to whom the Software is furnished to do so, subject to
|
636 | the following conditions:
|
637 |
|
638 | The above copyright notice and this permission notice shall be
|
639 | included in all copies or substantial portions of the Software.
|
640 |
|
641 | THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
|
642 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
643 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
644 | IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
|
645 | CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
|
646 | TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
|
647 | SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
\ | No newline at end of file |