Option++

Table of Contents

• Introduction
• Features
• Option Format
• Example Program
• Copyright

C++ library for reading command-line program options. Written by Greg Kikola.

• Tutorial
• Example Programs
• Build Instructions
• Class List
• File List
• GitHub Repository

Introduction

Option++ provides an easy way to read, validate, and process command-line options. It can also generate a detailed, properly formatted help message.

There is a single-header version of the library provided, or you can build and link to the shared library.

Features

• Supports the usual Unix and GNU/Linux conventions
  • Use long (--option) and short (-o) option names
  • Double dash by itself (--) indicates end of options
  • Options may have mandatory or optional arguments
• Can parse arguments passed to main directly, or can read options from a string
• Allows you to bind variables directly to options
• Input validation for numerical arguments
• Can automatically generate a help message
• Options can be separated into groups for better organization
• Easily iterate over all parsed data
  • If desired, can iterate over only non-option arguments
  • Can also iterate over only option arguments
• The strings that are used as option prefixes can be customized
• Exception-based error handling

Option Format

Both long and short option names are supported. For example:

myprogram --verbose -af file.txt

Each option may be set to take an optional or mandatory argument:

myprogram --output=file.txt

The equals sign is not required:

myprogram -o file.txt

With short options, an argument may be written immediately after the option name:

mycompiler -DMY_DEFINE

'--' can be provided by itself as an argument to indicate that all remaining command-line arguments should not be interpreted as options:

myprogram --this-is-an-option -- --this-is-not

Example Program

Here is a simple program that demonstrates how you can use Option++:

#include <iostream>
#include <string>
 
#include <optionpp/optionpp.hpp>
 
struct Settings {
  bool show_help {false};
  bool show_version {false};
  bool verbose {false};
  std::string output_file;
};
 
using optionpp::parser;
using optionpp::parser_result;
using optionpp::non_option_const_iterator;
 
void print_version() {
  std::cout << "My Program 1.0" << std::endl;
}
 
int main(int argc, char* argv[]) {
  Settings settings;
  parser opt_parser;
 
  // Set up options
  opt_parser["help"].short_name('?')
    .description("Show help information")
    .bind_bool(&settings.show_help);
  opt_parser["version"]
    .description("Show program version information")
    .bind_bool(&settings.show_version);
  opt_parser["verbose"].short_name('v')
    .description("Display additional explanations")
    .bind_bool(&settings.verbose);
  opt_parser["output"].short_name('o')
    .description("File to write output")
    .bind_string(&settings.output_file);
 
  parser_result result;
 
  // Parse options
  try {
    result = opt_parser.parse(argc, argv);
  } catch(const optionpp::error& e) {
    std::cerr << "Error: " << e.what() << std::endl;
    return 1;
  }
 
  // Show help/version info
  if (settings.show_help) {
    print_version();
    std::cout << "This program does important stuff.\n\n"
              << "My Program accepts the following options:\n"
              << opt_parser << std::endl;
    return 0;
  } else if (settings.show_version) {
    print_version();
    return 0;
  }
 
  if (!settings.output_file.empty()) {
    if (settings.verbose)
      std::cout << "Writing output to '"
                << settings.output_file
                << "'" << std::endl;
 
    // Write output...
  } else {
    if (settings.verbose)
      std::cout << "Writing output to standard out" << std::endl;
 
    // Write output...
  }
 
  // Iterate over non-option arguments
  for (const auto& entry : non_option_const_iterator(result)) {
    if (!entry.is_option)
      std::cout << "Received argument '"
                << entry.original_text
                << "'" << std::endl;
  }
 
  return 0;
}

See the Examples page for more examples.

Copyright

Copyright © 2017-2020 Greg Kikola. License BSL-1.0: Boost Software License version 1.0.

Option++ is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.