nrEngine::IScript Class Reference
[Engine Scripting]

Script interface for any kind of script languages. More...

Inheritance diagram for nrEngine::IScript:

nrEngine::IResource nrEngine::ITask nrEngine::IThread nrEngine::EmptyScript nrEngine::Script

Public Types

typedef std::list< std::pair<
std::string, std::string > > 
ArgumentList
 You can also push a list of arguments to the function directly.

Public Member Functions

NR_FORCEINLINE const std::string & getContent () const
virtual Result loadFromString (const std::string &str)=0
std::string popLastError ()
Result execute (bool runOnce=true)
Result forceExecute (bool runOnce=true)
ScriptResult call (const std::string &funcName)
uint32 pushArgument (const std::string &funcName, const std::string &type, const std::string &value)
uint32 setArguments (const std::string &funcName, const ArgumentList &args)
int32 popArgument (const std::string &funcName, std::string &type, std::string &value)

Protected Member Functions

virtual Result run ()=0
virtual Result callfunc (const std::string &funcName, ScriptResult &result)
void pushErrorMessage (const std::string &msg)
 IScript (const std::string &)
virtual ~IScript ()
Result updateTask ()
Result onStartTask ()
virtual Result unloadResource ()
virtual Result reloadResource (PropertyList *params)
bool shouldRunOnce () const
 Check if script should only run once.
void setRunOnce (bool b)
 Should the script run only once (no loop).
virtual bool hasCommands ()=0
virtual void onStartScript ()
void notifyLoaded ()

Protected Attributes

std::string mContent
 Here we store the whole script as a string.

Detailed Description

Script interface for any kind of script languages.

This is an interface for any kind of scripting language provided by the plugins. This interface is used to executed strings typed in the console or readed from the scripting files.

We also define each script as an task in the kernel. So the script will be updated in each tick by the kernel and will be unloaded from the task queue as soon as the script ends his execution. Using of scripts as a task has the advantage, that we are able to run scripts with a certain priority/order number. So the script_Task can run before certain application task or after them.

Each script can not only be executed, but if specify any functions or routines, so this routines could be explicitely called. You can also specify arguments for such a routine. Therefor the IScript interface does only store the arguments and their type as a string. Derived class should read this and pass the parameters in the right way. If a derived script language does not support any arguments or function calling so just ignore them. Passed parameters will be automaticaly removed from the waiting list as soon as the function from the script will be called.

See also:
IResource, ITask

Definition at line 97 of file IScript.h.


Constructor & Destructor Documentation

nrEngine::IScript::IScript ( const std::string &   )  [protected]

Initialize the script interface Specify also the script type name, so we know of which type is the given script

Definition at line 96 of file IScript.cpp.

References nrEngine::ITask::setTaskName().

nrEngine::IScript::~IScript (  )  [protected, virtual]

Virtual destructor

Definition at line 90 of file IScript.cpp.


Member Function Documentation

NR_FORCEINLINE const std::string& nrEngine::IScript::getContent (  )  const

Returns the content of the script file

Definition at line 105 of file IScript.h.

virtual Result nrEngine::IScript::loadFromString ( const std::string &  str  )  [pure virtual]

Load a script from string. The given string should contain the script in the appropriate language, so it can be executed.

Parameters:
str String containing the script
Returns:
either OK or:
  • SCRIPT_PARSE_ERROR

Implemented in nrEngine::EmptyScript, and nrEngine::Script.

std::string nrEngine::IScript::popLastError (  ) 

Get short description of the last error.

Definition at line 158 of file IScript.cpp.

Result nrEngine::IScript::execute ( bool  runOnce = true  ) 

Execute the script. The script will be executed completely, before go back to the system run. Execution is done by adding the script to the kernel's pipeline. In the next cycle the script will be then executed.

Parameters:
runOnce If true, so the script method run() will be called only once. If you specify false, so run() will be called in each kernel cycle.
NOTE: If you want to execute script immidiately, use forceExecute() instead

Definition at line 40 of file IScript.cpp.

References nrEngine::Kernel::AddTask(), nrEngine::ITask::getTaskState(), nrEngine::OK, nrEngine::ORDER_NORMAL, nrEngine::SCRIPT_ALREADY_RUNNING, nrEngine::Engine::sKernel(), and nrEngine::TASK_RUNNING.

Referenced by forceExecute().

Result nrEngine::IScript::forceExecute ( bool  runOnce = true  ) 

Force starting the script. Script will be added to the kernel and started immeiately after that, by calling the run() method. Afer that the script will be updated in each cycle if not otherwise specified.

See also:
execute()

Definition at line 58 of file IScript.cpp.

References execute(), and run().

ScriptResult nrEngine::IScript::call ( const std::string &  funcName  ) 

By calling the execute() method you will execute the whole script completely. This is usefull if you do not interested in the results of the scripts, but in its handling. However if you wish to call a certain function from the script (only if function calling is supported by the scripting language), so you have to use this method.

Here a certain function from the script will be called. The result of this function will be given back in a generic type ScriptResult. You have to know how to interpret the results given back by the script. If any error occurs the error message will be logged and an exception will be thrown. Catch the exception to handle the errors.

