Chapter 10: Complete Reference to Features

The design principle of SML is “from minimalism to richness, with customizable functions” - the basic nine piece set is enabled by default; Complex abilities are disabled by default and can be explicitly enabled using @feature enable when needed.

This chapter is an authoritative reference for each feature: opening methods, syntax, error messages, and relationships with other features.

⚠️ Scope of this chapter (added after measurement, 2026-09-19): the @feature enable/disable gating mechanism itself currently exists only on Rust (reference implementation) and JS — C / C++ / Lua treat @feature … as an illegal directive (E-PARSE-005, measured; their legal directives are only contract / is / version), so their capability set is fixed. Individual features are also unevenly implemented (e.g. typed-block is Rust + JS only); see the table below and the audit table in §5.2.2. In documents shared across implementations, use forms all five understand (such as @is) and do not rely on @feature.

Implementation coverage (measured on real binaries, 2026-09-19)

Every cell is a behaviour obtained by running real binaries (Rust smltools, the C dumper, a purpose-built C++ runner, luajit, JS parseSafe) — not a guess from reading source. ? means not measured this round (it does not mean “unsupported”).

※ JS resolves include from a host-supplied file map: parse(text, { files }) — JS itself never touches the filesystem (designed for editors / servers; files is { "relative/path": "content" }). Without files you get E-INCLUDE-001. ⚑ glob-include / regex-include status on both ends (measured 2026-09-19): ① the JS side now has both (it used to report E-INCLUDE-001 for glob and E-LEX-004 for re:"…"); ② built from the current source, Rust and JS now agree on the same 15 inputs (directory prefixes, anchors, error codes, zero-hit cases); ③ there is an older record of “Rust’s release binary did not expand glob” (os error 123) — if the binary you have still behaves that way it is simply older than the source (the glob branch has been there all along); rebuild it; ④ Rust’s regex-include had a Windows-only defect: a \. in the pattern was treated as a path separator (re:"widget_.*\.sml" was split into dir=widget_.* ⇒ “directory read failed”) — fixed (the split now uses SML’s /); ⑤ JS’s re: is the same restricted subset: groups (), alternation |, {n,m} and \d are treated as literal characters on both ends (the engine only has . [...] * + ? ^ $). (preserved note about the release binary follows)

