Skip to content
This repository has been archived by the owner on Apr 6, 2023. It is now read-only.
/ popl20 Public archive
forked from badaix/popl

Header-only C++ program options parser library based on the original popl repo but restyled using C++20,

License

Notifications You must be signed in to change notification settings

WinterWind33/popl20

This branch is 1 commit ahead of badaix/popl:master.

Folders and files

NameName
Last commit message
Last commit date

Latest commit

5357345 · Aug 25, 2022
Aug 25, 2022
Aug 25, 2022
Aug 25, 2022
Aug 2, 2021
Aug 25, 2022
Aug 2, 2021
Aug 25, 2022
Aug 25, 2022
Aug 25, 2022
Aug 25, 2022
Aug 25, 2022
Aug 2, 2021
Aug 25, 2022

Repository files navigation

popl20

popl20 is a fork of popl repo that aims to bring the same idea of the original project but rewritten with a more modern style, following the C++ 20 standard.

popl is a C++ command line arguments parser that supports the same set of options as GNU's getopt and thus closely follows the POSIX guidelines for the command-line options of a program.

The popl20 refactor

What is being developed in this forked repository is essentially a refactor of popl where the same features are rewritten using C++20.

The refactor is carried on following the roadmap:

  1. Initial update with build system refactoring, workflow setup, VS Code configuration files setup and test framework in place;

  2. Analysis of the features and test suite with a full code coverage (Unit, Integration and Functional tests);

  3. Refactor of the library using C++20;

These are the main objective that this repo wants to reach, these can be unpacked into sub-tasks.

More tests

Of course, since this is a refactor it's unpleasant to have regressions and bugs during or after the refactor so there is a need to cover the production code with more tests than there are now, so there can be a safety net against regressions.

To achieve a great test suite, dependencies need to be broken down: there could be changes in this respect inside the API. Breaking changes are not fun, so if there will be the need to change something, deprecation will be the preferred route.

An objective that this refactor wants to achieve is Tests as Documentation: anyone who wants to use this library can understand how it works by looking at unit tests.

New features

There is a chance that during the refactor some new features can be added but with retro-compatibility of the previous ones in mind.

Possible new features:

  1. (Not confirmed) More char types support;

Features

  • Single header file implementation. Simply include and use it!
  • No external dependencies (in production code), just C++20
  • Platform independent
  • Supports the same set of options as GNU's getopt: short options, long options, non-option arguments, ...
  • Supports parsing of ini files
  • Templatized option parsing: arguments are directly casted into the desired target type
  • Automatic creation of a usage message
    • Console help message
    • Groff formatted help message for use in man pages
    • Script snippets for use in bash completion scripts
  • Easy to use: no strange braces syntax, but for each command line option one typesafe object

Howto

Key object is OptionParser, which is populated with different option types:

  • Value<T> Option with argument
  • Switch Option without argument
  • Implicit<T> Option with optional argument (using an implicit value if no argument is given)

Next, OptionParser will parse the command line (by passing argc and argv) and fill the option objects. Each option type is initialized with a short option, long option and a help message.

Basic usage example

OptionParser op("Allowed options");
auto help_option   = op.add<Switch>("h", "help", "produce help message");
auto string_option = op.add<Value<std::string>>("s", "string", "some string value");
auto implicit_int  = op.add<Implicit<int>>("m", "implicit", "implicit value", 42);
op.parse(argc, argv);

// print auto-generated help message
if (help_option->is_set())
	cout << op << "\n";
cout << "string_option - is_set: " << string_option->is_set() << ", value: " << string_option->value() << "\n";
cout << "implicit_int  - is_set: " << implicit_int->is_set() << ", value: " << implicit_int->value() << "\n";

Multiple definition

Options can be set multiple times on command line. Use count() and value(n) to access them:

cout << "string_option - count: " << string_option->count() << "\n";
if (string_option->is_set())
{
	for (size_t n=0; n<string_option->count(); ++n)
		cout << "string_option #" << n << " - value: " << string_option->value(n) << "\n";
}

Default values

Every option type can have a default value:

auto string_option = op.add<Value<std::string>>("s", "string", "some string value", "default value");

if not set on command line, string_option->is_set() will be false and string_option->value() will be default value

Assigning to a variable

The argument of an option can be directly assigned to a variable:

std::string s;
/*auto string_option =*/ op.add<Value<std::string>>("s", "string", "some string value", "default value", &s);

The variable s will carry the same value as string_option.value(), and thus the declaration of string_option can be omitted.

Attributes of an option

Options have an Attribute: they can be hidden in the auto-created help message, or classified as "advanced", or "expert":

auto string_option = op.add<Value<std::string>>("s", "string", "some string value");
auto advanced_int  = op.add<Value<int>, Attribute::advanced>("i", "integer", "advanced integer value");
auto hidden_bool   = op.add<Switch, Attribute::hidden>("", "hidden", "hidden flag");

