Rc 0.6.0

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "bpaf"
-version = "0.5.7"
+version = "0.6.0"
 edition = "2021"
 categories = ["command-line-interface"]
 description = "A simple Command Line Argument Parser with parser combinators"
@@ -14,7 +14,7 @@ exclude = [".github/workflows", "tarp.sh"]
 
 
 [dependencies]
-bpaf_derive = { path = "./bpaf_derive", version = "0.2.2", optional = true }
+bpaf_derive = { path = "./bpaf_derive", version = "=0.3.0", optional = true }
 
 [dev-dependencies]
 bpaf = { path = ".",  features = ["derive", "extradocs", "autocomplete"] }

Changelog.md

@@ -1,26 +1,39 @@
 # Change Log
 ## bpaf [0.6.0] - unreleased
-- removed `positional_os()` and `argument_os()`
-- removed `from_str`
-- internal refactors
-- documentation refactor: examples with input/output
-- `any` - a positional way to capture anything
-- `adjacent` restriction
-- `catch` inside `ParseOption`, `ParseMany` and `ParseSome`
-- usage line refactor, cosmetic mostly
-- include \n in --version, cosmetic
-
-Migration guide:
-1. replace `positional_os("FOO")` with `positional::<Type>("FOO")` or use `positional` in derive API
-2. replace `argument_os("FOO")` with `argument::<Type>("FOO")` or use `argument` in derive API
-3. replace any uses of `from_str::<T>` with turbofish on the nearest `positional` or
-   `argument`. You can use `map` to apply `FromStr` parser if `String` gets created inside your parsers
-
-You shouldn't be using those names directly, but there are some structure renames:
-1. `Positional` -> `ParsePositional`
-2. `BuildArgument` -> ParseArgument`
-3. `Command` -> `ParseCommand`
-
+# What's new in 0.6.0
+- `adjacent` restriction to parse things in a tighter context
+- `catch` for `many`, `some` and `optional` to handle parse errors
+- `any` positional like, to consume pretty much anything from a command line
+- improved documentation with more detailed examples
+- cosmetic improvements
+- a sneaky reminder to use `to_options` on `Parser` before trying to run it
+- a way to make boxed parsers with single item `construct!` macro for making dynamic parsers
+- a horrible way to reduce Yoda-talk coding by placing primitive definitions inside the `construct!` macro
+
+With new additions you should be able to parse pretty much anything and then some more :)
+
+# Migration guide 0.5.x -> 0.6.x
+
+1. Replace any uses of `positional_os` and `argument_os` with `positional` and `argument` plus turbofish:
+    ```diff
+    -let file = positional_os("FILE").help("File to use").map(PathBuf::from);
+    +let file = positional::<PathBuf>("FILE").help("File to use");
+    ```
+2. Replace any uses of `from_str` with either turbofish on the consumer or with `parse`, if `String` is generated inside the parser:
+    ```diff
+    -let number = short('n').argument("N").from_str::<usize>();
+    +let number = short('n').argument::<usize>("N");
+    ```
+    You can still use it for your own types if you implement `FromOsStr`, alternatively `parse` still works:
+    ```diff
+    -let my = long("my-type").argument("MAGIC").from_str::<MyType>();
+    +let my = long("my-type").argument::<String>("MAGIC").parse(|s| MyType::from_str(s));
+    ```
+3. You shouldn't be using those names directly in your code, but there are some renames
+    - `Positional` -> `ParsePositional`
+    - `BuildArgument` -> `ParseArgument`
+    - `Command` -> `ParseCommand`
+    - `Named` -> `NamedArg`
 
 ## bpaf [0.5.7] - 2022-09-04
 - bugfix with zsh autocomplete #46

bpaf_cauwugo/Cargo.toml

@@ -6,7 +6,7 @@ edition = "2021"
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
-bpaf = { version = "0.5.5", path = "../", features = ["derive", "autocomplete"] }
+bpaf = { version = "0.6.0", path = "../", features = ["derive", "autocomplete"] }
 cargo_metadata = "0.15.0"
 once_cell = "1.13.1"
 

bpaf_derive/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "bpaf_derive"
-version = "0.2.2"
+version = "0.3.0"
 edition = "2021"
 categories = ["command-line-interface"]
 description = "Derive macros for bpaf Command Line Argument Parser"

docs/src/cargo_helper/cases.txt

@@ -0,0 +1,25 @@
+? Let's say the goal is to parse an argument and a switch:
+> --argument 15
+OK
+Options { argument: 15, switch: false }
+
+? But when used as a `cargo` subcommand, cargo will also pass the command name, this example
+? uses _wrong_ subcommand name to bypass the helper and show how it would look without it
+> wrong --argument 15
+Stderr
+No such command: `wrong`, did you mean `-s`?
+
+? When used with the right command - helper simply consumes it
+> pretty --argument 42 -s
+OK
+Options { argument: 42, switch: true }
+
+? And it doesn't show up in `--help` so not to confuse users
+> --help
+Stdout
+Usage: --argument ARG [-s]
+
+Available options:
+        --argument <ARG>  An argument
+    -s                    A switch
+    -h, --help            Prints help information

docs/src/cargo_helper/combine.rs

@@ -0,0 +1,19 @@
+//
+use bpaf::*;
+//
+#[allow(dead_code)]
+#[derive(Debug, Clone)]
+pub struct Options {
+    argument: usize,
+    switch: bool,
+}
+
+pub fn options() -> OptionParser<Options> {
+    let argument = long("argument")
+        .help("An argument")
+        .argument::<usize>("ARG");
+    let switch = short('s').help("A switch").switch();
+    let options = construct!(Options { argument, switch });
+
+    cargo_helper("pretty", options).to_options()
+}

docs/src/cargo_helper/derive.rs

@@ -0,0 +1,13 @@
+//
+use bpaf::*;
+//
+#[allow(dead_code)]
+#[derive(Debug, Clone, Bpaf)]
+#[bpaf(options("pretty"))]
+pub struct Options {
+    /// An argument
+    argument: usize,
+    /// A switch
+    #[bpaf(short)]
+    switch: bool,
+}

examples/basic.rs

@@ -16,10 +16,11 @@ struct Out {
 
 fn main() {
     // A flag, true if used in the command line. Can be required, this one is optional
-    let debug = short('d')
-        .long("debug")
-        .help("Activate debug mode")
-        .switch();
+
+    let debug = short('d') // start with a short name
+        .long("debug") // also add a long name
+        .help("Activate debug mode") // and a help message to use
+        .switch(); // turn this into a switch
 
     // number of occurrences of the v/verbose flag capped at 3 with an error here but you can also
     // use `max` inside `map`
@@ -35,22 +36,23 @@ fn main() {
     let speed = short('s')
         .long("speed")
         .help("Set speed")
-        .argument("SPEED")
+        .argument::<f64>("SPEED") // you can specify a type to parse
         .fallback(42.0);
 
     let output = short('o')
         .long("output")
         .help("output file")
-        .argument::<PathBuf>("OUTPUT");
+        .argument("OUTPUT"); // but it's optional when rustc can derive it
 
-    // no magical name transmogrifications in combinatoric API
+    // no magical name transmogrifications in combinatoric API,
     let nb_cars = short('n').long("nb-cars").argument("N");
 
     // a parser that consumes one argument
+    // you can build the inner parser in one go or as multiple steps giving each step a name
     let file_to_proces = short('f')
         .long("file")
         .help("File to process")
-        .argument::<PathBuf>("FILE");
+        .argument("FILE");
     let files_to_process = file_to_proces.many();
 
     // packing things in a struct assumes parser for each field is in scope.
@@ -63,6 +65,7 @@ fn main() {
         files_to_process
     })
     .to_options()
+    .descr("This is a description")
     .run();
 
     println!("{:#?}", opt);

examples/cat.rs

@@ -1,5 +1,9 @@
 //! You can open files as part of parsing process too, might not be the best idea though
-//! because depending on a context `bpaf` might need to evaluate some parsers multiple times
+//! because depending on a context `bpaf` might need to evaluate some parsers multiple times.
+//!
+//! Main motivation for this example is that you can open a file as part of the argument parsing
+//! and give a reader directly to user. In practice to replicate `cat`'s behavior you'd accept
+//! multiple files with `many` and open them one by one in your code.
 
 use bpaf::*;
 use std::{
@@ -10,19 +14,26 @@ use std::{
 
 fn main() {
     let file = positional::<OsString>("FILE")
+        .help("File name to concatenate, with no FILE or when FILE is -, read standard input")
+        .optional()
         .parse::<_, Box<dyn Read>, std::io::Error>(|path| {
-            Ok(if path == "-" {
-                Box::new(stdin())
+            Ok(if let Some(path) = path {
+                if path == "-" {
+                    Box::new(stdin())
+                } else {
+                    Box::new(File::open(path)?)
+                }
             } else {
-                Box::new(File::open(path)?)
+                Box::new(stdin())
             })
         })
         .to_options()
+        .descr("Concatenate a file to standard output")
         .run();
 
     let reader = BufReader::new(file);
 
     for line in reader.lines() {
-        println!("{:?}", line.unwrap());
+        println!("{}", line.unwrap());
     }
 }

examples/after_help.rs → examples/customize_help.rs

@@ -1,17 +1,17 @@
-//! How to append a prefix or suffix to the help message generated.
+//! `--help` output customizations
 //!
-//! You can also override usage line if you don't like the generated one
+//! help header, help footer, a short description and a custom usage line
 use bpaf::*;
 
 fn main() {
     let opt = short('d')
         .help("Release the dragon")
         .switch()
         .to_options()
-        // help metadata
         .descr("I am a program and I do things")
         .header("Sometimes they even work.")
         .footer("Beware `-d`, dragons be here")
+        .usage("You can call it with following flags: {usage}")
         .run();
 
     println!("{:?}", opt);