Skip to content

Commit 373deeb

Browse files
committed
Use 3-backticks for code blocks in README
1 parent 77c408a commit 373deeb

File tree

1 file changed

+80
-54
lines changed

1 file changed

+80
-54
lines changed

README.md

Lines changed: 80 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -19,16 +19,18 @@ Typical usage is to create a class to represent the set of parsed arguments,
1919
which 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

103117
The delegates returned by any of these methods also have a few methods for setting
104118
optional 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

129147
For 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

134154
The name ("DEST", here) is used in error handling and help text.
135155

136156
For 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

141163
The range indicates how many arguments should be collected, and actually
142164
defaults to the value shown in this example. As the name suggests, the
@@ -145,11 +167,13 @@ resulting property will be a `List`.
145167
Both of these methods accept an optional transform function for converting
146168
arguments 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
165189
As a convenience, these exceptions can be handled by using the `runMain`
166190
extension 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

173199
Note 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

Comments
 (0)