opzioni

opzioni is a command line arguments parser library for C++.

Goals

The goals of this library, in order of importance, are:

1. Be as simple and enjoyable as possible.

   This mainly targets the user of the library, but also includes the user of the command line tool built with it.

2. constexpr-all-the-things.

   Most of the time, all the information needed to build a command line interface is available at compile-time, so we should take advantage of that.

3. If it compiles, it works.

   That's utopic, but that's what is being strived for. It's also very closely related to the previous goal. We should be able to detect most errors at compile-time and provide decent diagnostics.

4. Try not to repeat yourself.

   When specifying a CLI, if some information was already given to the library, that same information should not be needed again. For example, if the type of an argument was already specified, the user should not be asked to tell the type again. Unfortunately that is very hard, so some places still require duplicate information.

5. Be bleeding-edge.

   This library requires C++20. That limits a lot its potential users, but also allows for the use of the new and powerful features of C++. It also helps to accomplish the previous goals.

Disclaimer

• This is a personal project with no promise of maintainability for the time being.

  I started it to learn more about C++ and its new features.

• Although it is not in early development, since I'm working on it for months and iterated over it many times, it is not stable or production-ready.

• There are many unit tests missing.

• I frequently changed the interface of the library and I'm not afraid of changing it radically again if I think it would improve the UX.

  Another example is the names of the namespaces and what is in them.

• There is a lot of polish and optimization work to do.

• There is a whole documentation to write.

Sneak peek

The code below is a fully working example, taken from examples/hello.cpp, only reformatted and with quotes changed to angle brackets in the #include. Feel free to take a look at the other, more complex, examples in the same directory.

#include <iostream>
#include <string_view>

#include <opzioni.hpp>

int main(int argc, char const *argv[]) {
  using namespace opzioni;

  constexpr auto hello =
    Program("hello")
      .version("0.1")
      .intro("Greeting people since the dawn of computing")
      .add(Pos("name").help("Your name please, so I can greet you"))
      .add(Help())
      .add(Version());

  auto const args = hello(argc, argv);
  std::string_view const name = args["name"];
  std::cout << "Hello, " << name << "!\n";
}

That gives us:

1. Automatic help with --help or -h

   $ ./build/examples/hello -h
   hello 0.1
   
   Greeting people since the dawn of computing
   
   Usage:
       hello <name> [--help] [--version]
   
   Positionals:
       name             Your name please, so I can greet you
   
   Options & Flags:
       -h, --help       Display this information
       -V, --version    Display the software version
   

2. Automatic version with --version or -V

   $ ./build/examples/hello -V
   hello 0.1
   

3. Automatic error handling

   $ ./build/examples/hello Gabriel Galli
   Unexpected positional argument `Galli`. This program expects 1 positional arguments
   
   Usage:
       hello <name> [--help] [--version]
   

4. And finally:

   $ ./build/examples/hello "Gabriel Galli"
   Hello, Gabriel Galli!
   

Getting started

opzioni is not published anywhere yet. Meanwhile, it is kinda straightforward to build it locally, since just a simple conda environment is enough to bootstrap a development environment. The build system is the awesome Meson.

1. Download and install conda if you haven't already. Just grab a suitable installer from here and run it. There's also an install guide here.

2. Clone this repository:

   git clone https://github.com/ggabriel96/opzioni.git

3. Create the conda environment:

   conda env create -f environment.yml

4. Activate the newly created conda environment:

   conda activate opzioni

5. Build it!

   make

Note that the Makefile is just a shortcut to the actual commands. Feel free to inspect it and not use it.

License

opzioni's license is the Boost Software License (BSL) 1.0.

This means you are free to use this library as you wish and see fit.

It is only needed to provide a copy of the license if the source is also being distributed.

In other words, there is no need to bundle opzioni's license with your binary.

Acknowledgements

Thank you to JetBrains for supporting this project by providing free access to its products as part of the Open Source Licenses program.