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
 154 //   /**
 155 //    * Execute a command with no argument.
 156 //    *
 157 //    * The command function will receive a pointer to a property node
 158 //    * with no value and no children.
 159 //    *
 160 //    * @param name The name of the command.
 161 //    * @return true if the command is present and executes successfully,
 162 //    * false otherwise.
 163 //    */
 164 //   virtual bool execute (const string &name) const;
 165
 166
 167 //   /**
 168 //    * Execute a command with a single bool argument.
 169 //    *
 170 //    * The command function will receive a pointer to a property node
 171 //    * with a bool value and no children.
 172 //    *
 173 //    * @param name The name of the command.
 174 //    * @param arg The bool argument to the command.
 175 //    * @return true if the command is present and executes successfully,
 176 //    * false otherwise.
 177 //    */
 178 //   virtual bool execute (const string &name, bool arg) const;
 179
 180
 181 //   /**
 182 //    * Execute a command with a single int argument.
 183 //    *
 184 //    * The command function will receive a pointer to a property node
 185 //    * with a int value and no children.
 186 //    *
 187 //    * @param name The name of the command.
 188 //    * @param arg The int argument to the command.
 189 //    * @return true if the command is present and executes successfully,
 190 //    * false otherwise.
 191 //    */
 192 //   virtual bool execute (const string &name, int arg) const;
 193
 194
 195 //   /**
 196 //    * Execute a command with a single long argument.
 197 //    *
 198 //    * The command function will receive a pointer to a property node
 199 //    * with a long value and no children.
 200 //    *
 201 //    * @param name The name of the command.
 202 //    * @param arg The long argument to the command.
 203 //    * @return true if the command is present and executes successfully,
 204 //    * false otherwise.
 205 //    */
 206 //   virtual bool execute (const string &name, long arg) const;
 207
 208
 209 //   /**
 210 //    * Execute a command with a single float argument.
 211 //    *
 212 //    * The command function will receive a pointer to a property node
 213 //    * with a float value and no children.
 214 //    *
 215 //    * @param name The name of the command.
 216 //    * @param arg The float argument to the command.
 217 //    * @return true if the command is present and executes successfully,
 218 //    * false otherwise.
 219 //    */
 220 //   virtual bool execute (const string &name, float arg) const;
 221
 222
 223 //   /**
 224 //    * Execute a command with a single double argument.
 225 //    *
 226 //    * The command function will receive a pointer to a property node
 227 //    * with a double value and no children.
 228 //    *
 229 //    * @param name The name of the command.
 230 //    * @param arg The double argument to the command.
 231 //    * @return true if the command is present and executes successfully,
 232 //    * false otherwise.
 233 //    */
 234 //   virtual bool execute (const string &name, double arg) const;
 235
 236
 237 //   /**
 238 //    * Execute a command with a single string argument.
 239 //    *
 240 //    * The command function will receive a pointer to a property node
 241 //    * with a string value and no children.
 242 //    *
 243 //    * @param name The name of the command.
 244 //    * @param arg The string argument to the command.
 245 //    * @return true if the command is present and executes successfully,
 246 //    * false otherwise.
 247 //    */
 248 //   virtual bool execute (const string &name, string arg) const;
 249
 250
 251 private:
 252
 253   typedef map<string,command_t> command_map;
 254   command_map _commands;
 255
 256 };
 257
 258 #endif // __COMMANDS_HXX
 259
 260 // end of commands.hxx