smallD 🧸

Language Engineering as a Toy Language — the name is Small D. Integrated with the Eclipse Debug UI 🐞, it provides a simple interpreter and debugger.

Contents

• Overview
• What and Why is small D?
• Blueprint
• Features of the small D Project
  • 1. small DSL language with Xtext
  • 2. Debuggable Interpreter & Debugger
  • 3. Integration with Eclipse Debug UI
  • 4. Eclipse Product for Deploying
  • 5. Java & C# Generator
• small D Specification
  • Limitations
  • Standard Functions
• Class Hierarchy & Execution Flow
• Setup & Deploy
  • Setup
  • Deploy Interpreter
  • Equinox Configuration
• Troubleshooting
  • Debug Ports
  • Known Issues
• References
• License

Overview 🔍

1. org.xtext.labs.mydsl.interpreter is fully developed and designed based on parsing results. It's not a built-in feature of the Xtend framework.
2. The interpreter is integrated with the Eclipse Debug UI — this is an independent module, not relying on Xtend.
3. Code editor functionalities are provided and fixed by the Xtend framework.
4. Minimap view and deployment are implemented via Eclipse plugin development.
5. ANTLR parses the language definition file at org.xtext.labs.mydsl/src/org/xtext/labs/Mydsl.xtext. Once parsing is complete and the AST is generated, it becomes the foundation for all language customization and engineering.

What and Why is small D? ❓

Small D is a toy language for exploring Language Engineering.
“D” stands for DSL (Domain-Specific Language). Unlike general-purpose languages like C or Java, DSLs are tailored for specific tasks or domains.

Normally, implementing a new language doesn’t make sense for time- or budget-constrained projects. But sometimes, it's necessary. Unfortunately, simple and practical references are hard to find, and most DSLs are proprietary, making examples rare.

Even finding debugger documentation often leads to low-level gdb or obscure references — not practical for newcomers. That’s why I created a small language with essential IDE features for learning purposes. I hope it helps you, too. 🙌

• What: Lexer 🪓 → Parser 📜 → Interpreter 🧠 → Debuggable Interpreter 🐛 → Eclipse Debug UI 🎛️
• Intermediate Products: Token (lexer) → AST (parser) → Call Stack & Symbol Table (interpreter)
• How: Using Xtext Framework 🛠️ + Custom Implementations 💡

Features of the small D Project 🌟

1. small DSL language with Xtext ✍️

🧱 Xtext documentation is sparse, sometimes outdated, and the community is small — but it's still better than nothing.

Features:

1. Error Checking
2. Semantic/Syntax Coloring
3. Outline View
4. Hover Tooltips
5. Auto-completion (Proposal)
6. Scoping, Cross-referencing, Labeling
7. Minimap View
8. Formatting, 🛠️ Quick Fix
9. Folding, 📌 Go-To Declaration

2. Debuggable Interpreter & Debugger 🐛

• Features a 🧮 call stack, 🧾 symbol table, and AST (Abstract syntax tree)
• Interpreter can suspend ⏸️ and resume ▶️ based on commands

3. Integration with Eclipse Debug UI 🎛️

• Communication with Eclipse Debug UI:
  • Request Socket <=> Response (data)
  • Event Socket

4. Eclipse Product for Deploying 🚀

• Use the Eclipse Product export wizard 🧙‍♂️
• Project: org.xtext.labs.mydsl.product
• File: DSLDeveloper.product

🛠️ For installers: Use Inno Setup — free and easy 💸

5. Java & C# Generator 🔄

• DSL code can be converted to Java and C# (though not perfectly, a feature of Xtend Framework)
• In C#, all function parameters are converted using ref (demonstrates call-by-reference) 🔁 — 💡 Pascal is a well-known language that supports call-by-reference.
• org.xtext.labs.mydsl/src/org/xtext/labs/generator/MydslGenerator.xtend → Java generator
• org.xtext.labs.mydsl/src/org/xtext/labs/generator/MydslGeneratorCS.xtend → C# generator

small D Specification 📚

