API Documentation
Classes and types
-
using Jerryscript::HeapStats = jerry_heap_stats_t
-
size_t Jerryscript::getHeapUsed()
-
bool Jerryscript::printHeap()
-
jerry_value_t Jerryscript::create_arg_count_error(const char *functionName)
-
inline Object Jerryscript::global()
Get global context.
-
void Jerryscript::initialise(jerry_init_flag_t flags = JERRY_INIT_EMPTY)
Initializes the JavaScript VM.
-
void Jerryscript::cleanup()
Clean up the virtual machine by unloading snapshots, freeing allocated memory, etc.
Note that this does not release Jerryscript heap memory allocated to existing values. This is done via
Value
destructor or by manually callingValue::reset()
.
-
inline bool Jerryscript::isFeatureEnabled(Feature feature)
Check if optional feature is available.
- Parameters
feature –
- Returns
bool – true if library has been compiled with requested feature
-
inline void Jerryscript::gc(bool maximumEffort = false)
Perform memory garbage collection.
-
class ArgumentError : public Jerryscript::Error
- #include <Types.h>
Provides consistent error message when checking external function arguments.
-
class Jerryscript::Jerryscript::Array : public Jerryscript::Object
- #include <Types.h>
Array objects have properties accessed by index.
Array element/property access by index
-
inline IndexedItem operator[](unsigned index)
operator[] uses
IndexedItem
proxy object so value can be assigned or read
Public Functions
-
inline Array(size_t size)
Create a new, fixed-size array with the given number of elements.
-
inline size_t count() const
Get number of elements in the array.
-
inline Object()
Default constructor creates a new, empty object.
-
struct IndexedItem
- #include <Types.h>
Iterator and operator[] access uses this wrapper class so items may be written or read.
-
class Iterator : public std::iterator<std::random_access_iterator_tag, IndexedItem>
- #include <Types.h>
-
inline IndexedItem operator[](unsigned index)
-
class Jerryscript::Jerryscript::Callable : public Jerryscript::Object
- #include <Types.h>
Callable object represent functions.
Public Functions
-
Value call(const Object &thisValue, std::initializer_list<Value> args = {})
Call with zero or multiple arguments.
e.g.
call(myObject, {1, 2, 3});
-
inline FunctionType functionType() const
Get specific type of callable object.
-
inline Object()
Default constructor creates a new, empty object.
-
Value call(const Object &thisValue, std::initializer_list<Value> args = {})
-
struct Jerryscript::Jerryscript::CallInfo
- #include <Function.h>
Maps directly onto jerry_call_info_t structure.
-
class Jerryscript::Jerryscript::Context
- #include <Context.h>
Jerryscript external context.
Applications may be segregated by running in separate contexts. Each context has its own dynamically allocated heap.
Subclassed by Jerryscript::ContextTemplate< ClassType >
-
template<class ClassType>
class Jerryscript::Jerryscript::ContextList : public OwnedLinkedObjectListTemplate<ClassType> - #include <Context.h>
Manages a list of contexts.
Public Functions
-
inline void foreach(Callback callback)
Invoke callback once for each context via task queue.
When calling into contexts we can do this:
JS::ContextList<MyContext> contexts; ... String str = F("Some text"); int value = 12; for(auto& ctx: contexts) { ctx.customNotify(str, value); }
However, with many containers system responsiveness may be adversely affected. Instead, separate the calls out like this:
contexts.foreach([=](auto& ctx){ ctx.customNotify(str, value); });
Note that all parameters are captured by copy (using
[=]
) as, for example,str
will be destroyed when it goes out of scope.
-
inline void foreach(Callback callback)
-
template<class ClassType>
class Jerryscript::Jerryscript::ContextTemplate : public LinkedObjectTemplate<ClassType>, public Jerryscript::Context - #include <Context.h>
Implement a custom Context class.
-
struct CopyValue
- #include <Types.h>
Use to initialise Value object by copying native/raw jerryscript value.
-
class Jerryscript::Jerryscript::Error : public Jerryscript::Value
- #include <Types.h>
Error object class.
Subclassed by Jerryscript::ArgumentError
Create an error object
Public Functions
-
operator String() const
Formulate error message Base operator in Value class returns empty value for errors. To obtain error message, check for
isError()
then cast to Error():if (value.isError()) { Serial.println(JS::Error(value)); }
-
inline Value()
Construct An empty (unused) value.
-
inline Value(const OwnedValue &value)
Construct a Value and take ownership of the given native value.
-
inline Value(const CopyValue &value)
Construct a Value using a copy (or reference to) the given native value.
-
inline Value(const StringValue &value)
Construct a string Value from the given native value.
-
Value(int value)
Integer.
-
Value(unsigned value)
Unsigned integer.
-
inline Value(double value)
floating-point
-
inline Value(bool value)
Boolean.
-
inline Value(const char *s)
NUL-terminated ‘C’ string.
-
operator String() const
-
class Except
- #include <Except.h>
-
class ExternalFunction : public Jerryscript::Value
- #include <Types.h>
Object representing an external function implementation.
-
class Jerryscript::Jerryscript::Object : public Jerryscript::Value
- #include <Types.h>
Objects support named properties.
Subclassed by Jerryscript::Array, Jerryscript::Callable
Access object properties by name
-
inline NamedItem operator[](const String &name)
operator[] uses
NamedItem
proxy object so value can be assigned or read
-
inline Value getProperty(const Value &name) const
Get a property value.
- Parameters
name – Property name
- Returns
Value – The property value, or Error
Public Functions
-
inline Object()
Default constructor creates a new, empty object.
-
Value runFunction(const String &name, Value &arg)
Call a specified JavaScript function with exactly one argument.
- Parameters
name – Name of function to run (a property name)
arg – The argument
- Returns
Value – Return value from function, or Error
-
Value runFunction(const String &name, std::initializer_list<Value> args = {})
Call a specified JavaScript function with zero or more arguments.
- Parameters
name – Name of function to run (a property name)
- Returns
Value – Return value from function, or Error
-
inline bool registerFunction(const String &name, jerry_external_handler_t handler)
Register an external function so it may be called from javascript.
- Parameters
name – Name of the function (property name)
handler – The function handler, see Function.h for details
bool – true on success
-
inline bool unregisterFunction(const String &name)
Unregister an external function.
- Parameters
name – Name of the function
bool – true on success
-
Callable getFunction(const String &name)
Retrieve the given property as a function.
- Returns
The – callable object, or error (property not found or isn’t callable)
-
inline Value()
Construct An empty (unused) value.
-
inline Value(const OwnedValue &value)
Construct a Value and take ownership of the given native value.
-
inline Value(const CopyValue &value)
Construct a Value using a copy (or reference to) the given native value.
-
inline Value(const StringValue &value)
Construct a string Value from the given native value.
-
Value(int value)
Integer.
-
Value(unsigned value)
Unsigned integer.
-
inline Value(double value)
floating-point
-
inline Value(bool value)
Boolean.
-
inline Value(const char *s)
NUL-terminated ‘C’ string.
-
struct NamedItem
- #include <Types.h>
Iterator and operator[] access uses this wrapper class so items may be written or read.
-
inline NamedItem operator[](const String &name)
-
struct OwnedValue
- #include <Types.h>
Use to initialise Value object by taking ownership of native/raw jerryscript value.
e.g.
Value myValue = OwnedValue{raw_value};
This typecast is necessary because
jerry_value_t
is weakly typed (as uint32_t).
-
struct StringValue
- #include <Types.h>
Use to initialise Value object to a string given a native/raw jerryscript value.
e.g.
Value myValue = StringValue{raw_value};
-
class Jerryscript::Jerryscript::Task : public Task
- #include <Task.h>
Task that runs the
loop
JavaScript function in the background
Public Functions
-
inline virtual void loop() override
Inherited classes override this to perform actual work.
-
class Jerryscript::Jerryscript::Value
- #include <Types.h>
Represents a Jerryscript value.
This class resembles
std::unique_ptr
to manage a raw/nativejerry_value_t
value. Theget()
,reset()
andrelease()
methods all behave in the same manner.In addition, it provides intrinsic casts from numeric/boolean C++ types plus
String
.You can therefore create a value like this::
Value value = 12; Value str = "My String"; Value str2 = F("My other String");
If you need to working with floating point values be sure to compile with
JERRY_COMPACT_PROFILE=0
.IMPORTANT: When dealing with raw/native values, ALWAYS use either
OwnedValue
orCopyValue
casts.This is correct: Value value = OwnedValue{jerry_create_object()};
This is wrong: Value value = jerry_create_object(); // Ends up with memory leak plus garbage
Subclassed by Jerryscript::Error, Jerryscript::ExternalFunction, Jerryscript::Object
Construct a value from a simple type
-
Value(int value)
Integer.
-
Value(unsigned value)
Unsigned integer.
-
inline Value(double value)
floating-point
-
inline Value(bool value)
Boolean.
-
inline Value(const char *s)
NUL-terminated ‘C’ string.
Get raw/native value for use with jerryscript C API
Checks on value type
-
inline bool isArray() const
Can this object be accessed as an array? If so, can cast to
Array
type.
-
inline bool isEmpty() const
An empty Value contains nothing, i.e. no javascript type has been assigned. This gets interpreted as ‘undefined’ if any attempt is made to use it in javascript.
-
inline bool isDefined() const
Contains a javascript value, but contents undefined.
-
inline bool isBoolean() const
A true/false value type.
-
inline bool isFalse() const
Is this a Boolean type set to False?
-
inline bool isTrue() const
Is this a Boolean type set to True?
-
inline bool isNull() const
Is this a NULL value?
-
inline bool isNumber() const
Does this value contain a Number?
Public Functions
-
inline Value()
Construct An empty (unused) value.
-
inline Value(const OwnedValue &value)
Construct a Value and take ownership of the given native value.
-
inline Value(const CopyValue &value)
Construct a Value using a copy (or reference to) the given native value.
-
inline Value(const StringValue &value)
Construct a string Value from the given native value.
-
inline Value &reset(jerry_value_t value = jerry_value_t(Ecma::VALUE_EMPTY))
Reset contents of object to new value (default is unassigned)
-
inline jerry_value_t release()
Get raw/native value and release ownership.
-
size_t readString(unsigned offset, char *buffer, size_t length) const
Get content from within a string value.
- Parameters
offset – First character position to read, starting from 0
buffer – Where to store character data
length – Number of characters to read
- Returns
size_t – Number of characters read
Macros
- group jerryscript
Macros to implement methods callable from javascript within a Context class
Must be used inside a class constructed using
JS::ContextTemplate
.As with all external functions, must be registered using
JS::Object::registerFunction
to make available to javascript.-
JS_DEFINE_METHOD(method, ...)
Argument list is fixed.
Example:
class MyContext: public JS::ContextTemplate<MyContext> { public: void init() { select(); JS::initialise(); JS::global().registerFunction(F("myMethod"), myMethod); } protected: JS_DEFINE_METHOD(myMethod, 2, JS::Value& arg1, JS::Callable& arg2) { ... return ...; } };
- Parameters
method – Name of jerryscript wrapper function
... – Argument definitions
-
JS_DEFINE_METHOD_VAR(method)
Arguments are passed as array.
Method declaration has the following prototype:
JS::Value js_method(const JS::CallInfo& callInfo, JS::Value args[], unsigned argCount)
Example:
class MyContext: public JS::ContextTemplate<MyContext> { public: void init() { select(); JS::initialise(); JS::global().registerFunction(F("myMethod"), myMethod); } protected: JS_DEFINE_METHOD_VAR(myMethod) { for(unsigned i = 0; i < argCount; ++i) { Serial.print(args[i]); } return Value(); } };
- Parameters
method – Name of jerryscript wrapper function
Macros to implement functions callable from javascript
As with all external functions, must be registered using
JS::Object::registerFunction
to make available to javascript.Function arguments should be validated, returning
JS::Error
object on failure.-
JS_DEFINE_FUNCTION(func, ...)
Argument list is fixed.
Example:
JS_DEFINE_FUNCTION(myFunction, JS::Value& arg1, JS::Array& arg2) { ... return ...; }
- Parameters
func – Name of jerryscript wrapper function
... – Argument definitions
-
JS_DEFINE_FUNCTION_VAR(func)
Arguments are passed as array.
Example:
JS_DEFINE_FUNCTION_VAR(myFunction) { for(unsigned i = 0; i < argCount; ++i) { Serial.print(args[i]); } return Value(); }
- Parameters
func – Name of jerryscript wrapper function
-
JS_DECLARE_FUNCTION(func)
Declare a function wrapper.
Use in a header file or as forward declaration
- Parameters
func – Name of wrapper function
-
JS_DEFINE_METHOD(method, ...)