Executes a script. More...

#include <process.h>

Classes
class	HangError
	Execution is taking too long to complete. More...

class	NotStoppedError
	The process is running while an operation is attempted that requires the process to be stopped. More...

class	SuspendError
	Suspending or resuming fails. More...

Public Types
enum	CallResult { IgnoreResult, TakeResult }

using	Namespaces = Evaluator::Namespaces

enum	State { Running, Suspended, Stopped }
	A process is always in one of these states. More...

Public Member Functions
	Process (Record *externalGlobalNamespace=0)
	Constructs a new process. More...

	Process (Script const &script)
	Constructs a new process. More...

void	call (Function const &function, ArrayValue const &arguments, Value *self=0)
	Performs a function call. More...

void	clear ()
	Resets the process to an empty state. More...

Context &	context (duint downDepth=0)
	Return an execution context. More...

dsize	depth () const
	Determines the current depth of the call stack. More...

void	execute ()
	Execute the next command(s) in the script. More...

void	finish (Value *returnValue=0)
	Finish the execution of the topmost context. More...

Record &	globals ()
	Returns the global namespace of the process. More...

Record &	locals ()
	Returns the local namespace of the process. More...

void	namespaces (Namespaces &spaces) const
	Collects the namespaces currently visible. More...

Context *	popContext ()
	Pops the topmost context off the stack and returns it. More...

void	pushContext (Context *context)
	Pushes a new context to the process's stack. More...

void	run (Script const &script)
	Starts running the given script. More...

void	setWorkingPath (String const &newWorkingPath)
	Changes the working path of the process. More...

State	state () const

void	stop ()
	Stops the execution of the script. More...

void	suspend (bool suspended=true)
	Suspends or resumes execution of the script. More...

String const &	workingPath () const
	Returns the current working path. More...

Static Public Member Functions
template<typename... Args>
static Value *	scriptCall (CallResult result, Record &globals, String const &function, Args... args)
	Calls a script function. More...

template<typename ReturnValueType , typename... Args>
static ReturnValueType *	scriptCall (Record &globals, String const &function, Args... args)

Detailed Description

Executes a script.

The process maintains the execution environment, including things like local variables and keeping track of which statement is being executed.

Definition at line 155 of file process.h.

Member Typedef Documentation

◆ Namespaces

using de::Process::Namespaces = Evaluator::Namespaces

Definition at line 179 of file process.h.

Member Enumeration Documentation

◆ CallResult

enum de::Process::CallResult

Enumerator
IgnoreResult
TakeResult

Definition at line 330 of file process.h.

◆ State

enum de::Process::State

A process is always in one of these states.

Enumerator

Running

The process is running normally.

Suspended

The process has been suspended and will not continue running until restored.

A process cannot restore itself from a suspended state.

Stopped

The process has reached the end of the script or has been terminated.

Definition at line 169 of file process.h.

Constructor & Destructor Documentation

◆ Process() [1/2]

de::Process::Process ( Record * externalGlobalNamespace = 0 )

Constructs a new process.

The process is initialized to STOPPED state.

Parameters

externalGlobalNamespace Namespace to use as the global namespace of the process. If not specified, a private global namespace is created for the process. The process does not get ownership of the external global namespace.

Definition at line 150 of file process.cpp.

◆ Process() [2/2]

de::Process::Process ( Script const & script )

Constructs a new process.

The process is initialized to RUNNING state.

Parameters

script Script to run. No reference to the script is retained apart from pointing to its statements. The script instance must remain in existence while the process is running, as it is the owner of the statements.

Definition at line 158 of file process.cpp.

Member Function Documentation

◆ call()

void de::Process::call	(	Function const &	function,
		ArrayValue const &	arguments,
		Value *	self = `0`
	)

Performs a function call.

A new context is created on the context stack and the function's statements are executed on the new stack. After the call is finished, the result value is pushed to the calling context's evaluator.

Parameters

function	Function to call.
arguments	Arguments for the function. The array's first element must be a DictionaryValue containing values for the named arguments of the call. The rest of the array are the unnamed arguments.
self	Optional scope that becomes the value of the "self" variable. Ownership given to Process.

Definition at line 351 of file process.cpp.

◆ clear()

void de::Process::clear ( )

Resets the process to an empty state.

All existing content in the process's context stack is removed, leaving the process in a similar state than after construction.

Definition at line 171 of file process.cpp.

◆ context()

Context & de::Process::context ( duint downDepth = 0 )

Return an execution context.

By default returns the topmost context.

Parameters

downDepth How many levels to go down. There are depth() levels in the context stack.

