lambe library

Multi-format query language for structured data.

Lambé provides a composable query DSL for JSON, YAML, TOML, HCL, CSV, TSV, and Markdown, with pipeline operations, property access chains, and filter predicates. Built on Rumil parser combinators with left-recursive grammar support via Warth seed-growth.

import 'package:lambe/lambe.dart';

final name = query('.users[0].name', data);
final active = queryString('.users | filter(.active)', jsonString);
final host = queryString('.database.host', tomlString, format: Format.toml);

Classes

Access: Property access on an expression: expr.field.
AnyShape: Accepts any shape. Used by JSON and YAML, which have no root-shape restriction.
As: Shape-directed bridge to an output format: as(toml), as(csv).
AvgOp: Average of all numeric elements: avg.
BinaryOp: Binary operator application, e.g. a + b or x == y.
BoolLit: Boolean literal: true or false.
Conditional: Conditional expression: if cond then a else b.
ExplainReport: A full explain report for a query.
ExplainStage: A single row in an explain trace.
Field: Field access on the current context: .name.
FilterKeysOp: Filter map keys by predicate: filter_keys(. != "internal").
FilterOp: Filter elements by predicate: filter(.age > 30).
FilterValuesOp: Filter map values by predicate: filter_values(. > 5).
FirstOp: Get first element of a list: first.
FlattenOp: Flatten one level of nesting: flatten.
FromEntriesOp: Convert a list of {key, value} entries back to a map: from_entries.
GroupByOp: Group elements by a key expression: group_by(.type).
HasOp: Check if a key exists: has("name") or has(.key_field).
Identity: Identity: . - returns the current context value.
Index: Index into an expression: expr[index].
KeysOp: Get keys of a map or indices of a list: keys.
LamExpr: A query expression node.
LastOp: Get last element of a list: last.
LengthOp: Get length of a list, map, or string: length.
MapOp: Transform each element: map(.name).
MapValuesOp: Transform map values: map_values(. * 2).
MaxOp: Maximum element: max.
MinOp: Minimum element: min.
MustBeList: Requires a list at the root. Used by CSV and TSV.
MustBeMap: Requires a map at the root. Used by TOML and HCL, whose document-level grammar is a table.
NotWritable: The value's shape does not satisfy the target format's requirement.
NullLit: Null literal: null.
NumLit: Numeric literal, e.g. 42 or 3.14.
ObjConstruct: Object construction: {name, total: .price * .qty}.
Pipe: Pipeline expression: expr | expr.
Remediation: A query fragment that bridges a shape mismatch.
ReverseOp: Reverse element order: reverse.
SAny: Unknown or mixed shape.
SBool: Shape of a boolean value.
Shape: The structural shape of a value.
ShapeReport: Report returned by canWriteAs.
ShapeRequirement: The shape a given OutputFormat requires at its root.
Slice: Slice into a list: expr[start:end].
SList: Shape of a list, with the shape of its elements.
SMap: Shape of a map, with the shape of each known field.
SNull: Shape of a null value.
SNum: Shape of a numeric value (int or double, unified).
SortByOp: Sort by a key expression: sort_by(.age).
SortOp: Sort elements naturally: sort.
SString: Shape of a string value.
StringInterp: String interpolation: "\(.name) is \(.age) years old".
StrLit: String literal, e.g. "hello".
SumOp: Sum all numeric elements: sum.
ToEntriesOp: Convert a map to a list of {key, value} entries: to_entries.
ToNumberOp: Parse a string as a number: to_number.
TypeOp: Runtime type of the input as a string: type.
UnaryOp: Unary operator application, e.g. -x or !flag.
UniqueByOp: Remove duplicates by key: unique_by(.name).
UniqueOp: Remove duplicate elements: unique.
ValuesOp: Get values of a map (or identity for a list): values.
Writable: The value's shape satisfies the target format's requirement.

Enums

Format: Supported input formats.
OutputFormat: Supported output formats for --to.
PipeOpParseKind: How the parser should build a grammar rule for this op.

