usage_writer.h

Go to the documentation of this file.

#ifndef OOKII_USAGE_WRITER_H_
#define OOKII_USAGE_WRITER_H_
 
#pragma once
 
#include "string_helper.h"
#include "line_wrapping_stream.h"
#include "scope_helper.h"
 
namespace ookii
{
    template<typename CharType, typename Traits, typename Alloc>
    class basic_command_line_parser;
 
    template<typename CharType, typename Traits, typename Alloc>
    class basic_command_manager;
 
    template<typename CharType, typename Traits, typename Alloc>
    class command_info;
 
 
    enum class usage_help_request
    {
        full,
        syntax_only,
        none
    };
 
    enum class description_list_filter_mode
    {
        information,
        descripion,
        all,
        none,
    };
 
    enum class description_list_sort_mode
    {
        usage_order,
        alphabetical,
        alphabetical_descending,
        alphabetical_short_name,
        alphabetical_short_name_descending
    };
 
    template<typename CharType, typename Traits = std::char_traits<CharType>, typename Alloc = std::allocator<CharType>>
    class basic_usage_writer
    {
        using line_wrapping_stream_type = basic_line_wrapping_ostream<CharType, Traits>;
 
        std::optional<line_wrapping_stream_type> _owned_output;
        std::optional<line_wrapping_stream_type> _owned_error;
 
    public:
        struct defaults
        {
            static constexpr auto name_separator = literal_cast<CharType>(", ");
            static constexpr size_t application_description_indent = 0;
            static constexpr size_t syntax_indent = 3;
            static constexpr size_t argument_description_indent = 8;
            static constexpr size_t command_description_indent = 8;
        };
 
        using string_type = std::basic_string<CharType, Traits, Alloc>;
        using string_view_type = std::basic_string_view<CharType, Traits>;
        using stream_type = std::basic_ostream<CharType, Traits>;
        using parser_type = basic_command_line_parser<CharType, Traits, Alloc>;
        using argument_type = command_line_argument_base<CharType, Traits, Alloc>;
        using command_manager_type = basic_command_manager<CharType, Traits, Alloc>;
        using command_info_type = command_info<CharType, Traits, Alloc>;
 
        basic_usage_writer(std::optional<bool> use_color = {})
            : _owned_output{line_wrapping_stream_type::for_cout()},
              _owned_error{line_wrapping_stream_type::for_cerr()},
              output{*_owned_output},
              error{*_owned_error},
              _use_color{use_color}
        {
        }
 
        basic_usage_writer(stream_type &output, bool use_color = false)
            : output{output},
              error{output},
              _use_color{use_color}
        {
        }
 
        basic_usage_writer(stream_type &output, stream_type &error, bool use_color = false)
            : output{output},
              error{error},
              _use_color{use_color}
        {
        }
 
        virtual ~basic_usage_writer()
        {
        }
 
        stream_type &output;
 
        stream_type &error;
 
        size_t application_description_indent{defaults::application_description_indent};
 
        size_t syntax_indent{defaults::syntax_indent};
 
        size_t argument_description_indent{defaults::argument_description_indent};
 
        description_list_filter_mode argument_description_list_filter{};
 
        description_list_sort_mode argument_description_list_order{};
 
        bool use_white_space_value_separator{true};
 
        bool include_application_description{true};
 
        bool include_default_value_in_description{true};
 
        bool include_aliases_in_description{true};
 
        bool use_abbreviated_syntax{};
 
        bool blank_line_after_syntax{true};
 
        bool use_short_names_for_syntax{};
 
        bool blank_line_after_description{true};
 
        string_type name_separator{defaults::name_separator.data()};
 
        int command_description_indent{defaults::command_description_indent};
 
        bool blank_line_after_command_description{true};
 
        const char *usage_prefix_color{vt::text_format::foreground_cyan};
 
        const char *argument_description_color{vt::text_format::foreground_green};
 
        const char *command_description_color{vt::text_format::foreground_green};
 
        const char *error_color{vt::text_format::foreground_red};
 
