Con

Engine/source/cinterface/c_consoleInterface.cpp

This namespace contains the core of the console functionality.

More...

Classes:

class

Con::CollapseTest

class

Con::PathExpando

class

Con::XMLExport

Console Consumers

The console distributes its output through Torque by using consumers.

Every time a new line is printed to the console, all the ConsumerCallbacks registered using addConsumer are called, in order.

note:
The GuiConsole control, which provides the on-screen in-game console, uses a different technique to render the console. It calls getLockLog() to lock the Vector of on-screen console entries, then it renders them as needed. While the Vector is locked, the console will not change the Vector. When the GuiConsole control is done with the console entries, it calls unlockLog() to tell the console that it is again safe to modify the Vector.

see:

TelnetConsole

see:

TelnetDebugger

see:

WinConsole

see:

MacCarbConsole

see:

StdConsole

see:

ConsoleLogger

void

addConsumer(ConsumerCallback consumer)

void

removeConsumer(ConsumerCallback consumer)

Con::ConsoleInputEvent

smConsoleInput

Called from the native consoles to provide lines of console input to process.

JournaledSignal< void(RawData)>

ConsoleInputEvent

Variable Management

void

setLocalVariable(const char * name, const char * value)

Assign a string value to a locally scoped console variable.

const char *

getLocalVariable(const char * name)

Retrieve the string value to a locally scoped console variable.

void

addVariable(const char * name, S32 type, void * pointer, const char * usage)

Add a console variable that references the value of a variable in C++ code.

void

addConstant(const char * name, S32 type, const void * pointer, const char * usage)

Add a console constant that references the value of a constant in C++ code.

bool

removeVariable(const char * name)

Remove a console variable.

void

addVariableNotify(const char * name, const NotifyDelegate & callback)

Add a callback for notification when a variable is assigned a new value.

void

removeVariableNotify(const char * name, const NotifyDelegate & callback)

Remove an existing variable assignment notification callback.

Delegate< void()>

NotifyDelegate

The delegate signature for the variable assignment notifications.

Public User Defined

StringTableEntry

gCurrentFile

Current script file name and root, these are registered as console variables.

StringTableEntry

gCurrentRoot

Namespaces

const char *

getNamespaceList(Namespace * ns)

Namespace *

lookupNamespace(const char * ns)

bool

linkNamespaces(const char * parent, const char * child)

bool

unlinkNamespaces(const char * parent, const char * child)

bool

classLinkNamespaces(Namespace * parent, Namespace * child)

Console Function Implementation Helpers

The functions Con::getIntArg, Con::getFloatArg and Con::getArgBuffer(size) are used to allocate on the console stack string variables that will be passed into the next console

char *

getReturnBuffer(U32 bufferSize)

getReturnBuffer lets you allocate stack space to return data in.

char *

getReturnBuffer(const char * stringToCopy)

char *

getReturnBuffer(const String & str)

char *

getReturnBuffer(const StringBuilder & str)

char *

getArgBuffer(U32 bufferSize)

char *

getFloatArg(F64 arg)

char *

getIntArg(S32 arg)

char *

getBoolArg(bool arg)

char *

getStringArg(const char * arg)

char *

getStringArg(const String & arg)

Control Functions

The console must be initialized and shutdown appropriately during the lifetime of the app.

These functions are used to manage this behavior.

note:
Torque deals with this aspect of console management, so you don't need to call these functions in normal usage of the engine.

void

init()

Initializes the console.

void

shutdown()

Shuts down the console.

bool

isActive()

Is the console active at this time?

Logging

void

getLockLog(ConsoleLogEntry *& log, U32 & size)

void

unlockLog()

void

setLogMode(S32 newMode)

Miscellaneous

U32

tabComplete(char * inputBuffer, U32 cursorPos, U32 maxResultLength, bool forwardTab)

This is the basis for tab completion in the console.

void

stripColorChars(char * line)

Remove color marking information from a string.

bool

isFunction(const char * fn)

Returns true if fn is a global scripting function.

bool

isCurrentScriptToolScript()

StringTableEntry

getModNameFromPath(const char * path)

void

addPathExpando(const char * pExpandoName, const char * pPath)

StringTableEntry

getPathExpando(const char * pExpandoName)

void

removePathExpando(const char * pExpandoName)

bool

isPathExpando(const char * pExpandoName)

U32

getPathExpandoCount(void )

StringTableEntry

getPathExpandoKey(U32 expandoIndex)

StringTableEntry

getPathExpandoValue(U32 expandoIndex)

bool

expandPath(char * pDstPath, U32 size, const char * pSrcPath, const char * pWorkingDirectoryHint, const bool ensureTrailingSlash)

bool

isBasePath(const char * SrcPath, const char * pBasePath)

void

collapsePath(char * pDstPath, U32 size, const char * pSrcPath, const char * pWorkingDirectoryHint)

void

ensureTrailingSlash(char * pDstPath, const char * pSrcPath, S32 dstSize)

StringTableEntry

getDSOPath(const char * scriptPath)

bool

stripRepeatSlashes(char * pDstPath, const char * pSrcPath, S32 dstSize)

bool

expandScriptFilename(char * filename, U32 size, const char * src)

Convert from a relative script path to an absolute script path.

bool

expandGameScriptFilename(char * filename, U32 size, const char * src)

