Skip to content

EXAMPLES.md

Latest commit

 

History

History
279 lines (205 loc) · 6.73 KB

EXAMPLES.md

File metadata and controls

279 lines (205 loc) · 6.73 KB

Examples

Positional

mycmd aaa bbb
Declared Arg Value
arg1: str aaa
arg2: str bbb

Flags

mycmd aaa --arg2 bbb -c ddd -f
Declared Arg Value
arg1: str aaa
arg2: str bbb
arg3: str, short c ddd
arg4: bool, short f true

Positional slots assigned left to right

mycmd --arg1=aaa bbb  # assigns 'bbb' to 'arg2' because 'arg1' already assigned
Declared Arg Value
arg1: str aaa
arg2: str bbb 
mycmd aaa --arg1=bbb  # 'aaa' first gets assigned positionally to 'arg1', and then overridden by 'bbb'.
Declared Arg Value
arg1: str bbb
arg2: str undefined, error because both inputs go to assigning arg1.

Short clusters (bools)

mycmd -bcd aaa  # since flags are bools, 'aaa' gets interpreted as the first positional arg
Declared Arg Value
arg1: str aaa
arg2: bool, short b true
arg3: bool, short c true
arg4: bool, short d true
arg5: bool, short e false

Short clusters can end with non-bool

mycmd -abc ddd  # last flag 'c' is a non-bool and so will read 'ddd'
Declared Arg Value
arg1: bool, short a true
arg2: bool, short b true
arg3: str, short c ddd

Incrementing int shorts

Int and Int64 flags support clustered short flag counting:

  • When the same short flag is repeated (e.g., -vvv), the value is set to the count of repetitions
  • Explicit values override counting (e.g., -vvv=10 sets value to 10, not 3)
  • Later occurrences override earlier ones (e.g., -vv -v 5 sets value to 5)

Basic counting:

mycmd -aaa
Declared Arg Value
arg1: int, short a, default 0 3

Single flag with explicit value:

mycmd -a 3
Declared Arg Value
arg1: int, short a, default 0 3

Counting with two repetitions:

mycmd -aa
Declared Arg Value
arg1: int, short a, default 0 2

Explicit value overrides counting:

mycmd -aaa=10
Declared Arg Value
arg1: int, short a, default 0 10

Int64 flags work the same way:

mycmd -nnn
Declared Arg Value
arg1: int64, short n, default 0 3

Error case - non-integer value:

mycmd -a bbb
Declared Arg Value
arg1: int, short a, default 0 ?
arg2: str ?

Negative numbers

mycmd -1 --arg2 -2 -3.4
Declared Arg Value
arg1: int -1
arg2: int -2
arg3: float -3.4

Number shorts enables 'number shorts mode'

If any arg defines an int short, we enter 'number shorts mode'. This means that any standalone int flags are always interpreted as flags, not negative ints. In this mode, you can only pass negative ints as values to arguments by using =.

mycmd --arg1=-2 -2 aaa -a bbb ccc
Declared Arg Value
arg1: int -2
arg2: str, short 2 aaa
arg3: int ccc
arg4: str, short a bbb

Take the below alternative invocation.

mycmd --arg1 -2 -2 aaa -a bbb ccc

This is invalid. Because the -2 is interpreted as a short flag in both instances, the initial --arg1 doesn't have a corresponding value, nor does the -2 that follows.

In other words, number shorts mode is a more restrictive mode to avoid ambiguities and mistakes caused by the conflicting use cases of having int flags and passing negative ints as args to a script.

When no int shorts are defined, number shorts mode remains disabled, meaning any "int flags" are interpreted as negative integer values.

Positional variadic

The last positional arg can be a variadic. If nothing is read into it, it will be an empty slice.

mycmd aaa
Declared Arg Value
arg1: str aaa
arg2: str, variadic [ ] 
mycmd aaa bbb
Declared Arg Value
arg1: str aaa
arg2: str, variadic [ bbb ] 
mycmd aaa bbb ccc
Declared Arg Value
arg1: str aaa
arg2: str, variadic [ bbb, ccc ]

Variadic flags

mycmd aaa --arg2  # Can be specified as a flag, even with no arguments
Declared Arg Value
arg1: str aaa
arg2: str, variadic [ ] 
mycmd aaa --arg2 bbb ccc
Declared Arg Value
arg1: str aaa
arg2: str, variadic [ bbb, ccc ] 
mycmd --arg2 aaa bbb --arg1 ccc  # Vararg reads until the next flag
Declared Arg Value
arg1: str ccc
arg2: str, variadic [ aaa, bbb ]

Multiple Variadics

Input args will be assigned to the first var arg declaration the parser encounters, or until it reaches a new flag. A new flag could be another variadic arg, repeating the same logic again.

mycmd aaa bbb --arg2 ccc ddd -e fff
Declared Arg Value
arg1: str, variadic [ aaa, bbb ]
arg2: str, variadic [ ccc, ddd]
arg3: bool, short e true
arg4: str fff

Here, we consume ccc and ddd and assign them to arg2, but its variadic is then ended by -e. We then read fff, check to see our next unfilled positional arg (arg4), and assign to that.