Introduce a minimal command-line option parsing library

Signed-off-by: Juan Cruz Viotti <jv@jviotti.com>

Author: jviotti

.github/workflows/website-build.yml

@@ -28,5 +28,6 @@ jobs:
           -DSOURCEMETA_CORE_JSONPOINTER:BOOL=OFF
           -DSOURCEMETA_CORE_YAML:BOOL=OFF
           -DSOURCEMETA_CORE_EXTENSION_ALTERSCHEMA:BOOL=OFF
+          -DSOURCEMETA_CORE_EXTENSION_OPTIONS:BOOL=OFF
           -DSOURCEMETA_CORE_DOCS:BOOL=ON
       - run: cmake --build ./build --config Release --target doxygen

.github/workflows/website-deploy.yml

@@ -38,6 +38,7 @@ jobs:
           -DSOURCEMETA_CORE_JSONPOINTER:BOOL=OFF
           -DSOURCEMETA_CORE_YAML:BOOL=OFF
           -DSOURCEMETA_CORE_EXTENSION_ALTERSCHEMA:BOOL=OFF
+          -DSOURCEMETA_CORE_EXTENSION_OPTIONS:BOOL=OFF
           -DSOURCEMETA_CORE_DOCS:BOOL=ON
       - run: cmake --build ./build --config Release --target doxygen
       - name: Setup Pages

CMakeLists.txt

