% The Deepsea command-line parser % Deepsea Project % 23 January 2016
This library provides a collection of basic utilities for parsing string data that is read from the comand line.
The documentation is most easily read in html or pdf format. To render
in these formats, you will need the pandoc
tool. When you have pandoc installed, you can render html and pdf
versions simply by running make README.html5
or make README.pdf
.
The conventions assumed by this library are quite simple. Each command line is formed by a sequence of key/value pairs, given in the following format.
-key1 value1 -key2 value2 ... -keyn valuen
Because simple switches are convenient, the format provides for one additional form.
--key
The form above is equivalent to the following command-line string.
-key 1
The C++ library consists of a single header file that is written using
modern C++ features. We have tested the library on GCC and Clang. In
order to use the header file, the compiler must be configured to use
C++11 standard (e.g., by passing to the compiler the flag
-std=c++11
). To use the library in your project, you can simply
include the header file cmdline.hpp
.
The library can be used only after the following function is called. Any call to other functions in the cmdline library that occur prior to correct initialization will fail, terminating the program.
namespace deepsea {
namespace cmdline {
void set(int argc, char** argv);
} }
The following code snippet shows a correct initialization of the cmdline library.
#include "cmdline.hpp"
int main(int argc, char** argv) {
deepsea::cmdline::set(argc, argv);
// can use cmdline here, post initialization
return 0;
}
// (1)
template <class Item>
Item parse(std::string key);
// (2)
template <class Item>
Item parse_or_default(std::string key, Item d,
bool expected=true);
Let the string -k1 v1 -k2 v2 ...
represent the command-line string
of the program.
- The call
parse(key)
tries to read from the command line the value that is associated with a given key. The function either a. returns a value that is the result of parsing the stringvi
to a value of typeItem
, ifki == key
, or b. terminates the program, printing an error message tostderr
, otherwise. - The call
parse_or_default(key, d, expected)
is similar to the one above, but instead of failing when the requested key does not appear, the call instead returns the valued
. Ifexpected == true
, then a warning message is printed tostderr
to indicate that the default value was taken for the key.
In both cases, the first occurrence of the key matching the string
key
is the one that is parsed by the function.
Currently, the template parameter Item
can be instantiated for any
one of the following types: bool
, int
, long
, float
, double
,
and std::string
.
Contents of the file myparse.cpp
.
#include "cmdline.hpp"
#include <iostream>
int main(int argc, char** argv) {
deepsea::cmdline::set(argc, argv);
int x = deepsea::cmdline::parse<int>("x");
int y = deepsea::cmdline::parse_or_default("y", 123);
std::cout << "x = " << x << ", y = " << y << std::endl;
return 0;
}
Sample use:
$ g++ -std=c++11 myparse.cpp -o myparse
...
$ myparse -x 500
x = 500, y = 123
$ myparse -x 45 -y 9999
x = 45, y = 9999
namespace deepsea {
namespace cmdline {
class dispatcher;
} }
A disptacher is an object that stores a set of label/function pairs and provides a method to select and execute a function whose corresponding label matches with a certain string value in the command-line string.
+-----------------------------------------------+------------------------------------+
| Method | Description |
+===============================================+====================================+
| add
| Add a function to the dispatcher |
| | |
+-----------------------------------------------+------------------------------------+
| dispatch
| Dispatch on the command line |
| | |
+-----------------------------------------------+------------------------------------+
| dispatch_or_default
| Dispatch on the command line, using|
| |a default label |
+-----------------------------------------------+------------------------------------+
Table: Methods of the class disptacher
.
void add(std::string label, std::function<void()> f);
Adds the pair label
/ f
to the set.
// (1)
void dispatch(std::string key);
// (2)
void dispatch_or_default(std::string key, std::string d);
Let the string -k1 v1 -k2 v2 ...
represent the command-line string
of the program.
Let the set of the dispatcher be (l1
, f1
), (l2
, f2
), ...
- The call
dispatch(key)
performs one of the following actions: a. calls functionfj
, ifkey == ki
for some stringki
in the command-line string andki == lj
for some labellj
in the set of the dispatcher. b. halts the program and prints an error message tostderr
, otherwise. - The call
dispatch_or_default(key, d)
calls the functionfj
, such thatlj == d
, or halts the program and prints an error message if there is no suchlj
.
Contents of the file mydispatcher.cpp
:
#include "cmdline.hpp"
#include <iostream>
int main(int argc, char** argv) {
deepsea::cmdline::set(argc, argv);
deepsea::cmdline::dispatcher d;
d.add("foo", [&] {
std::cout << "Got foo" << std::endl;
});
d.add("bar", [&] {
std::cout << "Got bar" << std::endl;
});
d.dispatch_or_default("mykey", "foo");
return 0;
}
Sample use:
$ g++ -std=c++11 mydispatcher.cpp -o mydispatcher
...
$ mydispatcher -mykey foo
Got foo
$ mydispatcher -mykey bar
Got bar
$ mydispatcher
Got foo