cli_router

A router for parsing command line arguments.

Node CLI Router

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.

npm install --save cli_router

In your scripts:

var router = require("cli_router");

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

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
}

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"

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.

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

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.

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);

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() {});

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.

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!");
});

You can chain some methods:

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

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

router.clear()
  • Fork the repository
  • Clone it down
  • npm install
  • npm test
  • Push to your repository.
  • Make a pull request.
  • Optional Parameters
  • Fully document API (for now, the source and tests are pretty self documenting)
  • Tidy up some of the shared code across methods

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!