From 16e8ef454fa3517207bfccbea61857d0199dc0c2 Mon Sep 17 00:00:00 2001 From: Stephen Chung Date: Tue, 21 Jul 2020 23:08:46 +0800 Subject: [PATCH] Refine no-std sample. --- doc/src/about/non-design.md | 4 +- doc/src/engine/raw.md | 2 +- doc/src/start/builds/no-std.md | 6 +++ doc/src/start/examples/rust.md | 16 ++++-- doc/src/start/examples/scripts.md | 52 +++++++++---------- no_std/{no_std_win => no_std_test}/Cargo.toml | 6 +-- no_std/{no_std_win => no_std_test}/README.md | 6 +-- .../{no_std_win => no_std_test}/src/main.rs | 2 +- 8 files changed, 55 insertions(+), 39 deletions(-) rename no_std/{no_std_win => no_std_test}/Cargo.toml (84%) rename no_std/{no_std_win => no_std_test}/README.md (66%) rename no_std/{no_std_win => no_std_test}/src/main.rs (92%) diff --git a/doc/src/about/non-design.md b/doc/src/about/non-design.md index da3747df..52888164 100644 --- a/doc/src/about/non-design.md +++ b/doc/src/about/non-design.md @@ -25,12 +25,12 @@ It doesn't attempt to be a new language. For example: * No closures - do your closure magic in Rust instead; [turn a Rhai scripted function into a Rust closure]({{rootUrl}}/engine/call-fn.md). * No byte-codes/JIT - Rhai has an AST-walking interpreter which will not win any speed races. The purpose of Rhai is not - to be extremely _fast_, but to make it as easy as possible to integrate with native Rust programs. + to be extremely _fast_, but to make it as easy as possible to integrate with native Rust applications. Due to this intended usage, Rhai deliberately keeps the language simple and small by omitting advanced language features such as classes, inheritance, first-class functions, closures, concurrency, byte-codes, JIT etc. -Avoid the temptation to write full-fledge program logic entirely in Rhai - that use case is best fulfilled by +Avoid the temptation to write full-fledge application logic entirely in Rhai - that use case is best fulfilled by more complete languages such as JavaScript or Lua. Therefore, in actual practice, it is usually best to expose a Rust API into Rhai for scripts to call. diff --git a/doc/src/engine/raw.md b/doc/src/engine/raw.md index ed7154ed..ce61aa91 100644 --- a/doc/src/engine/raw.md +++ b/doc/src/engine/raw.md @@ -7,7 +7,7 @@ Raw `Engine` `Engine::new` creates a scripting [`Engine`] with common functionalities (e.g. printing to the console via `print`). In many controlled embedded environments, however, these may not be needed and unnecessarily occupy -program code storage space. +application code storage space. Use `Engine::new_raw` to create a _raw_ `Engine`, in which only a minimal set of basic arithmetic and logical operators are supported. diff --git a/doc/src/start/builds/no-std.md b/doc/src/start/builds/no-std.md index 46a8e986..75395ed6 100644 --- a/doc/src/start/builds/no-std.md +++ b/doc/src/start/builds/no-std.md @@ -13,3 +13,9 @@ Nightly Required ---------------- Currently, [`no_std`] requires the nightly compiler due to the crates that it uses. + + +Samples +------- + +Check out the [`no-std` sample applications](../examples/rust.md#no-std-samples) for different operating environments. diff --git a/doc/src/start/examples/rust.md b/doc/src/start/examples/rust.md index b32d5529..276b3d15 100644 --- a/doc/src/start/examples/rust.md +++ b/doc/src/start/examples/rust.md @@ -35,6 +35,16 @@ cargo run --example {example_name} To illustrate `no-std` builds, a number of sample applications are available under the `no_std` directory: -| Example | Environment | -| ------------------------------------------------------------------------------------- | :---------: | -| [`no_std_win`](https://github.com/jonathandturner/rhai/tree/master/no_std/no_std_win) | Windows API | +| Sample | Description | Optimization | Allocator | Panics | +| --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | :----------: | :-----------------------------------------------: | :----: | +| [`no_std_test`](https://github.com/jonathandturner/rhai/tree/master/no_std/no_std_test) | Bare-bones test application that evaluates a Rhai expression and sets the result as the return value. | Size | [`wee_alloc`](https://crates.io/crates/wee_alloc) | Abort | + +`cargo run` cannot be used to run a `no-std` sample. It must first be built: + +```bash +cd no_std/no_std_test + +cargo +nightly build --release + +./target/release/no_std_test +``` diff --git a/doc/src/start/examples/scripts.md b/doc/src/start/examples/scripts.md index 222b3604..0875f869 100644 --- a/doc/src/start/examples/scripts.md +++ b/doc/src/start/examples/scripts.md @@ -8,25 +8,25 @@ Language Feature Scripts There are also a number of examples scripts that showcase Rhai's features, all in the `scripts` directory: -| Script | Description | -| -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | -| [`array.rhai`](https://github.com/jonathandturner/rhai/tree/master/scripts/array.rhai) | [Arrays] | -| [`assignment.rhai`](https://github.com/jonathandturner/rhai/tree/master/scripts/assignment.rhai) | Variable declarations | -| [`comments.rhai`](https://github.com/jonathandturner/rhai/tree/master/scripts/comments.rhai) | Just comments | -| [`for1.rhai`](https://github.com/jonathandturner/rhai/tree/master/scripts/for1.rhai) | [`for`](#for-loop) loops | -| [`for2.rhai`](https://github.com/jonathandturner/rhai/tree/master/scripts/for2.rhai) | [`for`](#for-loop) loops on [arrays] | -| [`function_decl1.rhai`](https://github.com/jonathandturner/rhai/tree/master/scripts/function_decl1.rhai) | A [function] without parameters | -| [`function_decl2.rhai`](https://github.com/jonathandturner/rhai/tree/master/scripts/function_decl2.rhai) | A [function] with two parameters | -| [`function_decl3.rhai`](https://github.com/jonathandturner/rhai/tree/master/scripts/function_decl3.rhai) | A [function] with many parameters | -| [`if1.rhai`](https://github.com/jonathandturner/rhai/tree/master/scripts/if1.rhai) | [`if`](#if-statement) example | -| [`loop.rhai`](https://github.com/jonathandturner/rhai/tree/master/scripts/loop.rhai) | Count-down [`loop`](#infinite-loop) in Rhai, emulating a `do` .. `while` loop | -| [`oop.rhai`](https://github.com/jonathandturner/rhai/tree/master/scripts/oop.rhai) | Simulate [object-oriented programming (OOP)][OOP] | -| [`op1.rhai`](https://github.com/jonathandturner/rhai/tree/master/scripts/op1.rhai) | Just simple addition | -| [`op2.rhai`](https://github.com/jonathandturner/rhai/tree/master/scripts/op2.rhai) | Simple addition and multiplication | -| [`op3.rhai`](https://github.com/jonathandturner/rhai/tree/master/scripts/op3.rhai) | Change evaluation order with parenthesis | -| [`string.rhai`](https://github.com/jonathandturner/rhai/tree/master/scripts/string.rhai) | [String] operations | -| [`strings_map.rhai`](https://github.com/jonathandturner/rhai/tree/master/scripts/strings_map.rhai) | [String] and [object map] operations | -| [`while.rhai`](https://github.com/jonathandturner/rhai/tree/master/scripts/while.rhai) | [`while`](#while-loop) loop | +| Script | Description | +| -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | +| [`array.rhai`](https://github.com/jonathandturner/rhai/tree/master/scripts/array.rhai) | [Arrays] | +| [`assignment.rhai`](https://github.com/jonathandturner/rhai/tree/master/scripts/assignment.rhai) | Variable declarations | +| [`comments.rhai`](https://github.com/jonathandturner/rhai/tree/master/scripts/comments.rhai) | Just comments | +| [`for1.rhai`](https://github.com/jonathandturner/rhai/tree/master/scripts/for1.rhai) | [`for`]({{rootUrl}}/language/for.md) loops | +| [`for2.rhai`](https://github.com/jonathandturner/rhai/tree/master/scripts/for2.rhai) | [`for`]({{rootUrl}}/language/for.md) loops on [arrays] | +| [`function_decl1.rhai`](https://github.com/jonathandturner/rhai/tree/master/scripts/function_decl1.rhai) | A [function] without parameters | +| [`function_decl2.rhai`](https://github.com/jonathandturner/rhai/tree/master/scripts/function_decl2.rhai) | A [function] with two parameters | +| [`function_decl3.rhai`](https://github.com/jonathandturner/rhai/tree/master/scripts/function_decl3.rhai) | A [function] with many parameters | +| [`if1.rhai`](https://github.com/jonathandturner/rhai/tree/master/scripts/if1.rhai) | [`if`]({{rootUrl}}/language/if.md) example | +| [`loop.rhai`](https://github.com/jonathandturner/rhai/tree/master/scripts/loop.rhai) | Count-down [`loop`]({{rootUrl}}/language/loop.md) in Rhai, emulating a `do` .. `while` loop | +| [`oop.rhai`](https://github.com/jonathandturner/rhai/tree/master/scripts/oop.rhai) | Simulate [object-oriented programming (OOP)][OOP] | +| [`op1.rhai`](https://github.com/jonathandturner/rhai/tree/master/scripts/op1.rhai) | Just simple addition | +| [`op2.rhai`](https://github.com/jonathandturner/rhai/tree/master/scripts/op2.rhai) | Simple addition and multiplication | +| [`op3.rhai`](https://github.com/jonathandturner/rhai/tree/master/scripts/op3.rhai) | Change evaluation order with parenthesis | +| [`string.rhai`](https://github.com/jonathandturner/rhai/tree/master/scripts/string.rhai) | [String] operations | +| [`strings_map.rhai`](https://github.com/jonathandturner/rhai/tree/master/scripts/strings_map.rhai) | [String] and [object map] operations | +| [`while.rhai`](https://github.com/jonathandturner/rhai/tree/master/scripts/while.rhai) | [`while`]({{rootUrl}}/language/while.md) loop | Benchmark Scripts @@ -34,18 +34,18 @@ Benchmark Scripts The following scripts are for benchmarking the speed of Rhai: -| Scripts | Description | -| ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | -| [`speed_test.rhai`](https://github.com/jonathandturner/rhai/tree/master/scripts/speed_test.rhai) | A simple program to measure the speed of Rhai's interpreter (1 million iterations). | -| [`primes.rhai`](https://github.com/jonathandturner/rhai/tree/master/scripts/primes.rhai) | Use Sieve of Eratosthenes to find all primes smaller than a limit. | -| [`fibonacci.rhai`](https://github.com/jonathandturner/rhai/tree/master/scripts/fibonacci.rhai) | Calculate the n-th Fibonacci number using a really dumb algorithm. | -| [`mat_mul.rhai`](https://github.com/jonathandturner/rhai/tree/master/scripts/mat_mul.rhai) | Matrix multiplication test to measure the speed of multi-dimensional array access. | +| Scripts | Description | +| ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- | +| [`speed_test.rhai`](https://github.com/jonathandturner/rhai/tree/master/scripts/speed_test.rhai) | A simple application to measure the speed of Rhai's interpreter (1 million iterations). | +| [`primes.rhai`](https://github.com/jonathandturner/rhai/tree/master/scripts/primes.rhai) | Use Sieve of Eratosthenes to find all primes smaller than a limit. | +| [`fibonacci.rhai`](https://github.com/jonathandturner/rhai/tree/master/scripts/fibonacci.rhai) | Calculate the n-th Fibonacci number using a really dumb algorithm. | +| [`mat_mul.rhai`](https://github.com/jonathandturner/rhai/tree/master/scripts/mat_mul.rhai) | Matrix multiplication test to measure the speed of multi-dimensional array access. | Running Example Scripts ---------------------- -To run the scripts, either make a tiny program or use of the `rhai_runner` example: +The [`rhai_runner`](../examples/rust.md) example can be used to run the scripts: ```bash cargo run --example rhai_runner scripts/any_script.rhai diff --git a/no_std/no_std_win/Cargo.toml b/no_std/no_std_test/Cargo.toml similarity index 84% rename from no_std/no_std_win/Cargo.toml rename to no_std/no_std_test/Cargo.toml index 46140968..f22daed0 100644 --- a/no_std/no_std_win/Cargo.toml +++ b/no_std/no_std_test/Cargo.toml @@ -1,10 +1,10 @@ [package] -name = "no_std_win" +name = "no_std_test" version = "0.1.0" edition = "2018" authors = ["Stephen Chung"] -description = "no-std test application for the Windows API" -homepage = "https://github.com/jonathandturner/rhai/tree/master/no_std/no_std_win" +description = "no-std test application" +homepage = "https://github.com/jonathandturner/rhai/tree/master/no_std/no_std_test" repository = "https://github.com/jonathandturner/rhai" [dependencies] diff --git a/no_std/no_std_win/README.md b/no_std/no_std_test/README.md similarity index 66% rename from no_std/no_std_win/README.md rename to no_std/no_std_test/README.md index 22af28b6..e7edfc51 100644 --- a/no_std/no_std_win/README.md +++ b/no_std/no_std_test/README.md @@ -1,7 +1,7 @@ -`no-std` Sample for Windows API -============================== +`no-std` Test Sample +==================== -This sample application is a bare-bones `no-std` build for the Windows API. +This sample application is a bare-bones `no-std` build for testing. [`wee_alloc`](https://crates.io/crates/wee_alloc) is used as the allocator. diff --git a/no_std/no_std_win/src/main.rs b/no_std/no_std_test/src/main.rs similarity index 92% rename from no_std/no_std_win/src/main.rs rename to no_std/no_std_test/src/main.rs index 4df87b2b..88ba8b02 100644 --- a/no_std/no_std_win/src/main.rs +++ b/no_std/no_std_test/src/main.rs @@ -1,4 +1,4 @@ -//! This is a `no-std` application for the Windows API that evaluates +//! This is a `no-std` application for the that evaluates //! a simple expression and uses the result as the return value. #![no_std]