lambe

# Lambë

*A query language for structured data that shows you what you're working with.*

`lam` queries JSON, YAML, TOML, HCL, CSV, TSV, and Markdown. Unlike other query tools, it tells you what your query *does* before you run it — the shape at each pipe stage, which output formats can serialize the result, what would go wrong.

Use it when you don't already know the data: inspecting an unfamiliar API response, auditing a Helm chart, verifying a CI pipeline's assumptions, or asking an AI agent to extract something without guessing at the structure.

```
$ lam --to toml '.dependencies | keys' pubspec.yaml
Error: TOML output requires a map at the root, got list<string>.
Try appending one of:
  | as(toml)    # Wraps the list under a single-entry map (equivalent to `{items: .}`).

$ lam --to toml '.dependencies | keys | as(toml)' pubspec.yaml
items = ["rumil", "rumil_parsers", "rumil_expressions"]
```

Queries are bounded and always terminate. No recursion, no lambdas, no `def`. That's the tradeoff: Lambë doesn't try to be a programming language, so its shape inference, `--explain`, `--schema`, and error remediations all work.

*Lambë (pronounced "lam-beh") means "language" in Quenya (Tolkien's elvish). The package name is `lambe` for ASCII compatibility.*

## Installation

One-line installer (Linux and macOS, no `sudo`, verifies SHA256 checksums):

```bash
curl -fsSL https://raw.githubusercontent.com/hakimjonas/lambe/main/install.sh | sh
```

This downloads `lam` and `lam-mcp` from the latest GitHub release into `~/.local/bin/`. Environment variables `LAMBE_VERSION` (pin a version) and `LAMBE_PREFIX` (change install dir) are supported; see the script for details.

Other options:

```bash
# From pub.dev (Dart users)
dart pub global activate lambe

# Dart library
dart pub add lambe

# Build from source
git clone https://github.com/hakimjonas/lambe.git && cd lambe
dart compile exe bin/lam.dart -o lam
```

See [Getting started](doc/getting-started.md) for all installation options.

## Shape-aware output

Lambë checks the result of your query against the shape the target format can serialize. When they match, output is produced. When they don't, the error names the required shape and lists query fragments that would bridge it. In an interactive terminal, Lambë offers to apply the chosen fragment and retry in place.

```
$ lam --to toml '.name' pubspec.yaml
TOML output requires a map at the root, got string.
Try appending one of:
  | as(toml)    # Wraps the scalar under a single-entry map (equivalent to `{value: .}`).

Apply a bridge?
  [1] | as(toml)    # Wraps the scalar under a single-entry map (equivalent to `{value: .}`).
  [q] cancel
> 1
value = "rumil"
```

The same flow applies to CSV and TSV (which require a list of records at the root) and HCL (which requires a map).

Suggestions surface the intent-level `as(<format>)` form. The explanation names the raw fragment (`{value: .}`, `to_entries`, etc.) the bridge composes, so `--explain` and manual composition stay available to anyone who wants them.

### Non-scalar cells in CSV/TSV

By default, nested lists or maps in CSV/TSV cells are rejected — there is no faithful delimited rendering for them. When you need a quick export and lossy is acceptable, pass `--flatten-cells json` (CLI) or `:flatten-cells json` (REPL) to encode them as JSON strings inline. Round-tripping the resulting file back into Lambë does not recover the original structure; prefer reshaping the data query-side when fidelity matters.

### `as(fmt)` — bridging in the query language

When the shape of the target format is known up front, `as(fmt)` performs the bridge inside the query. The combinator is a no-op when the input already satisfies the target, applies a single curated bridge when one exists, and lists the candidates when more than one could apply.

```
$ lam --to toml '.dependencies | as(toml)' pubspec.yaml
rumil = "^0.6.0"
rumil_parsers = "^0.6.0"
rumil_expressions = "^0.6.0"

$ lam --to csv '.dependencies | as(csv)' pubspec.yaml
key,value
rumil,^0.6.0
rumil_parsers,^0.6.0
rumil_expressions,^0.6.0
```

`as` accepts `json`, `yaml`, `toml`, `csv`, `tsv`, and `hcl`.

### `--explain` — see the shape at every pipe stage

`--explain` walks the pipe backbone of a query and reports the shape at each stage, followed by the set of output formats the final shape can be serialized as. It performs static analysis only and does not evaluate the query; pass a data file to seed with real shape information, or omit it to trace against an unknown input.

```
$ lam --explain '.dependencies | keys' pubspec.yaml
.dependencies  : map<rumil: string, rumil_parsers: string, rumil_expressions: string>
| keys         : list<string>

Writable as: json, yaml, csv, tsv
Not writable as: toml, hcl
```

Explain flags provably-empty filters (`filter(.missing)` on a known shape) and runtime-rejection mismatches (`filter` on a non-list input) by default. Pass `--explain-trivial` to also flag `sort_by`/`group_by`/`map`/`unique_by` whose argument references a missing field (often a typo, sometimes intentional). For agent tooling and build pipelines, `--explain-json` emits the same information as a structured JSON document.

### `--schema` — declare a shape and let Lambë check your work

When you have a JSON Schema for your data — from an API contract, OpenAPI spec, or hand-written docs — point `--schema` at it:

```
$ lam --schema api.schema.json --explain '.users | map(.email)' response.json
.users         : list<map<id: string, name: string, email: optional<string>>>
| map(.email)  : list<optional<string>>

Writable as: json, yaml, csv, tsv
Not writable as: toml, hcl
```

The schema fills in information data alone can't express: optional fields (from JSON Schema's `required`), element shapes of empty lists, types `shapeOf` couldn't infer from sampling. `--explain` shows them; the evaluator trusts them.

