Command-Line Arguments

Access command-line arguments using the 's property syntax.

Arguments Properties#

Basic Usage#

a number called argc is arguments's count.
Print "Argument count: ".
Print the argc.

a text called program is arguments's name.
Print "Program name: ".
Print the program.

Accessing User Arguments#

(Get the first argument passed by the user)
If arguments's count is greater than 1 then,
    a text called username is arguments's first,
    Print "Hello, ",
    Print the username.
Otherwise,
    Print "Hello, World!".

Checking if Arguments Were Provided#

If arguments's empty then,
    Print "No arguments provided.".

Dynamic Index Access#

For accessing arguments by a computed index, use the argument at syntax:

a number called i is 2.
a text called val is the argument at the i.

Declarative Flag Parsing#

Vox supports declarative CLI flag parsing with a schema-first style.

1) Declare a flag schema#

Define each supported flag once, including aliases and type:

a flag called verbose is "-v" or "--verbose", it is a boolean.
a flag called output is "-o" or "--output", it is a text.
a flag called retries is "-r" or "--retries", it is a number.

Supported flag value types:

• boolean (presence sets true)
• text (consumes the next token as text)
• number (consumes the next token and parses it as a number)

2) Optional schema modifiers#

Flags may be marked as required and/or given defaults:

a flag called output is "-o" or "--output", it is a text with default "out.txt".
a flag called retries is "-r" or "--retries", it is a number and is required.

• with default ... initializes the flag value if the flag is not passed.
• and is required requires the flag to be present at runtime.
• A flag with no with default that is not passed holds its type's empty value: "" for a text, 0 for a number, and false for a boolean. An unsupplied text flag is therefore safe to read, and can be tested with is empty.

3) Parse point: explicit or automatic#

You can parse flags explicitly:

Parse flags.

Or omit it. If omitted, Vox inserts parsing automatically immediately after the last flag schema declaration.

4) Placement rules#

Flag schema declarations are valid as long as they appear before parsing occurs.

• You may place normal code before/between schema declarations.
• You may use explicit Parse flags. to choose exactly when parsing happens.
• Declaring new schemas after Parse flags. is a compile-time error.
• Using flag variables before the parse point is a compile-time error.

5) arguments's all vs arguments's raw#

After parsing:

• arguments's all is the filtered positional argument view (recognized flags removed).
• arguments's raw keeps the original user-provided argument sequence unchanged.

Example:

a flag called verbose is "-v" or "--verbose", it is a boolean.
a flag called output is "-o" or "--output", it is a text with default "out.txt".
Parse flags.

Print "output:{output}".

Print "ALL".
Print each item from arguments's all.

Print "RAW".
Print each item from arguments's raw.

6) Unix -- separator#

-- stops flag processing. Tokens after -- are treated as positional arguments.

Example invocation:

myprog --verbose -- -v file.txt

In this case:

• --verbose is parsed as a flag
• -v after -- is treated as a normal positional argument

7) Practical pattern#

a flag called help is "-h" or "--help", it is a boolean.
a flag called 'version' is "-V" or "--version", it is a boolean.
a flag called 'number' is "-n" or "--number", it is a boolean.

Parse flags.

If help then,
    Print "Usage: myprog [options] [files]".

If 'version' then,
    Print "myprog 1.0.0".

Print each item from arguments's all.