Merge pull request #266 from pacak/rc-0.9.4

Release 0.9.4

documentation/_documentation/_2_howto/_0_testing/index.md

@@ -0,0 +1,43 @@
+#### Testing your parsers
+
+You can test values your parser produces and expected output
+
+```no_run
+#[derive(Debug, Clone, Bpaf)]
+#[bpaf(options)]
+pub struct Options {
+    pub user: String
+}
+
+#[test]
+fn test_my_options() {
+    let help = options()
+        .run_inner(&["--help"])
+        .unwrap_err()
+        .unwrap_stdout();
+    let expected_help = "\
+Usage --user=ARG
+<skip>
+";
+
+    assert_eq!(help, expected_help);
+}
+
+#[test]
+fn test_value() {
+    let value = options()
+         .run_inner(&["--user", "Bob"])
+         .unwrap();
+    assert_eq!(value.user, "Bob");
+}
+```
+
+[`OptionParser::run_inner`] takes [`Args`] or anything that can be converted to it, in most
+cases using a static slice with strings is enough.
+
+Easiest way to consume [`ParseFailure`] for testing purposes is with
+[`ParseFailure::unwrap_stderr`] and [`ParseFailure::unwrap_stdout`] - result will lack any colors
+even with them enabled which makes testing easier.
+
+Successful result parse produces a value, "failed" parse produces stdout or stderr outputs -
+stdout to print help message or version number and stderr to print the error message.

documentation/_documentation/_2_howto/_1_completion/index.md

@@ -0,0 +1,49 @@
+#### Dynamic shell completion
+
+`bpaf` implements shell completion to allow to automatically fill in not only flag and command
+names, but also argument and positional item values.
+
+1. Enable `autocomplete` feature:
+
+
+	```toml
+	bpaf = { version = "0.9", features = ["autocomplete"] }
+	```
+
+2. Decorate [`argument`](crate::parsers::NamedArg::argument) and [`positional`] parsers with
+    [`Parser::complete`] to provide completion functions for arguments
+
+
+3. Depending on your shell generate appropriate completion file and place it to whereever your
+    shell is going to look for it, name of the file should correspond in some way to name of
+    your program. Consult manual for your shell for the location and named conventions:
+
+	 1. **bash**
+		```console
+		$ your_program --bpaf-complete-style-bash >> ~/.bash_completion
+		```
+
+	 1. **zsh**: note `_` at the beginning of the filename
+		```console
+		$ your_program --bpaf-complete-style-zsh > ~/.zsh/_your_program
+		```
+
+	 1. **fish**
+		```console
+		$ your_program --bpaf-complete-style-fish > ~/.config/fish/completions/your_program.fish
+		```
+
+	 1. **elvish**
+		```console
+		$ your_program --bpaf-complete-style-elvish >> ~/.config/elvish/rc.elv
+		```
+
+4. Restart your shell - you need to done it only once or optionally after bpaf major version
+    upgrade: generated completion files contain only instructions how to ask your program for
+    possible completions and don’t change even if options are different.
+
+
+5. Generated scripts rely on your program being accessible in $PATH
+
+
+

documentation/_documentation/_2_howto/index.md

@@ -1,7 +1 @@
-#### Parsing cookbook
-
-
-While `bpaf`'s design tries to cover the most common use cases, mostly
-[posix conventions](https://pubs.opengroup.org/onlinepubs/9699919799.2018edition/basedefs/V1_chap12.html),
-it can also handle some more unusual requirements. It might come at the cost of having to write
-more code, more confusing error messages or worse performance, but it will get the job done.
+#### HOWTO - practical, oriented to solving problems guides

documentation/_documentation/_3_cookbook/index.md

@@ -0,0 +1,7 @@
+#### Parsing cookbook
+How to parse less frequent combinations
+
+While `bpaf`'s design tries to cover the most common use cases, mostly
+[posix conventions](https://pubs.opengroup.org/onlinepubs/9699919799.2018edition/basedefs/V1_chap12.html),
+it can also handle some more unusual requirements. It might come at the cost of having to write
+more code, more confusing error messages or worse performance, but it will get the job done.