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