README.md
1# cliui
2
3[](https://travis-ci.org/yargs/cliui)
4[](https://coveralls.io/r/yargs/cliui?branch=)
5[](https://www.npmjs.com/package/cliui)
6[](https://github.com/conventional-changelog/standard-version)
7
8easily create complex multi-column command-line-interfaces.
9
10## Example
11
12```js
13var ui = require('cliui')()
14
15ui.div('Usage: $0 [command] [options]')
16
17ui.div({
18 text: 'Options:',
19 padding: [2, 0, 2, 0]
20})
21
22ui.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
40console.log(ui.toString())
41```
42
43<img width="500" src="screenshot.png">
44
45## Layout DSL
46
47cliui exposes a simple layout DSL:
48
49If you create a single `ui.div`, passing a string rather than an
50object:
51
52* `\n`: characters will be interpreted as new rows.
53* `\t`: characters will be interpreted as new columns.
54* `\s`: characters will be interpreted as padding.
55
56**as an example...**
57
58```js
59var ui = require('./')({
60 width: 60
61})
62
63ui.div(
64 'Usage: node ./bin/foo.js\n' +
65 ' <regex>\t provide a regex\n' +
66 ' <glob>\t provide a glob\t [required]'
67)
68
69console.log(ui.toString())
70```
71
72**will output:**
73
74```shell
75Usage: node ./bin/foo.js
76 <regex> provide a regex
77 <glob> provide a glob [required]
78```
79
80## Methods
81
82```js
83cliui = require('cliui')
84```
85
86### cliui({width: integer})
87
88Specify the maximum width of the UI being generated.
89If 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`.
90
91### cliui({wrap: boolean})
92
93Enable or disable the wrapping of text in a column.
94
95### cliui.div(column, column, column)
96
97Create a row with any number of columns, a column
98can either be a string, or an object with the following
99options:
100
101* **text:** some text to place in the column.
102* **width:** the width of a column.
103* **align:** alignment, `right` or `center`.
104* **padding:** `[top, right, bottom, left]`.
105* **border:** should a border be placed around the div?
106
107### cliui.span(column, column, column)
108
109Similar to `div`, except the next row will be appended without
110a new line being created.
111
112### cliui.resetOutput()
113
114Resets the UI elements of the current cliui instance, maintaining the values
115set for `width` and `wrap`.
116
){kind=link}
){kind=link}
){kind=link}
){kind=link}
