diff --git a/docs2/src/deb_fallback/cases.md b/docs2/src/deb_fallback/cases.md new file mode 100644 index 00000000..03cb00c6 --- /dev/null +++ b/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 diff --git a/docs2/src/deb_fallback/combine.rs b/docs2/src/deb_fallback/combine.rs new file mode 100644 index 00000000..ec34530e --- /dev/null +++ b/docs2/src/deb_fallback/combine.rs @@ -0,0 +1,15 @@ +// +use bpaf::*; +#[derive(Debug, Clone)] +pub struct Options { + jobs: usize, +} + +pub fn options() -> OptionParser { + let jobs = long("jobs") + .help("Number of jobs") + .argument("JOBS") + .fallback(42) + .debug_fallback(); + construct!(Options { jobs }).to_options() +} diff --git a/docs2/src/deb_fallback/derive.rs b/docs2/src/deb_fallback/derive.rs new file mode 100644 index 00000000..21222ca6 --- /dev/null +++ b/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, +} diff --git a/docs2/src/deb_fallback_with/cases.md b/docs2/src/deb_fallback_with/cases.md new file mode 100644 index 00000000..eb613b93 --- /dev/null +++ b/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 diff --git a/docs2/src/deb_fallback_with/combine.rs b/docs2/src/deb_fallback_with/combine.rs new file mode 100644 index 00000000..8e0af07d --- /dev/null +++ b/docs2/src/deb_fallback_with/combine.rs @@ -0,0 +1,19 @@ +// +use bpaf::*; +fn try_to_get_version() -> Result { + Ok(42) +} + +#[derive(Debug, Clone)] +pub struct Options { + version: usize, +} + +pub fn options() -> OptionParser { + let version = long("version") + .help("Specify protocol version") + .argument("VERS") + .fallback_with(try_to_get_version) + .debug_fallback(); + construct!(Options { version }).to_options() +} diff --git a/docs2/src/deb_fallback_with/derive.rs b/docs2/src/deb_fallback_with/derive.rs new file mode 100644 index 00000000..3edfac61 --- /dev/null +++ b/docs2/src/deb_fallback_with/derive.rs @@ -0,0 +1,13 @@ +// +use bpaf::*; +fn try_to_get_version() -> Result { + 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, +} diff --git a/docs2/src/dis_fallback/cases.md b/docs2/src/dis_fallback/cases.md new file mode 100644 index 00000000..03cb00c6 --- /dev/null +++ b/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 diff --git a/docs2/src/dis_fallback/combine.rs b/docs2/src/dis_fallback/combine.rs new file mode 100644 index 00000000..551a4e05 --- /dev/null +++ b/docs2/src/dis_fallback/combine.rs @@ -0,0 +1,15 @@ +// +use bpaf::*; +#[derive(Debug, Clone)] +pub struct Options { + jobs: usize, +} + +pub fn options() -> OptionParser { + let jobs = long("jobs") + .help("Number of jobs") + .argument("JOBS") + .fallback(42) + .display_fallback(); + construct!(Options { jobs }).to_options() +} diff --git a/docs2/src/dis_fallback/derive.rs b/docs2/src/dis_fallback/derive.rs new file mode 100644 index 00000000..d355aaa8 --- /dev/null +++ b/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, +} diff --git a/docs2/src/dis_fallback_with/cases.md b/docs2/src/dis_fallback_with/cases.md new file mode 100644 index 00000000..eb613b93 --- /dev/null +++ b/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 diff --git a/docs2/src/dis_fallback_with/combine.rs b/docs2/src/dis_fallback_with/combine.rs new file mode 100644 index 00000000..00ffb227 --- /dev/null +++ b/docs2/src/dis_fallback_with/combine.rs @@ -0,0 +1,19 @@ +// +use bpaf::*; +fn try_to_get_version() -> Result { + Ok(42) +} + +#[derive(Debug, Clone)] +pub struct Options { + version: usize, +} + +pub fn options() -> OptionParser { + let version = long("version") + .help("Specify protocol version") + .argument("VERS") + .fallback_with(try_to_get_version) + .display_fallback(); + construct!(Options { version }).to_options() +} diff --git a/docs2/src/dis_fallback_with/derive.rs b/docs2/src/dis_fallback_with/derive.rs new file mode 100644 index 00000000..346c6874 --- /dev/null +++ b/docs2/src/dis_fallback_with/derive.rs @@ -0,0 +1,13 @@ +// +use bpaf::*; +fn try_to_get_version() -> Result { + 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, +} diff --git a/src/docs2/deb_fallback.md b/src/docs2/deb_fallback.md new file mode 100644 index 00000000..f7abe002 --- /dev/null +++ b/src/docs2/deb_fallback.md @@ -0,0 +1,113 @@ +
Combinatoric example + +```no_run +#[derive(Debug, Clone)] +pub struct Options { + jobs: usize, +} + +pub fn options() -> OptionParser { + let jobs = long("jobs") + .help("Number of jobs") + .argument("JOBS") + .fallback(42) + .debug_fallback(); + construct!(Options { jobs }).to_options() +} + +fn main() { + println!("{:?}", options().run()) +} +``` + +
+
Derive example + +```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()) +} +``` + +
+
Output + +`fallback` changes parser to fallback to a default value used when argument is not specified + + +
+$ app
+Options { jobs: 42 } +
+ + +If value is present - fallback value is ignored + + +
+$ app --jobs 10
+Options { jobs: 10 } +
+ + +Parsing errors are preserved and preserved to user + + +
+$ app --jobs ten
+Error: couldn't parse ten: invalid digit found in string + +
+ + +With [`display_fallback`](ParseFallback::display_fallback) and +[`debug_fallback`](ParseFallback::debug_fallback) you can make it so default value +is visible in `--help` output + + +
+$ app --help
+

