🖥️ Simple Machine Language (SML) Interpreter

A stack-based interpreter written in Java, demonstrating software engineering principles including reflection API, dependency injection, and object-oriented design patterns.

📋 Table of Contents

🚀 Project Overview
🏗️ Architecture
📝 SML Language Features
🛠️ Technical Implementation Highlights
🚀 Getting Started
📁 Project Structure
🧪 Testing
🎯 Design Patterns and Concepts
🔧 Technologies Used
📈 Learning Outcomes
🤝 Extending the Interpreter
📧 Contact
🙏 Acknowledgements

🚀 Project Overview

SML is a simple assembly-like programming language interpreter that operates on a stack-based execution model. The project demonstrates object-oriented design principles, reflection usage, and dependency injection patterns.

Key Features

🏗️ Stack-based Execution: Implements an execution environment with method frames, operand stacks, and program counters
⚙️ Complete Instruction Set: Supports arithmetic operations, control flow, method invocation, and variable management
🔍 Reflection-based Instruction Factory: Uses Java reflection to instantiate instruction objects dynamically
🌱 Spring Dependency Injection: Uses Spring Framework for component management
🧬 Abstract Class Hierarchies: Implements sealed classes and inheritance patterns to reduce code duplication
🧪 Comprehensive Testing: Unit tests for instruction implementations and core components

🏗️ Architecture

The interpreter follows a layered architecture for executing SML programs:

graph TD
    A[SML Source File] --> B[SMLTranslator]
    B --> C[Machine]
    C --> D[Frame Stack]
    D --> E[Method Execution]
    
    B --> F[SMLInstructionFactory]
    F --> G{Instruction Type}
    
    G --> H[CalculateInstruction<br/>Sealed Abstract]
    G --> I[ComparisonInstruction<br/>Sealed Abstract]
    G --> J[Other Instructions]
    
    H --> K[Math Operations<br/>add, sub, mul, div]
    I --> L[Comparisons<br/>if_cmpgt, if_cmpeq]
    J --> M[Stack & Flow<br/>load, store, push<br/>goto, invoke, return, print]
    
    style F fill:#e1f5fe
    style H fill:#f3e5f5
    style I fill:#f3e5f5
    style B fill:#e1f5fe
    
    classDef sealed fill:#f3e5f5,stroke:#9c27b0
    classDef spring fill:#e1f5fe,stroke:#2196f3
    
    class H,I sealed
    class F,B spring

Core Components

Machine: Executes the fetch-decode-execute cycle and manages program execution
Frame: Represents method execution context with local variables and operand stack
SMLTranslator: Parses SML source code and builds the internal program representation
SMLInstructionFactory: Uses reflection to dynamically instantiate instruction objects
Instruction (Abstract): Base class for all SML instructions with polymorphic execution
CalculateInstruction (Sealed): Abstract base for arithmetic instructions
ComparisonInstruction (Sealed): Abstract base for comparison instructions

📝 SML Language Features

Instruction Set

Category	Instructions	Description
Arithmetic	`add`, `sub`, `mul`, `div`	Basic mathematical operations
Stack Operations	`push`, `load`, `store`	Stack and variable manipulation
Control Flow	`goto`, `if_cmpgt`, `if_cmpeq`	Branching and jumps
Method Management	`invoke`, `return`	Method calls and returns
I/O	`print`	Output operations

Example Program

Here's a recursive Fibonacci implementation in SML:

@main:
   push 10
   invoke @fib
   print
   push 1
   return

@fib: n
    load n
    push 1
    if_cmpgt L7
    push 1
    return
L7: load n
    push 1
    sub
    invoke @fib
    load n
    push 2
    sub
    invoke @fib
    add
    return

🛠️ Technical Implementation Highlights

1. Reflection-Based Instruction Factory

The instruction factory uses reflection to dynamically instantiate instructions based on opcode:

// Dynamically find and instantiate instruction classes
for (Class<?> instruction : instructionClasses) {
    Field[] fields = instruction.getDeclaredFields();
    for (Field field : fields) {
        if (field.getName().equals("OP_CODE")) {
            String opcodeValue = String.valueOf(field.get(null));
            if (opcodeValue.equals(opcode)) {
                return buildInstruction(label, programInstruction, instruction);
            }
        }
    }
}

