Cliffy ❯ Table

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

❯ Content

• Install
• Usage
  • Basic Usage
  • Using as Array
  • Header and Body
  • Table Options
  • Row’s and Cell’s
  • Colspan and Rowspan
• API
• Contributing
• License

❯ 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 Talbe 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)
  • .body(rows)
  • .clone()
  • .toString()
  • .render()
  • .minColWidth(width,override)
  • .maxColWidth(width,override)
  • .indent(width,override)
  • .padding(padding,override)
  • .border(enable,override)
  • .align(direction,override)
  • .chars(chars)
  • .getHeader()
  • .getBody()
  • .getMinColWidth()
  • .getMaxColWidth()
  • .getIndent()
  • .getPadding()
  • .getBorder()
  • .getAlign()
• Row
  • .clone()
  • .border(enable,override)
  • .align(direction,override)
  • .getBorder()
  • .getAlign()
• Cell
  • .clone()
  • .border(enable,override)`
  • .align(direction,override)
  • .colSpan(span,override)
  • .rowSpan(span,override)
  • .getBorder()
  • .getAlign()
  • .getColSpan()
  • .getRowSpan()

Table

.header(row)

Sets the table header row.

Return type: this

.body(rows)

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

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.

Return type: this

.maxColWidth(width,override)

Set max column with.

Return type: this

.indent(width,override)

Indent the table output.

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.

Return type: this

.border(enable,override)

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

Return type: this

.align(direction,override)

Align table content.

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.

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.

Return type: this

.align(direction,override)

Align row content.

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.

Return type: this

.align(direction,override)

Align cell content.

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().

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().

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