API Documentation

Classes and types

enum class Jerryscript::FatalCode

Values:

enumerator XX

enum class Jerryscript::Type

Values:

enumerator XX

enum class Jerryscript::ErrorType

Values:

enumerator XX

enum class Jerryscript::ObjectType

Values:

enumerator XX

enum class Jerryscript::FunctionType

Values:

enumerator XX

enum class Jerryscript::Feature

Values:

enumerator XX

enum class Jerryscript::Ecma

Values:

enumerator XX

using Jerryscript::HeapStats = jerry_heap_stats_t

inline bool Jerryscript::getHeapStats(HeapStats &stats)

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 calling Value::reset().

inline bool Jerryscript::isFeatureEnabled(Feature feature)

Check if optional feature is available.

Parameters:: feature –
Return values:: bool – true if library has been compiled with requested feature

Value Jerryscript::eval(const String &jsCode)

inline void Jerryscript::gc(bool maximumEffort = false): Perform memory garbage collection.

class 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 >

Public Functions

Context(): Create a context using the default JERRY_GLOBAL_HEAP_SIZE setting.

Context(size_t heapSize)

Create a context with custom heap size.

Parameters:: heapSize – Size of heap in bytes. Will be rounded up as necessary.

inline void select()

Make this the current context.

Context must be selected before calling into jerryscript.

template<class ClassType> class ContextTemplate : public LinkedObjectTemplate<ClassType>, public Jerryscript::Context 

#include <Context.h>

Implement a custom Context class.

Public Functions

Context(): Create a context using the default JERRY_GLOBAL_HEAP_SIZE setting.

Context(size_t heapSize)

Create a context with custom heap size.

Parameters:: heapSize – Size of heap in bytes. Will be rounded up as necessary.

template<class ClassType> class 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.

class Except: #include <Except.h>

struct CallInfo

#include <Function.h>

Maps directly onto jerry_call_info_t structure.

Public Members

Value function: invoked function object

Value this_value: this value passed to the function

Value new_target: current new target value, undefined for non-constructor calls

class 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.

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 CopyValue

#include <Types.h>

Use to initialise Value object by copying native/raw jerryscript value.

e.g. Value myValue = CopyValue{raw_value};

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};

struct Undefined

#include <Types.h>

Use to create Value containing javascript ‘undefined’.

e.g. Value myValue = Undefined{};

struct Null

#include <Types.h>

Use to create Value containing javascript ‘null’.

e.g. Value myValue = Null{};

class Value

#include <Types.h>

Represents a Jerryscript value.

This class resembles std::unique_ptr to manage a raw/native jerry_value_t value. The get(), reset() and release() 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 or CopyValue 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 String &s): Wiring String.

inline Value(const char *s): NUL-terminated ‘C’ string.

inline Value(const FSTR::String &s): Flash String.

Get raw/native value for use with jerryscript C API

inline const jerry_value_t &get() const: const get()

inline jerry_value_t &get(): get()

Checks on value type

inline bool isCallable() const: Is this object a function? If so, can cast to Callable type.

inline bool isArray() const: Can this object be accessed as an array? If so, can cast to Array type.

inline bool isError() const: Determine if value represents an error. If so, can cast to Error 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 isString() const: Is this a String?

inline bool isObject() const: Is this an Object type? If so, can cast to Object class.

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(const Value &value): Copy constructor.

inline Value(Value &&value): Move constructor.

inline Value &operator=(const Value &value): Assignment copy operator.

inline Value &operator=(Value &&value): Assignment move operator.

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.

inline Type type() const: Get value type.

Object toObject() const: Create a new object from this value.

inline Value toString() const: Create a new string value from this value.

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

Return values:

size_t – Number of characters read

String subString(unsigned offset, size_t length) const

Get content from within a string value.

Parameters:

offset – First character position to read, starting from 0
length – Number of characters to read

Return values:

String – Requested range, or nullptr if value is not a string

operator String() const: Support intrinsic cast to Wiring String.

template<typename T> inline T as() const

Get value of object with specific type. e.g. value.as<int>().

Return value will revert to sensible default if conversion cannot be completed. If in doubt, check type first.

struct As: #include <Types.h>

Used by as() method.

class ExternalFunction : public Jerryscript::Value : #include <Types.h>

Object representing an external function implementation.

class 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 const Value operator[](const String &name) const: const operator[] returns Value directly

inline Value setProperty(const Value &name, const Value &value)

Set a property value.

Parameters:

name – Property name
value – Value to set

Return values:

Value – true on success, otherwise Error

inline Value getProperty(const Value &name) const

Get a property value.

Parameters:: name – Property name
Return values:: Value – The property value, or Error

inline bool hasProperty(const Value &name) const

Determine if a property exists.

Parameters:: name – Property name
Return values:: bool – true if property exists

inline bool removeProperty(const Value &name)

Remove a property.

Parameters:: name – Property name
Return values:: bool – true on success

Public Functions

inline Object(): Default constructor creates a new, empty object.

Array keys() const: Get list of property names.

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

Return values:

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)
Return values:: 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.

Return values:: 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.

inline Value(const Value &value): Copy constructor.

inline Value(Value &&value): Move constructor.

Value(int value): Integer.

Value(unsigned value): Unsigned integer.

inline Value(double value): floating-point

inline Value(bool value): Boolean.

inline Value(const String &s): Wiring String.

inline Value(const char *s): NUL-terminated ‘C’ string.

inline Value(const FSTR::String &s): Flash String.

struct NamedItem: #include <Types.h>

Iterator and operator[] access uses this wrapper class so items may be written or read.

class Error : public Jerryscript::Value 

#include <Types.h>

Error object class.

Subclassed by Jerryscript::ArgumentError

Create an error object

inline Error(ErrorType type): Error with type only.

inline Error(ErrorType type, const String &message): Error with type and message.

Public Functions

inline Error(const Value &value): Copy constructor.

inline Error(Value &&value): Move constructor.

inline ErrorType errorType() const: Get type of error.

Value message() const: Get error message, if any.

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.

inline Value(const Value &value): Copy constructor.

inline Value(Value &&value): Move constructor.

Value(int value): Integer.

Value(unsigned value): Unsigned integer.

inline Value(double value): floating-point

inline Value(bool value): Boolean.

inline Value(const String &s): Wiring String.

inline Value(const char *s): NUL-terminated ‘C’ string.

inline Value(const FSTR::String &s): Flash String.

class ArgumentError : public Jerryscript::Error : #include <Types.h>

Provides consistent error message when checking external function arguments.

class Array : public Jerryscript::Object 

#include <Types.h>

Array objects have properties accessed by index.

Iterator support

inline Iterator begin(): begin

inline Iterator end(): end

Array element/property access by index

inline IndexedItem operator[](unsigned index): operator[] uses IndexedItem proxy object so value can be assigned or read

inline const Value operator[](unsigned index) const: const operator[] returns value directly

inline Value getProperty(unsigned index) const

Get a property value.

Parameters:: index – Index of property
Return values:: Value – The property value, or Error

inline Value setProperty(unsigned index, const Value &value)

Set a property value.

Parameters:

index – Index of property
value – Value to set

Return values:

Value – true on success, otherwise Error

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: #include <Types.h>

class Callable : public Jerryscript::Object 

#include <Types.h>

Callable object represent functions.

Public Functions

Value call(const Object &thisValue, const Value &arg): Call with one argument.

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.

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