Sample code can be found in org.xtext.labs.mydsl.product/src

• num, string, bool
• Multi-dimensional arrays
• if ~ else (no else if)
• while loop only
• Function definition: def function_name() {}
• launch_main is the entry point
• Scope resolution: local → global fallback
• No object-oriented features

Limitations ⚠️

• Not supporting Direct function calls in expressions

  ❌ printstr(numtostr(b))
  ✅

  a = numtostr(b)
  printstr(a)

Standard Functions (for testing only) 🧪

Function	Description
printstr(varStr)	🖨️ Print string
strjoin(var1, var2)	🔗 Join two strings
varArr = strsplit(var1, "delimiter")	Split string into array
varStr = numtostr(varNum)	Convert number to string
getargs(index)	Get command line argument

Class Hierarchy & Execution Flow

The interpreter module (org.xtext.labs.mydsl.interpreter) is designed with a layered architecture for processing DSL statements and managing debugging state.

classDiagram
    direction TB
    
    %% Base Thread Management
    class ThreadLauncher {
        <<abstract>>
        #Thread t
        #boolean suspended
        +start()
        +resume()
        +suspend()
    }
    
    %% Process Handler for Debugging
    class AbstractProcessHandler {
        <<abstract>>
        #ThreadStateForDebugging(BodyStatement)
        #waitOrResumeBodyExpr(BodyStatement)
        +suspend()
        +resume()
    }
    
    %% Body Statement Switcher
    class AbstractBodySwitcher {
        +executor(BodyStatement, String)
        #executeTerminalOrMethod(TerminalOrMethod, String, AbstractStackHelper)
        +run()
    }
    
    %% Stack Helper
    class AbstractStackHelper {
        <<abstract>>
        #boolean isBrk
        #boolean isRtn
        #Object lastFunctionReturn
        #lookupStackItem(String)
        #lookupSymbolByTerminal(Terminal, String)
        #DecoupleTerminal(Terminal, String)
        #pushCallStackItem(String)
    }
    
    %% Logical Helper
    class AbstractLogicalHelper {
        <<abstract>>
        #evaluateLogical(boolean, String, boolean)
        #evaluateCondition(Object, String, Object)
    }
    
    %% Concrete Runners
    class DirectRunner {
        -DSLProgram program
        +run()
        -execute(mainDeclared)
        -execute(EList~varDeclared~)
    }
    
    class Debuggable {
        -DSLProgram program
        -Socket event
        +run()
        -execute(mainDeclared)
        -execute(EList~varDeclared~)
    }
    
    %% Body Handlers
    class IBody {
        <<interface>>
        +execute(String funcId)
    }
    
    class BodyVarExpression {
        +execute(String)
    }
    
    class BodyVarDeclared {
        +execute(String)
    }
    
    class BodyMethodCall {
        +execute(String)
    }
    
    class BodyIf {
        +execute(String)
    }
    
    class BodyWhile {
        +execute(String)
    }
    
    class BodyVarReturn {
        +execute(String)
    }
    
    class BodyBrk {
        +execute(String)
    }
    
    %% Inheritance
    ThreadLauncher <|-- AbstractProcessHandler
    AbstractProcessHandler <|-- AbstractBodySwitcher
    AbstractBodySwitcher <|-- DirectRunner
    AbstractBodySwitcher <|-- Debuggable
    
    AbstractStackHelper <|-- AbstractLogicalHelper
    AbstractLogicalHelper <|-- BodyVarExpression
    AbstractLogicalHelper <|-- BodyIf
    AbstractLogicalHelper <|-- BodyWhile
    AbstractStackHelper <|-- BodyVarDeclared
    AbstractStackHelper <|-- BodyVarReturn
    AbstractStackHelper <|-- BodyMethodCall
    AbstractStackHelper <|-- BodyBrk
    
    IBody <|.. BodyVarExpression
    IBody <|.. BodyVarDeclared
    IBody <|.. BodyMethodCall
    IBody <|.. BodyIf
    IBody <|.. BodyWhile
    IBody <|.. BodyVarReturn
    IBody <|.. BodyBrk

