Options

After reading this guide you will know:

  1. How to define options in multiple ways
  2. Configure aliases and default values
  3. Set up global options

Defining options

Let’s take a look on a full example on how to define options for imaginary apps create command:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
var CreateApplication = Command.extend({
    desc: 'Create application',

    options: {
        region: {
            type: 'string',
            aliases: ['r', 'reg'],
            default: 'london'
        },

        size: {
            alias: 's',
            default: 512
        }
    },

    run: function (region, size, name) {
        // create app with supplied options
    }
});

All options should be defined in options property. For each option object, you can specify these properties:

There’s also a shorthand API for defining options.

1
2
3
4
5
6
7
8
options: {
    region: {
        type: 'string'
    },
    force: {
        type: 'boolean'
    }
}

equals to:

1
2
3
4
options: {
    region: 'string',
    force: 'boolean'
}

If option’s property value is a String, Ronin understands it as a value type of an option, as if it was defined using type.

Option values are passed to the .run() method in the order they were defined

Global options

There are cases when global options are required, options that can be consumed by each command in your program. Global options are defined in index.js, where you initialize your program. The API for defining global options is exactly the same as for local options.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
var ronin = require('ronin');

var program = ronin({
    path: __dirname,
    desc: 'Simple to-do application',
    options: {
        user: {
            type: 'string',
            alias: 'u',
            default: 'me'
        }
    }
});

program.run();

To get the value of a global option, use this.global property inside .run() method:

1
2
3
4
5
6
7
8
var RemoveTask = Command.extend({
    desc: 'Removes task',

    run: function (name) {
        // value of --user, -u global option
        var user = this.global.user;
    }
});