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.@inlinearguments
— Macro@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
ArgMacros.@structarguments
— Macro@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
ArgMacros.@tuplearguments
— Macro@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
ArgMacros.@dictarguments
— Macro@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
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.@argumentrequired
— Macro@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
ArgMacros.@argumentdefault
— Macro@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
ArgMacros.@argumentoptional
— Macro@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
ArgMacros.@argumentflag
— Macro@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
ArgMacros.@argumentcount
— Macro@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
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.@positionalrequired
— Macro@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
ArgMacros.@positionaldefault
— Macro@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
ArgMacros.@positionaloptional
— Macro@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
ArgMacros.@positionalleftover
— Macro@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
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.@helpusage
— Macro@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
ArgMacros.@helpdescription
— Macro@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
ArgMacros.@helpepilog
— Macro@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
ArgMacros.@arghelp
— Macro@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
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.@argtest
— Macro@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
ArgMacros.@allowextraarguments
— Macro@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
Index
ArgMacros.@allowextraarguments
ArgMacros.@arghelp
ArgMacros.@argtest
ArgMacros.@argumentcount
ArgMacros.@argumentdefault
ArgMacros.@argumentflag
ArgMacros.@argumentoptional
ArgMacros.@argumentrequired
ArgMacros.@dictarguments
ArgMacros.@helpdescription
ArgMacros.@helpepilog
ArgMacros.@helpusage
ArgMacros.@inlinearguments
ArgMacros.@positionaldefault
ArgMacros.@positionalleftover
ArgMacros.@positionaloptional
ArgMacros.@positionalrequired
ArgMacros.@structarguments
ArgMacros.@tuplearguments