        const char *color_reset{vt::text_format::default_format};
 
        virtual void write_parser_usage(const parser_type &parser, usage_help_request request = usage_help_request::full)
        {
            _parser = &parser;
            write_usage_internal(parser.locale(), request);
        }
 
        virtual void write_command_list_usage(const command_manager_type &manager)
        {
            _command_manager = &manager;
            write_usage_internal(manager.locale());
        }
 
        void write_error(string_view_type message)
        {
            auto support = enable_error_color();
            if (support)
            {
                error << error_color;
            }
 
            error << message;
            if (support)
            {
                error << color_reset;
            }
 
            error << std::endl << std::endl;
        }
 
    protected:
        virtual void write_parser_usage_core(usage_help_request request)
        {
            if (request == usage_help_request::none)
            {
                write_more_info_message();
                return;
            }
 
            if (request == usage_help_request::full && include_application_description && !parser().description().empty())
            {
                write_application_description(parser().description());
            }
 
            write_parser_usage_syntax();
            if (request == usage_help_request::full)
            {
                write_argument_descriptions();
            }
            else
            {
                output << reset_indent << set_indent(0);
                write_more_info_message();
            }
        }
 
        virtual void write_application_description(string_view_type description)
        {
            output << set_indent(application_description_indent);
            output << description << std::endl << std::endl;
        }
 
        virtual void write_parser_usage_syntax()
        {
            output << reset_indent << set_indent(syntax_indent);
            write_usage_syntax_prefix(parser().command_name());
            for (const auto &arg : parser().arguments())
            {
                output << ' ';
                if (use_abbreviated_syntax && !arg.position())
                {
                    write_abbreviated_remaining_arguments();
                    break;
                }
 
                if (arg.is_required())
                {
                    write_argument_syntax(arg);
                }
                else
                {
                    write_optional_argument_syntax(arg);
                }
            }
 
            output << std::endl;
            if (blank_line_after_syntax)
            {
                output << std::endl;
            }
        }
 
        virtual void write_usage_syntax_prefix(string_view_type command_name)
        {
            set_color(usage_prefix_color);
            output << "Usage:";
            set_color(color_reset);
            output << " " << command_name;
        }
 
        virtual void write_abbreviated_remaining_arguments()
        {
            output << "[arguments]";
        }
 
        virtual void write_optional_argument_syntax(const argument_type &arg)
        {
            output << c_optionalStart;
            write_argument_syntax(arg);
            output << c_optionalEnd;
        }
 
        virtual void write_argument_syntax(const argument_type &arg)
        {
            string_view_type name;
            CharType short_name;
            if (arg.has_short_name() && use_short_names_for_syntax)
            {
                short_name = arg.short_name();
                name = string_view_type(&short_name, 1);
            }
            else
            {
                name = arg.name();
            }
 
            const auto &prefix = parser().mode() != parsing_mode::long_short || (arg.has_short_name() && (use_short_names_for_syntax || !arg.has_long_name()))
                ? parser().prefixes()[0]
                : parser().long_prefix();
 
            std::optional<CharType> separator = parser().allow_white_space_separator() && use_white_space_value_separator
                ? std::nullopt
                : std::optional<CharType>(parser().argument_value_separator());
 
            if (arg.position())
            {
                write_positional_argument_name(name, prefix, separator);
            }
            else
            {
                write_argument_name(name, prefix);
            }
 
            if (!arg.is_switch())
            {
                // Otherwise, the separator was included in the argument name.
                if (!arg.position() || !separator)
                {
                    if (separator)
                    {
                        output << *separator;
                    }
                    else
                    {
                        output << ' ';
                    }
                }
 
                write_value_description(arg.value_description());
            }
 
            if (arg.is_multi_value())
            {
                write_multi_value_suffix();
            }
        }
 
        virtual void write_argument_name(string_view_type name, string_view_type prefix)
        {
            output << prefix << name;
        }
 
