Options
All
  • Public
  • Public/Protected
  • All
Menu

Tablur

Tablur pronounced "tay-bler" is a simple cli table util. It is similar to cliui with a few extra helpers. The main advantage to Tablur is that it's quick and it's written in Typescript. Typings for existing table utils isn't that great and in part the reason for this release.

Install

$ npm install tablur

Usage

Tablur is similar to other CLI table utilities. You can configure using strings or objects for more control. Tablur also has a handy shorthand syntax that's a little easier to look at than using multiple objects for columns.

const table = new Tablur();

table
  .section('Tablur CLI Tables', 'center')

  .break()

  .row([
    { text: 'app run --dev' },
    { text: 'Runs the app.' },
    { text: 'Alias: r', align: 'right' }])

  .row(
    [{ text: 'app create <name>' },
    { text: 'Creates an app.' },
    { text: 'Alias: c', align: 'right' }])

  .break()

  .section('Options:\n', 'left')

  .row(
    [{ text: ' <name>' },
    { text: 'App name to create.' },
    { text: '[string] [required]', align: 'right' }])

  .row(
    [{ text: ' --dev, -d' },
    { text: 'Runs in dev mode.' },
    { text: '[boolean]', align: 'right' }])

  .break()

  .section({ text: '© 2018 Tablur', align: 'center' });


// Render to string and return.
const result = table.toString();

// OR

// Output to specified writable stream.
table.render(true);

Shorthand

Tablur has handy shorthand that is a little easier to look at than a bunch of objects. Using column configuration objects still gives the best control but using shorthand works well for simpler solutions and is a bit quicker to write.

Here's the order

text|width|align|padding

OR

text|align|padding

table.row('Some Title|center');

// use : for padding order is top, right, bottom, left
table.row('Username|30|left|0:1:0:1', 'Email|50');

Debug

What to know what's going on with Tablur's output? Create table passing in "true" to show padding, alignment and shifting. This was used during development but found it so handy just left it in. If something isn't responding as you expect give it a try, it will do one of two things. 1) Help you adjust your column or 2) show you a bug we need to fix!

const table = new Tablur(true);

// OR

const table = new Tablur({ /* options here */ }, true);

Characters

A - Represents alignment padding. P - Represents padding. S - Represents shifted text at boundary. > - Represents indent spaces.

╭──────────────────────────────────────────────────────────╮
│Root Path:AAAAAAAA │ .myappAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA│
│──────────────────────────────────────────────────────────│
│Import Path:AAAAAA │ dist/myapp.jsAAAAAAAAAAAAAAAAAAAAAAAA│
│──────────────────────────────────────────────────────────│
│Source Path:AAAAAA │ src/myapp.tsAAAAAAAAAAAAAAAAAAAAAAAAA│
│──────────────────────────────────────────────────────────│
│Output Path:AAAAAA │ srcAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA│
│──────────────────────────────────────────────────────────│
│Template:AAAAAAAAA │ my.template.jsAAAAAAAAAAAAAAAAAAAAAAA│
╰──────────────────────────────────────────────────────────╯

Options

A quick note on "padding". The vertical padding is not 1 to 1. This is because it gets pretty huge when you do that. Hence verticle padding is divided by 2. This looks a little better when scaling padding. Just keep that in mind.

NameDescriptionDefault
streamwritable output stream.process.stdout
widththe width of your table, use "0" for auto.undefined
justifywhen true justify columns to widest width.true
gutterthe width between columns.2
shiftwhen true trailing space against boundary trimmed.false
paddingglobal column padding settings.[0, 0, 0, 0]
borderborder to use - single, double, round, singleDouble, doubleSingle, classic.undefined
borderColorred, green, blue, cyan, yellow, magenta, black, gray, redBright, greenBright, blueBright, cyanBright, yellowBright, magentaBrightundefined
stringLengthmethod used to calculate string length.2

API

The Tablur API is very simple. You can add columns as strings with shorthand or as objects.

row

Adds a new row to the table. See Docs for more on method arguments.

Argumentstext: any | ITablurColumn | any[] | ITablurColumn[], width?: number | TablurAlign | ITablurColumnGlobal, align?: TablurPadding | TablurAlign, padding?: TablurPadding
ReturnsTablur

section

Creates a section header. Similar to row but with some opinions most commonly used for this purpose. See Docs for more on method arguments.

Argumentstext: string | ITablurColumn, align?: TablurPadding | TablurAlign, padding?: TablurPadding
ReturnsTablur

repeat

Repeats a string in a row. For example if you wanted to have a row with *. See Docs for more on method arguments.

Argumentstext: string | ITablurColumn, align?: TablurPadding | TablurAlign, padding?: TablurPadding
ReturnsTablur

break

Adds an empty break row to the table.

Argumentsnone
ReturnsTablur

toString

Renders the table and returns string representation.

Argumentsnone
Returnsstring

render

Renders the table and writes to output stream. Pass true to wrap output in new lines for spacing.

Arguments(wrap?: boolean)
ReturnsTablur

clear

Clears the current rows but maintains options.

Argumentsnone
ReturnsTablur

reset

Clears rows and resets all options, optionally can provide new options and debug mode.

Arguments(options?: ITablerOptions, debug?: boolean)
ReturnsTablur

Docs

See https://blujedis.github.io/tablur/

Change

See CHANGE.md

License

See LICENSE.md

Generated using TypeDoc