Performant, macro-only, pure Julia package for parsing command line arguments. Uses macros to generate the parsing code within your main function, directly storing results in typed local variables.

Basic usage:

julia_main()
    @inlinearguments begin
        @argumentrequired Int foo "-f" "--foo"
        @argumentdefault Int 5 bar "-b" "--bar"
        ...
        @positionalrequired String baz
        ...
        @positionaloptional String anotheroption
    end

    x::Int = foo + bar # required and default values are typed and completely type stable
    y::String = baz * something(anotheroption, "optional arguments may have nothing value")
    ...
end

See the documentation before using.

Hold information to print an argument

Hold information to print entire help screen

If x is not a string (i.e. literal passed as default) assume direct conversion is possible. Does NOT validate.

Quit program if the value is nothing

Convert string to Number type with parse or other type with direct conversion.

Convert a vector of strings to Number type with parse or other types with direct conversions

Extract name of macro and change from ArgMacros.@... to @...

Find the index of the (first) occurrence of one of the specified flags in args

Extract name => type pair from argument macrocall expression

Extract name => type pairs for all argument macros in block

Get the macrocall expressions from a block as a generator

Check for -h/–help flag, end program and print help if needed

Assemble the Help struct from the macro contents

Remove the option and value for any flag in flags and return the given value

Remove multiple occurrences of flag from args and return the count removed

Remove a flag if present and return whether the flag was found

Print a message, ask user to try –help, and exit the program

Split the arguments into a usable form with separated tokens

Split up multiple flag arguments, e.g. "-zx-v2f" → ["-z", "-x", "-v", "2", "-f"]

Ensure flags is not empty and that no flag overlaps with those used by help

Enforce argument declaration ordering: Flagged → Required Positional → Optional Positional → Leftover Positional

Throw ArgumentError if ordering violates this rule.

@allowextraarguments

Disables the default behavior of printing a message and exiting the program when not all values in ARGS could be assigned to specified arguments.

This will not capture any arguments, use @positionalleftover if you want to capture extra arguments that could not otherwise be assigned.

Must be used in @beginarguments begin ... end block

Example

@beginarguments begin
    ...
    @allowextraarguments
end

@arghelp help_text::String

Add help string for an argument. Applied to the preceding declared argument

Must be used in @beginarguments begin ... end block

Example

@beginarguments begin
    ...
    @argumentflag v "-v" "--verbose"
    @arghelp "Display additional output"
    ...
end

@argtest argname func [desc]

Apply func to the value stored in argname, printing an error message (optionally specified by desc) and the program if func returns false. Test skipped if argname has value nothing (only possible for optional arguments). This macro must be used AFTER declaring the arugment with another macro.

Must be used in @beginarguments begin ... end block

Example

@beginarguments begin
    ...
    @positionalrequired String input_file
    @argtest input_file isfile "Couldn't find the input file."
    ...
end

@argumentcount local_name flag::String

Store the number of occurrences of flag in local_name with type Int.

Must be used in @beginarguments begin ... end block

Example

@beginarguments begin
    ...
    @argumentcount verbose "-v"
    ...
end

@argumentdefault type default_value local_name flags::String...

Attempt to get an argument specified by the given flags and store in the variable local_name with the specified type. Store the default value instead if the flags cannot be found. Default value automatically converted to specified type.

Must be used in @beginarguments begin ... end block

Example

@beginarguments begin
    ...
    @argumentdefault String "output.txt" output_file "-o" "--output"
    ...
end

@argumentflag local_name flags::String...

Store true in the variable local_name with type Bool if one or more of the flags is found. Otherwise, store false.

Must be used in @beginarguments begin ... end block

Example

@beginarguments begin
    ...
    @argumentflag verbose "-v" "--verbose"
    ...
end

@argumentoptional type local_name flags::String...

Attempt to get an argument specified by the given flags and store in the variable local_name with the type Union{type, Nothing}. Store nothing if the flags cannot be found.

Must be used in @beginarguments begin ... end block

Example

@beginarguments begin
    ...
    @argumentoptional String output_file "-o" "--output"
    ...
end

@argumentrequired type local_name flags::String...

Get a required argument specified by the given flags and store in the variable local_name with the specified type.

Print a message and exit the program if the value is not found or cannot be converted to the specified type.

Must be used in @beginarguments begin ... end block

Example

