Module bpaf::_combinatoric_tutorial
source · [−]Expand description
Using the library in combinatoric style
About examples
Examples tend to omit help
, you should try to specify them whenever possible.
Most of the examples stop at defining the Parser
, to be able to run them you need to
convert your Parser
into OptionParser
with Parser::to_options
.
fn parser() -> OptionParser<bool> {
short('s')
.switch()
.to_options() // <- important bit
}
In addition to examples in the documentation there’s a bunch more in the github repository: https://github.com/pacak/bpaf/tree/master/examples
Recommended reading order
Combinatoric and derive APIs share the documentation and most of the names, recommended reading order:
construct!
- what combinations are and how you should read the examplesNamed
,positional
andcommand
- on consuming dataParser
- on transforming the dataOptionParser
- on running the result
Getting started
-
Define primitive field parsers using builder pattern starting with
short
,long
,command
orpositional
, add more information usinghelp
,env
and other member functions.For some constructors you end up with parser objects right away, some require finalization with
argument
,flag
orswitch
.At the end of this step you’ll get one or more parser one or more objects implementing trait
Parser
, such asimpl Parser<String>
. -
If you need additional parsing and validation you can use trait
Parser
:map
,parse
,guard
,from_str
.You can change type or shape of contained or shape with
many
,some
,optional
and add a fallback values withfallback
,fallback_with
. -
You can compose resulting primitive parsers using
construct
macro into a concrete datatype and still apply additional processing from step 2 after this. -
Transform the toplevel parser created at the previous step into
OptionParser
withto_options
and attach additional metadata withdescr
and other methods available toOptionParser
. -
run
the resulting option parser at the beginning of your program. If option parser succeeds you’ll get the results. If there are errors or user asked for help infobpaf
handles this and exits.