HiseJavascriptEngine Class Reference

The HISE Javascript Engine. More...

Public Member Functions
var	callFunction (const Identifier &function, const var::NativeFunctionArgs &args, Result *errorMessage=nullptr)
	Calls a function in the root namespace, and returns the result. More...
var	evaluate (const String &javascriptCode, Result *errorMessage=nullptr)
	Attempts to parse and run a javascript expression, and returns the result. More...
Result	execute (const String &javascriptCode, bool allowConstDeclarations=true)
	Attempts to parse and run a block of javascript code. More...
const NamedValueSet &	getRootObjectProperties () const noexcept
	Provides access to the set of properties of the root namespace object. More...
	HiseJavascriptEngine (JavascriptProcessor *p)
	Creates an instance of the engine. More...
int	registerCallbackName (const Identifier &callbackName, int numArgs, double bufferTime)
	Registers a callback to the engine. More...
void	registerNativeObject (const Identifier &objectName, DynamicObject *object)
	Adds a native object to the root namespace. More...
	~HiseJavascriptEngine ()
	Destructor. More...

Public Attributes
RelativeTime	maximumExecutionTime
	This value indicates how long a call to one of the evaluate methods is permitted to run before timing-out and failing. More...

Detailed Description

The HISE Javascript Engine.

This class is a modified version of the original Javascript engine found in JUCE. It adds some language features that were missing in the original code:

• switch statements
• const (immutable) variables
• for ... in iterator loop

As well as some HISE specific features, which are not standard Javascript, but a useful addition for a DSP scripting language. However, they don't break any Javascript features.

Inline Functions no overhead inlining of functions with parameters and return value).

inline function square(x)
{
    return x*x;
};

C++ API Wrapper class

A class interface for low overhead calling of C++ functions / methods. Instead of using the standard DynamicObject class, which involves O(n) lookup, allocations and creating a scope for each function call, calling a ApiClass method comes with almost no overhead (it directly accesses the C++ function via a func pointer).

See also

ApiClass

VariantBuffer

A native object type to efficiently operate on an array of floats. There are also some overloaded operators for making things faster to type (and execute!):

var buffer = Buffer.create(256); // Creates a buffer with 256 samples
0.5 >> buffer;                   // Fills the buffer with 0.5;
buffer * 1.2;                    // Multiplies every sample with 1.2;
for (s in buffer) s = s * 1.2;   // Does the same thing but for each sample (much slower).

See also

VariantBuffer.

Register variables

A special storage location with accelerated access / lookup times. There are 32 slots which can be directly from Javascript (without a lookup in the NamedValueSet of a scope) to improve the performance for temporary / working variables.

See also

VarRegister

Constructor & Destructor Documentation

HiseJavascriptEngine

(

JavascriptProcessor *

p

)

Creates an instance of the engine.

This creates a root namespace and defines some basic Object, String, Array and Math library methods.

~HiseJavascriptEngine

(

)

Destructor.

Member Function Documentation

var callFunction	(	const Identifier &	function,
		const var::NativeFunctionArgs &	args,
		Result *	errorMessage = nullptr
	)

Calls a function in the root namespace, and returns the result.

The function arguments are passed in the same format as used by native methods in the var class.

var evaluate	(	const String &	javascriptCode,
		Result *	errorMessage = nullptr
	)

Attempts to parse and run a javascript expression, and returns the result.

If there's a syntax error, or the expression can't be evaluated, the return value will be var::undefined(). The errorMessage parameter gives you a way to find out any parsing errors. You can specify a maximum time for which the program is allowed to run, and it'll return with an error message if this time is exceeded.

Result execute	(	const String &	javascriptCode,
		bool	allowConstDeclarations = true
	)

Attempts to parse and run a block of javascript code.

If there's a parse or execution error, the error description is returned in the result. You can specify a maximum time for which the program is allowed to run, and it'll return with an error message if this time is exceeded.

const NamedValueSet & getRootObjectProperties ( ) const

noexcept

Provides access to the set of properties of the root namespace object.

int registerCallbackName	(	const Identifier &	callbackName,
		int	numArgs,
		double	bufferTime
	)

Registers a callback to the engine.

If a function with this name is found at parsing, it will be stored as callback for faster execution:

• no scope (only global variables)
• no arguments
• no overhead if the callback is not found

void registerNativeObject	(	const Identifier &	objectName,
		DynamicObject *	object
	)

Adds a native object to the root namespace.

The object passed-in is reference-counted, and will be retained by the engine until the engine is deleted. The name must be a simple JS identifier, without any dots.

Member Data Documentation

RelativeTime maximumExecutionTime

This value indicates how long a call to one of the evaluate methods is permitted to run before timing-out and failing.

The default value is a number of seconds, but you can change this to whatever value suits your application.