CommandLineParser

Inherits: Reference < Object

Enables parsing of command-line arguments.

Description

CommandLineParser allows to define a set of CommandLineOptions, parse the command-line arguments, store parsed options and respective values. The class is mainly useful for parsing arguments from OS.get_cmdline_args, but can be used for other purposes as well.

Options on the command line are recognized as starting with any of the specified long_prefixes or short_prefixes values. Long options consist of more than one character. Short options always consist of one character and can be written in a compound form, for instance -abc is equivalent to -a -b -c.

Option values can be specified either separated by a space or by an = sign (if the option takes only 1 argument). Short options can also have sticky values (without a space in-between, e.g. -Dvalue).

Values can also be specified without an option name and the first option that is marked as CommandLineOption.positional will be assigned automatically. For example, if the input-file argument is marked as positional, then you can write either --input-file=filename or just filename.

The option -- (without any symbol after) is a special case and means that all following options will be captured as valid and can be obtained later using get_forwarding_args.

Example:

var parser = CommandLineParser.new()

func _init():
    var help = parser.add_help_option()
    var version = parser.add_version_option()
    var input = parser.add_option("input", "Specify filename to process.")

    if parser.parse(["--input", "/path/to/file.txt"]) != OK:
        print(parser.get_error_text())
        return

    if parser.is_set(help):
        print(parser.get_help_text())
        return

    if parser.is_set(version):
        print(GoostEngine.get_version_info().string)
        return

    print("Parsed value from '--input': ", parser.get_value(input))

Property Descriptions

  • bool allow_adjacent
Default true
Setter set_allow_adjacent(value)
Getter is_adjacent_allowed()

If true, values for options can delimited by = sign. Example: --input=filename.png.

  • bool allow_compound
Default true
Setter set_allow_compound(value)
Getter is_compound_allowed()

If true, short options can be specified without a space. Example: -aux will be equivalent to -a -u -x.

  • bool allow_forwarding_args
Default false
Setter set_allow_forwarding_args(value)
Getter are_forwarding_args_allowed()

If true, all arguments after -- will be treated as forwarding arguments and will be available using the get_forwarding_args. Such arguments won’t be parsed as options.

Default true
Setter set_allow_sticky(value)
Getter is_sticky_allowed()

If true, values for short options can be specified without a space. Example: -ifilename.png.

Default PoolStringArray( "--" )
Setter set_long_prefixes(value)
Getter get_long_prefixes()

A list of prefixes after which an argument will be considered a long option. If two or more prefixes share the same set of characters (e.g. -- and --no-), longest prefixes have higher precedence for parsing. For instance, --no-debug won’t be parsed as a separate no-debug option, but as debug.

Default PoolStringArray( "-" )
Setter set_short_prefixes(value)
Getter get_short_prefixes()

A list of prefixes after which an argument will be considered a short option.

Default 0.3
Setter set_similarity_bias(value)
Getter get_similarity_bias()

If a user entered a wrong option, the parser will suggest the most similar one in the error text returned by get_error_text. If the most similar option found has a similarity value lower than the specified one, then it won’t be suggested. Similarity is determined by String.similarity.

Method Descriptions

Adds the help option (-h, –help) with the default description. The option is automatically marked as CommandLineOption.meta.

Instantiates a new CommandLineOption with a single name and adds it to the parser. Description, default value, and a list of allowed values can be optionally specified. Note that this method provides common parameters only, you can create CommandLineOption and use append_option manually if you need to configure other properties for a new option, or modify the properties of the option returned by this method instead before parsing command-line arguments with parse.

Adds the version option (-v, –version) with the default description. The option is automatically marked as CommandLineOption.meta.

Adds an existing option to look for while parsing. Prefer to use add_option for defining new command-line options.

  • void clear ( )

Clears all parsed data and specified options.

Finds an option by name, returns null if it doesn’t exist.

Returns all arguments that were passed by parse.

  • String get_error_text ( ) const

Returns a human-readable description of the last parser error that occurred.

Returns all arguments that were forwarded after parsing (e.g. all arguments after --).

Returns a string containing the complete help information generated from the added options. If format is not null, the returned text will be formatted with a custom format defined via CommandLineHelpFormat object, otherwise the default format is used.

Returns the number of times the option was parsed. Mostly useful for options which are defined as multitoken, see CommandLineOption.multitoken.

Returns the option at index position index. Negative indices can be used to count from the back, like in Python (-1 is the last element, -2 the second to last, etc.).

  • int get_option_count ( ) const

Returns the number of options in the parser.

Returns first used prefix for option. Example: for parsed --help will return --. Convenient helper for get_prefix_list.

Returns all used prefixes for option.

Returns first specified value for option. Example: for parsed --input filename.png will return filename.png. Convenient helper for get_value_list.

Returns all specified values for option.

Returns true if option was specified. If the option does not accept any arguments (CommandLineOption.arg_count is equal to 0), this is the only way to check whether the option was specified on the command-line.

Parses command-line args. Returns @GlobalScope.OK upon success, or @GlobalScope.ERR_PARSE_ERROR upon failure. In case of user error, refer to get_error_text which returns human-readable error message which can be printed to a user.

The method can accept command-line arguments returned by OS.get_cmdline_args.

Note: this method accepts a list of strings. Do not attempt to parse a single string containing command-line arguments with this method. You should split the string into components prior to parsing using String.split, if needed.

  • void remove_option ( int index )

Removes option at specified index.

Replaces option at specified index with another option.