console.h

Public Functions

collapseEscape(char * buf)

dAtob(ConsoleValue & ref)

dAtof(ConsoleValueRef & ref)

dAtoi(ConsoleValueRef & ref)

expandEscape(char * dest, const char * src)

HashPointer(StringTableEntry ptr)

TYPEID()

Return the type ID for the primary console type associated with the given native type.

There can only be one console type associated with a C++ type. This is referred to as the primary console type.

   1
   2//-----------------------------------------------------------------------------
   3// Copyright (c) 2012 GarageGames, LLC
   4//
   5// Permission is hereby granted, free of charge, to any person obtaining a copy
   6// of this software and associated documentation files (the "Software"), to
   7// deal in the Software without restriction, including without limitation the
   8// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
   9// sell copies of the Software, and to permit persons to whom the Software is
  10// furnished to do so, subject to the following conditions:
  11//
  12// The above copyright notice and this permission notice shall be included in
  13// all copies or substantial portions of the Software.
  14//
  15// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  16// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  17// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  18// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  19// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  20// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
  21// IN THE SOFTWARE.
  22//-----------------------------------------------------------------------------
  23
  24#ifndef _CONSOLE_H_
  25#define _CONSOLE_H_
  26
  27#ifndef _PLATFORM_H_
  28   #include "platform/platform.h"
  29#endif
  30#ifndef _BITSET_H_
  31   #include "core/bitSet.h"
  32#endif
  33#ifndef _REFBASE_H_
  34   #include "core/util/refBase.h"
  35#endif
  36#include <stdarg.h>
  37
  38#include "core/util/str.h"
  39#include "core/util/journal/journaledSignal.h"
  40
  41class SimObject;
  42class Namespace;
  43struct ConsoleFunctionHeader;
  44
  45class EngineEnumTable;
  46typedef EngineEnumTable EnumTable;
  47
  48typedef U32 StringStackPtr;
  49
  50template< typename T > S32 TYPEID();
  51
  52
  53/// @defgroup console_system Console System
  54/// The Console system is the basis for logging, SimObject, and TorqueScript itself.
  55///
  56/// @{
  57
  58/// Indicates that warnings about undefined script variables should be displayed.
  59///
  60/// @note This is set and controlled by script.
  61extern bool gWarnUndefinedScriptVariables;
  62
  63enum StringTableConstants
  64{
  65   StringTagPrefixByte = 0x01 ///< Magic value prefixed to tagged strings.
  66};
  67
  68/// Represents an entry in the log.
  69struct ConsoleLogEntry
  70{
  71   /// This field indicates the severity of the log entry.
  72   ///
  73   /// Log entries are filtered and displayed differently based on
  74   /// their severity. Errors are highlighted red, while normal entries
  75   /// are displayed as normal text. Often times, the engine will be
  76   /// configured to hide all log entries except warnings or errors,
  77   /// or to perform a special notification when it encounters an error.
  78   enum Level
  79   {
  80      Normal = 0,
  81      Warning,
  82      Error,
  83      NUM_CLASS
  84   } mLevel;
  85
  86   /// Used to associate a log entry with a module.
  87   ///
  88   /// Log entries can come from different sources; for instance,
  89   /// the scripting engine, or the network code. This allows the
  90   /// logging system to be aware of where different log entries
  91   /// originated from.
  92   enum Type
  93   {
  94      General = 0,
  95      Assert,
  96      Script,
  97      GUI,
  98      Network,
  99     GGConnect,
 100     NUM_TYPE
 101   } mType;
 102
 103   /// Indicates the actual log entry.
 104   ///
 105   /// This contains a description of the event being logged.
 106   /// For instance, "unable to access file", or "player connected
 107   /// successfully", or nearly anything else you might imagine.
 108   ///
 109   /// Typically, the description should contain a concise, descriptive
 110   /// string describing whatever is being logged. Whenever possible,
 111   /// include useful details like the name of the file being accessed,
 112   /// or the id of the player or GuiControl, so that if a log needs
 113   /// to be used to locate a bug, it can be done as painlessly as
 114   /// possible.
 115   const char *mString;
 116};
 117
 118typedef const char *StringTableEntry;
 119extern char *typeValueEmpty;
 120
 121class ConsoleValue
 122{
 123public:
 124   
 125   enum
 126   {
 127      TypeInternalInt = -5,
 128      TypeInternalFloat = -4,
 129      TypeInternalStringStackPtr = -3,
 130      TypeInternalStackString = -2,
 131      TypeInternalString = -1,
 132   };
 133   
 134   S32 type;
 135   
 136public:
 137   
 138   // NOTE: This is protected to ensure no one outside
 139   // of this structure is messing with it.
 140   
 141#pragma warning( push )
 142#pragma warning( disable : 4201 ) // warning C4201: nonstandard extension used : nameless struct/union
 143   
 144   // An variable is either a real dynamic type or
 145   // its one exposed from C++ using a data pointer.
 146   //
 147   // We use this nameless union and struct setup
 148   // to optimize the memory usage.
 149   union
 150   {
 151      struct
 152      {
 153         char *sval;
 154         U32 ival;  // doubles as strlen when type is TypeInternalString
 155         F32 fval;
 156         U32 bufferLen;
 157      };
 158      
 159      struct
 160      {
 161         /// The real data pointer.
 162         void *dataPtr;
 163         
 164         /// The enum lookup table for enumerated types.
 165         const EnumTable *enumTable;
 166      };
 167   };
 168   
 169   U32 getIntValue();
 170   S32 getSignedIntValue();
 171   F32 getFloatValue();
 172   const char *getStringValue();
 173   StringStackPtr getStringStackPtr();
 174   bool getBoolValue();
 175   
 176   void setIntValue(U32 val);
 177   void setIntValue(S32 val);
 178   void setFloatValue(F32 val);
 179   void setStringValue(const char *value);
 180   void setStackStringValue(const char *value);
 181   void setStringStackPtrValue(StringStackPtr ptr);
 182   void setBoolValue(bool val);
 183   
 184   void init()
 185   {
 186      ival = 0;
 187      fval = 0;
 188      sval = typeValueEmpty;
 189      bufferLen = 0;
 190      type = TypeInternalString;
 191   }
 192   
 193   void cleanup()
 194   {
 195      if ((type <= TypeInternalString) && (bufferLen > 0))
 196      {
 197         dFree(sval);
 198         bufferLen = 0;
 199      }
 200      sval = typeValueEmpty;
 201      type = ConsoleValue::TypeInternalString;
 202      ival = 0;
 203      fval = 0;
 204   }
 205   ConsoleValue(){ init(); };
 206   ~ConsoleValue(){ cleanup(); };
 207};
 208
 209// Proxy class for console variables
 210// Can point to existing console variables,
 211// or act like a free floating value.
 212class ConsoleValueRef
 213{
 214public:
 215   ConsoleValue *value;
 216
 217   ConsoleValueRef() : value(0) { ; }
 218   ~ConsoleValueRef() { ; }
 219
 220   ConsoleValueRef(const ConsoleValueRef &ref);
 221
 222   static ConsoleValueRef fromValue(ConsoleValue *value) { ConsoleValueRef ref; ref.value = value; return ref; }
 223
 224   const char *getStringValue() { return value ? value->getStringValue() : ""; }
 225   StringStackPtr getStringStackPtrValue() { return value ? value->getStringStackPtr() : 0; }
 226
 227   inline U32 getIntValue() { return value ? value->getIntValue() : 0; }
 228   inline S32 getSignedIntValue() { return value ? value->getSignedIntValue() : 0; }
 229   inline F32 getFloatValue() { return value ? value->getFloatValue() : 0.0f; }
 230   inline bool getBoolValue() { return value ? value->getBoolValue() : false; }
 231
 232   inline operator const char*() { return getStringValue(); }
 233   inline operator String() { return String(getStringValue()); }
 234   inline operator U32() { return getIntValue(); }
 235   inline operator S32() { return getSignedIntValue(); }
 236   inline operator F32() { return getFloatValue(); }
 237   inline operator bool() { return getBoolValue(); }
 238   
 239   inline bool isStringStackPtr() { return value ? value->type == ConsoleValue::TypeInternalStringStackPtr : false; }
 240   inline bool isString() { return value ? value->type >= ConsoleValue::TypeInternalStringStackPtr : true; }
 241   inline bool isInt() { return value ? value->type == ConsoleValue::TypeInternalInt : false; }
 242   inline bool isFloat() { return value ? value->type == ConsoleValue::TypeInternalFloat : false; }
 243   inline S32 getType() { return value ? value->type : -1; }
 244
 245   // Note: operators replace value
 246   ConsoleValueRef& operator=(const ConsoleValueRef &other);
 247   ConsoleValueRef& operator=(const char *newValue);
 248   ConsoleValueRef& operator=(U32 newValue);
 249   ConsoleValueRef& operator=(S32 newValue);
 250   ConsoleValueRef& operator=(F32 newValue);
 251   ConsoleValueRef& operator=(F64 newValue);
 252};
 253
 254// Overrides to allow ConsoleValueRefs to be directly converted to S32&F32
 255
 256inline S32 dAtoi(ConsoleValueRef &ref)
 257{
 258   return ref.getSignedIntValue();
 259}
 260
 261inline F32 dAtof(ConsoleValueRef &ref)
 262{
 263   return ref.getFloatValue();
 264}
 265
 266inline bool dAtob(ConsoleValue &ref)
 267{
 268   return ref.getBoolValue();
 269}
 270
 271
 272// Transparently converts ConsoleValue[] to const char**
 273class StringStackWrapper
 274{
 275public:
 276   const char **argv;
 277   int argc;
 278
 279   StringStackWrapper(int targc, ConsoleValueRef targv[]);
 280   ~StringStackWrapper();
 281
 282   const char* operator[](int idx) { return argv[idx]; }
 283   operator const char**() { return argv; }
 284
 285   int count() { return argc; }
 286};
 287
 288// Transparently converts const char** to ConsoleValue
 289class StringStackConsoleWrapper
 290{
 291public:
 292   ConsoleValue *argvValue;
 293   ConsoleValueRef *argv;
 294   int argc;
 295
 296   StringStackConsoleWrapper(int targc, const char **targv);
 297   ~StringStackConsoleWrapper();
 298
 299   ConsoleValueRef& operator[](int idx) { return argv[idx]; }
 300   operator ConsoleValueRef*() { return argv; }
 301
 302   int count() { return argc; }
 303};
 304
 305/// @defgroup console_callbacks Scripting Engine Callbacks
 306///
 307/// The scripting engine makes heavy use of callbacks to represent
 308/// function exposed to the scripting language. StringCallback,
 309/// IntCallback, FloatCallback, VoidCallback, and BoolCallback all
 310/// represent exposed script functions returning different types.
 311///
 312/// ConsumerCallback is used with the function Con::addConsumer; functions
 313/// registered with Con::addConsumer are called whenever something is outputted
 314/// to the console. For instance, the TelnetConsole registers itself with the
 315/// console so it can echo the console over the network.
 316///
 317/// @note Callbacks to the scripting language - for instance, onExit(), which is
 318///       a script function called when the engine is shutting down - are handled
 319///       using Con::executef() and kin.
 320/// @{
 321
 322///
 323typedef const char * (*StringCallback)(SimObject *obj, S32 argc, ConsoleValueRef argv[]);
 324typedef S32             (*IntCallback)(SimObject *obj, S32 argc, ConsoleValueRef argv[]);
 325typedef F32           (*FloatCallback)(SimObject *obj, S32 argc, ConsoleValueRef argv[]);
 326typedef void           (*VoidCallback)(SimObject *obj, S32 argc, ConsoleValueRef argv[]); // We have it return a value so things don't break..
 327typedef bool           (*BoolCallback)(SimObject *obj, S32 argc, ConsoleValueRef argv[]);
 328
 329typedef void (*ConsumerCallback)(U32 level, const char *consoleLine);
 330/// @}
 331
 332/// @defgroup console_types Scripting Engine Type Functions
 333///
 334/// @see Con::registerType
 335/// @{
 336typedef const char* (*GetDataFunction)(void *dptr, EnumTable *tbl, BitSet32 flag);
 337typedef void        (*SetDataFunction)(void *dptr, S32 argc, const char **argv, EnumTable *tbl, BitSet32 flag);
 338/// @}
 339
 340/// This namespace contains the core of the console functionality.
 341///
 342/// @section con_intro Introduction
 343///
 344/// The console is a key part of Torque's architecture. It allows direct run-time control
 345/// of many aspects of the engine.
 346///
 347/// @nosubgrouping
 348namespace Con
 349{
 350   /// Various configuration constants.
 351   enum Constants 
 352   {
 353      /// This is the version number associated with DSO files.
 354      ///
 355      /// If you make any changes to the way the scripting language works
 356      /// (such as DSO format changes, adding/removing op-codes) that would
 357      /// break compatibility, then you should increment this.
 358      ///
 359      /// If you make a really major change, increment it to the next multiple
 360      /// of ten.
 361      ///
 362      /// 12/29/04 - BJG - 33->34 Removed some opcodes, part of namespace upgrade.
 363      /// 12/30/04 - BJG - 34->35 Reordered some things, further general shuffling.
 364      /// 11/03/05 - BJG - 35->36 Integrated new debugger code.
 365      //  09/08/06 - THB - 36->37 New opcode for internal names
 366      //  09/15/06 - THB - 37->38 Added unit conversions
 367      //  11/23/06 - THB - 38->39 Added recursive internal name operator
 368      //  02/15/07 - THB - 39->40 Bumping to 40 for TGB since the console has been
 369      //                          majorly hacked without the version number being bumped
 370      //  02/16/07 - THB - 40->41 newmsg operator
 371      //  06/15/07 - THB - 41->42 script types
 372      /// 07/31/07 - THB - 42->43 Patch from Andreas Kirsch: Added opcode to support nested new declarations.
 373      /// 09/12/07 - CAF - 43->44 remove newmsg operator
 374      /// 09/27/07 - RDB - 44->45 Patch from Andreas Kirsch: Added opcode to support correct void return
 375      /// 01/13/09 - TMS - 45->46 Added script assert
 376      /// 09/07/14 - jamesu - 46->47 64bit support
 377      /// 10/14/14 - jamesu - 47->48 Added opcodes to reduce reliance on strings in function calls
 378      DSOVersion = 48,
 379
 380      MaxLineLength = 512,  ///< Maximum length of a line of console input.
 381      MaxDataTypes = 256    ///< Maximum number of registered data types.
 382   };
 383
 384   /// @name Control Functions
 385   ///
 386   /// The console must be initialized and shutdown appropriately during the
 387   /// lifetime of the app. These functions are used to manage this behavior.
 388   ///
 389   /// @note Torque deals with this aspect of console management, so you don't need
 390   ///       to call these functions in normal usage of the engine.
 391   /// @{
 392
 393   /// Initializes the console.
 394   ///
 395   /// This performs the following steps:
 396   ///   - Calls Namespace::init() to initialize the scripting namespace hierarchy.
 397   ///   - Calls ConsoleConstructor::setup() to initialize globally defined console
 398   ///     methods and functions.
 399   ///   - Registers some basic global script variables.
 400   ///   - Calls AbstractClassRep::init() to initialize Torque's class database.
 401   ///   - Registers some basic global script functions that couldn't usefully
 402   ///     be defined anywhere else.
 403   void init();
 404
 405   /// Shuts down the console.
 406   ///
 407   /// This performs the following steps:
 408   ///   - Closes the console log file.
 409   ///   - Calls Namespace::shutdown() to shut down the scripting namespace hierarchy.
 410   void shutdown();
 411
 412   /// Is the console active at this time?
 413   bool isActive();
 414
 415   /// @}
 416
 417   /// @name Console Consumers
 418   ///
 419   /// The console distributes its output through Torque by using
 420   /// consumers. Every time a new line is printed to the console,
 421   /// all the ConsumerCallbacks registered using addConsumer are
 422   /// called, in order.
 423   ///
 424   /// @note The GuiConsole control, which provides the on-screen
 425   ///       in-game console, uses a different technique to render
 426   ///       the console. It calls getLockLog() to lock the Vector
 427   ///       of on-screen console entries, then it renders them as
 428   ///       needed. While the Vector is locked, the console will
 429   ///       not change the Vector. When the GuiConsole control is
 430   ///       done with the console entries, it calls unlockLog()
 431   ///       to tell the console that it is again safe to modify
 432   ///       the Vector.
 433   ///
 434   /// @see TelnetConsole
 435   /// @see TelnetDebugger
 436   /// @see WinConsole
 437   /// @see MacCarbConsole
 438   /// @see StdConsole
 439   /// @see ConsoleLogger
 440   ///
 441   /// @{
 442
 443   ///
 444   void addConsumer(ConsumerCallback cb);
 445   void removeConsumer(ConsumerCallback cb);
 446
 447   typedef JournaledSignal<void(RawData)> ConsoleInputEvent;
 448
 449   /// Called from the native consoles to provide lines of console input
 450   /// to process. This will schedule it for execution ASAP.
 451   extern ConsoleInputEvent smConsoleInput;
 452
 453   /// @}
 454
 455   /// @name Miscellaneous
 456   /// @{
 457
 458   /// Remove color marking information from a string.
 459   ///
 460   /// @note It does this in-place, so be careful! It may
 461   ///       potentially blast data if you're not careful.
 462   ///       When in doubt, make a copy of the string first.
 463   void stripColorChars(char* line);
 464
 465   /// Convert from a relative script path to an absolute script path.
 466   ///
 467   /// This is used in (among other places) the exec() script function, which
 468   /// takes a parameter indicating a script file and executes it. Script paths
 469   /// can be one of:
 470   ///      - <b>Absolute:</b> <i>fps/foo/bar.cs</i> Paths of this sort are passed
 471   ///        through.
 472   ///      - <b>Mod-relative:</b> <i>~/foo/bar.cs</i> Paths of this sort have their
 473   ///        replaced with the name of the current mod.
 474   ///      - <b>File-relative:</b> <i>./baz/blip.cs</i> Paths of this sort are
 475   ///        calculated relative to the path of the current scripting file.
 476   ///
 477   /// @note This function determines paths relative to the currently executing
 478   ///       CodeBlock. Calling it outside of script execution will result in
 479   ///       it directly copying src to filename, since it won't know to what the
 480   ///       path is relative!
 481   ///
 482   /// @param  filename    Pointer to string buffer to fill with absolute path.
 483   /// @param  size        Size of buffer pointed to by filename.
 484   /// @param  src         Original, possibly relative script path.
 485   bool expandScriptFilename(char *filename, U32 size, const char *src);
 486   bool expandGameScriptFilename(char *filename, U32 size, const char *src);
 487   bool expandToolScriptFilename(char *filename, U32 size, const char *src);
 488   bool collapseScriptFilename(char *filename, U32 size, const char *src);
 489
 490   bool expandPath(char* pDstPath, U32 size, const char* pSrcPath, const char* pWorkingDirectoryHint = NULL, const bool ensureTrailingSlash = false);
 491   void collapsePath(char* pDstPath, U32 size, const char* pSrcPath, const char* pWorkingDirectoryHint = NULL);
 492   bool isBasePath(const char* SrcPath, const char* pBasePath);
 493   void ensureTrailingSlash(char* pDstPath, const char* pSrcPath);
 494   bool stripRepeatSlashes(char* pDstPath, const char* pSrcPath, S32 dstSize);
 495   StringTableEntry getDSOPath(const char *scriptPath);
 496
 497   void addPathExpando(const char* pExpandoName, const char* pPath);
 498   void removePathExpando(const char* pExpandoName);
 499   bool isPathExpando(const char* pExpandoName);
 500   StringTableEntry getPathExpando(const char* pExpandoName);
 501   U32 getPathExpandoCount(void);
 502   StringTableEntry getPathExpandoKey(U32 expandoIndex);
 503   StringTableEntry getPathExpandoValue(U32 expandoIndex);
 504
 505   bool isCurrentScriptToolScript();
 506
 507   StringTableEntry getModNameFromPath(const char *path);
 508
 509   /// Returns true if fn is a global scripting function.
 510   ///
 511   /// This looks in the global namespace. It also checks to see if fn
 512   /// is in the StringTable; if not, it returns false.
 513   bool isFunction(const char *fn);
 514
 515   /// This is the basis for tab completion in the console.
 516   ///
 517   /// @note This is an internally used function. You probably don't
 518   ///       care much about how this works.
 519   ///
 520   /// This function does some basic parsing to try to ascertain the namespace in which
 521   /// we are attempting to do tab completion, then bumps control off to the appropriate
 522   /// tabComplete function, either in SimObject or Namespace.
 523   ///
 524   /// @param  inputBuffer     Pointer to buffer containing starting data, or last result.
 525   /// @param  cursorPos       Location of cursor in this buffer. This is used to indicate
 526   ///                         what part of the string should be kept and what part should
 527   ///                         be advanced to the next match if any.
 528   /// @param  maxResultLength Maximum amount of result data to put into inputBuffer. This
 529   ///                         is capped by MaxCompletionBufferSize.
 530   /// @param  forwardTab      Should we go forward to next match or backwards to previous
 531   ///                         match? True indicates forward.
 532   U32 tabComplete(char* inputBuffer, U32 cursorPos, U32 maxResultLength, bool forwardTab);
 533
 534   /// @}
 535
 536
 537   /// @name Variable Management
 538   /// @{
 539
 540   /// The delegate signature for the variable assignment notifications.
 541   ///
 542   /// @see addVariableNotify, removeVariableNotify
 543   typedef Delegate<void()> NotifyDelegate;
 544
 545   /// Add a console variable that references the value of a variable in C++ code.
 546   ///
 547   /// If a value is assigned to the console variable the C++ variable is updated,
 548   /// and vice-versa.
 549   ///
 550   /// @param name      Global console variable name to create.
 551   /// @param type      The type of the C++ variable; see the ConsoleDynamicTypes enum for a complete list.
 552   /// @param pointer   Pointer to the variable.
 553   /// @param usage     Documentation string.
 554   ///
 555   /// @see ConsoleDynamicTypes
 556   void addVariable( const char *name, 
 557                     S32 type, 
 558                     void *pointer, 
 559                     const char* usage = NULL );
 560                     
 561   /// Add a console constant that references the value of a constant in C++ code.
 562   ///
 563   /// @param name      Global console constant name to create.
 564   /// @param type      The type of the C++ constant; see the ConsoleDynamicTypes enum for a complete list.
 565   /// @param pointer   Pointer to the constant.
 566   /// @param usage     Documentation string.
 567   ///
 568   /// @see ConsoleDynamicTypes
 569   void addConstant( const char *name, 
 570                     S32 type, 
 571                     const void *pointer, 
 572                     const char* usage = NULL );
 573                     
 574   /// Remove a console variable.
 575   ///
 576   /// @param name   Global console variable name to remove
 577   /// @return       true if variable existed before removal.
 578   bool removeVariable(const char *name);
 579
 580   /// Add a callback for notification when a variable
 581   /// is assigned a new value.
 582   ///
 583   /// @param name      An existing global console variable name.
 584   /// @param callback  The notification delegate function.
 585   ///
 586   void addVariableNotify( const char *name, const NotifyDelegate &callback );
 587
 588   /// Remove an existing variable assignment notification callback.
 589   ///
 590   /// @param name      An existing global console variable name.
 591   /// @param callback  The notification delegate function.
 592   ///
 593   void removeVariableNotify( const char *name, const NotifyDelegate &callback );
 594
 595   /// Assign a string value to a locally scoped console variable
 596   ///
 597   /// @note The context of the variable is determined by gEvalState; that is,
 598   ///       by the currently executing code.
 599   ///
 600   /// @param name   Local console variable name to set
 601   /// @param value  String value to assign to name
 602   void setLocalVariable(const char *name, const char *value);
 603
 604   /// Retrieve the string value to a locally scoped console variable
 605   ///
 606   /// @note The context of the variable is determined by gEvalState; that is,
 607   ///       by the currently executing code.
 608   ///
 609   /// @param name   Local console variable name to get
 610   const char* getLocalVariable(const char* name);
 611
 612   /// @}
 613
 614   /// @name Global Variable Accessors
 615   /// @{
 616   /// Assign a string value to a global console variable
 617   /// @param name   Global console variable name to set
 618   /// @param value  String value to assign to this variable.
 619   void setVariable(const char *name, const char *value);
 620
 621   /// Retrieve the string value of a global console variable
 622   /// @param name   Global Console variable name to query
 623   /// @return       The string value of the variable or "" if the variable does not exist.
 624   const char* getVariable(const char* name);
 625
 626   /// Retrieve the string value of an object field
 627   /// @param name   "object.field" string to query
 628   /// @return       The string value of the variable or NULL if no object is specified
 629   const char* getObjectField(const char* name);
 630
 631   /// Same as setVariable(), but for bools.
 632   void setBoolVariable (const char* name,bool var);
 633
 634   /// Same as getVariable(), but for bools.
 635   ///
 636   /// @param  name  Name of the variable.
 637   /// @param  def   Default value to supply if no matching variable is found.
 638   bool getBoolVariable (const char* name,bool def = false);
 639
 640   /// Same as setVariable(), but for ints.
 641   void setIntVariable  (const char* name,S32 var);
 642
 643   /// Same as getVariable(), but for ints.
 644   ///
 645   /// @param  name  Name of the variable.
 646   /// @param  def   Default value to supply if no matching variable is found.
 647   S32  getIntVariable  (const char* name,S32 def = 0);
 648
 649   /// Same as setVariable(), but for floats.
 650   void setFloatVariable(const char* name,F32 var);
 651
 652   /// Same as getVariable(), but for floats.
 653   ///
 654   /// @param  name  Name of the variable.
 655   /// @param  def   Default value to supply if no matching variable is found.
 656   F32  getFloatVariable(const char* name,F32 def = .0f);
 657
 658   /// @}
 659
 660   /// @name Global Function Registration
 661   /// @{
 662
 663   /// Register a C++ function with the console making it a global function callable from the scripting engine.
 664   ///
 665   /// @param name      Name of the new function.
 666   /// @param cb        Pointer to the function implementing the scripting call; a console callback function returning a specific type value.
 667   /// @param usage     Documentation for this function. @ref console_autodoc
 668   /// @param minArgs   Minimum number of arguments this function accepts
 669   /// @param maxArgs   Maximum number of arguments this function accepts
 670   /// @param toolOnly  Wether this is a TORQUE_TOOLS only function.
 671   /// @param header    The extended function header.
 672   void addCommand( const char* name, StringCallback cb, const char* usage, S32 minArgs, S32 maxArgs, bool toolOnly = false, ConsoleFunctionHeader* header = NULL );
 673
 674   void addCommand( const char* name, IntCallback    cb, const char* usage, S32 minArgs, S32 maxArgs, bool toolOnly = false, ConsoleFunctionHeader* header = NULL ); ///< @copydoc addCommand( const char *, StringCallback, const char *, S32, S32, bool, ConsoleFunctionHeader* )
 675   void addCommand( const char* name, FloatCallback  cb, const char* usage, S32 minArgs, S32 maxArgs, bool toolOnly = false, ConsoleFunctionHeader* header = NULL ); ///< @copydoc addCommand( const char *, StringCallback, const char *, S32, S32, bool, ConsoleFunctionHeader* )
 676   void addCommand( const char* name, VoidCallback   cb, const char* usage, S32 minArgs, S32 maxArgs, bool toolOnly = false, ConsoleFunctionHeader* header = NULL ); ///< @copydoc addCommand( const char *, StringCallback, const char *, S32, S32, bool, ConsoleFunctionHeader* )
 677   void addCommand( const char* name, BoolCallback   cb, const char* usage, S32 minArgs, S32 maxArgs, bool toolOnly = false, ConsoleFunctionHeader* header = NULL ); ///< @copydoc addCommand( const char *, StringCallback, const char *, S32, S32, bool, ConsoleFunctionHeader* )
 678   
 679   /// @}
 680
 681   /// @name Namespace Function Registration
 682   /// @{
 683
 684   /// Register a C++ function with the console making it callable
 685   /// as a method of the given namespace from the scripting engine.
 686   ///
 687   /// @param nameSpace Name of the namespace to associate the new function with; this is usually the name of a class.
 688   /// @param name      Name of the new function.
 689   /// @param cb        Pointer to the function implementing the scripting call; a console callback function returning a specific type value.
 690   /// @param usage     Documentation for this function. @ref console_autodoc
 691   /// @param minArgs   Minimum number of arguments this function accepts
 692   /// @param maxArgs   Maximum number of arguments this function accepts
 693   /// @param toolOnly  Wether this is a TORQUE_TOOLS only function.
 694   /// @param header    The extended function header.
 695   void addCommand(const char *nameSpace, const char *name,StringCallback cb, const char *usage, S32 minArgs, S32 maxArgs, bool toolOnly = false, ConsoleFunctionHeader* header = NULL );
 696
 697   void addCommand(const char *nameSpace, const char *name,IntCallback cb,    const char *usage, S32 minArgs, S32 maxArgs, bool toolOnly = false, ConsoleFunctionHeader* header = NULL ); ///< @copydoc addCommand( const char*, const char *, StringCallback, const char *, S32, S32, bool, ConsoleFunctionHeader* )
 698   void addCommand(const char *nameSpace, const char *name,FloatCallback cb,  const char *usage, S32 minArgs, S32 maxArgs, bool toolOnly = false, ConsoleFunctionHeader* header = NULL ); ///< @copydoc addCommand( const char*, const char *, StringCallback, const char *, S32, S32, bool, ConsoleFunctionHeader* )
 699   void addCommand(const char *nameSpace, const char *name,VoidCallback cb,   const char *usage, S32 minArgs, S32 maxArgs, bool toolOnly = false, ConsoleFunctionHeader* header = NULL ); ///< @copydoc addCommand( const char*, const char *, StringCallback, const char *, S32, S32, bool, ConsoleFunctionHeader* )
 700   void addCommand(const char *nameSpace, const char *name,BoolCallback cb,   const char *usage, S32 minArgs, S32 maxArgs, bool toolOnly = false, ConsoleFunctionHeader* header = NULL ); ///< @copydoc addCommand( const char*, const char *, StringCallback, const char *, S32, S32, bool, ConsoleFunctionHeader* )
 701
 702   /// @}
 703
 704   /// @name Special Purpose Registration
 705   ///
 706   /// These are special-purpose functions that exist to allow commands to be grouped, so
 707   /// that when we generate console docs, they can be more meaningfully presented.
 708   ///
 709   /// @ref console_autodoc "Click here for more information about console docs and grouping."
 710   ///
 711   /// @{
 712
 713   void markCommandGroup (const char * nsName, const char *name, const char* usage=<a href="/coding/file/types_8lint_8h/#types_8lint_8h_1a070d2ce7b6bb7e5c05602aa8c308d0c4">NULL</a>);
 714   void beginCommandGroup(const char * nsName, const char *name, const char* usage);
 715   void endCommandGroup  (const char * nsName, const char *name);
 716
 717   void noteScriptCallback( const char *className, const char *funcName, const char *usage, ConsoleFunctionHeader* header = NULL );
 718
 719   /// @}
 720
 721   /// @name Console Output
 722   ///
 723   /// These functions process the formatted string and pass it to all the ConsumerCallbacks that are
 724   /// currently registered. The console log file and the console window callbacks are installed by default.
 725   ///
 726   /// @see addConsumer()
 727   /// @see removeConsumer()
 728   /// @{
 729
 730   /// @param _format   A stdlib printf style formatted out put string
 731   /// @param ...       Variables to be written
 732   void printf(const char *_format, ...);
 733
 734   /// @note The console window colors warning text as LIGHT GRAY.
 735   /// @param _format   A stdlib printf style formatted out put string
 736   /// @param ...       Variables to be written
 737   void warnf(const char *_format, ...);
 738
 739   /// @note The console window colors warning text as RED.
 740   /// @param _format   A stdlib printf style formatted out put string
 741   /// @param ...       Variables to be written
 742   void errorf(const char *_format, ...);
 743
 744   /// @note The console window colors warning text as LIGHT GRAY.
 745   /// @param type      Allows you to associate the warning message with an internal module.
 746   /// @param _format   A stdlib printf style formatted out put string
 747   /// @param ...       Variables to be written
 748   /// @see Con::warnf()
 749   void warnf(ConsoleLogEntry::Type type, const char *_format, ...);
 750
 751   /// @note The console window colors warning text as RED.
 752   /// @param type      Allows you to associate the warning message with an internal module.
 753   /// @param _format   A stdlib printf style formatted out put string
 754   /// @param ...       Variables to be written
 755   /// @see Con::errorf()
 756   void errorf(ConsoleLogEntry::Type type, const char *_format, ...);
 757
 758   //some additions from t2d
 759   /// Prints a separator to the console.
 760   inline void printSeparator(void) { printf("--------------------------------------------------------------------------------"); }
 761
 762   /// Prints a separator to the console.
 763   inline void printBlankLine(void) { printf(""); }
 764
 765   /// @}
 766
 767   /// Returns true when called from the main thread, false otherwise
 768   bool isMainThread();
 769
 770
 771   /// @name Console Execution
 772   ///
 773   /// These are functions relating to the execution of script code.
 774   ///
 775   /// @{
 776
 777   /// Call a script function from C/C++ code.
 778   ///
 779   /// @param argc      Number of elements in the argv parameter
 780   /// @param argv      A character string array containing the name of the function
 781   ///                  to call followed by the arguments to that function.
 782   /// @code
 783   /// // Call a Torque script function called mAbs, having one parameter.
 784   /// char* argv[] = {"abs", "-9"};
 785   /// char* result = execute(2, argv);
 786   /// @endcode
 787   /// NOTE: this function restores the console stack on return.
 788   ConsoleValueRef execute(S32 argc, const char* argv[]);
 789   ConsoleValueRef execute(S32 argc, ConsoleValueRef argv[]);
 790
 791   /// Call a Torque Script member function of a SimObject from C/C++ code.
 792   /// @param object    Object on which to execute the method call.
 793   /// @param argc      Number of elements in the argv parameter (must be >2, see argv)
 794   /// @param argv      A character string array containing the name of the member function
 795   ///                  to call followed by an empty parameter (gets filled with object ID)
 796   ///                  followed by arguments to that function.
 797   /// @code
 798   /// // Call the method setMode() on an object, passing it one parameter.
 799   ///
 800   /// char* argv[] = {"setMode", "", "2"};
 801   /// char* result = execute(mysimobject, 3, argv);
 802   /// @endcode
 803   /// NOTE: this function restores the console stack on return.
 804   ConsoleValueRef execute(SimObject *object, S32 argc, const char* argv[], bool thisCallOnly = false);
 805   ConsoleValueRef execute(SimObject *object, S32 argc, ConsoleValueRef argv[], bool thisCallOnly = false);
 806
 807   /// Executes a script file and compiles it for use in script.
 808   ///
 809   /// @param  string   File name that is the script to be executed and compiled.
 810   /// @param fileName Path to the file to execute
 811   /// @param noCalls Deprecated
 812   /// @param journalScript Deprecated
 813   ///
 814   /// @return True if the script was successfully executed, false if not.
 815   bool executeFile(const char* fileName, bool noCalls, bool journalScript);
 816
 817   /// Evaluate an arbitrary chunk of code.
 818   ///
 819   /// @param  string   Buffer containing code to execute.
 820   /// @param  echo     Should we echo the string to the console?
 821   /// @param  fileName Indicate what file this code is coming from; used in error reporting and such.
 822   /// NOTE: This function restores the console stack on return.
 823   ConsoleValueRef evaluate(const char* string, bool echo = false, const char *fileName = NULL);
 824
 825   /// Evaluate an arbitrary line of script.
 826   ///
 827   /// This wraps dVsprintf(), so you can substitute parameters into the code being executed.
 828   /// NOTE: This function restores the console stack on return.
 829   ConsoleValueRef evaluatef(const char* string, ...);
 830
 831   /// @}
 832
 833   /// @name Console Function Implementation Helpers
 834   ///
 835   /// The functions Con::getIntArg, Con::getFloatArg and Con::getArgBuffer(size) are used to
 836   /// allocate on the console stack string variables that will be passed into the next console
 837   //  function called.  This allows the console to avoid copying some data.
 838   ///
 839   /// getReturnBuffer lets you allocate stack space to return data in.
 840   /// @{
 841
 842   ///
 843   char* getReturnBuffer(U32 bufferSize);
 844   char* getReturnBuffer(const char *stringToCopy);
 845   char* getReturnBuffer( const String& str );
 846   char* getReturnBuffer( const StringBuilder& str );
 847
 848   char* getArgBuffer(U32 bufferSize);
 849   char* getFloatArg(F64 arg);
 850   char* getIntArg  (S32 arg);
 851   char* getBoolArg(bool arg);
 852   char* getStringArg( const char* arg );
 853   char* getStringArg( const String& arg );
 854   /// @}
 855
 856   /// @name Namespaces
 857   /// @{
 858
 859   Namespace *lookupNamespace(const char *nsName);
 860   bool linkNamespaces(const char *parentName, const char *childName);
 861   bool unlinkNamespaces(const char *parentName, const char *childName);
 862
 863   /// @note This should only be called from consoleObject.h
 864   bool classLinkNamespaces(Namespace *parent, Namespace *child);
 865
 866   const char *getNamespaceList(Namespace *ns);
 867   /// @}
 868
 869   /// @name Logging
 870   /// @{
 871
 872   void getLockLog(ConsoleLogEntry * &log, U32 &size);
 873   void unlockLog(void);
 874   void setLogMode(S32 mode);
 875
 876   /// @}
 877
 878   /// @name Instant Group
 879   /// @{
 880
 881   void pushInstantGroup( String name = String() );
 882   void popInstantGroup();
 883
 884   /// @}
 885
 886   /// @name Dynamic Type System
 887   /// @{
 888
 889   void setData(S32 type, void *dptr, S32 index, S32 argc, const char **argv, const EnumTable *tbl = NULL, BitSet32 flag = 0);
 890   const char *getData(S32 type, void *dptr, S32 index, const EnumTable *tbl = NULL, BitSet32 flag = 0);
 891   const char *getFormattedData(S32 type, const char *data, const EnumTable *tbl = NULL, BitSet32 flag = 0);
 892
 893   /// @}
 894};
 895
 896struct _EngineConsoleCallbackHelper;
 897template<typename P1> struct _EngineConsoleExecCallbackHelper;
 898
 899namespace Con
 900{
 901   /// @name Console Execution - executef
 902   /// {
 903   ///
 904   /// Implements a script function thunk which automatically converts parameters to relevant console types.
 905   /// Can be used as follows:
 906   /// - Con::executef("functionName", ...);
 907   /// - Con::executef(mySimObject, "functionName", ...);
 908   /// 
 909   /// NOTE: if you get a rather cryptic template error coming through here, most likely you are trying to 
 910   /// convert a parameter which EngineMarshallType does not have a specialization for.
 911   /// Another problem can occur if you do not include "console/simBase.h" and "console/engineAPI.h" 
 912   /// since _EngineConsoleExecCallbackHelper and SimConsoleThreadExecCallback are required.
 913   ///
 914   /// @see _EngineConsoleExecCallbackHelper
 915   ///
 916   template<typename A> ConsoleValueRef executef(A a) { _EngineConsoleExecCallbackHelper<A> callback( a ); return callback.template call<ConsoleValueRef>(); }
 917   template<typename A, typename B> ConsoleValueRef executef(A a, B b) { _EngineConsoleExecCallbackHelper<A> callback( a ); return callback.template call<ConsoleValueRef>(b); }
 918   template<typename A, typename B, typename C> ConsoleValueRef executef(A a, B b, C c) { _EngineConsoleExecCallbackHelper<A> callback( a ); return callback.template call<ConsoleValueRef>(b, c); }
 919   template<typename A, typename B, typename C, typename D> ConsoleValueRef executef(A a, B b, C c, D d) { _EngineConsoleExecCallbackHelper<A> callback( a ); return callback.template call<ConsoleValueRef>(b, c, d); }
 920   template<typename A, typename B, typename C, typename D, typename E> ConsoleValueRef executef(A a, B b, C c, D d, E e) { _EngineConsoleExecCallbackHelper<A> callback( a ); return callback.template call<ConsoleValueRef>(b, c, d, e); }
 921   template<typename A, typename B, typename C, typename D, typename E, typename F> ConsoleValueRef executef(A a, B b, C c, D d, E e, F f) { _EngineConsoleExecCallbackHelper<A> callback( a ); return callback.template call<ConsoleValueRef>(b, c, d, e, f); }
 922   template<typename A, typename B, typename C, typename D, typename E, typename F, typename G> ConsoleValueRef executef(A a, B b, C c, D d, E e, F f, G g) { _EngineConsoleExecCallbackHelper<A> callback( a ); return callback.template call<ConsoleValueRef>(b, c, d, e, f, g); }
 923   template<typename A, typename B, typename C, typename D, typename E, typename F, typename G, typename H> ConsoleValueRef executef(A a, B b, C c, D d, E e, F f, G g, H h) { _EngineConsoleExecCallbackHelper<A> callback( a ); return callback.template call<ConsoleValueRef>(b, c, d, e, f, g, h); }
 924   template<typename A, typename B, typename C, typename D, typename E, typename F, typename G, typename H, typename I> ConsoleValueRef executef(A a, B b, C c, D d, E e, F f, G g, H h, I i) { _EngineConsoleExecCallbackHelper<A> callback( a ); return callback.template call<ConsoleValueRef>(b, c, d, e, f, g, h, i); }
 925   template<typename A, typename B, typename C, typename D, typename E, typename F, typename G, typename H, typename I, typename J> ConsoleValueRef executef(A a, B b, C c, D d, E e, F f, G g, H h, I i, J j) { _EngineConsoleExecCallbackHelper<A> callback( a ); return callback.template call<ConsoleValueRef>(b, c, d, e, f, g, h, i, j); }
 926   template<typename A, typename B, typename C, typename D, typename E, typename F, typename G, typename H, typename I, typename J, typename K> ConsoleValueRef executef(A a, B b, C c, D d, E e, F f, G g, H h, I i, J j, K k) { _EngineConsoleExecCallbackHelper<A> callback( a ); return callback.template call<ConsoleValueRef>(b, c, d, e, f, g, h, i, j, k); }
 927   template<typename A, typename B, typename C, typename D, typename E, typename F, typename G, typename H, typename I, typename J, typename K, typename L> ConsoleValueRef executef(A a, B b, C c, D d, E e, F f, G g, H h, I i, J j, K k, L l) { _EngineConsoleExecCallbackHelper<A> callback( a ); return callback.template call<ConsoleValueRef>(b, c, d, e, f, g, h, i, j, k, l); }
 928   /// }
 929};
 930
 931extern void expandEscape(char *dest, const char *src);
 932extern bool collapseEscape(char *buf);
 933extern U32 HashPointer(StringTableEntry ptr);
 934
 935
 936/// Extended information about a console function.
 937struct ConsoleFunctionHeader
 938{
 939   /// Return type string.
 940   const char* mReturnString;
 941   
 942   /// List of arguments taken by the function.  Used for documentation.
 943   const char* mArgString;
 944   
 945   /// List of default argument values.  Used for documentation.
 946   const char* mDefaultArgString;
 947   
 948   /// Whether this is a static method in a class.
 949   bool mIsStatic;
 950   
 951   ConsoleFunctionHeader(
 952      const char* returnString,
 953      const char* argString,
 954      const char* defaultArgString,
 955      bool isStatic = false )
 956      : mReturnString( returnString ),
 957        mArgString( argString ),
 958        mDefaultArgString( defaultArgString ),
 959        mIsStatic( isStatic ) {}
 960};
 961
 962
 963/// This is the backend for the ConsoleMethod()/ConsoleFunction() macros.
 964///
 965/// See the group ConsoleConstructor Innards for specifics on how this works.
 966///
 967/// @see @ref console_autodoc
 968/// @nosubgrouping
 969class ConsoleConstructor
 970{
 971public:
 972   /// @name Entry Type Fields
 973   ///
 974   /// One of these is set based on the type of entry we want
 975   /// inserted in the console.
 976   ///
 977   /// @ref console_autodoc
 978   /// @{
 979   
 980   StringCallback sc;   ///< A function/method that returns a string.
 981   IntCallback ic;      ///< A function/method that returns an int.
 982   FloatCallback fc;    ///< A function/method that returns a float.
 983   VoidCallback vc;     ///< A function/method that returns nothing.
 984   BoolCallback bc;     ///< A function/method that returns a bool.
 985   bool group;          ///< Indicates that this is a group marker.
 986   bool ns;             ///< Indicates that this is a namespace marker.
 987                        ///  @deprecated Unused.
 988   bool callback;       ///< Is this a callback into script?
 989   
 990   /// @}
 991
 992   /// Minimum number of arguments expected by the function.
 993   S32 mina;
 994   
 995   /// Maximum number of arguments accepted by the funtion.  Zero for varargs.
 996   S32 maxa;
 997      
 998   /// Name of the function/method.
 999   const char* funcName;
1000   
1001   /// Name of the class namespace to which to add the method.
1002   const char* className;
1003
1004   /// Usage string for documentation.
1005   const char* usage;
1006
1007   /// Whether this is a TORQUE_TOOLS only function.
1008   bool toolOnly;
1009   
1010   /// The extended function header.
1011   ConsoleFunctionHeader* header;
1012   
1013   /// @name ConsoleConstructor Innards
1014   ///
1015   /// The ConsoleConstructor class is used as the backend for the ConsoleFunction() and
1016   /// ConsoleMethod() macros. The way it works takes advantage of several properties of
1017   /// C++.
1018   ///
1019   /// The ConsoleFunction()/ConsoleMethod() macros wrap the declaration of a ConsoleConstructor.
1020   ///
1021   /// @code
1022   ///      // The definition of a ConsoleFunction using the macro
1023   ///      ConsoleFunction(ExpandFilename, const char*, 2, 2, "(string filename)")
1024   ///      {
1025   ///         argc;
1026   ///         char* ret = Con::getReturnBuffer( 1024 );
1027   ///         Con::expandScriptFilename(ret, 1024, argv[1]);
1028   ///         return ret;
1029   ///      }
1030   ///
1031   ///      // Resulting code
1032   ///      static const char* cExpandFilename(SimObject *, S32, const char **argv);
1033   ///      static ConsoleConstructor
1034   ///            gExpandFilenameobj(NULL,"ExpandFilename", cExpandFilename,
1035   ///            "(string filename)", 2, 2);
1036   ///      static const char* cExpandFilename(SimObject *, S32 argc, const char **argv)
1037   ///      {
1038   ///         argc;
1039   ///         char* ret = Con::getReturnBuffer( 1024 );
1040   ///         Con::expandScriptFilename(ret, 1024, argv[1]);
1041   ///         return ret;
1042   ///      }
1043   ///
1044   ///      // A similar thing happens when you do a ConsoleMethod.
1045   /// @endcode
1046   ///
1047   /// As you can see, several global items are defined when you use the ConsoleFunction method.
1048   /// The macro constructs the name of these items from the parameters you passed it. Your
1049   /// implementation of the console function is is placed in a function with a name based on
1050   /// the actual name of the console funnction. In addition, a ConsoleConstructor is declared.
1051   ///
1052   /// Because it is defined as a global, the constructor for the ConsoleConstructor is called
1053   /// before execution of main() is started. The constructor is called once for each global
1054   /// ConsoleConstructor variable, in the order in which they were defined (this property only holds true
1055   /// within file scope).
1056   ///
1057   /// We have ConsoleConstructor create a linked list at constructor time, by storing a static
1058   /// pointer to the head of the list, and keeping a pointer to the next item in each instance
1059   /// of ConsoleConstructor. init() is a helper function in this process, automatically filling
1060   /// in commonly used fields and updating first and next as needed. In this way, a list of
1061   /// items to add to the console is assemble in memory, ready for use, before we start
1062   /// execution of the program proper.
1063   ///
1064   /// In Con::init(), ConsoleConstructor::setup() is called to process this prepared list. Each
1065   /// item in the list is iterated over, and the appropriate Con namespace functions (usually
1066   /// Con::addCommand) are invoked to register the ConsoleFunctions and ConsoleMethods in
1067   /// the appropriate namespaces.
1068   ///
1069   /// @see Namespace
1070   /// @see Con
1071   /// @{
1072
1073   ///
1074   ConsoleConstructor *next;
1075   static ConsoleConstructor *first;
1076
1077   void init( const char* cName, const char* fName, const char *usg, S32 minArgs, S32 maxArgs, bool toolOnly = false, ConsoleFunctionHeader* header = NULL );
1078
1079   static void setup();
1080
1081   /// Validate there are no duplicate entries for this item.
1082   void validate();
1083
1084   /// @}
1085
1086   /// @name Basic Console Constructors
1087   /// @{
1088
1089   ConsoleConstructor( const char* className, const char* funcName, StringCallback sfunc, const char* usage,  S32 minArgs, S32 maxArgs, bool toolOnly = false, ConsoleFunctionHeader* header = NULL );
1090   ConsoleConstructor( const char* className, const char* funcName, IntCallback    ifunc, const char* usage,  S32 minArgs, S32 maxArgs, bool toolOnly = false, ConsoleFunctionHeader* header = NULL );
1091   ConsoleConstructor( const char* className, const char* funcName, FloatCallback  ffunc, const char* usage,  S32 minArgs, S32 maxArgs, bool toolOnly = false, ConsoleFunctionHeader* header = NULL );
1092   ConsoleConstructor( const char* className, const char* funcName, VoidCallback   vfunc, const char* usage,  S32 minArgs, S32 maxArgs, bool toolOnly = false, ConsoleFunctionHeader* header = NULL );
1093   ConsoleConstructor( const char* className, const char* funcName, BoolCallback   bfunc, const char* usage,  S32 minArgs, S32 maxArgs, bool toolOnly = false, ConsoleFunctionHeader* header = NULL );
1094   
1095   /// @}
1096
1097   /// @name Magic Console Constructors
1098   ///
1099   /// These perform various pieces of "magic" related to consoleDoc functionality.
1100   /// @ref console_autodoc
1101   /// @{
1102
1103   /// Indicates a group marker. (A doxygen illusion)
1104   ///
1105   /// @see Con::markCommandGroup
1106   /// @ref console_autodoc
1107   ConsoleConstructor( const char *className, const char *groupName, const char* usage );
1108
1109   /// Indicates a callback declared with the DECLARE_SCRIPT_CALLBACK macro and friends.
1110   ConsoleConstructor( const char *className, const char *callbackName, const char *usage, ConsoleFunctionHeader* header );
1111
1112   /// @}
1113};
1114
1115
1116/// An arbitrary fragment of auto-doc text for the script reference.
1117struct ConsoleDocFragment
1118{
1119   /// The class in which to put the fragment.  If NULL, the fragment
1120   /// will be placed globally.
1121   const char* mClass;
1122   
1123   /// The definition to output for this fragment.  NULL for fragments
1124   /// not associated with a definition.
1125   const char* mDefinition;
1126   
1127   /// The documentation text.
1128   const char* mText;
1129   
1130   /// Next fragment in the global link chain.
1131   ConsoleDocFragment* mNext;
1132   
1133   /// First fragment in the global link chain.
1134   static ConsoleDocFragment* smFirst;
1135   
1136   ConsoleDocFragment( const char* text, const char* inClass = NULL, const char* definition = NULL )
1137      : mClass( inClass ),
1138        mDefinition( definition ),
1139        mText( text ),
1140        mNext( smFirst )
1141   {
1142      smFirst = this;
1143   }
1144};
1145
1146
1147/// Utility class to save and restore the current console stack frame
1148///
1149class ConsoleStackFrameSaver
1150{
1151public:
1152
1153   bool mSaved;
1154
1155   ConsoleStackFrameSaver() : mSaved(false)
1156   {
1157   }
1158
1159   ~ConsoleStackFrameSaver()
1160   {
1161      restore();
1162   }
1163
1164   void save();
1165   void restore();
1166};
1167
1168
1169/// @name Global Console Definition Macros
1170///
1171/// @note If TORQUE_DEBUG is defined, then we gather documentation information, and
1172///       do some extra sanity checks.
1173///
1174/// @see ConsoleConstructor
1175/// @ref console_autodoc
1176/// @{
1177
1178
1179/// Define a C++ method that calls back to script on an object.
1180/// 
1181/// @see consoleCallback.h
1182#define DECLARE_CALLBACK( returnType, name, args )  \
1183   virtual returnType name ## _callback args
1184
1185// O hackery of hackeries
1186#define conmethod_return_const              return (const
1187#define conmethod_return_S32                return (S32
1188#define conmethod_return_F32                return (F32
1189#define conmethod_nullify(val)
1190#define conmethod_return_void               conmethod_nullify(void
1191#define conmethod_return_bool               return (bool
1192
1193#if !defined(TORQUE_SHIPPING)
1194
1195// Console function macros
1196#  define ConsoleFunctionGroupBegin(groupName, usage) \
1197      static ConsoleConstructor cfg_ConsoleFunctionGroup_##groupName##_GroupBegin(NULL,#groupName,usage)
1198
1199#  define ConsoleFunction(name,returnType,minArgs,maxArgs,usage1) \
1200   returnType cf_##name(SimObject *, S32, ConsoleValueRef *argv); \
1201   ConsoleConstructor cc_##name##_obj(NULL,#name,cf_##name,usage1,minArgs,maxArgs); \
1202      returnType cf_##name(SimObject *, S32 argc, ConsoleValueRef *argv)
1203
1204#  define ConsoleToolFunction(name,returnType,minArgs,maxArgs,usage1) \
1205   returnType ctf_##name(SimObject *, S32, ConsoleValueRef *argv); \
1206   ConsoleConstructor cc_##name##_obj(NULL,#name,ctf_##name,usage1,minArgs,maxArgs, true); \
1207   returnType ctf_##name(SimObject *, S32 argc, ConsoleValueRef *argv)
1208
1209#  define ConsoleFunctionGroupEnd(groupName) \
1210      static ConsoleConstructor cfg_##groupName##_GroupEnd(NULL,#groupName,NULL)
1211
1212// Console method macros
1213#  define ConsoleNamespace(className, usage) \
1214   ConsoleConstructor cc_##className##_Namespace(#className, usage)
1215
1216#  define ConsoleMethodGroupBegin(className, groupName, usage) \
1217   static ConsoleConstructor cc_##className##_##groupName##_GroupBegin(#className,#groupName,usage)
1218
1219#  define ConsoleMethod(className,name,returnType,minArgs,maxArgs,usage1) \
1220   inline returnType cm_##className##_##name(className *, S32, ConsoleValueRef *argv); \
1221   returnType cm_##className##_##name##_caster(SimObject *object, S32 argc, ConsoleValueRef *argv) { \
1222         AssertFatal( dynamic_cast<className*>( object ), "Object passed to " #name " is not a " #className "!" ); \
1223         conmethod_return_##returnType ) cm_##className##_##name(static_cast<className*>(object),argc,argv); \
1224      };                                                                                              \
1225      ConsoleConstructor cc_##className##_##name##_obj(#className,#name,cm_##className##_##name##_caster,usage1,minArgs,maxArgs); \
1226      inline returnType cm_##className##_##name(className *object, S32 argc, ConsoleValueRef *argv)
1227
1228#  define ConsoleStaticMethod(className,name,returnType,minArgs,maxArgs,usage1) \
1229   inline returnType cm_##className##_##name(S32, ConsoleValueRef *); \
1230   returnType cm_##className##_##name##_caster(SimObject *object, S32 argc, ConsoleValueRef *argv) { \
1231   conmethod_return_##returnType ) cm_##className##_##name(argc,argv); \
1232   }; \
1233   ConsoleConstructor \
1234   cc_##className##_##name##_obj(#className,#name,cm_##className##_##name##_caster,usage1,minArgs,maxArgs); \
1235   inline returnType cm_##className##_##name(S32 argc, ConsoleValueRef *argv)
1236
1237#  define ConsoleMethodGroupEnd(className, groupName) \
1238   static ConsoleConstructor cc_##className##_##groupName##_GroupEnd(#className,#groupName,NULL)
1239   
1240/// Add a fragment of auto-doc text to the console API reference.
1241/// @note There can only be one ConsoleDoc per source file.
1242#  define ConsoleDoc( text )                                \
1243      namespace {                                           \
1244         ConsoleDocFragment _sDocFragment( text );           \
1245      }
1246
1247#else
1248
1249// These do nothing if we don't want doc information.
1250#  define ConsoleFunctionGroupBegin(groupName, usage)
1251#  define ConsoleFunctionGroupEnd(groupName)
1252#  define ConsoleNamespace(className, usage)
1253#  define ConsoleMethodGroupBegin(className, groupName, usage)
1254#  define ConsoleMethodGroupEnd(className, groupName)
1255
1256// These are identical to what's above, we just want to null out the usage strings.
1257#  define ConsoleFunction(name,returnType,minArgs,maxArgs,usage1)                   \
1258      static returnType c##name(SimObject *, S32, ConsoleValueRef*);                   \
1259      static ConsoleConstructor g##name##obj(NULL,#name,c##name,"",minArgs,maxArgs);\
1260      static returnType c##name(SimObject *, S32 argc, ConsoleValueRef *argv)
1261
1262#  define ConsoleToolFunction(name,returnType,minArgs,maxArgs,usage1)                   \
1263   static returnType c##name(SimObject *, S32, ConsoleValueRef*);                   \
1264   static ConsoleConstructor g##name##obj(NULL,#name,c##name,"",minArgs,maxArgs, true);\
1265   static returnType c##name(SimObject *, S32 argc, ConsoleValueRef *argv)
1266
1267#  define ConsoleMethod(className,name,returnType,minArgs,maxArgs,usage1)                             \
1268      static inline returnType c##className##name(className *, S32, ConsoleValueRef *argv);               \
1269      static returnType c##className##name##caster(SimObject *object, S32 argc, ConsoleValueRef *argv) {  \
1270         conmethod_return_##returnType ) c##className##name(static_cast<className*>(object),argc,argv);              \
1271      };                                                                                              \
1272      static ConsoleConstructor                                                                       \
1273         className##name##obj(#className,#name,c##className##name##caster,"",minArgs,maxArgs);        \
1274      static inline returnType c##className##name(className *object, S32 argc, ConsoleValueRef *argv)
1275
1276#  define ConsoleStaticMethod(className,name,returnType,minArgs,maxArgs,usage1)                       \
1277      static inline returnType c##className##name(S32, ConsoleValueRef*);                                \
1278      static returnType c##className##name##caster(SimObject *object, S32 argc, ConsoleValueRef *argv) {  \
1279         conmethod_return_##returnType ) c##className##name(argc,argv);                                                        \
1280      };                                                                                              \
1281      static ConsoleConstructor                                                                       \
1282         className##name##obj(#className,#name,c##className##name##caster,"",minArgs,maxArgs);        \
1283      static inline returnType c##className##name(S32 argc, ConsoleValueRef *argv)
1284
1285#define ConsoleDoc( text )
1286
1287#endif
1288
1289/// @}
1290
1291/// @}
1292
1293#endif // _CONSOLE_H_
1294