juce::JSCursor Class Reference

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

#include <juce_JSCursor.h>

Collaboration diagram for juce::JSCursor:

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

Private Types
using	PartialResolution = std::pair< JSObject, std::optional< Property > >
using	Property = std::variant< Identifier, int64 >

Private Member Functions
std::optional< JSObject >	getFullResolution () const
std::optional< PartialResolution >	getPartialResolution () const

Static Private Member Functions
static std::optional< JSObject >	resolve (JSObject reference, Property property)

Private Attributes
std::vector< Property >	path
JSObject	root

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.

@tags{Core}

Member Typedef Documentation

PartialResolution

using juce::JSCursor::PartialResolution = std::pair<JSObject, std::optional<Property> >

private

Property

using juce::JSCursor::Property = std::variant<Identifier, int64>

private

Constructor & Destructor Documentation

JSCursor()

juce::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

get()

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

getChild() [1/2]

JSCursor juce::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.

getChild() [2/2]

JSCursor juce::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.

getFullResolution()

std::optional< JSObject > juce::JSCursor::getFullResolution ( ) const

private

getOrCreateObject()

JSObject juce::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

getPartialResolution()

std::optional< PartialResolution > juce::JSCursor::getPartialResolution ( ) const

private

invoke()

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

isArray()

bool juce::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.

isValid()

bool juce::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().

operator()()

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

inline

Equivalent to invoke().

operator[]() [1/2]

JSCursor juce::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.

operator[]() [2/2]

JSCursor juce::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.

resolve()

static std::optional< JSObject > juce::JSCursor::resolve ( JSObject  reference, Property  property  )

staticprivate

set()

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

Member Data Documentation

path

std::vector<Property> juce::JSCursor::path

private

root

JSObject juce::JSCursor::root

private

---

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

• juce_JSCursor.h