Returns: Context at downDepth.

Definition at line 285 of file process.cpp.

◆ depth()

dsize de::Process::depth ( ) const

Determines the current depth of the call stack.

Definition at line 176 of file process.cpp.

◆ execute()

void de::Process::execute ( )

Execute the next command(s) in the script.

Execution continues until the script leaves RUNNING state.

Exceptions

HangError Execution takes too long.

Definition at line 222 of file process.cpp.

◆ finish()

void de::Process::finish ( Value * returnValue = 0 )

Finish the execution of the topmost context.

Execution will continue from the second topmost context.

Parameters

returnValue Value to use as the return value from the context. Takes ownership of the value.

Definition at line 310 of file process.cpp.

◆ globals()

Record & de::Process::globals ( )

Returns the global namespace of the process.

This is always the bottommost context in the stack.

Definition at line 436 of file process.cpp.

◆ locals()

Record & de::Process::locals ( )

Returns the local namespace of the process.

This is always the topmost context in the stack.

Definition at line 450 of file process.cpp.

◆ namespaces()

void de::Process::namespaces ( Namespaces & spaces ) const

Collects the namespaces currently visible.

This includes the process's own stack and the global namespaces.

Parameters

spaces The namespaces are collected here. The order is important: earlier namespaces shadow the subsequent ones.

Definition at line 411 of file process.cpp.

◆ popContext()

Context * de::Process::popContext ( )

Pops the topmost context off the stack and returns it.

Ownership given to caller.

Definition at line 295 of file process.cpp.

◆ pushContext()

void de::Process::pushContext ( Context * context )

Pushes a new context to the process's stack.

Parameters

context Context. Ownership taken.

Definition at line 290 of file process.cpp.

◆ run()

void de::Process::run ( Script const & script )

Starts running the given script.

Note that the process must be in the FINISHED state for this to be a valid operation.

Parameters

script Script to run. No reference to the script is retained apart from pointing to its statements. The script instance must remain in existence while the process is running, as it is the owner of the statements.

Definition at line 181 of file process.cpp.

◆ scriptCall() [1/2]

template<typename... Args>

static Value* de::Process::scriptCall	(	CallResult	result,
		Record &	globals,
		String const &	function,
		Args...	args
	)

inlinestatic

Calls a script function.

Native arguments are converted to script source text and then parsed into Values when the call is executed.

Only non-named function arguments are supported by this method.

The namespace global may be modified if some of the argument values require variables, e.g., for refering Records. The created variables are named __argN__, with N being an increasing number.

Parameters

result	What to do with the result value.
globals	Global namespace where to execute the call.
function	Name of the function.
args	Argument values for the function call.

Returns: Depending on result, returns nullptr or the return value from the call. Caller gets ownership of the possibly returned Value.

Definition at line 351 of file process.h.

◆ scriptCall() [2/2]

template<typename ReturnValueType , typename... Args>

static ReturnValueType* de::Process::scriptCall	(	Record &	globals,
		String const &	function,
		Args...	args
	)

inlinestatic

Definition at line 366 of file process.h.

◆ setWorkingPath()

void de::Process::setWorkingPath ( String const & newWorkingPath )

Changes the working path of the process.

File system access within the process is relative to the working path.

Parameters

newWorkingPath New working path for the process.

Definition at line 346 of file process.cpp.

◆ state()

Process::State de::Process::state ( ) const

Definition at line 166 of file process.cpp.

◆ stop()

void de::Process::stop ( )

Stops the execution of the script.

The process is set to the FINISHED state, which means it must be rerun with a new script.

Definition at line 200 of file process.cpp.

◆ suspend()

void de::Process::suspend ( bool suspended = true )

Suspends or resumes execution of the script.

Definition at line 189 of file process.cpp.

◆ workingPath()

String const & de::Process::workingPath ( ) const

Returns the current working path.

Definition at line 341 of file process.cpp.

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

sdk/libcore/include/de/scriptsys/process.h
sdk/libcore/src/scriptsys/process.cpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

◆ Namespaces

Member Enumeration Documentation

◆ CallResult

◆ State

Constructor & Destructor Documentation

◆ Process() [1/2]

◆ Process() [2/2]

Member Function Documentation

◆ call()

◆ clear()

◆ context()

◆ depth()

◆ execute()

◆ finish()

◆ globals()

◆ locals()

◆ namespaces()

◆ popContext()

◆ pushContext()

◆ run()

◆ scriptCall() [1/2]

◆ scriptCall() [2/2]

◆ setWorkingPath()

◆ state()

◆ stop()

◆ suspend()

◆ workingPath()