rnr::cmd::addons Namespace Reference

Add-Ons. More...

Enumerations
enum	HelpSect {   HelpSectAll,   HelpSectName,   HelpSectBrief,   HelpSectUsage }
	Command help section identifiers. More...

Functions
int	printCmdHelp (std::ostream &os, const CmdDef &cmddef, const HelpSect section=HelpSectAll)
	Print help for a command convenience function. More...
int	printCmdHelp (std::ostream &os, const CmdDesc &desc, const HelpSect section=HelpSectAll)
	Print help for a command convenience function. More...
int	printCmdHelp (std::ostream &os, const std::string &strName, const std::string &strSyntax, const std::string &strSynopsis, const std::string &strLongDesc, const HelpSect section=HelpSectAll)
	Print help for a command convenience function. More...
int	addHelpCommand (CommandLine &cli, const std::string &strName="help")
	Add the core 'help' command to the command-line interface. More...
int	addQuitCommand (CommandLine &cli, const std::string &strName="quit")
	Add the core 'quit' command to the command-line interface. More...
int	addBtEnableCommand (CommandLine &cli, const std::string &strName="bt")
	Add the core 'bt' command to the command-line interface. More...
static string	atname ("@N@")
	string to replace by command name
static int	execHelp (CommandLine &cli, const CmdExtArgVec &argv)
	Execute 'help' command. More...
int	printCmdHelp (ostream &os, const CmdDef &cmddef, const HelpSect section)
int	printCmdHelp (ostream &os, const CmdDesc &desc, const HelpSect section)
int	printCmdHelp (ostream &os, const string &strName, const string &strSyntax, const string &strSynopsis, const string &strLongDesc, const HelpSect section)
int	addHelpCommand (CommandLine &cli, const string &strName)
static int	execQuit (CommandLine &cli, const CmdExtArgVec &argv)
	Execute 'quit' command. More...
int	addQuitCommand (CommandLine &cli, const string &strName)
static int	execBtEnable (CommandLine &cli, const CmdExtArgVec &argv)
	Execute 'backtrace' command. More...
int	addBtEnableCommand (CommandLine &cli, const string &strName)

Detailed Description

Add-Ons.

Enumeration Type Documentation

enum rnr::cmd::addons::HelpSect

Command help section identifiers.

Enumerator
HelpSectAll	all commond help sections
HelpSectName	command name help section
HelpSectBrief	command brief description help section
HelpSectUsage	command usage (synopsis) help section

Definition at line 95 of file CmdAddOns.h.

      {
        HelpSectAll,    ///< all commond help sections
        HelpSectName,   ///< command name help section
        HelpSectBrief,  ///< command brief description help section
        HelpSectUsage   ///< command usage (synopsis) help section
      };

Function Documentation

int rnr::cmd::addons::addBtEnableCommand	(	CommandLine &	cli,
		const std::string &	strName = "bt"
	)

Add the core 'bt' command to the command-line interface.

Syntax: bt <onoff>

The bt command enables/disables backtracing of input line parsing. The trace is written to cerr.

Any relevant command data is applied to the command line interface "core" data section.

The name of the command may be overridded, but the syntax and semantics cannot.

Parameters

cli	Command-line interface.
strName	Name of the command.

Returns

On success, returns command's assigned unique id. Otherwise NoUid is returned.

Referenced by execBtEnable(), and loadCommands().

int rnr::cmd::addons::addHelpCommand	(	CommandLine &	cli,
		const std::string &	strName = "help"
	)

Add the core 'help' command to the command-line interface.

Syntax: help [{–brief | -b | –list | -l | –usage | -u}] [<cmd>]

The help command will print help for the given help sections for the given command names to cout.

Any relevant command data is applied to the command line interface "core" data section.

The name of the command may be overridded, but the syntax and semantics cannot.

Parameters

cli	Command-line interface.
strName	Name of the command.

Returns

On success, returns command's assigned unique id. Otherwise NoUid is returned.

Referenced by loadCommands(), and printCmdHelp().

int rnr::cmd::addons::addQuitCommand	(	CommandLine &	cli,
		const std::string &	strName = "quit"
	)

Add the core 'quit' command to the command-line interface.

Syntax: quit

The quit command will disable anymore execution of the command line. It is up to the application to terminate by querying the command line ok() method.

Any relevant command data is applied to the command line interface "core" data section.

The name of the command may be overridded, but the syntax and semantics cannot.

Parameters

cli	Command-line interface.
strName	Name of the command.

Returns

On success, returns command's assigned unique id. Otherwise NoUid is returned.

Referenced by execQuit(), and loadCommands().

static int rnr::cmd::addons::execBtEnable ( CommandLine &  cli, const CmdExtArgVec &  argv  )

