2.5 Using the library

karpfen-dsl-tools is the Kotlin library that reads, checks and writes the three languages. The runtime and the IDE use it, and any JVM program can use it too. The examples use the lamp files of 2 Modeling languages: lamp.kmeta, lamp.kmodel, lamp.kstates, and lamp-events.kmeta from 2.1.7 Event definitions.

2.5.1 Adding the library to a build#

ItemValue
Group and artifactio.karpfen:karpfen-dsl-tools
Version2.0.0-SNAPSHOT
Repositoryhttps://maven.pkg.github.com/karpfenproject/karpfen-dsl-tools (GitHub Packages)
JDK21
Dependencies a consumer getsANTLR runtime 4.13.1, org.json, SLF4J API

GitHub Packages asks for credentials also for reading: a GitHub user and a token that may read packages. The library itself names them as the Gradle properties GitHubPackagesUsername and GitHubPackagesPassword when it publishes.

A build may also take the library from a git submodule. The runtime includes the checkout as a subproject with include 'karpfen-dsl-tools' in its settings.gradle, and the IDE includes it as an included build. To build the library on its own, run ./gradlew build in its folder with JDK 21.

2.5.2 Reading a text#

A reader reads one text and never throws. KmetaReader, KmodelReader and KstatesReader each have the method read(text), which returns a ParseResult. It holds the model the reader built, the problems it found and a source map, which tells where each element of the model is written. A byte order mark at the start of the text is ignored, while positions still count it as the first char of the first line, as the text holds it.

Member of ParseResultContent
modelThe metamodel, model or state machine. With errors it is partial: the reader leaves out what it cannot read. It is null only if nothing could be built, such as for a KMeta text without a type.
diagnosticsEvery problem, ordered by its position in the text.
errorsThe problems of severity ERROR.
hasErrorsTrue if there is at least one error.
sourceMapThe ranges of the elements of model in the text.

KmodelReader takes the metamodel in its constructor, and KstatesReader the optional features that are switched on, see 2.5.6 Optional features. A reader keeps no state between reads, so one reader may serve several threads.

import io.karpfen.dsl.diagnostics.Diagnostic
import io.karpfen.dsl.reader.kmeta.KmetaReader
import io.karpfen.dsl.reader.kmodel.KmodelReader
import java.io.File

fun report(fileName: String, problems: List<Diagnostic>) {
    for (problem in problems) {
        val start = problem.range.start
        println("$fileName:${start.line}:${start.column}: ${problem.severity} ${problem.code.id}: ${problem.message}")
    }
}

fun readLamp(folder: File) {
    val metamodelRead = KmetaReader().read(File(folder, "lamp.kmeta").readText())
    report("lamp.kmeta", metamodelRead.diagnostics)
    val metamodel = metamodelRead.model ?: return
    val modelRead = KmodelReader(metamodel).read(File(folder, "lamp.kmodel").readText())
    report("lamp.kmodel", modelRead.diagnostics)
    val room = modelRead.model?.objects?.singleOrNull() ?: return
    val bulb = room.getRel("lamp").single().getRel("bulb").single()
    println(bulb.getProp("maxWatts"))
    println(modelRead.sourceMap.nameRangeOf(bulb))
}

For the lamp files, readLamp reports no problem and prints the maximum watts of the bulb and where its key is written:

[40.0]
SourceRange(start=SourcePosition(offset=148, line=4, column=37), end=SourcePosition(offset=152, line=4, column=41))

A diagnostic has a range with a start and an end, each with an offset, a line and a column; lines and columns count from 1. Its code is a DiagnosticCode, whose id is the code that 2.4 Checks lists, and its severity is ERROR or WARNING. The code is stable, the message is meant for people. A metamodel with prop("watts", "Number") in line 2 gives:

lamp.kmeta:2:20: ERROR kmeta.unknown-property-type: Unknown type 'Number' of prop 'watts'; a prop is of type 'string', 'number', 'boolean'

