Node CLI Router

Version 0.3.0

I build a lot of Node CLI tools and one of the things I've always wanted is a small router for user arguments.

I build a lot of websites using Sinatra and I love how in Sinatra you can route URLs to functions easily. I decided to take a go at doing something similar for command line flags and arguments for CLI tools.

Installation

npm install --save cli_router

In your scripts:

var router = require("cli_router");

Examples

If you'd like to see an actual module that uses this, check my Github Opener Module.

## Array Matching Syntax Say we have a CLI tool which is run on the command line by running foo. We can match on arguments like so:

router.match(["-a", "-b"], function() {
  // do something
});

router.go(process.argv);

That would match:

$ foo -a -b
$ foo -b -a

We can also use flags that take a parameter:

router.match(["-a", ["-b", "num"]], function(params) {
  console.log(params.num);
});
router.go(process.argv);

That would match:

$ foo -a -b 5
$ foo -b 5 -a

And in the callback, params.num === "5" and params.a === true.

The callback takes one argument, containing the parameters the user passed in. For example:

With this route:

router.match(["-a", ["-b", "num"], "-c"], function(params) {});

Here's how the params object will look for each of these calls:

$ foo -a -b -5 -c
{
  a: true,
  b: "5",
  c: true
}

String Matching Syntax

If you don't like the array syntax, you can match with strings too. These two matches are equivalent:

router.match(["-a", ["-b", "num"]], function(params) {...});
router.match("-a -b <num>", function(params) {...});

The same parameters are passed into the function.

Of course, ordering doesn't matter. So all four of these are identical in terms of what they match:

["-a", ["-b", "num"]]
[["-b", "num"], "-a"]
"-a -b <num>"
"-b <num> -a"

## Multiple Routes When a user string is matched by more than one defined route, the first route will take affect. For example:

router.match("-a <num> -b", function(){});
router.match("-b -a <num>", function(){});

When $ foo -a 5 -b is run, the first route will be used, because it was defined first.

Joined up Arguments

The router is able to split arguments up, allowing your users to enter them joined. For example, with this match:

router.match("-a -b -c", function() {});

All of these will be matched:

$ foo -abc
$ foo -bca
$ foo -a -b -c

In fact, you can even used joined up arguments in your match calls:

router.match("-abc", function() {});

Which will match all of:

$ foo -abc
$ foo -b -a -c
$ foo -bca
$ foo -a -b -c
... and so on

Other Arguments

Some tools might take it one main argument and then allow flags to be set. For example:

$ foo test.txt -a -b -c

The CLI Router doesn't support this, but you can get around it yourself. Rather than calling router.go(process.argv), strip the user arguments out and call router.process on them. Using the above example, say the user passes in arguments such that process.argv looks like so:

["node", "/Users/MadeUp/yourscript.js", "test.txt", "-a", "-b"]

You can get the main argument, test.txt as process.argv[2], and then call router.process(process.argv.slice(3).join(" ")) to route based on the flags.

Contexts

If you care about the context in which the callback function is called, you can add it as a third parameter to match:

router.match("some string", function() {}, this);

Wildcards

You can use * in your routes to denote wildcards. For example:

//string syntax
router.match("-a -b *", function() {});
//array syntax
router.match(["-a", "-b", "*"], function() {});

Will match:

$ foo -a -b -c -d -e
$ foo -b -a -c 5

The wildcard matching passes all the passed in arguments to the callback. Example:

$ foo -a -b -c 5

// the object passed into the callback:
{
  a: true,
  b: true,
  c: "5"
}

Note that you must define the wildcard last in the match string/array. This will not work:

route.match("-a * -b", function() {});

Before and After

Often there will be code you want to execute before or after a route callback method. Just use the before and after methods to add this:

var callback1 = function() {...};
var callback2 = function() {...};
router.before(callback1);
router.after(callback2);

These methods are only called if a route was matched. They are not called if no route was matched.

Else

You can define a method to run if and only if no routes are matched.

router.else(function() {
  console.log("Sorry, you didn't enter the right arguments!");
});

Chaining

You can chain some methods:

router.clear().match("*", callback).before(function() {}).after(function() {}).go(process.argv);

Clearing

If you ever need to clear out all matches, you can:

router.clear()

Contributing

Fork the repository
Clone it down
npm install
npm test
Push to your repository.
Make a pull request.

Todo

Optional Parameters
Fully document API (for now, the source and tests are pretty self documenting)
Tidy up some of the shared code across methods

Changelog

v0.3.0

added else
support for -abc as -a -b -c

v0.2.0

added before and after
made match, before, after, clear chainable

v0.1.0

wildcard support
improve parameter passing

v0.0.1

initial release!

iTrauco/node_cli_router