arg_parser.hpp

// FEAT3: Finite Element Analysis Toolbox, Version 3
// Copyright (C) 2010 by Stefan Turek & the FEAT group
// FEAT3 is released under the GNU General Public License version 3,
// see the file 'copyright.txt' in the top level directory for details.
 
#pragma once
 
#include <kernel/runtime.hpp>
#include <kernel/util/assertion.hpp>
#include <kernel/util/property_map.hpp>
#include <kernel/util/string.hpp>
 
#include <algorithm>
#include <any>
#include <deque>
#include <functional>
#include <iostream>
#include <memory>
#include <set>
#include <sstream>
#include <stdexcept>
#include <utility>
 
namespace FEAT
{
  // Architecture Notes. Read class documentation of ArgParser first.
  // The core of this argument parser implementation consists of four classes
  // - ArgParser is the actual parser
  // - Parameter is the user-facing interface of a parameter
  // - ParameterCore is the inner interface of a parameter used by the ArgParser
  // - ParameterBuilder is a class implementing the builder pattern to define parameters
  //
  // The split into Parameter and ParameterCore is a matter of type-erasure.
  // We want to both present a neat and well-typed interface to the user and
  // automatically handle the parameters in the parser.
  // But the parser can not handle the templated Parameters directly, because
  // they form a non-homogenous collection. To solve this the Parameter class
  // is just a thin wrapper around a type-erased ParameterCore.
  // The parser can handle the ParameterCores, and the Parameter presents a
  // well-typed interface.
  //
  // To achieve this type-erasure the ParameterCore stores its parsed values
  // in a std::any (essentially a void* and a type tag). Any type dependent
  // logic required by the ParameterCore (parsing and validation, for now)
  // is handled by supplying functions that accept std::any to the ParameterCore.
  // These functions are constructed during the parameter definition
  // (when type information is still available), by wrapping the properly
  // typed functions into std::any_casts.
  //
  // Thus the ArgParser holds a list of shared pointers to ParameterCores and has
  // the Parameters as members. The parameters hold a shared pointer to their
  // respective ParameterCore as well. The ArgParser then uses its list of
  // parameter cores to match arguments to parameters during parsing.
  //
  // Start reading at ArgParser::parameter to see how parameters are created and defined.
  // Start reading at ArgParser::parse to see how parsing is implemented.
 
  namespace Intern
  {
    template<typename>
    struct is_std_deque : std::false_type
    {
    };
 
    template<typename T, typename A>
    struct is_std_deque<std::deque<T, A>> : std::true_type
    {
    };
 
    template<typename T>
    constexpr bool is_std_deque_v = is_std_deque<T>::value;
 
    template<typename T, typename = void>
    struct has_input_operator : std::false_type
    {
    };
 
    template<typename T>
    struct has_input_operator<T, std::void_t<decltype((std::declval<std::istringstream&>() >> std::declval<T&>()))>>
      : std::true_type
    {
    };
 
    template<typename T>
    constexpr bool can_default_parse_v = has_input_operator<T>::value;
 
    template<typename T, typename A>
    constexpr bool can_default_parse_v<std::deque<T, A>> = has_input_operator<T>::value;
 
    template<typename T_>
    static void parse_collection(std::any& any, const String& s)
    {
      std::deque<T_> collection;
      for(const String& value_str : s.split_by_whitespaces())
      {
        T_ tmp{};
        if(!value_str.parse(tmp))
        {
          throw std::invalid_argument("Parsing failed for string '" + s + "'");
        }
        collection.push_back(tmp);
      }
 
      any = collection;
    }
 
    template<typename T_>
    static void parse_single(std::any& any, const String& s)
    {
      if(!s.parse(std::any_cast<T_&>(any)))
      {
        throw std::invalid_argument("Parsing failed for string '" + s + "'");
      }
    }
 
    template<typename T_>
    static void (*make_parser())(std::any&, const String&)
    {
      // If T_ has no input operator then instantiating a parser function for T_ will fail,
      // because String::parse depends on that operator.
      // But we want to give the user a chance to set a custom parser,
      // so we guard the instantiation of the default parser behind
      // can_default_parse_v
 
      if constexpr(!can_default_parse_v<T_>)
      {
        return nullptr;
      }
      else
      {
        if constexpr(is_std_deque_v<T_>)
        {
          return parse_collection<typename T_::value_type>;
        }
        else
        {
          return parse_single<T_>;
        }
      }
    }
 
