bfgroup/Lyra - Githubissues

= Lyra

// tag::intro[]

[.tagline] A simple to use, composing, header only, command line arguments parser for C++ 11 and beyond.

// end::intro[]

== License

// tag::license[]

Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

// end::license[]

== Features

// tag::features[]

Header only with no external dependencies (except the std library).
Define your interface once to get parsing, type conversions and usage strings with no redundancy.
Composing. Each opt or arg is an independent parser. Combine these to produce a composite parser -- this can be done in stages across multiple function calls -- or even projects.
Bind parsers directly to variables that will receive the results of the parse -- no intermediate dictionaries to worry about.
Or can also bind parsers to lambdas for more custom handling.
Deduces types from bound variables or lambdas and performs type conversions (via ostream <<), with error handling, behind the scenes.
Bind parsers to vectors for args that can have multiple values.
Uses result types for error propagation, rather than exceptions (doesn't yet build with exceptions disabled, but that will be coming later)
Models POSIX standards for short and long opt behavior.
Customizable option syntax.
Specify cardinality of arg-s from one to many.
Limit option values to a specified set of values.
Recursive argument groups with callback for detection. This allows for easy and generic sub-command specifications.

// end::features[]

== Using

// tag::using[]

To use, just #include <lyra/lyra.hpp>

A parser for a single option can be created like this:

[source,cpp]

int width = 0; auto cli = lyra::cli() | lyra::opt( width, "width" ) ["-w"]["--width"] ("How wide should it be?");

You can use this parser directly like this:

[source,cpp]

auto result = cli.parse( { argc, argv } ); if ( !result ) { std::cerr << "Error in command line: " << result.message() << std::endl; exit(1); }

// Everything was ok, width will have a value if supplied on command line.

Note that exceptions are not used for error handling.

You can combine parsers by composing with |, like this:

[source,cpp]

int width = 0; std::string name; bool doIt = false; std::string command; auto cli = lyra::opt( width, "width" ) ["-w"]["--width"] ("How wide should it be?") | lyra::opt( name, "name" ) ["-n"]["--name"] ("By what name should I be known") | lyra::opt( doIt ) ["-d"]["--doit"] ("Do the thing" ) | lyra::arg( command, "command" ) ("which command to run");

opt specifies options that start with a short dash (-) or long dash (--). Options can be argument taking (such as -w 42), in which case the opt takes a second argument -- a hint, or they are pure flags (such as -d), in which case the opt has only one argument -- which must be a boolean. The option names are provided in one or more sets of square brackets, and a description string can be provided in parentheses. The first argument to an opt is any variable, local, global member, of any type that can be converted from a string using std::ostream.

arg specifies arguments that are not tied to options, and so have no square bracket names. They otherwise work just like opt.

A usage string can be obtained by inserting the parser into a stream. The usage string is built from the information supplied.

As a convenience, the standard help options (-h, --help and -?) can be specified using the help parser, which just takes a boolean to bind to.

// end::using[]

== More

There is a single-header version that is generated from the source files. You can find it at data/single_include/lyra/lyra.hpp. Some caveats for it:

It's not the preferred method of using the library.
It's not thoroughly tested.
It's intended for use cases like Compiler Explorer. Where it allows for immediate experimentation.
Support for it will not be a priority.
Hence prefer to use the regular multi-file sources in your projects.

For more information and documentation see the link:https://bfgroup.github.io/Lyra/[web site].

bfgroup / Lyra

readme

[source,cpp]

int width = 0; auto cli = lyra::cli() | lyra::opt( width, "width" ) ["-w"]["--width"] ("How wide should it be?");

[source,cpp]

// Everything was ok, width will have a value if supplied on command line.

[source,cpp]