JUCE  v5.4.1-191-g0ab5e696f
JUCE API
Looking for a senior C++ dev?
I'm looking for work. Hire me!
juce::JavascriptEngine Class Referencefinal

A simple javascript interpreter! More...

#include <juce_Javascript.h>

Collaboration diagram for juce::JavascriptEngine:

Public Member Functions

 JavascriptEngine ()
 Creates an instance of the engine. More...
 
 ~JavascriptEngine ()
 Destructor. More...
 
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 callFunctionObject (DynamicObject *objectScope, const var &functionObject, const var::NativeFunctionArgs &args, Result *errorMessage=nullptr)
 Calls a function object in the namespace of a dynamic object, 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)
 Attempts to parse and run a block of javascript code. More...
 
const NamedValueSetgetRootObjectProperties () const noexcept
 Provides access to the set of properties of the root namespace object. More...
 
void registerNativeObject (const Identifier &objectName, DynamicObject *object)
 Adds a native object to the root namespace. More...
 
void stop () noexcept
 When called from another thread, causes the interpreter to time-out as soon as possible. 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...
 

Private Member Functions

void prepareTimeout () const noexcept
 

Private Attributes

const ReferenceCountedObjectPtr< RootObject > root
 

Detailed Description

A simple javascript interpreter!

It's not fully standards-compliant, and won't be as fast as the fancy JIT-compiled engines that you get in browsers, but this is an extremely compact, low-overhead javascript interpreter, which is integrated with the juce var and DynamicObject classes. If you need a few simple bits of scripting in your app, and want to be able to easily let the JS work with native objects defined as DynamicObject subclasses, then this might do the job.

To use, simply create an instance of this class and call execute() to run your code. Variables that the script sets can be retrieved with evaluate(), and if you need to provide native objects for the script to use, you can add them with registerNativeObject().

One caveat: Because the values and objects that the engine works with are DynamicObject and var objects, they use reference-counting rather than garbage-collection, so if your script creates complex connections between objects, you run the risk of creating cyclic dependencies and hence leaking.

{Core}

Constructor & Destructor Documentation

◆ JavascriptEngine()

juce::JavascriptEngine::JavascriptEngine ( )

Creates an instance of the engine.

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

◆ ~JavascriptEngine()

juce::JavascriptEngine::~JavascriptEngine ( )

Destructor.

Member Function Documentation

◆ callFunction()

var juce::JavascriptEngine::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.

◆ callFunctionObject()

var juce::JavascriptEngine::callFunctionObject ( DynamicObject objectScope,
const var functionObject,
const var::NativeFunctionArgs args,
Result errorMessage = nullptr 
)

Calls a function object in the namespace of a dynamic object, and returns the result.

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

◆ evaluate()

var juce::JavascriptEngine::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.

◆ execute()

Result juce::JavascriptEngine::execute ( const String javascriptCode)

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.

◆ getRootObjectProperties()

const NamedValueSet& juce::JavascriptEngine::getRootObjectProperties ( ) const
noexcept

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

◆ prepareTimeout()

void juce::JavascriptEngine::prepareTimeout ( ) const
privatenoexcept

◆ registerNativeObject()

void juce::JavascriptEngine::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.

◆ stop()

void juce::JavascriptEngine::stop ( )
noexcept

When called from another thread, causes the interpreter to time-out as soon as possible.

Member Data Documentation

◆ maximumExecutionTime

RelativeTime juce::JavascriptEngine::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.

◆ root

const ReferenceCountedObjectPtr<RootObject> juce::JavascriptEngine::root
private

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