Cliffy ❯ Table
Fast and customizable table module to render unicode table’s on the command line
❯ 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)
- .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
- Cell
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` | 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` | 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.