Wraps SM APIs for manipulating JS objects. More...

Typedefs
using	StructuredClone = std::shared_ptr< JSStructuredCloneData >
	Structured clones are a way to serialize 'simple' JS::Values into a buffer that can safely be passed between compartments and between threads. More...

Functions
std::string	ToString (const ScriptRequest &rq, JS::MutableHandleValue obj, bool pretty=false)
	Convert an object to a UTF-8 encoded string, either with JSON (if pretty == true and there is no JSON error) or with toSource(). More...

bool	ParseJSON (const ScriptRequest &rq, const std::string &string_utf8, JS::MutableHandleValue out)
	Parse a UTF-8-encoded JSON string. More...

void	ReadJSONFile (const ScriptRequest &rq, const VfsPath &path, JS::MutableHandleValue out)
	Read a JSON file. More...

std::string	StringifyJSON (const ScriptRequest &rq, JS::MutableHandleValue obj, bool indent=true)
	Stringify to a JSON string, UTF-8 encoded. More...

template<typename PropType >
bool	GetProperty (const ScriptRequest &rq, JS::HandleValue obj, PropType name, JS::MutableHandleValue out)
	Get the named property on the given object. More...

template<typename T , typename PropType >
bool	GetProperty (const ScriptRequest &rq, JS::HandleValue obj, PropType name, T &out)

bool	GetProperty (const ScriptRequest &rq, JS::HandleValue obj, const char *name, JS::MutableHandleObject out)

template<typename T >
bool	GetPropertyInt (const ScriptRequest &rq, JS::HandleValue obj, int name, T &out)

bool	GetPropertyInt (const ScriptRequest &rq, JS::HandleValue obj, int name, JS::MutableHandleValue out)

bool	HasProperty (const ScriptRequest &rq, JS::HandleValue obj, const char *name)
	Check the named property has been defined on the given object. More...

template<typename PropType >
bool	SetProperty (const ScriptRequest &rq, JS::HandleValue obj, PropType name, JS::HandleValue value, bool constant=false, bool enumerable=true)
	Set the named property on the given object. More...

template<typename T , typename PropType >
bool	SetProperty (const ScriptRequest &rq, JS::HandleValue obj, PropType name, const T &value, bool constant=false, bool enumerable=true)

template<typename T >
bool	SetPropertyInt (const ScriptRequest &rq, JS::HandleValue obj, int name, const T &value, bool constant=false, bool enumerable=true)

template<typename T >
bool	GetObjectClassName (const ScriptRequest &rq, JS::HandleObject obj, T &name)

template<typename T >
bool	GetObjectClassName (const ScriptRequest &rq, JS::HandleValue val, T &name)
	Get the name of the object's class. More...

bool	FreezeObject (const ScriptRequest &rq, JS::HandleValue objVal, bool deep)

bool	EnumeratePropertyNames (const ScriptRequest &rq, JS::HandleValue objVal, bool enumerableOnly, std::vector< std::string > &out)
	Returns all properties of the object, both own properties and inherited. More...

