OpalKelly::ScriptEngine Class Reference

Allows to load scripts and run functions defined in them. More...

Classes
class	AsyncResultHandler
	Result handler for asynchronous operations. More...

Public Member Functions
	ScriptEngine ()
	Create a non-initialized scripting engine.
void	ConstructLua (okCFrontPanel &fp)
	Create a new Lua scripting engine.
bool	IsValid () const
	Return true if the engine is ready to use.
void	LoadScript (const std::string &name, const std::string &code)
	Load code in the scripting language.
void	LoadFile (const std::string &path)
	Load a script from file and prepare it for execution.
void	PrependToScriptPath (const std::string &dir)
	Adds the specified directory to the list of directories searched by LoadFile().
ScriptValues	RunScriptFunction (const std::string &name, const ScriptValues &args=ScriptValues())
	Run the specified scripting function.
void	RunScriptFunctionAsync (AsyncResultHandler &handler, const std::string &name, const ScriptValues &args=ScriptValues())
	Starts running the specified scripting function.

Detailed Description

A scripting engine is typically created for a non-local FrontPanel device once, after opening it, and allows to run scripts working with the device on the remote computer in order to reduce the latency.

Constructor & Destructor Documentation

ScriptEngine()

OpalKelly::ScriptEngine::ScriptEngine

(

)

ConstructLua() can be called at a later time to really initialize the engine, no methods other than this one and IsValid() can be called on the object until then.

Member Function Documentation

ConstructLua()

void OpalKelly::ScriptEngine::ConstructLua

(

okCFrontPanel &

fp

)

This scripting engine uses Lua 5 for interpreting the scripts passed to LoadScript().

Throws a std::exception-derived exception if the scripting engine couldn't be created.

Parameters

fp	An opened FrontPanel device which will be used for running scripts using this engine object.

IsValid()

bool OpalKelly::ScriptEngine::IsValid

(

)

const

This method returns false if ConstructLua() hadn't been called yet and true after its successful completion.

LoadFile()

void OpalKelly::ScriptEngine::LoadFile

(

const std::string &

path

)

This method loads a script from file and calls LoadScript() on it.

Throws a std::exception-derived exception if script couldn't be loaded, either because the file couldn't be found or read or because LoadScript() failed.

If path is not an absolute path, it is searched in the script path directories, see PrependToScriptPath().

LoadScript()

void OpalKelly::ScriptEngine::LoadScript	(	const std::string &	name,
		const std::string &	code )

Throws a std::exception-derived exception if script couldn't be loaded, e.g. because it contained invalid code.

Parameters

name	The name of the script module, used mostly for diagnostic purposes (e.g. reporting errors in the code) currently.
code	Code in the scripting language.

PrependToScriptPath()

void OpalKelly::ScriptEngine::PrependToScriptPath

(

const std::string &

dir

)

By default, only the current working directory is searched for the file name passed to LoadFile(), but after calling this function dir will be searched for it as well. Notice that the directories are searched in the reverse order of their additions, i.e. the last added one has priority.

RunScriptFunction()

ScriptValues OpalKelly::ScriptEngine::RunScriptFunction	(	const std::string &	name,
		const ScriptValues &	args = ScriptValues() )

Throws a std::exception-derived exception if the function couldn't be executed, either because such function wasn't found at all or because a run-time occurred while executing it. In any case, what() method of the exception object returns more information about the error.

Parameters

name	The name of the function to run, which must have been defined by a script previously loaded using LoadScript().
args	Possible empty collection containing the function arguments.

Returns

The value returned by the function, if any.

RunScriptFunctionAsync()

void OpalKelly::ScriptEngine::RunScriptFunctionAsync	(	AsyncResultHandler &	handler,
		const std::string &	name,
		const ScriptValues &	args = ScriptValues() )

The function is executed in a background thread and AsyncResultHandler::OnResult() method of the provided handler will be called in that thread context later.

Parameters

handler	The handler to notify about the function execution completion.
name	The name of the function to run, which must have been defined by a script previously loaded using LoadScript().
args	Possible empty collection containing the function arguments.