-
-
Notifications
You must be signed in to change notification settings - Fork 3.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Closing issue #2312 #2942
Open
irvincardoza
wants to merge
4
commits into
catchorg:devel
Choose a base branch
from
irvincardoza:devel
base: devel
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Closing issue #2312 #2942
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
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,101 @@ | ||
# Clara v1.1.5 | ||
[![Build Status](https://travis-ci.org/catchorg/Clara.svg?branch=master)](https://travis-ci.org/catchorg/Clara) | ||
[![Build status](https://ci.appveyor.com/api/projects/status/github/catchorg/Clara?brach=master&svg=true)](https://ci.appveyor.com/project/catchorg/clara) | ||
[![codecov](https://codecov.io/gh/catchorg/Clara/branch/master/graph/badge.svg)](https://codecov.io/gh/catchorg/Clara) | ||
|
||
----------------------------- | ||
|
||
|
||
A simple to use, composable, command line parser for C++ 11 and beyond. | ||
|
||
Clara is a single-header library. | ||
|
||
To use, just `#include "clara.hpp"` | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. No longer true for the embedded version |
||
|
||
A parser for a single option can be created like this: | ||
|
||
```c++ | ||
int width = 0; | ||
// ... | ||
using namespace clara; | ||
auto cli | ||
= Opt( width, "width" ) | ||
["-w"]["--width"] | ||
("How wide should it be?"); | ||
``` | ||
|
||
You can use this parser directly like this: | ||
|
||
```c++ | ||
auto result = cli.parse( Args( argc, argv ) ); | ||
if( !result ) { | ||
std::cerr << "Error in command line: " << result.errorMessage() << 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: | ||
|
||
```c++ | ||
int width = 0; | ||
std::string name; | ||
bool doIt = false; | ||
std::string command; | ||
auto cli | ||
= Opt( width, "width" ) | ||
["-w"]["--width"] | ||
("How wide should it be?") | ||
| Opt( name, "name" ) | ||
["-n"]["--name"] | ||
("By what name should I be known") | ||
| Opt( doIt ) | ||
["-d"]["--doit"] | ||
("Do the thing" ) | ||
| Arg( command, "command" ) | ||
("which command to run"); | ||
``` | ||
|
||
`Opt`s specify options that start with a short dash (`-`) or long dash (`--`). | ||
On Windows forward slashes are also accepted (and automatically interpretted as a short 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`s specify arguments that are not tied to options, and so have no square bracket names. They otherwise work just like `Opt`s. | ||
|
||
A, console optimised, usage string can be obtained by inserting the parser into a stream. | ||
The usage string is built from the information supplied and is formatted for the console width. | ||
|
||
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. | ||
|
||
For more usage please see the unit tests or look at how it is used in the Catch code-base (catch-lib.net). | ||
Fuller documentation will be coming soon. | ||
|
||
Some of the key features: | ||
|
||
- A single header file with no external dependencies (except the std library). | ||
- Define your interface once to get parsing, type conversions and usage strings with no redundancy. | ||
- Composable. 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 behaviour. | ||
|
||
|
||
## Old version | ||
|
||
If you used the earlier, v0.x, version of Clara please note that this is a complete rewrite which assumes C++11 and has | ||
a different interface (composability was a big step forward). Conversion between v0.x and v1.x is a fairly simple and mechanical task, but is a bit of manual | ||
work - so don't take this version until you're ready (and, of course, able to use C++11). | ||
|
||
I hope you'll find the new interface an improvement - and this will be built on to offer new features moving forwards. | ||
I don't expect to maintain v0.x any further, but it remains on a branch. |
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 |
---|---|---|
|
@@ -110,7 +110,7 @@ int main( int argc, char* argv[] ) { | |
} | ||
``` | ||
|
||
See the [Clara documentation](https://github.com/catchorg/Clara/blob/master/README.md) | ||
See the [Clara documentation](https://github.com/irvincardoza/Catch2/blob/devel/docs/Clara.md) | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This link is reliant on your fork. Instead, it should be using relative reference to the new file. |
||
for more details on how to use the Clara parser. | ||
|
||
|
||
|
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
These are all irrelevant to the version embedded into the repo, as it is not built or tested separately.