⚑ Rust’s glob-include did not expand in that older round (the literal path inc/*.sml was opened ⇒ os error 123), although the source does contain a glob branch (rust/sml-include/src/parse.rs:367-377) ⇒ the release binary in use is suspected to be out of sync with the sources (needs a rebuild + re-measure). ⚠️ Lua’s for needs re-checking: it “accepted” @for without the feature while rejecting @feature — confirm whether it really expands or just swallows the token as an ordinary key.

Three conclusions for anyone writing docs:

1. @when / @for exist only in Rust today (the other four all return E-PARSE-005) — do not put them in examples that claim to be cross-implementation.
2. top-level-array is Rust + C only; namespace / multi-include are missing only in Lua (and Lua fails loudly with a code, not silently).
3. C / C++ / Lua have no @feature (E-PARSE-005), so “trim capabilities with @feature” simply does not apply to them; they support namespace / multi-include etc. unconditionally.

Lexical-level differences (measured 2026-09-19, again from real binaries)

The same round swept lexical units too (20 cases × 5 implementations; the verdict for each case is “did the case’s key x survive”, which is what catches silent data corruption — “does it parse at all” cannot see it):

How the BOM was fixed (one place per implementation, all treated as file-level normalisation): Rust in sml-parse::scan::strip_version (the single funnel of every text entry) plus sml-include::expand_file_tokens (child files); JS in parse(); C in sml_parse plus the child-file read in resolve_includes; C++ in Parser::parse plus the include child-file read; Lua in Sml.load plus the include child-file read. Each implementation gained a test that asserts the key is still x — asserting “it parses” would not catch this (without the fix it still “parses fine”). ⚠️ Worth noting: smltools’ YAML / XML importers already stripped the BOM (yaml.rs:93, xml.rs:63); only the native SML path was missing it — the same job treated two ways.

10.1 How to turn on/off features

At the beginning of the file, use the @feature command:

@version v1
@feature enable glob regex
@feature disable ext-rewrite

-enable name list: separated by spaces.

-disable name list: Same as above.

-It can appear multiple times and take effect by overlapping in the order of appearance.

-Write after @version and before other content.

After activation, the corresponding capabilities can be used within this file (or included subfiles); Different files can be declared independently.

10.2 Built in feature list

include (default enabled)

The most basic “file insertion” ability.

Error codes: include.circular, include.depth-exceeded, include.not-found.

namespace (default enabled)

as namespace, pointwise path, macro/contract isolation.

Error codes: ns.invalid-path, ns.duplicate-symbol, ns.unresolved-prefix.

implicit-ns (default enabled)

include without extension is automatically used as a namespace.

Close it: @feature disable implicit-ns - Afterwards, include "ui" must have an extension.

multi (default off)

Include multiple targets and import aliases at once.

Error codes: multi.dup-name, multi.empty.

glob (default off)

* is compatible with multiple files in the matching directory.

Error code: glob.not-found (if 0 matches) glob.malformed.

regex (default off)

re://.../ prefix triggers regular matching.

Complete regularization features (lookahead, backref) not supported - deliberately kept simple, for complex matching, please use shell universal+glob.

ext-rewrite (default off)

Parse files with any suffix as .sml.

contract (default enabled)

@contract/@is verification and backfilling.

Error codes: contract.required-missing, contract.type-mismatch, contract.enum-invalid, contract.out-of-range, contract.unknown-field, contract.recursive.

env (default enabled)

$env.VAR environment variable injection.

Error code: env.bad-name.

escape (default enabled)

Escaping within a quoted string.

fragment (default enabled)

@name/&name fragment inheritance.

top-array (default enabled)

The top level of the file allows for arrays (not objects).

bareword-str (default enabled)

Naked words are automatically recognized as strings.

when (default off)

Parse-time static conditional pruning: based on $env.*, decide at parse stage whether the next field/block is kept.

@version v1
@feature enable when

@when $env.ENV == "prod"
log_level: warn        # only appears in prod

@when $env.DEBUG       # truthiness: non-empty and not "0"/"false"
verbose: true

Design trade-off: no general expressions (&&/||/()/function calls). Supporting them would require an evaluator plus sandbox, timeout and IO-restriction guards, conflicting with “SML is a pure data format”. Split compound conditions into multiple @when, or generate per-environment files with an external build tool.

for (default off)

Parse-time bounded loop unrolling: substitute each item of the finite list after in into the loop body, producing an array.

@version v1
@feature enable for

hosts: @for h in web api db {
  name: "${h}"
  port: 8080
}
# ⇒ hosts: [ {name:"web",port:8080}, {name:"api",...}, {name:"db",...} ]

Combination trap @when × @for:

• When outer @when is written before the @for field, a false condition means the whole hosts field disappears (not an empty array, the key is deleted) — “@when filters the field, not a single iteration”.
• When @when is written inside the @for body, it applies to the next field within the block and is evaluated per-element. The two semantics differ — keep them straight.

Why no general loops: bounded for ... in enumeration belongs to LOOP (primitive recursive) languages — it cannot compute Ackermann, thus is not Turing-complete; once while/recursion is introduced, sandbox and resource quotas become mandatory, which conflicts with “SML is a pure data format”.

${VAR} is NOT supported in key position: the {/} inside ${VAR} are treated as block boundaries by the lexer, which would split the key and silently produce garbage. Loop-variable interpolation only accepts value position (name: "${h}"); for “dynamic keys”, use an array instead: hosts: @for h in a b c { name: "${h}", ... } and index by name on the consumer side. Writing ${VAR} in a key position raises an explicit error (fail-fast), not garbage.

A complete runnable example is in examples/for_when.sml (@when + @for + nested @for + combination trap, demonstrated in one file).

10.3 Compatibility Matrix

Note 1: The “comma separated” syntax of include "a, b" as y is used together with multi, and a single target in the list cannot contain , (even inside quotation marks - commas inside quotation marks are considered literal).

Note 2: include "re:^.*\\.sml$" has already covered all. sml, there is no need to use include "*.sml" again. Simultaneously using what may be interpreted as “glob priority” or “regex priority” may result in different cross implementation behaviors - SML specifies explicit prefix priority: re: follows regex; *.sml takes the globe.

typed-block (default off; Rust ✅ + JS ✅, C / C++ / Lua ❌)

Block-level type annotation: put the contract name in front of the block name (Metrics metrics { }), equivalent to writing @is Metrics on the block’s first line. No new tokens — it is exactly the same shape as the existing bare-block form type [name] { } and only takes effect when the first word is an already-defined contract name. See §5.2.2.

Block-level annotation also supports multi-contract mixin: put several contract names in front of the block name (HasHost HasPort api { } — from the first word, every consecutive word that hits the contract table is a contract; the first miss is the block name), equivalent to @is HasHost, HasPort inside the block. The single-contract form (Metrics metrics { }) is byte-for-byte unchanged; only ≥ 2 contract words trigger the mixin, and a same-field conflict reports E-CONTRACT-016. See §5.4.1 Mixin.

@feature enable typed-block

⚠️ On C / C++ / Lua the form degrades to a plain bare block (extra __type/__name metadata) — the contract is neither validated nor default-filled, and no error is raised: a silent divergence (measured with C’s dumper).

⚠️⚠️ Even more important: the @feature gating mechanism itself currently exists only on Rust + JS — C / C++ / Lua treat @feature … as an illegal directive and report E-PARSE-005 (“legal directives: contract / is / version”; measured on C, same code path in C++ / Lua). So this chapter’s “trim capabilities with @feature” narrative does not apply to those three (their feature set is fixed). ⇒ In documents shared across implementations prefer @is ContractName and do not rely on @feature.

10.4 Implementation Layer of Features (Architecture Tips)

SML parser runs according to “feature bitmask”:

FeatureSet = (include | namespace | implicit-ns | contract | env | escape
              | fragment | top-array | bareword-str
              | multi | glob | regex | ext-rewrite
              | when | for | typed-block)

-Core layer (default enabled) 9 bits default=1 (all basics except when/for).

-Entering the hierarchy (default off) multi | glob | regex | ext-rewrite | when | for 6 bits default=0.

-The parser directly rejects the corresponding syntax for unopened features (parsing error, not silently skipping).

when/for belong to the “parse-time directive” family, gated by the Rust-side cargo feature when at compile time; the document-level when/for feature switches control whether the syntax is allowed at runtime. Compile-time and runtime are decoupled: even if the cargo feature is off at build time, other features are unaffected.

This is the implementation foundation of ‘customizable functionality, don’t fall into the same path as YAML’.

10.5 Performance and Portability

10.6 Future Features (Roadmap)

The following items are all unimplemented, roadmap previews only; each is annotated with its current substitute / mitigation so readers neither misuse them nor reinvent the wheel:

10.7 Give it a try with your hands

Write an features.sml for your project:

@version v1
@feature enable glob multi
@feature disable ext-rewrite

include "modules/*.sml" as modules
import modules.auth, modules.billing

Use commands such as sml check features.sml (refer to ch07 Multilingual) to run parsing and contract verification.

→ Appendix: Comparison and Investigation

Hands on practice

After reading this chapter, directly modify SML in the editor below and click “Run” to immediately see the parsing results or validation errors - having output is necessary for efficient learning.

@contract Module { name: str }
@is Module
name: auth

@contract Module { name: str }
@is Module
name: billing