A metamodel holds its types in types, each a ClassType with simpleProperties and objectProperties, and its root type in rootClass. A model holds its root object in objects. A DataObject has its id, its type ofType, the values of a property by getProp(key) and the objects of a relation by getRel(key), both as lists. A ClassType whose KMeta type has behaves after holds it in behavesAfter, a BehavesAfter with the stateMachineName. A state machine read from KStates is a StateMachine with attachedToClass, states, transitions and macros:

import io.karpfen.dsl.reader.kstates.KstatesReader
import java.io.File

fun readLampMachine(folder: File) {
    val read = KstatesReader().read(File(folder, "lamp.kstates").readText())
    report("lamp.kstates", read.diagnostics)
    val machine = read.model ?: return
    println(machine.attachedToClass)
    for (state in machine.states) {
        println("${state.name} ${read.sourceMap.rangeOf(state)?.start?.line}")
    }
}
Lamp
off 3
on 10

An attachable state machine, see 2.3.1 The state machine, has isAttachable true, its name and its types in attachableTo, and an empty attachedToClass. An attached one has the name null. types holds the types of either form. A fragment, see 2.3.12 Pages, has isFragment true, its name, no types and isAttachable false. A State tells its kind: isContainer with the name of its fragment in fragment, and isFinal. DONE is a DoneCondition. An action rule with an ATTACH clause holds it in attach, an AttachClause whose stateMachineName is the value, and EXCHANGE is the operation ActionOperationType.EXCHANGE.

The source map has rangeOf(element) for the whole element, nameRangeOf(element) for its name or key, codeRangeOf(element) for the code of an EVAL and operandRangesOf(element) for the operands of an action rule. It knows the elements of the model by identity. The name of an attached state machine is its type. The name of an attachable state machine is its name, and its operands are its types. An AttachClause and a BehavesAfter range over the whole clause, keyword included, and the name of a BehavesAfter is the name of the state machine.

2.5.3 Throwing converters#

The converters are the throwing form of the readers, for a text that is expected to be right. They are KmetaDSLConverter, KmodelDSLConverter and KstatesDSLConverter in the package io.karpfen.dsl.dsl.textual, each with a function for a string and one for a file. Each reads through its reader, so every rule of the language holds for it as for the reader. It returns the model of a text without errors and throws for a text with at least one error. Warnings do not make it throw. KstatesDSLConverter reads with every optional feature switched on.

import io.karpfen.dsl.dsl.textual.JsonToModelConverter
import io.karpfen.dsl.dsl.textual.KmetaDSLConverter
import io.karpfen.dsl.dsl.textual.KmodelDSLConverter
import io.karpfen.dsl.dsl.textual.KstatesDSLConverter
import java.io.File

fun convertLamp(folder: File) {
    val metamodel = KmetaDSLConverter.parseKmetaFile(File(folder, "lamp.kmeta").path)
    val events = KmetaDSLConverter.parseKmetaString(File(folder, "lamp-events.kmeta").readText(), metamodel.types)
    val model = KmodelDSLConverter.parseKmodelFile(File(folder, "lamp.kmodel").path, metamodel)
    val machine = KstatesDSLConverter.parseKstatesFile(File(folder, "lamp.kstates").path)
    println("${metamodel.rootClass.name} ${model.objects.single().id} ${machine.states.size}")
    val payload = JsonToModelConverter(events).toDataObject("""{"bright": true}""", "dim")
    println(payload.getProp("bright"))
}
Room living room 2
[true]

parseKmetaString takes the types of the domain metamodel as its second argument when it reads an event metamodel. KmodelDSLConverter.parseSingleObject reads a KModel text such as an event payload and returns its root object. A KModel text is always one object, so it reads the text exactly as parseKmodelString does, with the same errors. JsonToModelConverter turns a JSON object into an object of a type, here the payload of the event dim.

