Nose Picking Mechanisms

    coa
    TypeScript icon, indicating that this package has built-in type declarations

    2.0.2 • Public • Published

    Command-Option-Argument

    Yet another parser for command line options.

    NPM Status Travis Status AppVeyor Status Coverage Status Dependency Status

    What is it?

    COA is a parser for command line options that aim to get maximum profit from formalization your program API. Once you write definition in terms of commands, options and arguments you automaticaly get:

    • Command line help text
    • Program API for use COA-based programs as modules
    • Shell completion

    Other features

    • Rich types for options and arguments, such as arrays, boolean flags and required
    • Commands can be async throught using promising (powered by Q)
    • Easy submoduling some existing commands to new top-level one
    • Combined validation and complex parsing of values

    TODO

    • Localization
    • Shell-mode
    • Configs
    • Aliases
    • Defaults

    Examples

    require('coa').Cmd() // main (top level) command declaration
        .name(process.argv[1]) // set top level command name from program name
        .title('My awesome command line util') // title for use in text messages
        .helpful() // make command "helpful", i.e. options -h --help with usage message
        .opt() // add some option
            .name('version') // name for use in API
            .title('Version') // title for use in text messages
            .short('v') // short key: -v
            .long('version') // long key: --version
            .flag() // for options without value
            .act(function(opts) { // add action for option
                // return message as result of action
                return JSON.parse(require('fs').readFileSync(__dirname + '/package.json'))
                    .version;
            })
            .end() // end option chain and return to main command
        .cmd().name('subcommand').apply(require('./subcommand').COA).end() // load subcommand from module
        .cmd() // inplace subcommand declaration
            .name('othercommand').title('Awesome other subcommand').helpful()
            .opt()
                .name('input').title('input file, required')
                .short('i').long('input')
                .val(function(v) { // validator function, also for translate simple values
                    return require('fs').createReadStream(v) })
                .req() // make option required
                .end() // end option chain and return to command
            .end() // end subcommand chain and return to parent command
        .run(process.argv.slice(2)); // parse and run on process.argv
    // subcommand.js
    exports.COA = function() {
        this
            .title('Awesome subcommand').helpful()
            .opt()
                .name('output').title('output file')
                .short('o').long('output')
                .output() // use default preset for "output" option declaration
                .end()
    };

    API reference

    Cmd

    Command is a top level entity. Commands may have options and arguments.

    Cmd.api

    Returns object containing all its subcommands as methods to use from other programs.
    @returns {Object}

    Cmd.name

    Set a canonical command identifier to be used anywhere in the API.
    @param String _name command name
    @returns COA.Cmd this instance (for chainability)

    Cmd.title

    Set a long description for command to be used anywhere in text messages.
    @param String _title command title
    @returns COA.Cmd this instance (for chainability)

    Cmd.cmd

    Create new or add existing subcommand for current command.
    @param COA.Cmd [cmd] existing command instance
    @returns COA.Cmd new or added subcommand instance

    Cmd.opt

    Create option for current command.
    @returns COA.Opt new option instance

    Cmd.arg

    Create argument for current command.
    @returns COA.Opt new argument instance

    Cmd.act

    Add (or set) action for current command.
    @param Function act action function, invoked in the context of command instance and has the parameters:
    - Object opts parsed options
    - Array args parsed arguments
    - Object res actions result accumulator
    It can return rejected promise by Cmd.reject (in case of error) or any other value treated as result.
    @param {Boolean} [force=false] flag for set action instead add to existings
    @returns COA.Cmd this instance (for chainability)

    Cmd.apply

    Apply function with arguments in context of command instance.
    @param Function fn
    @param Array args
    @returns COA.Cmd this instance (for chainability)

    Cmd.comp

    Set custom additional completion for current command.
    @param Function fn completion generation function, invoked in the context of command instance. Accepts parameters:
    - Object opts completion options
    It can return promise or any other value treated as result.
    @returns COA.Cmd this instance (for chainability)

    Cmd.helpful

    Make command "helpful", i.e. add -h --help flags for print usage.
    @returns COA.Cmd this instance (for chainability)

    Cmd.completable

    Adds shell completion to command, adds "completion" subcommand, that makes all the magic.
    Must be called only on root command.
    @returns COA.Cmd this instance (for chainability)

    Cmd.usage

    Build full usage text for current command instance.
    @returns String usage text

    Cmd.run

    Parse arguments from simple format like NodeJS process.argv and run ahead current program, i.e. call process.exit when all actions done.
    @param Array argv
    @returns COA.Cmd this instance (for chainability)

    Cmd.invoke

    Invoke specified (or current) command using provided options and arguments.
    @param String|Array cmds subcommand to invoke (optional)
    @param Object opts command options (optional)
    @param Object args command arguments (optional)
    @returns Q.Promise

    Cmd.reject

    Return reject of actions results promise.
    Use in .act() for return with error.
    @param Object reason reject reason
    You can customize toString() method and exitCode property of reason object.
    @returns Q.promise rejected promise

    Cmd.end

    Finish chain for current subcommand and return parent command instance.
    @returns COA.Cmd parent command

    Opt

    Option is a named entity. Options may have short and long keys for use from command line.
    @namespace
    @class Presents option

    Opt.name

    Set a canonical option identifier to be used anywhere in the API.
    @param String _name option name
    @returns COA.Opt this instance (for chainability)

    Opt.title

    Set a long description for option to be used anywhere in text messages.
    @param String _title option title
    @returns COA.Opt this instance (for chainability)

    Opt.short

    Set a short key for option to be used with one hyphen from command line.
    @param String _short
    @returns COA.Opt this instance (for chainability)

    Opt.long

    Set a short key for option to be used with double hyphens from command line.
    @param String _long
    @returns COA.Opt this instance (for chainability)

    Opt.flag

    Make an option boolean, i.e. option without value.
    @returns COA.Opt this instance (for chainability)

    Opt.arr

    Makes an option accepts multiple values.
    Otherwise, the value will be used by the latter passed.
    @returns COA.Opt this instance (for chainability)

    Opt.req

    Makes an option req.
    @returns COA.Opt this instance (for chainability)

    Opt.only

    Makes an option to act as a command, i.e. program will exit just after option action.
    @returns COA.Opt this instance (for chainability)

    Opt.val

    Set a validation (or value) function for argument.
    Value from command line passes through before becoming available from API.
    Using for validation and convertion simple types to any values.
    @param Function _val validating function, invoked in the context of option instance and has one parameter with value from command line
    @returns COA.Opt this instance (for chainability)

    Opt.def

    Set a default value for option. Default value passed through validation function as ordinary value.
    @param Object _def
    @returns COA.Opt this instance (for chainability)

    Opt.input

    Make option value inputting stream. It's add useful validation and shortcut for STDIN. @returns {COA.Opt} this instance (for chainability)

    Opt.output

    Make option value outputing stream.
    It's add useful validation and shortcut for STDOUT.
    @returns COA.Opt this instance (for chainability)

    Opt.act

    Add action for current option command. This action is performed if the current option is present in parsed options (with any value).
    @param Function act action function, invoked in the context of command instance and has the parameters:
    - Object opts parsed options
    - Array args parsed arguments
    - Object res actions result accumulator
    It can return rejected promise by Cmd.reject (in case of error) or any other value treated as result.
    @returns COA.Opt this instance (for chainability)

    Opt.comp

    Set custom additional completion for current option.
    @param Function fn completion generation function, invoked in the context of command instance. Accepts parameters:
    - Object opts completion options
    It can return promise or any other value treated as result.
    @returns COA.Opt this instance (for chainability)

    Opt.end

    Finish chain for current option and return parent command instance.
    @returns COA.Cmd parent command

    Arg

    Argument is a unnamed entity.
    From command line arguments passed as list of unnamed values.

    Arg.name

    Set a canonical argument identifier to be used anywhere in text messages.
    @param String _name argument name
    @returns COA.Arg this instance (for chainability)

    Arg.title

    Set a long description for argument to be used anywhere in text messages.
    @param String _title argument title
    @returns COA.Arg this instance (for chainability)

    Arg.arr

    Makes an argument accepts multiple values.
    Otherwise, the value will be used by the latter passed.
    @returns COA.Arg this instance (for chainability)

    Arg.req

    Makes an argument req.
    @returns COA.Arg this instance (for chainability)

    Arg.val

    Set a validation (or value) function for argument.
    Value from command line passes through before becoming available from API.
    Using for validation and convertion simple types to any values.
    @param Function _val validating function, invoked in the context of argument instance and has one parameter with value from command line
    @returns COA.Arg this instance (for chainability)

    Arg.def

    Set a default value for argument. Default value passed through validation function as ordinary value.
    @param Object _def
    @returns COA.Arg this instance (for chainability)

    Arg.output

    Make argument value outputing stream.
    It's add useful validation and shortcut for STDOUT.
    @returns COA.Arg this instance (for chainability)

    Arg.comp

    Set custom additional completion for current argument.
    @param Function fn completion generation function, invoked in the context of command instance. Accepts parameters:
    - Object opts completion options
    It can return promise or any other value treated as result.
    @returns COA.Arg this instance (for chainability)

    Arg.end

    Finish chain for current option and return parent command instance.
    @returns COA.Cmd parent command

    Keywords

    none

    Install

    npm i coa

    DownloadsWeekly Downloads

    9,202,373

    Version

    2.0.2

    License

    MIT

    Unpacked Size

    72.5 kB

    Total Files

    15

    Last publish

    Collaborators

    • veged
    • qfox