bool

expandToolScriptFilename(char * filename, U32 size, const char * src)

bool

collapseScriptFilename(char * filename, U32 size, const char * src)

Console Output

These functions process the formatted string and pass it to all the ConsumerCallbacks that are currently registered.

The console log file and the console window callbacks are installed by default.

see:

addConsumer()

see:

removeConsumer()

void

printf(const char * _format, ... )

void

warnf(ConsoleLogEntry::Type type, const char * _format, ... )

void

errorf(ConsoleLogEntry::Type type, const char * _format, ... )

void

warnf(const char * _format, ... )

void

errorf(const char * _format, ... )

void

printSeparator(void )

Prints a separator to the console.

void

printBlankLine(void )

Prints a separator to the console.

Global Variable Accessors

Assign a string value to a global console variable

Parameters:

name	Global console variable name to set
value	String value to assign to this variable.

void

setVariable(const char * name, const char * value)

void

setBoolVariable(const char * varName, bool value)

Same as setVariable(), but for bools.

void

setIntVariable(const char * varName, S32 value)

Same as setVariable(), but for ints.

void

setFloatVariable(const char * varName, F32 value)

Same as setVariable(), but for floats.

const char *

getVariable(const char * name, const char * def)

Retrieve the string value of a global console variable.

bool

getBoolVariable(const char * name, bool def)

Same as getVariable(), but for bools.

S32

getIntVariable(const char * name, S32 def)

Same as getVariable(), but for ints.

F32

getFloatVariable(const char * name, F32 def)

Same as getVariable(), but for floats.

const char *

getObjectField(const char * name)

Retrieve the string value of an object field.

Namespace Function Registration

void

addCommand(const char * nameSpace, const char * name, StringCallback cb, const char * usage, S32 minArgs, S32 maxArgs, bool toolOnly, ConsoleFunctionHeader * header)

Register a C++ function with the console making it callable as a method of the given namespace from the scripting engine.

void

addCommand(const char * nameSpace, const char * name, VoidCallback cb, const char * usage, S32 minArgs, S32 maxArgs, bool toolOnly, ConsoleFunctionHeader * header)

Register a C++ function with the console making it callable as a method of the given namespace from the scripting engine.

void

addCommand(const char * nameSpace, const char * name, IntCallback cb, const char * usage, S32 minArgs, S32 maxArgs, bool toolOnly, ConsoleFunctionHeader * header)

Register a C++ function with the console making it callable as a method of the given namespace from the scripting engine.

void

addCommand(const char * nameSpace, const char * name, FloatCallback cb, const char * usage, S32 minArgs, S32 maxArgs, bool toolOnly, ConsoleFunctionHeader * header)

Register a C++ function with the console making it callable as a method of the given namespace from the scripting engine.

void

addCommand(const char * nameSpace, const char * name, BoolCallback cb, const char * usage, S32 minArgs, S32 maxArgs, bool toolOnly, ConsoleFunctionHeader * header)

Register a C++ function with the console making it callable as a method of the given namespace from the scripting engine.

Special Purpose Registration

These are special-purpose functions that exist to allow commands to be grouped, so that when we generate console docs, they can be more meaningfully presented.

Click here for more information about console docs and grouping.

void

noteScriptCallback(const char * className, const char * funcName, const char * usage, ConsoleFunctionHeader * header)

void

markCommandGroup(const char * nsName, const char * name, const char * usage)

void

beginCommandGroup(const char * nsName, const char * name, const char * usage)

void

endCommandGroup(const char * nsName, const char * name)

Global Function Registration

void

addCommand(const char * name, StringCallback cb, const char * usage, S32 minArgs, S32 maxArgs, bool toolOnly, ConsoleFunctionHeader * header)

void

addCommand(const char * name, VoidCallback cb, const char * usage, S32 minArgs, S32 maxArgs, bool toolOnly, ConsoleFunctionHeader * header)

void

addCommand(const char * name, IntCallback cb, const char * usage, S32 minArgs, S32 maxArgs, bool toolOnly, ConsoleFunctionHeader * header)

void

addCommand(const char * name, FloatCallback cb, const char * usage, S32 minArgs, S32 maxArgs, bool toolOnly, ConsoleFunctionHeader * header)

void

addCommand(const char * name, BoolCallback cb, const char * usage, S32 minArgs, S32 maxArgs, bool toolOnly, ConsoleFunctionHeader * header)

Console Execution

These are functions relating to the execution of script code.

bool

executeFile(const char * fileName, bool noCalls, bool journalScript)

Executes a script file and compiles it for use in script.

ConsoleValueRef

evaluate(const char * string, bool echo, const char * fileName)

Evaluate an arbitrary chunk of code.

ConsoleValueRef

evaluatef(const char * string, ... )

Evaluate an arbitrary line of script.

ConsoleValueRef

execute(S32 argc, ConsoleValueRef argv)

ConsoleValueRef

execute(S32 argc, const char * argv)

Call a script function from C/C++ code.

ConsoleValueRef

execute(SimObject * object, S32 argc, ConsoleValueRef argv, bool thisCallOnly)

ConsoleValueRef

execute(SimObject * object, S32 argc, const char * argv, bool thisCallOnly)

Call a Torque Script member function of a SimObject from C/C++ code.

Dynamic Type System

void