JS::Value	CreateObject (const ScriptRequest &rq)
	Create a plain object (i.e. More...

bool	CreateObject (const ScriptRequest &rq, JS::MutableHandleValue objectValue)

template<typename T , typename... Args>
bool	CreateObject (const ScriptRequest &rq, JS::MutableHandleValue objectValue, const char *propertyName, const T &propertyValue, Args const &... args)
	Sets the given value to a new plain JS::Object, converts the arguments to JS::Values and sets them as properties. More...

bool	CreateArray (const ScriptRequest &rq, JS::MutableHandleValue objectValue, size_t length=0)
	Sets the given value to a new JS object or Null Value in case of out-of-memory. More...

template<typename T >
bool	FromJSVal (const ScriptRequest &rq, const JS::HandleValue val, T &ret)
	Convert a JS::Value to a C++ type. More...

template<typename T >
void	ToJSVal (const ScriptRequest &rq, JS::MutableHandleValue ret, T const &val)
	Convert a C++ type to a JS::Value. More...

template<>
void	ToJSVal< JS::PersistentRootedValue > (const ScriptRequest &rq, JS::MutableHandleValue handle, const JS::PersistentRootedValue &a)

template<>
void	ToJSVal< JS::Heap< JS::Value > > (const ScriptRequest &rq, JS::MutableHandleValue handle, const JS::Heap< JS::Value > &a)

template<>
void	ToJSVal< JS::RootedValue > (const ScriptRequest &rq, JS::MutableHandleValue handle, const JS::RootedValue &a)

template<>
void	ToJSVal< JS::HandleValue > (const ScriptRequest &rq, JS::MutableHandleValue handle, const JS::HandleValue &a)

template<typename T >
bool	FromJSProperty (const ScriptRequest &rq, const JS::HandleValue val, const char *name, T &ret, bool strict=false)
	Convert a named property of an object to a C++ type. More...

template<typename T >
void	ToJSVal_vector (const ScriptRequest &rq, JS::MutableHandleValue ret, const std::vector< T > &val)

template<typename T >
bool	FromJSVal_vector (const ScriptRequest &rq, JS::HandleValue v, std::vector< T > &out)

StructuredClone	WriteStructuredClone (const ScriptRequest &rq, JS::HandleValue v)

void	ReadStructuredClone (const ScriptRequest &rq, const StructuredClone &ptr, JS::MutableHandleValue ret)

JS::Value	CloneValueFromOtherCompartment (const ScriptInterface &to, const ScriptInterface &from, JS::HandleValue val)
	Construct a new value by cloning a value (possibly from a different Compartment). More...

JS::Value	DeepCopy (const ScriptRequest &rq, JS::HandleValue val)
	Clone a JS value, ensuring that changes to the result won't affect the original value. More...

Detailed Description

Wraps SM APIs for manipulating JS objects.

Typedef Documentation

◆ StructuredClone

using Script::StructuredClone = typedef std::shared_ptr<JSStructuredCloneData>

Structured clones are a way to serialize 'simple' JS::Values into a buffer that can safely be passed between compartments and between threads.

A StructuredClone can be stored and read multiple times if desired. We wrap them in shared_ptr so memory management is automatic and thread-safe.

Function Documentation

◆ CloneValueFromOtherCompartment()

JS::Value Script::CloneValueFromOtherCompartment	(	const ScriptInterface &	to,
		const ScriptInterface &	from,
		JS::HandleValue	val
	)

Construct a new value by cloning a value (possibly from a different Compartment).

Complex values (functions, XML, etc) won't be cloned correctly, but basic types and cyclic references should be fine. Takes ScriptInterfaces to enter the correct realm. Caller beware - manipulating several compartments in the same function is tricky.

Parameters

to	- ScriptInterface of the target. Should match the rooting context of the result.
from	- ScriptInterface of val.

◆ CreateArray()

bool Script::CreateArray	(	const ScriptRequest &	rq,
		JS::MutableHandleValue	objectValue,
		size_t	length = `0`
	)

inline

Sets the given value to a new JS object or Null Value in case of out-of-memory.

◆ CreateObject() [1/3]

JS::Value Script::CreateObject ( const ScriptRequest & rq )

inline

Create a plain object (i.e.

{}). If it fails, returns undefined.

◆ CreateObject() [2/3]

bool Script::CreateObject	(	const ScriptRequest &	rq,
		JS::MutableHandleValue	objectValue
	)

inline

◆ CreateObject() [3/3]

template<typename T , typename... Args>

bool Script::CreateObject	(	const ScriptRequest &	rq,
		JS::MutableHandleValue	objectValue,
		const char *	propertyName,
		const T &	propertyValue,
		Args const &...	args
	)

inline

Sets the given value to a new plain JS::Object, converts the arguments to JS::Values and sets them as properties.

This is static so that callers like ToJSVal can use it with the JSContext directly instead of having to obtain the instance using GetScriptInterfaceAndCBData. Can throw an exception.

◆ DeepCopy()

JS::Value Script::DeepCopy	(	const ScriptRequest &	rq,
		JS::HandleValue	val
	)

Clone a JS value, ensuring that changes to the result won't affect the original value.

Works by cloning, so the same restrictions as CloneValueFromOtherCompartment apply.

◆ EnumeratePropertyNames()

bool Script::EnumeratePropertyNames	(	const ScriptRequest &	rq,
		JS::HandleValue	objVal,
		bool	enumerableOnly,
		std::vector< std::string > &	out
	)

inline

Returns all properties of the object, both own properties and inherited.

This is essentially equivalent to calling Object.getOwnPropertyNames() and recursing up the prototype chain. NB: this does not return properties with symbol or numeric keys, as that would require a variant in the vector, and it's not useful for now.

Parameters

enumerableOnly - only return enumerable properties.

◆ FreezeObject()

bool Script::FreezeObject	(	const ScriptRequest &	rq,
		JS::HandleValue	objVal,
		bool	deep
	)

inline

◆ FromJSProperty()

template<typename T >

bool Script::FromJSProperty	(	const ScriptRequest &	rq,
		const JS::HandleValue	val,
		const char *	name,
		T &	ret,
		bool	strict = `false`
	)

inline

Convert a named property of an object to a C++ type.

◆ FromJSVal()

template<typename T >

bool Script::FromJSVal	(	const ScriptRequest &	rq,
		const JS::HandleValue	val,
		T &	ret
	)

Convert a JS::Value to a C++ type.

(This might trigger GC.)

◆ FromJSVal_vector()

template<typename T >

bool Script::FromJSVal_vector	(	const ScriptRequest &	rq,
		JS::HandleValue	v,
		std::vector< T > &	out
	)

inline

◆ GetObjectClassName() [1/2]

template<typename T >

bool Script::GetObjectClassName	(	const ScriptRequest &	rq,
		JS::HandleObject	obj,
		T &	name
	)

inline

◆ GetObjectClassName() [2/2]

template<typename T >

bool Script::GetObjectClassName	(	const ScriptRequest &	rq,
		JS::HandleValue	val,
		T &	name
	)

inline

Get the name of the object's class.

Note that inheritance may lead to unexpected results.

◆ GetProperty() [1/3]

template<typename PropType >

bool Script::GetProperty	(	const ScriptRequest &	rq,
		JS::HandleValue	obj,
		PropType	name,
		JS::MutableHandleValue	out
	)

inline

Get the named property on the given object.

◆ GetProperty() [2/3]

template<typename T , typename PropType >

bool Script::GetProperty	(	const ScriptRequest &	rq,
		JS::HandleValue	obj,
		PropType	name,
		T &	out
	)

inline

◆ GetProperty() [3/3]

bool Script::GetProperty	(	const ScriptRequest &	rq,
		JS::HandleValue	obj,
		const char *	name,
		JS::MutableHandleObject	out
	)

inline

◆ GetPropertyInt() [1/2]

template<typename T >

bool Script::GetPropertyInt	(	const ScriptRequest &	rq,
		JS::HandleValue	obj,
		int	name,
		T &	out
	)

inline

◆ GetPropertyInt() [2/2]

bool Script::GetPropertyInt	(	const ScriptRequest &	rq,
		JS::HandleValue	obj,
		int	name,
		JS::MutableHandleValue	out
	)

inline

◆ HasProperty()

bool Script::HasProperty	(	const ScriptRequest &	rq,
		JS::HandleValue	obj,
		const char *	name
	)

inline

Check the named property has been defined on the given object.

◆ ParseJSON()

bool Script::ParseJSON	(	const ScriptRequest &	rq,
		const std::string &	string_utf8,
		JS::MutableHandleValue	out
	)

Parse a UTF-8-encoded JSON string.

Returns the unmodified value on error and prints an error message.

Returns: true on success; false otherwise

◆ ReadJSONFile()

void Script::ReadJSONFile	(	const ScriptRequest &	rq,
		const VfsPath &	path,
		JS::MutableHandleValue	out
	)

Read a JSON file.

Returns the unmodified value on error and prints an error message.

◆ ReadStructuredClone()

void Script::ReadStructuredClone	(	const ScriptRequest &	rq,
		const StructuredClone &	ptr,
		JS::MutableHandleValue	ret
	)

◆ SetProperty() [1/2]

template<typename PropType >

bool Script::SetProperty	(	const ScriptRequest &	rq,
		JS::HandleValue	obj,
		PropType	name,
		JS::HandleValue	value,
		bool	constant = `false`,
		bool	enumerable = `true`
	)

inline

Set the named property on the given object.

◆ SetProperty() [2/2]

template<typename T , typename PropType >

bool Script::SetProperty	(	const ScriptRequest &	rq,
		JS::HandleValue	obj,
		PropType	name,
		const T &	value,
		bool	constant = `false`,
		bool	enumerable = `true`
	)

inline

◆ SetPropertyInt()

template<typename T >

bool Script::SetPropertyInt	(	const ScriptRequest &	rq,
		JS::HandleValue	obj,
		int	name,
		const T &	value,
		bool	constant = `false`,
		bool	enumerable = `true`
	)

inline

◆ StringifyJSON()

std::string Script::StringifyJSON	(	const ScriptRequest &	rq,
		JS::MutableHandleValue	obj,
		bool	indent = `true`
	)

Stringify to a JSON string, UTF-8 encoded.

Returns an empty string on error.

◆ ToJSVal()

template<typename T >

void Script::ToJSVal	(	const ScriptRequest &	rq,
		JS::MutableHandleValue	ret,
		T const &	val
	)

Convert a C++ type to a JS::Value.

(This might trigger GC. The return value must be rooted if you don't want it to be collected.) NOTE: We are passing the JS::Value by reference instead of returning it by value. The reason is a memory corruption problem that appears to be caused by a bug in Visual Studio. Details here: http://www.wildfiregames.com/forum/index.php?showtopic=17289&p=285921

◆ ToJSVal< JS::HandleValue >()

template<>

void Script::ToJSVal< JS::HandleValue >	(	const ScriptRequest &	rq,
		JS::MutableHandleValue	handle,
		const JS::HandleValue &	a
	)

inline

◆ ToJSVal< JS::Heap< JS::Value > >()

template<>

void Script::ToJSVal< JS::Heap< JS::Value > >	(	const ScriptRequest &	rq,
		JS::MutableHandleValue	handle,
		const JS::Heap< JS::Value > &	a
	)

inline

◆ ToJSVal< JS::PersistentRootedValue >()

template<>

void Script::ToJSVal< JS::PersistentRootedValue >	(	const ScriptRequest &	rq,
		JS::MutableHandleValue	handle,
		const JS::PersistentRootedValue &	a
	)

inline

◆ ToJSVal< JS::RootedValue >()

template<>

void Script::ToJSVal< JS::RootedValue >	(	const ScriptRequest &	rq,
		JS::MutableHandleValue	handle,
		const JS::RootedValue &	a
	)

inline

◆ ToJSVal_vector()

template<typename T >

void Script::ToJSVal_vector	(	const ScriptRequest &	rq,
		JS::MutableHandleValue	ret,
		const std::vector< T > &	val
	)

inline

◆ ToString()

std::string Script::ToString	(	const ScriptRequest &	rq,
		JS::MutableHandleValue	obj,
		bool	pretty = `false`
	)

Convert an object to a UTF-8 encoded string, either with JSON (if pretty == true and there is no JSON error) or with toSource().

◆ WriteStructuredClone()

Script::StructuredClone Script::WriteStructuredClone	(	const ScriptRequest &	rq,
		JS::HandleValue	v
	)

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ StructuredClone

Function Documentation

◆ CloneValueFromOtherCompartment()

◆ CreateArray()

◆ CreateObject() [1/3]

◆ CreateObject() [2/3]

◆ CreateObject() [3/3]

◆ DeepCopy()

◆ EnumeratePropertyNames()

◆ FreezeObject()

◆ FromJSProperty()

◆ FromJSVal()

◆ FromJSVal_vector()

◆ GetObjectClassName() [1/2]

◆ GetObjectClassName() [2/2]

◆ GetProperty() [1/3]

◆ GetProperty() [2/3]

◆ GetProperty() [3/3]

◆ GetPropertyInt() [1/2]

◆ GetPropertyInt() [2/2]

◆ HasProperty()

◆ ParseJSON()

◆ ReadJSONFile()

◆ ReadStructuredClone()

◆ SetProperty() [1/2]

◆ SetProperty() [2/2]

◆ SetPropertyInt()

◆ StringifyJSON()

◆ ToJSVal()

◆ ToJSVal< JS::HandleValue >()

◆ ToJSVal< JS::Heap< JS::Value > >()

◆ ToJSVal< JS::PersistentRootedValue >()

◆ ToJSVal< JS::RootedValue >()

◆ ToJSVal_vector()

◆ ToString()

◆ WriteStructuredClone()