From 932cd1177e93f5cc99edfe57a4028e30717bf8fb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rory=20O=E2=80=99Kane?= Date: Sat, 9 May 2020 20:30:25 -0400 Subject: [PATCH] fix(docs): describe usage of `.check()` in more detail I added an example of usage that was distilled from my own code. Co-authored-by: Benjamin E. Coe --- docs/api.md | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/docs/api.md b/docs/api.md index a5bf7776a..aa120c49e 100644 --- a/docs/api.md +++ b/docs/api.md @@ -87,12 +87,27 @@ Check that certain conditions are met in the provided arguments. `fn` is called with two arguments, the parsed `argv` hash and an array of options and their aliases. -If `fn` throws or returns a non-truthy value, show the thrown error, usage information, and -exit. +If `fn` throws or returns a non-truthy value, Yargs will show the thrown error +and usage information. Yargs will then exit, unless +[`.exitProcess()`](#exitprocess) was used to prevent Yargs from exiting after a +failed check. `global` indicates whether `check()` should be enabled both at the top-level and for each sub-command. +```js +const argv = require('yargs') + .check((argv, options) => { + const filePaths = argv._ + if (filePaths.length > 1) { + throw new Error("Only 0 or 1 files may be passed.") + } else { + return true // tell Yargs that the arguments passed the check + } + }) + .argv +``` + .choices(key, choices) ----------------------