arment v1.0.1

Arment

A node.js command line parser and checker

Introduction

This is a module that parses command line arguments.

Forget those type checks and the comprobation of mandatory arguments. Even the manual documentation is automatically generated.

Lazier to use, easier to read.

Install

npm install arment --save

Usage Examples

Basic example

const arment = require("arment");

//We add the arguments and its config!
arment
    .add("name", ["n", "name"], { desc: "Human name" })
    .catch((errs) => {
        if(errs.length) console.log(errs[0].message);
        process.exit(-1);
    });
console.log(arment.args.name);

Full example

const arment = require("arment");

//function to call when the parameter is used on the command line
const showEaterType = (food) => {
    if (food === "meat") console.log("It is indeed carnivore!");
    else console.log("It is indeed NOT carnivore!");
};

const showManual = (help) => {
    if(help){
        arment.show();
        process.exit(0);
    }
}

//We add the arguments and its config!
arment
    .add("type", [0], { optional: false, desc: "Animal type" })
    .add("name", ["n", "name"], { type: arment.TYPES.STRING, defaultValue: "Mark", desc: "Animal name" })
    .add("legs", ["nLegs"], { type: arment.TYPES.NUMBER, defaultValue: 2, desc: "Number of legs" })
    .add("food", ["f", "nomnom"], { type: arment.TYPES.STRING, desc: "Food for nom", func: showEaterType })
    .add("help", ["h", "help"], { desc: "Displays help manual", func: showManual })
    .catch((errs) => {
        if(errs.length) console.log(errs[0].message);
        process.exit(-1);
    });
//and done!

//every argument we added can be used via arment.args
console.log(arment.args.type);
console.log(arment.args.name);
console.log(arment.args.legs);
console.log(arment.args.food);

//To get the documentation 
//arment.show();
/**
 * Usage:
 * node file.js <type> [options]
 * node file.js <type> [-n|--name <string>] [--nLegs <number>] [-f|--nomnom <string>] [-h|--help <any>]
 *
 * Options: 
 * -n --name <string>
 *                         Animal name [default: Mark]
 * --nLegs <number>
 *                         Number of legs of the animal [default: 2]
 * -f --nomnom <string>
 *                         Food for nom 
 * -h --help <any>
 *                         Displays help manual 
 */

Usage

add

This is the main tool with arment, just set your variables, and arment will take care of them.

Variables are created in order, therefore its recommendable to add the manual as the last one if you execute show whitin the ArmentOption 'func'.

Any variable added with add will be parsed and saved on the args property.

Since it returns the arment object, they can be chained, even ending with a catch.

When you want to use an unflagged argument keys must be an array with only one number, wich will be the position on the notFlags array in parsedArgs.

• Example unflagged argument

  arment.add("first", [0]);

• Example flagged arguments

  //this will take into account -n and --number
  arment.add("number", ["n","number"]);

• Example mandatory argument

  arment.add("number", ["n"], { optional: false });

• Example number argument

  arment.add("number", ["n"], { type: arment.TYPES.NUMBER });

• Example number argument with default value

  arment.add("number", ["n"], { type: arment.TYPES.NUMBER, defaultValue: 3 });

• Example argument with description

  arment.add("number", ["n"], { desc: "This is a number if you set it!" });

• Example argument with function

  arment.add("number", ["n"], { func: (value)=>console.log(\`In number argument, received ${value}\`) });

• Example typical manual

  const showManual = (help) => {
      if(help){
          arment.show();
          process.exit(0);
      }
  }

  arment.add("help", ["h", "help"], { desc: "Displays help manual", func: showManual })

ArmentOptions

show

When this function is called, a manual for the script arguments defined with add will be shown via the output function.

//node file.js --nomnom cheese

arment.add("food", ["f", "nomnom"]);

arment.show();
/**
 * Usage:
 * node file.js [options]
 * node file.js [-f|--nomnom <string>]
 *
 * Options: 
 * -f --nomnom <string>
 *                         Food for nom 
 */

parsedArgs

When arment is required, will automatically read the command line arguments.

You can get them parsed in an object with the parsedArgs property.

//node script.js argument -l --banana 

console.log(arment.parsedArgs); //{ notFlags: ["argument"], banana: true }

All arguments passed without flag, will be pushed to the notFlags array

TYPES

In order to parse, arment has a set of variable types to parse the argument when indicated.

You can get the possible types in an object with the TYPES property.

console.log(arment.TYPES);
/**
*{
*    ANY: "any",
*    BOOLEAN: "boolean",
*    STRING: "string",
*    NUMBER: "number",
*    DATE: "date",
*    OBJECT: "object",
*    ARRAY: "array",
*}
*/

args

Whenever you add a new arment variable, its name parameter will be added to the args property with its value.

//node file.js --nomnom cheese

arment
    .add("food", ["f", "nomnom"]);

console.log(arment.args);//{ food: "cheese" } 

catch

Whenever you add a new arment variable, it will be checked with its ArmentOptions. If certain variable conditions are not met, errors will be generated.

Cases:

• A variable is set to non optional and no value was found
• A variable value could not be parsed to the defined type from TYPES

Returns an array of errors.

arment.catch((errs) => {
    if(errs.length) console.log(errs[0].message);
    process.exit(-1);
});

output

This is the function that will be used when show is called.

Default function is 'console.log'. You can set your custom output function with its setter.

const showText= (text) => {
    console.log("This is my manual!");
    console.log(text);
    process.exit(-1);
};

arment.output = showText;

License

MIT