二、yargs用法 - yargs API

.command(cmd, desc, [builder], [handler])
.command(cmd, desc, [module])
.command(module)

 

定義應用暴露出來的命令
參數：cmd ，必須是一個字符串類型命令名稱，或者是一個數組，數組的類型是字符串，代表是命令的名稱或者命令的別名
參數: desc，用來描述命令是作什么用的， 如果設置 desc 的值為 false，則會創建一個隱藏的指令
可選參數: builder，這個是用來提示命令需要接收的參數

yargs
  .command('get', 'make a get HTTP request', {
    url: {
      alias: 'u',
      default: 'http://yargs.js.org/'
    }
  })
  .help()
  .argv

  可選參數：builder，也可以是一個方法，這個方法的參數是yargs的實例 
  yargs
  .command('get', 'make a get HTTP request', function (yargs) {
    return yargs.option('url', {
      alias: 'u',
      default: 'http://yargs.js.org/'
    })
  })
  .help()
  .argv

//  還可以傳另一個處理函數，這個函數會被調用並且傳入處理過的argv
yargs
  .command(
    'get',
    'make a get HTTP request',
    function (yargs) {
      return yargs.option('u', {
        alias: 'url',
        describe: 'the URL to make an HTTP request to'
      })
    },
    function (argv) {
      console.log(argv.url)
    }
  )
  .help()
  .argv

.completion([cmd], [description], [fn]);

這個用於命令行被全
cmd定義參與命令補全的命令。第一次使用會有提示，如果用的zsh，那么將提示中 .bashrc改成.zshrc，然后按照提示操作(切記將你的js文件設置(chmod u+x)為可執行文件，然后不規則操作)
description 描述命令的使用方法
fn 提供待補全的參數

如果實現的時候沒有攜帶參數，那么.completion()會讓補全命令輸出補全腳本

var argv = require('yargs')
  .completion('completion', function(current, argv) {
    // 'current' is the current command being completed.
    // 'argv' is the parsed arguments so far.
    // simply return an array of completions.
    return [
      'foo',
      'bar'
    ];
  })
  .argv;

  //還可以實現異步方法被全
  var argv = require('yargs')
  .completion('completion', function(current, argv, done) {
    setTimeout(function() {
      done([
        'apple',
        'banana'
      ]);
    }, 500);
  })
  .argv;

 //還可以返回一個promise對象進行補全 var argv = require('yargs')
  .completion('completion', function(current, argv) {
    return new Promise(function (resolve, reject) {
      setTimeout(function () {
        resolve(['apple', 'banana'])
      }, 10)
    })
  })
  .argv;

.config([key], [desction], [parseFn])
這個方法傳入key，相當於是一個 JSON 配置文件的路徑。文件中的 JSON 屬性被設置為對應的 key 和 value(掛在 argv 上)。文件使用 nodejs 的 require api 加載的，文件名最好為.js, .json。
如果此方法沒有攜帶任何參數，.config()將會使用--config選項傳入 JSON 配置文件（此時只能傳入以.json 結尾文件）
description同其他方法，用於描述命令
可選項 parseFn 可以用來定制轉換器。轉換函數必須是同步的，並且應當返回一個帶有 key,value 鍵值對的對象或者一個 error。

.config(object)
還可以傳一個明確的object, 同樣的，它的鍵值對會轉化為argv的鍵值對。
var argv = require("yargs").config({ foo: 1, bar: 2 }).argv;

config和pkgConf可以提供extends關鍵詞，用來表明配置應該從別處繼承。
extends參數可以是絕對路徑也可以是相對路徑

yargs.config({
  extends: "./configs/a.json",
  logLevel: "verbose"
}).argv;

//或者也可以提供一個模塊（這對函數性很有用，就像babel-presets）
yargs.pkgConf('nyc');

自定義的package.json
{
"nyc": {
　　　　"extends": "nyc-babel-config"
　　}
}
nyc-babel-config是一個包，這個包導出了configuration在index文件中

 

.conflicts(x, y);
設置了x之后y就不能設置了。y可以是一個字符串，也可以是一組 key不與x共存的

.count(key)
此命令用來對命令計數，並轉化為命令的參數，例如：

#!/usr/bin/env node
var argv = require("yargs")
  .count("verbose")
  .alias("v", "verbose").argv;

VERBOSE_LEVEL = argv.verbose;

function WARN() {
  VERBOSE_LEVEL >= 0 && console.log.apply(console, arguments);
}
function INFO() {
  VERBOSE_LEVEL >= 1 && console.log.apply(console, arguments);
}
function DEBUG() {
  VERBOSE_LEVEL >= 2 && console.log.apply(console, arguments);
}

WARN("Showing only important stuff");
INFO("Showing semi-important stuff too");
DEBUG("Extra chatty mode");

