Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
FBB::CmdFinder(3bobcat)	 Command-function associations FBB::CmdFinder(3bobcat)

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	 (mem-
       ber)  functions are often defined in a switch, a	switch is not the pre-
       ferred 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-support-
       ing,  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 (tex-
       tual) commands and functions to be called can also  easily  be  defined
       using  a	 std::map or other hash-type data structure. However, the syn-
       tactical	requirements for such a	std::map  structure  are  non-trivial,
       and besides: user-entered commands often	require	some preprocessing be-
       fore 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 particu-
       lar, 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	 func-
	      tion associated with the command.	The function addresses may ei-
	      ther 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  insensi-
	      tively;

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

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

       The  class  CmdFinder  itself is	defined	as a template class. This tem-
       plate 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,	defin-
       ing  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 ob-
	      tained  from the CmdFinder object. By default, the complete con-
	      tents 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 associa-
	      tions exactly.

       o      INSENSITIVE:
	      When this	value is specified, commands may be  specified	disre-
	      garding 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 pro-
	      vided 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  *,	 Func-
	      tionPtr>.	 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 be-
	      tween commands and functions. The	parameter begin	should be ini-
	      tialized	to the first element of	an array of Entry objects, the
	      parameter	end must point just beyond the last element of the ar-
	      ray. 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  en-
	      countered	 by  the CmdFinder object.  It is initially empty, and
	      will be redefined	at each	call of	findCmd()  (see	 below).   ob-
	      ject.

       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 re-
	      turns  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 com-
	      mand-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), exception(3bobcat)

BUGS
       None Reported.

DISTRIBUTION FILES
       o      bobcat_3.25.01-x.dsc: detached signature;

       o      bobcat_3.25.01-x.tar.gz: source archive;

       o      bobcat_3.25.01-x_i386.changes: change log;

       o      libbobcat1_3.25.01-x_*.deb:  debian  package  holding  the   li-
	      braries;

       o      libbobcat1-dev_3.25.01-x_*.deb:  debian  package holding the li-
	      braries, 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).

libbobcat-dev_3.25.01-x.tar.gz	   2005-2015	       FBB::CmdFinder(3bobcat)

NAME | SYNOPSIS | DESCRIPTION | NAMESPACE | INHERITS FROM | ENUMERATION | TEMPLATE TYPE PARAMETER | PROTECTED DEFINED TYPES | CONSTRUCTORS | OVERLOADED OPERATORS | PUBLIC MEMBER FUNCTION | PROTECTED MEMBER FUNCTIONS | PROTECTED DATA MEMBERS | EXAMPLE | FILES | SEE ALSO | BUGS | DISTRIBUTION FILES | BOBCAT | COPYRIGHT | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=cmdfinder&sektion=3bobcat&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help