From 14de098f5494824e1fe396c574047f516a9de717 Mon Sep 17 00:00:00 2001 From: Michael Baikov Date: Sun, 6 Aug 2023 14:00:56 -0400 Subject: [PATCH] documentation --- .../_0_simple_parser/_1_argument/index.md | 5 +-- .../_1_combinatoric_api/_1_chaining/index.md | 24 ++++++++++++++ .../_1_combinatoric_api/_2_combining/index.md | 2 +- .../_1_tutorials/_3_picking_type/index.md | 1 + src/_documentation.rs | 32 +++++++++++++++++-- 5 files changed, 58 insertions(+), 6 deletions(-) diff --git a/documentation/_documentation/_1_tutorials/_1_combinatoric_api/_0_simple_parser/_1_argument/index.md b/documentation/_documentation/_1_tutorials/_1_combinatoric_api/_0_simple_parser/_1_argument/index.md index 0453a46e..22d280b3 100644 --- a/documentation/_documentation/_1_tutorials/_1_combinatoric_api/_0_simple_parser/_1_argument/index.md +++ b/documentation/_documentation/_1_tutorials/_1_combinatoric_api/_0_simple_parser/_1_argument/index.md @@ -22,8 +22,9 @@ fn file_parser() -> OptionParser { } ``` -You can use any type for as long as it implements [`FromStr`]. See the next chapter about -parsing items that don't implement [`FromStr`] +You can use any type for as long as it implements [`FromStr`]. To parse items that don't +implement it you can first parse a `String` or `OsString` and then use [`Parser::parse`], see +[the next chapter](super::super::_1_chaining) how to do that. Full example with some sample inputs and outputs: #![cfg_attr(not(doctest), doc = include_str!("docs2/compose_basic_argument.md"))] diff --git a/documentation/_documentation/_1_tutorials/_1_combinatoric_api/_1_chaining/index.md b/documentation/_documentation/_1_tutorials/_1_combinatoric_api/_1_chaining/index.md index 6f85f368..0e1d96d1 100644 --- a/documentation/_documentation/_1_tutorials/_1_combinatoric_api/_1_chaining/index.md +++ b/documentation/_documentation/_1_tutorials/_1_combinatoric_api/_1_chaining/index.md @@ -76,3 +76,27 @@ fn even() -> impl Parser> { In later case validation function must deal with a possibility where number is absent, for this specific example it makes code less readable. + +One of the important types of transformations you can apply is a set of failing +transformations. Suppose your application operates with numbers and uses `newtype` pattern to +keep track what numbers are odd or even. Parser that consumes an even number can use +[`Parser::parse`] and look like this: + +```rust +# use bpaf::*; +pub struct Even(usize); + +fn mk_even(n: usize) -> Result { + if n % 2 == 0 { + Ok(Even(n)) + } else { + Err("Not an even number") + } +} + +fn even() -> impl Parser { + long("even") + .argument::("N") + .parse(mk_even) +} +``` diff --git a/documentation/_documentation/_1_tutorials/_1_combinatoric_api/_2_combining/index.md b/documentation/_documentation/_1_tutorials/_1_combinatoric_api/_2_combining/index.md index dc5309c9..d72bedaa 100644 --- a/documentation/_documentation/_1_tutorials/_1_combinatoric_api/_2_combining/index.md +++ b/documentation/_documentation/_1_tutorials/_1_combinatoric_api/_2_combining/index.md @@ -29,7 +29,7 @@ Full example: #![cfg_attr(not(doctest), doc = include_str!("docs2/compose_basic_construct.md"))] If you are using positional parsers - they must go to the right most side and will run in -order you specify them. For named parsers order affects only the --help` message. +order you specify them. For named parsers order affects only the `--help` message. Second type of composition `construct!` offers is a parallel composition. You pass multiple parsers that produce the same result type and `bpaf` runs one that fits best with the data user diff --git a/documentation/_documentation/_1_tutorials/_3_picking_type/index.md b/documentation/_documentation/_1_tutorials/_3_picking_type/index.md index 99c23691..df51a608 100644 --- a/documentation/_documentation/_1_tutorials/_3_picking_type/index.md +++ b/documentation/_documentation/_1_tutorials/_3_picking_type/index.md @@ -122,3 +122,4 @@ struct Options { - - - +- diff --git a/src/_documentation.rs b/src/_documentation.rs index ffedfac8..a8535082 100644 --- a/src/_documentation.rs +++ b/src/_documentation.rs @@ -786,8 +786,9 @@ //! } //! ``` //! - //! You can use any type for as long as it implements [`FromStr`]. See the next chapter about - //! parsing items that don't implement [`FromStr`] + //! You can use any type for as long as it implements [`FromStr`]. To parse items that don't + //! implement it you can first parse a `String` or `OsString` and then use [`Parser::parse`], see + //! [the next chapter](super::super::_1_chaining) how to do that. //! //! Full example with some sample inputs and outputs: #![cfg_attr(not(doctest), doc = include_str!("docs2/compose_basic_argument.md"))] @@ -964,6 +965,30 @@ //! //! In later case validation function must deal with a possibility where number is absent, for this //! specific example it makes code less readable. + //! + //! One of the important types of transformations you can apply is a set of failing + //! transformations. Suppose your application operates with numbers and uses `newtype` pattern to + //! keep track what numbers are odd or even. Parser that consumes an even number can use + //! [`Parser::parse`] and look like this: + //! + //! ```rust + //! # use bpaf::*; + //! pub struct Even(usize); + //! + //! fn mk_even(n: usize) -> Result { + //! if n % 2 == 0 { + //! Ok(Even(n)) + //! } else { + //! Err("Not an even number") + //! } + //! } + //! + //! fn even() -> impl Parser { + //! long("even") + //! .argument::("N") + //! .parse(mk_even) + //! } + //! ``` //! //! //!   @@ -1040,7 +1065,7 @@ #![cfg_attr(not(doctest), doc = include_str!("docs2/compose_basic_construct.md"))] //! //! If you are using positional parsers - they must go to the right most side and will run in - //! order you specify them. For named parsers order affects only the --help` message. + //! order you specify them. For named parsers order affects only the `--help` message. //! //! Second type of composition `construct!` offers is a parallel composition. You pass multiple //! parsers that produce the same result type and `bpaf` runs one that fits best with the data user @@ -1952,6 +1977,7 @@ //! - //! - //! - + //! - //! //! //!