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::Errno 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]).
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>
#include "../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),
errno(3bobcat)
BUGS¶
None Reported.
DISTRIBUTION FILES¶
- o
- bobcat_3.01.00-x.dsc: detached signature;
- o
- bobcat_3.01.00-x.tar.gz: source archive;
- o
- bobcat_3.01.00-x_i386.changes: change log;
- o
- libbobcat1_3.01.00-x_*.deb: debian package holding
the libraries;
- o
- libbobcat1-dev_3.01.00-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).