1 | # cliui
|
2 |
|
3 | ![ci](https://github.com/yargs/cliui/workflows/ci/badge.svg)
|
4 | [![NPM version](https://img.shields.io/npm/v/cliui.svg)](https://www.npmjs.com/package/cliui)
|
5 | [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org)
|
6 | ![nycrc config on GitHub](https://img.shields.io/nycrc/yargs/cliui)
|
7 |
|
8 | easily create complex multi-column command-line-interfaces.
|
9 |
|
10 | ## Example
|
11 |
|
12 | ```js
|
13 | const ui = require('cliui')()
|
14 |
|
15 | ui.div('Usage: $0 [command] [options]')
|
16 |
|
17 | ui.div({
|
18 | text: 'Options:',
|
19 | padding: [2, 0, 1, 0]
|
20 | })
|
21 |
|
22 | ui.div(
|
23 | {
|
24 | text: "-f, --file",
|
25 | width: 20,
|
26 | padding: [0, 4, 0, 4]
|
27 | },
|
28 | {
|
29 | text: "the file to load." +
|
30 | chalk.green("(if this description is long it wraps).")
|
31 | ,
|
32 | width: 20
|
33 | },
|
34 | {
|
35 | text: chalk.red("[required]"),
|
36 | align: 'right'
|
37 | }
|
38 | )
|
39 |
|
40 | console.log(ui.toString())
|
41 | ```
|
42 |
|
43 | ## Deno/ESM Support
|
44 |
|
45 | As of `v7` `cliui` supports [Deno](https://github.com/denoland/deno) and
|
46 | [ESM](https://nodejs.org/api/esm.html#esm_ecmascript_modules):
|
47 |
|
48 | ```typescript
|
49 | import cliui from "https://deno.land/x/cliui/deno.ts";
|
50 |
|
51 | const ui = cliui({})
|
52 |
|
53 | ui.div('Usage: $0 [command] [options]')
|
54 |
|
55 | ui.div({
|
56 | text: 'Options:',
|
57 | padding: [2, 0, 1, 0]
|
58 | })
|
59 |
|
60 | ui.div({
|
61 | text: "-f, --file",
|
62 | width: 20,
|
63 | padding: [0, 4, 0, 4]
|
64 | })
|
65 |
|
66 | console.log(ui.toString())
|
67 | ```
|
68 |
|
69 | <img width="500" src="screenshot.png">
|
70 |
|
71 | ## Layout DSL
|
72 |
|
73 | cliui exposes a simple layout DSL:
|
74 |
|
75 | If you create a single `ui.div`, passing a string rather than an
|
76 | object:
|
77 |
|
78 | * `\n`: characters will be interpreted as new rows.
|
79 | * `\t`: characters will be interpreted as new columns.
|
80 | * `\s`: characters will be interpreted as padding.
|
81 |
|
82 | **as an example...**
|
83 |
|
84 | ```js
|
85 | var ui = require('./')({
|
86 | width: 60
|
87 | })
|
88 |
|
89 | ui.div(
|
90 | 'Usage: node ./bin/foo.js\n' +
|
91 | ' <regex>\t provide a regex\n' +
|
92 | ' <glob>\t provide a glob\t [required]'
|
93 | )
|
94 |
|
95 | console.log(ui.toString())
|
96 | ```
|
97 |
|
98 | **will output:**
|
99 |
|
100 | ```shell
|
101 | Usage: node ./bin/foo.js
|
102 | <regex> provide a regex
|
103 | <glob> provide a glob [required]
|
104 | ```
|
105 |
|
106 | ## Methods
|
107 |
|
108 | ```js
|
109 | cliui = require('cliui')
|
110 | ```
|
111 |
|
112 | ### cliui({width: integer})
|
113 |
|
114 | Specify the maximum width of the UI being generated.
|
115 | If no width is provided, cliui will try to get the current window's width and use it, and if that doesn't work, width will be set to `80`.
|
116 |
|
117 | ### cliui({wrap: boolean})
|
118 |
|
119 | Enable or disable the wrapping of text in a column.
|
120 |
|
121 | ### cliui.div(column, column, column)
|
122 |
|
123 | Create a row with any number of columns, a column
|
124 | can either be a string, or an object with the following
|
125 | options:
|
126 |
|
127 | * **text:** some text to place in the column.
|
128 | * **width:** the width of a column.
|
129 | * **align:** alignment, `right` or `center`.
|
130 | * **padding:** `[top, right, bottom, left]`.
|
131 | * **border:** should a border be placed around the div?
|
132 |
|
133 | ### cliui.span(column, column, column)
|
134 |
|
135 | Similar to `div`, except the next row will be appended without
|
136 | a new line being created.
|
137 |
|
138 | ### cliui.resetOutput()
|
139 |
|
140 | Resets the UI elements of the current cliui instance, maintaining the values
|
141 | set for `width` and `wrap`.
|