Constants

lambeVersion → const String: Lambe version, sourced from pubspec.yaml at generation time.

Properties

pipeOpNames → List<String>: All pipe-op names, sorted alphabetically.
final
pipeOpSpecs → List<PipeOpInfo>: All pipe-op specs, ordered so the parser can build grammar rules without manual disambiguation.
final

Functions

acceptsInputShape(String opName, Shape shape) → bool: Whether opName accepts an input of shape.
applyBridge(LamExpr user, LamExpr bridge) → LamExpr: Compose user's query with a bridge AST fragment via Pipe.
canWriteAs(Object? value, OutputFormat format) → ShapeReport: Check whether value can be written in format.
canWriteShapeAs(Shape shape, OutputFormat format) → ShapeReport: Shape-only variant of canWriteAs.
detectFormat(String path) → Format?: Detect format from a file path's extension.
eval(LamExpr ast, Object? data) → Object?: Evaluate a pre-parsed LamExpr AST against data.
evaluateAst(LamExpr ast, Object? data) → Object?: Evaluate a parsed ast against data.
explain(LamExpr expr, Shape inputShape) → ExplainReport: Produce an ExplainReport for expr given inputShape as the initial context. Pass SAny when the input's shape is unknown.
formatOutput(Object? value, OutputFormat format, {bool pretty = true}) → String: Format value as a string in the given format.
inferPipeOpShape(Shape input, LamExpr op) → Shape: Infer the output shape of a pipe op.
inferSchema(Object? value) → Object?: Infer the structure of value without showing actual data.
inferShape(LamExpr expr, Shape input) → Shape: Infer the shape of expr given input as the initial context.
mdToNative(MdDocument doc) → Object?: Convert an MdDocument into queryable native Dart types.
parse(String expression) → Result<ParseError, LamExpr>: Parse a query expression string into a LamExpr AST.
parseAst(String expression) → LamExpr: Parse an expression string to its LamExpr AST.
parseInput(String input, Format format) → Object?: Parse input string in the given format to native Dart types.
pipeOpInfoFor(LamExpr node) → PipeOpInfo?: Look up the spec for a pipe-op AST node, or null if node is not a pipe op.
pipeOpInfoForName(String name) → PipeOpInfo?: Spec lookup by op name. Returns null for names that are not in the spec table.
query(String expression, Object? data) → Object?: Parse and evaluate a query expression against data.
queryJson(String expression, String json) → Object?: Parse a JSON string, then evaluate expression against it.
queryString(String expression, String input, {Format? format}) → Object?: Parse an input string in the given format, then evaluate expression.
renderExplain(ExplainReport report) → String: Render an ExplainReport as a plaintext table suitable for stdout.
renderShape(Shape shape) → String: Human-readable rendering of a Shape.
requirementFor(OutputFormat format) → ShapeRequirement: The requirement for each supported OutputFormat.
shapeOf(Object? value) → Shape: Infer the structural Shape of value.
sniffFormat(String input) → Format: Guess format by sniffing the input content.
synthesize(Shape from, OutputFormat target) → List<LamExpr>: AST fragments that, when piped after a query producing from, yield a value satisfying target's shape requirement.
synthesizeWithLabels(Shape from, OutputFormat target) → List<Remediation>: Shape-directed synthesis returning full Remediation records.

Typedefs

PipeOpInfo = ({bool Function(Shape input) accepts, Shape Function(Shape input, LamExpr op) infer, String name, LamExpr Function(LamExpr)? oneArgCtor, PipeOpParseKind parseKind, LamExpr Function()? zeroArgCtor}): Metadata for one pipe operation.

Exceptions / Errors

OutputShapeError: Error thrown when a value's shape is incompatible with a requested output format.
QueryError: Error thrown during query evaluation or output serialization.

lambe library

Classes

Enums

Constants

Properties

Functions

Typedefs

Exceptions / Errors

lambe package

lambe library