Crate ratslang

Expand description

§Ratslang

A compact configuration language for physical systems with native support for time and length units.

Ratslang solves the unit conversion problem that plagues physical system configuration, while keeping the implementation simple and declarative. Physical units are stored directly as uom types (Length and Time) for full type-safety and precision.

§Features

Time units: ns, us, ms, s, min, h, d, a (year), shake (and SI prefixes, see Supported Time Units)
Length units: nm, um, mm, cm, m (see Supported Length Units)
Ranges: 1mm..100m, 5s.., ..10m, ..
Namespaces: Dot notation (sensor.range) or blocks
Includes: Compose configuration files with namespace scoping
Annotations: Mark configuration sections with # @annotation_name for selective filtering and extraction
Types: Booleans, integers, floats, strings, paths, arrays
Type-safe units: Values stored directly as uom types - no conversion or rounding

§Example

use ratslang::compile_code;

let source = r#"
    distance = 100mm..2m
    scan_rate = 10.5s
     
    sensor {
        type = Lidar
        enabled = true
    }
"#;

let result = compile_code(source).unwrap();
let distance = result.vars.resolve("distance").unwrap();

§Usage

Compile and resolve variables:

use ratslang::{compile_code, Rhs, Val, NumVal};

let code = r#"
    timeout = 5000
    sensor.type = Lidar
    sensor.range = 10
"#;

let ast = compile_code(code).unwrap();

// Manual resolution
let timeout = ast.vars.resolve("timeout").unwrap().unwrap();
assert_eq!(timeout, Rhs::Val(Val::NumVal(NumVal::Integer(5000))));

let name = ast.vars.resolve("sensor.type").unwrap().unwrap();
assert_eq!(name, Rhs::Val(Val::StringVal("Lidar".to_string())));

// Filter namespace
let sensor = ast.vars.filter_ns(&["sensor"]);
let range = sensor.resolve("range").unwrap().unwrap();
assert_eq!(range, Rhs::Val(Val::NumVal(NumVal::Integer(10))));

Note: Ratslang is deliberately simple—no arithmetic, loops, or conditionals.

§Syntax Highlighting

Syntax highlighting is available with this tree-sitter grammar or this VS Code extension.

§Annotations

Annotations allow you to mark sections of configuration for selective extraction and filtering. Use # @annotation_name to mark lines or entire blocks that you want to extract later.

§Syntax

Annotate a single line:

timeout = 5000

Annotate an entire namespace block:

sensor {
    type = Lidar
    range = 100m
}

§Usage

Extract annotated configuration (see also: [crate::VariableHistory::to_string_filtered]):

use ratslang::compile_code;

let source = r#"
timeout = 5000

sensor {
    type = Lidar
}

sensor.range = 100m
"#;

let ast = compile_code(source).unwrap();
let minimal_config = ast.to_string_filtered("minimal").unwrap();
println!("{}", minimal_config);

§Use Cases

Minimal configurations: Mark only essential parameters with @minimal for deployment or documentation
Feature flags: Use @feature_name to extract configurations for specific features
Environment-specific: Use @prod, @dev, @test for environment-specific settings
Documentation: Mark parameters with @documented for user-facing config examples

§Supported Time Units

§Base Units

SI Prefixes: fs (femto), ps (pico), ns (nano), us (micro), ms (milli), s (second), min (minute), h (hour), d (day), ks (kilo)

§Common Units

s – second (base unit)
min – minute (60 seconds)
h – hour (3600 seconds)
d – day (86400 seconds)

§Astronomical and Special Units

a – year (365.25 days, Julian year)
shake – 10 nanoseconds (unit used in nuclear physics)
sidereal_year – sidereal year (365.256363004 days)
tropical_year – tropical year (365.242190402 days)

§Notes

SI prefixes combine with base units: ms, us, ns, ps, fs
All time values are stored internally as uom::si::f64::Time with no conversion loss
Ranges work with all time units: 100ms..5s, 1h.., ..30s

§Supported Length Units

§SI Prefixes

pm (pico), nm (nano), um (micro), mm (milli), cm (centi), m (meter), km (kilo), Mm (mega), Gm (giga), Tm (tera), Pm (peta), Em (exa), Zm (zetta), Ym (yotta)

§Imperial Units

in or inch – inch (25.4 mm)
ft or foot – foot (304.8 mm)
yd or yard – yard (914.4 mm)
mi or mile – mile (1609.344 m)

§Astronomical Units

au or AU – astronomical unit (~149.6 million km)
ly or light_year – light-year (~9.46 trillion km)
pc or parsec – parsec (~30.86 trillion km)

§Nautical Units

nmi or nautical_mile – nautical mile (1852 m)
fathom – fathom (1.8288 m, nautical depth measurement)

§Small Units

angstrom – 10^-10 meters (used in atomic physics and chemistry)
bohr_radius – Bohr radius (~0.529 Ångströms, atomic unit)
fermi – femtometer (10^-15 m, nuclear unit)

