Crate boa_engine 

Boa’s boa_engine crate implements ECMAScript’s standard library of builtin objects and an ECMAScript context, bytecompiler, and virtual machine for code execution.

Example usage

You can find multiple examples of the usage of Boa in the boa_examples crate. In order to use Boa in your project, you will need to add the boa_engine crate to your Cargo.toml file. You will need to use a Source structure to handle the JavaScript code to execute, and a Context structure to execute the code:

use boa_engine::{Context, Source};

let js_code = r#"
    let two = 1 + 1;
    let definitely_not_four = two + "2";

    definitely_not_four
"#;

// Instantiate the execution context
let mut context = Context::default();

// Parse the source code
match context.eval(Source::from_bytes(js_code)) {
    Ok(res) => {
        println!(
            "{}",
            res.to_string(&mut context).unwrap().to_std_string_escaped()
        );
    }
    Err(e) => {
        // Pretty print the error
        eprintln!("Uncaught {e}");
    }
};

Crate Features

• serde - Enables serialization and deserialization of the AST (Abstract Syntax Tree).
• profiler - Enables profiling with measureme (this is mostly internal).
• intl - Enables boa’s ECMA-402 Internationalization API (Intl object)

About Boa

Boa is an open-source, experimental ECMAScript Engine written in Rust for lexing, parsing and executing ECMAScript/JavaScript. Currently, Boa supports some of the language. More information can be viewed at Boa’s website.

Try out the most recent release with Boa’s live demo playground.

Boa Crates

• boa_cli - Boa’s CLI && REPL implementation
• boa_ast - Boa’s ECMAScript Abstract Syntax Tree.
• boa_engine - Boa’s implementation of ECMAScript builtin objects and execution.
• boa_gc - Boa’s garbage collector.
• boa_icu_provider - Boa’s ICU4X data provider.
• boa_interner - Boa’s string interner.
• boa_macros - Boa’s macros.
• boa_parser - Boa’s lexer and parser.
• boa_runtime - Boa’s WebAPI features.
• boa_string - Boa’s ECMAScript string implementation.
• tag_ptr - Utility library that enables a pointer to be associated with a tag of type usize.
• small_btree - Utility library that adds the SmallBTreeMap data structure.

Re-exports

pub use crate::bigint::JsBigInt;

pub use crate::context::Context;

pub use crate::error::JsError;

pub use crate::error::JsNativeError;

pub use crate::error::JsNativeErrorKind;

pub use crate::interop::IntoJsFunctionCopied;

pub use crate::interop::UnsafeIntoJsFunction;

pub use crate::module::IntoJsModule;

pub use crate::module::Module;

pub use crate::native_function::NativeFunction;

pub use crate::object::JsData;

pub use crate::object::JsObject;

pub use crate::object::NativeObject;

pub use crate::script::Script;

pub use crate::symbol::JsSymbol;

pub use crate::value::JsValue;

pub use crate::value::JsVariant;

pub use boa_ast as ast;

pub use boa_gc as gc;

pub use boa_interner as interner;

pub use boa_parser as parser;

Modules

bigint

Boa’s implementation of ECMAScript’s bigint primitive type.

builtins

Boa’s ECMAScript built-in object implementations, e.g. Object, String, Math, Array, etc.

bytecompiler

This module contains the bytecode compiler.

class

Traits and structs for implementing native classes.

context

The ECMAScript context.

environments

Boa’s implementation of ECMAScript’s Environment Records.

error

Error-related types and conversions.

interop

Interop module containing traits and types to ease integration between Boa and Rust.

job

Boa’s API to create and customize ECMAScript jobs and job queues.

module

Boa’s implementation of the ECMAScript’s module system.

native_function

Boa’s wrappers for native Rust functions to be compatible with ECMAScript calls.

object

Boa’s representation of a JavaScript object and builtin object wrappers

optimizer

Implements optimizations.

prelude

A convenience module that re-exports the most commonly-used Boa APIs

property

Boa’s implementation of ECMAScript’s Property Descriptor.

realm

Boa’s implementation of ECMAScript’s Realm Records

script

Boa’s implementation of ECMAScript’s Scripts.

string

This module contains the js_string macro and the js_str macro.

symbol

Boa’s implementation of ECMAScript’s global Symbol object.

value

Boa’s ECMAScript Value implementation.

vm

Boa’s ECMAScript Virtual Machine

Macros

__embed_module_inner

Implementation of the inner iterator of the embed_module! macro. All arguments are required.

embed_module

Create a module loader that embeds files from the filesystem at build time. This is useful for bundling assets with the binary.

js_error

Create an error object from a value or string literal. Optionally the first argument of the macro can be a type of error (such as TypeError, RangeError or InternalError).

js_object

The js_value! macro creates a JsValue instance based on a JSON-like DSL.

js_str

Convert a utf8 string literal to a JsString

js_string

Utility macro to create a JsString.

js_value

Create a JsObject object from a simpler DSL that resembles JSON.

Structs

HostDefined

This represents a ECMASCript specification [HostDefined] field.

JsStr

This is equivalent to Rust’s &str.

JsString

A Latin1 or UTF-16–encoded, reference counted, immutable string.

Source

A source of ECMAScript code.

SpannedSourceText

Contains pointer to source code and span of the object.

Traits

Finalize

Substitute for the Drop trait for garbage collected types.

JsArgs

A utility trait to make working with function arguments easier.

Trace

The Trace trait, which needs to be implemented on garbage-collected objects.

TryIntoJsResult

Create a JsResult from a Rust value. This trait is used to convert Rust types to JS types, including JsResult of Rust values and JsValues.

Type Aliases

JsResult

The result of a Javascript expression is represented like this so it can succeed (Ok) or fail (Err)

Attribute Macros

boa_class

boa_class proc macro attribute that applies to an impl XYZ block and add a [boa_engine::JsClass] implementation for it.

boa_module

boa_module proc macro attribute for declaring a boa_engine::Module based on a Rust module. The original Rust module will also be exposed as is.

Derive Macros

Finalize

Derive the Finalize trait.

JsData

Derive the JsData trait.

Trace

Derive the Trace trait.