Skip to content

Branchline DSL Documentation

Branchline is a Kotlin-based DSL for transforming structured data. These docs cover language features, guides, and an interactive playground. For a formal reference, see the language grammar.

What is Branchline?

Branchline is a compact language for reshaping structured data (JSON, XML, more coming) with built-in tracing. It aims for clarity, composability, and debuggability while remaining fast across JVM and JS runtimes.

Try it now

  • Open the embedded playground and load an example such as customer-profile or pipeline-health-gating.
  • Toggle tracing to see EXPLAIN(...) output; edit JSON/XML input and rerun with Cmd/Ctrl + Enter.
  • Use ?example=stdlib-hof-overview (or any ID) in the URL to preload a scenario.

Quickstart (local)

# 1) Clone and verify toolchain
git clone https://github.com/ehlyzov/branchline-public.git
cd branchline-public
./gradlew --version

# 2) Run a Branchline program on JVM
./gradlew :cli:runBl --args "path/to/program.bl --input sample.json"

# 3) Run via Node
./gradlew :cli:jsNodeProductionRun --args="path/to/program.bl --input sample.json"
Need more detail? See Install Branchline and First steps.

Use Branchline in your project

  • CLI (JVM/Node): Use the Gradle helpers above during development or CI. Keep your .bl scripts in your repo and call the CLI from your build/test steps.
  • JS tarball: ./gradlew :cli:packageJsCli produces cli/build/distributions/branchline-cli-js-<version>.tgz. Add it to your build artifacts, unpack it in CI, and run bin/bl.cjs with --input/--input-format.
  • Vendoring: You can vendor the packaged CLI into your own tools or Docker images; no Maven/npm packages are published yet, so bundling the tarball (or building from source) is the current path.

Simplest program

TRANSFORM Hello {
    OUTPUT { greeting: "Hello, " + input.name };
}
Run it on JVM: 
./gradlew :cli:runBl --args "hello.bl --input sample.json"
Or on Node: 
./gradlew :cli:jsNodeProductionRun --args="hello.bl --input sample.json"

Language highlights

  • Straightforward data paths: $ or INPUT to navigate payloads; dot, slice, predicate, wildcard support.
  • Built-in tracing: EXPLAIN, CHECKPOINT, and ASSERT surface provenance.
  • Rich stdlib: arrays, aggregation, text utilities, higher-order functions, time, and shared-memory helpers.
  • Multiplatform parity: JVM and JS runtimes share the same interpreter/VM code.

Learn the language

  • Start with the Language Overview and the Getting Started guide.
  • Explore the standard library pages for runnable examples linked to the playground.
  • Use the playground to tweak code and inputs without installing anything.

What you can build