Merge pull request #257 from pacak/rc-0.9.4

changes for 0.9.4

Changelog.md

@@ -1,5 +1,11 @@
 # Change Log
 
+## bpaf [0.9.4] - Unreleased
+- add `help` to `ParseFlag` and `ParseArgument `
+- stop deprecating `Parser::run`
+- documentation
+- changes to rendered markdown
+
 ## bpaf [0.9.3], bpaf_derive [0.5.3] - 2023-07-26
 - `Parser::collect` allows to collect multiple items into an arbitrary `FromIterator` collection
 - Bugfix in parsing for unit structs

docs2/src/deb_fallback/cases.md

@@ -0,0 +1,17 @@
+`fallback` changes parser to fallback to a default value used when argument is not specified
+
+>
+
+If value is present - fallback value is ignored
+
+> --jobs 10
+
+Parsing errors are preserved and preserved to user
+
+> --jobs ten
+
+With [`display_fallback`](ParseFallback::display_fallback) and
+[`debug_fallback`](ParseFallback::debug_fallback) you can make it so default value
+is visible in `--help` output
+
+> --help

docs2/src/deb_fallback/combine.rs

@@ -0,0 +1,15 @@
+//
+use bpaf::*;
+#[derive(Debug, Clone)]
+pub struct Options {
+    jobs: usize,
+}
+
+pub fn options() -> OptionParser<Options> {
+    let jobs = long("jobs")
+        .help("Number of jobs")
+        .argument("JOBS")
+        .fallback(42)
+        .debug_fallback();
+    construct!(Options { jobs }).to_options()
+}

docs2/src/deb_fallback/derive.rs

@@ -0,0 +1,10 @@
+//
+use bpaf::*;
+#[derive(Debug, Clone, Bpaf)]
+#[bpaf(options)]
+#[allow(dead_code)]
+pub struct Options {
+    /// Number of jobs
+    #[bpaf(argument("JOBS"), fallback(42), debug_fallback)]
+    jobs: usize,
+}

docs2/src/deb_fallback_with/cases.md

@@ -0,0 +1,16 @@
+`fallback_with` changes parser to fallback to a value that comes from a potentially failing
+computation when argument is not specified
+
+>
+
+If value is present - fallback value is ignored
+
+> --version 10
+
+Parsing errors are preserved and preserved to user
+
+> --version ten
+
+`bpaf` encases parsers with fallback value of some sort in usage with `[]`
+
+> --help

docs2/src/deb_fallback_with/combine.rs

@@ -0,0 +1,19 @@
+//
+use bpaf::*;
+fn try_to_get_version() -> Result<usize, &'static str> {
+    Ok(42)
+}
+
+#[derive(Debug, Clone)]
+pub struct Options {
+    version: usize,
+}
+
+pub fn options() -> OptionParser<Options> {
+    let version = long("version")
+        .help("Specify protocol version")
+        .argument("VERS")
+        .fallback_with(try_to_get_version)
+        .debug_fallback();
+    construct!(Options { version }).to_options()
+}

docs2/src/deb_fallback_with/derive.rs

@@ -0,0 +1,13 @@
+//
+use bpaf::*;
+fn try_to_get_version() -> Result<usize, &'static str> {
+    Ok(42)
+}
+
+#[derive(Debug, Clone, Bpaf)]
+#[bpaf(options)]
+pub struct Options {
+    #[bpaf(argument("VERS"), fallback_with(try_to_get_version), debug_fallback)]
+    /// Specify protocol version
+    version: usize,
+}

docs2/src/dis_fallback/cases.md

@@ -0,0 +1,17 @@
+`fallback` changes parser to fallback to a default value used when argument is not specified
+
+>
+
+If value is present - fallback value is ignored
+
+> --jobs 10
+
+Parsing errors are preserved and preserved to user
+
+> --jobs ten
+
+With [`display_fallback`](ParseFallback::display_fallback) and
+[`debug_fallback`](ParseFallback::debug_fallback) you can make it so default value
+is visible in `--help` output
+
+> --help

docs2/src/dis_fallback/combine.rs

@@ -0,0 +1,15 @@
+//
+use bpaf::*;
+#[derive(Debug, Clone)]
+pub struct Options {
+    jobs: usize,
+}
+
+pub fn options() -> OptionParser<Options> {
+    let jobs = long("jobs")
+        .help("Number of jobs")
+        .argument("JOBS")
+        .fallback(42)
+        .display_fallback();
+    construct!(Options { jobs }).to_options()
+}

docs2/src/dis_fallback/derive.rs

@@ -0,0 +1,10 @@
+//
+use bpaf::*;
+#[derive(Debug, Clone, Bpaf)]
+#[bpaf(options)]
+#[allow(dead_code)]
+pub struct Options {
+    /// Number of jobs
+    #[bpaf(argument("JOBS"), fallback(42), display_fallback)]
+    jobs: usize,
+}

docs2/src/dis_fallback_with/cases.md

