JSCursor Class Reference

A high-level wrapper around an owning root JSObject and a hierarchical path relative to it. More...

#include <juce_Javascript.h>

Public Member Functions
	JSCursor (JSObject root)
	Creates a JSCursor that points to the provided root object and also participates in its ownership.
JSObject	getOrCreateObject () const
	Returns an owning reference to the Javascript Object at the cursor's location.
var	get () const
	Returns the value corresponding to the Object that the cursor points to.
void	set (const var &value) const
	Sets the Object under the cursor's location to the specified value.
var	invoke (Span< const var > args, Result *result=nullptr) const
	Invokes this node as though it were a method.
var	operator() (Span< const var > args, Result *result=nullptr) const
	Equivalent to invoke().
JSCursor	getChild (const Identifier &name) const
	Returns a new cursor that has the same root Object as the parent and has the name parameter appended to the cursor's location.
JSCursor	operator[] (const Identifier &name) const
	Returns a new cursor that has the same root Object as the parent and has the name parameter appended to the cursor's location.
JSCursor	getChild (int64 index) const
	Returns a new cursor that has the same root Object as the parent and has the index parameter appended to the cursor's location.
JSCursor	operator[] (int64 index) const
	Returns a new cursor that has the same root Object as the parent and has the index parameter appended to the cursor's location.
bool	isValid () const
	Returns true if the location of the cursor is reachable from the cursor's JSObject root.
bool	isArray () const
	Returns true if there is an Array under the cursor's location.

Detailed Description

A high-level wrapper around an owning root JSObject and a hierarchical path relative to it.

It can be used to query and manipulate the location relative to the root JSObject in the Javascript Object graph. A cursor only maintains ownership of the root Object. So as long as a cursor points at the root it will always remain in a valid state, and isValid will return true.

Using getChild you can add elements to the cursor's relative path. You need to ensure that the cursor is in a valid state when calling get or set in such cases. You can use the isValid function to determine if the cursor currently points to a reachable location.

Constructor & Destructor Documentation

JSCursor()

JSCursor::JSCursor ( JSObject root )

explicit

Creates a JSCursor that points to the provided root object and also participates in its ownership.

This guarantees that this root object will remain valid for the lifetime of this cursor.

Child JSCursors created by getChild() will contain this same root object and each will further ensure that this root remains valid through reference counting.

While the validity of the root is ensured through shared ownership, the JSCursor itself is not guaranteed to be valid, unless its also pointing directly at the root.

See also

isValid

Member Function Documentation

getOrCreateObject()

JSObject JSCursor::getOrCreateObject

(

)

const

Returns an owning reference to the Javascript Object at the cursor's location.

If there is no Object at the location but the cursor is valid, a new Object will be created.

You must only call this function on a valid JSCursor.

By creating an owning reference, you can create a new JSCursor object that owns the underlying object and is guaranteed to remain in a valid state e.g.

JSCursor rootCursor { engine.getRootObject() };
auto nonOwningCursor = rootCursor["path"]["to"]["object"];
 
jassert (nonOwningCursor.isValid());
 
JSCursor owningCursor { nonOwningCursor.getOrCreateObject(); };
engine.execute (arbitraryScript);
 
// owningCursor is guaranteed to remain valid even after subsequent script evaluations
jassert (owningCursor.isValid());

See also

isValid

get()

var JSCursor::get

(

)

const

Returns the value corresponding to the Object that the cursor points to.

If there is no Object at the cursor's location var::undefined() is returned.

This function is safe to call for invalid cursors.

See also

isValid

set()

void JSCursor::set

(

const var &

value

)

const

Sets the Object under the cursor's location to the specified value.

You must only call this function for valid cursors.

See also

isValid

invoke()

var JSCursor::invoke	(	Span< const var >	args,
		Result *	result = nullptr ) const

Invokes this node as though it were a method.

If the optional Result pointer is provided it will contain Result::ok() in case of success, or an error message in case an exception was thrown during evaluation.

You must only call this function for valid cursors.

operator()()

var JSCursor::operator()	(	Span< const var >	args,
		Result *	result = nullptr ) const

Equivalent to invoke().

getChild() [1/2]

JSCursor JSCursor::getChild

(

const Identifier &

name

)

const

Returns a new cursor that has the same root Object as the parent and has the name parameter appended to the cursor's location.

If the new path points to a location unreachable from the root, the resulting JSCursor object will be invalid. This however can change due to subsequent script executions.

operator[]() [1/2]

JSCursor JSCursor::operator[]

(

const Identifier &

name

)

const

Returns a new cursor that has the same root Object as the parent and has the name parameter appended to the cursor's location.

If the new path points to a location unreachable from the root, the resulting JSCursor object will be invalid. This however can change due to subsequent script executions. Shorthand for getChild.

getChild() [2/2]

JSCursor JSCursor::getChild

(

int64

index

)

const

Returns a new cursor that has the same root Object as the parent and has the index parameter appended to the cursor's location.

This overload will create a path that indexes into an Array.

If the new path points to a location unreachable from the root, the resulting JSCursor object will be invalid. This however can change due to subsequent script executions.

operator[]() [2/2]

JSCursor JSCursor::operator[]

(

int64

index

)

const

Returns a new cursor that has the same root Object as the parent and has the index parameter appended to the cursor's location.

This overload will create a path that indexes into an Array.

If the new path points to a location unreachable from the root, the resulting JSCursor object will be invalid. This however can change due to subsequent script executions. Shorthand for getChild.

isValid()

bool JSCursor::isValid

(

)

const

Returns true if the location of the cursor is reachable from the cursor's JSObject root.

This means it is safe to call set on this JSCursor and the location will then point to an Object corresponding to the supplied value.

It isn't guaranteed that there is already an Object at this location, in which case calling get will return var::undefined().

isArray()

bool JSCursor::isArray

(

)

const

Returns true if there is an Array under the cursor's location.

It is safe to call this function on an invalid cursor.

---

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

• juce_Javascript.h