rhaj/rhai_engine/rhaibook/engine/metadata/export_to_json.md

Export Functions Metadata to JSON

{{#include ../../links.md}}

Engine::gen_fn_metadata_to_json
Engine::gen_fn_metadata_with_ast_to_json

As part of a reflections API, Engine::gen_fn_metadata_to_json and the corresponding Engine::gen_fn_metadata_with_ast_to_json export the full list of [custom types] and [functions metadata] in JSON format.

The [`metadata`] feature is required for this API, which also pulls in the
[`serde_json`](https://crates.io/crates/serde_json) crate.

Sources

Functions and [custom types] from the following sources are included:

1. Script-defined functions in an [AST] (for Engine::gen_fn_metadata_with_ast_to_json)
2. Native Rust functions registered into the global namespace via the Engine::register_XXX API
3. [Custom types] registered into the global namespace via the Engine::register_type_with_name API
4. Public (i.e. non-[private]) functions (native Rust or Rhai scripted) and [custom types] in static modules registered via Engine::register_static_module
5. Native Rust functions and [custom types] in external [packages] registered via Engine::register_global_module
6. Native Rust functions and [custom types] in [built-in packages] (optional)

JSON Schema

The JSON schema used to hold metadata is very simple, containing a nested structure of modules, a list of customTypes and a list of functions.

Module Schema

{
    "doc": "//! Module documentation",

    "modules":
    {
        "sub_module_1": /* namespace 'sub_module_1' */
        {
            "modules":
            {
                "sub_sub_module_A": /* namespace 'sub_module_1::sub_sub_module_A' */
                {
                    "doc": "//! Module documentation can also occur in any sub-module",

                    "customTypes": /* custom types exported in 'sub_module_1::sub_sub_module_A' */
                    [
                        { ... custom type metadata ... },
                        { ... custom type metadata ... },
                        { ... custom type metadata ... }
                        ...
                    ],
                    "functions": /* functions exported in 'sub_module_1::sub_sub_module_A' */
                    [
                        { ... function metadata ... },
                        { ... function metadata ... },
                        { ... function metadata ... },
                        { ... function metadata ... }
                        ...
                    ]
                },
                "sub_sub_module_B": /* namespace 'sub_module_1::sub_sub_module_B' */
                {
                    ...
                }
            }
        },
        "sub_module_2": /* namespace 'sub_module_2' */
        {
            ...
        },
        ...
    },

    "customTypes": /* custom types registered globally */
    [
        { ... custom type metadata ... },
        { ... custom type metadata ... },
        { ... custom type metadata ... },
        ...
    ],

    "functions": /* functions registered globally or in the 'AST' */
    [
        { ... function metadata ... },
        { ... function metadata ... },
        { ... function metadata ... },
        { ... function metadata ... },
        ...
    ]
}

Custom Type Metadata Schema

{
    "typeName": "alloc::string::String",    /* name of Rust type */
    "displayName": "MyType",
    "docComments":  /* omitted if none */
    [
        "/// My super-string type.",
        ...
    ]
}

Function Metadata Schema

{
    "baseHash": 9876543210,     /* partial hash with only number of parameters */
    "fullHash": 1234567890,     /* full hash with actual parameter types */
    "namespace": "internal" | "global",
    "access": "public" | "private",
    "name": "fn_name",
    "isAnonymous": false,
    "type": "native" | "script",
    "numParams": 42,            /* number of parameters */
    "params":                   /* omitted if no parameters */
    [
        { "name": "param_1", "type": "type_1" },
        { "name": "param_2" },  /* no type name */
        { "type": "type_3" },   /* no parameter name */
        ...
    ],
    "thisType": "this_type",    /* omitted if none */
    "returnType": "ret_type",   /* omitted if () or 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 */",
        ...
    ]
}