Provides an engine-independent interface for a scripting engine. More...

#include <ScriptEngine.h>

Inherits QObject.

Collaboration diagram for ScriptEngine:

Public Types
enum	ValueOwnership { QtOwnership = 0 , ScriptOwnership = 1 , AutoOwnership = 2 }
	Who owns a given object. More...

enum	QObjectWrapOption { ExcludeSuperClassMethods = 0x0002 , ExcludeSuperClassProperties = 0x0004 , ExcludeSuperClassContents = ExcludeSuperClassMethods \| ExcludeSuperClassProperties , ExcludeSlots = 0x0020 , AutoCreateDynamicProperties = 0x0100 , PreferExistingWrapperObject = 0x0200 , SkipMethodsInEnumeration = 0x0008 }
	Which part of an object is exposed to the script. More...

Signals
void	exception (std::shared_ptr< ScriptException > exception)
	The script being run threw an exception. More...

Public Member Functions
virtual void	abortEvaluation ()=0
	Stops the currently running script.

virtual void	clearExceptions ()=0
	Clears uncaughtException and related.

virtual ScriptContext *	currentContext () const =0
	Context of the currently running script. More...

virtual ScriptValue	evaluate (const QString &program, const QString &fileName=QString())=0
	Runs a script. More...

virtual ScriptValue	evaluate (const ScriptProgramPointer &program)=0
	Evaluates a pre-compiled program. More...

virtual ScriptValue	evaluateInClosure (const ScriptValue &locals, const ScriptProgramPointer &program)=0
	Evaluate a script in a separate environment. More...

virtual ScriptValue	globalObject ()
	Global object which holds all the functions and variables available everywhere. More...

virtual bool	hasUncaughtException () const =0
	Whether the script has an uncaught exception. More...

virtual bool	isEvaluating () const =0
	Whether a script is currently being evaluated. More...

virtual ScriptValue	checkScriptSyntax (ScriptProgramPointer program)=0
	Check a program for syntax errors. More...

ScriptManager *	manager () const
	Pointer to the ScriptManager that controls this scripting engine. More...

virtual ScriptValue	makeError (const ScriptValue &other, const QString &type="Error")=0
	Make a ScriptValue that contains an error. More...

virtual bool	raiseException (const ScriptValue &exception, const QString &reason=QString())=0
	Causes an exception to be raised in the currently executing script. More...

virtual bool	raiseException (const QString &error, const QString &reason=QString())=0
	Causes an exception to be raised in the currently executing script. More...

virtual std::shared_ptr< ScriptException >	uncaughtException () const =0
	Last uncaught exception, if any. More...

virtual void	compileTest ()=0
	Test the underlying scripting engine. More...

virtual void	logBacktrace (const QString &title)=0
	Log the current backtrace. More...

virtual ScriptEngineMemoryStatistics	getMemoryUsageStatistics ()=0
	Return memory usage statistics data. More...

virtual void	startCollectingObjectStatistics ()=0
	Start collecting object statistics that can later be reported with dumpHeapObjectStatistics().

virtual void	dumpHeapObjectStatistics ()=0
	Prints heap statistics to a file. Collecting needs to first be started with dumpHeapObjectStatistics().

virtual void	startProfiling ()=0
	Starts collecting profiling data.

virtual void	stopProfilingAndSave ()=0
	Stops collecting profiling data and saves it to a CSV file in Logs directory.

virtual void	disconnectSignalProxies ()=0
	Cleanup function that disconnects signals connected to script proxies to avoid use-after-delete crash when shutting down script engine.

Detailed Description

Provides an engine-independent interface for a scripting engine.

Each script engine is strictly single threaded.

This class only provides an interface to the underlying scripting engine, and doesn't provide the full environment needed to execute scripts.

To execute scripts that have access to the API, use ScriptManager.

Exception handling

Exceptions are handled in two directions: exceptions thrown by the code executing in the scripting engine, but not captured by the running code are caught by this object and can be inspected.

If an exception in the running code occurs, then the exception() signal is emitted. Also, hasUncaughtException() returns true, and uncaughException() returns the ScriptException with the details. Both the signal and uncaughtException() return the same information, and either can be used depending on what best fits the program.

To inject an exception into the running script, use raiseException(). This may result in the script not capturing it and an uncaughtException happening as a result.

Member Enumeration Documentation

◆ QObjectWrapOption

enum ScriptEngine::QObjectWrapOption

Which part of an object is exposed to the script.

Enumerator
ExcludeSuperClassMethods	The script object will not expose child objects as properties. The script object will not expose signals and slots inherited from the superclass.
ExcludeSuperClassProperties	The script object will not expose properties inherited from the superclass.
ExcludeSuperClassContents	The script object will not expose the QObject::deleteLater() slot.
ExcludeSlots	The script object will not expose the QObject's slots.
AutoCreateDynamicProperties	Properties that don't already exist in the QObject will be created as dynamic properties of that object, rather than as properties of the script object.
PreferExistingWrapperObject	If a wrapper object with the requested configuration already exists, return that object.
SkipMethodsInEnumeration	Don't include methods (signals and slots) when enumerating the object's properties.

◆ ValueOwnership

enum ScriptEngine::ValueOwnership

Who owns a given object.

Enumerator
QtOwnership	Object is managed by Qt.
ScriptOwnership	Object is managed by the script.
AutoOwnership	Ownership is determined automatically. If the object has a parent, it's deemed QtOwnership. If the object has no parent, it's deemed ScriptOwnership.

Member Function Documentation

◆ checkScriptSyntax()