        virtual void write_positional_argument_name(string_view_type name, string_view_type prefix, std::optional<CharType> separator)
        {
            output << c_optionalStart;
            write_argument_name(name, prefix);
            if (separator)
            {
                output << *separator;
            }
 
            output << c_optionalEnd;
        }
 
        virtual void write_value_description(string_view_type value_description)
        {
            output << '<' << value_description << '>';
        }
 
        virtual void write_multi_value_suffix()
        {
            output << "...";
        }
 
        virtual void write_argument_descriptions()
        {
            auto indent = argument_description_indent;
            if (parser().mode() == parsing_mode::long_short)
            {
                // For long/short mode, increase the indentation by the size of the short argument.
                indent += parser().prefixes()[0].length() + name_separator.length() + 1;
            }
 
            output << set_indent(indent);
            bool first = true;
            for_each_argument_in_description_order([this, &first](const auto &arg)
                {
                    if (first)
                    {
                        write_argument_description_list_header();
                        first = false;
                    }
 
                    write_argument_description(arg);
 
                    return true;
                });
        }
 
        virtual void write_argument_description_list_header()
        {
            // Intentionally blank.
        }
 
        virtual void write_argument_description(const argument_type &arg)
        {
            write_argument_description_header(arg);
            write_argument_description_body(arg);
 
            if (blank_line_after_description)
            {
                output << std::endl;
            }
        }
 
        virtual void write_argument_description_header(const argument_type &arg)
        {
            output << reset_indent;
            write_spacing(argument_description_indent / 2);
            const auto &short_prefix = parser().prefixes()[0];
            const auto &prefix = parser().long_prefix().length() == 0
                ? short_prefix
                : parser().long_prefix();
 
            set_color(argument_description_color);
            if (parser().mode() == parsing_mode::long_short)
            {
                if (arg.has_short_name())
                {
                    auto short_name = arg.short_name();
                    write_argument_name_for_description(string_view_type{&short_name, 1}, short_prefix);
                    if (arg.has_long_name())
                    {
                        output << name_separator;
                    }
                }
                else
                {
                    write_spacing(short_prefix.length() + name_separator.length() + 1);
                }
 
                if (arg.has_long_name())
                {
                    write_argument_name_for_description(arg.name(), prefix);
                }
            }
            else
            {
                write_argument_name_for_description(arg.name(), prefix);
            }
 
            output << ' ';
            if (arg.is_switch())
            {
                write_switch_value_description(arg.value_description());
            }
            else
            {
                write_value_description_for_description(arg.value_description());
            }
 
            if (include_aliases_in_description)
            {
                write_aliases(arg.aliases(), arg.short_aliases(), prefix, short_prefix);
            }
 
            set_color(color_reset);
            output << std::endl;
        }
 
        virtual void write_argument_description_body(const argument_type &arg)
        {
            if (!arg.description().empty())
            {
                write_argument_description(arg.description());
            }
 
            if (include_default_value_in_description && arg.has_default_value())
            {
                write_default_value(arg);
            }
 
            output << std::endl;
        }
 
        virtual void write_argument_name_for_description(string_view_type name, string_view_type prefix)
        {
            output << prefix << name;
        }
 
        virtual void write_value_description_for_description(string_view_type value_description)
        {
            output << '<' << value_description << '>';
        }
 
        virtual void write_switch_value_description(string_view_type value_description)
        {
            output << c_optionalStart;
            write_value_description_for_description(value_description);
            output << c_optionalEnd;
        }
 
        virtual void write_aliases(const std::vector<string_type> &aliases, const std::vector<CharType> &short_aliases,
            string_view_type prefix, string_view_type short_prefix)
        {
            bool first = true;
            for (const auto &alias : short_aliases)
            {
                if (first)
                {
                    output << " (";
                    first = false;
                }
                else
                {
                    output << name_separator;
                }
 
                write_alias(string_view_type{&alias, 1}, short_prefix);
            }
 
            for (const auto &alias : aliases)
            {
                if (first)
                {
                    output << " (";
                    first = false;
                }
                else
                {
                    output << name_separator;
                }
 
                write_alias(alias, prefix);
            }
 
            if (!first)
            {
                output << ")";
            }
        }
 