static

Execute 'backtrace' command.

Syntax:

bt <onoff>

Parameters

cli	Command line interface.
argv	Extended command line arguments.

Returns

OK(0) on success, negative value on failure.

Definition at line 474 of file CmdAddOns.cxx.

References addBtEnableCommand(), rnr::cmd::CommandLine::addCommand(), atname(), rnr::cmd::CmdDesc::name, rnr::str::replace(), and rnr::cmd::CommandLine::setBtEnable().

      {
        cli.setBtEnable(argv[1].b());
        return OK;
      }

static int rnr::cmd::addons::execHelp ( CommandLine &  cli, const CmdExtArgVec &  argv  )

static

Execute 'help' command.

Syntax:

help [{–list | -l | –synopsis | -s | –usage | -u}] [<cmd>]

Todo:

Support ellipses ... syntax.

Parameters

cli	Command line interface.
argv	Extended command line arguments.

Returns

OK(0) on success, negative value on failure.

Definition at line 114 of file CmdAddOns.cxx.

References rnr::cmd::CommandLine::at(), rnr::cmd::CommandLine::begin(), rnr::cmd::CommandLine::end(), rnr::cmd::CmdDef::getLongDesc(), rnr::cmd::CmdDef::getName(), rnr::cmd::CmdDef::getSynopsis(), rnr::cmd::CmdDef::getSyntax(), rnr::cmd::CmdDef::getUid(), HelpSectAll, HelpSectBrief, HelpSectName, HelpSectUsage, rnr::cmd::CmdDesc::longdesc, rnr::cmd::CmdDesc::name, rnr::cmd::NoUid, printCmdHelp(), rnr::cmd::CmdDesc::synopsis, and rnr::cmd::CmdDesc::syntax.

Referenced by printCmdHelp().

      {
        HelpSect section = HelpSectAll;         // default help option
  
        std::set<string>            setOfCmds;  // set of commands for help
        std::set<string>::iterator  iterHelp;   // help commands iterator
        size_t                      i;
      
        //
        // Process Input arguments.
        //
        for(i = 1; i < argv.size(); ++i)
        {
          if( (argv[i] == "--brief") || (argv[i] == "-b") )
          {
            section = HelpSectBrief;
          }
          else if( (argv[i] == "--list") || (argv[i] == "-l") )
          {
            section = HelpSectName;
          }
          else if( (argv[i] == "--usage") || (argv[i] == "-u") )
          {
            section = HelpSectUsage;
          }
          else
          {
            setOfCmds.insert(argv[i].s());
          }
        }
      
        //
        // All commands.
        //
        if( setOfCmds.empty() )
        {
          CmdDefCIter iterDefs;
  
          // alphbetize
          for(iterDefs = cli.begin(); iterDefs != cli.end(); ++iterDefs)
          {
            setOfCmds.insert(iterDefs->second.getName());
          }
        }
  
        //
        // Print help for command(s).
        //
        for(iterHelp = setOfCmds.begin();
            iterHelp != setOfCmds.end();
            ++iterHelp)
        {
          const string &cmdName = *iterHelp;
          const CmdDef &cmdDef  = cli.at(cmdName);
  
          if( cmdDef.getUid() == NoUid )
          {
            cout << "Error: help: No help for command '" << cmdName << "'."
              << endl;
            return RC_ERROR;
          }
  
          printCmdHelp(cout, cmdDef, section);
  
          switch( section )
          {
            case HelpSectName:
              cout << " ";
              break;
            case HelpSectBrief:
            case HelpSectUsage:
              cout << endl;
              break;
            case HelpSectAll:
            default:
              cout << "    ---" << endl << endl;
              break;
          }
        }
  
        switch( section )
        {
          case HelpSectName:
            cout << endl;
            break;
          case HelpSectBrief:
          case HelpSectUsage:
          case HelpSectAll:
          default:
            cout << "  " << setOfCmds.size() << " commands" << endl;
            break;
        }
      
        return OK;
      }

static int rnr::cmd::addons::execQuit ( CommandLine &  cli, const CmdExtArgVec &  argv  )

static

Execute 'quit' command.

Syntax:

quit

Parameters

cli	Command line interface.
argv	Extended command line arguments.

Returns

OK(0) on success, negative value on failure.

Definition at line 428 of file CmdAddOns.cxx.

References rnr::cmd::CommandLine::addCommand(), addQuitCommand(), atname(), rnr::cmd::CmdDesc::name, rnr::cmd::CommandLine::quit(), and rnr::str::replace().

      {
        cli.quit();
        return OK;
      }

int rnr::cmd::addons::printCmdHelp	(	std::ostream &	os,
		const CmdDef &	cmddef,
		const HelpSect	section = HelpSectAll
	)

