mimas/lib.rs
1//! mimas is a statically typed, embeddable scripting language for Rust.
2//!
3//! This crate is the front door for host programs: it re-exports the pieces of the pipeline you
4//! need and bundles the standard library, so embedding is two lines.
5//!
6//! ```
7//! let mut vm = mimas::compile_source(r#"print("hello from mimas");"#).unwrap();
8//! vm.run().unwrap();
9//! ```
10//!
11//! # Sharing Rust with a script
12//!
13//! Tag an item with [`macro@mimas`] and the script can see it, type-checked like anything native.
14//! Structs, enums, free functions, and `impl` blocks all work -- note that an `impl` needs the
15//! attribute too, not just the type it belongs to.
16//!
17//! ```
18//! use mimas::mimas;
19//!
20//! #[mimas]
21//! struct User(String);
22//!
23//! #[mimas]
24//! impl User {
25//! fn greet(self) -> String {
26//! format!("Hello, {}!", self.0)
27//! }
28//! }
29//!
30//! let mut vm = mimas::compile_source(r#"print(User("mimas").greet());"#).unwrap();
31//! vm.run().unwrap();
32//! ```
33//!
34//! Multi-file projects go through [`compile_files`]. For host state, runtime errors, and the rest
35//! of the embedding surface, see the [Extension with Rust](https://mim.as/extension-with-rust.html)
36//! guide.
37//!
38//! # Bevy
39//!
40//! The `bevy` feature adds [`bevy`], a plugin for running mimas scripts in a Bevy app.
41
42pub use library;
43pub use vm;
44
45#[cfg(feature = "bevy")]
46pub use mimas_bevy as bevy;
47
48pub use macros::{MimasEnum, MimasStruct, mimas, native};
49
50pub use shared::{Literal, Ty};
51pub use vm::{Ctx, Val, Vm, api::Api};
52
53/// A host run from its cargo target dir already writes `target/mimas/<binary>.json`. Call this
54/// to put the manifest somewhere else, like a copy committed for modders.
55///
56/// ```no_run
57/// let library = mimas::Vm::new().install_library(mimas::library::std);
58/// mimas::write_api(&library, "scripts/api.json".as_ref())?;
59/// # Ok::<(), std::io::Error>(())
60/// ```
61#[cfg(feature = "export-api")]
62pub use vm::write_api;
63
64/// Compiles the given source with mimas's std included.
65pub fn compile_source(source: &str) -> Result<vm::Vm, vm::ExecuteError> {
66 vm::Vm::compile(source, library::std)
67}
68
69/// Compiles the given files with mimas's std included. Files should be passed in within a tuple
70/// first containing their name then followed by their source.
71pub fn compile_files(files: &[(&str, &str)]) -> Result<vm::Vm, vm::ExecuteError> {
72 vm::Vm::compile_files(files, library::std)
73}