Style Guide

Everything you need to know before changing the DML interpreter or the dml-go library. Read the rules for all repositories first, then the section for the repository you are editing.

Rules for every change

DML

The interpreter and command line tool. It is written in Kotlin 1.9 for the JVM 17, built with Gradle into a shadow jar (DML-all.jar), and uses an ANTLR 4.13 grammar, snakeyaml and kotlinx-serialization.

Commands

Command What it does
./gradlew testRuns the test suite
./gradlew buildBuilds and tests the project
./gradlew shadowJarBuilds build/libs/DML-all.jar
java -jar build/libs/DML-all.jar -r dml file.dmlRuns a DML file with the freshly built jar

Structure

src/main/antlr/DML.g4                 grammar
src/main/kotlin/Main.kt  DMLInterpreter.kt
src/main/kotlin/cli/                  Cli.kt, argument handling
src/main/kotlin/interpreter/          DMLExecutor.kt, SymbolTable.kt
src/test/kotlin/                      JUnit 5, one class per concern, @TempDir for files
src/test/resources/                   .dml fixtures used by tests
.circleci/config.yml                  test, build, release

Code style

Security

The interpreter runs untrusted .dml input, so these rules are not negotiable.

dml-go

The Go library and command line tool that loads, parses, validates and caches .dml configuration files. The module is github.com/tree-software-company/dml-go and targets Go 1.21.

Commands

Command What it does
go build -o bin/dml ./cmd/dmlBuilds the command line tool
go test ./...Runs all tests
gofmt -l .Lists files that are not formatted
go vet ./...Reports suspicious code

Structure

cmd/dml/main.go          CLI entry only
dml/                     public package: parser, config, env, error, lint
dml/*_test.go            tests next to the code they cover
internal/                jar download and verification
examples/  testdata/     runnable examples and fixtures

Code style

Security

Workflow