dropt (deliberately rudimentary options)

Goals

Aren’t there plenty of existing option-parsing libraries already? Yes, there are, but none of the ones that I had seen had the ease of use I wanted. The primary design goal for dropt is to have minimal barriers to entry. Specifically, this includes:

High portability. dropt is written in standard C99 with compatibility code for most non-pathological C89 compilers. (wchar_t support for the help facility is supported only on Windows platforms, however.) dropt is written in C to make it easily consumable. C++ wrappers also are provided as a convenience for C++ clients.
(Hopefully) straightforward usage.
No global variables.
Minimal dependencies. dropt has no dependencies other than the standard C library. dropt also lets clients opt-in to use only the specific features they want.
An unrestrictive license. dropt uses the zlib/libpng license and may be statically linked with existing code freely. This avoids some of the hassles that sometimes come with dynamically-linked libraries (such as ensuring that the compiler options used to build the library match those used for the main binary).
(Approximate) POSIX compatibility. Existing applications that use POSIX-style options hopefully should be able to use dropt without breaking their command-line interface. (The notable difference is that dropt by default does not allow options to be concatenated with their arguments (e.g. -oARGUMENT). POSIX also discourages this but makes exceptions for backwards compatibility reasons. dropt requires that applications opt-in to this behavior.)
Flexibility. dropt is designed to be callback-based. This allows it to handle arbitrary arguments to command-line options. Even basic types such as integers or strings are handled by callbacks; dropt provides standard handlers for them. Exposing the handlers for basic types also allows programs to extend them by building wrappers around them.

Features

dropt provides basic option-parsing features:

GNU-style long options (e.g. --option).
Grouping for short options (e.g. “-abc” is equivalent to “-a -b -c”).
Automatically stops parsing when encountering a “--” token. This allows programs to take arguments that start with “-” and not have them be treated as options. Examples:
- rm -- -rf
- some_numeric_program -- -123
Unambiguous syntax for arguments to options. Arguments may always be specified with “=” (e.g. --option=1, -x=1).
Overridable option values. For example, “--option=1 --option=2” will use the value 2. Boolean flags can be disabled by using --flag=0 (since --flag by itself is syntactic sugar for --flag=1). This is useful to override options specified by shell aliases. Note that clients that specify custom handlers can implement different behaviors if desired.

The implementation is intended to be minimalistic. What dropt does not do:

Localization. dropt doesn’t provide localization facilities, but it does try not to stand in the way of programs that want to localize their help text however they choose.
Tokenizing a single command-line string into an argv array. This is the shell’s responsibility. (On Windows, where WinMain() does not receive a tokenized argv array, developers should use CommandLineToArgvW or should use the __argv global from Microsoft’s C runtime library.)
Command-line argument permutation. dropt always expects options to come before non-options.
Handling of different option styles (e.g. /option, -option). dropt is meant to encourage consistent command-line option interfaces.

Usage

There’s no formal documentation yet, but for now, see dropt_example.c.

Download

Version History

1.0.3 (2010-08-08)
- dropt_handle_bool and dropt_handle_verbose_bool now return dropt_error_mismatch instead of dropt_error_insufficient_arguments if given empty string arguments.
- The error messages from dropt_default_error_handler now consistently do not end with periods.
1.0.2 (2010-07-28)
- dropt_handle_bool and dropt_handle_verbose_bool now return dropt_error_mismatch instead of dropt_error_overflow if given very large numbers.
- Fixed the compilation of test_dropt.c when building with _UNICODE=1.
1.0.1 (2010-07-03)
- Calling dropt_ssgetstring on a newly-opened dropt_stringstream returned garbage. Fixed. This would have affected only clients that used dropt_stringstream directly.
- The MIN and MAX macros in dropt_string.c are now conditionally defined.
- dropt_safe_malloc and dropt_safe_realloc are now publicly declared in dropt_string.h.
- Renamed DROPT_MISUSE_PANIC to DROPT_MISUSE since it's non-fatal in non-debug builds.
- DEFAULT_STRINGSTREAM_BUFFER_SIZE is now an enum constant instead of a preprocessor macro.
- Modified test_dropt.c. Now tries harder to report line numbers on failure, and more tests continue executing upon failure. Added a few more tests for dropt_stringstream functions. Rewrote one of the sample option handler callbacks more general.
1.0 (2010-06-19)
- Initial release.