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

Add export to JSON.

Browse Source
This commit is contained in:
Stephen Chung 2020-12-20 12:27:47 +08:00
parent c6a3ce2cd5
commit 22039b24b3
9 changed files with 232 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Cargo.toml
View File

@ -42,7 +42,7 @@ no_closure = [] # no automatic sharing and capture of anonymous functions to
no_module = [] # no modules
internals = [] # expose internal data structures
unicode-xid-ident = ["unicode-xid"] # allow Unicode Standard Annex #31 for identifiers.
metadata = [ "serde", "serde_json"]
metadata = [ "serde", "serde_json"] # enables exporting functions metadata to JSON
# compiling for no-std
no_std = [ "smallvec/union", "num-traits/libm", "hashbrown", "core-error", "libm", "ahash" ]

4
RELEASES.md
View File

@ -10,6 +10,9 @@ Each function defined in an `AST` can optionally attach _doc-comments_ (which, a
are comments prefixed by either `///` or `/**`). Doc-comments allow third-party tools to
automatically generate documentation for functions defined in a Rhai script.
A new API, `Engine::gen_fn_metadata_to_json`, paired with the new `metadata` feature,
exports the full list of functions metadata (including those in an `AST`) as a JSON document.
Bug fixes
---------
@ -31,6 +34,7 @@ New features
* `AST::iter_functions` now returns `ScriptFnMetadata` which includes, among others, _doc-comments_ for functions prefixed by `///` or `/**`.
* A functions lookup cache is added to make function call resolution faster.
* A new feature `metadata` is added that pulls in `serde_json` and enables `Engine::gen_fn_metadata_to_json` which exports the full list of functions metadata (including those inside an `AST`) in JSON format.
Enhancements
------------

4
doc/src/SUMMARY.md
View File

@ -136,7 +136,9 @@ The Rhai Scripting Language
2. [Custom Operators](engine/custom-op.md)
3. [Extending with Custom Syntax](engine/custom-syntax.md)
5. [Multiple Instantiation](patterns/multiple.md)
6. [Get Function Signatures](engine/get_fn_sig.md)
6. [Functions Metadata](engine/metadata/index.md)
1. [Generate Function Signatures](engine/metadata/gen_fn_sig.md)
2. [Export Metadata to JSON](engine/metadata/export_to_json.md)
10. [Appendix](appendix/index.md)
1. [Keywords](appendix/keywords.md)
2. [Operators and Symbols](appendix/operators.md)

106
doc/src/engine/metadata/export_to_json.md Normal file
View File

@ -0,0 +1,106 @@
Export Functions Metadata to JSON
================================
{{#include ../../links.md}}
`Engine::gen_fn_metadata_to_json`
--------------------------------
As part of a _reflections_ API, `Engine::gen_fn_metadata_to_json` exports the full list
of [functions metadata] in JSON format.
The [`metadata`] feature must be used to turn on this method, which requires
the [`serde_json`](https://crates.io/crates/serde_json) crate.
### Sources
Functions from the following sources are included:
1) Script-defined functions in an [`AST`], if provided
2) Native Rust functions registered into the global namespace via the `Engine::register_XXX` API
3) _Public_ (i.e. non-[`private`]) functions (native Rust or Rhai scripted) in global sub-modules registered via
[`Engine::register_module`]({{rootUrl}}/rust/modules/create.md)
4) Native Rust functions in registered [packages] (optional)
Notice that if a function has been [overloaded][function overloading], only the overriding function's
metadata is included.
JSON Schema
-----------
The JSON schema used to hold functions metadata is very simple, containing a nested structure of
`modules` and a list of `functions`.
### Modules Schema
```json
{
"modules":
{
"sub_module_1":
{
"modules":
{
"sub_sub_module_A":
{
"functions":
[
{ ... function metadata ... },
{ ... function metadata ... },
{ ... function metadata ... },
{ ... function metadata ... },
...
]
},
"sub_sub_module_B":
{
...
}
}
},
"sub_module_2":
{
...
},
...
},
"functions":
[
{ ... function metadata ... },
{ ... function metadata ... },
{ ... function metadata ... },
{ ... function metadata ... },
...
]
}
```
### Function Metadata Schema
```json
{
"namespace": "internal" | "global",
"access": "public" | "private",
"name": "fn_name",
"type": "native" | "script",
"numParams": 42, /* number of parameters */
"params": /* omitted if no parameters */
[
{ "name": "param_1", "type": "type_1" },
{ "name": "param_2" }, /* no type info */
{ "name": "_", "type": "type_3" },
...
],
"returnType": "ret_type", /* omitted if unknown */
"signature": "[private] fn_name(param_1: type_1, param_2, _: type_3) -> ret_type",
"docComments": /* omitted if none */
[
"/// doc-comment line 1",
"/// doc-comment line 2",
"/** doc-comment block */",
...
]
}
```

31
doc/src/engine/get_fn_sig.md → doc/src/engine/metadata/gen_fn_sig.md
View File