.demandOption(key, [msg | boolean]) .demandOption(key, msg)
此命令用來強制用戶輸入某些參數
如果 key 是一個字符串，且 key 沒有出現在命令行參數中，展示使用說明並退出。
如果 key 是數組，限制每一個數組中的參數
如果提供了 msg，而且沒有相應參數，那么 msg 將會展示，替代原有的標准錯誤信息

require("yargs")
  .option("run", {
    alias: "r",
    describe: "run your program"
  })
  .option("path", {
    alias: "p",
    describe: "provide a path to file"
  })
  .option("spec", {
    alias: "s",
    describe: "program specifications"
  })
  .demandOption(
    ["run", "path"],
    "Please provide both run and path arguments to work with this tool"
  )
  .help().argv;

  //當第二個參數為布爾值的時候，布爾值決定了這個選項是不是必須的。當使用 options 方法的時候，這個選項很有用

require("yargs")
  .options({
    run: {
      alias: "r",
      describe: "run your program",
      demandOption: true
    },
    path: {
      alias: "p",
      describe: "provide a path to file",
      demandOption: true
    },
    spec: {
      alias: "s",
      describe: "program specifications"
    }
  })
  .help().argv;

.demandCommand([min=1], [minMsg]) .demandCommand([min=1], [max], [minMsg], [maxMsg])
此命令用於限定用戶在程序中使用的命令次數。如果命令沒有傳進來，使用 msg 提供標准的錯誤提示

require("yargs")
  .command({
    command: "configure <key> [value]",
    aliases: ["config", "cfg"],
    desc: "Set a config variable",
    builder: yargs => yargs.default("value", "true"),
    handler: argv => s
      console.log(`setting ${argv.key} to ${argv.value}`);
    }
  })
  // provide a minimum demand and a minimum demand message
  .demandCommand(1, "You need at least one command before moving on")
  .help().argv;

.hide(key)
在使用信息中隱藏一個key, 除非用 --show-hidden

var yargs = require("yargs")(['--help'])
  .showHidden('show-hidden', 'Show hidden options')
  .argv

.detectLocale(boolean)
yargs檢測操作系統本地，默認是trues

.env([prefix])
定義環境變量的值，使用”_“來表明嵌套的選項（nested__foo => nested.foo）

程序參數定義優先的次序:

命令行參數
env 參數
配置文件或者 object
默認選項

//fruity.js
var argv = require("yargs")
  .env("MY_PROGRAM")
  .option("f", {
    alias: "fruit-thing",
    default: "apple"
  }).argv;
console.log(argv);

$: node fruity.js
{ _: [],
  f: 'apple',
  'fruit-thing': 'apple',
  fruitThing: 'apple',
  '$0': 'fruity.js' }

  $ MY_PROGRAM_FRUIT_THING=banana node fruity.js
{ _: [],
  fruitThing: 'banana',
  f: 'banana',
  'fruit-thing': 'banana',
  '$0': 'fruity.js' }

  $ MY_PROGRAM_FRUIT_THING=banana node fruity.js -f cat
{ _: [],
  f: 'cat',
  'fruit-thing': 'cat',
  fruitThing: 'cat',
  '$0': 'fruity.js' }

.epilog(str)
.epilogue(str)
使用說明結尾處的文案

var argv = require('yargs')
  .epilogue('for more information, find our manual at http://example.com');

.example(cmd, desc)
增加示例，第一個參數cmd中，$0代表命令行中的第一個參數。例子會隨着幫助信息打印出來。

.exitProcess(enable)
如果yargs由於調用 .version或者校驗失敗或者命令執行失敗，調用exitProcess(false)，可以繼續執行其它正常的指令。

.exit(code, err)
主動退出程序，並且可以提示 上下文表示為什么我們要退出。

.fail(fn)
發生錯誤的時候會調用
msg是本來要打印的錯誤
err本來要拋出的錯誤
yargs是yargs的實例

var argv = require('yargs')
  .fail(function (msg, err, yargs) {
    if (err) throw err // preserve stack
    console.error('You broke it!')
    console.error(msg)
    console.error('You should be doing', yargs.help())
    process.exit(1)
  })
  .argv

.getCompletion(args, done);
允許程序按步取得補全內容
args：命令行需要被補全的數組
done: 回調函數，函數會獲取當前的補全內容

require('yargs')
  .option('foobar')
  .option('foobaz')
  .completion()
  .getCompletion(['./test.js', '--foo'], function (completions) {
    console.log(completions)
  })
  //如果輸入 ./test.js --foo 輸入TAB: --foobar 和 --foobaz

.global(globals, [global=true])
此命令指點某個選項不會被重置當命令執行的時候

