Struct boa_engine::Context

pub struct Context { /* private fields */ }

Javascript context. It is the primary way to interact with the runtime.

Contexts constructed in a thread share the same runtime, therefore it is possible to share objects from one context to another context, but they have to be in the same thread.

Examples

Execute Function of Script File

use boa_engine::{
    Context,
    object::ObjectInitializer,
    property::{Attribute, PropertyDescriptor}
};

let script = r#"
function test(arg1) {
    if(arg1 != null) {
        return arg1.x;
    }
    return 112233;
}
"#;

let mut context = Context::default();

// Populate the script definition to the context.
context.eval(script).unwrap();

// Create an object that can be used in eval calls.
let arg = ObjectInitializer::new(&mut context)
    .property("x", 12, Attribute::READONLY)
    .build();
context.register_global_property(
    "arg",
    arg,
    Attribute::all()
);

let value = context.eval("test(arg)").unwrap();

assert_eq!(value.as_number(), Some(12.0))

Implementations

impl Context

pub fn new(interner: Interner) -> Self

Create a new Context.

pub fn interner(&self) -> &Interner

Gets the string interner.

pub fn interner_mut(&mut self) -> &mut Interner

Gets a mutable reference to the string interner.

pub fn strict(&self) -> bool

Returns if strict mode is currently active.

pub fn set_strict_mode(&mut self, strict: bool)

Set the global strict mode of the context.

pub fn construct_object(&self) -> JsObject

Constructs an object with the %Object.prototype% prototype.

pub fn parse<S>(&mut self, src: S) -> Result<StatementList, ParseError> where
    S: AsRef<[u8]>, 

pub fn global_object(&self) -> &JsObject

Return the global object.

pub fn construct_error<M>(&mut self, message: M) -> JsValue where
    M: Into<Box<str>>, 

Constructs a Error with the specified message.

pub fn throw_error<M, R>(&mut self, message: M) -> JsResult<R> where
    M: Into<Box<str>>, 

Throws a Error with the specified message.

pub fn construct_range_error<M>(&mut self, message: M) -> JsValue where
    M: Into<Box<str>>, 

Constructs a RangeError with the specified message.

pub fn throw_range_error<M, R>(&mut self, message: M) -> JsResult<R> where
    M: Into<Box<str>>, 

Throws a RangeError with the specified message.

pub fn construct_type_error<M>(&mut self, message: M) -> JsValue where
    M: Into<Box<str>>, 

Constructs a TypeError with the specified message.

pub fn throw_type_error<M, R>(&mut self, message: M) -> JsResult<R> where
    M: Into<Box<str>>, 

Throws a TypeError with the specified message.

pub fn construct_reference_error<M>(&mut self, message: M) -> JsValue where
    M: Into<Box<str>>, 

Constructs a ReferenceError with the specified message.

pub fn throw_reference_error<M, R>(&mut self, message: M) -> JsResult<R> where
    M: Into<Box<str>>, 

Throws a ReferenceError with the specified message.

pub fn construct_syntax_error<M>(&mut self, message: M) -> JsValue where
    M: Into<Box<str>>, 

Constructs a SyntaxError with the specified message.

pub fn throw_syntax_error<M, R>(&mut self, message: M) -> JsResult<R> where
    M: Into<Box<str>>, 

Throws a SyntaxError with the specified message.

pub fn construct_eval_error<M>(&mut self, message: M) -> JsValue where
    M: Into<Box<str>>, 

Constructs a EvalError with the specified message.

pub fn construct_uri_error<M>(&mut self, message: M) -> JsValue where
    M: Into<Box<str>>, 

Constructs a URIError with the specified message.

pub fn throw_eval_error<M, R>(&mut self, message: M) -> JsResult<R> where
    M: Into<Box<str>>, 

Throws a EvalError with the specified message.

pub fn throw_uri_error<M>(&mut self, message: M) -> JsResult<JsValue> where
    M: Into<Box<str>>, 

Throws a URIError with the specified message.

pub fn register_global_function(
    &mut self,
    name: &str,
    length: usize,
    body: NativeFunctionSignature
)

