Cliffy

Cliffy ❯ Table

Version Build status issues Deno version doc Discord License
Discord nest.land badge

Fast and customizable table module to render unicode table's on the command line

table

❯ Content§

❯ Install§

This module can be imported directly from the repo and from following registries.

Deno Registry

import { Table } from "https://deno.land/x/cliffy@<version>/table/mod.ts";

Nest Registry

import { Table } from "https://x.nest.land/cliffy@<version>/table/mod.ts";

Github

import { Table } from "https://raw.githubusercontent.com/c4spar/deno-cliffy/<version>/table/mod.ts";

❯ Usage§

Basic Usage§

To create a table you can simple create an instance of the Table class and pass the rows as arguments to the constructor. The example below will output a simple table with three rows and without any styles. The only default option is padding which is set to 1.

const table: Table = new Table(
  ["Baxter Herman", "Oct 1, 2020", "Harderwijk", "Slovenia"],
  ["Jescie Wolfe", "Dec 4, 2020", "Alto Hospicio", "Japan"],
  ["Allegra Cleveland", "Apr 16, 2020", "Avernas-le-Bauduin", "Samoa"],
  ["Aretha Gamble", "Feb 22, 2021", "Honolulu", "Georgia"],
);

console.log(table.toString());
$ deno run https://deno.land/x/cliffy/examples/table/basic_usage.ts

Using as Array§

Since the Table class is an Array, you can call all the methods of the array class like .from(), .sort(), .push(), .unshift() and friends.

const table: Table = Table.from([
  ["Baxter Herman", "Oct 1, 2020", "Harderwijk", "Slovenia"],
  ["Jescie Wolfe", "Dec 4, 2020", "Alto Hospicio", "Japan"],
  ["Allegra Cleveland", "Apr 16, 2020", "Avernas-le-Bauduin", "Samoa"],
]);

table.push(["Aretha Gamble", "Feb 22, 2021", "Honolulu", "Georgia"]);
table.sort();
table.render();
$ deno run https://deno.land/x/cliffy/examples/table/using_as_array.ts

Header and Body§

To define a table header you can use the .header() method. The header is not affected by any Array method like .sort() because it is stored as a separate property and not in the array stack. The .body() method adds an array of rows to the table and removes all existing rows.

new Table()
  .header(["Name", "Date", "City", "Country"])
  .body([
    ["Baxter Herman", "Oct 1, 2020", "Harderwijk", "Slovenia"],
    ["Jescie Wolfe", "Dec 4, 2020", "Alto Hospicio", "Japan"],
    ["Allegra Cleveland", "Apr 16, 2020", "Avernas-le-Bauduin", "Samoa"],
    ["Aretha Gamble", "Feb 22, 2021", "Honolulu", "Georgia"],
  ])
  .render();
$ deno run https://deno.land/x/cliffy/examples/table/header_and_body.ts

Table Options§

To customize the table, the table class provides a few chainable option methods. To see a list of all available options go to the Table API section.

new Table()
  .header(["Name", "Date", "City", "Country"])
  .body([
    ["Baxter Herman", "Oct 1, 2020", "Harderwijk", "Slovenia"],
    ["Jescie Wolfe", "Dec 4, 2020", "Alto Hospicio", "Japan"],
    ["Allegra Cleveland", "Apr 16, 2020", "Avernas-le-Bauduin", "Samoa"],
    ["Aretha Gamble", "Feb 22, 2021", "Honolulu", "Georgia"],
  ])
  .maxColWidth(10)
  .padding(1)
  .indent(2)
  .border(true)
  .render();
$ deno run https://deno.land/x/cliffy/examples/table/table_options.ts

Row's and Cell's§

It is also possible to customize single rows and cell. To do this you can use the Row and Cell class. The Row class is also an Array class like the Table class. To see a list of all available options go to the Row or Cell API section.

import {
  Cell,
  Row,
  Table,
} from "https://deno.land/x/cliffy@<version>/table/mod.ts";

new Table()
  .header(Row.from(["Name", "Date", "City", "Country"]).border(true))
  .body([
    [
      "Baxter Herman",
      Cell.from("Oct 1, 2020").border(true),
      "Row 1 Column 3",
      "Harderwijk",
      "Slovenia",
    ],
    new Row("Jescie Wolfe", "Dec 4, 2020", "Alto Hospicio", "Japan").border(
      true,
    ),
    ["Allegra Cleveland", "Apr 16, 2020", "Avernas-le-Bauduin", "Samoa"],
    ["Aretha Gamble", "Feb 22, 2021", "Honolulu", "Georgia"],
  ])
  .render();
$ deno run https://deno.land/x/cliffy/examples/table/rows_and_cells.ts

Colspan and Rowspan§

Colspan and rowspan allows a single table cell to span the width/height of more than one column and/or row.

Table.from([
  [
    Cell.from("Row 1 & 2 Column 1").rowSpan(2),
    "Row 1 Column 2",
    "Row 1 Column 3",
  ],
  [Cell.from("Row 2 Column 2 & 3").colSpan(2)],
  [
    Cell.from("Row 3 & 4 Column 1").rowSpan(2),
    "Row 3 Column 2",
    "Row 3 Column 3",
  ],
  [Cell.from("Row 4 Column 2 & 3").colSpan(2)],
  ["Row 5 Column 1", Cell.from("Row 5 & 6 Column 2 & 3").rowSpan(2).colSpan(2)],
  ["Row 6 Column 1"],
])
  .border(true)
  .render();
