From 9804c77e4d96d835dc7f483b07b578faae8712ce Mon Sep 17 00:00:00 2001 From: Kevin <46825870+nekevss@users.noreply.github.com> Date: Wed, 7 Feb 2024 02:06:13 -0500 Subject: [PATCH] Docs: Update README.md and add `boa_cli`'s README.md (#3659) * Build out boa_cli readme * Review feedback --- README.md | 64 +++++++++++++++++++++----------------------- cli/README.md | 71 +++++++++++++++++++++++++++++++++++++++++++++++++ cli/src/main.rs | 2 +- 3 files changed, 103 insertions(+), 34 deletions(-) create mode 100644 cli/README.md diff --git a/README.md b/README.md index 29ea4e38b7..06a9b4f927 100644 --- a/README.md +++ b/README.md @@ -32,15 +32,16 @@ Prefer a CLI? Feel free to try out `boa_cli`! Boa currently publishes and actively maintains the following crates: -- **`boa_ast`** - Boa's ECMAScript Abstract Syntax Tree. +- **`boa_ast`** - Boa's ECMAScript Abstract Syntax Tree +- **`boa_cli`** - Boa's CLI && REPL implementation - **`boa_engine`** - Boa's implementation of ECMAScript builtin objects and - execution. -- **`boa_gc`** - Boa's garbage collector. -- **`boa_interner`** - Boa's string interner. -- **`boa_parser`** - Boa's lexer and parser. -- **`boa_profiler`** - Boa's code profiler. -- **`boa_icu_provider`** - Boa's ICU4X data provider. -- **`boa_runtime`** - Boa's WebAPI features. + execution +- **`boa_gc`** - Boa's garbage collector +- **`boa_interner`** - Boa's string interner +- **`boa_parser`** - Boa's lexer and parser +- **`boa_profiler`** - Boa's code profiler +- **`boa_icu_provider`** - Boa's ICU4X data provider +- **`boa_runtime`** - Boa's WebAPI features Please note: the `Boa` and `boa_unicode` crate are deprecated. @@ -58,31 +59,27 @@ boa_engine = "0.17.3" Then in `main.rs`, copy the below: ```rust -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}"); - } -}; +use boa_engine::{Context, Source, JsResult}; + +fn main() -> JsResult<()> { + 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 + let result = context.eval(Source::from_bytes(js_code))?; + + println!("{}", result.display()); + + Ok(()) +} + ``` Now, all that's left to do is `cargo run`. @@ -94,6 +91,7 @@ Congrats! You've executed your first `JavaScript` using `Boa`! For more information on `Boa`'s API. Feel free to check out our documentation. [**Release Documentation**](https://docs.rs/boa_engine/latest/boa_engine/) + [**Dev `main` Documentation**](https://boajs.dev/boa/doc/boa_engine/index.html) ## Conformance diff --git a/cli/README.md b/cli/README.md new file mode 100644 index 0000000000..ac8ea12996 --- /dev/null +++ b/cli/README.md @@ -0,0 +1,71 @@ +# Boa CLI + +Boa CLI is `Boa`'s REPL implementation to execute `JavaScript` directly from +your CLI. + +## Installation + +`boa_cli` can be installed directly via `Cargo`. + +```shell + cargo install boa_cli +``` + + + +## Usage + + + + +Once installed, your good to go! + +To execute some JavaScript source code, navigate to the directy of your choosing and type: + +```shell + boa test.js +``` + +Or if you'd like to use Boa's REPL, simply type: + +```shell + boa +``` + +## CLI Options + +```txt +Usage: boa [OPTIONS] [FILE]... + +Arguments: + [FILE]... The JavaScript file(s) to be evaluated + +Options: + --strict Run in strict mode + -a, --dump-ast [] Dump the AST to stdout with the given format [possible values: debug, json, json-pretty] + -t, --trace Dump the AST to stdout with the given format + --vi Use vi mode in the REPL + -O, --optimize + --optimizer-statistics + --flowgraph [] Generate instruction flowgraph. Default is Graphviz [possible values: graphviz, mermaid] + --flowgraph-direction Specifies the direction of the flowgraph. Default is top-top-bottom [possible values: top-to-bottom, bottom-to-top, left-to-right, right-to-left] + --debug-object Inject debugging object `$boa` + -m, --module Treats the input files as modules + -r, --root Root path from where the module resolver will try to load the modules [default: .] + -h, --help Print help (see more with '--help') + -V, --version Print version +``` + +## Features + +Boa's CLI currently has a variety of features (as listed in `Options`). + +Features include: + +- Implemented runtime features (please note that only `Console` is currently implemented) +- AST Visibility: View the compiled Boa AST (--dump-ast) +- Tracing: Enabling a vm tracing when executing any JavaScript +- Flowgraphs: View a generated (with various provided options) +- Debugging: Boa's CLI comes with an implemented `$boa` debug object with various functionality (see documentation). + +Have an idea for a feature? Feel free to submit an issue and/or contribute! diff --git a/cli/src/main.rs b/cli/src/main.rs index 3c6a796fc0..9f246992c6 100644 --- a/cli/src/main.rs +++ b/cli/src/main.rs @@ -1,4 +1,4 @@ -//! A ECMAScript REPL implementation based on boa_engine. +//! A CLI implementation for `boa_engine` that comes complete with file execution and a REPL. #![doc = include_str!("../ABOUT.md")] #![doc( html_logo_url = "https://raw.githubusercontent.com/boa-dev/boa/main/assets/logo.svg",