Scorium

Readable on the surface. Programmable when you need it.

Scorium is a readable, programmable configuration framework. It keeps ordinary configuration declarative while allowing Lua-powered expressions, conditions, loops, and functions when static data is not enough.

Simple configuration for beginners. Programmable configuration for advanced users.

@base_port = 8000

server {
    host = localhost
    port = base_port + 80
    timeout = 5s
    enabled = true
}

for i = 1, 3 do
    worker {
        name = worker-$i
        index = i
    }
end

A beginner writes ordinary data and never touches the programmable layer. An advanced user adds logic without migrating to another file format.

---

Why Scorium?

Most configuration formats are easy to read but become repetitive as they grow. Pure scripting languages remove repetition, but force every user to write code. Scorium is the middle that does not force the choice: a file reads like data, and the moment you need a loop, a conditional, a function, or a raw Lua block, the language is already there.

• Readable on the surface. Nodes, key = value leaves, @name = value variables, $name references in bare strings, quoted strings that mean what they say. A config file is readable by someone who has never seen the language.
• Programmable when needed. if, for, while, fn, include, and script { } blocks with raw Lua. Loops generate repeated structure. Conditionals branch on values. Functions encode your conventions once.
• Typed values. Colors and durations are real values, not strings: #8EDDFF carries RGBA channels, so primary.darken(0.35) derives a palette from one line; 600ms is a duration, not text.
• Validation with suggestions. A schema is the set of nodes and keys your application accepts. Unknown keys and wrong types fail with precise spans and typo suggestions, instead of silently becoming strings.
• Sandboxed by design. Evaluation runs against a restricted Lua state (math, string, table only) with bounded loops and instruction budgets. No io, no os, no network, no processes -- unless the host explicitly grants them.
• Canonical formatting. scorium fmt renders canonical output straight from the syntax tree, idempotent by construction.
• Embeddable. The runtime is a Rust library: lexer, parser, AST, evaluator, schema, formatter. Your application defines the host functions and the schema; Scorium does the rest.

How it differs from JSON, YAML, TOML, and raw Lua

JSON is suitable for machine interchange. Scorium is designed for human-written application configuration -- it is not trying to replace JSON as a serialization format.

	JSON	YAML	TOML	Raw Lua	Scorium
Human-readable config	verbose	yes	yes	verbose	yes
Typed literals (color, duration)	no	no	no	no	yes
Logic when needed	no	anchors only	no	always	opt-in
Beginners write pure data	n/a	yes	yes	no	yes
Sandboxed	n/a	n/a	n/a	no	yes
Schema + typo suggestions	external	external	no	no	built-in

A first file

server {
    port = 8080
    timeout = 5s
    enabled = true
}

A more advanced one, using a variable, interpolation, an expression, a condition, and a function:

@mod = SUPER
@base = 8

binding = $mod+Return
gaps = base * 2

theme {
    primary = #8EDDFF
    deep = primary.darken(0.35)
}

if gpu == nvidia then
    driver {
        overlay_planes = false
    }
end

fn service(name, port) {
    server {
        id = $name
        port = port
    }
}
service(web, 8080)

Three rules cover variables almost completely:

Where	Form	Meaning
Definition	@name = value	Defines a variable. @ appears only here.
In a bare string	$name	Interpolates the value into the string.
In an expression	name	References the typed value.

Read the language guide for the rest.

Install and use

Install the CLI from the official crates.io release:

cargo install scorium-cli
scorium check examples/basic.scor

Or, to embed the libraries in your own project:

cargo add scorium-core scorium-lua scorium-schema

Or build from source:

cargo build -p scorium-cli
# then, from the repository root:
cargo run -p scorium-cli -- check examples/basic.scor
cargo run -p scorium-cli -- fmt --check examples/basic.scor
cargo run -p scorium-cli -- parse examples/variables.scor
cargo run -p scorium-cli -- eval examples/conditions.scor

Only @fi3w0 publishes official Scorium releases; see Licensing.

Command	Does
scorium check file.scor	Parse + evaluate; report diagnostics.
scorium parse file.scor	Print the parsed syntax tree.
scorium fmt file.scor	Format a file in place.
scorium fmt --check file.scor	Exit non-zero if a file isn't formatted.
scorium eval file.scor	Print the evaluated configuration tree.

check and eval run against a generic runtime: control flow, variables, arithmetic, includes, and script { } all work without a host, but host-registered functions and schema validation require an embedding application. See the embedding example.

Embed it

Scorium is a Rust workspace of focused crates:

Crate	What it is
scorium-core	Lexer, parser, AST, typed values, spans, diagnostics.
scorium-lua	Sandboxed evaluator, control flow, includes, host registry.
scorium-schema	Schema builder, validation, typo suggestions, custom types.
scorium-format	Canonical formatter.
scorium-cli	The scorium command-line tool.

A complete embedding -- parse, evaluate against a host runtime, validate against a schema, inspect -- is in examples/embedding/:

use scorium_core::{parse, Source, Value};
use scorium_lua::{Runtime, RuntimeOptions};
use scorium_schema::{NodeSchema, Schema, ValueType};

// 1. parse, 2. evaluate with registered host value + function,
// 3. validate against a schema, 4. inspect.

Run it with cargo run -p scorium-embedding-example. Full API documentation is in docs/EMBEDDING.md.

Status

The language core, the sandboxed evaluator, the schema validator, the canonical formatter, and the CLI are implemented and tested. This is a real, compiling, embeddable foundation, but it is pre-1.0 and the public API may change. See docs/ROADMAP.md for what is planned and what is deferred.

Documentation

• Language guide -- start here.
• Grammar -- the implemented grammar.
• Embedding -- the Rust API for hosts.
• Diagnostics -- the diagnostic catalogue.
• Security model -- the sandbox and host responsibility.
• Roadmap -- what exists and what is deferred.

Security

script { } blocks run against a restricted Lua state (math, string, table only). There is no io, os, package, debug, process spawning, filesystem access, or networking. Loops and Lua instructions are bounded. See docs/SECURITY.md and report vulnerabilities privately as described in SECURITY.md.

Licensing

Scorium is source-available under the PolyForm Strict License 1.0.0. It is free for personal, educational, hobby, and local noncommercial use, and for contribution-focused forks. Commercial use requires a written agreement.

Scorium is not OSI-approved open source. Only official releases published by @fi3w0 (crates.io, GitHub Releases) are sanctioned distribution channels; see docs/LICENSING.md, COMMERCIAL.md, and TRADEMARKS.md.

The legal files are initial project terms that have not been reviewed by a lawyer. Obtain professional legal review before relying on them for commercial use.

Contributing

Contributions are welcome. Read CONTRIBUTING.md, CONTRIBUTION_PERMISSION.md, and CONTRIBUTOR_TERMS.md before opening a pull request.