Printing Usage

While we're dealing with options at the command line, we might as well address the small bit of functionality regrading printing usage.

I frequently see code which just prints out usage as one large block of text.  There's nothing really wrong with this although it has the small drawback that it can sometimes be a pain to edit on changes and the slightly bigger drawback that it's freeform and can lead to irregular standards of what you might expect when you invoke an application with -?.  It also tends to mean that some text gets repeated by copy/paste within any instance.

It's not that hard to come up with a class for encapsulating a bit of the formatting logic and having a setting model which is a little easier to update.

So without further ado:

namespace JSBUtil

{

class UsagePrinter

{

public:

  class UsageInfo

  {

  public:

    UsageInfo(const char inShortOption, const std::string &inLongOption,

      const std::string &inArgValue, const std::string &inDescription,

      const bool inMandatory):

      m_shortOption(inShortOption),

      m_longOption(inLongOption), m_argValue(inArgValue),

      m_description(inDescription), m_mandatory(inMandatory)

    { }

    void print(std::ostream &outStream) const;

    void printDescription(std::ostream &outStream, const int inOffset) const;

  private:

    char m_shortOption;

    std::string m_longOption;

    std::string m_argValue;

    std::string m_description;

    bool m_mandatory;

  };

  void addUsage(const char inShortOption,

                const std::string &inLongOption, const std::string &inArgValue,

                const std::string &inDescription,

                const bool inMandatory = false);

  void print(std::ostream& outStream, const std::string& inAppName) const;

private:

  std::vector<UsageInfo> m_info;

};

}

inline std::ostream &operator<<(std::ostream &inStream,

                                const JSBUtil::UsagePrinter::UsageInfo &inInfo)

{

  inInfo.print(inStream);

  return inStream;

}

Implementations are:

void UsagePrinter::addUsage(const char inShortOption,

                            const std::string &inLongOption,

                            const std::string &inArgValue,

                            const std::string &inDescription,

                            const bool inMandatory)

{

  m_info.emplace_back(inShortOption, inLongOption, inArgValue, inDescription,

                      inMandatory);

}

void UsagePrinter::UsageInfo::print(std::ostream &outStream) const

{

  if (!m_mandatory)

    outStream << "[ ";

  if (m_shortOption == '\0')

    {

      if (m_longOption.empty())

        outStream << "<" << m_argValue << ">";

      else

        {

          outStream << "--" << m_longOption;

          if (!m_argValue.empty())

            outStream << " <" << m_argValue << ">";

        }

    }

  else

    {

      if (m_longOption.empty())

        {

          outStream << '-' << m_shortOption;

          if (!m_argValue.empty())

            outStream << " <" << m_argValue << ">";

        }

      else

        {

          outStream << '-' << m_shortOption << "| --" << m_longOption;

          if (!m_argValue.empty())

            outStream << " <" << m_argValue << ">";

        }

    }

  if (!m_mandatory) outStream << " ] ";

  else outStream << " ";

}

void UsagePrinter::UsageInfo::printDescription(std::ostream &outStream,

                                               const int inOffset) const

{

  if (m_shortOption == '\0')

    {

      if (!m_longOption.empty())

        outStream << m_longOption << ": ";

    }

  else

    {

      if (m_longOption.empty())

        {

          outStream << m_shortOption << ": ";

        }

      else

        {

          outStream << "Short form: " << m_shortOption

                    << "; Long form: " << m_longOption << ": ";

        }

    }

  if (m_mandatory)

    outStream << " (Mandatory argument)";

  if (!m_argValue.empty())

    {

      if (m_longOption.empty() && (m_shortOption == '\0'))

outStream << "Argument " << inOffset + 1 << ": ";

      outStream << m_argValue;

    }

  outStream << " " << m_description << std::endl;

}


void UsagePrinter::print(std::ostream &outStream,

                         const std::string &inAppName) const

{

  outStream << "Usage: " << inAppName << " ";

  int count = 0;

  std::ranges::for_each(m_info, [&outStream, &count](const auto &inVal) {

    outStream << inVal;

    ++count;

  });

  outStream << "\n";

  std::ranges::for_each(std::ranges::iota_view{ 0, count },

                        [&](const int inVal) {

                          m_info[inVal].printDescription(outStream, inVal);

                        });

}

This is a little finicky, but the details aren't easily reducible.

This gets invoked as:

  JSBUtil::UsagePrinter printer;

  printer.addUsage('\0', "", "Config file", "General configuration file");

  printer.addUsage('?', "", "", "Print this message");

  printer.addUsage('D', "", "Date", "Date in MM-DD format for office date");

  printer.addUsage('O', "", "Office", "Office name (exclusive with -x)");

  printer.addUsage('P', "", "", "Office is said by priest");

  printer.addUsage(

      'e', "", "Easter",

      "Date of Easter in YYYY-MM-DD format (Exclusive with -y option)");

  printer.addUsage('f', "", "Filename", "Output filename");

  printer.addUsage('x', "", "", "Choose office for current time of day");

  printer.addUsage('y', "", "Year", "Year for office");

  printer.print(std::cout, inApp);

which means that the option information is nicely structured and easy to add to, and also that the summary execution line stays in sync with the longer descriptions.

This produces output that looks like:

Usage: ./breviary_app [ <Config file> ] [ -? ] [ -D <Date> ] [ -O <Office> ] [ -P ] [ -e <Easter> ] [ -f <Filename> ] [ -x ] [ -y <Year> ] 

Argument 1: Config file General configuration file

?:  Print this message

D: Date Date in MM-DD format for office date

O: Office Office name (exclusive with -x)

P: Office is said by priest

e: Easter Date of Easter in YYYY-MM-DD format (Exclusive with -y option)

f: Filename Output filename

x: Choose office for current time of day

y: Year Year for office


Comments

Post a Comment

Popular posts from this blog

Boundaries

Imagine that you have a well-designed application, possibly using dependency injection. It will almost always have a very thin layer visible in main() - capturing command-line parameters and environment variables, mainly[1], and then a call to an Application class which manages the rest of the initial logic - setting up resources such as logging, doing substantive validation of parameters, and creating and running the objects on the next level down which actually carry out the work of the application. This is simply following the SRP at a high level.
Read more

State Machines

Almost any program can be modelled as a state machine. I say "almost any" because it is, just, possible to think of a program which cannot easily be resolved into anything more than a one-state state machine. Consider a command interpreter with no support for loops or function definitions (like the old DOS command.com) and with no internal commands, only the ability to execute external commands. It loops forever and does only one thing for every line it reads.    If it does no error handling, the execution is a single line, a call to execve or one of its relatives. There are internal stages inside the C library call, but they are effectively invisible to the program.  However, it's not a very useful program. Neither is any version of HelloWorld. The echo application does have its uses. Once one gets beyond this, even simple programs have at least two states: setup and execute. A simple version of cp has to open two files for input and output before beginning to copy data....
Read more

Considerations on an Optimization

An application – actually, successive pair of applications – is meant to process (in the end) about three hundred or so entries to convert a simple markup into complex LaTeX markup. It also enhances the data with information drawn from a flat-file text database (i.e. literally a set of .txt files in a single directory). This application was originally written in rust, which is not my favourite language, but one worth exercising to a degree. The rust application covered a limited subdomain, and generally avoided unsafe rust code, although in some cases it had to use cell mechanisms which converted compile-time to runtime safety. The initial iteration had the text database as one large file, with some logic allowing for extended seeking through chapters. It soon became apparent, after extending my dataset to about twenty or so items, that this was going to result in an unacceptable runtime — it was taking longer to process than the later TeX processing took, and although in theory this w...
Read more