Available Macros

@...arguments

The @...arguments begin ... end block will hold all of your ArgMacros code. The Using Argument Values section provides a good comparison of the different available macros.

ArgMacros.@inlineargumentsMacro
@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
source
ArgMacros.@structargumentsMacro
@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
source
ArgMacros.@tupleargumentsMacro
@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
source
ArgMacros.@dictargumentsMacro
@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
source

Option Arguments

These arguments are specified by long and/or short flags (e.g. -v, --verbose), and all follow a similar format. It is important to put these before positional arguments. Additionally, it is recommended to specify the short flag first when using multiple flags.

ArgMacros.@argumentrequiredMacro
@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
source
ArgMacros.@argumentdefaultMacro
@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
source
ArgMacros.@argumentoptionalMacro
@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
source
ArgMacros.@argumentflagMacro
@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
source
ArgMacros.@argumentcountMacro
@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
source

Positional Arguments

These arguments are specified by their position in the command. You must specify these in your code in the same order that users are expected to enter them. It is important to put these after all option arguments, and specify the required positional arguments first. If you want to specify leftover positional arguments, they must come after all other arguments.

ArgMacros.@positionalrequiredMacro
@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
source
ArgMacros.@positionaldefaultMacro
@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
source
ArgMacros.@positionaloptionalMacro
@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
source
ArgMacros.@positionalleftoverMacro
@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
source

Help Options

These macros are used to generate the help screen for your program. Note that usage will NOT be automatically generated if it is unspecified.

@helpusage, @helpdescription, and @helpepilog can be placed anywhere in the @beginarguments block with identical effect. However, placing them in that order at the beginning of the block is recommended.

@arghelp, however, will always apply to the last argument declared before it appears.

ArgMacros.@helpusageMacro
@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
source
ArgMacros.@helpdescriptionMacro
@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
source
ArgMacros.@helpepilogMacro
@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
source
ArgMacros.@arghelpMacro
@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
source

Additional Options

These options can be used to validate argument values or change parsing behavior.

It is recommended to place @argtest immediately after the argument it applies to, and @allowextraarguments before or after all of the arguments are declared.

ArgMacros.@argtestMacro
@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
source
ArgMacros.@allowextraargumentsMacro
@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
source

Index