Copyright © 2017, 2020 Ramsey Dow.

• What is Arg Machine?
• What Arg Machine doesn't do
• Requirements
• Using Arg Machine
• Where to go next

Arg Machine is free software. It is distributed under The MIT License.

Arg Machine is a portable command line argument processor that runs on Unix and Unix-like operating systems, like Linux and macOS. It also runs on modern Windows. In fact, Arg Machine can run anywhere that supports modern C++ apps. Arg Machine implements the functionality you've come to expect from GNU getopt, but in a simpler, more straightforward way.

Arg Machine is opinionated. Instead of requiring you to write the logic to process argc and argv**, it does the work for you. Just specify the arguments that your program accepts, instantiate the processor and feed user-supplied arguments to the process method. Arg Machine will translate those command line arguments into runtime state for your program.

Arg Machine understands short (-h) and long (--help) arguments, including variants that support only one type (e.g., short only with no long counterpart). However, Arg Machine is not completely POSIX compliant. It does not permit multiple arguments to follow a single hyphen (e.g., -abc as shorthand for -a -b -c). Arguments may be configured to take an additional parameter, but this is not required. Additional parameters may be optional or they may be required.

Non-argument inputs may be freely interspersed throughout the command line. These will be ignored by the argument processor. In fact, arguments will be removed as they are processed, leaving argv** to contain only the non-argument inputs. argc is automatically updated to the correct count. The user program can make use of these additional program inputs once argument processing has completed.

Arg Machine provides several convenience features:

• The base name of the program
• The complete, original command line invocation (useful for logging purposes)
• Detailed usage information provided automatically via the -h and --help arguments
• The ability to add an additional string to usage output, e.g., a copyright statement

Arg Machine favors convention over configuration, allowing you to add standard argument processing capabilities to your programs quickly and easily. Arg Machine lets you focus on your app instead of the intricacies of argument processing.

Additional benefits:

• Distributed as a single header file (just #include <arguments> and start using the API)
• Flexible argument configuration using initialized lambda captures to define your program's runtime state
• No memory allocations on the heap

Please note that Arg Machine has not been tested for multithread safety. It is meant to be invoked by main and executed in the main thread.

Arg Machine does not perform argument validation. It has no idea what constitutes a valid argument for your app. Similarly, Arg Machine does not assign default values to arguments with parameters or ensure that all required arguments have been invoked. These are all tasks best left to the application developer.

Arg Machine follows the Unix tradition of doing one thing and doing it well. In this case, translating command line arguments into actionable runtime state. What you do with that state (and any left over, non-argument input parameters) is up to you.

Arg Machine was born in the Unix world where main doesn't have a wchar_t variant (like WinMain on Windows platforms). Arg Machine does not currently support wide arguments on Windows. This shortcoming will be addressed in a future release.

This all sounds great, but what's the catch?

Arg Machine requires a modern C++ compiler because it relies on initialized lambda captures, a C++14 extension.

That's it!

Arg Machine is supplied as a single header file. Just #include <arguments> in your C++ application and you are ready to go. Using the API is straightforward:

• Initialize and configure one argument::config instance per argument.
• Instantiate an argument::processor instance, passing in a std::initialization_list of your argument::config instances.
• Invoke the process method on your argument::processor instance.
• Catch and deal with any argument::bad_argument exceptions that arise.

Assuming no exceptional conditions, the command line arguments will have been processed and the runtime state configured as specified by the configurations of your argument::config instances. The program's argc and argv** will have been rewritten to include just the non-arguments that were skipped by the processor. It is at this point that you will perform argument validation, initialize unspecified arguments to sane defaults, and deal with any non-argument input parameters.

Refer to sample.cc for a complete example that illustrates how to use the Arg Machine API.

All of Arg Machine's documentation can be found in the project wiki. In addition to API documentation, there are pages that detail additional topics, including how to contribute to the project.