Defining arguments, commands and flags

In this page we will lay out how certain input is processed and how the parser handles some edge cases.

Defining arguments, commands and flags

We define arguments as any distinct element of a command line command. For example in the command https://madladsquad.com/app hello --world the arguments are hello and --world

Commands are arguments that change the behaviour of your application. The de facto standard for command line interfaces is for commands to be plain words. Commands can also have short forms in the form of single characters. In the previous example, hello would be a command. An example of a short command is npm i where i is equivalent to typing install

Flags are arguments that change the behaviour of one of the current commands. The de facto standard for flags is to prefix them with -- if they are long argumens(like --flag) or with - for short arguments(like -f = --flag). Multiple short flags can be batched into a single argument by adding other flags with short names to the end of a short flag(like -aBcD). A flag has to be tied to a specific command and its purpose is to add customisability to it.

Boolean arguments

Boolean arguments are used to enable or disable an application feature. For example in git clone, the clone command is a boolean command that enables the cloning feature.

We support the following long name syntax for boolean arguments:

bool/--bool - either enables or toggles the underlying boolean flag
bool=true/--bool=true - explicitly sets the boolean to true or false
bool=1/--bool=1 - we also support numbers instead of true or false
bool true/--bool true - try to use the next variable as a boolean literal

We also support the following short arguments:

c/-c - the same as 1
-aBcD - the same as 1
c true/-c true - the same as 4

The following edge cases are handled by defaulting to enabling/toggling the flag:

bool=/--bool=
bool --flag/bool --flag

String arguments

String arguments are arguments that receive a string value. For example: git config user.name my_name where user.name is a string argument.

We support the following long name syntax:

string/--string - uses the default values when specified, otherwise sets an empty string
string=string/--string=string - sets the specified string as the value of the argument
string string/--string string - sets the specifed string as the value of the argument

We also support the following short forms:

s string/-s string

We handle the following edge cases as follows:

--string --flag - same as 1, except when the argument has enabled interpreting flags as strings
string --flag - same as 1, except when the argument has enabled interpreting flags as strings
string --flag --flag-array a b c d -- string - this is a special case where the flags are interpreted until a string is found, so the behaviour is the same as writing string string --flag --flag-array a b c d --.
string=/--string= - same as 1
-sS - same as 1

Array arguments

Array arguments are the same as string arguments, but they accept multiple strings.

We support the following long name syntax:

array a b c d/--array a b c d - Produces the array [a, b, c, d]
array a b c d --/--array a b c d -- - Produces the array [a, b, c, d] and continues parsing any futher arguments
array=a,b,c,d/--array=a,b,c,d - Produces the array [a, b, c, d]
array/--array - uses the default values when specified, otherwise sets an empty array

We also support the following short syntax:

a a b c d or a a b c d -- - Produces the array [a, b, c, d]
a/-a - same as 4
-aABb - same as 4

We also handle the following edge cases:

--array a b c d --flag - The same as 2
array a b c d --flag - The same as 2
array --flag --flag-array a b c d -- a b c d - a special case where the command and flags are interpreted as if the command was array a b c d -- --flag --flag-array a b c d --
array=/--array= - same as 4
array --flag - the same as 4, except when the argument has enabled interpreting flags as strings