diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,7 @@ +### 0.7.0.2 + +- Minor docs/README tweaks [#13] + ### 0.7.0.1 - Fix docs in README and in Docopt.hs diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ Save your help text to a file (i.e. `USAGE.txt`): - Usage: + Usage: myprog cat myprog echo [--caps] @@ -19,7 +19,7 @@ -c, --caps Caps-lock the echoed argument Then, in your `Myprog.hs`: - + ```haskell {-# LANGUAGE QuasiQuotes #-} import Control.Monad (when) @@ -66,22 +66,22 @@ ================ Docopt only cares about 2 parts of your help text: - + - **Usage patterns**, e.g.: ``` - Usage: + Usage: my_program [-hs] [-o=] [--quiet | --verbose] [...] ``` - These begin with `Usage:` (case-insensitive), and end with a blank line. + These begin with `Usage:` (case-insensitive), and end with a blank line. -- **Option descriptions**, e.g.: +- **Option descriptions**, e.g.: ``` Options: -h --help show this -s --sorted sorted output - -o= specify output file + -o= specify output file [default: ./test.txt] --quiet print less text --verbose print more text @@ -92,21 +92,21 @@ Usage Patterns -------------- -- #### `` +- #### `` or `ARGUMENT` - Positional arguments. Constructed via `argument`, i.e. `argument "arg"` matches an `` element in the help text. + Positional arguments. Constructed via `argument`, i.e. `argument "arg"` matches an `` element in the help text, and `argument "ARG"` matches an `ARG` element. - #### `--flag` or `--option=` - Options are typically optional (though this is up to you), and can be either boolean (present/absent), as in `--flag`, or expect a trailing argument, as in `--option=`. Arguments can be separated from the option name by an `=` or a single space, and can be in `` form or `ARG` form (though consistency of style is recommended, it is not enforced). + Options are typically optional (though this is up to you), and can be either boolean (present/absent), as in `--flag`, or expect a trailing argument, as in `--option=` or `--option=ARG`. Arguments can be separated from the option name by an `=` or a single space, and can be specified as `` or `ARG` (consistency of style is recommended, but it is not enforced). - Short-style options, as in `-f` or `-f ARG`, are also allowed. Synonyms between different spellings of the same option (e.g. `-v` and `--verbose`) can be established in the option descriptions (see below). Short-style options can also be stacked, as in `-rfA`. When options are stacked, `-rfA` is effectively equivalent to `(-r | -f | -A)...` to the argument parser. + Short-style options, as in `-f` or `-f ARG` or `-f=`, are also allowed. Synonyms between different spellings of the same option (e.g. `-v` and `--verbose`) can be established in the option descriptions (see below). Short-style options can also be stacked, as in `-rfA`. When options are stacked, `-rfA` is effectively equivalent to `(-r | -f | -A)...` to the argument parser. - You can match a long-style option `--flag` with `longOption "flag"`, and a short-style option `-f` with `shortOption 'f'` The same constructor is used whether the option expects an argument or not. + You can match a long-style option `--option` or `--option=` with `longOption "option"`, and a short-style option `-f` `or -f=` with `shortOption 'f'`. _Note that neither `--option=` nor `-f=` would be matched by `argument "arg"`._ - #### `command` - Anything not recognized as a positional argument or a short or long option is treated as a command (or subcommand, same thing to docopt). A command named `pull` can be matched with `command "pull"`. + Anything not recognized as a positional argument or a short or long option is treated as a command (or subcommand, same thing to docopt). A command named `pull` can be matched with `command "pull"`. - #### `[]` (brackets) e.g. `command [--option]` @@ -118,7 +118,7 @@ - #### `|` (pipe) e.g. `command [--quiet | --verbose]` - A pipe `|` separates mutually elements in a group. A group could be elements inside `[]`, `()`, or the whole usage line. + A pipe `|` separates mutually exclusive elements in a group. A group could be elements inside `[]`, `()`, or the whole usage line. ``` Usage: @@ -139,7 +139,7 @@ - #### `[-]` and `[--]` - Single hyphen `-` is used by convention to specify using `stdin` as input instead of reading a file. Double hyphen `--` is typically used to manually separate leading options from trailing positional arguments. Both of these are treated as `command`s, and so are perfectly legal in usage patterns. They are typically optional elements, but can be required if you drop the `[]`. + Single hyphen `-` is used by convention to specify using `stdin` as input instead of reading a file. Double hyphen `--` is typically used to manually separate leading options from trailing positional arguments. Both of these are treated as `command`s, and so are perfectly legal in usage patterns. They are typically optional elements, but can be required if you drop the `[]`. Option descriptions ------------------- @@ -152,7 +152,7 @@ **Rules**: - Any line *after* the usage patterns whose first non-space character is a `-` is treated as an option description. (`Options:` prefix line not required). - + ``` Options: --help # invalid: line does not start with '-' --verbose # good @@ -164,9 +164,9 @@ Usage: myprog --help | --verbose - Options: + Options: -h, --help Print help text - -v --verbose Print help text twice + -v --verbose Print help text twice ``` Here, `myprog --help` and `myprog -h` will both work the same, as will `myprog --verbose` and `myprog -v`. @@ -189,7 +189,7 @@ --opt1 ARG1 Option 1. --opt2= Option 2. # BAD: use 2 spaces -a Option 3. - -b=ARG4 Option 4. + -b=ARG4 Option 4. ``` - Options that expect arguments can be given a default value, in the form `[default: ]`. Default values do not need to be on the same line @@ -197,7 +197,7 @@ ``` --host=NAME Host to listen on. [default: localhost] --port=PORT Port number [default: 8080] - --directory=DIR This option has an especially long description + --directory=DIR This option has an especially long description explaining its meaning. [default: ./] ``` diff --git a/System/Console/Docopt/Public.hs b/System/Console/Docopt/Public.hs --- a/System/Console/Docopt/Public.hs +++ b/System/Console/Docopt/Public.hs @@ -153,14 +153,20 @@ command = Command -- | For @Usage: prog \@, ask for @argument \"file\"@. +-- +-- __Note:__ A @Usage: prog --output=\@ is /not/ matched by @argument \"file\"@. See 'longOption'. argument :: String -> Option argument = Argument -- | For @Usage: prog -h@, ask for @shortOption \'h\'@. +-- +-- For @Usage: prog -o=\@, ask for @shortOption \'o\'@. shortOption :: Char -> Option shortOption = ShortOption --- | For @Usage: prog --version@, ask for @shortOption \"version\"@. +-- | For @Usage: prog --version@, ask for @longOption \"version\"@. +-- +-- For @Usage: prog --output=\@, ask for @longOption \"output\"@. longOption :: String -> Option longOption = LongOption diff --git a/docopt.cabal b/docopt.cabal --- a/docopt.cabal +++ b/docopt.cabal @@ -1,5 +1,5 @@ name: docopt -version: 0.7.0.1 +version: 0.7.0.2 synopsis: A command-line interface parser that will make you smile description: Docopt parses command-line interface usage text that adheres to a familiar syntax, and from it builds a command-line argument parser that will ensure your program is invoked correctly with the available options specified in the usage text. This allows the developer to write a usage text and get an argument parser for free.