    template<typename T_>
    static void (*make_printer())(std::ostream&, const std::any&)
    {
      if constexpr(is_std_deque_v<T_>)
      {
        return [](std::ostream& s, const std::any& v)
        {
          s << "[";
          for(const auto& i : std::any_cast<const T_&>(v))
          {
            s << i << ", ";
          }
          s << "]";
        };
      }
      else
      {
        return [](std::ostream& s, const std::any& v) { s << std::any_cast<const T_&>(v); };
      }
    }
 
    enum class ParameterType : std::uint8_t
    {
      flag,
      option,
      collection_option,
    };
 
    class ParameterCore
    {
    public:
      using ParserType = std::function<void(std::any&, const String&)>;
      using ValidatorType = std::function<void(const std::any&)>;
      using PrinterType = std::function<void(std::ostream&, const std::any&)>;
 
      using Need = std::pair<std::weak_ptr<ParameterCore>, std::function<bool(const std::any&)>>;
 
      // Parsing information
      ParameterType type = ParameterType::flag;
      String short_flag{""};
      String long_flag{""};
      String environment_variable{""};
      String property_path{""};
 
      // Strings for usage documentation
      String custom_name;
      String placeholder;
      String help_string;
 
      // Metadata
      int priority = 0;
      bool required = false;
      bool set_by_user = false;
      std::deque<Need> needs;
 
      // Raw and parsed values
      std::deque<String> arguments;
      std::any default_value;
      std::any value;
 
      // Type-erased functions
      ParserType parser;
      ValidatorType validator;
      PrinterType printer;
 
      template<typename T_>
      explicit ParameterCore(T_ def_value) :
        default_value(def_value),
        value(default_value),
        printer(Intern::make_printer<T_>())
      {
        if constexpr(std::is_same_v<T_, bool>)
        {
          // Boolean flags do not consume any arguments beyond the flag itself
          type = ParameterType::flag;
        }
        else if constexpr(Intern::is_std_deque_v<T_>)
        {
          // Collection options append all arguments until the next flag
          type = ParameterType::collection_option;
        }
        else
        {
          type = ParameterType::option;
        }
      }
 
      String name() const;
 
      void add_argument(const String& s, int incoming_priority);
 
      void validate(std::deque<String>& errors) const;
 
      void parse(std::deque<String>& errors);
 
      void reset();
    };
 
  } // namespace Intern
 
  template<typename T_>
  class ParameterBuilder;
 
  template<typename T_>
  class Parameter
  {
  private:
    std::shared_ptr<Intern::ParameterCore> _core;
 
  public:
    template<typename U_>
    friend class ParameterBuilder;
 
    explicit Parameter(std::shared_ptr<Intern::ParameterCore>&& core) : _core(std::move(core))
    {
    }
 
    explicit Parameter(std::shared_ptr<Intern::ParameterCore> core) : _core(std::move(core))
    {
    }
 
    operator bool() // NOLINT
    {
      return _core->set_by_user;
    }
 
    const T_& value() const
    {
      return std::any_cast<const T_&>(_core->value);
    }
 
    const T_& operator*() const
    {
      return std::any_cast<const T_&>(_core->value);
    }
 
    const T_* operator->() const
    {
      return std::any_cast<const T_>(&(_core->value));
    }
  };
 
  template<typename T_>
  class ParameterBuilder
  {
  private:
    std::shared_ptr<Intern::ParameterCore> _core;
 
  public:
    explicit ParameterBuilder(std::shared_ptr<Intern::ParameterCore> core) : _core(std::move(core))
    {
    }
 
    ParameterBuilder& short_flag(String&& s)
    {
      XASSERTM(s.size() == 2, "Short flag must have length two");
      XASSERTM(s[0] == '-', "Short must start with a '-'");
      XASSERTM(s[1] != '-', "Short must not end with a '-'");
 
      _core->short_flag = std::move(s);
      return *this;
    }
 
    ParameterBuilder& long_flag(String&& s)
    {
      _core->long_flag = std::move(s);
      return *this;
    }
 
    ParameterBuilder& env(String&& s)
    {
      _core->environment_variable = std::move(s);
      return *this;
    }
 
    ParameterBuilder& property(String&& s)
    {
      _core->property_path = std::move(s);
      return *this;
    }
 
    ParameterBuilder& help_string(String&& s)
    {
      s.trim();
      _core->help_string = std::move(s);
      return *this;
    }
 
