vs-command-parser

VS command parser can be used to simplify command line argument handling. VS command parser can support handling for inline command line arguments with both node index.js {arguments} and npm run command {arguments}. VS command parser can parse inline arguments, inline named arguments, user input, user choice inputs.

Usage

1. Inline command line arguments

   a) Parsing inline argument is tricky as it depends on what sequence user is using. b) It can be marked as true, but user provided sequence only be assigned to options from configuration sequencially. c) Value meant for option 2 can be assigned to option 1, as it was provided in that sequence. d) Recommendation is to use namedOptions.

// module
const VsCommandParser  = require("@vs-org/command-parser").default;

// CJS
import VsCommandParser from "@vs-org/command-parser";

(async () => {
  const commandParser = new VsCommandParser({
    options: {
      1: {
        description: "option 1 description"
      },
      2: {
        description: "option 2 description"
      }
    }
  });

  const ans = await commandParser.parse();
  console.log(ans);
})();



// command
npm run command option1Val opion2Val

// output
{
  '1': {
    value: 'option1Val',
    validationMsg: '',
    description: 'option 1 description'
  },
  '2': {
    value: 'option2Val',
    validationMsg: '',
    description: 'option 2 description'
  }
}

2. Named command line arguments

   a) When using named options, sequence does not matter. b) Keep in mind when spaces are used in option name and value there would be unexpected results if value is empty. c) As long as there is value after space for option it will be properly assigned to option.

// module
const VsCommandParser  = require("@vs-org/command-parser").default;

// CJS
import VsCommandParser from "@vs-org/command-parser";

(async () => {
  const commandParser = new VsCommandParser({
    namedOptions: {
      1: {
        description: "option 1 description"
      },
      2: {
        description: "option 2 description"
      }
    }
  });

  const ans = await commandParser.parse();
  console.log(ans);
})();



// command
npm run command 1=option1Val 2=opion2Val
npm run command 1  =  option1Val 2 =  opion2Val

// output
{
  '1': {
    value: 'option1Val',
    validationMsg: '',
    description: 'option 1 description'
  },
  '2': {
    value: 'option2Val',
    validationMsg: '',
    description: 'option 2 description'
  }
}

// command
npm run command 1=option1Val 2=opion2Val

// Output
{
  '1': { value: 'option1Val', validationMsg: '', description: '' },
  '2': { value: 'option2Val', validationMsg: '', description: '' }
}


// command
npm run command 1  = 2 =  opion2Val

// Output
Throws Error (Error: 1 cannot have 2 as value. If you wish to provide empty value, either use named option at last position or mark this option as not required and don't provide it)

// As value for first named option is name of second option. That is not allowed

3. User input option

   a) If there are some arguments needs an user input like question and answer use this. b) Note blank answer can be provided only for optional questions. If required is true for question command parser will keep on asking question

// module
const VsCommandParser  = require("@vs-org/command-parser").default;

// CJS
import VsCommandParser from "@vs-org/command-parser";

(async () => {
  const commandParser = new VsCommandParser({
    userInputOptions: {
      1: { question: "que 1?", description: "option 1 description" },
      2: { question: "que 2?", description: "option 2 description" }
    }
  });

  const ans = await commandParser.parse();
  console.log(ans);
})();



// command
npm run command

// output without providing any answer
{
  '1': {
    question: 'que 1?',
    value: '',
    description: 'option 1 description',
    validationMsg: ''
  },
  '2': {
    question: 'que 2?',
    value: '',
    description: 'option 2 description',
    validationMsg: ''
  }
}

// With answers
{
  '1': {
    question: 'que 1?',
    value: 'question 1 answer',
    description: 'option 1 description',
    validationMsg: ''
  },
  '2': {
    question: 'que 2?',
    value: 'question 2 answer',
    description: 'option 2 description',
    validationMsg: ''
  }
}

4. User choice option

   a) If there are need for options then use this option. b) User will be presenteed with choices from config.

// module
const VsCommandParser  = require("@vs-org/command-parser").default;