virtual ScriptValue ScriptEngine::checkScriptSyntax ( ScriptProgramPointer program )

pure virtual

Check a program for syntax errors.

Returns an object with at least the following properties:

fileName
lineNumber
stack
formatted

Parameters

program Program to check

Returns: ScriptValue Result

Note: It could be a good improvement to redo this to return a struct instead.

◆ compileTest()

virtual void ScriptEngine::compileTest ( )

pure virtual

Test the underlying scripting engine.

This compiles, executes and verifies the execution of a trivial test program to make sure the underlying scripting engine actually works.

◆ currentContext()

virtual ScriptContext* ScriptEngine::currentContext ( ) const

pure virtual

Context of the currently running script.

This allows getting a backtrace, the local variables of the currently running function, etc.

Returns: ScriptContext*

◆ evaluate() [1/2]

virtual ScriptValue ScriptEngine::evaluate	(	const QString &	program,
		const QString &	fileName = `QString()`
	)

pure virtual

Runs a script.

This may be called several times during the lifetime of a scripting engine, with the side effects accumulating.

Parameters

program	Code to run
fileName	Name of the script, for informational purposes

Returns: ScriptValue Return value of the script when it finishes running.

◆ evaluate() [2/2]

virtual ScriptValue ScriptEngine::evaluate ( const ScriptProgramPointer & program )

pure virtual

Evaluates a pre-compiled program.

Parameters

program Program to evaluaate

Returns: ScriptValue

◆ evaluateInClosure()

virtual ScriptValue ScriptEngine::evaluateInClosure	(	const ScriptValue &	locals,
		const ScriptProgramPointer &	program
	)

pure virtual

Evaluate a script in a separate environment.

Used for evaluating included scripts

Parameters

locals	Local variables available to the script
program	Code to run

Returns: ScriptValue

◆ exception

void ScriptEngine::exception ( std::shared_ptr< ScriptException > exception )

signal

The script being run threw an exception.

Parameters

exception Exception that was thrown

◆ getMemoryUsageStatistics()

virtual ScriptEngineMemoryStatistics ScriptEngine::getMemoryUsageStatistics ( )

pure virtual

Return memory usage statistics data.

Returns memory usage statistics data for debugging.

Returns: ScriptEngineMemoryStatistics Object containing memory usage statistics data.

◆ globalObject()

virtual ScriptValue ScriptEngine::globalObject ( )

inlinevirtual

Global object which holds all the functions and variables available everywhere.

This is a JavaScript concept, https://javascript.info/global-object

Note: This may not belong in the base class.

Returns: ScriptValue Global Object

◆ hasUncaughtException()

virtual bool ScriptEngine::hasUncaughtException ( ) const

pure virtual

Whether the script has an uncaught exception.

Returns: true There is an uncaught exception; false There's no exception

◆ isEvaluating()

virtual bool ScriptEngine::isEvaluating ( ) const

pure virtual

Whether a script is currently being evaluated.

Returns: true A script is currently being evaluated; false No script is being evaluated

◆ logBacktrace()

virtual void ScriptEngine::logBacktrace ( const QString & title )

pure virtual

Log the current backtrace.

Logs the current backtrace for debugging

Parameters

title Informative title for the backtrace

◆ makeError()

virtual ScriptValue ScriptEngine::makeError	(	const ScriptValue &	other,
		const QString &	type = `"Error"`
	)

pure virtual

Make a ScriptValue that contains an error.

This is used to throw an error inside the running script

Parameters

other
type

Returns: ScriptValue ScriptValue containing error

◆ manager()

ScriptManager* ScriptEngine::manager ( ) const

inline

Pointer to the ScriptManager that controls this scripting engine.

Returns: ScriptManager* ScriptManager

◆ raiseException() [1/2]

virtual bool ScriptEngine::raiseException	(	const QString &	error,
		const QString &	reason = `QString()`
	)

pure virtual

Causes an exception to be raised in the currently executing script.

Parameters

error	Exception to be thrown in the script
reason	Explanatory text about why the exception happened, for logging

Returns: true Exception was successfully thrown; false Exception couldn't be thrown because no script is running

◆ raiseException() [2/2]

virtual bool ScriptEngine::raiseException	(	const ScriptValue &	exception,
		const QString &	reason = `QString()`
	)

pure virtual

Causes an exception to be raised in the currently executing script.

Parameters

exception	Exception to be thrown in the script
reason	Explanatory text about why the exception happened, for logging

Returns: true Exception was successfully thrown; false Exception couldn't be thrown because no script is running

◆ uncaughtException()

virtual std::shared_ptr<ScriptException> ScriptEngine::uncaughtException ( ) const

pure virtual

Last uncaught exception, if any.

The returned shared pointer is newly allocated by the function, and modifying it has no effect on the internal state of the ScriptEngine.

Returns: std::shared_ptr<ScriptValue> Uncaught exception from the script

The documentation for this class was generated from the following files:

ScriptEngine.h
ScriptEngine.cpp

Public Types

Signals

Public Member Functions

Detailed Description

Exception handling

Member Enumeration Documentation

◆ QObjectWrapOption

◆ ValueOwnership

Member Function Documentation

◆ checkScriptSyntax()

◆ compileTest()

◆ currentContext()

◆ evaluate() [1/2]

◆ evaluate() [2/2]

◆ evaluateInClosure()

◆ exception

◆ getMemoryUsageStatistics()

◆ globalObject()

◆ hasUncaughtException()

◆ isEvaluating()

◆ logBacktrace()

◆ makeError()

◆ manager()

◆ raiseException() [1/2]

◆ raiseException() [2/2]

◆ uncaughtException()