Merge pull request #172 from schungx/oop

OOP support

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "rhai"
-version = "0.15.2"
+version = "0.16.0"
 edition = "2018"
 authors = ["Jonathan Turner", "Lukáš Hozda", "Stephen Chung"]
 description = "Embedded scripting for Rust"
@@ -33,6 +33,7 @@ no_index = []       # no arrays and indexing
 no_object = []      # no custom objects
 no_function = []    # no script-defined functions
 no_module = []      # no modules
+internals = []      # expose internal data structures
 
 # compiling for no-std
 no_std = [ "num-traits/libm", "hashbrown", "core-error", "libm", "ahash" ]

README.md

@@ -21,7 +21,7 @@ Supported targets and builds
 Features
 --------
 
-* Easy-to-use language similar to JS+Rust with dynamic typing.
+* Easy-to-use language similar to JavaScript+Rust with dynamic typing.
 * Tight integration with native Rust [functions](https://schungx.github.io/rhai/rust/functions.html) and [types]([#custom-types-and-methods](https://schungx.github.io/rhai/rust/custom.html)), including [getters/setters](https://schungx.github.io/rhai/rust/getters-setters.html), [methods](https://schungx.github.io/rhai/rust/custom.html) and [indexers](https://schungx.github.io/rhai/rust/indexers.html).
 * Freely pass Rust variables/constants into a script via an external [`Scope`](https://schungx.github.io/rhai/rust/scope.html).
 * Easily [call a script-defined function](https://schungx.github.io/rhai/engine/call-fn.html) from Rust.
@@ -31,15 +31,23 @@ Features
   one single source file, all with names starting with `"unsafe_"`).
 * Re-entrant scripting engine can be made `Send + Sync` (via the [`sync`] feature).
 * Sand-boxed - the scripting engine, if declared immutable, cannot mutate the containing environment unless explicitly permitted (e.g. via a `RefCell`).
-* Rugged - protection against malicious attacks (such as [stack-overflow](https://schungx.github.io/rhai/safety/max-call-stack.html), [over-sized data](https://schungx.github.io/rhai/safety/max-string-size.html), and [runaway scripts](https://schungx.github.io/rhai/safety/max-operations.html) etc.) that may come from untrusted third-party user-land scripts.
+* Rugged - protected against malicious attacks (such as [stack-overflow](https://schungx.github.io/rhai/safety/max-call-stack.html), [over-sized data](https://schungx.github.io/rhai/safety/max-string-size.html), and [runaway scripts](https://schungx.github.io/rhai/safety/max-operations.html) etc.) that may come from untrusted third-party user-land scripts.
 * Track script evaluation [progress](https://schungx.github.io/rhai/safety/progress.html) and manually terminate a script run.
 * [Function overloading](https://schungx.github.io/rhai/language/overload.html).
 * [Operator overloading](https://schungx.github.io/rhai/rust/operators.html).
+* Dynamic dispatch via [function pointers](https://schungx.github.io/rhai/language/fn-ptr.html).
+* Some support for [object-oriented programming (OOP)](https://schungx.github.io/rhai/language/oop.html).
 * Organize code base with dynamically-loadable [modules](https://schungx.github.io/rhai/language/modules.html).
 * Scripts are [optimized](https://schungx.github.io/rhai/engine/optimize.html) (useful for template-based machine-generated scripts) for repeated evaluations.
 * Support for [minimal builds](https://schungx.github.io/rhai/start/builds/minimal.html) by excluding unneeded language [features](https://schungx.github.io/rhai/start/features.html).
 
 Documentation
 -------------
 
-See [The Rhai Book](https://schungx.github.io/rhai) for details on the Rhai script engine and language.
+See [The Rhai Book](https://schungx.github.io/rhai) for details on the Rhai scripting engine and language.
+
+Playground
+----------
+
+An [Online Playground](https://alvinhochun.github.io/rhai-demo/) is available with syntax-highlighting editor.
+Scripts can be evaluated directly from the editor.

RELEASES.md

@@ -1,18 +1,34 @@
 Rhai Release Notes
 ==================
 
-Version 0.15.2
+Version 0.16.0
 ==============
 
+The major new feature in this version is OOP - well, poor man's OOP, that is.
+
 Breaking changes
 ----------------
 
 * The trait function `ModuleResolver::resolve` no longer takes a `Scope` as argument.
+* Functions defined in script now differentiates between using method-call style and normal function-call style.
+  The method-call style will bind the object to the `this` parameter instead of consuming the first parameter.
+* Imported modules are no longer stored in the `Scope`.  `Scope::push_module` is removed.
+  Therefore, cannot rely on module imports to persist across invocations using a `Scope`.
+* `AST::retain_functions` is used for another purpose. The old `AST::retain_functions` is renamed to `AST::clear_statements`.
+
+New features
+------------
+
+* Support for _function pointers_ via `Fn(name)` and `Fn.call(...)` syntax - a poor man's first-class function.
+* Support for calling script-defined functions in method-call style with `this` binding to the object.
+* Special support in object maps for OOP.
+* Expanded the `AST` API for fine-tuned manipulation of functions.
 
 Enhancements
 ------------
 
 * [The Rhai Book](https://schungx.github.io/rhai) is online.  Most content in the original `README` was transferred to the Book.
+* New feature `internals` to expose internal data structures (e.g. the AST nodes).
 
 
 Version 0.15.1

doc/src/SUMMARY.md

@@ -1,36 +1,37 @@
 The Rhai Scripting Language
 ==========================
 
-1. [What is Rhai](about.md)
+1. [What is Rhai](about/index.md)
    1. [Features](about/features.md)
    2. [Supported Targets and Builds](about/targets.md)
    3. [What Rhai Isn't](about/non-design.md)
    4. [Related Resources](about/related.md)
-2. [Getting Started](start.md)
-   1. [Install the Rhai Crate](start/install.md)
-   2. [Optional Features](start/features.md)
-   3. [Special Builds](start/builds.md)
-      1. [Performance Build](start/builds/performance.md)
-      2. [Minimal Build](start/builds/minimal.md)
-      3. [no-std Build](start/builds/no-std.md)
+3. [Getting Started](start/index.md)
+   1. [Online Playground](start/playground.md)
+   2. [Install the Rhai Crate](start/install.md)
+   3. [Optional Features](start/features.md)
+   4. [Special Builds](start/builds/index.md)
+      1. [Performance](start/builds/performance.md)
+      2. [Minimal](start/builds/minimal.md)
+      3. [no-std](start/builds/no-std.md)
       4. [WebAssembly (WASM)](start/builds/wasm.md)
-   4. [Examples](start/examples.md)
+   5. [Examples](start/examples/index.md)
       1. [Rust](start/examples/rust.md)
       2. [Scripts](start/examples/scripts.md)
-3. [Using the `Engine`](engine.md)
+4. [Using the `Engine`](engine/index.md)
    1. [Hello World in Rhai - Evaluate a Script](engine/hello-world.md)
    2. [Compile a Script to AST for Repeated Evaluations](engine/compile.md)
    3. [Call a Rhai Function from Rust](engine/call-fn.md)
    4. [Create a Rust Anonymous Function from a Rhai Function](engine/func.md)
    5. [Evaluate Expressions Only](engine/expressions.md)
    6. [Raw Engine](engine/raw.md)
-4. [Extend Rhai with Rust](rust.md)
+5. [Extend Rhai with Rust](rust/index.md)
    1. [Traits](rust/traits.md)
    2. [Register a Rust Function](rust/functions.md)
       1. [String Parameters in Rust Functions](rust/strings.md)
    3. [Register a Generic Rust Function](rust/generic.md)
    4. [Register a Fallible Rust Function](rust/fallible.md)
-   5. [Packages](rust/packages.md)
+   5. [Packages](rust/packages/index.md)
       1. [Built-in Packages](rust/packages/builtin.md)
       2. [Create a Custom Package](rust/packages/create.md)
    6. [Override a Built-in Function](rust/override.md)
@@ -40,9 +41,9 @@ The Rhai Scripting Language
       2. [Indexers](rust/indexers.md)
       3. [Disable Custom Types](rust/disable-custom.md)
       4. [Printing Custom Types](rust/print-custom.md)
-   9.  [Scope - Initializing and Maintaining State](rust/scope.md)
+   9. [Scope - Initializing and Maintaining State](rust/scope.md)
    10. [Engine Configuration Options](rust/options.md)
-5. [Rhai Language Reference](language.md)
+6. [Rhai Language Reference](language/index.md)
    1. [Comments](language/comments.md)
    2. [Values and Types](language/values-and-types.md)
       1. [Dynamic Values](language/dynamic.md)
@@ -56,6 +57,7 @@ The Rhai Scripting Language
       5. [Arrays](language/arrays.md)
       6. [Object Maps](language/object-maps.md)
           1. [Parse from JSON](language/json.md)
+          2. [Special Support for OOP](language/object-maps-oop.md)
       7. [Time-Stamps](language/timestamps.md)
    3. [Keywords](language/keywords.md)
    4. [Statements](language/statements.md)
@@ -69,17 +71,19 @@ The Rhai Scripting Language
    12. [Return Values](language/return.md)
    13. [Throw Exception on Error](language/throw.md)
    14. [Functions](language/functions.md)
-       1. [Function Overloading](language/overload.md)
-       2. [Call Method as Function](language/method.md)
+       1. [Call Method as Function](language/method.md)
+       2. [Overloading](language/overload.md)
+       3. [Namespaces](language/fn-namespaces.md)
+       4. [Function Pointers](language/fn-ptr.md)
    15. [Print and Debug](language/print-debug.md)
-   16. [Modules](language/modules.md)
+   16. [Modules](language/modules/index.md)
        1. [Export Variables, Functions and Sub-Modules](language/modules/export.md)
        2. [Import Modules](language/modules/import.md)
        3. [Create from Rust](language/modules/rust.md)
        4. [Create from AST](language/modules/ast.md)
        5. [Module Resolvers](language/modules/resolvers.md)
           1. [Implement a Custom Module Resolver](language/modules/imp-resolver.md)
-6. [Safety and Protection](safety.md)
+7. [Safety and Protection](safety/index.md)
    1. [Checked Arithmetic](safety/checked.md)
    2. [Sand-Boxing](safety/sandbox.md)
    3. [Maximum Length of Strings](safety/max-string-size.md)
@@ -90,12 +94,17 @@ The Rhai Scripting Language
    7. [Maximum Number of Modules](safety/max-modules.md)
    8. [Maximum Call Stack Depth](safety/max-call-stack.md)
    9. [Maximum Statement Depth](safety/max-stmt-depth.md)
-7. [Advanced Topics](advanced.md)
-   1. [Script Optimization](engine/optimize.md)
+8. [Advanced Topics](advanced.md)
+   1. [Object-Oriented Programming (OOP)](language/oop.md)
+   2. [Script Optimization](engine/optimize/index.md)
       1. [Optimization Levels](engine/optimize/optimize-levels.md)
       2. [Re-Optimize an AST](engine/optimize/reoptimize.md)
       3. [Eager Function Evaluation](engine/optimize/eager.md)
       4. [Side-Effect Considerations](engine/optimize/side-effects.md)
       5. [Volatility Considerations](engine/optimize/volatility.md)
       6. [Subtle Semantic Changes](engine/optimize/semantics.md)
-   2. [Eval Statement](language/eval.md)
+   3. [Eval Statement](language/eval.md)
+9. [Appendix](appendix/index.md)
+   1. [Keywords](appendix/keywords.md)
+   2. [Operators](appendix/operators.md)
+   3. [Literals](appendix/literals.md)

doc/src/about/features.md

@@ -6,9 +6,9 @@ Features
 Easy
 ----
 
-* Easy-to-use language similar to JS+Rust with dynamic typing.
+* Easy-to-use language similar to JavaScript+Rust with dynamic typing.
 
-* Tight integration with native Rust [functions]({{rootUrl}}/rust/functions.md) and [types]({{rootUrl}}/rust/custom.md), including [getters/setters]({{rootUrl}}/rust/getters-setters.md), [methods]({{rootUrl}}/rust/custom.md) and [indexers]({{rootUrl}}/rust/indexers.md).
+* Tight integration with native Rust [functions] and [types][custom types], including [getters/setters], [methods][custom type] and [indexers].
 
 * Freely pass Rust variables/constants into a script via an external [`Scope`].
 
@@ -24,7 +24,7 @@ Fast
 
 * Fairly efficient evaluation (1 million iterations in 0.25 sec on a single core, 2.3 GHz Linux VM).
 
-* Scripts are [optimized]({{rootUrl}}/engine/optimize.md) (useful for template-based machine-generated scripts) for repeated evaluations.
+* Scripts are [optimized][script optimization] (useful for template-based machine-generated scripts) for repeated evaluations.
 
 Dynamic
 -------
@@ -35,6 +35,10 @@ Dynamic
 
 * Organize code base with dynamically-loadable [modules].
 
+* Dynamic dispatch via [function pointers].
+
+* Some support for [object-oriented programming (OOP)][OOP].
+
 Safe
 ----
 
@@ -46,7 +50,7 @@ Rugged
 
 * Sand-boxed - the scripting [`Engine`], if declared immutable, cannot mutate the containing environment unless explicitly permitted (e.g. via a `RefCell`).
 
-* Protected against malicious attacks (such as [stack-overflow]({{rootUrl}}/safety/max-call-stack.md), [over-sized data]({{rootUrl}}/safety/max-string-size.md), and [runaway scripts]({{rootUrl}}/safety/max-operations.md) etc.) that may come from untrusted third-party user-land scripts.
+* Protected against malicious attacks (such as [stack-overflow][maximum call stack depth], [over-sized data][maximum length of strings], and [runaway scripts][maximum number of operations] etc.) that may come from untrusted third-party user-land scripts.
 
 * Track script evaluation [progress] and manually terminate a script run.
 

doc/src/about.md → doc/src/about/index.md

@@ -1,7 +1,7 @@
 What is Rhai
 ============
 
-{{#include links.md}}
+{{#include ../links.md}}
 
 Rhai is an embedded scripting language and evaluation engine for Rust that gives a safe and easy way
 to add scripting to any application.

doc/src/about/non-design.md

@@ -11,10 +11,15 @@ It doesn't attempt to be a new language. For example:
 * No traits...  so it is also not Rust. Do your Rusty stuff in Rust.
 
 * No structures/records - define your types in Rust instead; Rhai can seamlessly work with _any Rust type_.
+
   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_.
 
 * No first-class functions - Code your functions in Rust instead, and register them with Rhai.
 
+  There is, however, support for simple [function pointers] allowing runtime dispatch by function name.
+
 * 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).
@@ -26,7 +31,7 @@ Due to this intended usage, Rhai deliberately keeps the language simple and smal
 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
-more complete languages such as JS or Lua.
+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.
 All your core functionalities should be in Rust.

doc/src/about/related.md

@@ -5,8 +5,13 @@ Related Resources
 
 Other online documentation resources for Rhai:
 
-* [`DOCS.RS`](https://docs.rs/rhai)
+* [`crates.io`](https://crates.io/crates/rhai/) - Rhai crate
 
+* [`DOCS.RS`](https://docs.rs/rhai) - Rhai API documentation
+
+* [`LIB.RS`](https://lib.rs/crates/rhai) - Rhai library info
+
+* [Online Playground][playground] - Run scripts directly from editor
 
 Other cool projects to check out:
 

doc/src/advanced.md

@@ -7,4 +7,4 @@ This section covers advanced features such as:
 
 * [Script optimization]
 
-* The dreaded (or beloved depending on your taste) [`eval`] statement
+* The dreaded (or beloved for those with twisted tastes) [`eval`] statement

doc/src/appendix/index.md

@@ -0,0 +1,6 @@
+Appendix
+========
+
+{{#include ../links.md}}
+
+This section contains miscellaneous reference materials.

doc/src/appendix/keywords.md

@@ -0,0 +1,33 @@
+Keywords List
+=============
+
+{{#include ../links.md}}
+
+|        Keyword        | Description                              | Not available under |
+| :-------------------: | ---------------------------------------- | :-----------------: |
+|        `true`         | Boolean true literal                     |                     |
+|        `false`        | Boolean false literal                    |                     |
+|         `let`         | Variable declaration                     |                     |
+|        `const`        | Constant declaration                     |                     |
+|         `if`          | If statement                             |                     |
+|        `else`         | else block of if statement               |                     |
+|        `while`        | While loop                               |                     |
+|        `loop`         | Infinite loop                            |                     |
+|         `for`         | For loop                                 |                     |
+|         `in`          | Containment test, part of for loop       |                     |
+|      `continue`       | Continue a loop at the next iteration    |                     |
+|        `break`        | Loop breaking                            |                     |
+|       `return`        | Return value                             |                     |
+|        `throw`        | Throw exception                          |                     |
+|       `import`        | Import module                            |    [`no_module`]    |
+|       `export`        | Export variable                          |    [`no_module`]    |
+|         `as`          | Alias for variable export                |    [`no_module`]    |
+|       `private`       | Mark function private                    |   [`no_function`]   |
+| `fn` (lower-case `f`) | Function definition                      |   [`no_function`]   |
+|  `Fn` (capital `F`)   | Function to create a [function pointer]  |                     |
+|        `call`         | Call a [function pointer]                |                     |
+|        `this`         | Reference to base object for method call |   [`no_function`]   |
+|       `type_of`       | Get type name of value                   |                     |
+|        `print`        | Print value                              |                     |
+|        `debug`        | Print value in debug format              |                     |
+|        `eval`         | Evaluate script                          |                     |

doc/src/appendix/literals.md

@@ -0,0 +1,16 @@
+Literals Syntax
+===============
+
+{{#include ../links.md}}
+
+|                Type                |                                  Literal syntax                                  |
+| :--------------------------------: | :------------------------------------------------------------------------------: |
+|               `INT`                | `42`, `-123`, `0`,<br/>`0x????..` (hex), `0b????..` (binary), `0o????..` (octal) |
+|              `FLOAT`               |                            `42.0`, `-123.456`, `0.0`                             |
+|              [String]              |                        `"... \x?? \u???? \U???????? ..."`                        |
+|             Character              |                        `"... \x?? \u???? \U???????? ..."`                        |
+|             [`Array`]              |                               `[ ???, ???, ??? ]`                                |
+|            [Object map]            |                    `#{ a: ???, b: ???, c: ???, "def": ??? }`                     |
+|            Boolean true            |                                      `true`                                      |
+|           Boolean false            |                                     `false`                                      |
+| `Nothing`/`null`/`nil`/`void`/Unit |                                       `()`                                       |