@beginarguments begin
    ...
    @argumentrequired String output_file "-o" "--output"
    ...
end

@beginarguments begin ... end

This macro is deprecated beginning in ArgMacros v0.2.0 Please use @inlinearguments, which has the same interface Or consider @structarguments, @tuplearguments, and @dictarguments depending on your use case

@dictarguments begin ... end

Denote and setup a block with other macros from ArgMacros Return a Dict with the arguments instead of dumping them in the enclosing namespace

Example

function julia_main()
    args = @dictarguments begin
        ...
        @argumentrequired Int foo "-f" "--foo"
        @argumentdefault Int 5 bar "-b" "--bar"
        ...
    end
    ...
end

@helpdescription description::String

Add description for the help screen

Must be used in @beginarguments begin ... end block

Example

@beginarguments begin
    ...
    @helpdescription "Lorem ipsum dolor sit amet"
    ...
end

@helpepilog epilog::String

Add epilog for the help screen, displayed after rest of help

Must be used in @beginarguments begin ... end block

Example

@beginarguments begin
    ...
    @helpepilog "Lorem ipsum dolor sit amet"
    ...
end

@helpusage usage_text::String

Add usage text for the help screen Automatically prepended with "Usage: "

Must be used in @beginarguments begin ... end block

Example

@beginarguments begin
    @helpusage "example.jl foo [bar] [-v]"
    ...
end

@inlinearguments begin ... end

Denote and setup a block with other macros from ArgMacros

Example

function julia_main()
    @inlinearguments begin
        ...
        @argumentrequired Int foo "-f" "--foo"
        @argumentdefault Int 5 bar "-b" "--bar"
        ...
    end
    ...
end

@positionaldefault type default_value local_name [help_name::String]

Attempt to get a positional argument and store in variable local_name with the specified type. Store the default value instead if an argument cannot be found.

Positional arguments are read in order after all flag/option arguments have been read. help_name used instead of local_name in messages to user if specified.

Default value automatically converted to specified type.

Must be used in @beginarguments begin ... end block

Example

@beginarguments begin
    ...
    @positionaldefault String output_file "output"
    ...
end

@positionalleftover type local_name [help_name]

Get any leftover positional arguments after all other arguments have been parsed, and store in variable local_name with the type Vector{type}. This vector will be empty if there are no leftover arguments.

This macro must be used after all other arguments have been declared, as positional arguments are read in order after all flag/option arguments have been read. Using this macro means all input will be captured by this argument if not by another, so @allowextraarguments is not necesesary when this macro is used. help_name used instead of local_name in messages to user if specified.

Must be used in @beginarguments begin ... end block

Example

@beginarguments begin
    ...
    @positionalleftover String file_names "files"
    ...
end

@positionaloptional type local_name [help_name]

Attempt to get a positional argument and store in variable local_name with the type Union{type, Nothing}. Store nothing if an argument is not found.

Positional arguments are read in order after all flag/option arguments have been read. help_name used instead of local_name in messages to user if specified.

Must be used in @beginarguments begin ... end block

Example

@beginarguments begin
    ...
    @positionaloptional String output_file "output"
    ...
end

@positionalrequired type local_name [help_name::String]

Attempt to get a positional argument and store in variable local_name with the specified type.

Positional arguments are read in order after all flag/option arguments have been read. help_name used instead of local_name in messages to user if specified.

Print a message and exit the program if a value is not found or cannot be converted to the specified type.

Must be used in @beginarguments begin ... end block

Example

@beginarguments begin
    ...
    @positionalrequired String output_file "output"
    ...
end

@structarguments mutable typename begin ... end

Denote and setup a block with other macros from ArgMacros Defines an optionally mutable struct type based on the arguments and a zero-argument constructor which will generate an instance of the struct based on the parsed arguments.

Example

@structarguments false Args begin
    ...
    @argumentrequired Int foo "-f" "--foo"
    @argumentdefault Int 5 bar "-b" "--bar"
    ...
end

function julia_main()
    args = Args()
    ...
end

@tuplearguments begin ... end

Denote and setup a block with other macros from ArgMacros Return a NamedTuple with the arguments instead of dumping them in the enclosing namespace

Example

function julia_main()
    args = @tuplearguments begin
        ...
        @argumentrequired Int foo "-f" "--foo"
        @argumentdefault Int 5 bar "-b" "--bar"
        ...
    end
    ...
end