@@ -0,0 +1,16 @@
+`fallback_with` changes parser to fallback to a value that comes from a potentially failing
+computation when argument is not specified
+
+>
+
+If value is present - fallback value is ignored
+
+> --version 10
+
+Parsing errors are preserved and preserved to user
+
+> --version ten
+
+`bpaf` encases parsers with fallback value of some sort in usage with `[]`
+
+> --help

docs2/src/dis_fallback_with/combine.rs

@@ -0,0 +1,19 @@
+//
+use bpaf::*;
+fn try_to_get_version() -> Result<usize, &'static str> {
+    Ok(42)
+}
+
+#[derive(Debug, Clone)]
+pub struct Options {
+    version: usize,
+}
+
+pub fn options() -> OptionParser<Options> {
+    let version = long("version")
+        .help("Specify protocol version")
+        .argument("VERS")
+        .fallback_with(try_to_get_version)
+        .display_fallback();
+    construct!(Options { version }).to_options()
+}

docs2/src/dis_fallback_with/derive.rs

@@ -0,0 +1,13 @@
+//
+use bpaf::*;
+fn try_to_get_version() -> Result<usize, &'static str> {
+    Ok(42)
+}
+
+#[derive(Debug, Clone, Bpaf)]
+#[bpaf(options)]
+pub struct Options {
+    #[bpaf(argument("VERS"), fallback_with(try_to_get_version), display_fallback)]
+    /// Specify protocol version
+    version: usize,
+}

src/docs2/deb_fallback.md

@@ -0,0 +1,113 @@
+<details><summary>Combinatoric example</summary>
+
+```no_run
+#[derive(Debug, Clone)]
+pub struct Options {
+    jobs: usize,
+}
+
+pub fn options() -> OptionParser<Options> {
+    let jobs = long("jobs")
+        .help("Number of jobs")
+        .argument("JOBS")
+        .fallback(42)
+        .debug_fallback();
+    construct!(Options { jobs }).to_options()
+}
+
+fn main() {
+    println!("{:?}", options().run())
+}
+```
+
+</details>
+<details><summary>Derive example</summary>
+
+```no_run
+#[derive(Debug, Clone, Bpaf)]
+#[bpaf(options)]
+#[allow(dead_code)]
+pub struct Options {
+    /// Number of jobs
+    #[bpaf(argument("JOBS"), fallback(42), debug_fallback)]
+    jobs: usize,
+}
+
+fn main() {
+    println!("{:?}", options().run())
+}
+```
+
+</details>
+<details><summary>Output</summary>
+
+`fallback` changes parser to fallback to a default value used when argument is not specified
+
+
+<div class='bpaf-doc'>
+$ app <br>
+Options { jobs: 42 }
+</div>
+
+
+If value is present - fallback value is ignored
+
+
+<div class='bpaf-doc'>
+$ app --jobs 10<br>
+Options { jobs: 10 }
+</div>
+
+
+Parsing errors are preserved and preserved to user
+
+
+<div class='bpaf-doc'>
+$ app --jobs ten<br>
+<b>Error:</b> couldn't parse <b>ten</b>: invalid digit found in string
+<style>
+div.bpaf-doc {
+    padding: 14px;
+    background-color:var(--code-block-background-color);
+    font-family: "Source Code Pro", monospace;
+    margin-bottom: 0.75em;
+}
+div.bpaf-doc dt { margin-left: 1em; }
+div.bpaf-doc dd { margin-left: 3em; }
+div.bpaf-doc dl { margin-top: 0; padding-left: 1em; }
+div.bpaf-doc  { padding-left: 1em; }
+</style>
+</div>
+
+
+With [`display_fallback`](ParseFallback::display_fallback) and
+[`debug_fallback`](ParseFallback::debug_fallback) you can make it so default value
+is visible in `--help` output
+
+
+<div class='bpaf-doc'>
+$ app --help<br>
+<p><b>Usage</b>: <tt><b>app</b></tt> [<tt><b>--jobs</b></tt>=<tt><i>JOBS</i></tt>]</p><p><div>
+<b>Available options:</b></div><dl><dt><tt><b>    --jobs</b></tt>=<tt><i>JOBS</i></tt></dt>
+<dd>Number of jobs</dd>
+<dt></dt>
+<dd>[default: 42]</dd>
+<dt><tt><b>-h</b></tt>, <tt><b>--help</b></tt></dt>
+<dd>Prints help information</dd>
+</dl>
+</p>
+<style>
+div.bpaf-doc {
+    padding: 14px;
+    background-color:var(--code-block-background-color);
+    font-family: "Source Code Pro", monospace;
+    margin-bottom: 0.75em;
+}
+div.bpaf-doc dt { margin-left: 1em; }
+div.bpaf-doc dd { margin-left: 3em; }
+div.bpaf-doc dl { margin-top: 0; padding-left: 1em; }
+div.bpaf-doc  { padding-left: 1em; }
+</style>
+</div>
+
+</details>