Crate ad_astra

Expand description

§Ad Astra API Documentation

Ad Astra is a configurable scripting language platform designed for embedding in Rust applications.

This documentation provides formal API descriptions. For a general exploration of the Ad Astra language and API usage, please refer to The Ad Astra Book.

Getting started examples are available in the GitHub repository.

§Requirements

§Desktop Builds

For desktop builds of the script engine, the engine uses link sections to export introspection metadata of the exported Rust code into the script environment.

This currently only works with the LLD linker, which is the default in stable Rust releases but optional in unstable releases. For the unstable Rust compiler, you need to reconfigure the linker manually.

One way to configure the linker is to add the following configuration to the .cargo/config.toml file of your Rust project:

[target.x86_64-unknown-linux-gnu]
rustflags=["-Zlinker-features=-lld"]
rustdocflags=["-Zlinker-features=-lld"]

§WebAssembly Builds

The Ad Astra crate supports the WebAssembly build target, but the linker is not available for wasm32-unknown-unknown builds. To work around this issue, the exporting system generates “hidden” registration functions that start with the __ADASTRA_EXPORT_ prefix.

You need to manually call these functions before using the loaded wasm module in JavaScript:

// Loading a WebAssembly file.
const assembly = fetch('./wasm.wasm');

// Compiling the file in the browser.
WebAssembly.instantiateStreaming(assembly, IMPORTS).then(({instance}) => {
    // Calling each module-exported function that starts with the special
    // `__ADASTRA_EXPORT_` prefix.
    //
    // These functions are generated by the Export macro.
    // By invoking them manually, you register the corresponding item's
    // introspection metadata in the Ad Astra script engine's export registry.
    for (const property in instance.exports) {
        if (property.startsWith('__ADASTRA_EXPORT_')) {
            instance.exports[property]();
        }
    }

    // The module is now ready for use.
});

§Feature Flags

export flag: Enabled by default. Disabling this flag prevents the generation of output code by the #[export] attribute macro.
shallow flag: Disabled by default. When both the export and shallow features are enabled, the #[export] macro generates the necessary traits with dummy implementations. This mode is used for API development purposes when you don’t need to run the script engine, as the Rust compiler processes the source code much faster with dummy implementations.
lsp flag: Enabled by default. When this feature is disabled, the server module of this crate is not available.

§Quick Links

§Copyright

This work is proprietary software with source-available code.

To copy, use, distribute, or contribute to this work, you must agree to the terms and conditions of the General License Agreement.

For an explanation of the licensing terms, see the F.A.Q.

Re-exports§

pub use lady_deirdre;

Modules§

analysis: Creation, editing, and incremental analysis of script modules.
format: Scripts formatting and printing to the terminal.
interpret: Ad Astra Virtual Machine.
runtime: Building blocks of the script evaluation runtime.
server: Built-in language server for code editors that support the LSP protocol.

Macros§

type_family: A macro that declares new type families.

Attribute Macros§

export: Exports Rust code to the Script Runtime.

Crate ad_astraCopy item path