// CJS
import VsCommandParser from "@vs-org/command-parser";

(async () => {
  const commandParser = new VsCommandParser({
    userChoiceOptions: {
      1: {
        question: "que 1?",
        choices: ["choice 1", "choice 2"],
        description: "option 1 description"
      },
      2: {
        question: "que 2?",
        choices: ["choice 1", "choice 2"],
        description: "option 2 description"
      }
    }
  });

  const ans = await commandParser.parse();
  console.log(ans);
})();



// command
npm run command

// output
{
  '1': {
    value: 'choice 1',
    validationMsg: '',
    description: 'option 1 description'
  },
  '2': {
    value: 'choice 2',
    validationMsg: '',
    description: 'option 2 description'
  }
}

5. Help

   a) If description is provided for each option, then it will be used in help command. b) Help is reserved keyword, command parser will throw error when help is used as option key.

6. All options

   a) Note if multiple type of options are needed, keys should be distinct, or else command parser will throw error. b) Follow below example for all inputs

// module
const VsCommandParser  = require("@vs-org/command-parser").default;

// CJS
import VsCommandParser from "@vs-org/command-parser";

(async () => {
  const commandParser = new VsCommandParser({
    options: {
      option1: {
        description: "option 1 description"
      },
      option2: {
        description: "option 2 description"
      }
    },
    namedOptions: {
      namedOptions1: {
        description: "option 1 description"
      },
      namedOptions2: {
        description: "option 2 description"
      }
    },
    userInputOptions: {
      userInputOptions1: {
        question: "que 1?",
        description: "option 1 description"
      },
      userInputOptions2: {
        question: "que 2?",
        description: "option 2 description"
      }
    },
    userChoiceOptions: {
      userChoiceOptions1: {
        question: "que 1?",
        choices: ["choice 1", "choice 2"],
        description: "option 1 description"
      },
      userChoiceOptions2: {
        question: "que 2?",
        choices: ["choice 1", "choice 2"],
        description: "option 2 description"
      }
    }
  });

  const ans = await commandParser.parse();
  console.log(ans);
})();

Options

1. inline argument options

   | option | required | Description | | --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | description | false | String: description, will be used to show help | | transformer | false | Function: value transformer, if provided value processed through function and then returned. You can transform value after parsing as well | | validator | false | Function: Validation function to validate provided value against | | validationMsg | false | String: validation message to return if user provided value is not valid or not provided in case of required option | | required | false | Boolean: flag for required validation |

2. Named argument options

   | option | required | Description | | --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | description | false | String: description, will be used to show help | | transformer | false | Function: value transformer, if provided value processed through function and then returned. You can transform value after parsing as well | | validator | false | Function: validation function to validate provided value against | | validationMsg | false | String: validation message to return if user provided value is not valid or not provided in case of required option | | required | false | Boolean: flag for required validation |

3. User input argument options

   | option | required | Description | | --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | description | false | String: description, will be used to show help | | question | true | String: question which will be presented to user, if it is required then user will be presented question till user provides valid answer | | transformer | false | Function: value transformer, if provided value processed through function and then returned. You can transform value after parsing as well | | validator | false | Function: validation function to validate provided value against | | validationMsg | false | String: validation message to return if user provided value is not valid or not provided in case of required option | | required | false | Boolean: flag for required validation |

4. User choice argument options

   | option | required | Description | | --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | description | false | String: description, will be used to show help | | question | true | String: question which will be presented to user | | choices | true | Array<String>: choices for user to choose from, by default first option will be selected when options are rendered | | transformer | false | Function: value transformer, if provided value processed through function and then returned. You can transform value after parsing as well | | validator | false | Function: validation function to validate provided value against | | validationMsg | false | String: validation message to return if user provided value is not valid or not provided in case of required option | | required | false | Boolean: flag for required validation |

License

MIT (see LICENSE)

Note

This package is tested with each and combined options, but there may be some unexpected errors or responses. Don't use it for critical flows without proper testing.