Merge pull request #259 from pacak/rc-0.9.4

Update more documentation
pacak · Aug 6, 2023 · babd3e6 · babd3e6
2 parents 9c56e78 + 27b0c90
commit babd3e6
Show file tree

Hide file tree

Showing 34 changed files with 264 additions and 875 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,7 +1,6 @@
 /target
 Cargo.lock
 .xwin-cache/
-/docs/src/*.rs
 /tarp
 /dotfiles
 /legacy/target

diff --git a/docs/src/boxed/cases.txt b/docs/src/boxed/cases.txt
diff --git a/docs/src/boxed/combine.rs b/docs/src/boxed/combine.rs
diff --git a/docs/src/dd/cases.txt b/docs/src/dd/cases.txt
diff --git a/docs/src/dd/example.rs b/docs/src/dd/example.rs
diff --git a/docs/src/find/cases.txt b/docs/src/find/cases.txt
diff --git a/docs/src/find/example.rs b/docs/src/find/example.rs
diff --git a/docs/src/numeric_prefix/cases.txt b/docs/src/numeric_prefix/cases.txt
diff --git a/docs/src/numeric_prefix/example.rs b/docs/src/numeric_prefix/example.rs
diff --git a/docs/src/xorg/cases.txt b/docs/src/xorg/cases.txt
diff --git a/docs/src/xorg/example.rs b/docs/src/xorg/example.rs
diff --git a/docs2/src/boxed/cases.md b/docs2/src/boxed/cases.md
@@ -0,0 +1,10 @@
+It is also possible to make dynamic choice about the parsers. This example defines two parsers
+for distance - imperial and metric and picks one from some source available at runtime only.
+
+Help message will contain only one parser
+
+> --help
+
+and only one parser will produce a result
+
+> --distance 10
diff --git a/docs2/src/boxed/combine.rs b/docs2/src/boxed/combine.rs
@@ -0,0 +1,26 @@
+//
+use bpaf::*;
+
+pub fn options() -> OptionParser<f64> {
+    let miles = long("distance")
+        .help("distance in miles")
+        .argument::<f64>("MILES")
+        .map(|d| d * 1.609344);
+
+    let km = long("distance")
+        .help("distance in km")
+        .argument::<f64>("KM");
+
+    // suppose this is reading from config fule
+    let use_metric = true;
+
+    // without use of `boxed` here branches have different types so it won't typecheck
+    // boxed make it so branches have the same type as long as they return the same type
+    let distance = if use_metric {
+        km.boxed()
+    } else {
+        miles.boxed()
+    };
+
+    distance.to_options()
+}
diff --git a/docs2/src/numeric_prefix/cases.md b/docs2/src/numeric_prefix/cases.md
@@ -0,0 +1,16 @@
+If `bpaf` can parse first positional argument as number - it becomes a numeric prefix
+
+> 10 eat
+
+Otherwise it gets ignored
+
+> "just eat"
+
+
+If validation passes but second argument is missing - in this example there's no fallback
+
+> 10
+
+Help should show that the prefix is optional
+
+> --help
diff --git a/documentation/_documentation/_2_howto/_03_command_chaining/index.md b/documentation/_documentation/_2_howto/_03_command_chaining/index.md
@@ -4,4 +4,4 @@ Lets you do things like `setup.py sdist bdist`: [command chaining](https://click
 With [`adjacent`](crate::parsers::ParseCommand::adjacent)
 `bpaf` allows you to have several commands side by side instead of being nested.
 
-#![cfg_attr(not(doctest), doc = include_str!("docs/adjacent_2.md"))]
+#![cfg_attr(not(doctest), doc = include_str!("docs2/adjacent_command.md"))]
diff --git a/documentation/_documentation/_2_howto/_04_multi_value/index.md b/documentation/_documentation/_2_howto/_04_multi_value/index.md
@@ -3,4 +3,4 @@
 By default arguments take at most one value, you can create multi value options by using
 [`adjacent`](crate::parsers::ParseCon::adjacent) modifier
 
-#![cfg_attr(not(doctest), doc = include_str!("docs/adjacent_0.md"))]
+#![cfg_attr(not(doctest), doc = include_str!("docs2/adjacent_struct_0.md"))]
diff --git a/documentation/_documentation/_2_howto/_05_struct_groups/index.md b/documentation/_documentation/_2_howto/_05_struct_groups/index.md
@@ -19,4 +19,4 @@ overwriting previous one.
          --sensor-i2c-address=0x49 \
 ```
 
-#![cfg_attr(not(doctest), doc = include_str!("docs/adjacent_1.md"))]
+#![cfg_attr(not(doctest), doc = include_str!("docs2/adjacent_struct_1.md"))]
diff --git a/documentation/_documentation/_2_howto/_06_multi_flag/index.md b/documentation/_documentation/_2_howto/_06_multi_flag/index.md
@@ -3,4 +3,4 @@
 So you can parse things while parsing things. Not sure why you might need this, but you can
 :)
 
-#![cfg_attr(not(doctest), doc = include_str!("docs/adjacent_4.md"))]
+#![cfg_attr(not(doctest), doc = include_str!("docs2/adjacent_struct_4.md"))]
diff --git a/documentation/_documentation/_2_howto/_07_skip_positional/index.md b/documentation/_documentation/_2_howto/_07_skip_positional/index.md
@@ -1,3 +1,7 @@
 #### Skipping optional positional items if parsing or validation fails
 
-#![cfg_attr(not(doctest), doc = include_str!("docs/numeric_prefix.md"))]
+Combinations like [`Parser::optional`] and
+[`ParseOptional::catch`](crate::parsers::ParseOptional::catch) allow to try to parse something
+and then handle the error as if pase attempt never existed
+
+#![cfg_attr(not(doctest), doc = include_str!("docs2/numeric_prefix.md"))]
diff --git a/documentation/_documentation/_2_howto/_08_cargo_helper/index.md b/documentation/_documentation/_2_howto/_08_cargo_helper/index.md
@@ -1,5 +1,6 @@
 #### Implementing cargo commands
 
-With [`cargo_helper`](crate::batteries::cargo_helper) you can use your application as a `cargo` command
+With [`cargo_helper`](crate::batteries::cargo_helper) you can use your application as a `cargo` command.
+You will need to enable `batteries` feature while importing `bpaf`.
 
-#![cfg_attr(not(doctest), doc = include_str!("docs/cargo_helper.md"))]
+#![cfg_attr(not(doctest), doc = include_str!("docs2/cargo_helper.md"))]
diff --git a/src/_documentation.rs b/src/_documentation.rs
@@ -2246,7 +2246,7 @@
             //! With [`adjacent`](crate::parsers::ParseCommand::adjacent)
             //! `bpaf` allows you to have several commands side by side instead of being nested.
             //! 
-            #![cfg_attr(not(doctest), doc = include_str!("docs/adjacent_2.md"))]
+            #![cfg_attr(not(doctest), doc = include_str!("docs2/adjacent_command.md"))]
             //!
             //!
             //! &nbsp;
@@ -2297,7 +2297,7 @@
             //! By default arguments take at most one value, you can create multi value options by using
             //! [`adjacent`](crate::parsers::ParseCon::adjacent) modifier
             //! 
-            #![cfg_attr(not(doctest), doc = include_str!("docs/adjacent_0.md"))]
+            #![cfg_attr(not(doctest), doc = include_str!("docs2/adjacent_struct_0.md"))]
             //!
             //!
             //! &nbsp;
@@ -2364,7 +2364,7 @@
             //!          --sensor-i2c-address=0x49 \
             //! ```
             //! 
-            #![cfg_attr(not(doctest), doc = include_str!("docs/adjacent_1.md"))]
+            #![cfg_attr(not(doctest), doc = include_str!("docs2/adjacent_struct_1.md"))]
             //!
             //!
             //! &nbsp;
@@ -2415,7 +2415,7 @@
             //! So you can parse things while parsing things. Not sure why you might need this, but you can
             //! :)
             //! 
-            #![cfg_attr(not(doctest), doc = include_str!("docs/adjacent_4.md"))]
+            #![cfg_attr(not(doctest), doc = include_str!("docs2/adjacent_struct_4.md"))]
             //!
             //!
             //! &nbsp;
@@ -2463,7 +2463,11 @@
             //! 
             //! #### Skipping optional positional items if parsing or validation fails
             //! 
-            #![cfg_attr(not(doctest), doc = include_str!("docs/numeric_prefix.md"))]
+            //! Combinations like [`Parser::optional`] and
+            //! [`ParseOptional::catch`](crate::parsers::ParseOptional::catch) allow to try to parse something
+            //! and then handle the error as if pase attempt never existed
+            //! 
+            #![cfg_attr(not(doctest), doc = include_str!("docs2/numeric_prefix.md"))]
             //!
             //!
             //! &nbsp;
@@ -2511,9 +2515,10 @@
             //! 
             //! #### Implementing cargo commands
             //! 
-            //! With [`cargo_helper`](crate::batteries::cargo_helper) you can use your application as a `cargo` command
+            //! With [`cargo_helper`](crate::batteries::cargo_helper) you can use your application as a `cargo` command.
+            //! You will need to enable `batteries` feature while importing `bpaf`.
             //! 
-            #![cfg_attr(not(doctest), doc = include_str!("docs/cargo_helper.md"))]
+            #![cfg_attr(not(doctest), doc = include_str!("docs2/cargo_helper.md"))]
             //!
             //!
             //! &nbsp;