Getting Started with Intuitive DSL Engine for Java

The Intuitive DSL Engine allows you to parse complex, human-readable text commands and bind them directly to your Java objects with strictly zero boilerplate.

This guide will show you how to set up the engine, define your first command using Intuitive BNF (iBNF), and execute it safely in just a few minutes.

1. Installation

Note : The Intuitive DSL Engine is a pure Java 17+ implementation with absolutely zero external dependencies. It will not pollute your classpath or create version conflicts (no Guava, no Jackson, no Log4j).

Add the following dependency to your pom.xml:

<dependency>  
    <groupId>ch.dbalabs</groupId>  
    <artifactId>intuitive-dsl-engine</artifactId>  
    <version>1.0-SNAPSHOT</version>  
</dependency>

2. Define your Command

Instead of maintaining external grammar files, you define your syntax directly on your Java class using the @DslCommand annotation.

Use @Bind to automatically capture and convert dynamic parameters, and @OnClause to detect structural keywords or flags.

import ch.dbalabs.intuitivedslengine.annotation.Bind;
import ch.dbalabs.intuitivedslengine.annotation.DslCommand;
import ch.dbalabs.intuitivedslengine.annotation.OnClause;

@DslCommand(  
    name = "PROVISION USER",  
    syntax = "PROVISION USER username [ WITH AGE user_age ] { AS ACTIVE | AS SUSPENDED } [ FORCE ] ;"  
)  
public class ProvisionUserCommand implements Runnable {

    // Captured from the input
    @Bind("username")  
    private String username;

    // Automatically converted from String to int
    @Bind("user_age")  
    private int age;

    // Resolves structural alternatives
    @OnClause("AS ACTIVE")  
    private boolean isActive;

    // Detects optional flags
    @OnClause("FORCE")  
    private boolean isForced;

    @Override  
    public void run() {  
        System.out.printf("Provisioning %s (Age: %d, Active: %b, Forced: %b)%n",   
            username, age, isActive, isForced);  
    }  
}

3. Execute the Engine

At startup, the engine compiles your iBNF syntax into an immutable Abstract Syntax Tree (AST). When processing raw input, it performs lightning-fast validation, resolves the variables using MethodHandles (fully GraalVM AOT compatible), and triggers the execution.

import ch.dbalabs.intuitivedslengine.core.IntuitiveDslEngine;
import ch.dbalabs.intuitivedslengine.core.ExecutionContext;

public class Application {
    public static void main(String[] args) {
        // 1. Instantiate the Engine
        IntuitiveDslEngine engine = new IntuitiveDslEngine();  
        
        // 2. Register your command
        engine.register(new ProvisionUserCommand());

        // 3. Create an execution context (used to pass session data, DB connections, etc.)
        ExecutionContext context = ExecutionContext.createDefault();  
        
        // 4. Execute raw string inputs safely
        engine.execute("PROVISION USER 'john.doe' WITH AGE 35 AS ACTIVE FORCE ;", context);
        // Output: Provisioning john.doe (Age: 35, Active: true, Forced: true)
        
        // The engine handles optional paths gracefully
        engine.execute("PROVISION USER 'jane.doe' AS SUSPENDED ;", context);
        // Output: Provisioning jane.doe (Age: 0, Active: false, Forced: false)
    }
}

Next Steps

• Learn how to write powerful grammar rules in the Introduction to iBNF.
• Discover how to inject live data into your grammar using Dynamic Macros (${...}).