Usage: app [--jobs=JOBS]

+Available options:
--jobs=JOBS
+
Number of jobs
+
+
[default: 42]
+
-h, --help
+
Prints help information
+
+

+ +
+ +
\ No newline at end of file diff --git a/src/docs2/deb_fallback_with.md b/src/docs2/deb_fallback_with.md new file mode 100644 index 00000000..5788d230 --- /dev/null +++ b/src/docs2/deb_fallback_with.md @@ -0,0 +1,119 @@ +
Combinatoric example + +```no_run +fn try_to_get_version() -> Result { + Ok(42) +} + +#[derive(Debug, Clone)] +pub struct Options { + version: usize, +} + +pub fn options() -> OptionParser { + let version = long("version") + .help("Specify protocol version") + .argument("VERS") + .fallback_with(try_to_get_version) + .debug_fallback(); + construct!(Options { version }).to_options() +} + +fn main() { + println!("{:?}", options().run()) +} +``` + +
+
Derive example + +```no_run +fn try_to_get_version() -> Result { + 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, +} + +fn main() { + println!("{:?}", options().run()) +} +``` + +
+
Output + +`fallback_with` changes parser to fallback to a value that comes from a potentially failing +computation when argument is not specified + + +
+$ app
+Options { version: 42 } +
+ + +If value is present - fallback value is ignored + + +
+$ app --version 10
+Options { version: 10 } +
+ + +Parsing errors are preserved and preserved to user + + +
+$ app --version ten
+Error: couldn't parse ten: invalid digit found in string + +
+ + +`bpaf` encases parsers with fallback value of some sort in usage with `[]` + + +
+$ app --help
+

Usage: app [--version=VERS]

+Available options:
--version=VERS
+
Specify protocol version
+
+
[default: 42]
+
-h, --help
+
Prints help information
+
+

+ +
+ +
\ No newline at end of file diff --git a/src/docs2/fallback.md b/src/docs2/dis_fallback.md similarity index 100% rename from src/docs2/fallback.md rename to src/docs2/dis_fallback.md diff --git a/src/docs2/fallback_with.md b/src/docs2/dis_fallback_with.md similarity index 100% rename from src/docs2/fallback_with.md rename to src/docs2/dis_fallback_with.md diff --git a/src/lib.rs b/src/lib.rs index ce45fee7..4e83a866 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -871,7 +871,7 @@ pub trait Parser { /// /// Parser would still fail if value is present but failure comes from some transformation /// - #[cfg_attr(not(doctest), doc = include_str!("docs2/fallback.md"))] + #[cfg_attr(not(doctest), doc = include_str!("docs2/dis_fallback.md"))] /// /// # See also /// [`fallback_with`](Parser::fallback_with) would allow to try to fallback to a value that @@ -897,7 +897,7 @@ pub trait Parser { /// /// Would still fail if value is present but failure comes from some earlier transformation /// - #[cfg_attr(not(doctest), doc = include_str!("docs2/fallback_with.md"))] + #[cfg_attr(not(doctest), doc = include_str!("docs2/dis_fallback_with.md"))] /// /// # See also /// [`fallback`](Parser::fallback) implements similar logic expect that failures aren't expected. diff --git a/src/structs.rs b/src/structs.rs index 8ca99d1e..9dbc08d9 100644 --- a/src/structs.rs +++ b/src/structs.rs @@ -495,7 +495,7 @@ impl ParseFallback { /// Show [`fallback`](Parser::fallback) value in `--help` using [`Display`](std::fmt::Display) /// representation /// - #[cfg_attr(not(doctest), doc = include_str!("docs2/fallback.md"))] + #[cfg_attr(not(doctest), doc = include_str!("docs2/dis_fallback.md"))] #[must_use] pub fn display_fallback(mut self) -> Self { self.value_str = format!("[default: {}]", self.value); @@ -507,7 +507,7 @@ impl ParseFallback { /// Show [`fallback`](Parser::fallback) value in `--help` using [`Debug`](std::fmt::Debug) /// representation /// - #[cfg_attr(not(doctest), doc = include_str!("docs2/fallback_with.md"))] + #[cfg_attr(not(doctest), doc = include_str!("docs2/deb_fallback_with.md"))] #[must_use] pub fn debug_fallback(mut self) -> Self { self.value_str = format!("[default: {:?}]", self.value); @@ -524,7 +524,7 @@ where /// /// If fallback function fails - no value will show up /// - #[cfg_attr(not(doctest), doc = include_str!("docs2/fallback_with.md"))] + #[cfg_attr(not(doctest), doc = include_str!("docs2/dis_fallback_with.md"))] #[must_use] pub fn display_fallback(mut self) -> Self { if let Ok(val) = (self.fallback)() { @@ -543,7 +543,7 @@ where /// /// If fallback function fails - no value will show up /// - #[cfg_attr(not(doctest), doc = include_str!("docs2/fallback.md"))] + #[cfg_attr(not(doctest), doc = include_str!("docs2/deb_fallback.md"))] #[must_use] pub fn debug_fallback(mut self) -> Self { if let Ok(val) = (self.fallback)() {