Now cout << op.help() (same as cout << op) will not show the hidden or advanced option, while cout << op.help(Attribute::advanced) will show the advanced option. The hidden one is never shown to the user. Also an option can be flagged as mandatory by assigning Attribute::required

Example

#include "popl.hpp"

using namespace std;
using namespace popl;

int main(int argc, char **argv)
{
	float f;
	int m, i;
	bool v;

	OptionParser op("Allowed options");
	auto help_option     = op.add<Switch>("h", "help", "produce help message");
	auto verbose_option  = op.add<Switch>("v", "verbose", "be verbose", &v);
	auto hidden_option   = op.add<Switch, Attribute::hidden>("x", "", "hidden option");
	auto double_option   = op.add<Value<double>>("d", "double", "test for double values", 3.14159265359);
	auto float_option    = op.add<Value<float>>("f", "float", "test for float values", 2.71828182845f, &f);
	                       op.add<Value<int>>("i", "int", "test for int value w/o option", 23, &i);
	auto string_option   = op.add<Value<string>>("s", "string", "test for string values");
	auto implicit_int_option = op.add<Implicit<int>>("m", "implicit", "implicit test", 42);
	auto advanced_option = op.add<Switch, Attribute::advanced>("", "advanced", "advanced option");
	auto expert_option   = op.add<Switch, Attribute::expert>("", "expert", "expert option");
	auto inactive_option = op.add<Switch>("", "inactive", "inactive option");
	inactive_option->set_attribute(Attribute::inactive);
	implicit_int_option->assign_to(&m);

	op.parse(argc, argv);

	// print auto-generated help message
	if (help_option->count() == 1)
		cout << op << "\n";
	else if (help_option->count() == 2)
		cout << op.help(Attribute::advanced) << "\n";
	else if (help_option->count() > 2)
		cout << op.help(Attribute::expert) << "\n";

	// show all non option arguments (those without "-o" or "--option")
	for (const auto& non_option_arg: op.non_option_args())
		cout << "non_option_args: " << non_option_arg << "\n";

	// show unknown options (undefined ones, like "-u" or "--undefined")
	for (const auto& unknown_option: op.unknown_options())
		cout << "unknown_options: " << unknown_option << "\n";

	// print all the configured values
	cout << "verbose_option  - is_set: " << verbose_option->is_set() << ", count: " << verbose_option->count() << ", reference: " << v << "\n";
	cout << "hidden_option   - is_set: " << hidden_option->is_set() << ", count: " << hidden_option->count() << "\n";
	cout << "double_option   - is_set: " << double_option->is_set() << ", count: " << double_option->count() << ", value: " << double_option->value() << "\n";
	cout << "string_option   - is_set: " << string_option->is_set() << ", count: " << string_option->count() << "\n";
	if (string_option->is_set())
	{
		for (size_t n=0; n<string_option->count(); ++n)
			cout << "string_option #" << n << " - value: " << string_option->value(n) << "\n";
	}
	cout << "float_option    - is_set: " << float_option->is_set() << ", value: " << float_option->value() << ", reference: " << f << "\n";
	cout << "int w/o option  - reference: " << i << "\n";
	auto int_option = op.get_option<Value<int>>('i');
	cout << "int_option      - is_set: " << int_option->is_set() << ", value: " << int_option->value() << ", reference: " << i << "\n";
	cout << "imp_int_option  - is_set: " << implicit_int_option->is_set() << ", value: " << implicit_int_option->value() << ", reference: " << m << "\n";
	cout << "advanced_option - is_set: " << advanced_option->is_set() << ", count: " << advanced_option->count() << "\n";
	cout << "expert_option   - is_set: " << expert_option->is_set() << ", count: " << expert_option->count() << "\n";
}

A call to popl -s hello -h -m23 test will produce an output like this:

Allowed options:
  -h, --help                   produce help message
  -v, --verbose                be verbose
  -d, --double arg (=3.14159)  test for double values
  -f, --float arg (=2.71828)   test for float values
  -i, --int arg (=23)          test for int value w/o option
  -s, --string arg             test for string values
  -m, --implicit [=arg(=42)]   implicit test

non_option_args: test
verbose_option  - is_set: 0, count: 0, reference: 0
hidden_option   - is_set: 0, count: 0
double_option   - is_set: 0, count: 0, value: 3.14159
string_option   - is_set: 1, count: 1
string_option #0 - value: hello
float_option    - is_set: 0, value: 2.71828, reference: 2.71828
int w/o option  - reference: 23
int_option      - is_set: 0, value: 23, reference: 23
imp_int_option  - is_set: 1, value: 23, reference: 23
advanced_option - is_set: 0, count: 0
expert_option   - is_set: 0, count: 0

About

Header-only C++ program options parser library based on the original popl repo but restyled using C++20,

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • C++ 91.2%
  • CMake 7.5%
  • Makefile 1.3%