The Starlark configuration language, implemented in Moonbit

starlark

interpreter

moon add connect0459/starlark@0.5.0

Download zip

Author

connect0459

Version

0.5.0

License

Apache-2.0

Repository

github.com/connect0459/starlark-mbt

Last updated

4 days ago

Downloads

Dependencies

moonbitlang/x0.4.49

README

#starlark-mbt

A MoonBit implementation of the Starlark scripting language interpreter.

#Packages

Package	Import alias	Description
connect0459/starlark	@starlark	Quick-start entry points: exec (run a script), eval (evaluate an expression); re-exported Value, Module, EvalError
connect0459/starlark/eval	@eval	Entry functions (exec_file, eval_expr, call, source_program, parse_file, …) plus Thread, Module, Options, Program, Predeclared, Universe
connect0459/starlark/value	@value	Value, StringDict, StarlarkDict, StarlarkList, StarlarkString, CustomValue; value helpers (equal, len_of, as_float, …)
connect0459/starlark/unpack	@unpack	unpack_args, unpack_positional, unpack_args_with for host-defined built-ins
connect0459/starlark/errors	@errors	EvalError, SyntaxError, ResolveError, Position, CallStack, …
connect0459/starlark/syntax	@syntax	File, Expr — AST types for parse_file/parse_expr
connect0459/starlark/lib/json	@json	JSON encode / decode extension
connect0459/starlark/lib/math	@math	Math functions extension (mirrors Python's math module)
connect0459/starlark/lib/struct	@struct	struct, module, and gensym extension (starlarkstruct)
connect0459/starlark/lib/time	@time	Time and duration extension (starlarktime)

#Installation

moon add connect0459/starlark

Then declare the packages you need in your moon.pkg (add extension packages as needed):

import {
  "connect0459/starlark",               // exec, eval — quick-start helpers with default thread and options
  "connect0459/starlark/eval",          // exec_file, eval_expr, call, parse_file, Thread, Module, Options, …
  "connect0459/starlark/value",         // Value, StringDict, StarlarkDict, value helpers (equal, len_of, …)
  // "connect0459/starlark/errors",     // EvalError, Position, CallStack, …
  // "connect0459/starlark/syntax",     // File, Expr (parse_file / parse_expr)
  // "connect0459/starlark/unpack",     // unpack_args* for host-defined built-ins
  // optional extensions:
  // "connect0459/starlark/lib/json",
  // "connect0459/starlark/lib/math",
  // "connect0459/starlark/lib/struct",
  // "connect0459/starlark/lib/time",
}

#Usage

#Quick start

The root @starlark package offers zero-ceremony helpers that run with a default thread and the default dialect options:

///|
test {
  // Run a script and read back a module global.
  match @starlark.exec("result = max([i * i for i in range(5)])") {
    Ok(m) => assert_true(m.get("result") is Some(@value.Value::Int(16N)))
    Err(e) => fail(e.msg())
  }
  // Evaluate a single expression.
  match @starlark.eval("1 + 2 * 3") {
    Ok(v) => assert_true(v is @value.Value::Int(7N))
    Err(e) => fail(e.msg())
  }
}

#Full control

For custom threads, options, predeclared bindings, or module loaders, use the @eval package directly:

///|
test {
  let thread = @eval.Thread::new("main")
  let src = "result = max([i * i for i in range(5)])"
  match @eval.exec_file(thread, "example.star", src, @eval.Options::default()) {
    Ok(m) => assert_true(m.get("result") is Some(@value.Value::Int(16N)))
    Err(e) => fail(e.to_string())
  }
}

For full usage examples — print capture, expression evaluation, host bindings, module loading, error handling, extensions, and calling Starlark functions from host code — see the per-package documentation (e.g. eval, value).

#Documentation

Each public package has a README.mbt.md with a key-types overview, usage examples, and a full API reference. Start with eval for the main entry points.

#Compatibility

This is an unofficial MoonBit implementation of Starlark — it is not associated with the Bazel team.

The implementation targets the Starlark specification.

#Contributing

See CONTRIBUTING.md.

#License

Apache-2.0

#
EvalError

source

using @connect0459/starlark/errors { type EvalError }

A runtime evaluation error carrying a message, a call-stack snapshot, and an optional inner cause for load-error chaining.

#
Module

source

using @connect0459/starlark/eval { type Module }

The result of executing a Starlark file: a frozen mapping of global names to their values, plus any injected predeclared bindings.

#
Value

source

using @connect0459/starlark/value { type Value }

The Starlark value sum type. Covers all built-in types plus embedder extensions via ExtVal.

#
eval

source

fn eval(src : String, filename? : String) -> Result[@connect0459/starlark/value.Value
Value, @connect0459/starlark/errors.EvalError
EvalError]

Evaluates a single Starlark expression using a default thread, the default dialect options, and an empty environment, returning its value.

#
exec

source

fn exec(src : String, filename? : String) -> Result[@connect0459/starlark/eval.Module
Module, @connect0459/starlark/errors.EvalError
EvalError]

Executes Starlark source as a module using a default thread and the default dialect options, returning the resulting frozen module.

This is the zero-ceremony entry point; embedders needing custom threads, options, predeclared bindings, or loaders should use the eval package directly.