        virtual void write_alias(string_view_type alias, string_view_type prefix)
        {
            write_argument_name_for_description(alias, prefix);
        }
 
        virtual void write_argument_description(string_view_type description)
        {
            output << description;
        }
 
        virtual void write_default_value(const argument_type &arg)
        {
            output << " Default value: ";
            arg.write_default_value(output);
            output << '.';
        }
 
        virtual void write_more_info_message()
        {
            auto arg = parser().get_help_argument();
            if (arg != nullptr)
            {
                output << "Run '" << parser().command_name() << " " << arg->name_with_prefix(parser()) << "' for more information."
                    << std::endl;
            }
        }
 
        virtual void write_command_list_usage_core()
        {
            if (!command_manager().description().empty())
            {
                write_application_description(command_manager().description());
            }
 
            output << reset_indent << set_indent(syntax_indent);
            write_command_list_usage_syntax();
            output << reset_indent << set_indent(0);
            write_available_commands_header();
            write_command_descriptions();
            output << reset_indent << set_indent(0);
            write_command_list_usage_footer();
        }
 
        virtual void write_command_list_usage_syntax()
        {
            write_usage_syntax_prefix(command_manager().application_name());
            output << " <command> [arguments]" << std::endl;
            if (blank_line_after_syntax)
            {
                output << std::endl;
            }
        }
 
        virtual void write_available_commands_header()
        {
            output << "The following commands are available:" << std::endl << std::endl;
        }
 
        virtual void write_command_descriptions()
        {
            output << set_indent(command_description_indent);
            for (const auto &command : command_manager().commands())
            {
                write_command_description(command);
            }
        }
 
        virtual void write_command_description(const command_info_type &command)
        {
            write_command_description_header(command);
            write_command_description_body(command);
 
            if (blank_line_after_command_description)
            {
                output << std::endl;
            }
        }
 
        virtual void write_command_description_header(const command_info_type &command)
        {
            output << reset_indent;
            write_spacing(command_description_indent / 2);
            set_color(command_description_color);
            write_command_name(command.name());
            set_color(color_reset);
            output << std::endl;
        }
 
        virtual void write_command_description_body(const command_info_type &command)
        {
            if (!command.description().empty())
            {
                write_command_description(command.description());
                output << std::endl;
            }
        }
 
        virtual void write_command_name(string_view_type name)
        {
            output << name;
        }
 
        virtual void write_command_description(string_view_type description)
        {
            output << description;
        }
 
        virtual void write_command_list_usage_footer()
        {
            if (!command_manager().common_help_argument().empty())
            {
                // If there wasn't already a blank line after the last command, add one now.
                if (!blank_line_after_command_description)
                {
                    output << std::endl;
                }
 
                output << "Run '" << command_manager().application_name() << " <command> " <<
                    command_manager().common_help_argument() << "' for more information about a command." << std::endl;
            }
        }
 
        virtual void write_spacing(size_t count)
        {
            for (size_t i = 0; i < count; ++i)
            {
                output << ' ';
            }
        }
 
        const parser_type &parser() const
        {
            return *_parser;
        }
 
        const command_manager_type &command_manager() const
        {
            return *_command_manager;
        }
 
        bool use_color() const
        {
            return _use_color && *_use_color;
        }
 
        void set_color(const char *color)
        {
            if (use_color())
            {
                output << color;
            }
        }
 
        template<typename Func>
        void for_each_argument_in_description_order(Func f) const
        {
            if (argument_description_list_filter == description_list_filter_mode::none)
            {
                return;
            }
 
            if (argument_description_list_order == description_list_sort_mode::usage_order)
            {
                for (const auto &arg : parser().arguments())
                {
                    if (check_filter(arg))
                    {
                        f(arg);
                    }
                }
 
                return;
            }
 
            std::vector<const argument_type *> arguments;
            arguments.reserve(parser().argument_count());
            auto source = parser().arguments();
            std::transform(source.begin(), source.end(), std::back_inserter(arguments), [](const auto &arg) { return &arg; });
            std::sort(arguments.begin(), arguments.end(), get_sort_function());
            for (const auto &arg : arguments)
            {
                if (check_filter(*arg))
                {
                    f(*arg);
                }
            }
        }
 
