simgear/misc/commands.hxx

   1 /**
   2  * \file commands.hxx
   3  * Interface definition for encapsulated commands.
   4  * Started Spring 2001 by David Megginson, david@megginson.com
   5  * This code is released into the Public Domain.
   6  *
   7  * $Id$
   8  */
   9
  10 #ifndef __COMMANDS_HXX
  11 #define __COMMANDS_HXX
  12
  13
  14 #include <simgear/compiler.h>
  15
  16 #include STL_STRING
  17 #include <map>
  18 #include <vector>
  19
  20 #include "props.hxx"
  21
  22 SG_USING_STD(string);
  23 SG_USING_STD(map);
  24 SG_USING_STD(vector);
  25
  26
  27 /**
  28  * Stored state for a command.
  29  *
  30  * <p>This class allows a command to cache parts of its state between
  31  * invocations with the same parameters.  Nearly every command that
  32  * actually uses this will subclass it in some way.  The command
  33  * allocates the structure, but it is up to the caller to delete it
  34  * when it is no longer necessary, unless the command deletes it
  35  * and replaces the value with 0 or another command-state object
  36  * first.</p>
  37  *
  38  * <p>Note that this class is for caching only; all of the information
  39  * in it must be recoverable by other means, since the state could
  40  * arbitrarily disappear between invocations if the caller decides to
  41  * delete it.</p>
  42  *
  43  * <p>By default, the command state includes a place to keep a copy of
  44  * the parameters.</p>
  45  *
  46  * @author David Megginson, david@megginson.com
  47  */
  48 class SGCommandState
  49 {
  50 public:
  51   SGCommandState ();
  52   SGCommandState (const SGPropertyNode * args);
  53   virtual ~SGCommandState ();
  54   virtual void setArgs (const SGPropertyNode * args);
  55   virtual const SGPropertyNode * getArgs () const { return _args; }
  56 private:
  57   SGPropertyNode * _args;
  58 };
  59
  60
  61 /**
  62  * Manage commands.
  63  *
  64  * <p>This class allows the application to register and unregister
  65  * commands, and provides shortcuts for executing them.  Commands are
  66  * simple functions that take a const pointer to an SGPropertyNode and
  67  * a pointer to a pointer variable (which should be 0 initially) where
  68  * the function can store compiled copies of its arguments, etc. to
  69  * avoid expensive recalculations.  If the command deletes the
  70  * SGCommandState, it must replace it with a new pointer or 0;
  71  * otherwise, the caller is free to delete and zero the pointer at any
  72  * time and the command will start fresh with the next invocation.
  73  * The command must return a bool value indicating success or failure.
  74  * The property node may be ignored, or it may contain values that the
  75  * command uses as parameters.</p>
  76  *
  77  * <p>There are convenience methods for invoking a command function
  78  * with no arguments or with a single, primitive argument.</p>
  79  *
  80  * @author David Megginson, david@megginson.com
  81  */
  82 class SGCommandMgr
  83 {
  84 public:
  85
  86   /**
  87    * Type for a command function.
  88    */
  89   typedef bool (*command_t) (const SGPropertyNode * arg,
  90                              SGCommandState ** state);
  91
  92
  93   /**
  94    * Default constructor.
  95    */
  96   SGCommandMgr ();
  97
  98
  99   /**
 100    * Destructor.
 101    */
 102   virtual ~SGCommandMgr ();
 103
 104
 105   /**
 106    * Register a new command with the manager.
 107    *
 108    * @param name The command name.  Any existing command with
 109    * the same name will silently be overwritten.
 110    * @param command A pointer to a one-arg function returning
 111    * a bool result.  The argument is always a const pointer to
 112    * an SGPropertyNode (which may contain multiple values).
 113    */
 114   virtual void addCommand (const string &name, command_t command);
 115
 116
 117   /**
 118    * Look up an existing command.
 119    *
 120    * @param name The command name.
 121    * @return A pointer to the command, or 0 if there is no registered
 122    * command with the name specified.
 123    */
 124   virtual command_t getCommand (const string &name) const;
 125
 126
 127   /**
 128    * Get a list of all existing command names.
 129    *
 130    * @return A (possibly empty) vector of the names of all registered
 131    * commands.
 132    */
 133   virtual vector<string> getCommandNames () const;
 134
 135
 136   /**
 137    * Execute a command.
 138    *
 139    * This is the primary method for invoking a command; the others
 140    * are convenience methods that invoke this one indirectly.
 141    *
 142    * @param name The name of the command.
 143    * @param arg A const pointer to an SGPropertyNode.  The node
 144    * may have a value and/or children, etc., so that it is possible
 145    * to pass an arbitrarily complex data structure to a command.
 146    * @return true if the command is present and executes successfully,
 147    * false otherwise.
 148    */
 149   virtual bool execute (const string &name,
 150                         const SGPropertyNode * arg,
 151                         SGCommandState ** state) const;
 152
 153 private:
 154
 155   typedef map<string,command_t> command_map;
 156   command_map _commands;
 157
 158 };
 159
 160 #endif // __COMMANDS_HXX
 161
 162 // end of commands.hxx