Struct ScriptFn 

pub struct ScriptFn {
    pub name: String,
    pub ns: ScriptNs,
    pub sig: ScriptSig,
    pub body: ScriptFnBody,
}

One native function, in terms every script host understands.

Fields

name: String

The name the script calls it by.

ns: ScriptNs

The namespace it lives in.

sig: ScriptSig

Its declared signature.

body: ScriptFnBody

The function body.

Implementations

impl ScriptFn

pub fn new(name: impl Into<String>) -> ScriptFnBuilder

Start a typed description.

use lumen_script::{ScriptFn, ScriptTy, ScriptValue};

let f = ScriptFn::new("set_pin")
    .param("pin", ScriptTy::Int)
    .ret(ScriptTy::Bool)
    .doc("Drive a GPIO pin high.")
    .build(|cx| Ok(ScriptValue::Bool(cx.int_arg(0) > 0)));
assert_eq!(f.sig.params.len(), 1);

ScriptFn::from_fn takes a plain Rust closure instead and reads the signature off its types; the builder is for a function that also wants a doc line, optional arguments, or the command sink.

pub fn value<F>(name: impl Into<String>, arity: usize, f: F) -> Self

where F: Fn(&[ScriptValue]) -> ScriptValue + Send + Sync + 'static,

Describe an untyped, value-returning function of arity arguments: the shape the C ABI’s lumen_app_expose and the Rust SDK’s native_fn produce. Lands in ScriptNs::Extension.

pub fn from_fn<Marker, F>(name: impl Into<String>, f: F) -> Self

where F: IntoScriptFn<Marker>,

Describe a function from a plain Rust closure, reading its signature off the argument and return types.

This is the short form: no builder, no ScriptTy spelled out. Each parameter type maps onto the declared type a host binds it as, so |pin: i64, high: bool| declares (int, bool) and a call passing anything else fails at the call site. A closure returning Result<T, String> may fail, and the message reaches the script.

Parameters are named arg0, arg1, … unless param_names renames them.

use lumen_script::{ScriptFn, ScriptTy};

let f = ScriptFn::from_fn("gpio_read", |pin: i64| -> Result<bool, String> {
    if pin < 0 {
        return Err(format!("pin {pin} is out of range"));
    }
    Ok(pin % 2 == 0)
})
.param_names(["pin"]);

assert_eq!(f.sig.params[0].ty, ScriptTy::Int);
assert_eq!(f.sig.ret, ScriptTy::Bool);

pub fn param_names<N: Into<String>>( self, names: impl IntoIterator<Item = N>, ) -> Self

Rename the parameters, in order. Names past the declared arity are ignored, and a parameter the list does not reach keeps argN.

Only docs and diagnostics read these, so a function built with ScriptFn::from_fn works without them; they are what makes an editor’s signature hint and a type-mismatch message readable.

pub fn commands<F>(name: impl Into<String>, arity: usize, f: F) -> Self

where F: Fn(&mut ScriptFnCx<'_>) + Send + Sync + 'static,

Describe an untyped function of arity arguments whose whole effect is the commands it emits. Returns ScriptValue::Unit to the script.

pub fn with_ns(self, ns: ScriptNs) -> Self

Move it into another namespace.

pub fn with_min_arity(self, min_arity: usize) -> Self

Accept fewer arguments than the signature declares; the trailing parameters become optional.

pub fn invoke_into( &self, args: &[ScriptValue], out: &mut Vec<ScriptCommand>, ) -> ScriptResult

Run the body over args, appending whatever it emitted to out.

Every host adapter goes through here, so a body observes the same argument slice and the same command scratch whichever language called it. out is the caller’s buffer rather than a fresh one, so a host that reuses CallScratch pays no allocation per call.

A struct argument reaches the body with every field present: the ones the script left out take their defaults here, so a Rhai or Lua map that sets one key reads the same as a full candela struct.

A body that fails still leaves what it emitted before failing: a host forwards those commands and then raises, which is what the runtime has always done with a partially-completed call.

A call to a builtin whose subsystem the engine was linked without warns once (see crate::unlinked) and then runs as it always does.

Errors

Whatever the body reported, verbatim.

pub fn invoke(&self, args: &[ScriptValue]) -> (ScriptResult, Vec<ScriptCommand>)

Run the body over args, returning its result and whatever it emitted.

The allocating convenience over Self::invoke_into, for a caller with no scratch of its own.

Trait Implementations

impl Clone for ScriptFn

fn clone(&self) -> ScriptFn

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ScriptFn

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.