§Notes

Ranges work with all length units: 1mm..100m, 5ft.., ..10mi
Mixed units in expressions are not supported; each value must use consistent units

Re-exports§

pub use uom;

Macros§

resolve_bool: Resolves a boolean value from user or default configuration.
resolve_float: Resolves a floating-point value from user or default configuration.
resolve_float_force_range: Resolves a numeric range, converting integers to floats if needed.
resolve_float_range: Resolves a floating-point range without implicit integer conversion.
resolve_int: Resolves an integer value from user or default configuration.
resolve_int_range: Resolves an integer range without type conversion.
resolve_length_range_meters_float: Resolves a length range from millimeters to meters as f32.
resolve_path: Resolves a path value from user or default configuration.
resolve_string: Resolves a string value from user or default configuration.
resolve_time_range_seconds_float: Resolves a time range from milliseconds to seconds as f32.
resolve_var: Resolves a variable from user or default configuration.

Structs§

Evaluated: The result of compiling and evaluating ratslang code.
Root: The root of the abstract syntax tree.
VariableHistory: Tracks the history of variable definitions and provides resolution capabilities.
angstrom: ångströms
astronomical_unit: astronomical units
attometer: attometers
attosecond: attoseconds
bohr_radius: bohr radiuses
centimeter: centimeters
centisecond: centiseconds
chain: chains
day: days
day_sidereal: days (sidereal)
decameter: decameters
decasecond: decaseconds
decimeter: decimeters
decisecond: deciseconds
exameter: exameters
exasecond: exaseconds
fathom: fathoms
femtometer: femtometers
femtosecond: femtoseconds
fermi: fermis
foot: feet
gigameter: gigameters
gigasecond: gigaseconds
hectometer: hectometers
hectosecond: hectoseconds
hour: hours
hour_sidereal: hours (sidereal)
inch: inches
kilometer: kilometers
kilosecond: kiloseconds
light_year: light years
megameter: megameters
megasecond: megaseconds
meter: The meter is the SI unit of length. It is defined by taking the fixed numerical value of the speed of light in vacuum c to be 299 792 458 when expressed in the unit m s⁻¹, where the second is defined in terms of the caesium frequency ∆ν_Cs.
microinch: microinches
micrometer: micrometers
micron: microns
microsecond: microseconds
mil: mils
mile: miles
millimeter: millimeters
millisecond: milliseconds
minute: minutes
nanometer: nanometers
nanosecond: nanoseconds
nautical_mile: nautical miles
parsec: parsecs
petameter: petameters
petasecond: petaseconds
picometer: picometers
picosecond: picoseconds
rod: rods
second: The second is the SI unit of time. It is defined by taking the fixed numerical value of the caesium frequency ∆ν_Cs, the unperturbed ground-state hyperfine transition frequency of the caesium 133 atom, to be 9 192 631 770 when expressed in the unit Hz, which is equal to s⁻¹.
second_sidereal: seconds (sidereal)
shake: shakes
terameter: terameters
terasecond: teraseconds
yard: yards
year: years
year_sidereal: years (sidereal)
year_tropical: years (tropical)
yoctometer: yoctometers
yoctosecond: yoctoseconds
yottameter: yottameters
yottasecond: yottaseconds
zeptometer: zeptometers
zeptosecond: zeptoseconds
zettameter: zettameters
zettasecond: zettaseconds

Enums§

NumVal: Represents a numeric value that can be either a floating-point or integer.
Operator
Rhs: Right-hand side of an assignment, representing various expression types.
Statement: A statement in the language (currently only variable assignments).
StatementKind
StatementKindOwned
StatementKindOwnedPass1
StatementKindPass1
StatementPass1
Unit: Physical unit types supported by the language.
UnitVal: A physical quantity with its unit, using the uom crate for type-safe dimensional analysis.
Val: A value in the language, which can be a number (with or without units), string, or boolean.
Var: A variable reference with optional namespace qualification.

Functions§

compile_code: Compiles ratslang source code from a string.
compile_code_with_state: Compiles ratslang source code with existing variable state.
compile_file: Compiles a ratslang source file.
compile_file_with_state: Compiles a ratslang source file with existing variable state.

Type Aliases§

Length: Quantity type alias using the default base units.
Time: Quantity type alias using the default base units.

Crate ratslang

Crate ratslang Copy item path

§Ratslang

§Features

§Example

§Usage

§Syntax Highlighting

§Annotations

§Syntax

§Usage

§Use Cases

§Supported Time Units

§Base Units

§Common Units

§Astronomical and Special Units

§Notes

§Supported Length Units

§SI Prefixes

§Imperial Units

§Astronomical Units

§Nautical Units

§Small Units

§Notes

Re-exports§

Macros§

Structs§

Enums§

Functions§

Type Aliases§

Crate ratslang