@@ -19,16 +19,18 @@ Typical usage is to create a class to represent the set of parsed arguments,
1919which are in turn each represented by properties that delegate to an
2020` ArgParser ` :
2121
22- class MyArgs(parser: ArgParser) {
23- val verbose by parser.flagging("-v", "--verbose",
24- help="enable verbose mode")
22+ ``` kotlin
23+ class MyArgs (parser : ArgParser ) {
24+ val verbose by parser.flagging(" -v" , " --verbose" ,
25+ help= " enable verbose mode" )
2526
26- val name by parser.storing("-N", "--name",
27- help = "name of the widget")
27+ val name by parser.storing(" -N" , " --name" ,
28+ help = " name of the widget" )
2829
29- val size by parser.storing("-s", "--size",
30- help = "size of the plumbus") { toInt() }
31- }
30+ val size by parser.storing(" -s" , " --size" ,
31+ help = " size of the plumbus" ) { toInt() }
32+ }
33+ ```
3234
3335
3436## Option Types
@@ -38,8 +40,10 @@ Various types of options can be parsed from the command line arguments:
3840- Boolean flags are created by asking the parser for a ` flagging ` delegate. One
3941 or more option names, either short or long style, must be provided:
4042
41- val verbose by parser.flagging("-v", "--verbose",
42- help = "enable verbose mode")
43+ ``` kotlin
44+ val verbose by parser.flagging(" -v" , " --verbose" ,
45+ help = " enable verbose mode" )
46+ ```
4347
4448 Here the presence of either ` -v ` or ` --verbose ` options in the
4549 arguments will cause the ` Boolean ` property ` verbose ` to be ` true ` , otherwise
@@ -48,36 +52,44 @@ Various types of options can be parsed from the command line arguments:
4852- Single argument options are created by asking the parser for a
4953 ` storing ` delegate.
5054
51- val name by parser.storing("-N", "--name",
52- help = "name of the widget")
55+ ``` kotlin
56+ val name by parser.storing(" -N" , " --name" ,
57+ help = " name of the widget" )
58+ ```
5359
5460 Here either ` -N ` or ` --name ` with an argument will cause ` name ` to have that
5561 argument as its value.
5662
5763 A function can also be supplied to transform the argument into the desired
5864 type. Here the ` size ` property will be an ` Int ` rather than a ` String ` :
5965
60- val size by parser.storing("-s", "--size",
61- help = "size of the plumbus") { toInt() }
66+ ``` kotlin
67+ val size by parser.storing(" -s" , " --size" ,
68+ help = " size of the plumbus" ) { toInt() }
69+ ```
6270
6371- Options that add to a ` Collection ` each time they
6472 appear in the arguments are created with using the ` adding ` delegate. Just like ` storing `
6573 delegates, a transform function may optionally be supplied:
6674
67- val includeDirs by parser.adding(
68- "-I", help = "directory to search for header files") { File(this) }
75+ ``` kotlin
76+ val includeDirs by parser.adding(
77+ " -I" , help = " directory to search for header files" ) { File (this ) }
78+ ```
6979
7080 Now each time the ` -I ` option appears, its argument is appended to
7181 ` includeDirs ` .
7282
7383- For choosing between a fixed set of values (typically, but not necessarily,
7484 from an enum), a ` mapping ` delegate can be used:
7585
76- val mode by parser.mapping(
77- "--fast" to Mode.FAST,
78- "--small" to Mode.SMALL,
79- "--quiet" to Mode.QUIET,
80- help = "mode of operation")
86+ ``` kotlin
87+ val mode by parser.mapping(
88+ " --fast" to Mode .FAST ,
89+ " --small" to Mode .SMALL ,
90+ " --quiet" to Mode .QUIET ,
91+ help = " mode of operation" )
92+ ```
8193
8294 Here the ` mode ` property will be set to the corresponding ` Mode ` value depending
8395 on which of ` --fast ` , ` --small ` , and ` --quiet ` appears (last) in the arguments.
@@ -86,19 +98,21 @@ Various types of options can be parsed from the command line arguments:
8698 ` option ` method can be used. (The methods described above are convenience
8799 methods built on top of ` option ` .)
88100
89- val zaphod by parser.option(
90- "--fibonacci",
91- help = "collects fibonnaci sequence, remembers length") {
92- var prev = 0
93- var current = 1
94- var result = 0
95- while (peek() == current) {
96- result++
97- prev, current = current, current+prev
98- next()
99- }
100- return result
101- }
101+ ``` kotlin
102+ val zaphod by parser.option(
103+ " --fibonacci" ,
104+ help = " collects fibonnaci sequence, remembers length" ) {
105+ var prev = 0
106+ var current = 1
107+ var result = 0
108+ while (peek() == current) {
109+ result++
110+ prev, current = current, current+ prev
111+ next()
112+ }
113+ return result
114+ }
115+ ```
102116
103117The delegates returned by any of these methods also have a few methods for setting
104118optional attributes:
@@ -107,18 +121,22 @@ optional attributes:
107121 default value, and hence will be required options unless a default
108122 value is provided. This is done with the ` default ` method:
109123
110- val name by parser.storing("-N", "--name", help="...")
111- .default("John Doe")
124+ ``` kotlin
125+ val name by parser.storing(" -N" , " --name" , help= " ..." )
126+ .default(" John Doe" )
127+ ```
112128
113129- Sometimes it's easier to validate an option at the end pf parsing, in which
114130 case the ` addValidator ` method can be used.
115131
116- val percentages by parser.adding("--percentages", help="...") { toInt() }
117- .addValidator {
118- if (sum() != 100)
119- throw InvalidArgumentException(
120- "Percentages must add up to 100%")
121- }
132+ ``` kotlin
133+ val percentages by parser.adding(" --percentages" , help= " ..." ) { toInt() }
134+ .addValidator {
135+ if (sum() != 100 )
136+ throw InvalidArgumentException (
137+ " Percentages must add up to 100%" )
138+ }
139+ ```
122140
123141
124142## Positional Arguments
@@ -128,15 +146,19 @@ Positional arguments are collected by using the `positional` and
128146
129147For a single positional argument:
130148
131- val destination by parser.positional("DEST",
132- help="destination filename")
149+ ``` kotlin
150+ val destination by parser.positional(" DEST" ,
151+ help= " destination filename" )
152+ ```
133153
134154The name ("DEST", here) is used in error handling and help text.
135155
136156For a list of positional arguments:
137157
138- val sources by parser.positionalList("SOURCE", 1..Int.MAX_VALUE,
139- help="source filename")
158+ ``` kotlin
159+ val sources by parser.positionalList(" SOURCE" , 1 .. Int .MAX_VALUE ,
160+ help= " source filename" )
161+ ```
140162
141163The range indicates how many arguments should be collected, and actually
142164defaults to the value shown in this example. As the name suggests, the
@@ -145,11 +167,13 @@ resulting property will be a `List`.
145167Both of these methods accept an optional transform function for converting
146168arguments from ` String ` to whatever type is actually desired:
147169
148- val destination by parser.positional(
149- "DEST", help="...") { File(this) }
170+ ``` kotlin
171+ val destination by parser.positional(" DEST" ,
172+ help= " ..." ) { File (this ) }
150173
151- val sources by parser.positionalList(
152- "SOURCE", 1..Int.MAX_VALUE, help="...") { File(this) }
174+ val sources by parser.positionalList(" SOURCE" , 1 .. Int .MAX_VALUE ,
175+ help= " ..." ) { File (this ) }
176+ ```
153177
154178
155179## Error Handling
@@ -165,10 +189,12 @@ Additional post-parsing validation can be performed on a delegate using
165189As a convenience, these exceptions can be handled by using the ` runMain `
166190extension function:
167191
168- fun main(args: Array<String>) =
169- MyArgs(ArgParser(args)).runMain(PROGRAM_NAME) {
170- println("Hello, {name}!")
171- }
192+ ``` kotlin
193+ fun main (args : Array <String >) =
194+ MyArgs (ArgParser (args)).runMain(PROGRAM_NAME ) {
195+ println (" Hello, {name}!" )
196+ }
197+ ```
172198
173199Note that parsing does not take place until at least one delegate is read, or
174200` force ` is called manually. It may be desirable to call ` force ` on the parser
0 commit comments