.config/coc/extensions/node_modules/coc-prettier/node_modules/stylelint/node_modules/table/README.md

   1 <a name="table"></a>
   2 # Table
   3
   4 [![Travis build status](http://img.shields.io/travis/gajus/table/master.svg?style=flat)](https://travis-ci.org/gajus/table)
   5 [![NPM version](http://img.shields.io/npm/v/table.svg?style=flat)](https://www.npmjs.com/package/table)
   6 [![js-canonical-style](https://img.shields.io/badge/code%20style-canonical-brightgreen.svg?style=flat)](https://github.com/gajus/canonical)
   7
   8 * [Table](#table)
   9     * [Features](#table-features)
  10     * [Usage](#table-usage)
  11         * [Cell Content Alignment](#table-usage-cell-content-alignment)
  12         * [Column Width](#table-usage-column-width)
  13         * [Custom Border](#table-usage-custom-border)
  14         * [Draw Horizontal Line](#table-usage-draw-horizontal-line)
  15         * [Padding Cell Content](#table-usage-padding-cell-content)
  16         * [Predefined Border Templates](#table-usage-predefined-border-templates)
  17         * [Streaming](#table-usage-streaming)
  18         * [Text Truncation](#table-usage-text-truncation)
  19         * [Text Wrapping](#table-usage-text-wrapping)
  20
  21
  22 Produces a string that represents array data in a text table.
  23
  24 ![Demo of table displaying a list of missions to the Moon.](./.README/demo.png)
  25
  26 <a name="table-features"></a>
  27 ## Features
  28
  29 * Works with strings containing [fullwidth](https://en.wikipedia.org/wiki/Halfwidth_and_fullwidth_forms) characters.
  30 * Works with strings containing [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code).
  31 * Configurable border characters.
  32 * Configurable content alignment per column.
  33 * Configurable content padding per column.
  34 * Configurable column width.
  35 * Text wrapping.
  36
  37 <a name="table-usage"></a>
  38 ## Usage
  39
  40 Table data is described using an array (rows) of array (cells).
  41
  42 ```js
  43 import {
  44   table
  45 } from 'table';
  46
  47 // Using commonjs?
  48 // const {table} = require('table');
  49
  50 let data,
  51     output;
  52
  53 data = [
  54     ['0A', '0B', '0C'],
  55     ['1A', '1B', '1C'],
  56     ['2A', '2B', '2C']
  57 ];
  58
  59 /**
  60  * @typedef {string} table~cell
  61  */
  62
  63 /**
  64  * @typedef {table~cell[]} table~row
  65  */
  66
  67 /**
  68  * @typedef {Object} table~columns
  69  * @property {string} alignment Cell content alignment (enum: left, center, right) (default: left).
  70  * @property {number} width Column width (default: auto).
  71  * @property {number} truncate Number of characters are which the content will be truncated (default: Infinity).
  72  * @property {number} paddingLeft Cell content padding width left (default: 1).
  73  * @property {number} paddingRight Cell content padding width right (default: 1).
  74  */
  75
  76 /**
  77  * @typedef {Object} table~border
  78  * @property {string} topBody
  79  * @property {string} topJoin
  80  * @property {string} topLeft
  81  * @property {string} topRight
  82  * @property {string} bottomBody
  83  * @property {string} bottomJoin
  84  * @property {string} bottomLeft
  85  * @property {string} bottomRight
  86  * @property {string} bodyLeft
  87  * @property {string} bodyRight
  88  * @property {string} bodyJoin
  89  * @property {string} joinBody
  90  * @property {string} joinLeft
  91  * @property {string} joinRight
  92  * @property {string} joinJoin
  93  */
  94
  95 /**
  96  * Used to dynamically tell table whether to draw a line separating rows or not.
  97  * The default behavior is to always return true.
  98  *
  99  * @typedef {function} drawJoin
 100  * @param {number} index
 101  * @param {number} size
 102  * @return {boolean}
 103  */
 104
 105 /**
 106  * @typedef {Object} table~config
 107  * @property {table~border} border
 108  * @property {table~columns[]} columns Column specific configuration.
 109  * @property {table~columns} columnDefault Default values for all columns. Column specific settings overwrite the default values.
 110  * @property {table~drawJoin} drawHorizontalLine
 111  */
 112
 113 /**
 114  * Generates a text table.
 115  *
 116  * @param {table~row[]} rows
 117  * @param {table~config} config
 118  * @return {String}
 119  */
 120 output = table(data);
 121
 122 console.log(output);
 123 ```
 124
 125 ```
 126 ╔════╤════╤════╗
 127 ║ 0A │ 0B │ 0C ║
 128 ╟────┼────┼────╢
 129 ║ 1A │ 1B │ 1C ║
 130 ╟────┼────┼────╢
 131 ║ 2A │ 2B │ 2C ║
 132 ╚════╧════╧════╝
 133 ```
 134
 135
 136 <a name="table-usage-cell-content-alignment"></a>
 137 ### Cell Content Alignment
 138
 139 `{string} config.columns[{number}].alignment` property controls content horizontal alignment within a cell.
 140
 141 Valid values are: "left", "right" and "center".
 142
 143 ```js
 144 let config,
 145     data,
 146     output;
 147
 148 data = [
 149     ['0A', '0B', '0C'],
 150     ['1A', '1B', '1C'],
 151     ['2A', '2B', '2C']
 152 ];
 153
 154 config = {
 155     columns: {
 156         0: {
 157             alignment: 'left',
 158             minWidth: 10
 159         },
 160         1: {
 161             alignment: 'center',
 162             minWidth: 10
 163         },
 164         2: {
 165             alignment: 'right',
 166             minWidth: 10
 167         }
 168     }
 169 };
 170
 171 output = table(data, config);
 172
 173 console.log(output);
 174 ```
 175
 176 ```
 177 ╔════════════╤════════════╤════════════╗
 178 ║ 0A         │     0B     │         0C ║
 179 ╟────────────┼────────────┼────────────╢
 180 ║ 1A         │     1B     │         1C ║
 181 ╟────────────┼────────────┼────────────╢
 182 ║ 2A         │     2B     │         2C ║
 183 ╚════════════╧════════════╧════════════╝
 184 ```
 185
 186 <a name="table-usage-column-width"></a>
 187 ### Column Width
 188
 189 `{number} config.columns[{number}].width` property restricts column width to a fixed width.
 190
 191 ```js
 192 let data,
 193     output,
 194     options;
 195
 196 data = [
 197     ['0A', '0B', '0C'],
 198     ['1A', '1B', '1C'],
 199     ['2A', '2B', '2C']
 200 ];
 201
 202 options = {
 203     columns: {
 204         1: {
 205             width: 10
 206         }
 207     }
 208 };
 209
 210 output = table(data, options);
 211
 212 console.log(output);
 213 ```
 214
 215 ```
 216 ╔════╤════════════╤════╗
 217 ║ 0A │ 0B         │ 0C ║
 218 ╟────┼────────────┼────╢
 219 ║ 1A │ 1B         │ 1C ║
 220 ╟────┼────────────┼────╢
 221 ║ 2A │ 2B         │ 2C ║
 222 ╚════╧════════════╧════╝
 223 ```
 224
 225 <a name="table-usage-custom-border"></a>
 226 ### Custom Border
 227
 228 `{object} config.border` property describes characters used to draw the table border.
 229
 230 ```js
 231 let config,
 232     data,
 233     output;
 234
 235 data = [
 236     ['0A', '0B', '0C'],
 237     ['1A', '1B', '1C'],
 238     ['2A', '2B', '2C']
 239 ];
 240
 241 config = {
 242     border: {
 243         topBody: `─`,
 244         topJoin: `┬`,
 245         topLeft: `┌`,
 246         topRight: `┐`,
 247
 248         bottomBody: `─`,
 249         bottomJoin: `┴`,
 250         bottomLeft: `└`,
 251         bottomRight: `┘`,
 252
 253         bodyLeft: `│`,
 254         bodyRight: `│`,
 255         bodyJoin: `│`,
 256
 257         joinBody: `─`,
 258         joinLeft: `├`,
 259         joinRight: `┤`,
 260         joinJoin: `┼`
 261     }
 262 };
 263
 264 output = table(data, config);
 265
 266 console.log(output);
 267 ```
 268
 269 ```
 270 ┌────┬────┬────┐
 271 │ 0A │ 0B │ 0C │
 272 ├────┼────┼────┤
 273 │ 1A │ 1B │ 1C │
 274 ├────┼────┼────┤
 275 │ 2A │ 2B │ 2C │
 276 └────┴────┴────┘
 277 ```
 278
 279 <a name="table-usage-draw-horizontal-line"></a>
 280 ### Draw Horizontal Line
 281
 282 `{function} config.drawHorizontalLine` property is a function that is called for every non-content row in the table. The result of the function `{boolean}` determines whether a row is drawn.
 283
 284 ```js
 285 let data,
 286     output,
 287     options;
 288
 289 data = [
 290     ['0A', '0B', '0C'],
 291     ['1A', '1B', '1C'],
 292     ['2A', '2B', '2C'],
 293     ['3A', '3B', '3C'],
 294     ['4A', '4B', '4C']
 295 ];
 296
 297 options = {
 298     /**
 299      * @typedef {function} drawJoin
 300      * @param {number} index
 301      * @param {number} size
 302      * @return {boolean}
 303      */
 304     drawHorizontalLine: (index, size) => {
 305         return index === 0 || index === 1 || index === size - 1 || index === size;
 306     }
 307 };
 308
 309 output = table(data, options);
 310
 311 console.log(output);
 312 ```
 313
 314 ```
 315 ╔════╤════╤════╗
 316 ║ 0A │ 0B │ 0C ║
 317 ╟────┼────┼────╢
 318 ║ 1A │ 1B │ 1C ║
 319 ║ 2A │ 2B │ 2C ║
 320 ║ 3A │ 3B │ 3C ║
 321 ╟────┼────┼────╢
 322 ║ 4A │ 4B │ 4C ║
 323 ╚════╧════╧════╝
 324 ```
 325
 326 <a name="table-usage-padding-cell-content"></a>
 327 ### Padding Cell Content
 328
 329 `{number} config.columns[{number}].paddingLeft` and `{number} config.columns[{number}].paddingRight` properties control content padding within a cell. Property value represents a number of whitespaces used to pad the content.
 330
 331 ```js
 332 let config,
 333     data,
 334     output;
 335
 336 data = [
 337     ['0A', 'AABBCC', '0C'],
 338     ['1A', '1B', '1C'],
 339     ['2A', '2B', '2C']
 340 ];
 341
 342 config = {
 343     columns: {
 344         0: {
 345             paddingLeft: 3
 346         },
 347         1: {
 348             width: 2,
 349             paddingRight: 3
 350         }
 351     }
 352 };
 353
 354 output = table(data, config);
 355
 356 console.log(output);
 357 ```
 358
 359 ```
 360 ╔══════╤══════╤════╗
 361 ║   0A │ AA   │ 0C ║
 362 ║      │ BB   │    ║
 363 ║      │ CC   │    ║
 364 ╟──────┼──────┼────╢
 365 ║   1A │ 1B   │ 1C ║
 366 ╟──────┼──────┼────╢
 367 ║   2A │ 2B   │ 2C ║
 368 ╚══════╧══════╧════╝
 369 ```
 370
 371 <a name="table-usage-predefined-border-templates"></a>
 372 ### Predefined Border Templates
 373
 374 You can load one of the predefined border templates using `getBorderCharacters` function.
 375
 376 ```js
 377 import {
 378     table,
 379     getBorderCharacters
 380 } from 'table';
 381
 382 let config,
 383     data;
 384
 385 data = [
 386     ['0A', '0B', '0C'],
 387     ['1A', '1B', '1C'],
 388     ['2A', '2B', '2C']
 389 ];
 390
 391 config = {
 392     border: getBorderCharacters(`name of the template`)
 393 };
 394
 395 table(data, config);
 396 ```
 397
 398 ```
 399 # honeywell
 400
 401 ╔════╤════╤════╗
 402 ║ 0A │ 0B │ 0C ║
 403 ╟────┼────┼────╢
 404 ║ 1A │ 1B │ 1C ║
 405 ╟────┼────┼────╢
 406 ║ 2A │ 2B │ 2C ║
 407 ╚════╧════╧════╝
 408
 409 # norc
 410
 411 ┌────┬────┬────┐
 412 │ 0A │ 0B │ 0C │
 413 ├────┼────┼────┤
 414 │ 1A │ 1B │ 1C │
 415 ├────┼────┼────┤
 416 │ 2A │ 2B │ 2C │
 417 └────┴────┴────┘
 418
 419 # ramac (ASCII; for use in terminals that do not support Unicode characters)
 420
 421 +----+----+----+
 422 | 0A | 0B | 0C |
 423 |----|----|----|
 424 | 1A | 1B | 1C |
 425 |----|----|----|
 426 | 2A | 2B | 2C |
 427 +----+----+----+
 428
 429 # void (no borders; see "bordless table" section of the documentation)
 430
 431  0A  0B  0C
 432
 433  1A  1B  1C
 434
 435  2A  2B  2C
 436
 437 ```
 438
 439 Raise [an issue](https://github.com/gajus/table/issues) if you'd like to contribute a new border template.
 440
 441 <a name="table-usage-predefined-border-templates-borderless-table"></a>
 442 #### Borderless Table
 443
 444 Simply using "void" border character template creates a table with a lot of unnecessary spacing.
 445
 446 To create a more plesant to the eye table, reset the padding and remove the joining rows, e.g.
 447
 448 ```js
 449 let output;
 450
 451 output = table(data, {
 452     border: getBorderCharacters(`void`),
 453     columnDefault: {
 454         paddingLeft: 0,
 455         paddingRight: 1
 456     },
 457     drawHorizontalLine: () => {
 458         return false
 459     }
 460 });
 461
 462 console.log(output);
 463 ```
 464
 465 ```
 466 0A 0B 0C
 467 1A 1B 1C
 468 2A 2B 2C
 469 ```
 470
 471 <a name="table-usage-streaming"></a>
 472 ### Streaming
 473
 474 `table` package exports `createStream` function used to draw a table and append rows.
 475
 476 `createStream` requires `{number} columnDefault.width` and `{number} columnCount` configuration properties.
 477
 478 ```js
 479 import {
 480     createStream
 481 } from 'table';
 482
 483 let config,
 484     stream;
 485
 486 config = {
 487     columnDefault: {
 488         width: 50
 489     },
 490     columnCount: 1
 491 };
 492
 493 stream = createStream(config);
 494
 495 setInterval(() => {
 496     stream.write([new Date()]);
 497 }, 500);
 498 ```
 499
 500 ![Streaming current date.](./.README/streaming.gif)
 501
 502 `table` package uses ANSI escape codes to overwrite the output of the last line when a new row is printed.
 503
 504 The underlying implementation is explained in this [Stack Overflow answer](http://stackoverflow.com/a/32938658/368691).
 505
 506 Streaming supports all of the configuration properties and functionality of a static table (such as auto text wrapping, alignment and padding), e.g.
 507
 508 ```js
 509 import {
 510     createStream
 511 } from 'table';
 512
 513 import _ from 'lodash';
 514
 515 let config,
 516     stream,
 517     i;
 518
 519 config = {
 520     columnDefault: {
 521         width: 50
 522     },
 523     columnCount: 3,
 524     columns: {
 525         0: {
 526             width: 10,
 527             alignment: 'right'
 528         },
 529         1: {
 530             alignment: 'center',
 531         },
 532         2: {
 533             width: 10
 534         }
 535     }
 536 };
 537
 538 stream = createStream(config);
 539
 540 i = 0;
 541
 542 setInterval(() => {
 543     let random;
 544
 545     random = _.sample('abcdefghijklmnopqrstuvwxyz', _.random(1, 30)).join('');
 546
 547     stream.write([i++, new Date(), random]);
 548 }, 500);
 549 ```
 550
 551 ![Streaming random data.](./.README/streaming-random.gif)
 552 <a name="table-usage-text-truncation"></a>
 553 ### Text Truncation
 554
 555 To handle a content that overflows the container width, `table` package implements [text wrapping](#table-usage-text-wrapping). However, sometimes you may want to truncate content that is too long to be displayed in the table.
 556
 557 `{number} config.columns[{number}].truncate` property (default: `Infinity`) truncates the text at the specified length.
 558
 559 ```js
 560 let config,
 561     data,
 562     output;
 563
 564 data = [
 565     ['Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus pulvinar nibh sed mauris convallis dapibus. Nunc venenatis tempus nulla sit amet viverra.']
 566 ];
 567
 568 config = {
 569     columns: {
 570         0: {
 571             width: 20,
 572             truncate: 100
 573         }
 574     }
 575 };
 576
 577 output = table(data, config);
 578
 579 console.log(output);
 580 ```
 581
 582 ```
 583 ╔══════════════════════╗
 584 ║ Lorem ipsum dolor si ║
 585 ║ t amet, consectetur  ║
 586 ║ adipiscing elit. Pha ║
 587 ║ sellus pulvinar nibh ║
 588 ║ sed mauris conva...  ║
 589 ╚══════════════════════╝
 590 ```
 591
 592 <a name="table-usage-text-wrapping"></a>
 593 ### Text Wrapping
 594
 595 `table` package implements auto text wrapping, i.e. text that has width greater than the container width will be separated into multiple lines, e.g.
 596
 597 ```js
 598 let config,
 599     data,
 600     output;
 601
 602 data = [
 603     ['Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus pulvinar nibh sed mauris convallis dapibus. Nunc venenatis tempus nulla sit amet viverra.']
 604 ];
 605
 606 config = {
 607     columns: {
 608         0: {
 609             width: 20
 610         }
 611     }
 612 };
 613
 614 output = table(data, config);
 615
 616 console.log(output);
 617 ```
 618
 619 ```
 620 ╔══════════════════════╗
 621 ║ Lorem ipsum dolor si ║
 622 ║ t amet, consectetur  ║
 623 ║ adipiscing elit. Pha ║
 624 ║ sellus pulvinar nibh ║
 625 ║ sed mauris convallis ║
 626 ║ dapibus. Nunc venena ║
 627 ║ tis tempus nulla sit ║
 628 ║ amet viverra.        ║
 629 ╚══════════════════════╝
 630 ```
 631
 632 When `wrapWord` is `true` the text is broken at the nearest space or one of the special characters ("-", "_", "\", "/", ".", ",", ";"), e.g.
 633
 634 ```js
 635 let config,
 636     data,
 637     output;
 638
 639 data = [
 640     ['Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus pulvinar nibh sed mauris convallis dapibus. Nunc venenatis tempus nulla sit amet viverra.']
 641 ];
 642
 643 config = {
 644     columns: {
 645         0: {
 646             width: 20,
 647             wrapWord: true
 648         }
 649     }
 650 };
 651
 652 output = table(data, config);
 653
 654 console.log(output);
 655 ```
 656
 657 ```
 658 ╔══════════════════════╗
 659 ║ Lorem ipsum dolor    ║
 660 ║ sit amet,            ║
 661 ║ consectetur          ║
 662 ║ adipiscing elit.     ║
 663 ║ Phasellus pulvinar   ║
 664 ║ nibh sed mauris      ║
 665 ║ convallis dapibus.   ║
 666 ║ Nunc venenatis       ║
 667 ║ tempus nulla sit     ║
 668 ║ amet viverra.        ║
 669 ╚══════════════════════╝
 670 ```
 671