Luna/libos/include/os/ArgumentParser.h

/**
 * @file ArgumentParser.h
 * @author apio (cloudapio.eu)
 * @brief Command-line argument parser.
 *
 * @copyright Copyright (c) 2023, the Luna authors.
 *
 */

#pragma once
#include <luna/StringView.h>
#include <luna/Vector.h>

namespace os
{
    /**
     * @brief A simple command-line argument parser.
     */
    class ArgumentParser
    {
      public:
        /**
         * @brief Construct a new ArgumentParser object.
         */
        ArgumentParser();

        /**
         * @brief Add a description for this command-line utility (shown in the help text).
         *
         * @param description The description to use.
         */
        void add_description(StringView description);

        /**
         * @brief Register a new positional argument.
         *
         * @param out The variable where the argument's value will be stored.
         * @param name The positional argument's name.
         * @param fallback The value to use if the user does not provide one.
         * @return Result<void> Whether the operation succeeded.
         */
        Result<void> add_positional_argument(StringView& out, StringView name, StringView fallback);

        /**
         * @brief Register a new positional argument.
         *
         * @param out The variable where the argument's value will be stored.
         * @param name The positional argument's name.
         * @param required Whether the user must enter a value for this argument. If this is false and the user does not
         * enter a value, out will be set to an empty string.
         * @return Result<void> Whether the operation succeeded.
         */
        Result<void> add_positional_argument(StringView& out, StringView name, bool required);

        /**
         * @brief Register a new switch argument.
         *
         * @param out This variable will be set to true if the user provides the switch argument on the command
         * line.
         * @param short_flag The short flag to use for this argument, excluding the '-' prefix: an option '-c' would be
         * passed as 'c'. Can only be a single ASCII character. If you do not wish this argument to have a short flag,
         * use the space character: ' '.
         * @param long_flag The long flag to use for this argument, excluding the '--' prefix: an option '--example'
         * would be passed as 'example'. Can be a string of any length. If you do not wish this argument to have a long
         * flag, use an empty string: "".
         * @param help The help text to show for this argument (optional).
         * @return Result<void> Whether the operation succeeded.
         */
        Result<void> add_switch_argument(bool& out, char short_flag, StringView long_flag, StringView help = {});

        /**
         * @brief Register a new value argument.
         *
         * @param out The variable where the argument's value will be stored.
         * @param short_flag The short flag to use for this argument, excluding the '-' prefix: an option '-c' would be
         * passed as 'c'. Can only be a single ASCII character. If you do not wish this argument to have a short flag,
         * use the space character: ' '.
         * @param long_flag The long flag to use for this argument, excluding the '--' prefix: an option '--example'
         * would be passed as 'example'. Can be a string of any length. If you do not wish this argument to have a long
         * flag, use an empty string: "".
         * @param help The help text to show for this argument (optional).
         * @return Result<void> Whether the operation succeeded.
         */
        Result<void> add_value_argument(StringView& out, char short_flag, StringView long_flag, StringView help = {});

        /**
         * @brief Register a positional argument vector (can be only done once).
         *
         * @param out The vector of StringViews to store arguments in.
         * @param name The name to give to the argument vector (in the help text).
         * @param fallback The value to put in the vector if no values are provided.
         * @param allow_no_more_flags If set, after starting to append values into the vector, no more flags (switch and
         * value arguments) will be parsed, and will instead be treated as regular positional arguments, as if '--' had
         * been specified on the command line.
         */
        Result<void> set_vector_argument(Vector<StringView>& out, StringView name, StringView fallback,
                                         bool allow_no_more_flags = false);

        /**
         * @brief Register a positional argument vector (can be only done once).
         *
         * @param out The vector of StringViews to store arguments in.
         * @param name The name to give to the argument vector (in the help text).
         * @param required Whether the user must enter at least one value for this argument. If this is false and the
         * user does not enter a value, out will be cleared.
         * @param allow_no_more_flags If set, after starting to append values into the vector, no more flags (switch and
         * value arguments) will be parsed, and will instead be treated as regular positional arguments, as if '--' had
         * been specified on the command line.
         */
        Result<void> set_vector_argument(Vector<StringView>& out, StringView name, bool required,
                                         bool allow_no_more_flags = false);

        /**
         * @brief Parse the given command-line using this ArgumentParser's registered arguments.
         *
         * @param argc The argc value passed to main() or luna_main().
         * @param argv The argv value passed to main() or luna_main().
         * @return Result<bool> Whether the operation succeeded, and if the arguments were correctly parsed (only needed
         * if should_exit_on_bad_usage is not set, otherwise the success result would always be true).
         */
        Result<bool> parse(int argc, char* const* argv);

        /**
         * @brief A program's copyright and version information.
         */
        struct ProgramInfo
        {
            StringView name;      // The program's name.
            StringView version;   // The program's version/release.
            StringView copyright; // The program's copyright statement.
            StringView license;   // The program's licensing information.
            StringView authors;   // The program's authors (optional).
            StringView package;   // The package the program is a part of (optional).
        };

        /**
         * @brief Set this program's copyright and version information (shown in the version text).
         *
         * @param info The program information to use.
         */
        void add_program_info(ProgramInfo info);

        /**
         * @brief For programs that are part of the Luna source tree, set the version information using Luna's own
         * version and copyright info and the program name.
         *
         * @param name The program name to show in the version information.
         */
        void add_system_program_info(StringView name);

        /**
         * @brief Show a short message describing how to find usage information (usually "<program> --help").
         *
         * The actual message shown is:
         *  "Try running '<program> --help' for more information." if --help has not been overridden.
         *  "Try running '<program> -h' for more information." if -h has not been overridden.
         *  If both have been overridden, no output is shown.
         *
         * Then, the program exits with a non-zero exit code, if should_exit_on_bad_usage is set.
         * This function is designed to be used when the program detects an invalid argument value after parse() has run
         * successfully.
         *
         * @param program_name The program name to show (usually argv[0]).
         */
        Result<void> short_usage(StringView program_name);

        /**
         * @brief Set whether the parser should exit the program when an incorrect usage is detected.
         *
         * @param b The boolean value to set.
         */
        void set_should_exit_on_bad_usage(bool b)
        {
            m_should_exit_on_bad_usage = b;
        }

      private:
        struct PositionalArgument
        {
            StringView* out;
            StringView name;
            bool required;
            StringView fallback;
        };

        struct SwitchArgument
        {
            bool* out;
            char short_flag;
            StringView long_flag;
            StringView help;
        };

        struct ValueArgument
        {
            StringView* out;
            char short_flag;
            StringView long_flag;
            StringView help;
        };

        Result<void> usage(StringView program_name);

        Result<void> version();

        Vector<PositionalArgument> m_positional_args;
        Vector<SwitchArgument> m_switch_args;
        Vector<ValueArgument> m_value_args;
        Vector<StringView>* m_vector_argument { nullptr };
        bool m_allow_no_more_flags_after_vector_argument_start { false };
        ProgramInfo m_program_info;
        StringView m_description = {};
        bool m_add_short_help_flag { false };
        bool m_add_long_help_flag { false };
        bool m_add_short_version_flag { false };
        bool m_add_long_version_flag { false };
        bool m_should_exit_on_bad_usage { true };
    };
}