Provided by: libbobcat-dev_5.00.02-2_amd64 bug

NAME

       FBB::CmdFinder - Determine (member) function associated with a command

SYNOPSIS

       #include <bobcat/cmdfinder>
       Linking option: -lbobcat

DESCRIPTION

       Objects  of the class CmdFinder determine which (member) function to call given a command.
       Although associations between commands and (member)  functions  are  often  defined  in  a
       switch, a switch is not the preferred way to define these associations because of the fect
       that the maintainability and clarity of switches suffer for even moderately large  command
       sets.   Moreover,   the   switch  is  hardly  ever  self-supporting,  since  usually  some
       command-processing is required to determine command/case-value associations.

       The alternative (and preferred) approach, which is also taken by CmdFinder is to define an
       array  of  pointers to (member) functions, and to define the associations between commands
       and member functions as a mapping of commands to array indices. Plain associations between
       (textual)  commands and functions to be called can also easily be defined using a std::map
       or other hash-type data structure.  However,  the  syntactical  requirements  for  such  a
       std::map  structure are non-trivial, and besides: user-entered commands often require some
       preprocessing before a command can be used as an index in a std::map.

       The class CmdFinder is an attempt to offer  a  versatile  implementation  of  associations
       between  commands  and  (member) functions.  In particular, the class offers the following
       features:

       o      Associations between textual commands and  (member)  functions  are  defined  in  a
              simple  array  of  pairs:  the first element defining a command, the second element
              containing the address of the function associated with the  command.  The  function
              addresses may either be addresses of free or static member functions or they may be
              defined as member function addresses.

       o      Commands may be used `as-is’, or the first word in a std::string may be used as the
              command;

       o      Commands may be specified case sensitively or case insensitively;

       o      Commands  may have to be specified in full, or unique abbreviations of the commands
              may be accepted;

       o      Several  types  are  defined  by  the  class  CmdFinder,  further  simplifying  the
              deriviation of classes from CmdFinder.

       The  class  CmdFinder itself is defined as a template class. This template class should be
       used  as  a  base  class  of  a  user-defined  derived  class  defining   the   array   of
       command-function  associations. The class CmdFinder itself is a derived class of the class
       CmdFinderBase, defining some template-independent functionality that is used by CmdFinder.
       The  enumeration  and  member  functions  sections below also contain the members that are
       available to classes derived from CmdFinder, but which are actually defined in  the  class
       CmdFinderBase.

NAMESPACE

       FBB
       All  constructors,  members,  operators  and manipulators, mentioned in this man-page, are
       defined in the namespace FBB.

INHERITS FROM

       FBB::CmdFinderBase

ENUMERATION

       The enumeration Mode is defined in the class  CmdFinderBase.  It  contains  the  following
       values,  which  may  be  combined by the bit_or operator to specify the CmdFinder object’s
       required mode of operation:

       o      USE_FIRST:
              This value can be specified when the first word (any white-space  separated  series
              of characters) of a provided textual command should be used as the command to find.
              Both the command that is used and any trailing information that may be present  can
              be  obtained  from the CmdFinder object. By default, the complete contents of the a
              provided command is used.

       o      UNIQUE:
              This value can be specified when any  unique  abbreviation  of  a  command  may  be
              accepted.  Assuming  that  the  commands  help  and  version  are defined, then the
              following (non-exhaustive) series are all accepted as specifications  of  the  help
              command  if  UNIQUE is specified: h, he, el, p. By default the command must match a
              command-key as found in the array of command-function associations exactly.

       o      INSENSITIVE:
              When this value is specified, commands may be specified disregarding letter-casing.
              E.g.,  when INSENSITIVE is specified, both Help and HELP are recognized as help. By
              default, letter casing is obeyed.  So, by default a  full,  literal  match  between
              provided command and predefined command-keys is required.

TEMPLATE TYPE PARAMETER

       The  template  class  CmdFinder has one template type parameter, which is the prototype of
       the functions defined in the array of command-function  associations.  This  type  becomes
       available as the typename FunctionPtr (defined by the class CmdFinder in the class that is
       derived from CmdFinder).

PROTECTED DEFINED TYPES

       The following (protected) types are defined by the template class CmdFinder:

       o      FunctionPtr:
              This type represents a pointer to the functions whose addresses are stored  in  the
              array of command-function associations.

       o      Entry:
              This type represents the type std::pair<char const *, FunctionPtr>. Its first field
              is the name of a command, its second field is the function address associated  with
              the command name.

CONSTRUCTORS

       o      CmdFinder<FunctionPtr>(Entry const *begin, Entry const *end, size_t mode = 0):
              This  constructor  is  defined in the protected section of the CmdFinder class. Its
              parameters begin and end define the half-open range of Entry objects, defining  the
              associations  between  commands  and  functions.  The  parameter  begin  should  be
              initialized to the first element of an array of Entry objects,  the  parameter  end
              must  point  just  beyond  the last element of the array. The parameter mode may be
              speified using any combination of values of the Mode enumeration, using the  bit_or
              operator  to  combine  multiple values. When a non-supported value is specified for
              mode, an FBB::Exception exception is thrown.

       o      Note:
              There is no default constructor.

       Copy and move constructors (and assignment operators) are available.

PUBLIC MEMBER FUNCTION

       o      setMode(size_t mode):
              This member function (defined in the class CmdFinderBase) may be called to redefine
              the  mode of the CmdFinder object. The mode parameter should be initialized subject
              to the same restrictions as mentioned with the CmdFinder’s constructor.

PROTECTED MEMBER FUNCTIONS

       o      std::string const &beyond() const:
              This member function returns the text that may have been entered beyond the command
              (if  Mode value USE_FIRST was specified). It is empty if no text beyond the command
              was encountered. It is initially empty, and will  be  redefined  at  each  call  of
              findCmd() (see below).

       o      std::string const &cmd() const:
              This  member  returns  the  original  (untransformed) command as encountered by the
              CmdFinder object.  It is initially empty, and will be redefined  at  each  call  of
              findCmd() (see below).  object.

       o      size_t count() const:
              This  member  function  returns the number of commands matching the command that is
              passed to the function findCmd() (see below). Its return value is 0 when  findCmd()
              hasn’t been called yet and is updated at each new call of findCmd().

       o      FunctionPtr findCmd(std::string const &cmd):
              Regarding the CmdFinder object’s mode setting, this function returns the address of
              the function to call given the provided command. By default, if no match was found,
              the  address  of  the  function  stored  in  the  last  element  of  the  array  of
              command-function associations is returned (i.e, element end[-1]).

       o      void swap(CmdFinderBase &other):
              The current and other object are swapped.

PROTECTED DATA MEMBERS

       The class CmdFinder has access to some protected data members of the class  CmdFinderBase,
       which should not be used or modified by classes derived from CmdFinder.

EXAMPLE

       #include <iostream>
       #include <string>

       #include <bobcat/cmdfinder>

       using namespace std;
       using namespace FBB;

       // Define a class `Command’ in which the array s_action defines the
       // command-function associations. Command is derived from CmdFinder,
       // specifying the prototype of the member functions to be called

       class Command: public CmdFinder<bool (Command::*)() const>
       {
           static Entry s_action[];

           bool add() const                       // some member functions
           {
               cout << "add called: command was `" << cmd() << "’\n";
               if (beyond().length())
                   cout << "Beyond " << cmd() << " `" << beyond() << "’\n";
               return true;
           }
           bool error() const
           {
               cout << "unrecognized command: `" << cmd() << "’ called\n" <<
                       count() << " matching alternatives found\n";
               return true;
           }
           bool quit() const
           {
               cout << "quit called: quitting this series\n";
               return false;
           }

           public:
               Command();                      // Declare the default constructor

               bool run(std::string const &cmd)    // run a command
               {
                   return (this->*findCmd(cmd))(); // execute the command matching
                                                   // ’cmd’
               }
       };

       // Define command-function associations. Note that the last is given an empty
       // command-text. This is not required, a command text could have been
       // specified for the last command as well.

       Command::Entry Command::s_action[] =
       {
           Entry("add",    &Command::add),
           Entry("quit",   &Command::quit),
           Entry("",       &Command::error),
       };

       // Define the default constructor
       Command::Command()                       // Define the default constructor
       :                               // Note the use of `FunctionPtr’
           CmdFinder<FunctionPtr>(s_action, s_action +
                                           sizeof(s_action) / sizeof(Entry))
       {}

       void run(Command &cmd, char const *descr, size_t mode = 0)
       {
           if (mode)
               cmd.setMode(mode);

           cout << "Enter 5 x a command using " << descr << ".\n";
           for (size_t idx = 0; idx++ < 5; )
           {
               cout << "Enter command " << idx << ": ";
               string text;
               getline(cin, text);
               if (!cmd.run(text))     // run a command
                   break;
           }
       }

       int main()
       {
           Command cmd;                // define a command

                                       // enter 5 commands using the default mode
           run (cmd, "the default mode");
           run (cmd, "abbreviated commands", Command::UNIQUE);
           run (cmd, "abbreviated case-insensitive commands",
                                          Command::UNIQUE | Command::INSENSITIVE);
           run (cmd, "abbreviated command lines",
                                          Command::USE_FIRST | Command::UNIQUE);
           run (cmd, "abbreviated case-insensitive command lines",
                                          Command::USE_FIRST | Command::UNIQUE |
                                                               Command::INSENSITIVE);
       }

FILES

       bobcat/cmdfinder - defines the class interface
       bobcat/cmdfinderbase - defines the base class of CmdFinder.

SEE ALSO

       bobcat(7), cmdfinderbase(3bobcat), exception(3bobcat)

BUGS

       None Reported.

DISTRIBUTION FILES

       o      bobcat_5.00.02-x.dsc: detached signature;

       o      bobcat_5.00.02-x.tar.gz: source archive;

       o      bobcat_5.00.02-x_i386.changes: change log;

       o      libbobcat1_5.00.02-x_*.deb: debian package holding the libraries;

       o      libbobcat1-dev_5.00.02-x_*.deb:  debian  package holding the libraries, headers and
              manual pages;

       o      http://sourceforge.net/projects/bobcat: public archive location;

BOBCAT

       Bobcat is an acronym of `Brokken’s Own Base Classes And Templates’.

COPYRIGHT

       This is free software, distributed under the terms  of  the  GNU  General  Public  License
       (GPL).

AUTHOR

       Frank B. Brokken (f.b.brokken@rug.nl).