help_printer.hpp

Go to the documentation of this file.

 
/*
    SPDX-FileCopyrightText: 2026 Igor Mironchik <igor.mironchik@gmail.com>
    SPDX-License-Identifier: MIT
*/
 
#ifndef ARGS__HELP_PRINTER_HPP__INCLUDED
#define ARGS__HELP_PRINTER_HPP__INCLUDED
 
// C++ include.
#include <algorithm>
#include <functional>
#include <vector>
 
// Args include.
#include "cmd_line.hpp"
#include "command.hpp"
#include "exceptions.hpp"
#include "group_iface.hpp"
#include "groups.hpp"
#include "help_printer_iface.hpp"
#include "types.hpp"
#include "utils.hpp"
 
namespace Args
{
 
class CmdLine;
class ArgIface;
 
//
// HelpPrinter
//

class HelpPrinter : public HelpPrinterIface
{
public:
    using ArgPtr = std::unique_ptr<ArgIface, details::Deleter<ArgIface>>;
 
    HelpPrinter();
 
    virtual ~HelpPrinter();

    void print(
        OutStreamType &to) override;

    void print(
        const String &name,
        OutStreamType &to,
        Command *parent = nullptr) override;

    void setExecutable(const String &exe) override;

    void setAppDescription(const String &desc) override;

    void setCmdLine(CmdLine *cmd) override;

    void setLineLength(String::size_type length) override;

