left-hook-scaffold v0.1.0-beta

Left Hook Scaffold

CLI App Creation Framework

Install

This CLI App is currently unpublished. To install the CLI

$ git clone <left-hook-scaffold repository> && cd left-hook-scaffold
$ npm i -g 
# The lhs command has been added to your PATH exports

Usage

The left-hook-scaffold CLI framework creates a command line application from a pre-defined schema. Once a schema is defined, the lhs CLI class constructor can be invoked on it to expose the parse method. In your CLI application's bin, simply invoke the CLI parse method on process.argv.slice(2)

#!/usr/bin/env node
/* myPackage/bin/myCLI.js */
const lhs = require("lhs")
const myCLI = new lhs.CLI( <schema> )
CLI.parse(process.argv.slice(2))

NOTE: The expression require("lhs") is currently invalid. Instead, require /lib directly.

Take the example command line input for myCLI:

$ myCLI doSomething -f --someOption someValue

When the myCLI.parse method is invoked, the command line arguments will be formatted in terms of verbs and phrases

   console.log(args)
   /*OUTPUT
   {
      verbs : ["doSomething"],
      phrases : {
         f: true,
         someOption: "someValue"
      }
   }
   */

Schema Definition

To start the schema definition, we must first define a Verb. A Verb reflects a top-level "action" or "command" the CLI user may use.

let lhs = require("lhs")
let test = new lhs.Verb({
   name: "test",
   alias: ["t"],
   operation: (phrases) => {
      console.log("[verb] test:")
   },
   phrases: [
   ]
})

let myCli = new lhs.CLI({
   verbs: [
      test
   ]
})

myCli.parse(process.argv.slice(2))

If this file is in our /bin directory and listed in the package.json bin field, we can now use the test command.

$ myCli test
# output : [verb] test:
$ myCli t
# output : [verb] test:

To add options to our verb, we can add a Phrase to our Verb's phrases array. A Phrase may describe any number of options - a flag, a key:value parameter, or a sub-operation

let echo = new lhs.Phrase({
   name: "echo",
   alias: ["fooEcho", "ech"],
   operation: (phrases) => {
      console.log("[phrase] echo:")
      console.log(phrases)
   }
})

Now that we've declared a echo with a name, alias, and operation, we can reference it from within the verb test's operation. The Phrase method isMemberOf allows us to check whether or not any alias of the echo phrase has been passed in as a command line argument.

The operation of the echo phrase is to simply console.log the phrases passed to it.

let echo = new lhs.Phrase({
   name: "echo",
   alias: ["fooEcho", "ech"],
   operation: (phrases) => {
      console.log("[phrase] echo:")
      console.log(phrases)
   }
})

let test = new lhs.Verb({
   name: "test",
   alias: ["t"],
   operation: (phrases) => {
      console.log("[verb] test:")
      /* if 'echo' or any respective alias is present in the 'phrases' object */
      if (echo.isMemberOf(phrases)) {
         /* invoke the 'echo' operation on the 'phrases`' */
         echo.operation(phrases)
      }
   },
   phrases: [
      echo
   ]
})

let myCli = new lhs.CLI({
   verbs: [
      test
   ]
})

myCli.parse(process.argv.slice(2))

Used in the terminal...

$ myCli test --echo
# output : [verb] test:
#          { echo : true }

Chaining Phrases

We can conditionally chain Phrases to allow us to execute lower level operations. In this example, we use the chalk library to color our output based on command line args.

const lhs = require("../../lib")
const chalk = require("chalk")

let color = new lhs.Phrase({
   name: "color",
   alias: ["col"],
   options: [
      {
         name: "blue",
         operation: (phrases) => {
            console.log(chalk.blue(phrases))
         }
      },
      {
         name: "red",
         operation: (phrases) => {
            console.log(chalk.red(phrases))
         }
      },
      {
         name: "magenta",
         operation: (phrases) => {
            console.log(chalk.magenta(phrases))
         }
      },
   ]
})

let echo = new lhs.Phrase({
   name: "echo",
   alias: ["fooEcho", "ech"],
   description : "Echo command line parameters",
   operation: (phrases) => {
      console.log("[phrase]: echo")
      if (color.isMemberOf(phrases)) {
         let colorOptionValue = color.captureValue(phrases)
         let colorOption = color.getOption(colorOptionValue)
         colorOption.operation(phrases)
      } else {
         console.log(phrases)
      }
   }
})

let test = new lhs.Verb({
   name: "test",
   alias: ["t"],
   operation: (phrases) => {
      console.log("[verb] test:")
      if (echo.isMemberOf(phrases)) {
         echo.operation(phrases)
      }
   },
   phrases: [
      echo
   ]
})

let myCli = new lhs.CLI({
   verbs: [
      test
   ]
})

myCli.parse(process.argv.slice(2))

Used in the terminal...

$ myCli test --echo
# output : [verb] test:
#          { echo : true }
$ myCli test --echo --color blue
# output : [verb] test:
#          [object Object] {{ blue-colored }}
$ myCli test --echo --color red
# output : [verb] test:
#          [object Object] {{ red-colored }}
$ myCli test --echo --color magenta
# output : [verb] test:
#          [object Object] {{ magenta-colored }}