    ParameterBuilder& placeholder(String&& s)
    {
      _core->placeholder = std::move(s);
      return *this;
    }
 
    ParameterBuilder& name(String&& s)
    {
      _core->custom_name = std::move(s);
      return *this;
    }
 
    ParameterBuilder& parser(T_ (*parser_fn)(const String&))
    {
      // SAFETY:
      // Functions exist for the lifetime of the program.
      // Thus a valid function pointer will never dangle
      // and calling this lambda later is always safe
      const auto lambda = [parser_fn](std::any& any, const String& s) { any = parser_fn(s); };
      _core->parser = lambda;
 
      return *this;
    }
 
    ParameterBuilder& validator(void (*validator_fn)(const T_&))
    {
      XASSERTM(validator_fn != nullptr, "Validator must be valid function pointer!");
 
      // NOTE:
      // We accept a function pointer here, because it
      // forbids the user from passing us a lambda-expression
      // that captures something from its environment
 
      // SAFETY:
      // Functions exist for the lifetime of the program.
      // Thus a valid function pointer will never dangle
      // and calling this lambda later is always safe
      const auto lambda = [validator_fn](const std::any& any) { validator_fn(std::any_cast<const T_&>(any)); };
      _core->validator = lambda;
 
      return *this;
    }
 
    ParameterBuilder& validator(bool (*validator_fn)(const T_&))
    {
      XASSERTM(validator_fn != nullptr, "Validator must be valid function pointer!");
 
      // NOTE:
      // We accept a function pointer here, because it
      // forbids the user from passing us a lambda-expression
      // that captures something from its environment
 
      // SAFETY:
      // Functions exist for the lifetime of the program.
      // Thus a valid function pointer will never dangle
      // and calling this lambda later is always safe
      const auto lambda = [validator_fn](const std::any& any)
      {
        if(!validator_fn(std::any_cast<const T_&>(any)))
        {
          throw std::invalid_argument("Failed boolean test");
        }
      };
      _core->validator = lambda;
 
      return *this;
    }
 
    ParameterBuilder& required()
    {
      _core->required = true;
 
      return *this;
    }
 
    template<typename U_>
    ParameterBuilder& needs(const Parameter<U_>& parameter)
    {
      XASSERTM(parameter._core != nullptr, "Needed parameter must be defined already!");
 
      _core->needs.emplace_back(parameter._core, [](const std::any& /*unused*/) { return true; });
 
      return *this;
    }
 
    template<typename U_>
    ParameterBuilder& needs_if(const Parameter<U_>& parameter, bool (*condition)(const T_&))
    {
      XASSERTM(parameter._core != nullptr, "Needed parameter must be defined already!");
 
      _core->needs.emplace_back(
        parameter._core,
        [condition](const std::any& value) { return condition(std::any_cast<const T_&>(value)); });
 
      return *this;
    }
 
    // NOTE: This conversion operator exists to convert the ParameterBuilder produced by ArgParser::parameter
    // into a parameter without forcing the user to call an additional function for every parameter.
    // For that reason it is deliberately implicit
    operator Parameter<T_>() // NOLINT
    {
      if(_core->placeholder.empty())
      {
        if(!_core->long_flag.empty())
        {
          _core->placeholder = _core->long_flag.substr(2);
        }
        else if(!_core->short_flag.empty())
        {
          _core->placeholder = _core->short_flag.substr(1);
        }
      }
 
      if(!_core->parser)
      {
        _core->parser = Intern::make_parser<T_>();
      }
      return Parameter<T_>(_core);
    }
  };
 
  class ArgParser
  {
  private:
    std::deque<std::shared_ptr<Intern::ParameterCore>> _parameters;
    std::deque<String> _errors;
 
    String _program{""};
    String _description{""};
 
    static constexpr int priority_default = 0;
    static constexpr int priority_env = 1;
    static constexpr int priority_property = 2;
    static constexpr int priority_cli = 3;
 
  public:
    const std::deque<String>& errors() const
    {
      return _errors;
    }
 
    void set_description(String&& description)
    {
      _description = std::move(description);
    }
 
