www.aleph1.co.uk Git - yaffs-website/blob - node_modules/meow/readme.md

   1 # meow [![Build Status](https://travis-ci.org/sindresorhus/meow.svg?branch=master)](https://travis-ci.org/sindresorhus/meow)
   2
   3 > CLI app helper
   4
   5 ![](meow.gif)
   6
   7
   8 ## Features
   9
  10 - Parses arguments using [minimist](https://github.com/substack/minimist)
  11 - Converts flags to [camelCase](https://github.com/sindresorhus/camelcase)
  12 - Outputs version when `--version`
  13 - Outputs description and supplied help text when `--help`
  14 - Makes unhandled rejected promises [fail loudly](https://github.com/sindresorhus/loud-rejection) instead of the default silent fail
  15 - Sets the process title to the binary name defined in package.json
  16
  17
  18 ## Install
  19
  20 ```
  21 $ npm install --save meow
  22 ```
  23
  24
  25 ## Usage
  26
  27 ```
  28 $ ./foo-app.js unicorns --rainbow-cake
  29 ```
  30
  31 ```js
  32 #!/usr/bin/env node
  33 'use strict';
  34 const meow = require('meow');
  35 const foo = require('./');
  36
  37 const cli = meow(`
  38         Usage
  39           $ foo <input>
  40
  41         Options
  42           -r, --rainbow  Include a rainbow
  43
  44         Examples
  45           $ foo unicorns --rainbow
  46           🌈 unicorns 🌈
  47 `, {
  48         alias: {
  49                 r: 'rainbow'
  50         }
  51 });
  52 /*
  53 {
  54         input: ['unicorns'],
  55         flags: {rainbow: true},
  56         ...
  57 }
  58 */
  59
  60 foo(cli.input[0], cli.flags);
  61 ```
  62
  63
  64 ## API
  65
  66 ### meow(options, [minimistOptions])
  67
  68 Returns an object with:
  69
  70 - `input` *(array)* - Non-flag arguments
  71 - `flags` *(object)* - Flags converted to camelCase
  72 - `pkg` *(object)* - The `package.json` object
  73 - `help` *(object)* - The help text used with `--help`
  74 - `showHelp([code=0])` *(function)* - Show the help text and exit with `code`
  75
  76 #### options
  77
  78 Type: `object`, `array`, `string`
  79
  80 Can either be a string/array that is the `help` or an options object.
  81
  82 ##### description
  83
  84 Type: `string`, `boolean`
  85 Default: The package.json `"description"` property
  86
  87 A description to show above the help text.
  88
  89 Set it to `false` to disable it altogether.
  90
  91 ##### help
  92
  93 Type: `string`, `boolean`
  94
  95 The help text you want shown.
  96
  97 The input is reindented and starting/ending newlines are trimmed which means you can use a [template literal](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/template_strings) without having to care about using the correct amount of indent.
  98
  99 <del>If it's an array each item will be a line.</del>
 100 *(Still supported, but you should use a template literal instead.)*
 101
 102 The description will be shown above your help text automatically.
 103
 104 Set it to `false` to disable it altogether.
 105
 106 ##### version
 107
 108 Type: `string`, `boolean`
 109 Default: The package.json `"version"` property
 110
 111 Set a custom version output.
 112
 113 Set it to `false` to disable it altogether.
 114
 115 ##### pkg
 116
 117 Type: `string`, `object`
 118 Default: Closest package.json upwards
 119
 120 Relative path to package.json or as an object.
 121
 122 ##### argv
 123
 124 Type: `array`
 125 Default: `process.argv.slice(2)`
 126
 127 Custom arguments object.
 128
 129 #### minimistOptions
 130
 131 Type: `object`
 132 Default: `{}`
 133
 134 Minimist [options](https://github.com/substack/minimist#var-argv--parseargsargs-opts).
 135
 136 Keys passed to the minimist `default` option are [decamelized](https://github.com/sindresorhus/decamelize), so you can for example pass in `fooBar: 'baz'` and have it be the default for the `--foo-bar` flag.
 137
 138
 139 ## Promises
 140
 141 Meow will make unhandled rejected promises [fail loudly](https://github.com/sindresorhus/loud-rejection) instead of the default silent fail. Meaning you don't have to manually `.catch()` promises used in your CLI.
 142
 143
 144 ## Tips
 145
 146 See [`chalk`](https://github.com/chalk/chalk) if you want to colorize the terminal output.
 147
 148 See [`get-stdin`](https://github.com/sindresorhus/get-stdin) if you want to accept input from stdin.
 149
 150 See [`update-notifier`](https://github.com/yeoman/update-notifier) if you want update notifications.
 151
 152 See [`configstore`](https://github.com/yeoman/configstore) if you need to persist some data.
 153
 154 [More useful CLI utilities.](https://github.com/sindresorhus/awesome-nodejs#command-line-utilities)
 155
 156
 157 ## License
 158
 159 MIT © [Sindre Sorhus](http://sindresorhus.com)