2. Spring Dependency Injection Configuration

<bean id="instruction-factory" class="sml.SMLInstructionFactory">
    <constructor-arg>
        <list>
            <value>sml.instruction.AdditionInstruction</value>
            <value>sml.instruction.LoadInstruction</value>
            <!-- Additional instruction types configured in beans.xml -->
        </list>
    </constructor-arg>
</bean>

3. Sealed Class Hierarchies

Using modern Java sealed classes to control inheritance:

public sealed abstract class CalculateInstruction extends Instruction
        permits AdditionInstruction, DivisionInstruction, 
                MultiplicationInstruction, SubtractionInstruction {
    
    // Pattern matching with switch expressions
    Function<CalculateInstruction,Integer> calculate = c ->
        switch (c) {
            case AdditionInstruction a -> Math.addExact(a.value1, a.value2);
            case SubtractionInstruction s -> Math.subtractExact(s.value1, s.value2);
            case MultiplicationInstruction m -> Math.multiplyExact(m.value1, m.value2);
            case DivisionInstruction d -> d.value1 / d.value2;
        };
}

🚀 Getting Started

Prerequisites

Java 21 or higher
Maven 3.6+

Local Development Setup

Clone the repository

git clone https://github.com/yourusername/sml-interpreter.git
cd sml-interpreter

Install dependencies and compile
```
mvn clean compile
```

Run sample programs

# Fibonacci example (calculates 10th Fibonacci number)
java -cp target/classes RunSml resources/test1.sml

# Alternative implementation example
java -cp target/classes RunSml resources/test2.sml

Run all tests
```
mvn test
```

Generate test reports

mvn surefire-report:report
# View reports in target/site/surefire-report.html

IDE Setup

IntelliJ IDEA / Eclipse:

Import as Maven project
Set Project SDK to Java 21
Enable annotation processing for Spring
Run configuration: Main class RunSml, Program arguments resources/test1.sml

📁 Project Structure

src/
├── main/java/
│   ├── RunSml.java                    # Main entry point
│   └── sml/
│       ├── Machine.java               # Interpreter execution engine
│       ├── Frame.java                 # Execution frame
│       ├── Instruction.java           # Abstract instruction base
│       ├── SMLTranslator.java         # Source code parser
│       ├── SMLInstructionFactory.java # Reflection-based factory
│       └── instruction/               # Instruction implementations
│           ├── CalculateInstruction.java    # Sealed abstract class
│           ├── ComparisonInstruction.java   # Sealed abstract class
│           ├── AdditionInstruction.java     # Concrete arithmetic
│           ├── LoadInstruction.java         # Variable operations
│           └── [other instructions...]
└── test/
    └── sml/                          # Unit tests
        ├── instruction/              # Instruction-specific tests
        ├── MachineTest.java
        ├── MethodTest.java
        └── SymbolTableTest.java
resources/
├── beans.xml                         # Spring DI configuration  
├── test1.sml                         # Fibonacci example
└── test2.sml                         # Additional examples

🧪 Testing

The project includes comprehensive unit tests covering:

Test Coverage

Instruction Tests: CalculateInstructionTest, ComparisonInstructionTest, LoadInstructionTest
Core Functionality: MachineTest, MethodTest, SymbolTableTest
Integration Tests: End-to-end program execution

Running Tests

# Run all tests
mvn test

# Run specific test class
mvn test -Dtest=CalculateInstructionTest

# Run tests with verbose output
mvn test -Dtest=* -DforkCount=1 -DreuseForks=false

# Generate coverage report
mvn jacoco:report

Example Test Scenarios

✅ Arithmetic Operations: Addition, subtraction, multiplication, division
✅ Control Flow: Conditional branching, goto statements
✅ Method Invocation: Recursive calls, parameter passing
✅ Variable Management: Load/store operations, scope handling
✅ Error Handling: Invalid operations, stack underflow

