Outputs a nicely formatted usage string with support for multi-column formatting and line-wrapping.
printUsage() takes the help texts of a Descriptor[] array and formats them into a usage message, wrapping lines to achieve the desired output width.
Table formatting:
Aside from plain strings which are simply line-wrapped, the usage may contain tables. Tables are used to align elements in the output.
-
c, --create |Creates something.
-k, --kill |Destroys something.
-
c, --create |Creates something.
-k, --kill |Destroys something.
Table formatting removes the need to pad help texts manually with spaces to achieve alignment. To create a table, simply insert \t (tab) characters to separate the cells within a row.
{..., "-c, --create \tCreates something." },
{..., "-k, --kill \tDestroys something." }, ...
Note that you must include the minimum amount of space desired between cells yourself. Table formatting will insert further spaces as needed to achieve alignment.
You can insert line breaks within cells by using \v (vertical tab).
{..., "-c,\v--create \tCreates\vsomething." },
{..., "-k,\v--kill \tDestroys\vsomething." }, ...
--create something.
-k, Destroys
--kill something.
You can mix lines that do not use \t or \v with those that do. The plain lines will not mess up the table layout. Alignment of the table columns will be maintained even across these interjections.
{..., "-c, --create \tCreates something." },
{..., "----------------------------------" },
{..., "-k, --kill \tDestroys something." }, ...
-
c, --create Creates something.
----------------------------------
-k, --kill Destroys something.
You can have multiple tables within the same usage whose columns are aligned independently. Simply insert a dummy Descriptor with help==0.
{..., "Long options:" },
{..., "--very-long-option \tDoes something long." },
{..., "--ultra-super-mega-long-option \tTakes forever to complete." },
{..., 0 },
{..., "Short options:" },
{..., "-s \tShort." },
{..., "-q \tQuick." }, ...
Long options:
--very-long-option Does something long.
--ultra-super-mega-long-option Takes forever to complete.
Short options:
Long options:
--very-long-option Does something long.
--ultra-super-mega-long-option Takes forever to complete.
Short options:
static constexpr double s
Output methods:
Because TheLeanMeanC++Option parser is freestanding, you have to provide the means for output in the first argument(s) to printUsage(). Because printUsage() is implemented as a set of template functions, you have great flexibility in your choice of output method. The following example demonstrates typical uses. Anything that's similar enough will work.
#include <unistd.h>
#include <iostream>
#include <sstream>
#include <cstdio>
using namespace std;
void my_write(const char* str, int size) {
fwrite(str, size, 1, stdout);
}
struct MyWriter {
void write(const char* buf, size_t size) const {
fwrite(str, size, 1, stdout);
}
};
struct MyWriteFunctor {
fwrite(str, size, 1, stdout);
}
};
...
printUsage(my_write, usage);
MyWriteFunctor wfunctor;
ostringstream sstr;
TRObject operator()(const T1 &t1) const
void printUsage(OStream &prn, const Descriptor usage[], int width=80, int last_column_min_percent=50, int last_column_own_line_max_percent=75)
Outputs a nicely formatted usage string with support for multi-column formatting and line-wrapping.
- Notes:
- the
write() method of a class that is to be passed as a temporary as MyWriter() is in the example, must be a const method, because temporary objects are passed as const reference. This only applies to temporary objects that are created and destroyed in the same statement. If you create an object like writer in the example, this restriction does not apply.
- a functor like
MyWriteFunctor in the example must be passed as a pointer. This differs from the way functors are passed to e.g. the STL algorithms.
- All printUsage() templates are tiny wrappers around a shared non-template implementation. So there's no penalty for using different versions in the same program.
- printUsage() always interprets Descriptor::help as UTF-8 and always produces UTF-8-encoded output. If your system uses a different charset, you must do your own conversion. You may also need to change the font of the console to see non-ASCII characters properly. This is particularly true for Windows.
- Security warning: Do not insert untrusted strings (such as user-supplied arguments) into the usage. printUsage() has no protection against malicious UTF-8 sequences.
- Parameters
-
| prn | The output method to use. See the examples above. |
| usage | the Descriptor[] array whose help texts will be formatted. |
| width | the maximum number of characters per output line. Note that this number is in actual characters, not bytes. printUsage() supports UTF-8 in help and will count multi-byte UTF-8 sequences properly. Asian wide characters are counted as 2 characters. |
| last_column_min_percent | (0-100) The minimum percentage of width that should be available for the last column (which typically contains the textual explanation of an option). If less space is available, the last column will be printed on its own line, indented according to last_column_own_line_max_percent. |
| last_column_own_line_max_percent | (0-100) If the last column is printed on its own line due to less than last_column_min_percent of the width being available, then only last_column_own_line_max_percent of the extra line(s) will be used for the last column's text. This ensures an indentation. See example below. |
--3456789 1234567890
1234567890
--3456789
123456789012345
67890
--3456789
12345
67890
12345
67890
Definition at line 2798 of file OptionParser.h.
ROOT 6.18/05 - Reference Guide Generated on Wed Apr 13 2022 01:59:23 (GVA Time) using Doxygen 1.9.4 (15dae504a167d838873053cc96417d8beae78df7).