Provided by: libbobcat-dev_4.08.02-2build1_amd64 
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 are available.
OVERLOADED OPERATORS
The copy and move 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);
return 0;
}
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_4.08.02-x.dsc: detached signature;
o bobcat_4.08.02-x.tar.gz: source archive;
o bobcat_4.08.02-x_i386.changes: change log;
o libbobcat1_4.08.02-x_*.deb: debian package holding the libraries;
o libbobcat1-dev_4.08.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).