    [[nodiscard]] String help_text()
    {
      // Sort parameters alphabetically
      std::sort(
        _parameters.begin(),
        _parameters.end(),
        [](auto& a, auto& b) { return a->name().compare_no_case(b->name()) <= 0; });
 
      std::stringstream stream;
 
      if(!_description.empty())
      {
        stream << _description << "\n\n";
      }
      stream << "Usage: " << _program << " [OPTIONS]\n\n";
      stream << "Options:\n";
 
      for(const auto& core : _parameters)
      {
        parameter_help(*core, stream);
      }
 
      return stream.str();
    }
 
    [[nodiscard]] String display()
    {
      // Sort parameters alphabetically
      std::sort(
        _parameters.begin(),
        _parameters.end(),
        [](auto& a, auto& b) { return a->name().compare_no_case(b->name()) <= 0; });
 
      std::stringstream stream;
 
      // Print header
      stream << String("Parameter").pad_back(40, ' ');
      stream << "|";
      stream << String("Source").pad_back(10, ' ');
      stream << "|";
      stream << "Value\n";
      stream << String("").pad_back(75, '-') << "\n";
 
      for(const auto& core : _parameters)
      {
        XASSERT(core->value.has_value());
 
        stream << core->name().pad_back(40, '.');
        stream << "|";
 
        switch(core->priority)
        {
        case priority_default:  stream << "default   |"; break;
        case priority_env:      stream << "env       |"; break;
        case priority_property: stream << "property  |"; break;
        case priority_cli:      stream << "cli       |"; break;
        default:                stream << "          |";
        }
 
        if(core->type == Intern::ParameterType::flag)
        {
          stream << (std::any_cast<const bool&>(core->value) ? "true" : "false");
        }
        else
        {
          XASSERT(bool(core->printer));
          core->printer(stream, core->value);
        }
 
        stream << "\n";
      }
 
      return stream.str();
    }
 
    [[nodiscard]] bool parse(int argc, const char* const* argv, const PropertyMap* property_map = nullptr)
    {
      // Reset errors
      _errors.clear();
 
      if(!_check_for_unique_parameters())
      {
        return false;
      }
 
      // Set default values, reset priorities, clear arguments
      for(auto& core : _parameters)
      {
        core->reset();
      }
 
      // Collect values in environment variables
      _collect_env();
 
      // Collect values in property map
      if(property_map != nullptr)
      {
        _collect_property_map(property_map);
      }
 
      // Collect command line args
      _collect_args(argc, argv);
 
      // Parse collected data types into proper data types
      for(auto& core : _parameters)
      {
        core->parse(_errors);
      }
 
      _validate();
 
      return _errors.empty();
    }
 
    [[nodiscard]] bool parse(const PropertyMap& property_map)
    {
      return parse(0, nullptr, &property_map);
    }
 
    [[nodiscard]] bool parse(int argc, const char* const* argv, const String& property_map_path)
    {
      PropertyMap pmap;
      pmap.read(property_map_path);
      return parse(argc, argv, &pmap);
    }
 
    [[nodiscard]] bool parse(const String& property_map_path)
    {
      PropertyMap pmap;
      pmap.read(property_map_path);
      return parse(0, nullptr, &pmap);
    }
 
  protected:
    template<typename T_>
    ParameterBuilder<T_> parameter(T_&& default_value = T_{})
    {
      // Create type-erased parameter core
      std::shared_ptr<Intern::ParameterCore> core = std::make_shared<Intern::ParameterCore>(std::forward<T_>(default_value));
 
      // Store type-erased core for parsing purposes.
      // This allows the parser to treat all parameters the same,
      // irrespective of the types of their values.
      _parameters.push_back(core);
 
      // Return builder to user for defining the parameter fully
      return ParameterBuilder<T_>(std::move(core));
    }
 
  private:
    bool _check_for_unique_parameters()
    {
      std::set<String> short_flags;
      std::set<String> long_flags;
      std::set<String> environment_variables;
      std::set<String> property_paths;
 
      bool result = true;
 
      auto handle_flag = [&](std::set<String>& set, const String& s)
      {
        if(s.empty())
        {
          return;
        }
 
        if(set.find(s) != set.end())
        {
          _errors.push_back("Error: Flag " + s + " is used by multiple parameters");
          result = false;
        }
        else
        {
          set.insert(s);
        }
      };
 
      for(auto& core : _parameters)
      {
        handle_flag(short_flags, core->short_flag);
        handle_flag(long_flags, core->long_flag);
        handle_flag(environment_variables, core->environment_variable);
        handle_flag(property_paths, core->property_path);
      }
 
      return result;
    }
 
