Ninety-nine Pitchers of Malt

    @sapphirejs/consoler

    0.1.0 • Public • Published

    Consoler

    Build Status Coverage Status license

    A micro framework for building small CLI applications. It is the package that drives console commands for the Sapphire Router and it was extracted from there. Although a minimalist framework, Consoler will let you express commands in a very simple and intuitive way. What it lacks the most right now are help screens, which would make the command syntax very verbose. If you don't need those, than take a look at the usage below.

    Internally it uses minimist to parse options and arguments, and string-argv to split dhe template command into an array.

    Usage

    Starting it up is quite simple:

    $ npm install --save @sapphirejs/consoler
    
    const consoler = require('@sapphirejs/consoler')
    const template = 'mycommand <name>'
    const cli = process.argv.slice(2)
    
    // Returns an object with the command name,
    // arguments, and options.
    const command = new Consoler(template, cli).parse()

    There's also the match method that simply returns true or false if the actual command matches the template. It only checks the firstmost argument, considering it the command name.

    const doesMatch = new Consoler(template, cli).match()

    Arguments

    Arguments will always be named and either required or optional. The convention is to use <arg> for required arguments and [arg] for optional ones.

    Required arguments need to be passed in the CLI, otherwise and error will be thrown.

    // CLI: readfile myfile.txt
    const template = 'readfile <name>'
    const cli = process.argv.slice(2)
    const command = new Consoler(template, cli).parse()
    
    console.log(command.argument.name) // myfile.txt

    Optional ones though will just be ingored if not present.

    // CLI: readfile
    const template = 'readfile [name]'
    const cli = process.argv.slice(2)
    const command = new Consoler(template, cli).parse()
    
    console.log(command.argument.name) // undefined

    Options

    Options are a tiny bit more complicated as they may be flags, may have a type, or default values. We'll explore each of them.

    In the simplest usecase, options can be anonymous and called by their name. Option flags will always return true.

    // CLI: writefile myfile.txt --atomic --content=hello
    const template = 'writefile <name> --atomic --content='
    const cli = process.argv.slice(2)
    const command = new Consoler(template, cli).parse()
    
    console.log(command.option.atomic) // true
    console.log(command.option.content) // hello

    For safer usage though, you'll most probably need to validate the input data. In that case, you'll use a familiar syntax. The example below calls for a number type and will throw if the actual value is different. It also sets a named parameter for the option.

    // CLI: writefile myfile.txt --attemps=3
    const template = 'writefile <name> --attemps=<tries|type:number>'
    const cli = process.argv.slice(2)
    const command = new Consoler(template, cli).parse()
    
    console.log(command.option.tries) // 3

    Consoler supports string, number, and array for non-boolean option flags. As we mentioned it, an array type is just a list of data separated by a comma that is converted to a JavaScript array.

    // CLI: concat --files=one.txt,two.txt
    const template = 'concat --files=<type:array>'
    const cli = process.argv.slice(2)
    const command = new Consoler(template, cli).parse()
    
    console.log(command.option.files) // ['one.txt', 'two.txt']

    Number values will be automatically cast to a number (integer or float). Let's see a more contrived example that takes advantage of lists and casting:

    // CLI: reduce 5 --numbers=1,2,3,4,5
    const template = 'reduce <start> --numbers=<nums|type:array>'
    const cli = process.argv.slice(2)
    const command = new Consoler(template, cli).parse()
    
    const result = command.option.nums.reduce((acc, num) => acc + num, command.argument.start)
    console.log(result) // 20

    Finally, you can set default values for options that will be considered when that option is missing from the actual command:

    // CLI: sum
    const template = 'sum --numbers=<nums|type:array|default:7,3>'
    const cli = process.argv.slice(2)
    const command = new Consoler(template, cli).parse()
    
    console.log(command.option.nums) // 10

    Install

    npm i @sapphirejs/consoler

    DownloadsWeekly Downloads

    0

    Version

    0.1.0

    License

    MIT

    Unpacked Size

    18.3 kB

    Total Files

    11

    Last publish

    Collaborators

    • aleksanderkoko
    • fadion