A converter throws an InvalidTextException from the package io.karpfen.dsl.reader, the same type for all three languages. It is an IllegalArgumentException. Its errors hold every error the reader found, as the diagnostics of 2.5.2 Reading a text, and its source holds the path of the file, or null for a string. The message names each error on a line of its own, with the position, the code and the message. If the state off of lamp.kstates lacks its INITIAL, parseKstatesFile("lamp.kstates") throws with the message:

lamp.kstates has 1 error:
lamp.kstates:2:5: kstates.initial-state-count: Exactly one state must be marked as INITIAL, but found 0.

For a string, the first line reads The text has 1 error: and the lines start with the position. The converters take this step with modelOrThrow() of ParseResult, which a program can also call on the result of a reader: it returns the model of a text without errors and throws the same exception otherwise.

Use a converter where a wrong text is a failure, such as a runtime that loads a deployed project or a test. Use a reader where a wrong text is normal and its problems are shown, such as an editor, or where a partial model is needed.

Model.collectAllObjects(objects) in the package io.karpfen.dsl.instance returns the given objects and every object embedded in them, each once, each object before the objects it embeds. For a model read from text, Model.collectAllObjects(model.objects) returns all objects of the model.

2.5.4 Printing back to text#

The printers write a metamodel, a model or a state machine as text: KmetaPrinter, KmodelPrinter and KstatesPrinter in the packages below io.karpfen.dsl.printer. print writes a whole text. The printers also write a single element as a fragment that can replace that element in an existing text: printType and printRule for KMeta, printObject for KModel, printState, printTransition and printMacro for KStates. The convertTo...String functions of the converters call the same printers.

import io.karpfen.dsl.instance.Model
import io.karpfen.dsl.printer.kmodel.KmodelPrinter
import io.karpfen.dsl.printer.kstates.KstatesPrinter
import io.karpfen.dsl.states.StateMachine

fun printLamp(model: Model, machine: StateMachine) {
    print(KmodelPrinter().print(model))
    val bulb = model.objects.single().getRel("lamp").single().getRel("bulb").single()
    println(KmodelPrinter().printObject(bulb))
    println(KstatesPrinter().printState(machine.states.first()))
}

For the lamp, the bulb and the state off come out as:

make object "bulb":"Bulb" {
    prop("maxWatts") -> "40.0"
    prop("watts") -> "0.0"
    prop("lit") -> "false"
}
INITIAL STATE "off" {
    ENTRY {
        SET("mode", "off")
        SET("bulb->lit", "false")
        SET("bulb->watts", "0")
    }
}

The printers use one layout: four spaces per level, one statement per line, and an empty block as { }. A text that is read and printed again loses its comments, except comments inside EVAL code. A number of a model is written as the library holds it, so "40" comes back as "40.0". The KMeta printer writes the properties of a type before its relations and the root type last. KmetaPrinter().print(events, metamodel.types) writes an event metamodel without the domain types it was read with. A printer throws an IllegalArgumentException for an element that its language cannot write, such as a name with a line break.

2.5.5 Building models in code#

MetamodelBuilder and ModelBuilder in the package io.karpfen.dsl.dsl.functional build a metamodel and a model without text. makeClass defines a type, makeNumber, makeString and makeBool and their ...List forms make properties, and makeClassProp and makeClassPropList make relations, EMBEDDED for has and LINK for knows. A relation can only lead to a type that is already defined.

import io.karpfen.dsl.dsl.functional.MetamodelBuilder
import io.karpfen.dsl.meta.Metamodel

fun buildLampMetamodel(): Metamodel {
    val m = MetamodelBuilder()
    m.makeClass("Bulb", "A light bulb", props = listOf(m.makeNumber("maxWatts"), m.makeNumber("watts"), m.makeBool("lit")))
    m.makeClass("Switch", "A wall switch", props = listOf(m.makeString("position"), m.makeStringList("presses")))
    m.makeClass(
        "Lamp", "A lamp with a bulb, wired to a switch",
        props = listOf(m.makeString("mode")),
        rels = listOf(m.makeClassProp("bulb", "Bulb", m.EMBEDDED), m.makeClassProp("control", "Switch", m.LINK))
    )
    m.makeClass(
        "Room", "The room the lamp stands in",
        rels = listOf(m.makeClassProp("lamp", "Lamp", m.EMBEDDED), m.makeClassProp("switch", "Switch", m.EMBEDDED))
    )
    m.setRoot("Room")
    return m.build()
}

