/usr/share/doc/libbobcat3-dev/man/cmdfinder.3.html is in libbobcat-dev 3.19.01-1ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 | <html><head>
<title>FBB::CmdFinder</title>
<link rev="made" href="mailto:Frank B. Brokken: f.b.brokken@rug.nl">
</head>
<body text="#27408B" bgcolor="#FFFAF0">
<hr>
<h1>FBB::CmdFinder</h1>
<h2>libbobcat-dev_3.19.01-x.tar.gz</h2>
<h2>2005-2013</h2>
<html><head>
<link rev="made" href="mailto:Frank B. Brokken: f.b.brokken@rug.nl">
</head>
<body text="#27408B" bgcolor="#FFFAF0">
<hr>
<h1></h1>
<html><head>
<title>FBB::CmdFinder(3bobcat)</title>
<link rev="made" href="mailto:Frank B. Brokken: f.b.brokken@rug.nl">
</head>
<body text="#27408B" bgcolor="#FFFAF0">
<hr>
<h1>FBB::CmdFinder(3bobcat)</h1>
<h2>libbobcat-dev_3.19.01-x.tar.gz Command-function associations</h2>
<h2>2005-2013</h2>
<p>
<h2>NAME</h2>FBB::CmdFinder - Determine (member) function associated with a command
<p>
<h2>SYNOPSIS</h2>
<strong>#include <bobcat/cmdfinder></strong><br>
Linking option: <em>-lbobcat</em>
<p>
<h2>DESCRIPTION</h2>
<p>
Objects of the class <strong>CmdFinder</strong> 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/<strong>case</strong>-value
associations.
<p>
The alternative (and preferred) approach, which is also taken by
<strong>CmdFinder</strong> 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 <strong>std::map</strong> or
other hash-type data structure. However, the syntactical requirements for such
a <strong>std::map</strong> structure are non-trivial, and besides: user-entered commands
often require some preprocessing before a command can be used as an index in a
<strong>std::map</strong>.
<p>
The class <strong>CmdFinder</strong> is an attempt to offer a versatile implementation
of associations between commands and (member) functions. In particular, the
class offers the following features:
<ul>
<li> 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.
<li> Commands may be used `as-is', or the first word in a <strong>std::string</strong>
may be used as the command;
<li> Commands may be specified case sensitively or case insensitively;
<li> Commands may have to be specified in full, or unique abbreviations of
the commands may be accepted;
<li> Several types are defined by the class <strong>CmdFinder</strong>, further
simplifying the deriviation of classes from <strong>CmdFinder</strong>.
</ul>
<p>
The class <strong>CmdFinder</strong> 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 <strong>CmdFinder</strong>
itself is a derived class of the class <strong>CmdFinderBase</strong>, defining some
template-independent functionality that is used by <strong>CmdFinder</strong>. The
enumeration and member functions sections below also contain the members that
are available to classes derived from <strong>CmdFinder</strong>, but which are actually
defined in the class <strong>CmdFinderBase</strong>.
<p>
<h2>NAMESPACE</h2>
<strong>FBB</strong><br>
All constructors, members, operators and manipulators, mentioned in this
man-page, are defined in the namespace <strong>FBB</strong>.
<p>
<h2>INHERITS FROM</h2>
<strong>FBB::CmdFinderBase</strong>
<p>
<h2>ENUMERATION</h2>
The enumeration <strong>Mode</strong> is defined in the class <strong>CmdFinderBase</strong>. It
contains the following values, which may be combined by the <strong>bit_or</strong>
operator to specify the <strong>CmdFinder</strong> object's required mode of operation:
<ul>
<li> <strong>USE_FIRST</strong>:<br>
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 <strong>CmdFinder</strong>
object. By default, the complete contents of the a provided command is used.
<li> <strong>UNIQUE</strong>:<br>
This value can be specified when any unique abbreviation of a command
may be accepted. Assuming that the commands <em>help</em> and <em>version</em> are
defined, then the following (non-exhaustive) series are all accepted as
specifications of the <em>help</em> command if <strong>UNIQUE</strong> is specified: <em>h, he,
el, p</em>. By default the command must match a command-key as found in the array
of command-function associations exactly.
<li> <strong>INSENSITIVE</strong>:<br>
When this value is specified, commands may be specified disregarding
letter-casing. E.g., when <strong>INSENSITIVE</strong> is specified, both <em>Help</em> and
<em>HELP</em> are recognized as <em>help</em>. By default, letter casing is obeyed.
</ul>
So, by default a full, literal match between provided command and
predefined command-keys is required.
<p>
<h2>TEMPLATE TYPE PARAMETER</h2>
The template class <strong>CmdFinder</strong> 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
<strong>FunctionPtr</strong> (defined by the class <strong>CmdFinder</strong> in the class that is
derived from <strong>CmdFinder</strong>).
<p>
<h2>PROTECTED DEFINED TYPES</h2>
The following (<strong>protected</strong>) types are defined by the template class
<strong>CmdFinder</strong>:
<ul>
<li> <strong>FunctionPtr</strong>:<br>
This type represents a pointer to the functions whose addresses are
stored in the array of command-function associations.
<li> <strong>Entry</strong>:<br>
This type represents the type <strong>std::pair<char const *,
FunctionPtr></strong>. Its <em>first</em> field is the name of a command, its <em>second</em>
field is the function address associated with the command name.
</ul>
<p>
<h2>CONSTRUCTORS</h2>
<ul>
<li> <strong>CmdFinder<FunctionPtr>(Entry const *begin, Entry const *end,
size_t mode = 0)</strong>:<br>
This constructor is defined in the <strong>protected</strong> section of the
<strong>CmdFinder</strong> class. Its parameters <em>begin</em> and <em>end</em> define the half-open
range of <strong>Entry</strong> objects, defining the associations between commands and
functions. The parameter <em>begin</em> should be initialized to the first element
of an array of <strong>Entry</strong> objects, the parameter <em>end</em> must point just beyond
the last element of the array. The parameter <em>mode</em> may be speified using
any combination of values of the <strong>Mode</strong> enumeration, using the <strong>bit_or</strong>
operator to combine multiple values. When a non-supported value is specified
for <em>mode</em>, an <strong>FBB::Exception</strong> exception is thrown.
<li> <strong>Note</strong>:<br>
There is no default constructor.
</ul>
Copy and move constructors are available.
<p>
<h2>OVERLOADED OPERATORS</h2>
<p>
The copy and move assignment operators are available.
<p>
<h2>PUBLIC MEMBER FUNCTION</h2>
<ul>
<li> <strong>setMode(size_t mode)</strong>:<br>
This member function (defined in the class <strong>CmdFinderBase</strong>) may be
called to redefine the mode of the <strong>CmdFinder</strong> object. The <em>mode</em>
parameter should be initialized subject to the same restrictions as mentioned
with the <strong>CmdFinder</strong>'s constructor.
</ul>
<p>
<h2>PROTECTED MEMBER FUNCTIONS</h2>
<ul>
<li> <strong>std::string const &beyond() const</strong>:<br>
This member function returns the text that may have been entered
beyond the command (if <strong>Mode</strong> value <strong>USE_FIRST</strong> 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 <strong>findCmd()</strong> (see below).
<li> <strong>std::string const &cmd() const</strong>:<br>
This member returns the original (untransformed) command as
encountered by the <strong>CmdFinder</strong> object. It is initially empty, and will be
redefined at each call of <strong>findCmd()</strong> (see below). object.
<li> <strong>size_t count() const</strong>:<br>
This member function returns the number of commands matching the
command that is passed to the function <strong>findCmd()</strong> (see below). Its return
value is 0 when <strong>findCmd()</strong> hasn't been called yet and is updated at each
new call of <strong>findCmd()</strong>.
<li> <strong>FunctionPtr findCmd(std::string const &cmd)</strong>:<br>
Regarding the <strong>CmdFinder</strong> object's <strong>mode</strong> 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 <em>end[-1]</em>).
</ul>
<p>
<h2>PROTECTED DATA MEMBERS</h2>
The class <strong>CmdFinder</strong> has access to some protected data members of the
class <strong>CmdFinderBase</strong>, which should not be used or modified by classes
derived from <strong>CmdFinder</strong>.
<p>
<h2>EXAMPLE</h2>
<pre>
#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;
}
</pre>
<p>
<h2>FILES</h2>
<em>bobcat/cmdfinder</em> - defines the class interface<br>
<em>bobcat/cmdfinderbase</em> - defines the base class of <strong>CmdFinder</strong>.
<p>
<h2>SEE ALSO</h2>
<strong>bobcat</strong>(7), <strong>cmdfinderbase</strong>(3bobcat), <strong>errno</strong>(3bobcat)
<p>
<h2>BUGS</h2>
None Reported.
<p>
<h2>DISTRIBUTION FILES</h2>
<ul>
<li> <em>bobcat_3.19.01-x.dsc</em>: detached signature;
<li> <em>bobcat_3.19.01-x.tar.gz</em>: source archive;
<li> <em>bobcat_3.19.01-x_i386.changes</em>: change log;
<li> <em>libbobcat1_3.19.01-x_*.deb</em>: debian package holding the
libraries;
<li> <em>libbobcat1-dev_3.19.01-x_*.deb</em>: debian package holding the
libraries, headers and manual pages;
<li> <em>http://sourceforge.net/projects/bobcat</em>: public archive location;
</ul>
<p>
<h2>BOBCAT</h2>
Bobcat is an acronym of `Brokken's Own Base Classes And Templates'.
<p>
<h2>COPYRIGHT</h2>
This is free software, distributed under the terms of the
GNU General Public License (GPL).
<p>
<h2>AUTHOR</h2>
Frank B. Brokken (<strong>f.b.brokken@rug.nl</strong>).
<p>
|