🎯 Design Patterns and Concepts Implemented

🏭 Abstract Factory: SMLInstructionFactory for creating instruction instances
🔒 Sealed Classes: CalculateInstruction and ComparisonInstruction with controlled inheritance
📋 Template Method: Abstract instruction classes defining execution patterns
💉 Dependency Injection: Spring-managed components (@Component, @Autowired)
🔍 Reflection: Dynamic class loading and field access for instruction creation
🎯 Pattern Matching: Modern Java switch expressions with sealed classes

🔧 Technologies Used

Core Technologies

Java 21: Modern Java features including sealed classes and pattern matching
Spring Boot 3.4.3: Dependency injection framework
Spring Context: Bean management and configuration
Maven: Build automation and dependency management

Testing & Quality

JUnit: Unit testing framework
Java Reflection API: Dynamic class loading and field access

📈 Learning Outcomes

This project demonstrates:

🔧 Modern Java Features: Sealed classes, pattern matching, switch expressions
🏗️ Object-Oriented Design: Abstract classes, inheritance hierarchies, polymorphism
🔍 Reflection API: Dynamic class loading, field access, constructor invocation
🌱 Spring Framework: Dependency injection, component scanning, XML configuration
🏛️ Software Architecture: Clean separation of concerns, extensible design
🧪 Testing: Unit test coverage with JUnit
⚙️ Build Tools: Maven project structure and dependency management

🤝 Extending the Interpreter

The architecture allows easy extension by:

Creating new instruction classes extending the appropriate abstract base
Adding the class name to the Spring beans configuration
The reflection-based factory automatically handles instantiation

Example: Adding a Modulo Operation

public non-sealed class ModuloInstruction extends CalculateInstruction {
    public static final String OP_CODE = "mod";
    
    public ModuloInstruction(Label label) { 
        super(label, OP_CODE); 
    }
}

Then add to beans.xml:

<value>sml.instruction.ModuloInstruction</value>

📧 Contact

Queenie Lee - Software Developer
📧 queenie.lee[at]live.ca
🔗 GitHub Portfolio
💼 Project Repository

🙏 Acknowledgements

This project demonstrates advanced Java programming concepts within a provided educational framework from the Software Design and Programming course.

Architecture & Implementation

Framework Foundation: Built upon a robust architectural skeleton including core VM components (Machine, Frame, Method, SymbolTable) and parsing infrastructure, allowing focus on advanced implementation techniques.

🔧 Key Technical Implementations:

Instruction System: Complete implementation of all concrete instruction classes with polymorphic execution
Sealed Class Hierarchies: CalculateInstruction and ComparisonInstruction using modern Java pattern matching
Reflection-Based Factory: Dynamic instruction instantiation using Java reflection API
Spring Integration: Dependency injection implementation with @Component and @Autowired patterns
Testing Suite: Comprehensive unit tests covering instruction implementations and core functionality
Modern Java Features: Leveraged Java 21 sealed classes, pattern matching, and switch expressions

🎯 Technical Focus Areas:

Code Extension & Modification: Working with existing architectural patterns
Advanced OOP: Abstract class hierarchies and polymorphic design
Reflection API: Dynamic object creation and field access
Dependency Injection: Spring Framework integration patterns
Test-Driven Development: Comprehensive unit test coverage

Resources & Documentation

Java Language Specifications for sealed classes and pattern matching implementation
Spring Framework Documentation for dependency injection best practices
Course Materials for foundational architecture and advanced Java concepts

Note: This project showcases the ability to work with existing codebases while implementing sophisticated features - a crucial skill in professional software development.

Built with ❤️ using Java 21, Spring Framework, and Maven

Stack-based interpreter for SML assembly language in Java. Features reflection API, Spring dependency injection, sealed classes, and modern design patterns. Demonstrates advanced OOP and enterprise development practices.

Name		Name	Last commit message	Last commit date
Latest commit History 50 Commits
resources		resources
src/main/java		src/main/java
test/sml		test/sml
.gitignore		.gitignore
README.md		README.md
pom.xml		pom.xml

Folders and files

Latest commit

History

Repository files navigation