Loading

flowchart TD
    subgraph Initialization[Program Setup]
        A["Parse DSL File"] --> B["Create DSLProgram AST"]
        B --> C["Debuggable Instance<br/>(AbstractBodySwitcher)"]
    end
    
    subgraph Execution_Control_Loop[Debugging & Execution Control]
        C --> D{"Is Debugging Active?"};
        
        D -- Yes (Debuggable) --> E["Listen on Socket<br/>(EventBroker/EventHandler)"];
        D -- No (DirectRunner) --> I;
        
        E --> F{"Received Command?"};
        
        F -- Step/Resume --> G["AbstractProcessHandler.resume()<br/>Release Wait"];
        F -- Suspend/Breakpoint Hit --> H["AbstractProcessHandler.suspend()<br/>Wait for Command"];
    end
    
    subgraph Statement_Execution[Core Interpreter Cycle]
        G --> I["AbstractBodySwitcher.executor(Statement)"];
        H --> I;
        
        I --> J{"Statement Type?"};
        
        J -- Var/Method Call --> K["Body* Handlers<br/>(AbstractStackHelper)"];
        J -- If/While/Logical --> L["BodyIf/While<br/>(AbstractLogicalHelper)"];
        J -- Return/Break --> M["BodyReturn/Brk<br/>(Update Stack State)"];
    end
    
    subgraph Runtime_State["State Management (AbstractStackHelper)"]
        K & L & M --> N["Lookup/Update CallStack"];
        N --> O["Check for Breakpoints<br/>(If suspended, go to H)"];
    end
    
    O --> I;
    
    style C fill:#aaf,stroke:#333
    style I fill:#fcc,stroke:#333
    style H fill:#faa,stroke:#333

Loading

Component	Description
ThreadLauncher	Base class for thread lifecycle management (start, suspend, resume)
AbstractProcessHandler	Handles debugging state transitions and breakpoint detection
AbstractBodySwitcher	Routes body statements to appropriate handlers based on type
AbstractStackHelper	Utilities for call stack and symbol table manipulation
AbstractLogicalHelper	Logical and comparison operation utilities
DirectRunner	Runs interpreter without debugging support
Debuggable	Runs interpreter with full debugging support
EventBroker	Socket server for Eclipse Debug UI communication
EventHandler	Processes debug commands (resume, step, suspend, breakpoints)

Setup & Deploy ⚙️

1. Import the project into Eclipse
2. Export org.xtext.labs.mydsl.interpreter as a Runnable JAR
3. Copy the JAR
4. Open DSLDeveloper.product
5. Use Eclipse Product Export Wizard (in Overview tab)
6. Create a new DSL file from MyDsl project

• Export debugDSL.jar from org.xtext.labs.mydsl.interpreter
• Copy to: D:\DSLDeveloper\debug\debugDSL.jar (example path)

Troubleshooting 🔧

Debug Ports 📡

Ports used:

• 29777, 29888

If port error occurs:

cmd> netstat -ona | findstr 0.0:29777
TCP    0.0.0.0:29777      0.0.0.0:0      LISTENING       3116

cmd> taskkill /F /PID 3116

🛑 PID 3116 will be terminated

Known Issues ⚠️

• Main function arguments set via Launch Configuration
• Use DSL Editor (not Xtext Editor) for debugging
• Dev environment: Xtext 2.12.0, Java SE 1.8, Eclipse Neon.3
• Minimap View: https://github.com/apauzies/eclipse-minimap-view

Variables view empty after suspend:

Workaround: switch view or reload it. Details

References 🔗

Topic	Resources
Xtext	eclipse.org/Xtext • LorenzoBettini (GitHub) • hishidama.home (JP)
Language Engineering	Let's Build a Simple Interpreter
Eclipse Debugger	Eclipse Debugger How-to • Vogella Tutorial • Code and Me
Deploying as Product	Robert Wloch's Tutorial

License 📜

© 2017 kimtth