www.aleph1.co.uk Git - yaffs-website/blob - node_modules/cliui/README.md

   1 # cliui
   2
   3 [![Build Status](https://travis-ci.org/yargs/cliui.svg)](https://travis-ci.org/yargs/cliui)
   4 [![Coverage Status](https://coveralls.io/repos/yargs/cliui/badge.svg?branch=)](https://coveralls.io/r/yargs/cliui?branch=)
   5 [![NPM version](https://img.shields.io/npm/v/cliui.svg)](https://www.npmjs.com/package/cliui)
   6 [![Standard Version](https://img.shields.io/badge/release-standard%20version-brightgreen.svg)](https://github.com/conventional-changelog/standard-version)
   7
   8 easily create complex multi-column command-line-interfaces.
   9
  10 ## Example
  11
  12 ```js
  13 var ui = require('cliui')({
  14   width: 80
  15 })
  16
  17 ui.div('Usage: $0 [command] [options]')
  18
  19 ui.div({
  20   text: 'Options:',
  21   padding: [2, 0, 2, 0]
  22 })
  23
  24 ui.div(
  25   {
  26     text: "-f, --file",
  27     width: 20,
  28     padding: [0, 4, 0, 4]
  29   },
  30   {
  31     text: "the file to load." +
  32       chalk.green("(if this description is long it wraps).")
  33     ,
  34     width: 20
  35   },
  36   {
  37     text: chalk.red("[required]"),
  38     align: 'right'
  39   }
  40 )
  41
  42 console.log(ui.toString())
  43 ```
  44
  45 <img width="500" src="screenshot.png">
  46
  47 ## Layout DSL
  48
  49 cliui exposes a simple layout DSL:
  50
  51 If you create a single `ui.row`, passing a string rather than an
  52 object:
  53
  54 * `\n`: characters will be interpreted as new rows.
  55 * `\t`: characters will be interpreted as new columns.
  56 * `\s`: characters will be interpreted as padding.
  57
  58 **as an example...**
  59
  60 ```js
  61 var ui = require('./')({
  62   width: 60
  63 })
  64
  65 ui.div(
  66   'Usage: node ./bin/foo.js\n' +
  67   '  <regex>\t  provide a regex\n' +
  68   '  <glob>\t  provide a glob\t [required]'
  69 )
  70
  71 console.log(ui.toString())
  72 ```
  73
  74 **will output:**
  75
  76 ```shell
  77 Usage: node ./bin/foo.js
  78   <regex>  provide a regex
  79   <glob>   provide a glob          [required]
  80 ```
  81
  82 ## Methods
  83
  84 ```js
  85 cliui = require('cliui')
  86 ```
  87
  88 ### cliui({width: integer})
  89
  90 Specify the maximum width of the UI being generated.
  91
  92 ### cliui({wrap: boolean})
  93
  94 Enable or disable the wrapping of text in a column.
  95
  96 ### cliui.div(column, column, column)
  97
  98 Create a row with any number of columns, a column
  99 can either be a string, or an object with the following
 100 options:
 101
 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
 109 Similar to `div`, except the next row will be appended without
 110 a new line being created.