addons/gut/cli/optparse.gd
Inherits: RefCounted
Parses command line arguments, as one might expect.
Description
Parses command line arguments with a bunch of options including generating text that displays all the arguments your script accepts. This is included in the GUT ClassRef since it might be usable by others and is portable (everything it needs is in this one file).
This does alot, if you want to see it in action have a look at scratch/optparse_example.gd
Godot Argument Lists
-------------------------
There are two sets of command line arguments that Godot populates:
OS.get_cmdline_args
OS.get_cmdline_user_args.
OS.get_cmdline_args contains any arguments that are not used by the engine
itself. This means options like --help and -d will never appear in this list
since these are used by the engine. The one exception is the -s option which
is always included as the first entry and the script path as the second.
Optparse ignores these values for argument processing but can be accessed
with my_optparse.options.script_option. This list does not contain any
arguments that appear in OS.get_cmdline_user_args.
OS.get_cmdline_user_args contains any arguments that appear on the command
line AFTER " -- " or " ++ ". This list CAN contain options that the engine
would otherwise use, and are ignored completely by the engine.
The parse method, by default, includes arguments from OS.get_cmdline_args and
OS.get_cmdline_user_args. You can optionally pass one of these to the parse
method to limit which arguments are parsed. You can also conjure up your own
array of arguments and pass that to parse.
See Godot's documentation for get_cmdline_args and get_cmdline_user_args for
more information.
Adding Options
--------------
Use the following to add options to be parsed. These methods return the
created Option instance. See that class above for more info. You can use
the returned instance to get values, or use get_value/get_value_or_null.
add("--name", "default", "Description goes here")
add(["--name", "--aliases"], "default", "Description goes here")
add_required(["--name", "--aliases"], "default", "Description goes here")
add_positional("--name", "default", "Description goes here")
add_positional_required("--name", "default", "Description goes here")
get_value will return the value of the option or the default if it was not
set. get_value_or_null will return the value of the option or null if it was
not set.
The Datatype for an option is determined from the default value supplied to
the various add methods. Supported types are
String
Int
Float
Array of strings
Boolean
Value Parsing
-------------
optparse uses option_name_prefix to differentiate between option names and
values. Any argument that starts with this value will be treated as an
argument name. The default is "-". Set this before calling parse if you want
to change it.
Values for options can be supplied on the command line with or without an "=":
option=value # no space around "="
option value # a space between option and value w/o =
There is no way to escape "=" at this time.
Array options can be specified multiple times and/or set from a comma delimited
list.
-gdir=a,b
-gdir c,d
-gdir e
Results in -gdir equaling [a, b, c, d, e]. There is no way to escape commas
at this time.
To specify an empty list via the command line follow the option with an equal
sign
-gdir=
Boolean options will have thier value set to !default when they are supplied
on the command line. Boolean options cannot have a value on the command line.
They are either supplied or not.
If a value is not an array and is specified multiple times on the command line
then the last entry will be used as the value.
Positional argument values are parsed after all named arguments are parsed.
This means that other options can appear before, between, and after positional
arguments.
--foo=bar positional_0_value --disabled --bar foo positional_1_value --a_flag
Anything that is not used by named or positional arguments will appear in the
unused property. You can use this to detect unrecognized arguments or treat
everything else provided as a list of things, or whatever you want. You can
use is_option on the elements of unused (or whatever you want really) to see
if optparse would treat it as an option name.
Use get_missing_required_options to get an array of Option with all required
options that were not found when parsing.
The parsed_args property holds the list of arguments that were parsed.
Help Generation
---------------
You can call get_help to generate help text, or you can just call print_help
and this will print it for you.
Set the banner property to any text you want to appear before the usage and
options sections.
Options are printed in the order they are added. You can add a heading for
different options sections with add_heading.
add("--asdf", 1, "This will have no heading")
add_heading("foo")
add("--foo", false, "This will have the foo heading")
add("--another_foo", 1.5, "This too.")
add_heading("This is after foo")
add("--bar", true, "You probably get it by now.")
If you include "[default]" in the description of a option, then the help will
substitue it with the default value.
Properties
|
||
|
Methods
void |
add_heading(display_text: String) |
add_positional(op_name, default, desc: String) |
|
add_positional_required(op_name, default, desc: String) |
|
add_required(op_names, default, desc: String) |
|
get_help() |
|
get_value_or_null(name: String) |
|
is_option(arg) |
|
void |
parse(cli_args = null) |
void |
Property Descriptions
Set the banner property to any text you want to appear before the usage and options sections when printing the options help.
String option_name_prefix = "-" 🔗
optparse uses option_name_prefix to differentiate between option names and values. Any argument that starts with this value will be treated as an argument name. The default is “-”. Set this before calling parse if you want to change it.
Method Descriptions
Test if something is an existing argument. If str(arg) begins with the option_name_prefix, it will considered true, otherwise it will be considered false.
“addons/gut/cli/optparse.gd”.Option add(op_names, default, desc: String) 🔗
Adds a command line option. If op_names is a String, this is set as the argument’s name. If op_names is an Array of Strings, all elements of the array will be aliases for the same argument and will be treated as such during parsing. default is the default value the option will be set to if it is not explicitly set during parsing. desc is a human readable text description of the option. If the option is successfully added, the Option object will be returned. If the option is not successfully added (e.g. a name collision with another option occurs), an error message will be printed and null will be returned.
“addons/gut/cli/optparse.gd”.Option add_required(op_names, default, desc: String) 🔗
Adds a required command line option. Required options that have not been set may be collected after parsing by calling get_missing_required_options. If op_names is a String, this is set as the argument’s name. If op_names is an Array of Strings, all elements of the array will be aliases for the same argument and will be treated as such during parsing. default is the default value the option will be set to if it is not explicitly set during parsing. desc is a human readable text description of the option. If the option is successfully added, the Option object will be returned. If the option is not successfully added (e.g. a name collision with another option occurs), an error message will be printed and null will be returned.
“addons/gut/cli/optparse.gd”.Option add_positional(op_name, default, desc: String) 🔗
Adds a positional command line option. Positional options are parsed by their position in the list of arguments are are not assigned by name by the user. If op_name is a String, this is set as the argument’s name. If op_name is an Array of Strings, all elements of the array will be aliases for the same argument and will be treated as such during parsing. default is the default value the option will be set to if it is not explicitly set during parsing. desc is a human readable text description of the option. If the option is successfully added, the Option object will be returned. If the option is not successfully added (e.g. a name collision with another option occurs), an error message will be printed and null will be returned.
“addons/gut/cli/optparse.gd”.Option add_positional_required(op_name, default, desc: String) 🔗
Adds a required positional command line option. If op_name is a String, this is set as the argument’s name. Required options that have not been set may be collected after parsing by calling get_missing_required_options. Positional options are parsed by their position in the list of arguments are are not assigned by name by the user. If op_name is an Array of Strings, all elements of the array will be aliases for the same argument and will be treated as such during parsing. default is the default value the option will be set to if it is not explicitly set during parsing. desc is a human readable text description of the option. If the option is successfully added, the Option object will be returned. If the option is not successfully added (e.g. a name collision with another option occurs), an error message will be printed and null will be returned.
void add_heading(display_text: String) 🔗
Headings are used to separate logical groups of command line options when printing out options from the help menu. Headings are printed out between option descriptions in the order that add_heading was called.
Variant get_value(name: String) 🔗
Gets the value assigned to an option after parsing. name can be the name of the option or an alias of it. name specifies the option whose value you wish to query. If the option exists, the value assigned to it during parsing is returned. Otherwise, an error message is printed and null is returned.
Variant get_value_or_null(name: String) 🔗
Gets the value assigned to an option after parsing, returning null if the option was not assigned instead of its default value. name specifies the option whose value you wish to query. This can be useful when providing an order of precedence to your values. For example if
default value < config file < command line
then you do not want to get the default value for a command line option or it will overwrite the value in a config file.
Returns the help text for all defined options.
void print_help() 🔗
Prints out the help text for all defined options.
void parse(cli_args = null) 🔗
Parses a string for all options that have been set in this optparse. if cli_args is passed as a String, then it is parsed. Otherwise if cli_args is null, aruments passed to the Godot engine at startup are parsed. See the explanation at the top of addons/gut/cli/optparse.gd to understand which arguments this will have access to.
Array get_missing_required_options() 🔗
Get all options that were required and were not set during parsing. The return value is an Array of Options.