Expand description
Boa’sboa_engine crate implements ECMAScript’s standard library of builtin objectsand an ECMAScript context, bytecompiler, and virtual machine for code execution.
§Example usage
You can find multiple examples of the usage of Boa in theboa_examples crate. Inorder to use Boa in your project, you will need to add theboa_engine crate to yourCargo.toml file. You will need to use aSource structure to handle the JavaScript codeto execute, and aContext structure to execute the code:
useboa_engine::{Context, Source};letjs_code =r#" let two = 1 + 1; let definitely_not_four = two + "2"; definitely_not_four"#;// Instantiate the execution contextletmutcontext = Context::default();// Parse the source codematchcontext.eval(Source::from_bytes(js_code)) {Ok(res) => {println!("{}", res.to_string(&mutcontext).unwrap().to_std_string_escaped() ); }Err(e) => {// Pretty print the erroreprintln!("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’sECMA-402 Internationalization API (Intlobject)
§About Boa
Boa is an open-source, experimental ECMAScript Engine written in Rust forlexing, parsing and executing ECMAScript/JavaScript. Currently, Boa supports someof thelanguage. More information can be viewed atBoa’swebsite.
Try out the most recent release with Boa’s live demoplayground.
§Boa Crates
boa_cli- Boa’s CLI && REPL implementationboa_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’sWebAPIfeatures.boa_string- Boa’s ECMAScript string implementation.tag_ptr- Utility library that enables a pointer to be associated with a tag of typeusize.small_btree- Utility library that adds theSmallBTreeMapdata 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 useboa_ast as ast;pub useboa_gc as gc;pub useboa_interner as interner;pub useboa_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 Boaand Rust.
- job
- Boa’s API to create and customize
ECMAScriptjobs 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_stringmacro and thejs_strmacro. - symbol
- Boa’s implementation of ECMAScript’s global
Symbolobject. - 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. Allarguments are required. - embed_
module - Create a module loader that embeds files from the filesystem at buildtime. This is useful for bundling assets with the binary.
- js_
error - Create an error object from a value or string literal. Optionally thefirst argument of the macro can be a type of error (such as
TypeError,RangeErrororInternalError). - js_
object - The
js_value!macro creates aJsValueinstance 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
JsObjectobject from a simpler DSL that resembles JSON.
Structs§
- Host
Defined - This represents a
ECMASCriptspecification [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.
- Spanned
Source Text - Contains pointer to source code and span of the object.
Traits§
- Finalize
- Substitute for the
Droptrait 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.
- TryInto
JsResult - Create a
JsResultfrom a Rust value. This trait is used toconvert Rust types to JS types, includingJsResultofRust values andJsValues.
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_classproc macro attribute that applies to animpl XYZblock andadd a[boa_engine::JsClass]implementation for it.- boa_
module boa_moduleproc macro attribute for declaring aboa_engine::Modulebasedon a Rust module. The original Rust module will also be exposed as is.