The problem with other option parsers, such as yargs or minimist, is they just accept all input, valid or not.
With Optionator, if you mistype an option, it will give you an error (with a suggestion for what you meant).
If you give the wrong type of argument for an option, it will give you an error rather than supplying the wrong input to your application.

Over helpful features include reformatting the help text based on the size of the console, so that it fits even if the console is narrow, and accepting not just an array (eg. process.argv), but a string or object as well, making things like testing much easier.

require('optionator'); returns a function. It has one property, VERSION, the current version of the library as a string. This function is called with an object specifying your options and other information, see the settings format section. This in turn returns an object with three properties, parse, generateHelp, and generateHelpForOption, which are all functions.

Object - the parsed options, each key is a camelCase version of the option name (specified in dash-case), and each value is the processed value for that option. Positional values are in an array under the _ key.

showHidden specifies whether to show options with hidden: true specified, by default it is false

interpolate specify data to be interpolated in prepend and append text, {{key}} is the format - eg. generateHelp({interpolate:{version: '0.4.2'}}), will change this append text: Version {{version}} to Version 0.4.2

generateHelpForOption produces expanded help text for the specified with optionName option. If an example was specified for the option, it will be displayed, and if a longDescription was specified, it will display that instead of the description.

prepend is an optional string to be placed before the options in the help text

append is an optional string to be placed after the options in the help text

options is a required array specifying your options and headings, the options and headings will be displayed in the order specified

helpStyle is an optional object which enables you to change the default appearance of some aspects of the help text

mutuallyExclusive is an optional array of arrays of either strings or arrays of strings. The top level array is a list of rules, each rule is a list of elements - each element can be either a string (the name of an option), or a list of strings (a group of option names) - there will be an error if more than one element is present

concatRepeatedArrays is an optional boolean (defaults to false) - when set to true and an option contains an array value and is repeated, the subsequent values for the flag will be appended rather than overwriting the original value - eg. option g of type [String]: -g a -g b -g c,d will result in ['a','b','c','d']

mergeRepeatedObjects is an optional boolean (defaults to false) - when set to true and an option contains an object value and is repeated, the subsequent values for the flag will be merged rather than overwriting the original value - eg. option g of type Object: -g a:1 -g b:2 -g c:3,d:4 will result in {a: 1, b: 2, c: 3, d: 4}

positionalAnywhere is an optional boolean (defaults to true) - when true it allows positional arguments anywhere, when false, all arguments after the first positional one are taken to be positional as well, even if they look like a flag. For example, with positionalAnywhere: false, the arguments --flag --boom 12 --crack would have two positional arguments: 12 and --crack

defaults is an optional object following the option properties format, which specifies default values for all options. A default will be overridden if manually set. For example, you can do default: { type: "String" } to set the default type of all options to String, and then override that default in an individual option by setting the type property

option the required name of the option - use dash-case, without the leading dashes

alias is an optional string or array of strings which specify any aliases for the option

type is a required string in the type checkformat, this will be used to cast the inputted value and validate it

enum is an optional array of strings, each string will be parsed by levn - the argument value must be one of the resulting values - each potential value must validate against the specified type

default is a optional string, which will be parsed by levn and used as the default value if none is set - the value must validate against the specified type

restPositional is an optional boolean - if set to true, everything after the option will be taken to be a positional argument, even if it looks like a named argument

required is an optional boolean - if set to true, the option parsing will fail if the option is not defined

overrideRequired is a optional boolean - if set to true and the option is used, and there is another option which is required but not set, it will override the need for the required option and there will be no error - this is useful if you have required options and want to use --help or --version flags

concatRepeatedArrays an optional boolean - same as the description in the Top Level Properties description, but just for this option, not all of them

mergeRepeatedObjects an optional boolean - same as the description in the Top Level Properties description, but just for this option, not all of them

dependsOn is an optional string or array of strings - if simply a string (the name of another option), it will make sure that that other option is set, if an array of strings, depending on whether 'and' or 'or' is first, it will either check whether all (['and', 'option-a', 'option-b']), or at least one (['or', 'option-a', 'option-b']) other options are set

description is an optional string, which will be displayed next to the option in the help text

longDescription is an optional string, it will be displayed instead of the description when generateHelpForOption is used

example is an optional string or array of strings with example(s) for the option - these will be displayed when generateHelpForOption is used

At the highest level there are two types of arguments: named, and positional.

Name arguments of any length are prefixed with -- (eg. --go), and those of one character may be prefixed with either -- or - (eg. -g).

There are two types of named arguments: boolean flags (eg. --problemo, -p) which take no value and result in a true if they are present, the falsey undefined if they are not present, or false if present and explicitly prefixed with no (eg. --no-problemo). Named arguments with values (eg. --tseries 800, -t 800) are the other type. If the option has a type Boolean it will automatically be made into a boolean flag. Any other type results in a named argument that takes a value.

For more information about how to properly set types to get the value you want, take a look at the type check and levn pages.

You can group single character arguments that use a single -, however all except the last must be boolean flags (which take no value). The last may be a boolean flag, or an argument which takes a value - eg. -ba 2 is equivalent to -b -a 2.

Positional arguments are all those values which do not fall under the above - they can be anywhere, not just at the end. For example, in cmd -b one -a 2 two where b is a boolean flag, and a has the type Number, there are two positional arguments, one and two.

Everything after an -- is positional, even if it looks like a named argument.

You may optionally use = to separate option names from values, for example: --count=2.

If you specify the option NUM, then any argument using a single - followed by a number will be valid and will set the value of NUM. Eg. -2 will be parsed into NUM: 2.

optionator is written in LiveScript - a language that compiles to JavaScript. It uses levn to cast arguments to their specified type, and uses type-check to validate values. It also uses the prelude.ls library.