    void _collect_env()
    {
      for(auto& core : _parameters)
      {
        const char* value = std::getenv(core->environment_variable.c_str());
        if(value != nullptr)
        {
          String s(value);
          core->add_argument(s, priority_env);
        }
      }
    }
 
    void _collect_property_map(const PropertyMap* property_map)
    {
      for(auto& core : _parameters)
      {
        auto [string, success] = property_map->query(core->property_path);
        if(success)
        {
          core->add_argument(string, priority_property);
        }
      }
    }
 
    void _collect_args(int argc, const char* const* argv)
    {
      if(argc == 0)
      {
        return;
      }
 
      _program = String(argv[0]);
 
      std::deque<String> args;
 
      for(int i(1); i < argc; i++)
      {
        args.emplace_back(argv[i]);
      }
 
      Index idx(0);
      while(idx < args.size())
      {
        const String& flag = args[idx++];
 
        if(!is_flag(flag))
        {
          XABORTM("Error: Expected flag in position " + stringify(idx));
        }
 
        bool handled = false;
        for(auto& core : _parameters)
        {
          if(flag.compare_no_case(core->short_flag) != 0 && flag.compare_no_case(core->long_flag) != 0)
          {
            continue;
          }
 
          handled = true;
 
          if(core->type == Intern::ParameterType::flag)
          {
            // Flag was given. Invert its state.
            // any_cast is safe because flags must be bool parameters
            core->value = !std::any_cast<const bool&>(core->default_value);
            core->set_by_user = true;
          }
          else if(core->type == Intern::ParameterType::option)
          {
            // Normal option. Consume a single argument
            core->add_argument(args[idx++], priority_cli);
          }
          else if(core->type == Intern::ParameterType::collection_option)
          {
            // Collect arguments until next flag
            while(idx < args.size() && !is_flag(args[idx]))
            {
              core->add_argument(args[idx++], priority_cli);
            }
          }
        }
 
        if(!handled)
        {
          // We found no parameter for this flag. Generate error
          _errors.push_back("Error: Unknown flag " + flag);
 
          // Then advance to next flag
          while(idx < args.size() && !is_flag(args[idx]))
          {
            idx++;
          }
        }
      }
    }
 
    void _validate()
    {
      for(auto& core : _parameters)
      {
        core->validate(_errors);
      }
    }
 
    static void parameter_help(const Intern::ParameterCore& core, std::stringstream& s)
    {
      if(
        core.short_flag.empty() && core.long_flag.empty() && core.property_path.empty() &&
        core.environment_variable.empty())
      {
        return;
      }
 
      s << "\t";
 
      auto format_flag = [&s](Intern::ParameterType type, const String& flag, const String& placeholder)
      {
        if(type == Intern::ParameterType::flag)
        {
          s << flag;
        }
        if(type == Intern::ParameterType::option)
        {
          s << flag << " <" << placeholder << ">";
        }
        if(type == Intern::ParameterType::collection_option)
        {
          s << flag << " <" << placeholder << "s...>";
        }
      };
 
      auto format_other = [&s](const std::string_view prefix, const String& value)
      { s << "[" << prefix << ":" << value << "]"; };
 
      // -a,  --arg, [property:arg], [env:FEAT_ARG]
 
      bool has_prev = false;
      if(!core.short_flag.empty())
      {
        format_flag(core.type, core.short_flag, core.placeholder);
        has_prev = true;
      }
 
      if(!core.long_flag.empty())
      {
        if(has_prev)
        {
          s << ", ";
        }
 
        format_flag(core.type, core.long_flag, core.placeholder);
 
        has_prev = true;
      }
 
      if(!core.property_path.empty())
      {
        if(has_prev)
        {
          s << ", ";
        }
 
        format_other("property", core.property_path);
 
        has_prev = true;
      }
 
      if(!core.environment_variable.empty())
      {
        if(has_prev)
        {
          s << ", ";
        }
 
        format_other("env", core.environment_variable);
 
        has_prev = true;
      }
 
      if(has_prev)
      {
        s << "\n";
      }
 
      if(core.required)
      {
        s << "\t\tRequired argument.\n";
      }
 
      for(const String& line : core.help_string.split_by_charset("\n"))
      {
        s << "\t\t" << line.trim() << "\n";
      }
 
      s << "\n";
    }
 
    static bool is_flag(const String& s)
    {
      return !s.empty() && s[0] == '-';
    }
  };
} // namespace FEAT