Merge pull request #2 from Mimickal/api-tweaks

Add docs, refactor code a bit, bug fixes

README.md

@@ -4,15 +4,16 @@
 src="https://www.gnu.org/graphics/lgplv3-with-text-154x68.png">
 </a>
 
+Unlike other argument parsers, this library is built specifically (and only) for
+positional arguments, allowing it to provide much more functionality and control
+over how positional arguments are interpreted. It also doesn't force you to
+restructure your code to use it. All the individual pieces are exposed and work
+standalone, so you only have to use as much of the library as you need.
+
 This library was originally written to be a lightweight, unintrusive alternative
 to [Commando](https://www.npmjs.com/package/discord.js-commando) for Discord
-bots.
-
-Unlike other argument parsers, this library is built specifically for positional
-arguments, allowing it to provide much more functionality and control over how
-positional arguments are interpreted. It also doesn't force you to restructure
-your code to use it. All the individual pieces are exposed and work standalone,
-so you only have to use as much of the library as you need.
+bots. There are no Discord-specific things in this library, but it does still
+work well for this purpose.
 
 Features:
 - No external dependencies.
@@ -37,8 +38,94 @@ Available on [npm](https://www.npmjs.com/package/positional-args).
 npm install positional-args
 ```
 
-## Usage
-Coming soon!
+## Usage and examples
+[See full API here!](API.md)
+
+[See GitHub releases page for API changes.](
+https://github.com/Mimickal/positional-args/releases)
+
+This example creates a `CommandRegistry` with multiple commands and handler for
+unrecognized commands.
+```js
+const registry = new CommandRegistry()
+    .add(new Command('say')
+        .description('Prints the args given. Also has multiple argument sets, for fun')
+        .addArgSet([ new Argument('first') ])
+        .addArgSet([
+            new Argument('first'),
+            new Argument('extras')
+                .varargs(true)
+                .optional(true),
+        ])
+        .handler(args => console.log('I got', args))
+    )
+    .add(new Command('die_always')
+        .description('I always throw because I am not nice')
+        .handler(() => { throw new Error('I strike again!') })
+    )
+    .helpHandler() // Use the built-in help handler
+    .defaultHandler((parts) => console.log('Unrecognized command', parts));
+
+registry.help('say'); /* Returns string:
+"say <first>\n" +
+"say <first> <extras_1> [extras_2] ... [extras_n]" */
+
+registry.execute('say one'); /* Prints:
+I got {
+  _: ["one"],
+  first: "one",
+} */
+
+registry.execute('say one two three four'); /* Prints:
+I got {
+  _: ["one", "two", "three", "four"],
+  first: "one",
+  extras: ["two", "three", "four"],
+} */
+
+try {
+    registry.execute('die_always');
+} catch (err) {
+    // CommandError
+    // .message: "Command failed"
+    // .nested: Error("I strike again!")
+    // .full_message: "Command failed: I strike again!"
+}
+
+registry.execute('some random thing'); /* Prints:
+Unrecognized command ["some", "random", "thing"] */
+```
+
+There are more examples in the [API docs](API.md).
+
+### A note on async
+This library has a permissive enough API that one could force mixing sync and
+async elements together. While this is possible, it is explicitly discouraged
+and not officially supported. If you need both sync and async commands, consider
+either making all commands async or dividing them into two separate registries.
+
+```js
+// DON'T DO THIS!
+const registry = new CommandRegistry()
+    .asynchronous(false)
+    .add(new Command('example'))
+    .add(new Command('other'));
+registry.commands.get('example').is_async = true;
+
+try {
+    registry.execute('example').then(...).catch(...);
+} catch (err) {
+    ...
+}
+
+// Do this instead!
+const registry = new CommandRegistry()
+    .asynchronous(true)
+    .add(new Command('example'))
+    .add(new Command('other'));
+
+registry.execute('example').then(...).catch(...);
+```
 
 ## License
 
@@ -49,4 +136,3 @@ This code is licensed under the
 
 Basically, you are free to use this library in your closed source projects, but
 any modifications to this library must be made open source.
-

build/release.js

@@ -0,0 +1,27 @@
+// This is not strictly part of the library. This is just a janky script that
+// bumps the release version and regenerates code docs.
+const fs = require('fs');
+const shell = require('child_process').execSync;
+
+const newversion = process.argv[2];
+if (!newversion) {
+	console.error('Missing version!');
+	process.exit(1);
+}
+
+function updateVersionForFile(file) {
+	const file_json = require(`../${file}`);
+	file_json.version = newversion;
+	fs.writeFileSync(file, JSON.stringify(file_json, null, 2));
+	console.log(`Wrote version ${newversion} to ${file}`);
+}
+
+updateVersionForFile('package.json');
+updateVersionForFile('package-lock.json');
+
+shell('npm run regen-docs');
+console.log('Wrote out new API.md');
+
+shell('git add package.json package-lock.json API.md');
+shell(`git commit -m "Version bump to ${newversion}, regen docs"`);
+