setData(S32 type, void * dptr, S32 index, S32 argc, const char ** argv, const EnumTable * tbl, BitSet32 flag)

const char *

getData(S32 type, void * dptr, S32 index, const EnumTable * tbl, BitSet32 flag)

const char *

getFormattedData(S32 type, const char * data, const EnumTable * tbl, BitSet32 flag)

Instant Group

void

pushInstantGroup(String name)

void

popInstantGroup()

Console Execution - executef

{

Implements a script function thunk which automatically converts parameters to relevant console types. Can be used as follows:

Con::executef("functionName", ...);
Con::executef(mySimObject, "functionName", ...);

NOTE: if you get a rather cryptic template error coming through here, most likely you are trying to convert a parameter which EngineMarshallType does not have a specialization for. Another problem can occur if you do not include "console/simBase.h" and "console/engineAPI.h" since _EngineConsoleExecCallbackHelper and SimConsoleThreadExecCallback are required.

see:

_EngineConsoleExecCallbackHelper

ConsoleValueRef

executef(R r, ArgTs ... argTs)

Public Enumerations

enum

Constants {
  DSOVersion = 49
  MaxLineLength = 512
  MaxDataTypes = 256
}

Various configuration constants.

Public Typedefs

HashMap< StringTableEntry, StringTableEntry >

typePathExpandoMap

Public Variables

bool

active

bool

alwaysUseDebugOutput

U32

completionBaseLen

U32

completionBaseStart

char

completionBuffer [MaxCompletionBufferSize]

Vector< ConsoleLogEntry >

consoleLog (__FILE__, __LINE__)

DataChunker

consoleLogChunker

FileStream

consoleLogFile

bool

consoleLogLocked

S32

consoleLogMode

const char *

defLogFileName

Vector< ConsumerCallback >

gConsumers (__FILE__, __LINE__)

String

gInstantGroup

The current $instantGroup setting.

S32

gObjectCopyFailures

bool

logBufferEnabled

const char *

logFileName

const S32

MaxCompletionBufferSize

bool

newLogFile

typePathExpandoMap

PathExpandos

S32

printLevel

ReturnBuffer

retBuffer

SimpleHashTable< PathExpando >

sgPathExpandos (64, false)

Vector< String >

sInstantGroupStack (__FILE__, __LINE__)

char

tabBuffer [MaxCompletionBufferSize]

SimObjectPtr< SimObject >

tabObject

bool

useRealTimestamp

bool

useTimestamp

Public Functions

ConsoleValueRef

_executef(S32 checkArgc, S32 argc, ConsoleValueRef * argv)

ConsoleValueRef

_executef(SimObject * obj, S32 checkArgc, S32 argc, ConsoleValueRef * argv)

ConsoleValueRef

_internalExecute(S32 argc, ConsoleValueRef argv)

ConsoleValueRef

_internalExecute(SimObject * object, S32 argc, ConsoleValueRef argv, bool thisCallOnly)

void

_printf(ConsoleLogEntry::Level level, ConsoleLogEntry::Type type, const char * fmt, va_list argptr)

Dictionary::Entry *

addVariableEntry(const char * name)

ConsoleFunctionGroupBegin(Clipboard , "Miscellaneous functions <a href="/coding/file/cmdgram_8cpp/#cmdgram_8cpp_1a5bafda9519252aa2d0fd038153f77dca">to</a> <a href="/coding/file/guieditctrl_8cpp/#guieditctrl_8cpp_1abb04e3738c4c5a96b3ade6fa47013a6c">control</a> the clipboard and clear the console." )

ConsoleFunctionGroupEnd(Clipboard )

DefineEngineFunction(cls , void , () , "()" "@brief Clears the console <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">output.\n\n</a>" "@ingroup Console" )

DefineEngineFunction(getClipboard , const char * , () , "()" "@brief Get text from the <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">clipboard.\n\n</a>" "@internal" )

DefineEngineFunction(setClipboard , bool , (const char *text) , "(string text)" "@brief Set the system <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">clipboard.\n\n</a>" "@internal" )

DefineNewEngineFunction(GetConsoleBool , bool , (String name) , "" )

DefineNewEngineFunction(GetConsoleFloat , F32 , (String name) , "" )

DefineNewEngineFunction(GetConsoleInt , S32 , (String name) , "" )

DefineNewEngineFunction(GetConsoleString , String , (String name) , "" )

DefineNewEngineFunction(SetConsoleBool , void , (String name, bool value) , "" )

DefineNewEngineFunction(SetConsoleFloat , void , (String name, F32 value) , "" )

DefineNewEngineFunction(SetConsoleInt , void , (String name, S32 value) , "" )

DefineNewEngineFunction(SetConsoleString , void , (String name, String value) , "" )

bool

expandOldScriptFilename(char * filename, U32 size, const char * src)

TORQUE_API void

fnAddConsumer(ConsumerCallback cb)

TORQUE_API void

fnRemoveConsumer(ConsumerCallback cb)

Dictionary::Entry *

getAddLocalVariableEntry(const char * name)

Dictionary::Entry *

getAddVariableEntry(const char * name)

Dictionary::Entry *

getLocalVariableEntry(const char * name)

const char *

getObjectTokenField(const char * name)

Dictionary::Entry *

getVariableEntry(const char * name)

bool

getVariableObjectField(const char * name, SimObject ** object, const char ** field)

bool

isMainThread()

Returns true when called from the main thread, false otherwise.

bool

isScriptPathExpando(const char * expando)

void

log(const char * string)

void

postConsoleInput(RawData data)

void

removeScriptPathExpando(const char * expando)

void

setScriptPathExpando(const char * expando, const char * path, bool toolsOnly)

StringTableEntry

tryGetBasePath(const char * path, const char * base)

Detailed Description

This namespace contains the core of the console functionality.

Introduction

The console is a key part of Torque's architecture. It allows direct run-time control of many aspects of the engine.

Console Consumers

The console distributes its output through Torque by using consumers.

Every time a new line is printed to the console, all the ConsumerCallbacks registered using addConsumer are called, in order.

note:
The GuiConsole control, which provides the on-screen in-game console, uses a different technique to render the console. It calls getLockLog() to lock the Vector of on-screen console entries, then it renders them as needed. While the Vector is locked, the console will not change the Vector. When the GuiConsole control is done with the console entries, it calls unlockLog() to tell the console that it is again safe to modify the Vector.

see:

TelnetConsole

see:

TelnetDebugger

see:

WinConsole

see:

MacCarbConsole

see:

StdConsole

see:

ConsoleLogger

addConsumer(ConsumerCallback consumer)

removeConsumer(ConsumerCallback consumer)

Con::ConsoleInputEvent smConsoleInput

Called from the native consoles to provide lines of console input to process.

This will schedule it for execution ASAP.

typedef JournaledSignal< void(RawData)> ConsoleInputEvent

Variable Management

setLocalVariable(const char * name, const char * value)

Assign a string value to a locally scoped console variable.

note:
The context of the variable is determined by gEvalState; that is, by the currently executing code.

Parameters:

name	Local console variable name to set
value	String value to assign to name

getLocalVariable(const char * name)

Retrieve the string value to a locally scoped console variable.

note:
The context of the variable is determined by gEvalState; that is, by the currently executing code.

Parameters:

name	Local console variable name to get

addVariable(const char * name, S32 type, void * pointer, const char * usage)

Add a console variable that references the value of a variable in C++ code.

If a value is assigned to the console variable the C++ variable is updated, and vice-versa.

Parameters:

name	Global console variable name to create.
type	The type of the C++ variable; see the ConsoleDynamicTypes enum for a complete list.
pointer	Pointer to the variable.
usage	Documentation string.

see:

ConsoleDynamicTypes

addConstant(const char * name, S32 type, const void * pointer, const char * usage)

Add a console constant that references the value of a constant in C++ code.

Parameters:

name	Global console constant name to create.
type	The type of the C++ constant; see the ConsoleDynamicTypes enum for a complete list.
pointer	Pointer to the constant.
usage	Documentation string.

see:

ConsoleDynamicTypes

removeVariable(const char * name)

Remove a console variable.

Parameters:

name	Global console variable name to remove

return:

true if variable existed before removal.

addVariableNotify(const char * name, const NotifyDelegate & callback)

Add a callback for notification when a variable is assigned a new value.

Parameters:

name	An existing global console variable name.
callback	The notification delegate function.

removeVariableNotify(const char * name, const NotifyDelegate & callback)

Remove an existing variable assignment notification callback.

Parameters:

name	An existing global console variable name.
callback	The notification delegate function.

typedef Delegate< void()> NotifyDelegate

The delegate signature for the variable assignment notifications.

see:

addVariableNotify, removeVariableNotify

Public User Defined

StringTableEntry gCurrentFile

Current script file name and root, these are registered as console variables.

StringTableEntry gCurrentRoot

Namespaces

getNamespaceList(Namespace * ns)

lookupNamespace(const char * ns)

linkNamespaces(const char * parent, const char * child)

unlinkNamespaces(const char * parent, const char * child)

classLinkNamespaces(Namespace * parent, Namespace * child)

note:
This should only be called from consoleObject.h

Console Function Implementation Helpers

The functions Con::getIntArg, Con::getFloatArg and Con::getArgBuffer(size) are used to allocate on the console stack string variables that will be passed into the next console

getReturnBuffer(U32 bufferSize)

getReturnBuffer lets you allocate stack space to return data in.

getReturnBuffer(const char * stringToCopy)

getReturnBuffer(const String & str)

getReturnBuffer(const StringBuilder & str)

getArgBuffer(U32 bufferSize)

getFloatArg(F64 arg)

getIntArg(S32 arg)

getBoolArg(bool arg)

getStringArg(const char * arg)

getStringArg(const String & arg)

Control Functions

The console must be initialized and shutdown appropriately during the lifetime of the app.

These functions are used to manage this behavior.

note:
Torque deals with this aspect of console management, so you don't need to call these functions in normal usage of the engine.

init()

Initializes the console.

This performs the following steps:

Calls Namespace::init() to initialize the scripting namespace hierarchy.
Calls ConsoleConstructor::setup() to initialize globally defined console methods and functions.
Registers some basic global script variables.
Calls AbstractClassRep::init() to initialize Torque's class database.
Registers some basic global script functions that couldn't usefully be defined anywhere else.

shutdown()

Shuts down the console.

This performs the following steps:

Closes the console log file.
Calls Namespace::shutdown() to shut down the scripting namespace hierarchy.

isActive()

Is the console active at this time?

Logging

getLockLog(ConsoleLogEntry *& log, U32 & size)

unlockLog()

setLogMode(S32 newMode)

Miscellaneous

tabComplete(char * inputBuffer, U32 cursorPos, U32 maxResultLength, bool forwardTab)

This is the basis for tab completion in the console.

note:
This is an internally used function. You probably don't care much about how this works.

This function does some basic parsing to try to ascertain the namespace in which we are attempting to do tab completion, then bumps control off to the appropriate tabComplete function, either in SimObject or Namespace.

Parameters:

inputBuffer	Pointer to buffer containing starting data, or last result.
cursorPos	Location of cursor in this buffer. This is used to indicate what part of the string should be kept and what part should be advanced to the next match if any.
maxResultLength	Maximum amount of result data to put into inputBuffer. This is capped by MaxCompletionBufferSize.
forwardTab	Should we go forward to next match or backwards to previous match? True indicates forward.

stripColorChars(char * line)

Remove color marking information from a string.

note:
It does this in-place, so be careful! It may potentially blast data if you're not careful. When in doubt, make a copy of the string first.

isFunction(const char * fn)

Returns true if fn is a global scripting function.

This looks in the global namespace. It also checks to see if fn is in the StringTable; if not, it returns false.

isCurrentScriptToolScript()

getModNameFromPath(const char * path)

addPathExpando(const char * pExpandoName, const char * pPath)

getPathExpando(const char * pExpandoName)

removePathExpando(const char * pExpandoName)

isPathExpando(const char * pExpandoName)

getPathExpandoCount(void )

getPathExpandoKey(U32 expandoIndex)

getPathExpandoValue(U32 expandoIndex)

expandPath(char * pDstPath, U32 size, const char * pSrcPath, const char * pWorkingDirectoryHint, const bool ensureTrailingSlash)

isBasePath(const char * SrcPath, const char * pBasePath)

collapsePath(char * pDstPath, U32 size, const char * pSrcPath, const char * pWorkingDirectoryHint)

ensureTrailingSlash(char * pDstPath, const char * pSrcPath, S32 dstSize)

getDSOPath(const char * scriptPath)

stripRepeatSlashes(char * pDstPath, const char * pSrcPath, S32 dstSize)

expandScriptFilename(char * filename, U32 size, const char * src)

Convert from a relative script path to an absolute script path.

This is used in (among other places) the exec() script function, which takes a parameter indicating a script file and executes it. Script paths can be one of:

Absolute: fps/foo/bar.tscript Paths of this sort are passed through.
Mod-relative: ~/foo/bar.tscript Paths of this sort have their replaced with the name of the current mod.
File-relative: ./baz/blip.tscript Paths of this sort are calculated relative to the path of the current scripting file.

note:
This function determines paths relative to the currently executing CodeBlock. Calling it outside of script execution will result in it directly copying src to filename, since it won't know to what the path is relative!

Parameters:

filename	Pointer to string buffer to fill with absolute path.
size	Size of buffer pointed to by filename.
src	Original, possibly relative script path.

expandGameScriptFilename(char * filename, U32 size, const char * src)

expandToolScriptFilename(char * filename, U32 size, const char * src)

collapseScriptFilename(char * filename, U32 size, const char * src)

Console Output

These functions process the formatted string and pass it to all the ConsumerCallbacks that are currently registered.

The console log file and the console window callbacks are installed by default.

see:

addConsumer()

see:

removeConsumer()

printf(const char * _format, ... )

Parameters:

_format	A stdlib printf style formatted out put string
...	Variables to be written

warnf(ConsoleLogEntry::Type type, const char * _format, ... )

note:
The console window colors warning text as LIGHT GRAY.

Parameters:

type	Allows you to associate the warning message with an internal module.
_format	A stdlib printf style formatted out put string
...	Variables to be written

see:

Con::warnf()

errorf(ConsoleLogEntry::Type type, const char * _format, ... )

note:
The console window colors warning text as RED.

Parameters:

type	Allows you to associate the warning message with an internal module.
_format	A stdlib printf style formatted out put string
...	Variables to be written

see:

Con::errorf()

warnf(const char * _format, ... )

note:
The console window colors warning text as LIGHT GRAY.

Parameters:

_format	A stdlib printf style formatted out put string
...	Variables to be written

errorf(const char * _format, ... )

note:
The console window colors warning text as RED.

Parameters:

_format	A stdlib printf style formatted out put string
...	Variables to be written

printSeparator(void )

Prints a separator to the console.

printBlankLine(void )

Prints a separator to the console.

Global Variable Accessors

Assign a string value to a global console variable

Parameters:

name	Global console variable name to set
value	String value to assign to this variable.

setVariable(const char * name, const char * value)

setBoolVariable(const char * varName, bool value)

Same as setVariable(), but for bools.

setIntVariable(const char * varName, S32 value)

Same as setVariable(), but for ints.

setFloatVariable(const char * varName, F32 value)

Same as setVariable(), but for floats.

getVariable(const char * name, const char * def)

Retrieve the string value of a global console variable.

Parameters:

name	Global Console variable name to query

return:

The string value of the variable or "" if the variable does not exist.

getBoolVariable(const char * name, bool def)

Same as getVariable(), but for bools.

Parameters:

name	Name of the variable.
def	Default value to supply if no matching variable is found.

getIntVariable(const char * name, S32 def)

Same as getVariable(), but for ints.

Parameters:

name	Name of the variable.
def	Default value to supply if no matching variable is found.

getFloatVariable(const char * name, F32 def)

Same as getVariable(), but for floats.

Parameters:

name	Name of the variable.
def	Default value to supply if no matching variable is found.

getObjectField(const char * name)

Retrieve the string value of an object field.

Parameters:

name	"object.field" string to query

return:

The string value of the variable or NULL if no object is specified

Namespace Function Registration

addCommand(const char * nameSpace, const char * name, StringCallback cb, const char * usage, S32 minArgs, S32 maxArgs, bool toolOnly, ConsoleFunctionHeader * header)

Register a C++ function with the console making it callable as a method of the given namespace from the scripting engine.

Parameters:

nameSpace	Name of the namespace to associate the new function with; this is usually the name of a class.
name	Name of the new function.
cb	Pointer to the function implementing the scripting call; a console callback function returning a specific type value.
usage	Documentation for this function. console_autodoc
minArgs	Minimum number of arguments this function accepts
maxArgs	Maximum number of arguments this function accepts
toolOnly	Wether this is a TORQUE_TOOLS only function.
header	The extended function header.

addCommand(const char * nameSpace, const char * name, VoidCallback cb, const char * usage, S32 minArgs, S32 maxArgs, bool toolOnly, ConsoleFunctionHeader * header)

Register a C++ function with the console making it callable as a method of the given namespace from the scripting engine.

Parameters:

nameSpace	Name of the namespace to associate the new function with; this is usually the name of a class.
name	Name of the new function.
cb	Pointer to the function implementing the scripting call; a console callback function returning a specific type value.
usage	Documentation for this function. console_autodoc
minArgs	Minimum number of arguments this function accepts
maxArgs	Maximum number of arguments this function accepts
toolOnly	Wether this is a TORQUE_TOOLS only function.
header	The extended function header.

addCommand(const char * nameSpace, const char * name, IntCallback cb, const char * usage, S32 minArgs, S32 maxArgs, bool toolOnly, ConsoleFunctionHeader * header)

Register a C++ function with the console making it callable as a method of the given namespace from the scripting engine.

Parameters:

nameSpace	Name of the namespace to associate the new function with; this is usually the name of a class.
name	Name of the new function.
cb	Pointer to the function implementing the scripting call; a console callback function returning a specific type value.
usage	Documentation for this function. console_autodoc
minArgs	Minimum number of arguments this function accepts
maxArgs	Maximum number of arguments this function accepts
toolOnly	Wether this is a TORQUE_TOOLS only function.
header	The extended function header.

addCommand(const char * nameSpace, const char * name, FloatCallback cb, const char * usage, S32 minArgs, S32 maxArgs, bool toolOnly, ConsoleFunctionHeader * header)

Register a C++ function with the console making it callable as a method of the given namespace from the scripting engine.

Parameters:

nameSpace	Name of the namespace to associate the new function with; this is usually the name of a class.
name	Name of the new function.
cb	Pointer to the function implementing the scripting call; a console callback function returning a specific type value.
usage	Documentation for this function. console_autodoc
minArgs	Minimum number of arguments this function accepts
maxArgs	Maximum number of arguments this function accepts
toolOnly	Wether this is a TORQUE_TOOLS only function.
header	The extended function header.

addCommand(const char * nameSpace, const char * name, BoolCallback cb, const char * usage, S32 minArgs, S32 maxArgs, bool toolOnly, ConsoleFunctionHeader * header)

Register a C++ function with the console making it callable as a method of the given namespace from the scripting engine.

Parameters:

nameSpace	Name of the namespace to associate the new function with; this is usually the name of a class.
name	Name of the new function.
cb	Pointer to the function implementing the scripting call; a console callback function returning a specific type value.
usage	Documentation for this function. console_autodoc
minArgs	Minimum number of arguments this function accepts
maxArgs	Maximum number of arguments this function accepts
toolOnly	Wether this is a TORQUE_TOOLS only function.
header	The extended function header.

Special Purpose Registration

These are special-purpose functions that exist to allow commands to be grouped, so that when we generate console docs, they can be more meaningfully presented.

Click here for more information about console docs and grouping.

noteScriptCallback(const char * className, const char * funcName, const char * usage, ConsoleFunctionHeader * header)

markCommandGroup(const char * nsName, const char * name, const char * usage)

beginCommandGroup(const char * nsName, const char * name, const char * usage)

endCommandGroup(const char * nsName, const char * name)

Global Function Registration

addCommand(const char * name, StringCallback cb, const char * usage, S32 minArgs, S32 maxArgs, bool toolOnly, ConsoleFunctionHeader * header)

Parameters:

name	Name of the new function.
cb	Pointer to the function implementing the scripting call; a console callback function returning a specific type value.
usage	Documentation for this function. console_autodoc
minArgs	Minimum number of arguments this function accepts
maxArgs	Maximum number of arguments this function accepts
toolOnly	Wether this is a TORQUE_TOOLS only function.
header	The extended function header.

addCommand(const char * name, VoidCallback cb, const char * usage, S32 minArgs, S32 maxArgs, bool toolOnly, ConsoleFunctionHeader * header)

Parameters:

name	Name of the new function.
cb	Pointer to the function implementing the scripting call; a console callback function returning a specific type value.
usage	Documentation for this function. console_autodoc
minArgs	Minimum number of arguments this function accepts
maxArgs	Maximum number of arguments this function accepts
toolOnly	Wether this is a TORQUE_TOOLS only function.
header	The extended function header.

addCommand(const char * name, IntCallback cb, const char * usage, S32 minArgs, S32 maxArgs, bool toolOnly, ConsoleFunctionHeader * header)

Parameters:

name	Name of the new function.
cb	Pointer to the function implementing the scripting call; a console callback function returning a specific type value.
usage	Documentation for this function. console_autodoc
minArgs	Minimum number of arguments this function accepts
maxArgs	Maximum number of arguments this function accepts
toolOnly	Wether this is a TORQUE_TOOLS only function.
header	The extended function header.

addCommand(const char * name, FloatCallback cb, const char * usage, S32 minArgs, S32 maxArgs, bool toolOnly, ConsoleFunctionHeader * header)

Parameters:

name	Name of the new function.
cb	Pointer to the function implementing the scripting call; a console callback function returning a specific type value.
usage	Documentation for this function. console_autodoc
minArgs	Minimum number of arguments this function accepts
maxArgs	Maximum number of arguments this function accepts
toolOnly	Wether this is a TORQUE_TOOLS only function.
header	The extended function header.

addCommand(const char * name, BoolCallback cb, const char * usage, S32 minArgs, S32 maxArgs, bool toolOnly, ConsoleFunctionHeader * header)

Parameters:

name	Name of the new function.
cb	Pointer to the function implementing the scripting call; a console callback function returning a specific type value.
usage	Documentation for this function. console_autodoc
minArgs	Minimum number of arguments this function accepts
maxArgs	Maximum number of arguments this function accepts
toolOnly	Wether this is a TORQUE_TOOLS only function.
header	The extended function header.

Console Execution

These are functions relating to the execution of script code.

executeFile(const char * fileName, bool noCalls, bool journalScript)

Executes a script file and compiles it for use in script.

Parameters:

string	File name that is the script to be executed and compiled.
fileName	Path to the file to execute
noCalls	Deprecated
journalScript	Deprecated

return:

True if the script was successfully executed, false if not.

evaluate(const char * string, bool echo, const char * fileName)

Evaluate an arbitrary chunk of code.

Parameters:

string	Buffer containing code to execute.
echo	Should we echo the string to the console?
fileName	Indicate what file this code is coming from; used in error reporting and such. NOTE: This function restores the console stack on return.

evaluatef(const char * string, ... )

Evaluate an arbitrary line of script.

This wraps dVsprintf(), so you can substitute parameters into the code being executed. NOTE: This function restores the console stack on return.

execute(S32 argc, ConsoleValueRef argv)

execute(S32 argc, const char * argv)

Call a script function from C/C++ code.

Parameters:

argc

Number of elements in the argv parameter

argv

A character string array containing the name of the function to call followed by the arguments to that function.

// Call a Torque script function called mAbs, having one parameter.
char* argv[] = {"abs", "-9"};
char* result = execute(2, argv);

NOTE: this function restores the console stack on return.

execute(SimObject * object, S32 argc, ConsoleValueRef argv, bool thisCallOnly)

execute(SimObject * object, S32 argc, const char * argv, bool thisCallOnly)

Call a Torque Script member function of a SimObject from C/C++ code.

Parameters:

object

Object on which to execute the method call.

argc

Number of elements in the argv parameter (must be >2, see argv)

argv

A character string array containing the name of the member function to call followed by an empty parameter (gets filled with object ID) followed by arguments to that function.

// Call the method setMode() on an object, passing it one parameter.

char* argv[] = {"setMode", "", "2"};
char* result = execute(mysimobject, 3, argv);

NOTE: this function restores the console stack on return.

Dynamic Type System

setData(S32 type, void * dptr, S32 index, S32 argc, const char ** argv, const EnumTable * tbl, BitSet32 flag)

getData(S32 type, void * dptr, S32 index, const EnumTable * tbl, BitSet32 flag)

getFormattedData(S32 type, const char * data, const EnumTable * tbl, BitSet32 flag)

Instant Group

pushInstantGroup(String name)

popInstantGroup()

Console Execution - executef

{

Implements a script function thunk which automatically converts parameters to relevant console types. Can be used as follows:

Con::executef("functionName", ...);
Con::executef(mySimObject, "functionName", ...);

see:

_EngineConsoleExecCallbackHelper

executef(R r, ArgTs ... argTs)

Public Enumerations

Constants

Enumerator

DSOVersion = 49

This is the version number associated with DSO files.

  If you make any changes to the way the scripting language works
  (such as DSO format changes, adding/removing op-codes) that would
  break compatibility, then you should increment this.

  If you make a really major change, increment it to the next multiple
  of ten.

  12/29/04 - BJG - 33->34 Removed some opcodes, part of namespace upgrade.
  12/30/04 - BJG - 34->35 Reordered some things, further general shuffling.
  11/03/05 - BJG - 35->36 Integrated new debugger code.
  09/08/06 - THB - 36->37 New opcode for internal names
  09/15/06 - THB - 37->38 Added unit conversions
  11/23/06 - THB - 38->39 Added recursive internal name operator
  02/15/07 - THB - 39->40 Bumping to 40 for TGB since the console has been
                          majorly hacked without the version number being bumped
  02/16/07 - THB - 40->41 newmsg operator
  06/15/07 - THB - 41->42 script types
  07/31/07 - THB - 42->43 Patch from Andreas Kirsch: Added opcode to support nested new declarations.
  09/12/07 - CAF - 43->44 remove newmsg operator
  09/27/07 - RDB - 44->45 Patch from Andreas Kirsch: Added opcode to support correct void return
  01/13/09 - TMS - 45->46 Added script assert
  09/07/14 - jamesu - 46->47 64bit support
  10/14/14 - jamesu - 47->48 Added opcodes to reduce reliance on strings in function calls
  10/07/17 - JTH - 48->49 Added opcode for function pointers and revamp of interpreter 
                          from switch to function calls.

MaxLineLength = 512

Maximum length of a line of console input.

MaxDataTypes = 256

Maximum number of registered data types.

Various configuration constants.

Public Typedefs

typedef HashMap< StringTableEntry, StringTableEntry > typePathExpandoMap

Public Variables

bool active

bool alwaysUseDebugOutput

U32 completionBaseLen

U32 completionBaseStart

char completionBuffer [MaxCompletionBufferSize]

Vector< ConsoleLogEntry > consoleLog (__FILE__, __LINE__)

DataChunker consoleLogChunker

FileStream consoleLogFile

bool consoleLogLocked

S32 consoleLogMode

const char * defLogFileName

Vector< ConsumerCallback > gConsumers (__FILE__, __LINE__)

String gInstantGroup

The current $instantGroup setting.

S32 gObjectCopyFailures

bool logBufferEnabled

const char * logFileName

const S32 MaxCompletionBufferSize

bool newLogFile

typePathExpandoMap PathExpandos

S32 printLevel

ReturnBuffer retBuffer

SimpleHashTable< PathExpando > sgPathExpandos (64, false)

Vector< String > sInstantGroupStack (__FILE__, __LINE__)

char tabBuffer [MaxCompletionBufferSize]

SimObjectPtr< SimObject > tabObject

bool useRealTimestamp

bool useTimestamp

Public Functions

_executef(S32 checkArgc, S32 argc, ConsoleValueRef * argv)

_executef(SimObject * obj, S32 checkArgc, S32 argc, ConsoleValueRef * argv)

_internalExecute(S32 argc, ConsoleValueRef argv)

_internalExecute(SimObject * object, S32 argc, ConsoleValueRef argv, bool thisCallOnly)

_printf(ConsoleLogEntry::Level level, ConsoleLogEntry::Type type, const char * fmt, va_list argptr)

addVariableEntry(const char * name)

ConsoleFunctionGroupBegin(Clipboard , "Miscellaneous functions <a href="/coding/file/cmdgram_8cpp/#cmdgram_8cpp_1a5bafda9519252aa2d0fd038153f77dca">to</a> <a href="/coding/file/guieditctrl_8cpp/#guieditctrl_8cpp_1abb04e3738c4c5a96b3ade6fa47013a6c">control</a> the clipboard and clear the console." )

ConsoleFunctionGroupEnd(Clipboard )

DefineEngineFunction(cls , void , () , "()" "@brief Clears the console <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">output.\n\n</a>" "@ingroup Console" )

DefineEngineFunction(getClipboard , const char * , () , "()" "@brief Get text from the <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">clipboard.\n\n</a>" "@internal" )

DefineEngineFunction(setClipboard , bool , (const char *text) , "(string text)" "@brief Set the system <a href="/coding/file/cmdscan_8cpp/#cmdscan_8cpp_1aeab71244afb687f16d8c4f5ee9d6ef0e">clipboard.\n\n</a>" "@internal" )

DefineNewEngineFunction(GetConsoleBool , bool , (String name) , "" )

DefineNewEngineFunction(GetConsoleFloat , F32 , (String name) , "" )

DefineNewEngineFunction(GetConsoleInt , S32 , (String name) , "" )

DefineNewEngineFunction(GetConsoleString , String , (String name) , "" )

DefineNewEngineFunction(SetConsoleBool , void , (String name, bool value) , "" )

DefineNewEngineFunction(SetConsoleFloat , void , (String name, F32 value) , "" )

DefineNewEngineFunction(SetConsoleInt , void , (String name, S32 value) , "" )

DefineNewEngineFunction(SetConsoleString , void , (String name, String value) , "" )

expandOldScriptFilename(char * filename, U32 size, const char * src)

fnAddConsumer(ConsumerCallback cb)

fnRemoveConsumer(ConsumerCallback cb)

getAddLocalVariableEntry(const char * name)

getAddVariableEntry(const char * name)

getLocalVariableEntry(const char * name)

getObjectTokenField(const char * name)

getVariableEntry(const char * name)

getVariableObjectField(const char * name, SimObject ** object, const char ** field)

isMainThread()

Returns true when called from the main thread, false otherwise.

isScriptPathExpando(const char * expando)

log(const char * string)

postConsoleInput(RawData data)

removeScriptPathExpando(const char * expando)

setScriptPathExpando(const char * expando, const char * path, bool toolsOnly)

tryGetBasePath(const char * path, const char * base)