Skip to content

Commit 4894e3c

Browse files
yakovypgyakovypg
committed
Add documentation
1 parent a651324 commit 4894e3c

File tree

5 files changed

+651
-0
lines changed

5 files changed

+651
-0
lines changed

‎Docs/AdditionalFeatures.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# Additional Features
2+
**NetArgumentParser** supports some useful options, which you will learn about below.
3+
4+
## Table of Contents
5+
* [Negative Numbers & Scientific Notation](#negative-numbers--scientific-notation)
6+
* [Use `option=value` Syntax](#use-optionvalue-syntax)
7+
* [Parse Known Arguments](#parse-known-arguments)
8+
* [Skip Arguments](#skip-arguments)
9+
10+
## Negative Numbers & Scientific Notation
11+
As you can see here, **NetArgumentParser** supports negative numbers and scientific notation.
12+
13+
```cs
14+
int? offset = null;
15+
double? angle = null;
16+
17+
var offsetOption = new ValueOption<int>("offset",
18+
afterValueParsingAction: t => offset = t);
19+
20+
var angleOption = new ValueOption<double>("angle", "a",
21+
description: "angle by which you want to rotate the image",
22+
afterValueParsingAction: t => angle = t);
23+
24+
var parser = new ArgumentParser();
25+
parser.AddOptions(offsetOption, angleOption);
26+
27+
parser.Parse(new string[] { "--offset", "-45", "--angle", "-1e-1" });
28+
// offset: -45
29+
// angle: -0.1
30+
```
31+
32+
## Use `option=value` Syntax
33+
**NetArgumentParser** supports `option=value` syntax. Please note that this syntax doesn't combine with the ability to capture multiple values.
34+
35+
```cs
36+
int? angle = null;
37+
List<string> inputFiles = [];
38+
39+
var angleOption = new ValueOption<int>("angle", "a",
40+
description: "angle by which you want to rotate the image",
41+
afterValueParsingAction: t => angle = t);
42+
43+
var filesOption = new MultipleValueOption<string>("input", "i",
44+
description: "files that need to be processed",
45+
contextCapture: new OneOrMoreContextCapture(),
46+
afterValueParsingAction: t => inputFiles = new List<string>(t));
47+
48+
var parser = new ArgumentParser();
49+
parser.AddOptions(angleOption, filesOption);
50+
51+
parser.ParseKnownArguments(
52+
new string[] { "--angle=45", "--input=file0.txt", "file1.txt" },
53+
out List<string> extraArguments);
54+
55+
// angle: 45
56+
// inputFiles: [file0.txt]
57+
// extraArguments: [file1.txt]
58+
```
59+
60+
## Parse Known Arguments
61+
Sometimes a program may need to parse only part of the command-line arguments and pass the remaining arguments to another program. In this case, the `ParseKnownArguments` function may be useful. It works in much the same way as the `Parse` function, except that it doesn't throw an exception if there are additional arguments. Instead, it allows you to get a list of the extra argument.
62+
63+
```cs
64+
bool verbose = false;
65+
66+
var option = new FlagOption("verbose", "v",
67+
description: "be verbose",
68+
afterHandlingAction: () => verbose = true);
69+
70+
var parser = new ArgumentParser();
71+
parser.AddOptions(option);
72+
73+
parser.ParseKnownArguments(new string[] { "-v", "10", "-a" }, out List<string> extraArguments);
74+
// extraArguments: [10, -a]
75+
```
76+
77+
## Skip Arguments
78+
Sometimes a program may need to skip some arguments from the beginning of the argument list and handle them in a special way. In this case, the `NumberOfArgumentsToSkip` property may be useful. With it, you can specify the number of arguments to be skipped.
79+
80+
```cs
81+
var parser = new ArgumentParser()
82+
{
83+
NumberOfArgumentsToSkip = 1
84+
};
85+
86+
/*
87+
...
88+
parser.AddOptions(...);
89+
*/
90+
91+
parser.Parse(new string[] { "merge", "./first.txt", "./second.txt" });
92+
// Only ["./first.txt", "./second.txt"] will be parsed
93+
```

‎Docs/CustomConverters.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# Custom Converters
2+
Custom converters allow you to easily work with options whose values are non-standard types. For standard types default converters have already been implemented. However, you can create your own converter for the standard type.
3+
4+
## Table of Contents
5+
* [Converter Types](#converter-types)
6+
* [Value Converter](#value-converter)
7+
* [Converter Set](#converter-set)
8+
9+
## Converter Types
10+
There are three converter types: value converter, multiple value converter and enum value converter. They are used in value options, multiple value options and enum value options. However, in the vast majority of situations it is sufficient to use only the value converter.
11+
12+
Furthermore, you can create your own converters. To do this you need to inherit your class from the `IValueConverter` interface. You can also use an existing option class as a base class. See examples of this kind of inheritance, for example, by looking at the implementation of the `MultipleValueConverter` and `EnumValueConverter` classes.
13+
14+
### Value Converter
15+
To create a value converter for type T, you need a function that takes a string and returns T. Pass this function to the constructor of the appropriate class as shown in the example below.
16+
17+
Here is an example of creating value converter and using it in the parser:
18+
19+
```cs
20+
string name = string.Empty;
21+
22+
var firstNameOption = new ValueOption<string>("name",
23+
afterValueParsingAction: t => name = t);
24+
25+
var converter = new ValueConverter<string>(t => t.ToUpper());
26+
27+
var parser = new ArgumentParser();
28+
parser.AddConverters(converter);
29+
30+
parser.Parse(new string[] { "--name", "name" });
31+
// name: NAME
32+
```
33+
34+
## Converter Set
35+
You can put just one converter for each type in converter set.
36+
```cs
37+
var defaultIntConverter = new ValueConverter<int>(t => Math.Abs(int.Parse(t)));
38+
var defaultStringConverter = new ValueConverter<string>(t => t.ToUpper());
39+
var additionalStringConverter = new ValueConverter<string>(t => t.ToLower());
40+
41+
var parser = new ArgumentParser();
42+
parser.AddConverters(defaultIntConverter); // Ok
43+
parser.AddConverters(defaultStringConverter); // Ok
44+
parser.AddConverters(additionalStringConverter); // Error
45+
```
46+
47+
However, you can transfer an individual ownership of any suitable converter to the option, even if a converter for the same type is already in the converter set. Options without their own converter will have a converter from the converter set.
48+
49+
```cs
50+
var defaultStringConverter = new ValueConverter<string>(t => t.ToUpper());
51+
var additionalStringConverter = new ValueConverter<string>(t => t.ToLower());
52+
53+
string firstName = string.Empty;
54+
string secondName = string.Empty;
55+
56+
var firstNameOption = new ValueOption<string>("f-name",
57+
afterValueParsingAction: t => firstName = t);
58+
59+
var secondNameOption = new ValueOption<string>("s-name",
60+
afterValueParsingAction: t => secondName = t)
61+
{
62+
Converter = additionalStringConverter
63+
};
64+
65+
var parser = new ArgumentParser();
66+
67+
parser.AddOptions(firstNameOption, secondNameOption);
68+
parser.AddConverters(defaultStringConverter);
69+
70+
parser.Parse(new string[] { "--f-name", "Name", "--s-name", "Name" });
71+
// firstName: NAME
72+
// secondName: name
73+
```

‎Docs/OptionalArguments.md‎

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
# Optional Arguments
2+
Let's consider **optional arguments**. Optional arguments start with `-`, `--` or `/`, e.g., `-h`, `--verbose` or `/m`.
3+
4+
## Table of Contents
5+
* [Flag Options](#flag-options)
6+
* [Help Option](#help-option)
7+
* [Version Option](#version-option)
8+
* [Value Options](#value-options)
9+
* [Multiple Value Options](#multiple-value-options)
10+
* [Enum Value Options](#enum-value-options)
11+
* [Custom Options](#custom-options)
12+
* [Option Groups](#option-groups)
13+
14+
## Flag Options
15+
**Flag options** are options without value. They make working with boolean values ​​easier.
16+
17+
Here is an example of creating flag option and using it in the parser:
18+
19+
```cs
20+
bool verbose = false;
21+
22+
var option = new FlagOption("verbose", "v",
23+
description: "be verbose",
24+
afterHandlingAction: () => verbose = true);
25+
26+
var parser = new ArgumentParser();
27+
parser.AddOptions(option);
28+
29+
parser.Parse(new string[] { "--verbose" });
30+
// verbose: true
31+
```
32+
33+
### Help Option
34+
**Help option** is a special final flag option whose default action is to print the help and exit the program.
35+
36+
This option is automatically added to the option set, so you don't have to add it explicitly:
37+
38+
```cs
39+
var parser = new ArgumentParser();
40+
parser.Parse(new string[] { "--help" });
41+
```
42+
43+
You can disable automatic addition of the help option as follows:
44+
45+
```cs
46+
var parser = new ArgumentParser()
47+
{
48+
UseDefaultHelpOption = false
49+
};
50+
```
51+
52+
Here is an example of creating custom help option and using it in the parser:
53+
54+
```cs
55+
var parser = new ArgumentParser()
56+
{
57+
UseDefaultHelpOption = false
58+
};
59+
60+
var option = new HelpOption("help", "h",
61+
description: "show command-line help",
62+
afterHandlingAction: () =>
63+
{
64+
Console.WriteLine(parser.GenerateProgramDescription());
65+
Environment.Exit(0);
66+
});
67+
68+
parser.AddOptions(option);
69+
parser.Parse(new string[] { "--help" });
70+
```
71+
72+
### Version Option
73+
**Version option** is a special final flag option whose default action is to print the version information and exit the program.
74+
75+
This option is automatically added to the option set, so you don't have to add it explicitly:
76+
77+
```cs
78+
var parser = new ArgumentParser();
79+
parser.Parse(new string[] { "--version" });
80+
```
81+
82+
You can disable automatic addition of the help option as follows:
83+
84+
```cs
85+
var parser = new ArgumentParser()
86+
{
87+
UseDefaultVersionOption = false
88+
};
89+
```
90+
91+
Here is an example of creating custom version option and using it in the parser:
92+
93+
```cs
94+
var parser = new ArgumentParser()
95+
{
96+
UseDefaultVersionOption = false
97+
};
98+
99+
var option = new VersionOption("version", "v",
100+
description: "show version information",
101+
afterHandlingAction: () =>
102+
{
103+
Console.WriteLine(parser.ProgramVersion);
104+
Environment.Exit(0);
105+
});
106+
107+
parser.AddOptions(option);
108+
parser.Parse(new string[] { "--version" });
109+
```
110+
111+
## Value Options
112+
**Value options** are options with value. The value type can be anything. However, for types that don't have a default converter, you will need to add a [custom converter](CustomConverters.md).
113+
114+
Here is an example of creating value option and using it in the parser:
115+
116+
```cs
117+
int? angle = null;
118+
119+
var option = new ValueOption<int>("angle", "a",
120+
description: "angle by which you want to rotate the image",
121+
afterValueParsingAction: t => angle = t);
122+
123+
var parser = new ArgumentParser();
124+
parser.AddOptions(option);
125+
126+
parser.Parse(new string[] { "--angle", "45" });
127+
// angle: 45
128+
```
129+
130+
### Multiple Value Options
131+
**Multiple value options** are options whose value is a list. The single value type can be anything. However, for types that don't have a default converter, you will need to add a [custom converter](CustomConverters.md).
132+
133+
Here is an example of creating multiple value option and using it in the parser:
134+
135+
```cs
136+
List<string> inputFiles = [];
137+
138+
var option = new MultipleValueOption<string>("input", "i",
139+
description: "files that need to be processed",
140+
contextCapture: new OneOrMoreContextCapture(),
141+
afterValueParsingAction: t => inputFiles = new List<string>(t));
142+
143+
var parser = new ArgumentParser();
144+
parser.AddOptions(option);
145+
146+
parser.Parse(new string[] { "-i", "file0.txt", "file1.txt" });
147+
// inputFiles: [file0.txt, file1.txt]
148+
```
149+
150+
One of the important features of the multiple value option is context capture. You can find out more about it in the [corresponding](OptionalArgumentsConfig.md#context-capture) section of the documentation.
151+
152+
### Enum Value Options
153+
**Enum value options** are options whose value is enum. The value type can be any enum.
154+
155+
Here is an example of creating enum value option and using it in the parser:
156+
157+
```cs
158+
StringSplitOptions? splitOption = null;
159+
160+
var option = new EnumValueOption<StringSplitOptions>("split-option", string.Empty,
161+
description: "specifies how the String.Split method should split a string",
162+
afterValueParsingAction: t => splitOption = t)
163+
164+
var parser = new ArgumentParser();
165+
parser.AddOptions(option);
166+
167+
parser.Parse(new string[] { "--split-option", "TrimEntries" });
168+
// splitOption: StringSplitOptions.TrimEntries
169+
```
170+
171+
## Custom Options
172+
You can create your own options. To do this you need to inherit your class from the `ICommonOption` interface. You can also use an existing option class as a base class. See examples of this kind of inheritance, for example, by looking at the implementation of the `FlagOption` and `EnumValueOption` classes.
173+
174+
## Option Groups
175+
Options can be divided into groups. This division may be useful when there are a lot of options.
176+
177+
```cs
178+
var parser = new ArgumentParser();
179+
parser.DefaultGroup.Header = "Default group:";
180+
181+
var option = new ValueOption<int>("angle");
182+
var additionalOption = new FlagOption("verbose");
183+
184+
parser.AddOptions(option);
185+
186+
OptionGroup<ICommonOption> group = parser.AddOptionGroup("Additional group:");
187+
group.AddOptions(additionalOption);
188+
189+
parser.Parse(new string[] { "--help" });
190+
```
191+
192+
In particular, this division will be displayed in the help output. It will be like the following:
193+
194+
```
195+
Usage: [--angle ANGLE] [--verbose] [--help] [--version]
196+
197+
Default group:
198+
--angle ANGLE rotation angle
199+
--help, -h show command-line help
200+
--version show version information
201+
202+
Additional group:
203+
--verbose be verbose
204+
```

0 commit comments

Comments
 (0)