Skip to content

Commit

Permalink
Documentation fixes for command-line parser related classes
Browse files Browse the repository at this point in the history
  • Loading branch information
@Xrayez
Xrayez committed Aug 7, 2021
1 parent ffaa96c commit b07f750
Show file tree
Hide file tree
Showing 3 changed files with 54 additions and 57 deletions.
8 changes: 4 additions & 4 deletions doc/CommandLineHelpFormat.xml
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="CommandLineHelpFormat" inherits="Reference" version="3.4">
<brief_description>
This class contains formatting options for help message. See also [CommandLineParser].
This class contains formatting options for constructing a help message in [CommandLineParser].
</brief_description>
<description>
The class is used to pass formatting parameters to the [method CommandLineParser.get_help_text] method.
Expand All @@ -12,13 +12,13 @@
</methods>
<members>
<member name="autogenerate_usage" type="bool" setter="set_autogenerate_usage" getter="is_autogenerate_usage" default="true">
If [code]true[/code], help will have autogenerated usage message.
If [code]true[/code], the usage text will be automatically generated according to passed options.
</member>
<member name="footer" type="String" setter="set_footer" getter="get_footer" default="&quot;&quot;">
Contains text to be displayed at the end of the help text.
</member>
<member name="header" type="String" setter="set_header" getter="get_header" default="&quot;&quot;">
Contains text to be displayed at the beggining of the help text.
Contains text to be displayed at the beginning of the help text.
</member>
<member name="left_pad" type="int" setter="set_left_pad" getter="get_left_pad" default="2">
The amount of indentation in spaces to the left of the options in the help text.
Expand All @@ -33,7 +33,7 @@
The amount of indentation in spaces to the right of the options in the help text.
</member>
<member name="usage_title" type="String" setter="set_usage_title" getter="get_usage_title" default="&quot;&quot;">
Executable name that will be displayed in usage in help text. If empty, the name of the current executable file will be used.
Title that will be displayed in usage text. If empty, the name of the current executable file will be used.
</member>
</members>
<constants>
Expand Down
34 changes: 16 additions & 18 deletions doc/CommandLineOption.xml
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="CommandLineOption" inherits="Reference" version="3.4">
<brief_description>
Defines a possible command-line option.
Defines a command-line option for [CommandLineParser].
</brief_description>
<description>
This class is used to describe an option on the command line. It allows different ways of defining the same option with multiple aliases possible. It is also used to describe how the option is used - it may be a flag (e.g. [code]-v[/code]) or take a value (e.g. [code]-o file[/code]).
This class is used to define an option on the command line. The same option is allowed to have multiple aliases. It is also used to describe how the option is used: it may be a flag (e.g. [code]-v[/code]) or take a value (e.g. [code]-o file[/code]).
</description>
<tutorials>
</tutorials>
Expand All @@ -27,18 +27,16 @@
Sets a [code]callable[/code] that accepts a [String] as input and returns [code]true[/code] if the value matches the given check. If the function returns [code]false[/code], then the parsing will fail and [method CommandLineParser.get_error] will return [code]error_msg[/code].
Example:
[codeblock]
var _parser := CommandLineParser.new()
var _command := CommandLineOption.new()

var parser = CommandLineParser.new()
var option = CommandLineOption.new()

func _init():
option.names = ["i", "ip"]
option.arg_count = 1
option.description = "This option can accept only IP."
option.description = "This option can accept IP address only."
option.arg_text = "&lt;ip&gt;"
option.set_checker(Callable(self, "_is_valid_ip"), "Invalid IP");
_parser.add_command(option)

parser.add_command(option)

