clap

    3.0.0-beta.1 • Public • Published

    NPM version Build Status Coverage Status

    Clap.js

    A library for node.js to build command-line interfaces (CLI). With its help, making a simple CLI application is a trivial task. It equally excels in complex tools with a lot of subcommands and specific features. This library supports argument coercion and completion suggestion — typing the commands is much easier.

    Inspired by commander.js

    Features:

    • TBD

    Usage

    npm install clap
    
    const cli = require('clap');
     
    const myCommand = cli.command('my-command [optional-arg]')
        .description('Optional description')
        .version('1.2.3')
        .option('-b, --bool', 'Bollean option')
        .option('--foo <foo>', 'Option with required argument')
        .option('--bar [bar]', 'Option with optional argument')
        .option('--baz [value]', 'Option with optional argument and normalize function',
            value => Number(value),
            123 // 123 is default
        )
        .action(function({ options, args, literalArgs }) {
            // options is an object with collected values
            // args goes before options
            // literal args goes after "--"
        });
     
    myCommand.run();  // the same as "myCommnad.run(process.argv.slice(2))"
    myCommand.run(['--foo', '123', '-b'])
     
    // sub-commands
    myCommand
        .command('nested')
            .option('-q, --quz', 'Some parameter', 'Default value')
            // ...
            .end()
        .command('another-command')
            // ...
            .command('level3-command')
                //...

    API

    Command

    .command()
        // definition
        .description(value)
        .version(value, usage, description, action)
        .help(usage, description, action)
        .option(usage, description, ...options)
        .command(usageOrCommand)
        .extend(fn, ...options)
        .end()
    
        // argv processing pipeline handler setters
        .init(command, context)
        .applyConfig(context)
        .prerareContenxt(context)
        .action(context)
    
        // main methods
        .parse(argv, suggest)
        .run(argv)
    
        // misc
        .clone(deep)
        .createOptionValues()
        .getCommand(name)
        .getCommands()
        .getOption(name)
        .getOptions()
        .outputHelp()
    

    .option(usage, description, ...options)

    There are two usage:

    .option(usage, description, normalize, value)
    .option(usage, description, options)
    

    Where options:

    {
        default: any,          // default value
        normalize: (value, oldValue) => { ... }, // any value for option is passing through this function and its result stores as option value
        shortcut: (value, oldValue) => { ... },  // for shortcut options, the handler is executed after the value is set, and its result (an object) is used as a source of values for other options
        action: () => { ... }, // for an action option, which breaks regular args processing and preform and action (e.g. show help or version)
        config: boolean        // mark option is about config and should be applied before `applyConfig()`
    }
    

    Argv processing

    • init(command, context) // before arguments parsing
      • invoke action option and exit if any
    • apply config options
    • applyConfig(context)
    • apply all the rest options
    • prepareContext(context) // after arguments parsing
      • switch to next command -> command is prescending
        • init(command, context)
          • invoke action option and exit if any
        • apply config options
        • applyConfig(context)
        • apply all the rest options
        • prepareContext(context) // after arguments parsing
          • switch to next command
            • ...
          • action(context) -> command is target
      • action(context) -> command is target

    License

    MIT

    Install

    npm i clap

    DownloadsWeekly Downloads

    1,034,946

    Version

    3.0.0-beta.1

    License

    MIT

    Unpacked Size

    29.8 kB

    Total Files

    11

    Last publish

    Collaborators

    • lahmatiy