1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
|
\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename argparser.info
@settitle argparser
@afourpaper
@documentencoding UTF-8
@documentlanguage en
@finalout
@c %**end of header
@dircategory Development
@direntry
* argparser: (argparser). Command line argument parser library
@end direntry
@copying
Copyright @copyright{} 2013 Mattias Andrée
@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts. A copy of the license is included in the section entitled
``GNU Free Documentation License''.
@end quotation
@end copying
@ifnottex
@node Top
@top argparser -- Command line argument parser library
@insertcopying
@end ifnottex
@titlepage
@title argparser
@subtitle Command line argument parser library
@author by Mattias Andrée (maandree)
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@contents
@menu
* Overview:: Brief overview of @command{argparser}.
* Python version:: Using the Python version.
* Java version:: Using the Java version.
@c* Bash version:: Using the Bash version.
@c* C version:: Using the C version.
* GNU Free Documentation License:: Copying and sharing this manual.
@end menu
@node Overview
@chapter Overview
Command line argument parser library for multiple languages with the
capability of both @code{-} and @code{+} short options and both
@code{--} and @code{++} long options. It supports variadic options,
colours and @code{--} and temporary @code{--} using @code{++}.
A variadic option is a option that takes all arguments placed after
it as an argument associated with it, rather than just the directly
following argument as an argumented option does.
@node Python version
@chapter Python version
To use argparser you need to import @code{ArgParser} from @code{argparser}
using the instruction @code{from argparser import *}.
The class @code{ArgParser} is used for parsing argument and requires an
instance. @code{ArgParser}'s constructor takes two manditory arguments
and three optional arguments. The first argument, @var{description}, is
a short, single-line, description of the program. The second argument,
@var{usage}, is multi-line usage text that is recommended to contain ANSI
colour escape sequences (for portability ESC 39m, ESC 49m and colours
beyond the lower 8 are not not recommended to be used); @code{None} can
be used if you do not have a usage descriptor.
@code{ArgParser}'s constructors there optional arguments are:
@var{longdescription}, @var{program} and @var{usestderr}.
@var{longdescription} is a long, multi-line, description of the program;
@code{None} can be used if you do not have a long description.
@var{program} is the program part of the executed command, but if you
rather, you can provide an exact name. You can also use the static function
@code{ArgParser.parent_name} to get the program part of the executed command
of a parent proces, it takes two optional arguments: @var{levels}, the
number of parent levels, by default 1; and @var{hasinterpretor}, whether
to get the name from an invocation of Python, by default false.
@var{usestderr} is by default @code{False} which means that printing is
done to stdout, otherwise, printing is done to stderr.
Before parsing arguments you need to populate the @code{ArgParser}
instance with valid options. There are three methods for this,
@code{add_argumentless}, @code{add_argumented} and @code{add_variadic},
that adds argumentless options, argumented options and variadic options
respectively. With the exception that @code{add_argumentless} does not
have the parameter @var{arg}, these three arguments has one manditory
argument, @var{alternatives}, and three optional arguments: @var{default},
@var{arg}, @var{help}. @var{default}'s deault value is zero, and either
the primary alternative or its index in @var{alternatives}.
@var{alternatives} is a list of alternatives, for example, a help option
could have @code{['-h', '--help']}. @var{arg} is a descriptive short name
of a argument associated with the option, and @var{help} is description
of the option and may span multiple lines but should only do so if the
lines below the first is just extra details.
When you have populated your @code{ArgParser} with options, it is time
to parse arguments, it is done with the method @code{parses} that optional
takes and list of arguments. If you choose to use a list of arguments
rather than letting @code{ArgParser} use arguments used to start the
program, the first ement will not be parsed as it is assumed to be the
executable.
If you now want to use any option alternative rather than just the
primary (using just the primary is good to keep your code consistent)
invoke the nulladic method @code{support_alternatives}.
Before using your options you should so some checks that the combination
of options and arguments are valid. There are some methods provided to do
this. @code{test_exclusiveness} checks that no confliction options are
used, as the first argument, a set of options provided from which at most
one may be used; as a optional second argument, a return code can be provided
if you want the program to exit if there are option conflicts.
@code{test_allowed} checks that only allowed options are used, as the first
argument, a set of options provided in which all used arguments must exist;
as a optional second argument, a return code can be provided if you want the
program to exit if there are out of context option.
@code{test_files} checks that the number of arguments not associated with
an option is within an acccepted range, it takes three option arguments,
@var{min}, @var{max} and @var{exit_value}. @var{min} is the minimum count,
@var{max} is the maximum count, @code{None} if unlimited, and @var{exit_value}
is a return code can be provided if you want the program to exit if there
are out of context option. Remember that you should also check that the
number of times an option is used is acceptable.
After running @code{parses}, your @code{ArgParser} has five attributes:
@var{unrecognisedCount}, the number of unrecognised options; and
@var{message}, the join of @var{files} which is all arguments not
associated with an option, @var{arguments} the parsed arguments, and
@var{argcount}, the number of arguments in @var{arguments}.
All valid options are stored in your @code{ArgParser}'s @var{opts},
it is a dictionary from the option to either @code{None} if the option
has not been used, or a list of all used values, in order. A variadic
option without any argumnt will have a empty list and a argumentless
option will have list filled with @code{None}.
To print a help page based on the constructor arguments and populated
options invoke the nulladic method @code{help}.
@node Java version
@chapter Java version
The JAR for ArgParser, @file{ArgParser.jar}, is located in @file{/usr/lib}.
When using it you need to import @code{argparser.ArgParser}.
@code{ArgParser} has six constructors, conforming to:
@code{description, usage, [longDescription, [program]], [useStderr]}.
These correspond to those in the Python version.
@code{ArgParser.parent_name} from the Python version is named
@code{ArgParser.parentName} in the Java version and is identical
except it parses Java invocation rather then Python invocation.
Further @code{support_alternatives}, @code{test_exclusiveness},
@code{test_allowed}, @code{test_files} and @code{help} are named
@code{supportAlternatives}, @code{testExclusiveness}, @code{testAllowed},
@code{testFiles} and @code{help} respectively and @code{testFiles}
without @var{min} is named @code{testFilesMax} and @code{testFiles}
without @var{max} is named @code{testFilesMin}.
@var{message} is a @code{String}, @var{files} is a @code{ArrayList<String>},
@var{unrecognisedCount} is a @code{int}, @var{arguments} is a @code{String[]},
and @var{opts} is a @code{HashMap<String, String[]>}.
@var{argcount} does not exist.
To populate the @code{ArgParser} with valid options, use the method
@code{add} with the option and optional, before or after, the description.
An option is created using a constructor for either @code{Argumentless},
@code{Argumented} or @code{Variadic}.
@code{Argumentless}'s constructor takes an @code{String[]} of alternatives
and optional, before or after, the index of the primary alternative. If
the index is not after the alternative array, the alternatives parameter
is variadic and each alternative can be an argument.
@code{Argumentless}'s constructor and @code{Variadic}'s constructor also
takes a descriptive short name of a argument associated with the option
optioned anywhere, and the alterantive array is variadic if places last.
@c@node Bash version
@c@chapter Bash version
@c@node C version
@c@chapter C version
@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include fdl.texinfo
@bye
|
