Feat: Command Aliases (#34)

* feat: add `alias` method & command option;

- Closes #26

* feat: add "Aliases" section to command help text

* chore: add `alias` test cases

* chore: add tests for `utils.help` text output

* chore: readme docs

* fix: typo

Author: lukeed

lib/index.js

@@ -45,7 +45,8 @@ class Sade {
 		this.curr = cmd;
 		if (opts.default) this.default=cmd;
 
-		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);
 
 		return this;
@@ -56,6 +57,13 @@ class Sade {
 		return this;
 	}
 
+	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) {
 		let cmd = this.tree[ this.curr || ALL ];
 
@@ -110,11 +118,18 @@ class Sade {
 			cmd = this.tree[DEF];
 		} else {
 			// Loop thru possible command(s)
-			let i=1, len=argv._.length + 1;
+			let k, i=1, len=argv._.length + 1;
 			for (; i < len; i++) {
 				tmp = argv._.slice(0, i).join(' ');
 				if (this.tree[tmp] !== void 0) {
 					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;
+						}
+					}
 				}
 			}
 

lib/utils.js

@@ -63,6 +63,9 @@ exports.help = function (bin, tree, key, single) {
 			out += (NL + __ + __ + `${pfx} ${k} --help`);
 		});
 		out += NL;
+	} else if (!single && key !== DEF) {
+		// Command help :: print its aliases if any
+		out += section('Aliases', cmd.alibi, prefix);
 	}
 
 	out += section('Options', format(cmd.options), noop);

readme.md

@@ -198,6 +198,75 @@ When `sirv --help` is run, the generated help text is trimmed, fully aware that
     $ sirv my-app --dev
 ```
 
+## 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
@@ -298,6 +367,26 @@ The Command's description. The value is passed directly to [`prog.describe`](#pr
 Type: `Object`<br>
 Default: `{}`
 
+##### 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
 
 Type: `Boolean`
@@ -343,6 +432,34 @@ For general `--help` output, ***only*** the first sentence will be displayed. Ho
 > **Note:** Pass an `Array` if you don't want internal assumptions. However, the first item is _always_ displayed in general help, so it's recommended to keep it short.
 
 
+### 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)
 
 Attach a callback to the current Command.
@@ -392,7 +509,7 @@ Type: `String`
 
 The example string to add. This will be included in the general or command-specific `--help` output.
 
-> **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).
 
 
 ### prog.option(flags, desc, value)

test/fixtures/alias1.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+const sade = require('../../lib');
+
+sade('bin <type> [dir]')
+	.alias('error')
+	.parse(process.argv);

test/fixtures/alias2.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+const sade = require('../../lib');
+
+sade('bin')
+	.alias('foo')
+	.command('bar <src>')
+	.parse(process.argv);

test/fixtures/args.js

@@ -3,10 +3,12 @@ const sade = require('../../lib');
 
 sade('bin')
 	.command('foo <dir>')
+	.alias('f')
 	.action(dir => {
 		console.log(`~> ran "foo" with "${dir}" arg`);
 	})
 	.command('bar [dir]')
+	.alias('b')
 	.action(dir => {
 		dir = dir || '~default~';
 		console.log(`~> ran "bar" with "${dir}" arg`);

test/fixtures/basic.js

@@ -3,6 +3,7 @@ const sade = require('../../lib');
 
 sade('bin')
 	.command('foo')
+	.alias('f', 'fo')
 	.action(() => {
 		console.log('~> ran "foo" action');
 	})

test/fixtures/default.js

@@ -2,10 +2,11 @@
 const sade = require('../../lib');
 
 sade('bin')
-	.command('foo', null, { default:true })
+	.command('foo', null, { alias: 'f', default:true })
 	.action(() => console.log('~> ran "foo" action'))
 
 	.command('bar')
+	.alias('b')
 	.action(() => console.log('~> ran "bar" action'))
 
 	.parse(process.argv);

test/fixtures/options.js

@@ -4,6 +4,7 @@ const sade = require('../../lib');
 sade('bin')
 	.option('-g, --global', 'global')
 	.command('foo')
+	.alias('f')
 	.option('-l, --long', 'long flag')
 	.option('-s, --short', 'short flag')
 	.option('-h, --hello', 'override')
@@ -15,6 +16,7 @@ sade('bin')
 	})
 
 	.command('bar <dir>')
+	.alias('b')
 	.option('--only', 'no short alias')
 	.action((dir, opts) => {
 		let pre = opts.only ? '~> (only)' : '~>';

test/fixtures/subs.js

@@ -2,17 +2,17 @@
 const sade = require('../../lib');
 
 sade('bin')
-	.command('remote')
+	.command('remote', '', { alias: 'r' })
   .action(opts => {
     console.log('~> ran "remote" action');
   })
 
-  .command('remote add <name> <url>')
+	.command('remote add <name> <url>', '', { alias: 'ra' })
   .action((name, uri, opts) => {
-    console.log(`~> ran "remote add" with "${name}" and "${uri}" args`);
+		console.log(`~> ran "remote add" with "${name}" and "${uri}" args`);
   })
 
-  .command('remote rename <old> <new>')
+  .command('remote rename <old> <new>', '', { alias: 'rr' })
   .action((old, nxt, opts) => {
     console.log(`~> ran "remote rename" with "${old}" and "${nxt}" args`);
   })