$ deno run https://deno.land/x/cliffy/examples/table/colspan_and_rowspan.ts

❯ API§

Table§

.header(row)§

Sets the table header row.

Argument Type Required Description
row IRow Yes Can be an Array of string's and Cell's

Return type: this

.body(rows)§

Adds an array of rows to the table and removes all existing rows.

Argument Type Required Description
rows Array<IRow> Yes Array of row's. A row can be an Array of string's and Cell's

Return type: this

.clone()§

Clones the table.

Return type: this

.toString()§

Generates the table string.

Return type: string

.render()§

Outputs the result of the .toString() method with Deno.stdout.writeSnyc().

Return type: this

.minColWidth(width,override)§

Set min column with.

Argument Type Required Description
width number | Array<number> Yes
override boolean No Set override to false to prevent overriding existing values.

Return type: this

.maxColWidth(width,override)§

Set max column with.

Argument Type Required Description
width number | Array<number> Yes
override boolean No Set override to false to prevent overriding existing values.

Return type: this

.indent(width,override)§

Indent the table output.

Argument Type Required Description
width number Yes Indent width.
override boolean No Set override to false to prevent overriding existing values.

Return type: this

.padding(padding,override)§

Set column padding. If border is enabled the padding will be applyed on the left and the right side of each cell.

Argument Type Required Description
padding number | number[] Yes
override boolean No Set override to false to prevent overriding existing values.

Return type: this

.border(enable,override)§

Enable table border. Doesn't override row and cell settings.

Argument Type Required Description
enable boolean Yes Enable or disable table border.
override boolean No Set override to false to prevent overriding existing values.

Return type: this

.align(direction,override)§

Align table content.

Argument Type Required Description
direction "left", "center" or "right" Yes Set alignment direction.
override boolean No Set override to false to prevent overriding existing values.

Return type: this

.chars(chars)§

Override default border characters. Doesn't override row and cell settings. To change the default border characters globally you can use the static Table.chars(chars) method.

Argument Type Required Description
chars IBorderOptions Yes An object with border characters.
override boolean No Set override to false to prevent overriding existing values.

Here is an example of the default border characters:

{
  top: "─",
  topMid: "┬",
  topLeft: "┌",
  topRight: "┐",
  bottom: "─",
  bottomMid: "┴",
  bottomLeft: "└",
  bottomRight: "┘",
  left: "│",
  leftMid: "├",
  mid: "─",
  midMid: "┼",
  right: "│",
  rightMid: "┤",
  middle: "│",
}

Return type: this

.getHeader()§

Returns the header row.

Return type: Row | undefined

.getBody()§

Returns all body rows.

Return type: IRow[]

.getMinColWidth()§

Get min columns width.

Return type: number | number[]

.getMaxColWidth()§

Get max columns width.

Return type: number | number[]

.getIndent()§

Get indent width.

Return type: number

.getPadding()§

Get padding.

Return type: number | number[]

.getBorder()§

Check if border is enabled on the table.

Return type: boolean

.getAlign()§

Get table alignment.

Return type: "left", "center" or "right"


Row§

.clone()§

Clones the row.

Return type: this

.border(enable,override)§

Enable row border. Override table settings but not cell settings.

Argument Type Required Description
enable boolean Yes Enable or disable table border.
override boolean No Set override to false to prevent overriding existing values.

Return type: this

.align(direction,override)§

Align row content.

Argument Type Required Description
direction "left", "center" or "right" Yes Set alignment direction.
override boolean No Set override to false to prevent overriding existing values.

Return type: this

.getBorder()§

Check if border is enabled on the row.

Return type: boolean

.getAlign()§

Get row alignment.

Return type: "left", "center" or "right"


Cell§

.clone()§

Clones the cell.

Return type: this

.border(enable,override)§

Enable cell border. Overrides table and row settings.

Argument Type Required Description
enable boolean Yes Enable or disable table border.
override boolean No Set override to false to prevent overriding existing values.

Return type: this

.align(direction,override)§

Align cell content.

Argument Type Required Description
direction "left", "center" or "right" Yes Set alignment direction.
override boolean No Set override to false to prevent overriding existing values.

Return type: this

.colSpan(span,override)§

Allows a single table cell to span the width of more than one cell or column. Can be combined with .rowSpan().

Argument Type Required Description
span number Yes Number of columns to span the cell.
override boolean No Set override to false to prevent overriding existing values.

Return type: this

.rowSpan(span,override)§

Allows a single table cell to span the height of more than one cell or row. Can be combined with .colSpan().

Argument Type Required Description
span number Yes Number of rows to span the cell.
override boolean No Set override to false to prevent overriding existing values.

Return type: this

.getBorder()§

Check if border is enabled on the cell.

Return type: boolean

.getAlign()§

Get cell alignment.

Return type: "left", "center" or "right"

.getColSpan()§

Get cell column span.

Return type: number

.getRowSpan()§

Get cell row span.

Return type: number

❯ Contributing§

Any kind of contribution is welcome! Please take a look at the contributing guidelines.

❯ License§

MIT