func _is_valid_ip(arg: String) -&gt; bool:
return arg.is_valid_ip_address()
Expand All @@ -48,34 +46,34 @@
</methods>
<members>
<member name="allowed_args" type="PoolStringArray" setter="set_allowed_args" getter="get_allowed_args" default="PoolStringArray( )">
Set of values that allowed by the option. If a different value is passed, the parsing will fail. Empty if any value is allowed.
A set of values that are allowed by the option. If a different value is passed, the parsing will fail. Empty if any value is allowed.
</member>
<member name="arg_count" type="int" setter="set_arg_count" getter="get_arg_count" default="1">
The number of arguments required for the option. A value less than 0 means all remaining values up to the next option or the end of the argument list.
</member>
<member name="arg_text" type="String" setter="set_arg_text" getter="get_arg_text" default="&quot;&lt;arg&gt;&quot;">
Name for the option arguments that will be displayed in help message. For example: [code]--input &lt;filename&gt;[/code], where [code]&lt;filename&gt;[/code] is arg_text.
Name for the option arguments that will be displayed in the help message. For example: [code]--input &lt;filename&gt;[/code], where [code]&lt;filename&gt;[/code] is [code]arg_text[/code].
</member>
<member name="category" type="String" setter="set_category" getter="get_category" default="&quot;&quot;">
Option category, options sharing the same category are grouped together in the help message.
Category name, options sharing the same category are grouped together in the help message.
</member>
<member name="default_args" type="PoolStringArray" setter="set_default_args" getter="get_default_args" default="PoolStringArray( )">
Set of values that will be used by default if no value specified.
A set of values that will be used by default if no value specified.
</member>
<member name="description" type="String" setter="set_description" getter="get_description" default="&quot;&quot;">
Option description that will be displayed in help.
Description that will be displayed in the help message.
</member>
<member name="hidden" type="bool" setter="set_hidden" getter="is_hidden" default="false">
If [code]true[/code], the option will be displayed in help.
If [code]true[/code], the option will [b]not[/b] be displayed in the help message.
</member>
<member name="multitoken" type="bool" setter="set_multitoken" getter="is_multitoken" default="false">
If [code]true[/code], option can be specified multiply times. Number of times can be obtained using [method CommandLineParser.get_occurrence_count].
If [code]true[/code], option can be specified multiple times. Total count can be obtained using [method CommandLineParser.get_occurrence_count].
</member>
<member name="names" type="PoolStringArray" setter="set_names" getter="get_names" default="PoolStringArray( )">
Returns the names set for this option.
Specifies all valid names (aliases) for this option.
</member>
<member name="positional" type="bool" setter="set_positional" getter="is_positional" default="false">
If [code]true[/code], option can be specified without option name. In this case, the first unparsed option marked as [member positional] will be selected.
If [code]true[/code], option can be specified without a name. In this case, the first unparsed option marked as [member positional] will be selected.
</member>
<member name="required" type="bool" setter="set_required" getter="is_required" default="false">
If [code]true[/code], [method CommandLineParser.validate] will return an error if the option was not specified in the argument list.
Expand All @@ -86,7 +84,7 @@
<argument index="0" name="values" type="PoolStringArray">
</argument>
<description>
Emitted when after calling [method CommandLineParser.validate] if it returns [constant OK] and this option was specified in the argument list. [code]values[/code] contains all values that was passed to the option.
Emitted after calling [method CommandLineParser.validate] if it returns [constant OK] and this option was specified in the argument list. [code]values[/code] contains all values that were passed to the option.
</description>
</signal>
</signals>
Expand Down
69 changes: 34 additions & 35 deletions doc/CommandLineParser.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,43 +4,42 @@
Provides a means for handling the command line options.
</brief_description>
<description>
[method OS.get_cmdline_args] provides the command-line arguments as a simple list of strings. [CommandLineParser] provides the ability to define a set of options, parse the command-line arguments, and store which options have actually been used, as well as option values.
Options on the command line are recognized as starting with any of specified [member long_prefixes] or [member short_prefixes] values. Long options consist of more than one character. Short options always consist of one character and can be written in a compact form, for instance [code]-abc[/code] is equivalent to [code]-a -b -c[/code]. Option values can be specified either separated by a space or by an [code]=[/code] sign (if the option takes only 1 argument). Short options can also have sticky values (without a space between, e.g. [code]-Dvalue[/code]).
Also values can be specified without an option name and the first option that is marked as [member CommandLineOption.positional] will be assigned automatically. For example, if the [code]input-file[/code] argument is marked as positional, then you can write either [code]--input-file=filename[/code] or just [code]filename[/code].
[method OS.get_cmdline_args] provides the command-line arguments as a simple list of strings. [CommandLineParser] gives an ability to define a set of options, parse the command-line arguments, and store which options have actually been used, as well as option values.
Options on the command line are recognized as starting with any of specified [member long_prefixes] or [member short_prefixes] values. Long options consist of more than one character. Short options always consist of one character and can be written in a compact form, for instance [code]-abc[/code] is equivalent to [code]-a -b -c[/code]. Option values can be specified either separated by a space or by an [code]=[/code] sign (if the option takes only 1 argument). Short options can also have sticky values (without a space in-between, e.g. [code]-Dvalue[/code]).
Values can also be specified without an option name and the first option that is marked as [member CommandLineOption.positional] will be assigned automatically. For example, if the [code]input-file[/code] argument is marked as positional, then you can write either [code]--input-file=filename[/code] or just [code]filename[/code].
The option [code]--[/code] (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 [method get_forwarded_args].
Example:
[codeblock]
var _parser := CommandLineParser.new()

var _help: CommandLineOption = _parser.add_help_option()
var _version: CommandLineOption = _parser.add_version_option()
var _one_arg := CommandLineOption.new()
var parser = CommandLineParser.new()

var help: CommandLineOption = parser.add_help_option()
var version: CommandLineOption = parser.add_version_option()
var input = CommandLineOption.new()

func _init():
_one_arg.names = ["i", "input"]
_one_arg.category = "General"
_one_arg.arg_text = "&lt;filename&gt;"
_one_arg.description = "Set one any arg."
_parser.add_option(_one_arg)
input.names = ["i", "input"]
input.category = "General"
input.arg_text = "&lt;filename&gt;"
input.description = "Specify filename to process."
parser.add_option(input)

if _parser.parse_args(OS.get_cmdline_args())
print(_parser.get_error())
if parser.parse_args(OS.get_cmdline_args()) != OK:
print(parser.get_error())
return

if _parser.is_set(_help):
print(_parser.get_help_text(CommandLineHelpFormat.new()))
if parser.is_set(help):
print(parser.get_help_text(CommandLineHelpFormat.new()))
return

if _parser.is_set(_version):
if parser.is_set(version):
print(ProjectSettings.get_setting("application/config/version"))
return

if _parser.validate() != OK:
print(_parser.get_error())
if parser.validate() != OK:
print(parser.get_error())
return

print(_parser.get_value(_one_arg))
print(parser.get_value(input))
[/codeblock]
</description>
<tutorials>
Expand All @@ -50,7 +49,7 @@
<return type="CommandLineOption">
</return>
<description>
Adds the help option (-h, --help) with default description.
Adds the help option (-h, --help) with the default description.
</description>
</method>
<method name="add_option">
Expand Down Expand Up @@ -82,21 +81,21 @@
<argument index="0" name="name" type="String">
</argument>
<description>
Finds option by name.
Finds an option by name.
</description>
</method>
<method name="get_args" qualifiers="const">
<return type="PoolStringArray">
</return>
<description>
Returns all arguments that was passed by [method parse_args].
Returns all arguments that were passed by [method parse_args].
</description>
</method>
<method name="get_error" qualifiers="const">
<return type="String">
</return>
<description>
Returns a human-readable description of the last parcer error that occurred.
Returns a human-readable description of the last parser error that occurred.
</description>
</method>
<method name="get_forwarded_args" qualifiers="const">
Expand All @@ -121,7 +120,7 @@
<argument index="0" name="option" type="CommandLineOption">
</argument>
<description>
Returns the number of times the option got parsed.
Returns the number of times the option was parsed.
</description>
</method>
<method name="get_option" qualifiers="const">
Expand All @@ -146,7 +145,7 @@
<argument index="0" name="option" type="CommandLineOption">
</argument>
<description>
Returns first used prefix for [code]option[/code]. Example: for parsed [code]--help[/code] will return [code]--[/code]. Convinient helper for [method get_prefixes].
Returns first used prefix for [code]option[/code]. Example: for parsed [code]--help[/code] will return [code]--[/code]. Convenient helper for [method get_prefixes].
</description>
</method>
<method name="get_prefixes" qualifiers="const">
Expand All @@ -164,7 +163,7 @@
<argument index="0" name="option" type="CommandLineOption">
</argument>
<description>
Returns first specified value for [code]option[/code]. Example: for parsed [code]--input filename.png[/code] will return [code]filename.png[/code]. Convinient helper for [method get_values].
Returns first specified value for [code]option[/code]. Example: for parsed [code]--input filename.png[/code] will return [code]filename.png[/code]. Convenient helper for [method get_values].
</description>
</method>
<method name="get_values" qualifiers="const">
Expand All @@ -191,7 +190,7 @@
<argument index="0" name="args" type="PoolStringArray">
</argument>
<description>
Parses command-line [code]args[/code].
Parses command-line [code]args[/code]. Returns [constant OK] upon success. In case of error, refer to [method get_error] which returns human-readable error message.
</description>
</method>
<method name="remove_option">
Expand All @@ -211,20 +210,20 @@
<argument index="1" name="option" type="CommandLineOption">
</argument>
<description>
Replaced option at specified index [code]idx[/code] with [code]option[/code].
Replaces option at specified index [code]idx[/code] with [code]option[/code].
</description>
</method>
<method name="validate">
<return type="int" enum="Error">
</return>
<description>
Checks if all required methods was specified. If succeed emits [signal CommandLineOption.validated] for options that was parsed.
Checks if all required methods were specified. Emits [signal CommandLineOption.validated] upon success for options that were parsed.
</description>
</method>
</methods>
<members>
<member name="allow_adjacent" type="bool" setter="set_allow_adjacent" getter="is_allow_adjacent" default="true">
If [code]true[/code], values for options can delimeted by [code]=[/code] sign. Example: [code]--input=filename.png[/code].
If [code]true[/code], values for options can delimited by [code]=[/code] sign. Example: [code]--input=filename.png[/code].
</member>
<member name="allow_compound" type="bool" setter="set_allow_compound" getter="is_allow_compound" default="true">
If [code]true[/code], short options can be specified without a space. Example: [code]-aux[/code] will be equivalent to [code]-a -u -x[/code].
Expand All @@ -236,13 +235,13 @@
If [code]true[/code], values for short options can be specified without a space. Example: [code]-ifilename.png[/code].
</member>
<member name="long_prefixes" type="PoolStringArray" setter="set_long_prefixes" getter="get_long_prefixes" default="PoolStringArray( &quot;--&quot; )">
Prefixes, after which the arguemtn will be considered a long option.
A list of prefixes after which an argument will be considered a long option.
</member>
<member name="short_prefixes" type="PoolStringArray" setter="set_short_prefixes" getter="get_short_prefixes" default="PoolStringArray( &quot;-&quot; )">
Prefixes, after which the arguemtn will be considered a short option.
A list of prefixes after which an argument will be considered a short option.
</member>
<member name="similarity_bias" type="float" setter="set_similarity_bias" getter="get_similarity_bias" default="0.3">
If the user entered the wrong option, the parser will try to suggest the most similar one (in case the user made a typo). If the found most similar option has a similarity value lower than the specified one, then it will not be suggested.
If a user entered the wrong option, the parser will try to suggest the most similar one (in case a user made a typo). If the most similar option found has a similarity value lower than the specified one, then it will not be suggested.
</member>
</members>
<constants>
Expand Down

0 comments on commit b07f750

Please sign in to comment.