ModelBuilder.makeObject(type, id) makes an object. It gives every property a default value, false, the empty string, Double.MIN_VALUE or an empty list, and every relation to one object a new default object without id. assignProps and assignRels replace these values; a key that the type does not have is ignored.

import io.karpfen.dsl.dsl.functional.ModelBuilder
import io.karpfen.dsl.instance.Model
import io.karpfen.dsl.meta.Metamodel

fun buildLampModel(metamodel: Metamodel): Model {
    val b = ModelBuilder(metamodel)
    val wallSwitch = b.makeObject("Switch", "wallSwitch")
    wallSwitch.assignProps(mapOf("position" to "down"))
    val bulb = b.makeObject("Bulb", "bulb")
    bulb.assignProps(mapOf("maxWatts" to 40.0, "watts" to 0.0, "lit" to false))
    val lamp = b.makeObject("Lamp", "lamp")
    lamp.assignProps(mapOf("mode" to "off"))
    lamp.assignRels(mapOf("bulb" to bulb, "control" to wallSwitch))
    val room = b.makeObject("Room", "living room")
    room.assignRels(mapOf("lamp" to lamp, "switch" to wallSwitch))
    return b.build()
}

The model of a builder holds every object it made, the default objects included. KmodelPrinter().print starts at the object of the root type with an id that no other object embeds, and for this model writes the same text as the lamp model of 2 Modeling languages, with numbers such as "40.0".

2.5.6 Optional features#

KstatesReader takes the optional features that a text may use, see 2.3.10 Optional features. The default is KstatesFeature.ALL. Each feature has a stable id, and KstatesFeature.byId finds a feature by its id, for example from a settings file.

import io.karpfen.dsl.reader.ParseResult
import io.karpfen.dsl.reader.kstates.KstatesReader
import io.karpfen.dsl.states.KstatesFeature
import io.karpfen.dsl.states.StateMachine

fun readWithFeatures(text: String, featureIds: List<String>): ParseResult<StateMachine> {
    val switchedOn = featureIds.mapNotNull { KstatesFeature.byId(it) }.toSet()
    return KstatesReader(switchedOn).read(text)
}

The converter KstatesDSLConverter always accepts every feature.

2.5.7 Verifying a project#

ProjectVerifier in the package io.karpfen.dsl.verification checks the state machines of a project against the metamodels and the model, see 2.4.6 Project. It takes the results of the readers in a ProjectInput: the domain metamodel, the event metamodel or null, the model or null, and the state machines. Each state machine is a StateMachineInput with the key of the object it runs on, or null if it is not known yet. The list holds every state machine of the project, the attached and the attachable ones and the fragments alike; an attachable state machine and a fragment have no key. The verifier needs all of them to check the names that behaves after, ATTACH and EXCHANGE use. The event metamodel is read with the domain types as base types.

import io.karpfen.dsl.reader.kmeta.KmetaReader
import io.karpfen.dsl.reader.kmodel.KmodelReader
import io.karpfen.dsl.reader.kstates.KstatesReader
import io.karpfen.dsl.verification.ProjectInput
import io.karpfen.dsl.verification.ProjectVerifier
import io.karpfen.dsl.verification.StateMachineInput
import java.io.File