@ -1,26 +1,29 @@
Get Function Signatures
=======================
Generate Function Signatures
===========================
{{#include ../links.md}}
{{#include ../../links.md}}
`Engine::gen_fn_signatures`
--------------------------
As part of a _reflections_ API, `Engine::gen_fn_signatures` returns a list of function signatures
(`Vec<String>`), each corresponding to a particular function available to that [`Engine`] instance.
As part of a _reflections_ API, `Engine::gen_fn_signatures` returns a list of function _signatures_
(as `Vec<String>`), each corresponding to a particular function available to that [`Engine`] instance.
> `fn_name ( param_1: type_1, param_2: type_2, ... , param_n : type_n ) -> return_type`
### Sources
Functions from the following sources are included, in order:
1) Functions registered into the global namespace via the `Engine::register_XXX` API,
2) Functions in global sub-modules registered via [`Engine::register_module`]({{rootUrl}}/rust/modules/create.md),
3) Functions in registered [packages] (optional)
Included are both native Rust as well as script-defined functions (except [`private`] ones).
1) Native Rust functions registered into the global namespace via the `Engine::register_XXX` API
2) _Public_ (i.e. non-[`private`]) functions (native Rust or Rhai scripted) in global sub-modules registered via
[`Engine::register_module`]({{rootUrl}}/rust/modules/create.md)
3) Native Rust functions in registered [packages] (optional)
Function Metadata
-----------------
Functions Metadata
------------------
Beware, however, that not all function signatures contain parameters and return value information.
@ -30,7 +33,7 @@ For instance, functions registered via `Engine::register_XXX` contain no informa
the names of parameter and their actual types because Rust simply does not make such metadata
available natively. The return type is also undetermined.
A function registered under the name 'foo' with three parameters and unknown return type:
A function registered under the name `foo` with three parameters and unknown return type:
> `foo(_, _, _)`
@ -41,7 +44,7 @@ Notice that function names do not need to be valid identifiers.
A [property setter][getters/setters] - again, unknown parameters and return type.
Notice that function names do not need to be valid identifiers.
In this case, the first parameter should be '&mut T' of the custom type and the return value is '()':
In this case, the first parameter should be `&mut T` of the custom type and the return value is `()`:
> `set$prop(_, _, _)`

28
doc/src/engine/metadata/index.md Normal file
View File

