Crate stav 

Stav, a statically typed, eager and total configuration language.

A Stav program is a set of .stav files written in block syntax. This crate is the whole language: it parses, formats, type checks and evaluates programs, merges the contributions of every file by priority, and turns the result into a Value that renders to JSON, TOML or YAML or converts to Rust types through serde.

Evaluation always terminates, reads nothing except the files the host serves, and gives the same value for the same inputs. The whole program is type checked before any of it is evaluated. The crate performs no I/O of its own.

Embedding

A Host is what the embedding program contributes: a Loader that serves source files, and optionally a prelude, standard modules, symbol types and host modules. A RootSpec names the root struct, the entry files and the import roots. check loads and type checks the program, Checked::eval evaluates it into an Evaluated value, and Evaluated::get converts an attribute into any type that implements serde::Deserialize. Every failure is reported as Diagnostics.

use serde::Deserialize;
use stav::{AttrPath, Format, Host, ImportRoot, Limits, MemoryLoader, RootSpec};

#[derive(Deserialize)]
struct Server {
    name: String,
    port: u16,
}

let source = "struct Server {\n  name: Str\n  port: Int where 1..=65535 = 80\n}\n\
              struct Root { server: Server }\n\
              server { name = \"web\", port = 8080 }\n";
let host = Host::new(MemoryLoader::new().with_file("app/main.stav", source));
let root = RootSpec {
    root_struct: "Root".to_owned(),
    entries: vec!["app/main.stav".into()],
    import_roots: vec![ImportRoot::new("app")],
};
let evaluated = stav::check(&host, &root)?.eval(&Limits::default())?;

let server: Server = evaluated.get(&AttrPath::new(["server"]))?;
assert_eq!((server.name.as_str(), server.port), ("web", 8080));
assert_eq!(
    evaluated.render(Format::Toml)?,
    "[server]\nname = \"web\"\nport = 8080\n"
);

Other entry points

lex splits source text into tokens, parse builds a lossless SyntaxTree with a typed view in ast, and format() lays source text out in its canonical form.

Modules

ast

A typed view of the syntax tree.

Structs

AttrPath

A path to an attribute of a value: struct field names, map keys and variant names, from the root down.

AttrPathError

Why a text is not the Display form of an AttrPath. Its Display form says what is wrong.

Checked

A program that passed every check, ready to be evaluated.

ConvertError

Why a value could not be converted to a Rust type.

Diagnostic

An error or a warning found in source text.

Diagnostics

The diagnostics of a program, in the order they were found, with the names and texts of the files they refer to.

Evaluated

The result of evaluating a checked program: the merged value of the root struct, and where each of its attributes came from.

FileDiagnostic

A Diagnostic together with the file it is about.

FileId

Identifies one file of a checked program.

Host

Everything a host program contributes to the checking of a root.

HostModule

A module whose source the host supplies for one evaluation, imported as "<namespace>/<module>".

ImplicitRefs

Labels that a host lets references to a struct name, in addition to the labels of the struct’s target map.

ImportRoot

A directory that the files of a root may reference.

Label

A secondary location that a Diagnostic points at, for example the other end of a dependency cycle.

Lexed

The tokens and lexical errors of one source text.

Limits

Limits on the work and the memory one evaluation may use.

MemoryLoader

A Loader that serves files and standard modules from memory.

Parsed

The syntax tree and all errors of one source text.

RelPath

A normalized path inside an import root, such as lib/net.stav.

RenderError

Why a value cannot be rendered in a format.

RootSpec

What to check: the root struct, the entry files and the import roots.

SchemaField

A field of a struct or a payload field of a variant.

SchemaIndex

Every struct and sum type a checked program declares, with the doc comments of the declarations, their fields and their variants.

SchemaStruct

A declared struct.

SchemaSum

A declared sum type.

SchemaVariant

A variant of a sum type.

Source

A source text the host passes in directly, such as a prelude file.

SourceSpan

A span in a particular file of a checked program.

Span

A half-open byte range start..end into a source text.

SymbolType

A domain type whose values the host validates after evaluation, such as a package reference.

SyntaxNode

A node of a SyntaxTree: a grammar construct and its children.

SyntaxToken

A token of a SyntaxTree.

SyntaxTree

A lossless syntax tree of one source text.

Token

One token of source text: its kind and the exact bytes it covers.

Enums

Format

A text format that values render to.

LoadError

Why a Loader could not read a file.

NodeKind

The kind of a SyntaxNode.

Severity

How serious a Diagnostic is.

SyntaxElement

A child of a SyntaxNode: either a node or a token.

TokenKind

The kind of a Token.

Value

A value of a Stav program, as an evaluated program produces it.

Constants

MAX_DEPTH

The deepest nesting the parser accepts. Each nested expression, statement, type or pattern is a level, and so is each operator of a chain such as a + b + c or a.b.c, because each one nests the tree one level deeper.

MAX_SOURCE_LEN

The largest source file the checker accepts, in bytes. A larger file is reported as E0706.

Traits

Loader

Reads source files for the checker.

Functions

check

Loads and type checks the root root of host.

format

Formats source into the canonical layout.

lex

Splits source into tokens.

parse

Parses source into a lossless syntax tree.