From c7a43d9a74cf42dc7894b0f73eac2b4a0fd30b6c Mon Sep 17 00:00:00 2001 From: Lloyd Brookes Date: Tue, 31 Jan 2017 21:00:18 +0000 Subject: [PATCH] overhauled the examples --- example/README.md | 31 ----------------------- example/alias.js | 5 ---- example/defaultValue.js | 4 --- example/group.js | 7 ------ example/mocha.js | 28 +++++++++++++++++---- example/multiple.js | 3 --- example/name.js | 5 ---- example/type.js | 38 +++++++++++++++++++++++------ example/typical.js | 54 ++++++++++++++++++++++++++++++++++++++++- example/unknown.js | 13 +++++++++- example/validate.js | 2 +- 11 files changed, 120 insertions(+), 70 deletions(-) delete mode 100644 example/README.md delete mode 100644 example/alias.js delete mode 100644 example/defaultValue.js delete mode 100644 example/group.js delete mode 100644 example/multiple.js delete mode 100644 example/name.js diff --git a/example/README.md b/example/README.md deleted file mode 100644 index f5f55cb..0000000 --- a/example/README.md +++ /dev/null @@ -1,31 +0,0 @@ -# Examples -Most of these example files are modules exporting an array of [Option Definitions](https://github.com/75lb/command-line-args/#optiondefinition-). They are consumed using the command-line-args test harness. - -## Install -Install the test harness: - -``` -$ npm install -g command-line-args -``` - -## Usage -Try one of the examples out - -``` -$ cat example/typical.js | command-line-args --timeout 100 --src lib/* - -{ timeout: 100, - src: - [ 'lib/argv.js', - 'lib/command-line-args.js', - 'lib/definition.js', - 'lib/definitions.js', - 'lib/option.js' ] } -``` - -# Validation -command-line-args parses the command line but does not validate the values received. There's one example ([validate.js](https://github.com/75lb/command-line-args/blob/master/example/validate.js)) suggesting how this could be done: - -``` -$ node example/validate.js -``` diff --git a/example/alias.js b/example/alias.js deleted file mode 100644 index 81fcb4c..0000000 --- a/example/alias.js +++ /dev/null @@ -1,5 +0,0 @@ -module.exports = [ - { name: 'hot', alias: 'h', type: Boolean }, - { name: 'discount', alias: 'd', type: Boolean }, - { name: 'courses', alias: 'c', type: Number } -] diff --git a/example/defaultValue.js b/example/defaultValue.js deleted file mode 100644 index eb00274..0000000 --- a/example/defaultValue.js +++ /dev/null @@ -1,4 +0,0 @@ -module.exports = [ - { name: 'files', type: String, multiple: true, defaultValue: [ 'one.js' ] }, - { name: 'max', type: Number, defaultValue: 3 } -] diff --git a/example/group.js b/example/group.js deleted file mode 100644 index a784439..0000000 --- a/example/group.js +++ /dev/null @@ -1,7 +0,0 @@ -module.exports = [ - { name: 'verbose', group: 'standard' }, - { name: 'help', group: [ 'standard', 'main' ] }, - { name: 'compress', group: [ 'server', 'main' ] }, - { name: 'static', group: 'server' }, - { name: 'debug' } -] diff --git a/example/mocha.js b/example/mocha.js index dcd452f..feda9cc 100644 --- a/example/mocha.js +++ b/example/mocha.js @@ -1,17 +1,35 @@ +'use strict' + /* demonstrates use in a mocha test script */ + const assert = require('assert') const commandLineArgs = require('../') -/* enable partial parsing to prevent exceptions being thrown -if the user sets undefined, mocha-specific options (e.g. --no-colors) */ +/* +enable partial parsing to prevent exceptions being thrown +if the user sets undefined, mocha-specific options (e.g. --no-colors) +*/ const options = commandLineArgs({ name: 'value', type: Number }, { partial: true }) describe('Array', function () { describe('#indexOf()', function () { - it('should return -1 when the value is not present', function () { - assert.equal(options.value, [ 1, 2, 3 ].indexOf(4)) + it('should pass when the supplied value is between 1 and 3', function () { + assert.ok([ 1, 2, 3 ].indexOf(options.value) > -1) }) }) }) -console.log(JSON.stringify(options, null, ' ')) +/* +Example output: + +$ mocha example/mocha.js --value 3 --no-colors + + + Array + #indexOf() + ✓ should pass when the supplied value is between 1 and 3 + + + 1 passing (7ms) + +*/ diff --git a/example/multiple.js b/example/multiple.js deleted file mode 100644 index 8154e77..0000000 --- a/example/multiple.js +++ /dev/null @@ -1,3 +0,0 @@ -module.exports = [ - { name: 'files', type: String, multiple: true } -] diff --git a/example/name.js b/example/name.js deleted file mode 100644 index 043f044..0000000 --- a/example/name.js +++ /dev/null @@ -1,5 +0,0 @@ -module.exports = [ - { name: 'file' }, - { name: 'verbose' }, - { name: 'depth' } -] diff --git a/example/type.js b/example/type.js index f48f79b..62cf01b 100644 --- a/example/type.js +++ b/example/type.js @@ -1,12 +1,36 @@ -var fs = require('fs') +'use strict' +const commandLineArgs = require('../') -function FileDetails (filename) { - if (!(this instanceof FileDetails)) return new FileDetails(filename) - this.filename = filename - this.exists = fs.existsSync(filename) +/* demonstrates a custom `type` function which returns a class instance */ + +class FileDetails { + constructor (filename) { + const fs = require('fs') + this.filename = filename + this.exists = fs.existsSync(filename) + } } -module.exports = [ - { name: 'file', type: FileDetails }, +const optionDefinitions = [ + { + name: 'file', + multiple: true, + defaultOption: true, + type: filename => new FileDetails(filename) + }, { name: 'depth', type: Number } ] + +const options = commandLineArgs(optionDefinitions) + +console.log(options) + +/* +Example output: + +$ node example/type.js package.json nothing.js +{ file: + [ FileDetails { filename: 'package.json', exists: true }, + FileDetails { filename: 'nothing.js', exists: false } ] } + */ + diff --git a/example/typical.js b/example/typical.js index e7bcad9..ef8a841 100644 --- a/example/typical.js +++ b/example/typical.js @@ -1,6 +1,58 @@ -module.exports = [ +'use strict' +const commandLineArgs = require('../') +const commandLineUsage = require('command-line-usage') + +/* + This example shows typical use alongside command-line-usage + https://github.com/75lb/command-line-usage +*/ + +const optionDefinitions = [ { name: 'help', alias: 'h', type: Boolean, description: 'Display this usage guide.' }, { name: 'src', type: String, multiple: true, defaultOption: true, description: 'The input files to process', typeLabel: '' }, { name: 'timeout', alias: 't', type: Number, description: 'Timeout value in ms', typeLabel: '' }, { name: 'log', alias: 'l', type: Boolean, description: 'info, warn or error' } ] + +const options = commandLineArgs(optionDefinitions) + +if (options.help) { + const usage = commandLineUsage([ + { + header: 'Typical Example', + content: 'A simple example demonstrating typical usage.' + }, + { + header: 'Options', + optionList: optionDefinitions + }, + { + content: 'Project home: [underline]{https://github.com/me/example}' + } + ]) + console.log(usage) +} + +console.log(options) + +/* + +Example output: + +$ node example/typical.js --help + +Typical Example + + A simple example demonstrating typical usage. + +Options + + -h, --help Display this usage guide. + --src The input files to process + -t, --timeout Timeout value in ms + -l, --log info, warn or error + + Project home: https://github.com/me/example + +{ help: true } +*/ diff --git a/example/unknown.js b/example/unknown.js index 6891742..8ac1ac7 100644 --- a/example/unknown.js +++ b/example/unknown.js @@ -2,10 +2,21 @@ const commandLineArgs = require('../') const optionDefinitions = [ - { name: 'help', type: Boolean }, + { name: 'depth', type: Number }, { name: 'files', alias: 'f', type: String, multiple: true, defaultOption: true } ] const options = commandLineArgs(optionDefinitions, { partial: true }) console.log(options) + +/* + +Example output: + +$ node example/unknown.js --depth 3 package.json README.md --unknown1 --unknown2 +{ depth: 3, + files: [ 'package.json', 'README.md' ], + _unknown: [ '--unknown1', '--unknown2' ] } + +*/ diff --git a/example/validate.js b/example/validate.js index af06c56..e94f1ee 100644 --- a/example/validate.js +++ b/example/validate.js @@ -1,6 +1,6 @@ /* command-line-args parses the command line but does not validate what was collected. - This is an example of how values collected can be validated. + This example demonstrates how the values collected can be validated. */ 'use strict'