Register a global native function.

This is more efficient that creating a closure function, since this does not allocate, it is just a function pointer.

The function will be both constructable (call with new).

The function will be bound to the global object with writable, non-enumerable and configurable attributes. The same as when you create a function in JavaScript.

Note

If you want to make a function only constructable, or wish to bind it differently to the global object, you can create the function object with FunctionBuilder. And bind it to the global object with Context::register_global_property method.

pub fn register_global_builtin_function(
    &mut self,
    name: &str,
    length: usize,
    body: NativeFunctionSignature
)

Register a global native function that is not a constructor.

This is more efficient that creating a closure function, since this does not allocate, it is just a function pointer.

The function will be bound to the global object with writable, non-enumerable and configurable attributes. The same as when you create a function in JavaScript.

Note

The difference to Context::register_global_function is, that the function will not be constructable. Usage of the function as a constructor will produce a TypeError.

pub fn register_global_closure<F>(
    &mut self,
    name: &str,
    length: usize,
    body: F
) -> JsResult<()> where
    F: Fn(&JsValue, &[JsValue], &mut Self) -> JsResult<JsValue> + Copy + 'static, 

Register a global closure function.

The function will be both constructable (call with new).

The function will be bound to the global object with writable, non-enumerable and configurable attributes. The same as when you create a function in JavaScript.

Note #1

If you want to make a function only constructable, or wish to bind it differently to the global object, you can create the function object with FunctionBuilder. And bind it to the global object with Context::register_global_property method.

Note #2

This function will only accept Copy closures, meaning you cannot move Clone types, just Copy types. If you need to move Clone types as captures, see FunctionBuilder::closure_with_captures.

See https://github.com/boa-dev/boa/issues/1515 for an explanation on why we need to restrict the set of accepted closures.

pub fn register_global_class<T>(&mut self) -> JsResult<()> where
    T: Class, 

Register a global class of type T, where T implements Class.

Example

#[derive(Debug, Trace, Finalize)]
struct MyClass;

impl Class for MyClass {
   // ...
}

context.register_global_class::<MyClass>();

pub fn register_global_property<K, V>(
    &mut self,
    key: K,
    value: V,
    attribute: Attribute
) where
    K: Into<PropertyKey>,
    V: Into<JsValue>, 

Register a global property.

Example

use boa_engine::{
    Context,
    property::{Attribute, PropertyDescriptor},
    object::ObjectInitializer
};

let mut context = Context::default();

context.register_global_property(
    "myPrimitiveProperty",
    10,
    Attribute::all()
);

let object = ObjectInitializer::new(&mut context)
   .property(
        "x",
        0,
        Attribute::all()
    )
    .property(
        "y",
        1,
        Attribute::all()
    )
   .build();
context.register_global_property(
    "myObjectProperty",
    object,
    Attribute::all()
);

pub fn eval<S>(&mut self, src: S) -> JsResult<JsValue> where
    S: AsRef<[u8]>, 

Evaluates the given code by compiling down to bytecode, then interpreting the bytecode into a value

Examples

let mut context = Context::default();

let value = context.eval("1 + 3").unwrap();

assert!(value.is_number());
assert_eq!(value.as_number().unwrap(), 4.0);

pub fn compile(
    &mut self,
    statement_list: &StatementList
) -> JsResult<Gc<CodeBlock>>

Compile the AST into a CodeBlock ready to be executed by the VM.

pub fn execute(&mut self, code_block: Gc<CodeBlock>) -> JsResult<JsValue>

Call the VM with a CodeBlock and return the result.

Since this function receives a Gc<CodeBlock>, cloning the code is very cheap, since it’s just a pointer copy. Therefore, if you’d like to execute the same CodeBlock multiple times, there is no need to re-compile it, and you can just call clone() on the Gc<CodeBlock> returned by the Self::compile() function.

pub fn intrinsics(&self) -> &Intrinsics

Return the intrinsic constructors and objects.

pub fn set_trace(&mut self, trace: bool)

Set the value of trace on the context

Trait Implementations

impl Debug for Context

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Context

fn default() -> Self

Returns the “default value” for a type.