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.

Name	Description	Default
stream	writable output stream.	process.stdout
width	the width of your table, use "0" for auto.	undefined
justify	when true justify columns to widest width.	true
gutter	the width between columns.	2
shift	when true trailing space against boundary trimmed.	false
padding	global column padding settings.	[0, 0, 0, 0]
border	border to use - single, double, round, singleDouble, doubleSingle, classic.	undefined
borderColor	red, green, blue, cyan, yellow, magenta, black, gray, redBright, greenBright, blueBright, cyanBright, yellowBright, magentaBright	undefined
stringLength	method 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.

Arguments	text: any | ITablurColumn | any[] | ITablurColumn[], width?: number | TablurAlign | ITablurColumnGlobal, align?: TablurPadding | TablurAlign, padding?: TablurPadding
Returns	Tablur

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.

Arguments	text: string | ITablurColumn, align?: TablurPadding | TablurAlign, padding?: TablurPadding
Returns	Tablur

repeat

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

Arguments	text: string | ITablurColumn, align?: TablurPadding | TablurAlign, padding?: TablurPadding
Returns	Tablur

break

Adds an empty break row to the table.

Arguments	none
Returns	Tablur

toString

Renders the table and returns string representation.

Arguments	none
Returns	string

render

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

Arguments	(wrap?: boolean)
Returns	Tablur

clear

Clears the current rows but maintains options.

Arguments	none
Returns	Tablur

reset

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

Arguments	(options?: ITablerOptions, debug?: boolean)
Returns	Tablur

Docs

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

Change

See CHANGE.md

License

See LICENSE.md