kjuulh/rhai
1
0
Fork 0
Code Issues 1 Pull Requests 1 Packages Projects Releases Wiki Activity

Revise docs for 0.19.0.

Browse Source
This commit is contained in:
Stephen Chung
2020-09-30 23:02:01 +08:00
parent a04ed02b54
commit cbc3d8764a
30 changed files with 291 additions and 125 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
doc/src/about/features.md
View File

@@ -14,8 +14,8 @@ Easy
* Easily [call a script-defined function]({{rootUrl}}/engine/call-fn.md) from Rust.
* Very few additional dependencies (right now only [`smallvec`](https://crates.io/crates/smallvec/));
for [`no-std`] builds, a number of additional dependencies are pulled in to provide for functionalities that used to be in `std`.
* Very few additional dependencies - right now only [`smallvec`](https://crates.io/crates/smallvec/) plus crates for procedural macros;
for [`no-std`] and `WASM` builds, a number of additional dependencies are pulled in to provide for missing functionalities.
Fast
----

26
doc/src/about/index.md
View File

@@ -3,6 +3,8 @@ What is Rhai
{{#include ../links.md}}
![Rhai Logo](../images/rhai_logo.png)
Rhai is an embedded scripting language and evaluation engine for Rust that gives a safe and easy way
to add scripting to any application.
@@ -13,3 +15,27 @@ Versions
This Book is for version **{{version}}** of Rhai.
For the latest development version, see [here]({{rootUrl}}/vnext/).
Etymology of the name "Rhai"
---------------------------
### As per Rhai's author Johnathan Turner
In the beginning there was [ChaiScript](http://chaiscript.com),
which is an embedded scripting language for C++.
Originally it was intended to be a scripting language similar to **JavaScript**.
With java being a kind of hot beverage, the new language was named after
another hot beverage - **Chai**, which is the word for "tea" in many world languages
and, in particular, a popular kind of milk tea consumed in India.
Later, when the novel implementation technique behind ChaiScript was ported from C++ to Rust,
logically the `C` was changed to an `R` to make it "RhaiScript", or just "Rhai".
### On the origin of the temporary Rhai logo
One of Rhai's maintainers, Stephen Chung, was thinking about a logo when he accidentally
came across a copy of _Catcher in the Rye_ in a restaurant. The rest was history.
It is temporary until it becomes official, that is...

6
doc/src/about/license.md
View File

@@ -3,13 +3,11 @@ Licensing
{{#include ../links.md}}
Rhai is licensed under either:
Rhai is licensed under either of the following, at your choice:
* [Apache License, Version 2.0]({{repoHome}}/LICENSE-APACHE.txt), or
* [MIT license]({{repoHome}}/LICENSE-MIT.txt)
at your choice.
* [MIT license]({{repoHome}}/LICENSE-MIT.txt).
Unless explicitly stated otherwise, any contribution intentionally submitted for inclusion in this crate,
as defined in the Apache-2.0 license, shall be dual-licensed as above,

31
doc/src/about/non-design.md
View File

@@ -14,7 +14,7 @@ It doesn't attempt to be a new language. For example:
There is, however, a built-in [object map] type which is adequate for most uses.
It is possible to simulate [object-oriented programming (OOP)][OOP] by storing [function pointers]
in [object map] properties, turning them into _methods_.
or [closures] in [object map] properties, turning them into _methods_.
* No first-class functions - Code your functions in Rust instead, and register them with Rhai.
@@ -22,22 +22,32 @@ It doesn't attempt to be a new language. For example:
* No garbage collection - this should be expected, so...
* No closures - do your closure magic in Rust instead; [turn a Rhai scripted function into a Rust closure]({{rootUrl}}/engine/call-fn.md).
* No first-class closures - do your closure magic in Rust instead: [turn a Rhai scripted function into a Rust closure]({{rootUrl}}/engine/call-fn.md).
But you can [curry][currying] a [function pointer] with arguments to simulate it somewhat.
There is, however, support for simulated [closures] via [currying] a [function pointer] with
captured shared variables.
* 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 applications.
* 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 applications.
* No formal language grammar - Rhai uses a hand-coded lexer, a hand-coded top-down recursive-descent parser
for statements and a Pratt parser for expressions.
This lack of formalism allows the parser itself to be exposed as a service in order to support
[disabling keywords/operators][disable keywords and operators], adding [custom operators],
and defining [custom syntax].
Do Not Write The Next 4D VR Game in Rhai
---------------------------------------
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.
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 VM, JIT etc.
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.
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.
Thin Dynamic Wrapper Layer Over Rust Code
@@ -47,7 +57,8 @@ In actual practice, it is usually best to expose a Rust API into Rhai for script
All the core functionalities should be written in Rust, with Rhai being the dynamic _control_ layer.
This is similar to some dynamic languages where most of the core functionalities reside in a C/C++ standard library.
This is similar to some dynamic languages where most of the core functionalities reside in a C/C++
standard library.
Another similar scenario is a web front-end driving back-end services written in a systems language.
In this case, JavaScript takes the role of Rhai while the back-end language, well... it can actually also be Rust.

4
doc/src/about/related.md
View File

@@ -5,7 +5,7 @@ Related Resources
Other online documentation resources for Rhai:
* [`crates.io`](https://crates.io/crates/rhai/) - Rhai crate
* [`crates.io`](https://crates.io/crates/rhai) - Rhai crate
* [`DOCS.RS`](https://docs.rs/rhai) - Rhai API documentation
@@ -15,6 +15,6 @@ Other online documentation resources for Rhai:
Other cool projects to check out:
* [ChaiScript](http://chaiscript.com/) - A strong inspiration for Rhai. An embedded scripting language for C++ that I helped created many moons ago, now being led by my cousin.
* [ChaiScript](http://chaiscript.com) - A strong inspiration for Rhai. An embedded scripting language for C++.
* Check out the list of [scripting languages for Rust](https://github.com/rust-unofficial/awesome-rust#scripting) on [awesome-rust](https://github.com/rust-unofficial/awesome-rust)

6
doc/src/about/targets.md
View File

@@ -10,3 +10,9 @@ The following targets and builds are support by Rhai:
* WebAssembly ([WASM])
* [`no-std`]
Minimum Rust Version
--------------------
The minimum version of Rust required to compile Rhai is `1.45.0`.