Release 0.9.25

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "bpaf"
-version = "0.9.24"
+version = "0.9.25"
 edition = "2021"
 categories = ["command-line-interface"]
 description = "A simple Command Line Argument Parser with parser combinators"

Changelog.md

@@ -1,5 +1,11 @@
 # Change Log
 
+## bpaf [0.9.25] - 2026-04-15
+- Change rendering of an adjacent block in Markdown - this is no longer a `###`
+  but a regular line item instead. Header messes up with generated navigation on
+  some pages
+- `app_name` - parser that extracts the executable name
+
 ## bpaf [0.9.24] - 2026-03-13
 - a less confusing error message when invalid user input mixes with parsers that
   can succeed with no input, see #442

docs2/src/appname/cases.md

@@ -0,0 +1,7 @@
+Parsed application name doesn't show up in the `--help` output
+
+> --help
+
+but simply produces the app name, when it is available
+
+> --user=Bob

docs2/src/appname/combine.rs

@@ -0,0 +1,18 @@
+//
+use bpaf::*;
+#[derive(Debug, Clone)]
+pub struct Options {
+    user: String,
+    appname: String,
+}
+
+pub fn options() -> OptionParser<Options> {
+    let user = short('u')
+        .long("user")
+        .help("Specify user name")
+        // you can specify exact type argument should produce
+        // for as long as it implements `FromStr`
+        .argument::<String>("NAME");
+
+    construct!(Options { user, appname() }).to_options()
+}

docs2/src/appname/derive.rs

@@ -0,0 +1,13 @@
+//
+use bpaf::*;
+#[derive(Debug, Clone, Bpaf)]
+#[bpaf(options)]
+pub struct Options {
+    /// Specify user name
+    #[bpaf(short, long, argument::<String>("NAME"))]
+    user: String,
+
+    /// Specify user age
+    #[bpaf(external)]
+    appname: String,
+}

examples/app_name.rs

@@ -0,0 +1,22 @@
+use bpaf::*;
+#[derive(Debug, Clone)]
+pub struct Options {
+    user: String,
+    appname: String,
+}
+
+pub fn options() -> OptionParser<Options> {
+    let user = short('u')
+        .long("user")
+        .help("Specify user name")
+        // you can specify exact type argument should produce
+        // for as long as it implements `FromStr`
+        .argument::<String>("NAME");
+
+    construct!(Options { user, appname() }).to_options()
+}
+
+fn main() {
+    let opts = options().run();
+    println!("{opts:?}");
+}

src/buffer.rs