var argv = require('yargs')
  .option('a', {
    alias: 'all',
    default: true,
    global: false
  })
  .option('n', {
    alias: 'none',
    default: true,
    global: false
  })
  .command('foo', 'foo command', function (yargs) {
    return yargs.option('b', {
      alias: 'bar'
    })
  })
  .help('help')
  .global('a')
  .argv

  //如果foo執行 ， all這個參數會被保留，但是node會被刪除

.group(key(s), groupName)
把一個key或者一組keys放到一個 groupName下，當調用使用文檔的時候會分組展示

var yargs = require('yargs')(['--help'])
  .help()
  .group('batman', 'Heroes:')
  .describe('batman', "world's greatest detective")
  .wrap(null)
  .argv

//結果:
//  Heroes:
//  --batman  world's greatest detective

//Options:
//  --help  Show help  [boolean]

.help([option, [description]])
設置幫助提示
如果不傳參數 ， .help(); 這里啟用 --help這個選項

var yargs = require("yargs")(['--info'])
  .usage("$0 -operand1 number -operand2 number -operation [add|subtract]")
  .help('info')
  .argv

.implies(x, y)
如果設置了x, 則y就必須設置

.locale()
返回當前正在使用的yargs

middleware(callbacks, [applyBeforeValidation])
定義中間件

.nargs(key, count)
此方法表示，這后面的參數個數

var argv = require('yargs')
  .nargs('token', 1)
  .parse(['--token', '-my-token']);

  //{ _: [], token: '-my-token', '$0': 'node test' }

.normalize(key)
據說是為了傳入 path 的時候,便於調用 path.normalize()

.number(key)
告訴 parser，一直將這個key當作數字轉換

參數可以是數組

選項如果並沒有值，默認為undefined

不能轉化為數字，會被轉換為NaN

小數，16 進制數，科學計數法都是合法的

var argv = require("yargs")
  .number("n")
  .number(["width", "height"]).argv;

.option(key, [opt]) .options(key, [opt])

為key配置各種選項的命令
var argv = require("yargs").option("f", {
  alias: "file",
  demandOption: true,
  default: "/etc/passwd",
  describe: "x marks the spot",
  type: "string"
}).argv;
//同
var argv = require("yargs")
  .alias("f", "file")
  .demandOption("f")
  .default("f", "/etc/passwd")
  .describe("f", "x marks the spot")
  .string("f").argv;
  //同
  var argv = require("yargs").options({
  f: {
    alias: "file",
    demandOption: true,
    default: "/etc/passwd",
    describe: "x marks the spot",
    type: "string"
  }
}).argv;

可用的 key 有以下這些

• alias
• array
• boolean
• choices
• coerce
• config
• configParser
• conflicts
• count
• default
• defaultDescription
• demandOption
• desc/describe/description
• global
• group
• hidden
• implies
• nargs
• normalize
• number
• requiresArg
• skipValidation
• string
• type: ‘array’,’boolean’,’count’,’number’,’string’

.parse([args], [context], [parseCallback])

可以替代從process.argv傳參，返回 argv 對象。args 可以是數組或者原生參數字符串。

context：可以同時攜帶的一個對象參數，可以為命令提供狀態信息，是很實用的技術。

const parser = yargs
  .command(
    "lunch-train <restaurant>",
    "start lunch train",
    function() {},
    function(argv) {
      console.log(argv.restaurant, argv.time);
    }
  )
  .parse("lunch-train rudy's", { time: "12:15" });

  

parseCallback: 此方法的回調函數，會攜帶三個參數

err: 轉化中出現的驗證錯誤
argv: 轉化的 argv 對象
output: 將要在終端輸出的文本

const parser = yargs
  .command(
    "lunch-train <restaurant> <time>",
    "start lunch train",
    function() {},
    function(argv) {
      api.scheduleLunch(argv.restaurant, moment(argv.time));
    }
  )
  .help();

parser.parse(bot.userText, function(err, argv, output) {
  if (output) bot.respond(output);
});

.pkgConf(key, [cwd])
類似於 .config()，這表明 yargs 從 package.json 中尋找特定的配置對象
cwd可以選擇性地提供，package.json 將從這里讀取

.scriptName($0)
設置執行文件的名字， $0

var yargs = require("yargs")
.scriptName("my-script")
.help()
.argv

 

.wrap(columns)
設置列

.showHelp(consoleLevel=’error’)

用 console 的consoleLevel打印使用數據 

 

var yargs = require("yargs").usage(
  "$0 -operand1 number -operand2 number -operation [add|subtract]"
);
yargs.showHelp(); //prints to stderr using console.error()

或者，使用標准輸出打印使用信息，可以選擇console.log:

 

yargs.showHelp("log"); //prints to stdout using console.log()