Print help for a command convenience function.

Parameters

os	Output stream.
cmddef	Command definition.
section	Help section.

Returns

OK(0) on success, negative value on failure.

int rnr::cmd::addons::printCmdHelp	(	std::ostream &	os,
		const CmdDesc &	desc,
		const HelpSect	section = HelpSectAll
	)

Print help for a command convenience function.

Parameters

os	Output stream.
desc	Command description.
section	Help section.

Returns

OK(0) on success, negative value on failure.

int rnr::cmd::addons::printCmdHelp	(	std::ostream &	os,
		const std::string &	strName,
		const std::string &	strSyntax,
		const std::string &	strSynopsis,
		const std::string &	strLongDesc,
		const HelpSect	section = HelpSectAll
	)

Print help for a command convenience function.

Parameters

os	Output stream.
strName	Command name.
strSyntax	Command usage syntax.
strSynopsis	Command short synopsis.
strLongDesc	Command long description.
section	Help section.

Returns

OK(0) on success, negative value on failure.

int rnr::cmd::addons::printCmdHelp	(	ostream &	os,
		const string &	strName,
		const string &	strSyntax,
		const string &	strSynopsis,
		const string &	strLongDesc,
		const HelpSect	section
	)

wrap and indent

Definition at line 226 of file CmdAddOns.cxx.

References rnr::cmd::CommandLine::addCommand(), addHelpCommand(), atname(), execHelp(), HelpSectAll, HelpSectBrief, HelpSectName, HelpSectUsage, rnr::cmd::CmdDesc::name, rnr::str::replace(), and rnr::str::split().

Referenced by execHelp().

      {
        size_t  i;
      
        if( strName.empty() )
        {
          os << "Error: Command has no name." << endl;
          return RC_ERROR;
        }
  
        if( strSyntax.empty() )
        {
          os << "Error: Command has no extended usage syntax." << endl;
          return RC_ERROR;
        }
  
        StringVec usages = split(strSyntax, '\n');
  
        switch( section )
        {
          case HelpSectName:
            os << strName;
            break;
  
          case HelpSectBrief:
            os << strName << " - " << strSynopsis << endl;
            break;
  
          case HelpSectUsage:
            for(i = 0; i < usages.size(); ++i)
            {
              if( !usages[i].empty() )
              {
                os << usages[i] << "\n";
              }
            }
            break;
  
          case HelpSectAll:
          default:
            ssize_t len;
            size_t  w;
  
            len = (ssize_t)strName.size() + 2;
            len = 80 - 2 * len;
            os << strName << "()";
            if( len > 1 )
            {
              w = os.width();
              os.width(len);
              os << "";
              os.width(w);
              os << strName << "()";
            }
            os << "\n\n";
  
            os << "Name\n  " << strName;
            os << " - " << strSynopsis;
            os << "\n\n";
  
            os << "Synopsis\n";
            for(i = 0; i < usages.size(); ++i)
            {
              if( !usages[i].empty() )
              {
                os << "  " << usages[i] << "\n";
              }
            }
            os << "\n";
  
            if( !strLongDesc.empty() )
            {
              os << "Description\n";
  
              StringVec lines = split(strLongDesc, '\n');
              size_t    wstart, wend, wlen; // word data
              size_t    cursor;             // output line cursor
  
              for(i = 0; i < lines.size(); ++i)
              {
                // indent
                os << "  ";
                cursor = 2;
  
                //
                // Output line, wrapping if necessary.
                //
                for(size_t j = 0; j < lines[i].size(); )
                {
                  // whitespace
                  while( isspace(lines[i][j]) && (j < lines[i].size()) )
                  {
                    // less than max output line length
                    if( cursor < 80 )
                    {
                      cout << ' ';
                      ++cursor;
                    }
                    // wrap
                    else
                    {
                      // wrap and indent
                      cout << "\n  ";
                      cursor = 2;
                    }
                    ++j;
                  }
  
                  if( j >= lines[i].size() )
                  {
                    break;
                  }
  
                  // word
                  wstart = j;
  
                  while( !isspace(lines[i][j]) && (j < lines[i].size()) )
                  {
                    ++j;
                  }
  
                  wend  = j;
                  wlen  = wend - wstart;
  
                  // wrap
                  if( (cursor > 2) && (cursor+wlen >= 80) )
                  {
                    /// wrap and indent
                    cout << "\n  ";
                    cursor = 2;
                  }
  
                  cout << lines[i].substr(wstart, wlen);
                  cursor += wlen;
                }
  
                cout << '\n';
              }
              cout << '\n';
            }
            break;
        }
  
        return OK;
      }