    ArgIface *findArgument(const String &name) override
    {
        return m_cmdLine->findArgument(name);
    }
 
private:
    StringList createUsageString(ArgIface *arg,
                                 bool required) const;
    StringList splitToWords(const String &s) const;
    void printString(OutStreamType &to,
                     const StringList &words,
                     String::size_type currentPos,
                     String::size_type leftMargin,
                     String::size_type rightMargin) const;
    void print(ArgIface *arg,
               OutStreamType &to) const;
    void printDefaultValue(ArgIface *arg,
                           OutStreamType &to,
                           String::size_type currentPos,
                           String::size_type leftMargin,
                           String::size_type rightMargin) const;
    void sortArg(const ArgPtr &arg,
                 std::vector<Command *> &commands,
                 std::vector<ArgIface *> &required,
                 std::vector<ArgIface *> &optional,
                 String::size_type &maxFlag,
                 String::size_type &maxName,
                 String::size_type &maxCommand,
                 bool requiredAllOfGroup = false) const;
    void printOnlyFor(ArgIface *arg,
                      OutStreamType &to,
                      String::size_type beforeDescription,
                      String::size_type maxFlag) const;
 
private:
    DISABLE_COPY(HelpPrinter)
 
    
    String m_exeName;
    String m_appDescription;
    CmdLine *m_cmdLine;
    String::size_type m_lineLength;
}; // class HelpPrinter
 
static const String c_positional = SL("[positional]");
 
static const String c_commands = SL("<command>");
 
static const String c_options = SL("<options>");
 
//
// HelpPrinter
//
 
inline HelpPrinter::HelpPrinter()
    : m_cmdLine(0)
    , m_lineLength(79)
{
}
 
inline HelpPrinter::~HelpPrinter()
{
}
 
static inline void printOffset(OutStreamType &to,
                               String::size_type &currentPos,
                               String::size_type leftMargin)
{
    if (currentPos < leftMargin) {
        to << String(leftMargin - currentPos, ' ');
        currentPos = leftMargin;
    }
}
 
static inline void calcMaxFlagAndName(ArgIface *arg,
                                      String::size_type &maxFlag,
                                      String::size_type &maxName)
{
    String::size_type f = 1;
    String::size_type n = (!arg->argumentName().empty() ? arg->argumentName().length()
                                                        : (arg->flag().empty() ? arg->name().length() : 0));
 
    if (arg->isWithValue()) {
        if (n > 0) {
            n += 3 + arg->valueSpecifier().length();
        } else {
            f += 3 + arg->valueSpecifier().length();
        }
    }
 
    if (f > maxFlag) {
        maxFlag = f;
    }
 
    if (n > maxName) {
        maxName = n;
    }
}
 
inline void HelpPrinter::sortArg(const ArgPtr &arg,
                                 std::vector<Command *> &commands,
                                 std::vector<ArgIface *> &required,
                                 std::vector<ArgIface *> &optional,
                                 String::size_type &maxFlag,
                                 String::size_type &maxName,
                                 String::size_type &maxCommand,
                                 bool requiredAllOfGroup) const
{
    GroupIface *g = dynamic_cast<GroupIface *>(arg.get());
 
    if (arg->type() == ArgType::Command) {
        Command *cmd = static_cast<Command *>(arg.get());
 
        commands.push_back(cmd);
 
        String::size_type length = cmd->name().length() + (cmd->isWithValue() ? 3 + cmd->valueSpecifier().length() : 0);
 
        if (length > maxCommand) {
            maxCommand = length;
        }
    } else if (g) {
        if (g->isRequired() && g->type() == ArgType::AllOfGroup) {
            requiredAllOfGroup = true;
        } else {
            requiredAllOfGroup = false;
        }
 
        auto f = std::bind(&HelpPrinter::sortArg,
                           this,
                           std::placeholders::_1,
                           std::ref(commands),
                           std::ref(required),
                           std::ref(optional),
                           std::ref(maxFlag),
                           std::ref(maxName),
                           std::ref(maxCommand),
                           requiredAllOfGroup);
 
        std::for_each(g->children().cbegin(), g->children().cend(), f);
    } else {
        if (arg->isRequired() || requiredAllOfGroup) {
            required.push_back(arg.get());
        } else {
            optional.push_back(arg.get());
        }
 
        calcMaxFlagAndName(arg.get(), maxFlag, maxName);
    }
}
 
inline void HelpPrinter::printOnlyFor(ArgIface *arg,
                                      OutStreamType &to,
                                      String::size_type beforeDescription,
                                      String::size_type) const
{
    String::size_type pos = 0;
 
    if (!arg->flag().empty()) {
        to << ' ';
        ++pos;
        to << '-' << arg->flag();
        pos += arg->flag().length() + 1;
 
        if (!arg->argumentName().empty()) {
            to << ',';
            ++pos;
        } else if (arg->isWithValue()) {
            to << " <" << arg->valueSpecifier() << '>';
            pos += arg->valueSpecifier().length() + 3;
        }
    } else {
        printOffset(to, pos, 4);
        pos = 4;
    }
 
    if (!arg->argumentName().empty()) {
        to << ' ';
        ++pos;
        to << "--" << arg->argumentName();
        pos += arg->argumentName().length() + 2;
 
        if (arg->isWithValue()) {
            to << " <" << arg->valueSpecifier() << '>';
            pos += arg->valueSpecifier().length() + 3;
        }
    } else if (arg->flag().empty() && arg->argumentName().empty()) {
        to << ' ';
        ++pos;
        to << arg->name();
        pos += arg->name().length();
 
        if (arg->isWithValue()) {
            to << " <" << arg->valueSpecifier() << '>';
            pos += arg->valueSpecifier().length() + 3;
        }
    }
 
    printString(to, splitToWords(arg->description()), pos, beforeDescription, 0);
 
    to << "\n" << "\n";
 
    printDefaultValue(arg, to, 0, beforeDescription, 0);
 
    to.flush();
}
 
namespace details
{
 
template<typename T>
bool argNameLess(const T &a1,
                 const T &a2)
{
    static const Char dash = SL('-');
 
    if (!a1->name().empty() && !a2->name().empty()) {
        if (*(a1->name().cbegin()) != dash && *(a2->name().cbegin()) == dash) {
            return true;
        } else if (*(a1->name().cbegin()) == dash && *(a2->name().cbegin()) != dash) {
            return false;
        } else if (a1->argumentName().empty() && !a2->argumentName().empty()) {
            return true;
        } else if (!a1->argumentName().empty() && a2->argumentName().empty()) {
            return false;
        } else {
            return (a1->name() < a2->name());
        }
    } else {
        return (a1->name() < a2->name());
    }
}
 
} /* namespace details */
 
inline void HelpPrinter::print(OutStreamType &to)
{
    std::vector<ArgIface *> required;
    std::vector<ArgIface *> optional;
    std::vector<Command *> commands;
 
    String::size_type maxFlag = 0;
    String::size_type maxName = 0;
    String::size_type maxCommand = 0;
 
    bool requiredAllOfGroup = false;
 
    auto f = std::bind(&HelpPrinter::sortArg,
                       this,
                       std::placeholders::_1,
                       std::ref(commands),
                       std::ref(required),
                       std::ref(optional),
                       std::ref(maxFlag),
                       std::ref(maxName),
                       std::ref(maxCommand),
                       requiredAllOfGroup);
 
    std::for_each(m_cmdLine->arguments().cbegin(), m_cmdLine->arguments().cend(), f);
 
    // Sort arguments by name.
    std::sort(required.begin(), required.end(), [](const auto &a1, const auto &a2) {
        return details::argNameLess(a1, a2);
    });
 
    std::sort(optional.begin(), optional.end(), [](const auto &a1, const auto &a2) {
        return details::argNameLess(a1, a2);
    });
 
    std::sort(commands.begin(), commands.end(), [](const auto &c1, const auto &c2) {
        return details::argNameLess(c1, c2);
    });
 
    maxFlag += 2;
    maxName += 2;
    maxCommand += 2;
 
    printString(to, splitToWords(m_appDescription), 0, 0, 0);
 
    to << "\n" << "\n";
 
    if (commands.empty()) {
        StringList usage;
 
        usage.push_back(m_exeName);
 
        bool requiredFlag = true;
 
        std::function<void(ArgIface *)> createUsageAndAppend = [&](ArgIface *arg) {
            const StringList words = createUsageString(arg, requiredFlag);
 
            for (const auto &w : details::asConst(words)) {
                usage.push_back(w);
            }
        };
 
        std::for_each(required.cbegin(), required.cend(), createUsageAndAppend);
 
        requiredFlag = false;
 
        std::for_each(optional.cbegin(), optional.cend(), createUsageAndAppend);
 
        to << "USAGE: ";
 
        if (m_cmdLine->parserOptions() & CmdLine::HandlePositionalArguments) {
            usage.push_back(m_cmdLine->positionalDescription().empty() ? c_positional
                                                                       : m_cmdLine->positionalDescription());
        }
 
        printString(to, usage, 7, 7, 1);
 
        to << "\n" << "\n";
    } else {
        StringList usage;
 
        usage.push_back(m_exeName);
        usage.push_back(c_commands);
 
        if (!optional.empty() || !required.empty()) {
            usage.push_back(c_options);
        }
 
        if (m_cmdLine->parserOptions() & CmdLine::HandlePositionalArguments) {
            usage.push_back(m_cmdLine->positionalDescription().empty() ? c_positional
                                                                       : m_cmdLine->positionalDescription());
        }
 
        to << "USAGE: ";
 
        printString(to, usage, 7, 7, 1);
 
        to << "\n" << "\n";
 
        std::for_each(commands.cbegin(), commands.cend(), [&](Command *cmd) {
            String::size_type pos = 2;
 
            to << "  " << cmd->name();
 
            pos += cmd->name().length();
 
            if (cmd->isWithValue()) {
                to << " <" << cmd->valueSpecifier() << ">";
 
                pos += 3 + cmd->valueSpecifier().length();
            }
 
            printString(to, splitToWords(cmd->description()), pos, maxCommand + 1, 0);
 
            to << "\n";
        });
 
        to << "\n";
    }
 
    auto printArg = std::bind(&HelpPrinter::printOnlyFor,
                              this,
                              std::placeholders::_1,
                              std::ref(to),
                              (maxFlag == 1 ? maxName + 6 : (maxName + 6 > maxFlag + 1 ? maxName + 6 : maxFlag + 1)),
                              maxFlag);
 
    if (!required.empty()) {
        to << "REQUIRED:" << "\n";
 
        std::for_each(required.cbegin(), required.cend(), printArg);
    }
 
    if (!optional.empty()) {
        to << "OPTIONAL:" << "\n";
 
        std::for_each(optional.cbegin(), optional.cend(), printArg);
    }
 
    to.flush();
}
 
inline void HelpPrinter::print(const String &name,
                               OutStreamType &to,
                               Command *parent)
{
    auto *arg = (parent ? parent->findChild(name) : m_cmdLine->findArgument(name));
 
    if (parent && !arg) {
        arg = m_cmdLine->findArgument(name);
    }
 
    if (arg && arg->type() == ArgType::Command) {
        Command *cmd = static_cast<Command *>(arg);
 
        // Prepare global arguments.
        std::vector<ArgIface *> grequired;
        std::vector<ArgIface *> goptional;
        std::vector<Command *> gcommands;
 
        String::size_type gmaxFlag = 0;
        String::size_type gmaxName = 0;
        String::size_type gmaxCommand = 0;
 
        bool requiredAllOfGroup = false;
 
        auto gf = std::bind(&HelpPrinter::sortArg,
                            this,
                            std::placeholders::_1,
                            std::ref(gcommands),
                            std::ref(grequired),
                            std::ref(goptional),
                            std::ref(gmaxFlag),
                            std::ref(gmaxName),
                            std::ref(gmaxCommand),
                            requiredAllOfGroup);
 
        std::for_each(m_cmdLine->arguments().cbegin(), m_cmdLine->arguments().cend(), gf);
 
        // Sort global arguments by name.
        std::sort(grequired.begin(), grequired.end(), [](const auto &a1, const auto &a2) {
            return details::argNameLess(a1, a2);
        });
 
        std::sort(goptional.begin(), goptional.end(), [](const auto &a1, const auto &a2) {
            return details::argNameLess(a1, a2);
        });
 
        gmaxFlag += 2;
        gmaxName += 2;
 
        // Prepare arguments of command.
        std::vector<ArgIface *> required;
        std::vector<ArgIface *> optional;
        std::vector<Command *> commands;
 
        String::size_type maxFlag = 0;
        String::size_type maxName = 0;
        String::size_type maxCommand = 0;
 
        requiredAllOfGroup = false;
 
        auto f = std::bind(&HelpPrinter::sortArg,
                           this,
                           std::placeholders::_1,
                           std::ref(commands),
                           std::ref(required),
                           std::ref(optional),
                           std::ref(maxFlag),
                           std::ref(maxName),
                           std::ref(maxCommand),
                           requiredAllOfGroup);
 
        std::for_each(cmd->children().cbegin(), cmd->children().cend(), f);
 
        // Sort arguments by name.
        std::sort(required.begin(), required.end(), [](const auto &a1, const auto &a2) {
            return details::argNameLess(a1, a2);
        });
 
        std::sort(optional.begin(), optional.end(), [](const auto &a1, const auto &a2) {
            return details::argNameLess(a1, a2);
        });
 
        std::sort(commands.begin(), commands.end(), [](const auto &c1, const auto &c2) {
            return details::argNameLess(c1, c2);
        });
 
        maxFlag += 2;
        maxName += 2;
        maxCommand += 2;
 
        // Print.
        printString(to, splitToWords(cmd->longDescription()), 0, 0, 0);
 
        to << "\n\n";
 
        if (commands.empty()) {
            to << "USAGE: " << name;
 
            if (cmd->isWithValue()) {
                to << " <" << cmd->valueSpecifier() << ">";
            }
 
            if (!grequired.empty() || !goptional.empty() || !required.empty() || !optional.empty()) {
                to << " <options>";
            }
 
            to << "\n\n";
        } else {
            to << "USAGE: " << name << " <command>";
 
            if (!optional.empty() || !required.empty()) {
                to << " <options>";
            }
 
            to << "\n\n";
 
            std::for_each(commands.cbegin(), commands.cend(), [&](Command *c) {
                String::size_type pos = 2;
 
                to << "  " << c->name();
 
                pos += c->name().length();
 
                if (c->isWithValue()) {
                    to << " <" << c->valueSpecifier() << ">";
 
                    pos += 3 + c->valueSpecifier().length();
                }
 
                printString(to, splitToWords(c->description()), pos, maxCommand + 1, 0);
 
                to << "\n";
            });
 
            to << "\n";
        }
 
        // Print command's arguments.
        auto printArg =
            std::bind(&HelpPrinter::printOnlyFor,
                      this,
                      std::placeholders::_1,
                      std::ref(to),
                      (maxFlag == 1 ? maxName + 6 : (maxName + 6 > maxFlag + 1 ? maxName + 6 : maxFlag + 1)),
                      maxFlag);
 
        if (!required.empty()) {
            to << "REQUIRED:" << "\n";
 
            std::for_each(required.cbegin(), required.cend(), printArg);
        }
 
        if (!optional.empty()) {
            to << "OPTIONAL:" << "\n";
 
            std::for_each(optional.cbegin(), optional.cend(), printArg);
        }
 
        // Print global arguments.
        if (!grequired.empty() || !goptional.empty()) {
            auto printGlobalArg =
                std::bind(&HelpPrinter::printOnlyFor,
                          this,
                          std::placeholders::_1,
                          std::ref(to),
                          (gmaxFlag == 1 ? gmaxName + 6 : (gmaxName + 6 > gmaxFlag + 1 ? gmaxName + 6 : gmaxFlag + 1)),
                          gmaxFlag);
 
            if (!grequired.empty()) {
                to << "GLOBAL REQUIRED:" << "\n";
 
                std::for_each(grequired.cbegin(), grequired.cend(), printGlobalArg);
            }
 
            if (!goptional.empty()) {
                to << "GLOBAL OPTIONAL:" << "\n";
 
                std::for_each(goptional.cbegin(), goptional.cend(), printGlobalArg);
            }
        }
 
        to.flush();
    } else if (arg) {
        print(arg, to);
    } else {
        print(to);
    }
}
 
inline void HelpPrinter::printDefaultValue(ArgIface *arg,
                                           OutStreamType &to,
                                           String::size_type currentPos,
                                           String::size_type leftMargin,
                                           String::size_type rightMargin) const
{
    if (!arg->defaultValue().empty()) {
        StringList words;
        words.push_back(String("Default"));
        words.push_back(String("value:"));
        words.push_back(arg->defaultValue());
 
        if (arg->valueSpecifier() != SL("arg")) {
            words.push_back(arg->valueSpecifier());
        }
 
        printString(to, words, currentPos, leftMargin, rightMargin);
 
        to << "\n" << "\n";
    }
}
 
inline void HelpPrinter::print(ArgIface *arg,
                               OutStreamType &to) const
{
    StringList usage = createUsageString(arg, arg->isRequired());
 
    to << "USAGE: ";
 
    std::for_each(usage.cbegin(), usage.cend(), [&](const String &s) {
        to << s << ' ';
    });
 
    to << "\n" << "\n";
 
    printString(to, splitToWords(arg->longDescription()), 0, 7, 7);
 
    to << "\n" << "\n";
 
    printDefaultValue(arg, to, 0, 7, 7);
 
    to.flush();
}
 
inline void HelpPrinter::setExecutable(const String &exe)
{
    m_exeName = exe;
}
 
inline void HelpPrinter::setAppDescription(const String &desc)
{
    m_appDescription = desc;
}
 
inline void HelpPrinter::setCmdLine(CmdLine *cmd)
{
    m_cmdLine = cmd;
}
 
inline void HelpPrinter::setLineLength(String::size_type length)
{
    if (length > 40) {
        m_lineLength = length;
    } else {
        m_lineLength = 40;
    }
}
 
inline StringList HelpPrinter::createUsageString(ArgIface *arg,
                                                 bool required) const
{
    StringList result;
 
    String usage;
 
    if (!required) {
        usage.append(SL("[ "));
    }
 
    if (!arg->flag().empty()) {
        usage.append(SL("-"));
        usage.append(arg->flag());
 
        if (!arg->argumentName().empty()) {
            usage.append(SL(","));
 
            result.push_back(usage);
 
            usage.clear();
        }
    }
 
    if (!arg->argumentName().empty()) {
        usage.append(SL("--"));
        usage.append(arg->argumentName());
    } else if (arg->flag().empty() && arg->argumentName().empty()) {
        usage.append(arg->name());
    }
 
    if (arg->isWithValue()) {
        usage.append(SL(" <"));
        usage.append(arg->valueSpecifier());
        usage.append(SL(">"));
    }
 
    if (!required) {
        usage.append(SL(" ]"));
    }
 
    result.push_back(usage);
 
    return result;
}
 
static inline bool isSpaceChar(const Char &c)
{
    static const String spaceChars = SL(" \t");
 
    return (spaceChars.find(c) != String::npos);
}
 
inline StringList HelpPrinter::splitToWords(const String &s) const
{
    String word;
    StringList result;
 
    const auto pushWord = [&word, &result]() {
        if (!word.empty()) {
            result.push_back(word);
        }
 
        word.clear();
    };
 
    std::for_each(s.cbegin(), s.cend(), [&](const Char &c) {
        if (isSpaceChar(c)) {
            pushWord();
        } else {
            if (c == '\n') {
                pushWord();
 
                result.push_back(String(1, c));
            } else {
                word.append(1, c);
            }
        }
    });
 
    pushWord();
 
    return result;
}
 
inline void HelpPrinter::printString(OutStreamType &to,
                                     const StringList &words,
                                     String::size_type currentPos,
                                     String::size_type leftMargin,
                                     String::size_type rightMargin) const
{
    String::size_type maxLineLength = (rightMargin < m_lineLength ? m_lineLength - rightMargin : 0);
 
    if (maxLineLength - leftMargin < 20) {
        to << "\n\n";
 
        maxLineLength = m_lineLength;
 
        currentPos = 0;
        leftMargin = 20;
        rightMargin = 0;
    }
 
    String::size_type length = 0;
 
    bool makeOffset = (currentPos < leftMargin);
 
    const auto moveToNewLine = [&]() {
        currentPos = 0;
 
        to << "\n";
 
        printOffset(to, currentPos, leftMargin);
 
        length = leftMargin;
    };
 
    std::function<void(const String &)> printWord;
 
    printWord = [&](const String &word) {
        const auto print = [&]() {
            length += word.length();
 
            to << word;
 
            if (length < maxLineLength) {
                ++length;
                to << ' ';
            }
        };
 
        if (length + word.length() < maxLineLength) {
            print();
        } else {
            if (length != leftMargin) {
                moveToNewLine();
            }
 
            const auto available = maxLineLength - length;
 
            if (available < word.length()) {
                to << word.substr(0, available);
                length += available;
 
                printWord(word.substr(available));
            } else {
                print();
            }
        }
    };
 
    std::for_each(words.cbegin(), words.cend(), [&](const String &word) {
        if (makeOffset) {
            printOffset(to, currentPos, leftMargin);
 
            length = leftMargin;
 
            makeOffset = false;
        }
 
        if (word == "\n") {
            moveToNewLine();
            moveToNewLine();
        } else {
            printWord(word);
        }
    });
}
 
} /* namespace Args */
 
#endif // ARGS__HELP_PRINTER_HPP__INCLUDED