yulang-runtime-refine 0.1.0

Runtime type refinement, validation, invariant checks, and hygiene printing for Yulang.
Documentation

Yulang

Yulang is an experimental programming language that makes algebraic effects and handlers feel like ordinary control flow.

The surface looks like a small expression-oriented scripting language: it has method syntax, compact block notation, structs, enums, roles, user-defined operators, loops, early return, and references. The unusual part is that many features usually fixed in the core language are expressed through effects, handlers, roles, and standard-library code.

Yulang is alpha-stage research software. The VM, playground, standard library, and language server are usable enough to try real examples, but syntax, type display, effect semantics, runtime IR, and library APIs may still change.

Japanese: README.ja.md

Try It

The fastest way to try Yulang is the browser playground:

https://yulang.momota.pw

To use the CLI locally, install the binary and the embedded standard library:

cargo install yulang
yulang install std

Run a file:

yulang run examples/06_undet_once.yu

The smallest complete program prints a user-facing string with say:

say "Hello, World"

run executes the program through the Yulang VM and only prints output produced by the program itself, such as say / println. To inspect root expression values while experimenting, add --print-roots. To run through the reference interpreter instead of the VM, pass --interpreter.

Check a file and print inferred public types:

yulang check examples/08_types.yu

The standard library is normally installed to ~/.yulang/lib/yulang-0.1.3/std. yulang run, yulang check, and yulang server can also install the embedded standard library automatically on first use when neither YULANG_STD nor a nearby lib/std is available.

To use a different standard-library checkout:

export YULANG_STD=/path/to/yulang/lib/std

Parser-combinator helpers and parser-sugar syntax such as rule { ... } and ~"..." are experimental. They are useful for trying the direction of the language, but their public API and diagnostics are not a compatibility promise.

A First Look

// nondeterministic search: every Pythagorean triple under 15
{
    my a = each 1..15
    my b = each a..15
    my c = each b..15
    guard: a * a + b * b == c * c
    (a, b, c)
}.list  // => [(3, 4, 5), (5, 12, 13), (6, 8, 10), (9, 12, 15)]

each returns a nondeterministic value, guard: prunes branches where the condition fails, and .list reifies the search into a concrete list. The block is an ordinary expression with the undet effect; nothing in this syntax is special-cased.

The same shape lifts over comparisons:

// junction lifts a comparison over many choices at once
if all [1, 2, 3] < any [3, 4, 5]:
    "every left dominated"
else:
    "no"

all and any are library functions that produce nondeterministic values. Lowering inserts junction::junction so the surrounding if receives a real bool after every left/right pair has been considered.

Mutable state, early return, loops, and effectful conditions use the same basic idea: familiar notation on the surface, typed effects and small library abstractions underneath.

Where To Read Next

Good first examples:

  • examples/showcase.yu: broad syntax and library tour.
  • examples/06_undet_once.yu: nondeterminism through library effects.
  • examples/10_effect_handler.yu: algebraic effect handlers.
  • examples/04_sub_return.yu: local early return through sub:.
  • examples/11_attached_impl.yu: attached role implementations.

Language Server

Start the language server with:

yulang server

Current language-server support includes:

  • hover for inferred values, locals, methods, and many type references;
  • semantic tokens;
  • document symbols;
  • parser, lowering, and type diagnostics;
  • relatedInformation on many type errors.

Zed support lives in yulang-zed/. The extension is not published through the Zed extension registry yet; install it as a dev extension and select the yulang-zed directory. When a yulang binary is available in the worktree environment or in ~/.cargo/bin, the extension starts yulang server automatically.

The old yulang-ls binary is a deprecated stub that delegates to yulang server.

Execution Backend

Yulang currently executes through a bytecode VM built on the runtime IR. An earlier Cranelift/MMTk native backend was explored but did not reach the performance bar set by the VM and has been retired; the CLI no longer exposes yulang run --native or yulang native.

Background notes on the experiment and the optimizer plans that grew out of it still live in:

Development

Run representative Rust test suites:

cargo test -p yulang-infer -p yulang-monomorphize --lib

Build the playground locally:

cd web/playground
npm ci
npm run build

Run an inline Yulang program:

yulang run --print-roots <<'YU'
(each [1, 2, 3] + each [4, 5, 6]).once
YU

Repository Layout

  • crates/yulang: CLI and language-server entry point.
  • crates/yulang-parser: parser and syntax tree support.
  • crates/yulang-sources: source sets, realms, compilation units, and syntax artifacts.
  • crates/yulang-typed-ir: typed intermediate representation and principal-type evidence.
  • crates/yulang-infer: type inference and principal-type export.
  • crates/yulang-runtime-ir: execution-facing runtime IR data structures.
  • crates/yulang-runtime-types: runtime type representation and type-system helpers.
  • crates/yulang-runtime-refine: refine, validate, invariant, and hygiene passes over runtime IR.
  • crates/yulang-runtime-lower: typed IR → runtime IR lowering.
  • crates/yulang-monomorphize: graph-based monomorphization and runtime finalization.
  • crates/yulang-vm: VM compilation and evaluation.
  • crates/yulang-compile: source-level compilation glue tying the frontend and runtime together.
  • crates/yulang-editor: editor and language-server support utilities (semantic tokens, etc.).
  • crates/yulang-lsp: deprecated yulang-ls stub that delegates to yulang server.
  • crates/yulang-wasm: WebAssembly API used by the playground.
  • examples: executable examples for the current language implementation.
  • lib/std: standard library written in Yulang.
  • web/playground: Vite-based browser playground.
  • web/docs: reference documentation.
  • notes: bug, refactor, and progress notes.

Status

Yulang is pre-release research software. Syntax, type output, runtime IR, the VM, and the standard library may change without compatibility promises. docs/status.md describes the current support matrix.

License

Licensed under either of:

at your option.