    private:
 
        bool check_filter(const argument_type &arg) const
        {
            switch (argument_description_list_filter)
            {
            case description_list_filter_mode::information:
                return has_information(arg);
 
            case description_list_filter_mode::descripion:
                return !arg.description().empty();
 
            case description_list_filter_mode::all:
                return true;
 
            default:
                return false;
            }
        }
 
        bool has_information(const argument_type &arg) const
        {
            if (!arg.description().empty())
            {
                return true;
            }
 
            if (use_abbreviated_syntax && arg.position())
            {
                return true;
            }
 
            if (parser().mode() == parsing_mode::long_short && use_short_names_for_syntax)
            {
                if (arg.has_long_name())
                {
                    return true;
                }
            }
            else if (arg.has_short_name())
            {
                return true;
            }
 
            if (include_aliases_in_description && (!arg.aliases().empty() || !arg.short_aliases().empty()))
            {
                return true;
            }
 
            if (include_default_value_in_description && arg.has_default_value())
            {
                return true;
            }
 
            return false;
        }
 
        std::function<bool(const argument_type *, const argument_type *)> get_sort_function() const
        {
            auto comparer = parser().argument_comparer();
            switch (argument_description_list_order)
            {
            case description_list_sort_mode::alphabetical:
                return [comparer](const argument_type *left, const argument_type *right)
                {
                    return comparer(left->name(), right->name());
                };
 
            case description_list_sort_mode::alphabetical_descending:
                return [comparer](const argument_type *left, const argument_type *right)
                {
                    return comparer(right->name(), left->name());
                };
 
            case description_list_sort_mode::alphabetical_short_name:
                return [comparer](const argument_type *left, const argument_type *right)
                {
                    return comparer(left->short_or_long_name(), right->short_or_long_name());
                };
 
            case description_list_sort_mode::alphabetical_short_name_descending:
                return [comparer](const argument_type *left, const argument_type *right)
                {
                    return comparer(right->short_or_long_name(), left->short_or_long_name());
                };
 
            default:
                throw std::logic_error("Invalid sort mode.");
            }
        }
 
        void write_usage_internal(const std::locale &loc, usage_help_request request = usage_help_request::full)
        {
            auto old_output_loc = output.imbue(loc);
            std::optional<std::locale> old_error_loc;
            details::scope_exit revert{[this, &old_output_loc, &old_error_loc]()
                {
                    _parser = nullptr;
                    if (old_error_loc)
                    {
                        error.imbue(*old_error_loc);
                    }
 
                    output.imbue(old_output_loc);
                }
            };
 
            if (std::addressof(output) != std::addressof(error))
            {
                old_error_loc = error.imbue(loc);
            }
 
            auto color = enable_color();
            output << set_indent(0) << reset_indent;
            if (_parser != nullptr)
            {
                write_parser_usage_core(request);
            }
            else
            {
                write_command_list_usage_core();
            }
        }
 
        vt::virtual_terminal_support enable_color()
        {
            if (!_use_color)
            {
                auto support = vt::virtual_terminal_support::enable_color(standard_stream::output);
                _use_color = support.is_supported();
                return support;
            }
 
            return {};
        }
 
        vt::virtual_terminal_support enable_error_color()
        {
            if (!_use_color)
            {
                return vt::virtual_terminal_support::enable_color(standard_stream::error);
            }
 
            return {};
        }
 
        const parser_type *_parser{};
        const command_manager_type *_command_manager{};
        std::optional<bool> _use_color;
 
        static constexpr char c_optionalStart = '[';
        static constexpr char c_optionalEnd = ']';
    };
 
    using usage_writer = basic_usage_writer<char>;
    using wusage_writer = basic_usage_writer<wchar_t>;
 
}
 
#endif