sade - npm Package Compare versions

Comparing version 1.6.1 to 1.7.0

lib/index.js

@@ -48,3 +48,4 @@ const mri = require('mri');
 
-		this.tree[cmd] = { usage, options:[], alias:{}, default:{}, examples:[] };
+		this.tree[cmd] = { usage, alibi:[], options:[], alias:{}, default:{}, examples:[] };
+		if (opts.alias) this.alias(opts.alias);
 		if (desc) this.describe(desc);
@@ -60,2 +61,9 @@
 
+	alias(...names) {
+		if (this.single) throw new Error('Cannot call `alias()` in "single" mode');
+		if (!this.curr) throw new Error('Cannot call `alias()` before defining a command');
+		this.tree[this.curr].alibi = this.tree[this.curr].alibi.concat(...names);
+		return this;
+	}
+
 	option(str, desc, val) {
@@ -115,3 +123,3 @@ let cmd = this.tree[ this.curr || ALL ];
 			// Loop thru possible command(s)
-			let i=1, len=argv._.length + 1;
+			let k, i=1, len=argv._.length + 1;
 			for (; i < len; i++) {
@@ -121,2 +129,9 @@ tmp = argv._.slice(0, i).join(' ');
 					name=tmp; offset=(i + 2); // argv slicer
+				} else {
+					for (k in this.tree) {
+						if (this.tree[k].alibi.includes(tmp)) {
+							name=k; offset=(i + 2);
+							break;
+						}
+					}
 				}
@@ -123,0 +138,0 @@ }

lib/utils.js

@@ -66,2 +66,5 @@ const GAP = 4;
 		out += NL;
+	} else if (!single && key !== DEF) {
+		// Command help :: print its aliases if any
+		out += section('Aliases', cmd.alibi, prefix);
 	}
@@ -68,0 +71,0 @@

package.json

 {
   "name": "sade",
-  "version": "1.6.1",
+  "version": "1.7.0",
   "description": "Smooth (CLI) operator 🎶",
@@ -5,0 +5,0 @@ "repository": "lukeed/sade",

readme.md

@@ -201,4 +201,73 @@ # sade [![Build Status](https://travis-ci.org/lukeed/sade.svg?branch=master)](https://travis-ci.org/lukeed/sade)
 
+## Command Aliases
 
+Command aliases are alternative names (aliases) for a command. They are often used as shortcuts or as typo relief!
 
+The aliased names do not appear in the general help text.<br>
+Instead, they only appear within the Command-specific help text under an "Aliases" section.
+
+***Limitations***
+
+* You cannot assign aliases while in [Single Command Mode](#single-command-mode)
+* You cannot call [`prog.alias()`](#progaliasnames) before defining any Commands (via `prog.commmand()`)
+* You, the developer, must keep track of which aliases have already been used and/or exist as Command names
+
+***Example***
+
+Let's reconstruct the `npm install` command as a Sade program:
+
+```js
+sade('npm')
+  // ...
+  .command('install [package]', 'Install a package', {
+    alias: ['i', 'add', 'isntall']
+  })
+  .option('-P, --save-prod', 'Package will appear in your dependencies.')
+  .option('-D, --save-dev', 'Package will appear in your devDependencies.')
+  .option('-O, --save-optional', 'Package will appear in your optionalDependencies')
+  .option('-E, --save-exact', 'Save exact versions instead of using a semver range operator')
+  // ...
+```
+
+When we run `npm --help` we'll see this general help text:
+
+```
+  Usage
+    $ npm <command> [options]
+
+  Available Commands
+    install    Install a package
+
+  For more info, run any command with the `--help` flag
+    $ npm install --help
+
+  Options
+    -v, --version    Displays current version
+    -h, --help       Displays this message
+```
+
+When we run `npm install --help` &mdash; ***or*** the help flag with any of `install`'s aliases &mdash; we'll see this command-specific help text:
+
+```
+  Description
+    Install a package
+
+  Usage
+    $ npm install [package] [options]
+
+  Aliases
+    $ npm i
+    $ npm add
+    $ npm isntall
+
+  Options
+    -P, --save-prod        Package will appear in your dependencies.
+    -D, --save-dev         Package will appear in your devDependencies.
+    -O, --save-optional    Package will appear in your optionalDependencies
+    -E, --save-exact       Save exact versions instead of using a semver range operator
+    -h, --help             Displays this message
+```
+
+
+
 ## API
@@ -302,2 +371,22 @@
 
+##### opts.alias
+Type: `String|Array`
+
+Optionally define one or more aliases for the current Command.<br>
+When declared, the `opts.alias` value is passed _directly_ to the [`prog.alias`](#progaliasnames) method.
+
+```js
+// Program A is equivalent to Program B
+// ---
+
+const A = sade('bin')
+  .command('build', 'My build command', { alias: 'b' })
+  .command('watch', 'My watch command', { alias: ['w', 'dev'] });
+
+const B = sade('bin')
+  .command('build', 'My build command').alias('b')
+  .command('watch', 'My watch command').alias('w', 'dev');
+```
+
+
 ##### opts.default
@@ -348,2 +437,30 @@
 
+### prog.alias(...names)
+
+Define one or more aliases for the current Command.
+
+> **Important:** An error will be thrown if:<br>1) the program is in [Single Command Mode](#single-command-mode); or<br>2) `prog.alias` is called before any `prog.command`.
+
+#### names
+
+Type: `String`
+
+The list of alternative names (aliases) for the current Command.<br>
+For example, you may want to define shortcuts and/or common typos for the Command's full name.
+
+> **Important:** Sade _does not_ check if the incoming `names` are already in use by other Commands or their aliases.<br>During conflicts, the Command with the same `name` is given priority, otherwise the first Command (according to Program order) with `name` as an alias is chosen.
+
+The `prog.alias()` is append-only, so calling it multiple times within a Command context will _keep_ all aliases, including those initially passed via [`opts.alias`](#optsdefault).
+
+```js
+sade('bin')
+  .command('hello <name>', 'Greet someone by their name', {
+    alias: ['hey', 'yo']
+  })
+  .alias('hi', 'howdy')
+  .alias('hola', 'oi');
+//=> hello aliases: hey, yo, hi, howdy, hola, oi
+```
+
+
 ### prog.action(handler)
@@ -398,3 +515,3 @@
 
-> **Note:** Your example's `str` will be prefixed with your Programs's [`name`](#sadename).
+> **Note:** Your example's `str` will be prefixed with your Program's [`name`](#sadename).
 
@@ -401,0 +518,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

29329

increased by17.83%

Lines of code

238

increased by7.69%

Number of lines in readme file

673

increased by21.04%

No dependency changes