fun verifyLamp(folder: File) {
    val metamodel = KmetaReader().read(File(folder, "lamp.kmeta").readText())
    val domainTypes = metamodel.model?.types.orEmpty()
    val events = KmetaReader(domainTypes).read(File(folder, "lamp-events.kmeta").readText())
    val model = metamodel.model?.let { KmodelReader(it).read(File(folder, "lamp.kmodel").readText()) }
    val lamp = StateMachineInput(KstatesReader().read(File(folder, "lamp.kstates").readText()), "lamp")
    val findings = ProjectVerifier().verify(ProjectInput(metamodel, events, model, listOf(lamp)))
    report("lamp.kstates", findings.of(lamp))
}

findings.of(lamp) holds the problems in the text of that state machine, ordered by position. findings.metamodel and findings.events hold the problems in the text of the domain metamodel and of the event metamodel, which concern behaves after. findings.all, findings.errors and findings.warnings hold those of all texts. The verifier adds to the diagnostics of the readers and never repeats them, so a tool shows both.

2.5.8 Flattening a composition#

StateMachineFlattener.flatten(machine, available) in the package io.karpfen.dsl.composition flattens the composition that starts from machine, see 2.3.12 Pages. available holds the state machines it may use, usually every state machine of the project; it uses only the fragments among them, found by name. The function is pure: it changes neither its input nor anything else, and it throws for no problem of the texts.

It returns a FlatteningResult. A Flattened holds the flat state machine in machine, with the header of machine and no container state left to resolve: each container state holds copies of the states of its fragment, named with slashes. sources lists the state machines of the composition, the starting one first. originOf(name) and origins tell where each state was written, as a StateOrigin with the fragment it was written in, or null for the starting state machine, its localName in that text and the flattened names of the containers above it. A NotFlattened holds the problems that prevent the flattening, each a FlatteningProblem with the state machine it stands in, the element it concerns and a message: UnknownFragment, NotAFragment, FragmentCycle, NameClash, ConflictingMacros, UnknownMacro and MacroArgumentMismatch, a call whose number of arguments does not fit the macro it names in another file of the composition.

import io.karpfen.dsl.composition.FlatteningResult
import io.karpfen.dsl.composition.StateMachineFlattener
import io.karpfen.dsl.reader.kstates.KstatesReader
import java.io.File

fun flattenLamp(folder: File) {
    val lamp = KstatesReader().read(File(folder, "lamp.kstates").readText()).model ?: return
    val bulbTest = KstatesReader().read(File(folder, "bulb test.frag.kstates").readText()).model ?: return
    when (val result = StateMachineFlattener.flatten(lamp, listOf(bulbTest))) {
        is FlatteningResult.Flattened -> {
            for ((name, origin) in result.origins) {
                println("$name ${origin.fragment} ${origin.localName}")
            }
        }
        is FlatteningResult.NotFlattened -> result.problems.forEach { println(it.message) }
    }
}

For the lamp with the container state self test and the bulb test of 2.3.12.2 Container states and DONE, this prints:

off null off
self test null self test
self test/powered bulb test powered
self test/passed bulb test passed
self test/failed bulb test failed
on null on

In the flat state machine, isContainer and isFinal stay as written. InitialStates.startPath(machine) in the package io.karpfen.dsl.states returns the states a state machine starts in, and InitialStates.enteredBelow(state) the states entered below a container state when it is entered, both the outermost first, by the rule of 2.3.2.2 The initial state. initialInnerState of a state is the first state of that path below it. The verifier flattens each state machine of a project in the same way, see 2.4.6.5 Pages, and the runtime flattens a state machine before it runs.

2.5.9 Logging#

The library logs through the SLF4J API and ships no logging backend. The program that uses it picks one, or gets no log output.

LoggerLevelWhat
Below io.karpfen.dsl.readererrorA reader that failed through a defect, with its stack trace.
Below io.karpfen.dsl.readerwarnA reader that failed on nesting deeper than its parser can follow.

A reader reports the problems of a text only as diagnostics, never in the log, and a converter only in its exception. When a reader fails, it reports the diagnostic reader.failure as well, and a converter throws with it.

Source: this page on GitHub at commit 3b6029f, refreshed 16 November 2026. The whole reference as a PDF.