Vcommand-parser NPM

VCommandParser

npm bundle size

Typescript / Javascript string parser to deal with command-like messages

This package takes a string and separates the content into different components to easily parse commands. This allows you to easily get the specified command, the options, the options contents, and even specify if a option allows content or not.

Installation

npm install vcommand-parser

Basic Usage

Parsing string / message

To use this utility, you can simply use the static functions provided by the VCommandParser class :

import parseMessage from 'vcommand-parser';

const parsedCommand = parseMessage('!command');

import parseMessage from 'vcommand-parser';

const parsedCommand = parseMessage('!command --option');

import parseMessage from 'vcommand-parser';

const parsedCommand = parseMessage('!command -abc');

In the last example above, there is three "short" options : ["a", "b", "c"].

The default function parseMessage is an alias of the VCommandParser.parse static method. You can achieve the same result with this notation, depending on your preferences :

import { VCommandParser } from 'vcommand-parser';

const parsedCommand = VCommandParser.parse('!command');

The default command prefix is ! and the default option prefix is -, which are both configurable, as shown below :

import { VCommandParser } from 'vcommand-parser';

const parsedCommand = VCommandParser.parse('\\command', {
    commandPrefix: '\\'
});

import { VCommandParser } from 'vcommand-parser';

const parsedCommand = VCommandParser.parse('\\command ~~option', {
    commandPrefix: '\\',
    optionPrefix: '~'
});

import { VCommandParser } from 'vcommand-parser';

const parsedCommand = VCommandParser.parse('\\command ~abc', {
    commandPrefix: '\\',
    optionPrefix: '~'
});

Dealing with parsed object

import { VCommandParser } from 'vcommand-parser';

const parsedCommand = VCommandParser.parse('!command --option');

console.log(parsedCommand);

The variable parsedCommand therefore contains this :

VParsedCommand {
  message: '!command --option',
  commandPrefix: '!',
  optionPrefix: '-',
  optionDefinitions: undefined,
  isCommand: true,
  command: 'command',
  content: undefined,
  options: [
    MessageOption {
      name: 'option',
      content: undefined,
      position: 0,
      definition: undefined
    }
  ],
  duplicatedOptions: undefined,
  fullContent: '--option'
}

Dealing with parsed object and content

import { VCommandParser } from 'vcommand-parser';

const parsedCommand = VCommandParser.parse('!command content --option "option content"');

console.log(parsedCommand);

The variable parsedCommand therefore contains this :

VParsedCommand {
  message: '!command content --option "option content"',
  commandPrefix: '!',
  optionPrefix: '-',
  optionDefinitions: undefined,
  isCommand: true,
  command: 'command',
  content: 'content',
  options: [
    MessageOption {
      name: 'option',
      content: 'option content',
      position: 0,
      definition: undefined
    }
  ],
  duplicatedOptions: undefined,
  fullContent: 'content --option "option content"'
}

Note in this example : since "option content" has a space in its content, you must pad the content with double or single quotes (" or '). This quoting behavior is handled by the package quoted-string-space-split.

Accessing options

import { VCommandParser } from 'vcommand-parser';

const parsedCommand = VCommandParser.parse('!command content --option "option content"');

const option = parsedCommand.getOption('option');

console.log(option);

The variable option therefore contains this :

MessageOption {
  name: 'option',
  content: 'option content',
  position: 0,
  definition: undefined
}

Usage with Option Definitions

This package allows to define options so that you can have option aliases, descriptions, and even custom behavior (such as "does the option accepts content?").

This is achieved using the OptionDef class. This class has 2 parameters, where the second parameter is optional parameters that defines the option :

new OptionDef(calls: string | string[], options?: {
  description: string | undefined,
  acceptsContent: boolean, // defaults to true
  weight: number // defaults to `OptionDef.DEFAULT_WEIGHT` (0)
})

There are two main ways of defining option definitions : at the parsing stage or in a lazy way :

Defining options at the parsing stage

import { VCommandParser, OptionDef } from 'vcommand-parser';

const definitions = [
  new OptionDef(['l', 'long'], {description: 'This is my long description', weight: 1}),
  new OptionDef(['s', 'short'], {description: 'This is my short description', weight: 2})
];

const parsedCommand = VCommandParser.parse('!command content -l "option content"', {optionDefinitions: definitions});

console.log(parsedCommand);

The variable parsedCommand therefore contains this :

VParsedCommand {
  message: '!command content -l "option content"',
  commandPrefix: '!',
  optionPrefix: '-',
  optionDefinitions: [
    OptionDef {
      calls: ['l', 'long'],
      acceptsContent: true,
      description: 'This is my long description',
      weight: 1
    },
    OptionDef {
      calls: ['s', 'short'],
      acceptsContent: true,
      description: 'This is my short description',
      weight: 2
    }
  ],
  isCommand: true,
  command: 'command',
  content: 'content',
  options: [
    MessageOption {
      name: 'l',
      content: 'option content',
      position: 0,
      definition: OptionDef {
        calls: [ 'l', 'long' ],
        acceptsContent: true,
        description: 'This is my long description',
        weight: 1
      }
    }
  ],
  duplicatedOptions: undefined,
  fullContent: 'content -l "option content"'
}

The definition is linked to the parsed option, which is useful if you need to access the option's description, weight, etc.

This definition also allows you to define multiple possible calls for the option, so in the previous example, it wouldn't matter if you used -l or --long, as the definition defines both. Please note that the calls will always be an array, but you can define an OptionDef using a single string, such as :

new OptionDef('l', {description: 'This is my long description', acceptsContent: true, weight: 1})

Defining options lazily

You may sometimes prefer to define the definitions after a basic parsing to get the command name and potentially the content too. You can therefore use the option lazy to get this behavior :

import { VCommandParser, OptionDef } from 'vcommand-parser';

const definitions = [
  new OptionDef(['l', 'long'], {description: 'This is my long description', weight: 1}),
  new OptionDef(['s', 'short'], {description: 'This is my short description', weight: 2})
];

const parsedCommand = VCommandParser.parse('!command content -l "option content"', {lazy: true});

console.log(parsedCommand.command); // 'command'
console.log(parsedCommand.content); // 'content -l "option content"'
console.log(parsedCommand.options); // undefined

parsedCommand.setOptionDefinitions(definitions);

console.log(parsedCommand.command); // 'command'
console.log(parsedCommand.content); // 'content'
console.log(parsedCommand.options); // MessageOption[]

console.log(parsedCommand);

The variable parsedCommand will therefore contain the same definitions as if you didn't do it lazy.

Usage for strings / messages that are not commands

This package automatically determines if the given string is a command or not based on if the messages starts with the given command prefix.

import { VCommandParser } from 'vcommand-parser';

const parsedCommand = VCommandParser.parse('this is a message');

console.log(parsedCommand);

VParsedCommand {
  message: 'this is a message',
  commandPrefix: '!',
  optionPrefix: '-',
  optionDefinitions: undefined,
  isCommand: false,
  command: undefined,
  content: 'this is a message',
  options: undefined,
  duplicatedOptions: undefined,
  fullContent: 'this is a message'
}

When the message is not a command, options aren't parsed :

import { VCommandParser } from 'vcommand-parser';

const parsedCommand = VCommandParser.parse('this is --a message');

console.log(parsedCommand);

VParsedCommand {
  message: 'this is --a message',
  commandPrefix: '!',
  optionPrefix: '-',
  optionDefinitions: undefined,
  isCommand: false,
  command: undefined,
  content: 'this is --a message',
  options: undefined,
  duplicatedOptions: undefined,
  fullContent: 'this is --a message'
}