With data present, Lambë also validates: a schema saying `age: number` against data with `age: "30"` exits 1 at load time with a JSON-path-annotated diagnostic. No silent drift, no running a query against data that doesn't match its contract.

A sibling `<datafile>.schema.json` is auto-detected, so a project convention of placing schemas next to data works without explicit flags.

The reverse direction is symmetrical: `lam --print-shape data.json` emits the inferred shape as a JSON Schema document. Round-trip:

```
lam --print-shape data.json > data.schema.json    # bootstrap a schema from data
lam --schema data.schema.json '.users' data.json  # use it back
```

Accepted JSON Schema keywords: `type`, `properties`, `items`, `required`. Value-level constraints (`minimum`, `pattern`, `enum`, etc.), structural combinators (`allOf`, `oneOf`), `$ref`, and conditional schemas are rejected with a per-keyword error. Lambë is a shape system, not a validation engine — for richer validation, reach for `ajv` or `check-jsonschema`.

## Query Syntax

Queries start with `.` (the current data) and chain operations with `|`:

```
.                              the whole document
.name                          access a field
.users[0]                      index into a list
.users[0].address.city         chain access
.users | filter(.age > 30)     pipe into an operation
.users | map(.name)            transform each element
```

Pipelines read left to right. Each `|` passes its result to the next operation:

```
.users | filter(.active) | sort_by(.name) | map(.name)
```

This takes `.users`, keeps active ones, sorts by name, and extracts names.

### Expressions

```
.price * .qty                  arithmetic (+, -, *, /, %)
.age > 30                      comparison (<, >, <=, >=, ==, !=)
.active && .verified           logic (&&, ||, !)
if .age > 65 then "senior" else "active"   conditional
{name, total: .price * .qty}   construct a new object
"\(.name) is \(.age)"          string interpolation
.[1:3]                         slice a list or string
```

### Operations

Operations follow `|` and transform the piped value:

```
. | filter(.age > 30)          keep matching elements
. | map(.name)                 transform each element
. | sort_by(.age)              sort by a key
. | group_by(.dept)            group into [{key, values}]
. | length                     count elements
. | first                      first element
. | sum                        sum numbers
. | keys                       map keys or list indices
. | has("field")               check if a field exists
. | unique                     remove duplicates
. | flatten                    flatten one level of nesting
. | to_entries                 map to [{key, value}] pairs
. | filter_values(. > 5)       filter a map's values
. | as(toml)                   bridge to an output format
```

See the full list in [Pipeline Operations](#pipeline-operations) below.

## CLI

```bash
# Extract values
lam '.database.host' config.toml
lam '.spec.containers[0].image' deployment.yaml

# Filter and transform
lam '.users | filter(.age > 30) | map(.name)' data.json

# Aggregate
lam '.items | map(.price) | sum' data.json

# Sort and pick
lam '.items | sort_by(.price) | first' data.json

# Object construction
lam '.users | map({name, senior: .age > 65})' data.json

# String interpolation
lam '.users | map("\(.name) is \(.age)")' data.json

# Shape trace
lam --explain '.users | map(.name)' data.json

# Shape inspection (JSON Schema output)
lam --print-shape data.json

# Schema-checked queries: validate data against a schema as it runs
lam --schema api.schema.json '.users | map(.email)' response.json

# CI validation
lam --assert '.version != "0.0.0"' package.json
lam --assert '.replicas >= 2' deployment.yaml

# Format conversion
lam --to yaml '.config' data.json
lam --to csv '.users | map({name, age})' data.json
lam --to toml '.config | as(toml)' data.json
lam --to csv --flatten-cells json '.users' data.json   # encode nested cells as JSON

# Line-delimited JSON (logs, event streams)
lam --ndjson '.