-
Notifications
You must be signed in to change notification settings - Fork 17
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
0 parents
commit a8619db
Showing
245 changed files
with
50,534 additions
and
0 deletions.
There are no files selected for viewing
Empty file.
Empty file.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,143 @@ | ||
| <!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content=" "><title>bpaf::_documentation::_0_intro - Rust</title><script>if(window.location.protocol!=="file:")document.head.insertAdjacentHTML("beforeend","SourceSerif4-Regular-46f98efaafac5295.ttf.woff2,FiraSans-Regular-018c141bf0843ffd.woff2,FiraSans-Medium-8f9a781e4970d388.woff2,SourceCodePro-Regular-562dcc5011b6de7d.ttf.woff2,SourceCodePro-Semibold-d899c5a5c4aeb14a.ttf.woff2".split(",").map(f=>`<link rel="preload" as="font" type="font/woff2" crossorigin href="../../../static.files/${f}">`).join(""))</script><link rel="stylesheet" href="../../../static.files/normalize-76eba96aa4d2e634.css"><link rel="stylesheet" href="../../../static.files/rustdoc-c5d6553a23f1e5a6.css"><meta name="rustdoc-vars" data-root-path="../../../" data-static-root-path="../../../static.files/" data-current-crate="bpaf" data-themes="" data-resource-suffix="" data-rustdoc-version="1.81.0 (eeb90cda1 2024-09-04)" data-channel="1.81.0" data-search-js="search-d234aafac6c221dd.js" data-settings-js="settings-4313503d2e1961c2.js" ><script src="../../../static.files/storage-118b08c4c78b968e.js"></script><script defer src="../sidebar-items.js"></script><script defer src="../../../static.files/main-d2fab2bf619172d3.js"></script><noscript><link rel="stylesheet" href="../../../static.files/noscript-df360f571f6edeae.css"></noscript><link rel="alternate icon" type="image/png" href="../../../static.files/favicon-32x32-422f7d1d52889060.png"><link rel="icon" type="image/svg+xml" href="../../../static.files/favicon-2c020d218678b618.svg"></head><body class="rustdoc mod"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="mobile-topbar"><button class="sidebar-menu-toggle" title="show sidebar"></button></nav><nav class="sidebar"><div class="sidebar-crate"><h2><a href="../../../bpaf/index.html">bpaf</a><span class="version">0.9.13</span></h2></div><h2 class="location"><a href="#">Module _0_intro</a></h2><div class="sidebar-elems"><h2><a href="../index.html">In bpaf::_documentation</a></h2></div></nav><div class="sidebar-resizer"></div><main><div class="width-limiter"><rustdoc-search></rustdoc-search><section id="main-content" class="content"><div class="main-heading"><h1>Module <a href="../../index.html">bpaf</a>::<wbr><a href="../index.html">_documentation</a>::<wbr><a class="mod" href="#">_0_intro</a><button id="copy-path" title="Copy item path to clipboard">Copy item path</button></h1><span class="out-of-band"><a class="src" href="../../../src/bpaf/_documentation.rs.html#11">source</a> · <button id="toggle-all-docs" title="collapse all docs">[<span>−</span>]</button></span></div><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p> </p> | ||
| <table width='100%' cellspacing='0' style='border: hidden;'><tr> | ||
| <td style='width: 33%; text-align: left;'> | ||
| </td> | ||
| <td style='width: 34%; text-align: center;'> | ||
| <p><a href="../index.html" title="mod bpaf::_documentation">↑ Project documentation ↑</a></p> | ||
| </td> | ||
| <td style='width: 33%; text-align: right;'> | ||
| <p><a href="../_1_tutorials/index.html" title="mod bpaf::_documentation::_1_tutorials">Tutorials →</a></p> | ||
| </td> | ||
| </tr></table> | ||
| <h5 id="introduction-and-design-goals"><a class="doc-anchor" href="#introduction-and-design-goals">§</a>Introduction and design goals</h5> | ||
| <p>A quick intro. What, why and how</p> | ||
| <p><code>bpaf</code> is a lightweight and flexible command line parser that uses both combinatoric and derive | ||
| style API</p> | ||
| <p>Combinatoric API usually means a bit more typing but no dependency on proc macros and more help | ||
| from the IDE, derive API uses proc macro to save on typing but your IDE will be less likely to | ||
| help you. Picking one API style does not lock you out from using the other style, you can mix | ||
| and match both in a single parser</p> | ||
| <h2 id="examples-of-both-styles"><a class="doc-anchor" href="#examples-of-both-styles">§</a>Examples of both styles</h2><details><summary>Combinatoric example</summary> | ||
|
|
||
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>bpaf::<span class="kw-2">*</span>; | ||
|
|
||
| <span class="attr">#[derive(Debug, Clone)] | ||
| </span><span class="kw">pub struct </span>Options { | ||
| message: String, | ||
| } | ||
|
|
||
| <span class="kw">pub fn </span>options() -> OptionParser<Options> { | ||
| <span class="kw">let </span>message = positional(<span class="string">"MESSAGE"</span>).help(<span class="string">"Message to print in a big friendly letters"</span>); | ||
| <span class="macro">construct!</span>(Options { message }).to_options() | ||
| } | ||
|
|
||
| <span class="kw">fn </span>main() { | ||
| <span class="macro">println!</span>(<span class="string">"{:?}"</span>, options().run()) | ||
| }</code></pre></div> | ||
| </details> | ||
| <details><summary>Derive example</summary> | ||
|
|
||
| <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>bpaf::<span class="kw-2">*</span>; | ||
|
|
||
| <span class="attr">#[derive(Debug, Clone, Bpaf)] | ||
| #[bpaf(options)] | ||
| </span><span class="kw">pub struct </span>Options { | ||
| <span class="doccomment">/// Message to print in a big friendly letters | ||
| </span><span class="attr">#[bpaf(positional(<span class="string">"MESSAGE"</span>))] | ||
| </span>message: String, | ||
| } | ||
|
|
||
| <span class="kw">fn </span>main() { | ||
| <span class="macro">println!</span>(<span class="string">"{:?}"</span>, options().run()) | ||
| }</code></pre></div> | ||
| </details> | ||
| <details><summary>Output</summary> | ||
| <p>With everything in place users should be able to pass their arguments</p> | ||
| <div class='bpaf-doc'> | ||
| $ app "Hello world"<br> | ||
| Options { message: "Hello world" } | ||
| </div> | ||
| <p>As well as read the help message generated by the library</p> | ||
| <div class='bpaf-doc'> | ||
| $ app --help<br> | ||
| <p><b>Usage</b>: <tt><b>app</b></tt> <tt><i>MESSAGE</i></tt></p><p><div> | ||
| <b>Available positional items:</b></div><dl><dt><tt><i>MESSAGE</i></tt></dt> | ||
| <dd>Message to print in a big friendly letters</dd> | ||
| </dl> | ||
| </p><p><div> | ||
| <b>Available options:</b></div><dl><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> | ||
| <h2 id="design-goals"><a class="doc-anchor" href="#design-goals">§</a>Design goals</h2><h3 id="parse-dont-validate"><a class="doc-anchor" href="#parse-dont-validate">§</a>Parse, don’t validate</h3> | ||
| <p><code>bpaf</code> tries hard to let you move as many invariants about the user input you are | ||
| trying to parse into rust types: for mutually exclusive options you can get <code>enum</code> with | ||
| exclusive items going into separate branches, and you can collect results into types like | ||
| <a href="https://doc.rust-lang.org/1.81.0/alloc/collections/btree/set/struct.BTreeSet.html" title="struct alloc::collections::btree::set::BTreeSet"><code>BTreeSet</code></a>, or whatever custom type you might have with | ||
| custom parsing. Ideas for | ||
| <a href="https://geeklaunch.io/blog/make-invalid-states-unrepresentable/">making invalid states unrepresentable</a> | ||
| and <a href="https://lexi-lambda.github.io/blog/2019/11/05/parse-don-t-validate/">using parsing over validation</a> | ||
| are not new.</p> | ||
| <p>That said you can also validate your inputs if this fits your situation better. If you want to | ||
| ensure that the sum of every numeric field must be divisible by both 3 and 5, but only when it’s | ||
| Thursday - you can do that too.</p> | ||
| <h3 id="flexibility"><a class="doc-anchor" href="#flexibility">§</a>Flexibility</h3> | ||
| <p>While aiming to be a general-purpose command line parser <code>bpaf</code> offers a few backdoors that | ||
| allow you to parse pretty much anything you want: chained commands, custom blocks of options, | ||
| DOS-style options (<code>/ofile.pas</code>), <code>dd</code> style options (<code>if=file of=out</code>), etc. A similar idea applies | ||
| to what the parser can produce - if your app operates with boxed string slices internally - <code>bpaf</code> | ||
| will give you <code>Box<str></code> instead of <code>String</code> if you ask it to.</p> | ||
| <p>The only restriction is that you cannot use information from items parsed earlier (but not | ||
| the fact that something was parsed successfully or not) to decide to how to parse further | ||
| options, and even then you can side step this restriction by passing some shared state as a | ||
| parameter to the parsers.</p> | ||
| <h3 id="reusability"><a class="doc-anchor" href="#reusability">§</a>Reusability</h3> | ||
| <p>Parsers in <code>bpaf</code> are not monolithic and you can share their parts across multiple binaries, | ||
| workspace members or even independent projects. Say you have multiple binaries in a workspace | ||
| that perform different operations on some input. You can declare a parser for the input | ||
| specifically, along with all the validations, help messages or shell dynamic completion | ||
| functions you need and use it across all the binaries alongside the arguments specific to | ||
| those binaries.</p> | ||
| <h3 id="composition-transformation"><a class="doc-anchor" href="#composition-transformation">§</a>Composition, transformation</h3> | ||
| <p>Parsers in <code>bpaf</code> are not finalized either, say you have a parser that describes a single input | ||
| for your program, it can take multiple arguments or perform extra validations, etc. You can | ||
| always compose this parser with any other parser to produce tuples of both results for example. | ||
| Or to make it so parser runs multiple times and collects results into a <code>Vec</code>.</p> | ||
| <h3 id="performance"><a class="doc-anchor" href="#performance">§</a>Performance</h3> | ||
| <p>While performance is an explicit non-goal - <code>bpaf</code> does nothing that would pessimize it either, | ||
| so performance is on par or better compared to other fully featured parsers.</p> | ||
| <h3 id="correctness"><a class="doc-anchor" href="#correctness">§</a>Correctness</h3> | ||
| <p><code>bpaf</code> would parse only items it can represent and will reject anything it cannot represent | ||
| in the output. Say your parser accepts both <code>--intel</code> and <code>--att</code> flags, but encodes the result | ||
| into <code>enum Style { Intel, Att }</code>, <code>bpaf</code> will accept those flags separately, but not if they | ||
| are used both at once. If the parser later collects multiple styles into a <code>Vec<Style></code> then it | ||
| will accept any combinationof those flags.</p> | ||
| <h3 id="user-friendly"><a class="doc-anchor" href="#user-friendly">§</a>User friendly</h3> | ||
| <p><code>bpaf</code> tries to provide user-friendly error messages, and suggestions for typos but also scripts | ||
| for shell completion, <code>man</code> pages and markdown documentation for the web.</p> | ||
| <p> </p> | ||
| <table width='100%' cellspacing='0' style='border: hidden;'><tr> | ||
| <td style='width: 33%; text-align: left;'> | ||
| </td> | ||
| <td style='width: 34%; text-align: center;'> | ||
| <p><a href="../index.html" title="mod bpaf::_documentation">↑ Project documentation ↑</a></p> | ||
| </td> | ||
| <td style='width: 33%; text-align: right;'> | ||
| <p><a href="../_1_tutorials/index.html" title="mod bpaf::_documentation::_1_tutorials">Tutorials →</a></p> | ||
| </td> | ||
| </tr></table> | ||
| </div></details></section></div></main></body></html> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| window.SIDEBAR_ITEMS = {}; |
Oops, something went wrong.