@@ -16,6 +16,7 @@ option(SOURCEMETA_CORE_JSONPOINTER "Build the Sourcemeta Core JSON Pointer libra
 option(SOURCEMETA_CORE_JSONL "Build the Sourcemeta Core JSONL library" ON)
 option(SOURCEMETA_CORE_YAML "Build the Sourcemeta Core YAML library" ON)
 option(SOURCEMETA_CORE_EXTENSION_ALTERSCHEMA "Build the Sourcemeta Core AlterSchema library" ON)
+option(SOURCEMETA_CORE_EXTENSION_OPTIONS "Build the Sourcemeta Core Options library" ON)
 option(SOURCEMETA_CORE_TESTS "Build the Sourcemeta Core tests" OFF)
 option(SOURCEMETA_CORE_BENCHMARK "Build the Sourcemeta Core benchmarks" OFF)
 option(SOURCEMETA_CORE_DOCS "Build the Sourcemeta Core docs" OFF)
@@ -115,6 +116,10 @@ if(SOURCEMETA_CORE_EXTENSION_ALTERSCHEMA)
   add_subdirectory(src/extension/alterschema)
 endif()
 
+if(SOURCEMETA_CORE_EXTENSION_OPTIONS)
+  add_subdirectory(src/extension/options)
+endif()
+
 if(SOURCEMETA_CORE_ADDRESS_SANITIZER)
   sourcemeta_sanitizer(TYPE address)
 elseif(SOURCEMETA_CORE_UNDEFINED_SANITIZER)
@@ -198,6 +203,10 @@ if(SOURCEMETA_CORE_TESTS)
     add_subdirectory(test/alterschema)
   endif()
 
+  if(SOURCEMETA_CORE_EXTENSION_OPTIONS)
+    add_subdirectory(test/options)
+  endif()
+
   if(PROJECT_IS_TOP_LEVEL)
     # Otherwise we need the child project to link
     # against the sanitizers too.

config.cmake.in

@@ -17,6 +17,7 @@ if(NOT SOURCEMETA_CORE_COMPONENTS)
   list(APPEND SOURCEMETA_CORE_COMPONENTS jsonschema)
   list(APPEND SOURCEMETA_CORE_COMPONENTS yaml)
   list(APPEND SOURCEMETA_CORE_COMPONENTS alterschema)
+  list(APPEND SOURCEMETA_CORE_COMPONENTS options)
 endif()
 
 include(CMakeFindDependencyMacro)
@@ -70,6 +71,8 @@ foreach(component ${SOURCEMETA_CORE_COMPONENTS})
     include("${CMAKE_CURRENT_LIST_DIR}/sourcemeta_core_jsonpointer.cmake")
     include("${CMAKE_CURRENT_LIST_DIR}/sourcemeta_core_jsonschema.cmake")
     include("${CMAKE_CURRENT_LIST_DIR}/sourcemeta_core_alterschema.cmake")
+  elseif(component STREQUAL "options")
+    include("${CMAKE_CURRENT_LIST_DIR}/sourcemeta_core_options.cmake")
   else()
     message(FATAL_ERROR "Unknown Sourcemeta Core component: ${component}")
   endif()

src/extension/options/CMakeLists.txt

@@ -0,0 +1,6 @@
+sourcemeta_library(NAMESPACE sourcemeta PROJECT core NAME options
+  PRIVATE_HEADERS error.h SOURCES options.cc)
+
+if(SOURCEMETA_CORE_INSTALL)
+  sourcemeta_library_install(NAMESPACE sourcemeta PROJECT core NAME options)
+endif()

src/extension/options/include/sourcemeta/core/options.h

@@ -0,0 +1,126 @@
+#ifndef SOURCEMETA_CORE_OPTIONS_H_
+#define SOURCEMETA_CORE_OPTIONS_H_
+
+#ifndef SOURCEMETA_CORE_OPTIONS_EXPORT
+#include <sourcemeta/core/options_export.h>
+#endif
+
+// NOLINTBEGIN(misc-include-cleaner)
+#include <sourcemeta/core/options_error.h>
+// NOLINTEND(misc-include-cleaner)
+
+#include <cstddef>          // std::size_t
+#include <initializer_list> // std::initializer_list
+#include <memory>           // std::unique_ptr
+#include <string>           // std::string
+#include <string_view>      // std::string_view
+#include <unordered_map>    // std::unordered_map
+#include <unordered_set>    // std::unordered_set
+#include <vector>           // std::vector
+
+/// @defgroup options Options
+/// @brief A simple and minimalistic UNIX-style command-line parsing library
+///
+/// This functionality is included as follows:
+///
+/// ```cpp
+/// #include <sourcemeta/core/options.h>
+/// ```
+
+namespace sourcemeta::core {
+
+/// @ingroup options
+/// Command-line option parsing modifiers
+struct OptionsModifiers {
+  /// Ignore the first N command-line arguments
+  std::size_t skip{0};
+};
+
+/// @ingroup options
+///
+/// This class performs basic command-line argument parsing based on options,
+/// flags, and aliases. For example:
+///
+/// ```cpp
+/// #include <sourcemeta/core/options.h>
+/// #include <cstdlib>
+/// #include <iostream>
+///
+/// auto main(int argc, char *argv[]) -> int {
+///   sourcemeta::core::Options app;
+///   app.option("name", {"n"});
+///   app.flag("shout", {"s"});
+///   app.parse(argc, argv);
+///
+///   if (!app.contains("name")) {
+///     std::cerr << "Missing name\n";
+///     return EXIT_FAILURE;
+///   }
+///
+///   std::cerr << "Hello, " << app.at("name").front();
+///   if (app.contains("shout")) {
+///     std::cerr << "!\n";
+///   } else {
+///     std::cerr << "\n";
+///   }
+///
+///   return EXIT_SUCCESS;
+/// }
+/// ```
+class SOURCEMETA_CORE_OPTIONS_EXPORT Options {
+public:
+  Options() = default;
+  // Disallow copies given the unique pointers
+  Options(const Options &) = delete;
+  auto operator=(const Options &) -> Options & = delete;
+  Options(Options &&) noexcept = default;
+  auto operator=(Options &&) noexcept -> Options & = default;
+
+  /// Declare a new option, which must take a value
+  auto option(std::string &&name, std::initializer_list<std::string> aliases)
+      -> void;
+
+  /// Declare a new flag, which must not take a value
+  auto flag(std::string &&name, std::initializer_list<std::string> aliases)
+      -> void;
+
+  /// Access the values (if any) set for an option or flag, by its main name
+  [[nodiscard]] auto at(std::string_view name) const
+      -> const std::vector<std::string_view> &;
+
+  /// Check if an option or flag was set, by its main name
+  [[nodiscard]] auto contains(std::string_view name) const -> bool;
+
+  /// Access the positional arguments, if any
+  [[nodiscard]] auto positional() const
+      -> const std::vector<std::string_view> &;
+
+  /// Parse program arguments given the declared options and flags
+  auto parse(const int argc,
+             // We want to be compatible with `main`s `argv`
+             // NOLINTNEXTLINE(modernize-avoid-c-arrays)
+             const char *const argv[], const OptionsModifiers options = {})
+      -> void;
+
+private:
+// Exporting symbols that depends on the standard C++ library is considered
+// safe.
+// https://learn.microsoft.com/en-us/cpp/error-messages/compiler-warnings/compiler-warning-level-2-c4275?view=msvc-170&redirectedfrom=MSDN
+#if defined(_MSC_VER)
+#pragma warning(disable : 4251 4275)
+#endif
+  static constexpr std::string_view POSITIONAL_ARGUMENT_NAME{""};
+  static constexpr std::vector<std::string_view> EMPTY{};
+
+  std::vector<std::unique_ptr<std::string>> storage;
+  std::unordered_map<std::string_view, std::string_view> aliases_;
+  std::unordered_map<std::string_view, std::vector<std::string_view>> options_;
+  std::unordered_set<std::string_view> flags;
+#if defined(_MSC_VER)
+#pragma warning(default : 4251 4275)
+#endif
+};
+
+} // namespace sourcemeta::core
+
+#endif // SOURCEMETA_CORE_OPTIONS_H_

src/extension/options/include/sourcemeta/core/options_error.h

@@ -0,0 +1,70 @@
+#ifndef SOURCEMETA_CORE_OPTIONS_ERROR_H_
+#define SOURCEMETA_CORE_OPTIONS_ERROR_H_
+
+#ifndef SOURCEMETA_CORE_OPTIONS_EXPORT
+#include <sourcemeta/core/options_export.h>
+#endif
+
+#include <stdexcept> // std::runtime_error
+#include <string>    // std::string
+#include <utility>   // std::move
+
+namespace sourcemeta::core {
+
+// Exporting symbols that depends on the standard C++ library is considered
+// safe.
+// https://learn.microsoft.com/en-us/cpp/error-messages/compiler-warnings/compiler-warning-level-2-c4275?view=msvc-170&redirectedfrom=MSDN
+#if defined(_MSC_VER)
+#pragma warning(disable : 4251 4275)
+#endif
+
+/// @ingroup options
+/// This class represents a general options error
+struct SOURCEMETA_CORE_OPTIONS_EXPORT OptionError : public std::runtime_error {
+  explicit OptionError(const std::string &message)
+      : std::runtime_error{message} {}
+};
+
+/// @ingroup options
+/// This class represents a unknown option error
+struct SOURCEMETA_CORE_OPTIONS_EXPORT OptionsUnknownOptionError
+    : public OptionError {
+  explicit OptionsUnknownOptionError(std::string name)
+      : OptionError{"Unknown option"}, name_{std::move(name)} {}
+  [[nodiscard]] auto name() const -> const auto & { return this->name_; }
+
+private:
+  std::string name_;
+};
+
+/// @ingroup options
+/// This class represents a value being passed to a flag
+struct SOURCEMETA_CORE_OPTIONS_EXPORT OptionUnexpectedValueFlagError
+    : public OptionError {
+  explicit OptionUnexpectedValueFlagError(std::string name)
+      : OptionError{"Cannot pass a value to a flag"}, name_{std::move(name)} {}
+  [[nodiscard]] auto name() const -> const auto & { return this->name_; }
+
+private:
+  std::string name_;
+};
+
+/// @ingroup options
+/// This class represents a missing value from an option
+struct SOURCEMETA_CORE_OPTIONS_EXPORT OptionMissingOptionValueError
+    : public OptionError {
+  explicit OptionMissingOptionValueError(std::string name)
+      : OptionError{"This option takes a value"}, name_{std::move(name)} {}
+  [[nodiscard]] auto name() const -> const auto & { return this->name_; }
+
+private:
+  std::string name_;
+};
+
+#if defined(_MSC_VER)
+#pragma warning(default : 4251 4275)
+#endif
+
+} // namespace sourcemeta::core
+
+#endif