@ -0,0 +1,28 @@
Functions Metadata
==================
{{#include ../../links.md}}
The _metadata_ of a [function] means all relevant information related to a function's
definition including:
1. Its callable name
2. Its access mode (public or [private][`private`])
3. Its parameters and types (if any)
4. Its return value and type (if any)
5. Its nature (i.e. native Rust-based or Rhai script-based)
6. Its [namespace][function namespace] (module or global)
7. Its purpose, in the form of [doc-comments]
8. Usage notes, warnings, etc., in the form of [doc-comments]
A function's _signature_ encapsulates the first four pieces of information in a single
concise line of definition:
> `[private] fn_name ( param_1: type_1, param_2: type_2, ... , param_n : type_n ) -> return_type`

2
doc/src/links.md
View File

@ -41,6 +41,7 @@
[plugin modules]: {{rootUrl}}/plugins/module.md
[plugin function]: {{rootUrl}}/plugins/function.md
[plugin functions]: {{rootUrl}}/plugins/function.md
[functions metadata]: {{rootUrl}}/engine/metadata/index.md
[`Scope`]: {{rootUrl}}/engine/scope.md
[`serde`]: {{rootUrl}}/rust/serde.md
@ -90,6 +91,7 @@
[timestamp]: {{rootUrl}}/language/timestamps.md
[timestamps]: {{rootUrl}}/language/timestamps.md
[doc-comments]: {{rootUrl}}/language/comments.md#doc-comments
[function]: {{rootUrl}}/language/functions.md
[functions]: {{rootUrl}}/language/functions.md
[function overloading]: {{rootUrl}}/rust/functions.md#function-overloading

6
doc/src/start/features.md
View File

@ -12,7 +12,7 @@ Excluding unneeded functionalities can result in smaller, faster builds as well
more control over what a script can (or cannot) do.
| Feature | Additive? | Description |
| ------------------- | :-------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ------------------- | :-------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `unchecked` | no | disables arithmetic checking (such as over-flows and division by zero), call stack depth limit, operations count limit and modules loading limit.<br/>Beware that a bad script may panic the entire system! |
| `sync` | no | restricts all values types to those that are `Send + Sync`. Under this feature, all Rhai types, including [`Engine`], [`Scope`] and [`AST`], are all `Send + Sync` |
| `no_optimize` | no | disables [script optimization] |
@ -22,13 +22,13 @@ more control over what a script can (or cannot) do.
| `only_i64` | no | sets the system integer type to `i64` and disable all other integer types. `INT` is set to `i64` |
| `no_index` | no | disables [arrays] and indexing features |
| `no_object` | no | disables support for [custom types] and [object maps] |
| `no_function` | no | disables script-defined [functions] |
| `no_function` | no | disables script-defined [functions] (implies `no_closure`) |
| `no_module` | no | disables loading external [modules] |
| `no_closure` | no | disables [capturing][automatic currying] external variables in [anonymous functions] to simulate _closures_, or [capturing the calling scope]({{rootUrl}}/language/fn-capture.md) in function calls |
| `no_std` | no | builds for `no-std` (implies `no_closure`). Notice that additional dependencies will be pulled in to replace `std` features |
| `serde` | yes | enables serialization/deserialization via `serde` (requires the [`serde`](https://crates.io/crates/serde) crate) |
| `unicode-xid-ident` | no | allows [Unicode Standard Annex #31](http://www.unicode.org/reports/tr31/) as identifiers |
| `metadata` | yes | enables exporting functions metadata to JSON format (requires the [`serde`](https://crates.io/crates/serde) and [`serde_json`](https://crates.io/crates/serde_json) crates) |
| `metadata` | yes | enables exporting [functions metadata] to [JSON format]({{rootUrl}}/engine/metadata/export_to_json.md) (implies `serde` and additionally requires the [`serde_json`](https://crates.io/crates/serde_json) crate) |
| `internals` | yes | exposes internal data structures (e.g. [`AST`] nodes). Beware that Rhai internals are volatile and may change from version to version |

53
src/serde_impl/metadata.rs
View File

@ -1,4 +1,5 @@
use crate::stdlib::{
cmp::Ordering,
collections::BTreeMap,
string::{String, ToString},
vec,
@ -46,7 +47,7 @@ impl From<crate::FnAccess> for FnAccess {
}
}
#[derive(Debug, Clone, Eq, PartialEq, Hash, Serialize, Deserialize)]
#[derive(Debug, Clone, Eq, PartialEq, Ord, Hash, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
struct FnParam {
pub name: String,
@ -54,6 +55,26 @@ struct FnParam {
pub typ: Option<String>,
}
impl PartialOrd for FnParam {
fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
Some(match self.name.partial_cmp(&other.name).unwrap() {
Ordering::Less => Ordering::Less,
Ordering::Greater => Ordering::Greater,
Ordering::Equal => match (self.typ.is_none(), other.typ.is_none()) {
(true, true) => Ordering::Equal,
(true, false) => Ordering::Greater,
(false, true) => Ordering::Less,
(false, false) => self
.typ
.as_ref()
.unwrap()
.partial_cmp(other.typ.as_ref().unwrap())
.unwrap(),
},
})
}
}
#[derive(Debug, Clone, Eq, PartialEq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
struct FnMetadata {
@ -67,10 +88,31 @@ struct FnMetadata {
pub params: Vec<FnParam>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub return_type: Option<String>,
pub signature: String,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub doc_comments: Option<Vec<String>>,
}
impl PartialOrd for FnMetadata {
fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
Some(match self.name.partial_cmp(&other.name).unwrap() {
Ordering::Less => Ordering::Less,
Ordering::Greater => Ordering::Greater,
Ordering::Equal => match self.num_params.partial_cmp(&other.num_params).unwrap() {
Ordering::Less => Ordering::Less,
Ordering::Greater => Ordering::Greater,
Ordering::Equal => self.params.partial_cmp(&other.params).unwrap(),
},
})
}
}
impl Ord for FnMetadata {
fn cmp(&self, other: &Self) -> Ordering {
self.partial_cmp(other).unwrap()
}
}
impl From<&crate::module::FuncInfo> for FnMetadata {
fn from(info: &crate::module::FuncInfo) -> Self {
Self {
@ -108,6 +150,7 @@ impl From<&crate::module::FuncInfo> for FnMetadata {
} else {
None
},
signature: info.gen_signature(),
doc_comments: if info.func.is_script() {
Some(info.func.get_fn_def().comments.clone())
} else {
@ -134,6 +177,7 @@ impl From<crate::ScriptFnMetadata<'_>> for FnMetadata {
})
.collect(),
return_type: Some("Dynamic".to_string()),
signature: info.to_string(),
doc_comments: if info.comments.is_empty() {
None
} else {
@ -154,12 +198,15 @@ struct ModuleMetadata {
impl From<&crate::Module> for ModuleMetadata {
fn from(module: &crate::Module) -> Self {
let mut functions: Vec<_> = module.iter_fn().map(|f| f.into()).collect();
functions.sort();
Self {
modules: module
.iter_sub_modules()
.map(|(name, m)| (name.to_string(), m.as_ref().into()))
.collect(),
functions: module.iter_fn().map(|f| f.into()).collect(),
functions,
}
}
}
@ -203,6 +250,8 @@ impl Engine {
.for_each(|info| global.functions.push(info));
}
global.functions.sort();
serde_json::to_string_pretty(&global)
}
}