You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The option parser is generated based on the docstring above that is passed to `docopt` function. `docopt` parses the usage pattern (`"Usage: ..."`) and option descriptions (lines starting with dash "`-`") and ensures that the program invocation matches the usage pattern; it parses options, arguments and commands based on that. The basic idea is that *a good help message has all necessary information in it to make a parser*.
`docopt` takes 1 required and 5 optional arguments:
49
+
50
+
-`doc` is a string that contains a **help message** that will be parsed to create the option parser. The simple rules of how to write such a help message are described at [docopt.org][]. Here is a quick example of such a string:
-`argv` is an optional argument vector; by default `docopt` uses the argument vector passed to your program (`commandLineParams()`). Alternatively you can supply a list of strings like `@["--verbose", "-o", "hai.txt"]`.
61
+
62
+
-`help`, by default `true`, specifies whether the parser should automatically print the help message (supplied as `doc`) and terminate, in case `-h` or `--help` option is encountered (options should exist in usage pattern). If you want to handle `-h` or `--help` options manually (as other options), set `help = false`.
63
+
64
+
-`version`, by default `nil`, is an optional argument that specifies the version of your program. If supplied, then, (assuming `--version` option is mentioned in usage pattern) when parser encounters the `--version` option, it will print the supplied version and terminate. `version` can be any string, e.g. `"2.1.0rc1"`.
65
+
> Note, when `docopt` is set to automatically handle `-h`, `--help` and `--version` options, you still need to mention them in usage pattern for this to work. Also, for your users to know about them.
66
+
67
+
-`optionsFirst`, by default `false`. If set to `true` will disallow mixing options and positional arguments. I.e. after first positional argument, all arguments will be interpreted as positional even if the look like options. This can be used for strict compatibility with POSIX, or if you want to dispatch your arguments to other programs.
68
+
69
+
-`quit`, by default `true`, specifies whether [`quit()`][quit] should be called after encountering invalid arguments or printing the help message (see `help`). Setting this to `false` will allow `docopt` to raise a `DocoptExit` exception (with the `usage` member set) instead.
70
+
71
+
If the `doc` string is invalid, `DocoptLanguageError` will be raised.
72
+
73
+
The **return** value is a [`Table`][table] with options, arguments and commands as keys, spelled exactly like in your help message. Long versions of options are given priority. For example, if you invoke the top example as:
74
+
75
+
naval_fate ship Guardian move 100 150 --speed=15
76
+
77
+
the result will be:
78
+
79
+
```nim
80
+
{"--drifting": false, "mine": false,
81
+
"--help": false, "move": true,
82
+
"--moored": false, "new": false,
83
+
"--speed": "15", "remove": false,
84
+
"--version": false, "set": false,
85
+
"<name>": @["Guardian"], "ship": true,
86
+
"<x>": "100", "shoot": false,
87
+
"<y>": "150"}
88
+
```
89
+
90
+
Note that this is not how the values are actually stored, because a `Table` can hold values of only one type. For that reason, a variant `Value` type is needed. `Value`'s only accessible member is `kind: ValueKind` (which shouldn't be needed anyway, because it is known beforehand). `ValueKind` is one of:
91
+
92
+
-`vkNone` (No value)
93
+
94
+
This kind of `Value` appears when there is an option which hasn't been set and has no default. It is `false` when converted `toBool`.
95
+
96
+
-`vkBool` (A boolean)
97
+
98
+
This represents whether a boolean flag has been set or not. Just use it in a boolean context (conversion `toBool` is present).
99
+
100
+
-`vkInt` (An integer)
101
+
102
+
An integer represents how many times a flag has been repeated (if it is possible to supply it multiple times). Use `value.len` to obtain this `int`, or just use the value in a boolean context to find out whether this flag is present at least once.
103
+
104
+
-`vkStr` (A string)
105
+
106
+
Any option that has a user-supplied value will be represented as a `string` (conversion to integers, etc, does not happen). To obtain this string, use `$value`.
107
+
108
+
-`vkList` (A list of strings)
109
+
110
+
Any value that can be supplied multiple times will be represented by a `seq[string]`, even if the user provides just one. To obtain this `seq`, use `@value`. To obtain its length, use `value.len` or `@value.len`. To obtain the n-th value (0-indexed), both `value[i]` and `@value[i]` will work. If you are sure there is exactly one value, `$value` is the same as `value[0]`.
111
+
112
+
Look [in the source code](src/docopt.nim#L30) to find out more about these conversions.
113
+
114
+
39
115
Installation
40
116
------------
41
117
42
-
`git clone` and `nimble install`
118
+
nimble install docopt
119
+
120
+
This library has no dependencies outside the standard library. An impure [`re`][re] library is used.
0 commit comments