@@ -275,6 +275,10 @@ pub(crate) enum Block {
     /// level 3 section header, "group_help" header, etc.
     Section3,
 
+    // 2 margin
+    /// Same as level 3, but with no `###` in markdown
+    Section4,
+
     // inline, 4 margin, no nesting
     /// -h, --help
     ItemTerm,

src/buffer/console.rs

@@ -271,7 +271,7 @@ impl Doc {
                             pending_newline = true;
                             margins.push(margin);
                         }
-                        Block::Section3 => {
+                        Block::Section3 | Block::Section4 => {
                             pending_newline = true;
                             margins.push(margin + 2);
                         }
@@ -310,6 +310,7 @@ impl Doc {
                         Block::Header
                         | Block::Section2
                         | Block::Section3
+                        | Block::Section4
                         | Block::ItemTerm
                         | Block::DefinitionList
                         | Block::Meta

src/buffer/html.rs

@@ -259,7 +259,9 @@ impl Doc {
                             res.push_str("<p>");
                         }
                         Block::Meta => todo!(),
-                        Block::Section3 => res.push_str("<div style='padding-left: 0.5em'>"),
+                        Block::Section3 | Block::Section4 => {
+                            res.push_str("<div style='padding-left: 0.5em'>")
+                        }
                         Block::Mono | Block::TermRef => {}
                         Block::InlineBlock => {
                             skip.push();
@@ -294,7 +296,7 @@ impl Doc {
                             res.push_str("</p>");
                         }
                         Block::Mono | Block::TermRef => {}
-                        Block::Section3 => res.push_str("</div>"),
+                        Block::Section3 | Block::Section4 => res.push_str("</div>"),
                         Block::Meta => todo!(),
                     }
                 }
@@ -395,7 +397,7 @@ impl Doc {
                         Block::Section2 => {
                             res.push_str("");
                         }
-                        Block::ItemTerm => {
+                        Block::ItemTerm | Block::Section4 => {
                             new_markdown_line(&mut res);
                             empty_term = matches!(
                                 self.tokens.get(ix + 1),
@@ -431,7 +433,11 @@ impl Doc {
                 Token::BlockEnd(b) => {
                     change_to_markdown_style(&mut res, &mut cur_style, Styles::default());
                     match b {
-                        Block::Header | Block::Block | Block::Section3 | Block::Section2 => {
+                        Block::Header
+                        | Block::Block
+                        | Block::Section3
+                        | Block::Section2
+                        | Block::Section4 => {
                             res.push('\n');
                         }
 

src/buffer/manpage.rs

@@ -190,7 +190,7 @@ impl Doc {
                 Token::BlockStart(block) => {
                     //
                     match block {
-                        Block::Header | Block::Section2 | Block::Section3 => {
+                        Block::Header | Block::Section2 | Block::Section3 | Block::Section4 => {
                             capture.1 = true;
                         }
                         Block::ItemTerm => {
@@ -218,7 +218,7 @@ impl Doc {
                             roff.control("SH", [capture.0.to_uppercase()]);
                             capture.0.clear();
                         }
-                        Block::Section2 | Block::Section3 => {
+                        Block::Section2 | Block::Section3 | Block::Section4 => {
                             capture.1 = false;
                             roff.control("SS", [capture.0.to_uppercase()]);
                             capture.0.clear();

src/docs2/appname.md

@@ -0,0 +1,85 @@
+<details><summary>Combinatoric example</summary>
+
+```no_run
+#[derive(Debug, Clone)]
+pub struct Options {
+    user: String,
+    appname: String,
+}
+
+pub fn options() -> OptionParser<Options> {
+    let user = short('u')
+        .long("user")
+        .help("Specify user name")
+        // you can specify exact type argument should produce
+        // for as long as it implements `FromStr`
+        .argument::<String>("NAME");
+
+    construct!(Options { user, appname() }).to_options()
+}
+
+fn main() {
+    println!("{:?}", options().run())
+}
+```
+
+</details>
+<details><summary>Derive example</summary>
+
+```no_run
+#[derive(Debug, Clone, Bpaf)]
+#[bpaf(options)]
+pub struct Options {
+    /// Specify user name
+    #[bpaf(short, long, argument::<String>("NAME"))]
+    user: String,
+
+    /// Specify user age
+    #[bpaf(external)]
+    appname: String,
+}
+
+fn main() {
+    println!("{:?}", options().run())
+}
+```
+
+</details>
+<details><summary>Output</summary>
+
+Parsed application name doesn't show up in the `--help` output
+
+
+<div class='bpaf-doc'>
+$ app --help<br>
+<p><b>Usage</b>: <tt><b>app</b></tt> <tt><b>-u</b></tt>=<tt><i>NAME</i></tt></p><p><div>
+<b>Available options:</b></div><dl><dt><tt><b>-u</b></tt>, <tt><b>--user</b></tt>=<tt><i>NAME</i></tt></dt>
+<dd>Specify user name</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>
+
+
+but simply produces the app name, when it is available
+
+
+<div class='bpaf-doc'>
+$ app --user=Bob<br>
+Options { user: "Bob", appname: "app" }
+</div>
+
+</details>

src/lib.rs

@@ -1523,3 +1523,30 @@ pub fn choice<T: 'static>(parsers: impl IntoIterator<Item = Box<dyn Parser<T>>>)
     }
     this
 }
+
+/// Parse the application name
+///
+/// If you are using [`OptionParser::run`] then it should just work. If you are using
+/// some variation of [`OptionParser::run_inner`] you'll need to set the application
+/// name using [`Args::set_name`].
+///
+#[cfg_attr(not(doctest), doc = include_str!("docs2/appname.md"))]
+pub fn appname() -> impl Parser<String> {
+    ParseAppname
+}
+
+#[derive(Debug, Copy, Clone)]
+struct ParseAppname;
+impl Parser<String> for ParseAppname {
+    fn eval(&self, args: &mut State) -> Result<String, Error> {
+        Ok(args
+            .path
+            .first()
+            .cloned()
+            .unwrap_or_else(|| String::from("app")))
+    }
+
+    fn meta(&self) -> Meta {
+        Meta::Skip
+    }
+}

src/meta_help.rs

@@ -52,11 +52,11 @@ pub(crate) enum HelpItem<'a> {
         env: Option<&'static str>,
         help: Option<&'a Doc>,
     },
-    AnywhereStart {
+    AdjacentStart {
         inner: &'a Meta,
         ty: HiTy,
     },
-    AnywhereStop {
+    AdjacentStop {
         ty: HiTy,
     },
 }
@@ -70,8 +70,8 @@ impl HelpItem<'_> {
             | HelpItem::Argument { help, .. } => help.is_some(),
             HelpItem::GroupStart { .. } | HelpItem::DecorSuffix { .. } => true,
             HelpItem::GroupEnd { .. }
-            | HelpItem::AnywhereStart { .. }
-            | HelpItem::AnywhereStop { .. } => false,
+            | HelpItem::AdjacentStart { .. }
+            | HelpItem::AdjacentStop { .. } => false,
         }
     }
 
@@ -80,8 +80,8 @@ impl HelpItem<'_> {
             HelpItem::GroupStart { ty, .. }
             | HelpItem::DecorSuffix { ty, .. }
             | HelpItem::GroupEnd { ty }
-            | HelpItem::AnywhereStart { ty, .. }
-            | HelpItem::AnywhereStop { ty } => *ty,
+            | HelpItem::AdjacentStart { ty, .. }
+            | HelpItem::AdjacentStop { ty } => *ty,
             HelpItem::Any {
                 anywhere: false, ..
             }
@@ -131,15 +131,15 @@ impl<'a, 'b> Iterator for HelpItemsIter<'a, 'b> {
             self.cur += 1;
 
             let keep = match item {
-                HelpItem::AnywhereStart { ty, .. } => {
+                HelpItem::AdjacentStart { ty, .. } => {
                     self.block = ItemBlock::Anywhere(*ty);
                     *ty == self.target
                 }
                 HelpItem::GroupStart { ty, .. } => {
                     self.block = ItemBlock::Decor(*ty);
                     *ty == self.target
                 }
-                HelpItem::GroupEnd { ty, .. } | HelpItem::AnywhereStop { ty, .. } => {
+                HelpItem::GroupEnd { ty, .. } | HelpItem::AdjacentStop { ty, .. } => {
                     self.block = ItemBlock::No;
                     *ty == self.target
                 }
@@ -206,12 +206,12 @@ impl<'a> HelpItems<'a> {
                 }
                 Meta::Adjacent(m) => {
                     if let Some(ty) = m.peek_front_ty() {
-                        hi.items.push(HelpItem::AnywhereStart {
+                        hi.items.push(HelpItem::AdjacentStart {
                             inner: m.as_ref(),
                             ty,
                         });
                         go(hi, m, no_ss);
-                        hi.items.push(HelpItem::AnywhereStop { ty });
+                        hi.items.push(HelpItem::AdjacentStop { ty });
                     }
                 }
                 Meta::CustomUsage(x, _)
@@ -488,12 +488,12 @@ fn write_help_item(buf: &mut Doc, item: &HelpItem, include_env: bool) {
                 buf.token(Token::BlockEnd(Block::ItemBody));
             }
         }
-        HelpItem::AnywhereStart { inner, .. } => {
-            buf.token(Token::BlockStart(Block::Section3));
+        HelpItem::AdjacentStart { inner, .. } => {
+            buf.token(Token::BlockStart(Block::Section4));
             buf.write_meta(inner, true);
-            buf.token(Token::BlockEnd(Block::Section3));
+            buf.token(Token::BlockEnd(Block::Section4));
         }
-        HelpItem::AnywhereStop { .. } => {
+        HelpItem::AdjacentStop { .. } => {
             buf.token(Token::BlockStart(Block::Block));
             buf.token(Token::BlockEnd(Block::Block));
         }
@@ -582,8 +582,8 @@ impl Dedup {
             HelpItem::DecorSuffix { .. } => std::mem::take(&mut self.keep),
             HelpItem::GroupStart { .. }
             | HelpItem::GroupEnd { .. }
-            | HelpItem::AnywhereStart { .. }
-            | HelpItem::AnywhereStop { .. } => {
+            | HelpItem::AdjacentStart { .. }
+            | HelpItem::AdjacentStop { .. } => {
                 self.keep = true;
                 true
             }