Parameters:
funcName Name of the function to call
Returns:
result from the script execution converted into generic ScriptResult object.
NOTE: To pass parameters to function use pushArgument()

Definition at line 140 of file IScript.cpp.

References callfunc(), NR_EXCEPT, and nrEngine::OK.

uint32 nrEngine::IScript::pushArgument ( const std::string &  funcName,
const std::string &  type,
const std::string &  value 
)

User application can also specify certain arguments for functions in the script. The derived class implementing specific script language must read out this values before starting the script. The derived class should also know how to pass them to the script language and how to parse them. If a script does not support function calling or argument binding, so this values can be ignored.

Parameters:
funcName Name of the function/routine in the script for which one the parameters are specified
type String containing the name of the type of the argument
value String containing the value of the argument.
Returns:
Number of arguments currently stored for the given function including the new argument.
NOTE: Push arguments from the first to the last.

Definition at line 103 of file IScript.cpp.

uint32 nrEngine::IScript::setArguments ( const std::string &  funcName,
const ArgumentList args 
)

Same as pushArgument() but set argument from the list. Already pushed arguments will be removed !

Definition at line 113 of file IScript.cpp.

int32 nrEngine::IScript::popArgument ( const std::string &  funcName,
std::string &  type,
std::string &  value 
)

Derived class should use this function to pop the first parameter from the list. The argument type and the value will be stored in the given variables. The function does return the number of remaining parameters. If function returns 0, so no parameters are available.

Parameters:
funcName Name of the function for which the arguments are retrieved
type Here the type of the argument will be stored
value Here the value of the argument will be stored
Returns:
Number of remaining arguments for the function. If the resulting value is -1, so no parameters for the function exists
NOTE: The arguments are returned from the first to the last

Definition at line 120 of file IScript.cpp.

virtual Result nrEngine::IScript::run (  )  [protected, pure virtual]

Run the script. This method must be overriden by the derived classes. run will be called by the execution of the script. However you can not be sure if the script executed completely or only stepwise by this method, this depends only on the implementation. Read appropriate documentation of script language implementation.

Implemented in nrEngine::EmptyScript.

Referenced by forceExecute(), and updateTask().

Result nrEngine::IScript::callfunc ( const std::string &  funcName,
ScriptResult result 
) [protected, virtual]

Derived class can overload this method if a implemented script language does support function calling. Default behaviour of this method is not to call any function or to execute a script. Overload this if you wish to have another behaviour.

Parameters:
funcName name of the function to call
result Store here the result of a call of a function
Returns:
OK if no error during the execution occurs or an error code. If any error code will be returned so an exception will be thrown.

Definition at line 152 of file IScript.cpp.

References nrEngine::OK.

Referenced by call().

void nrEngine::IScript::pushErrorMessage ( const std::string &  msg  )  [protected]

If any error occurs stor here the error messages. The base class will deliver them to the user. Also the base class does implement error message stack, so returned messages are automaticaly removed from the message stack.

Definition at line 167 of file IScript.cpp.

References nrEngine::Log::LL_ERROR, and nrEngine::Log::LOG_CONSOLE.

Result nrEngine::IScript::updateTask (  )  [protected, virtual]

Run one step from the script. This method will be automaticaly called from the engine's kernel.

Implements nrEngine::ITask.

Definition at line 70 of file IScript.cpp.

References hasCommands(), nrEngine::Kernel::RemoveTask(), run(), shouldRunOnce(), and nrEngine::Engine::sKernel().

Result nrEngine::IScript::onStartTask (  )  [protected, virtual]

Method is called from kernel, when script starts its execution

Reimplemented from nrEngine::ITask.

Definition at line 31 of file IScript.cpp.

References nrEngine::OK, and onStartScript().

virtual Result nrEngine::IScript::unloadResource (  )  [protected, virtual]

Bypass the IResource::unloadRes() function, so that derived class can overload them

Implements nrEngine::IResource.

Definition at line 274 of file IScript.h.

References nrEngine::OK.

Referenced by nrEngine::Script::~Script().

virtual Result nrEngine::IScript::reloadResource ( PropertyList params  )  [protected, virtual]

Reload resource. Each resource object should be able to reload itself from the disk or other media. It can use the assigned loader to load files or to make it by itself. At the end the resource should be marked as loaded.

Implements nrEngine::IResource.

Definition at line 275 of file IScript.h.

References nrEngine::OK.

virtual bool nrEngine::IScript::hasCommands (  )  [protected, pure virtual]

This method will be called to check from base class to check if run completes. If derived class returns false, so script will be removed from the kernel

Referenced by updateTask().

virtual void nrEngine::IScript::onStartScript (  )  [protected, virtual]

This method will be called if a script is gonna be executed. Override this method to make some initializations for example.

Definition at line 294 of file IScript.h.

Referenced by onStartTask().

void nrEngine::IScript::notifyLoaded (  )  [protected]

Call this method to manually specify, that a script is loaded and can be executed. The method should be called from loadFromString() method by derived classes

Definition at line 25 of file IScript.cpp.

References nrEngine::IResource::markResourceLoaded().

Referenced by nrEngine::Script::loadFromString().


The documentation for this class was generated from the following files:
Generated on Wed Sep 12 23:19:43 2007 for nrEngine by  doxygen 1.5.1