PPL (Promotion Policy Langauge)

A domain-specific language for e-commerce promotion management, built with Eclipse Xtext.

Prerequisites

• Eclipse IDE for Java and DSL Developers (2024-12 or later)
• Xtext 2.41.0 (included in the Eclipse DSL package)
• Java 21

Setup

1. Clone the repository.
2. In Eclipse: File > Import > General > Existing Projects into Workspace.
3. Select the repository root. Eclipse should detect these projects:
   • uk.ac.kcl.inf.promodsl (language runtime)
   • uk.ac.kcl.inf.promodsl.ide (IDE services)
   • uk.ac.kcl.inf.promodsl.ui (Eclipse editor integration)
   • uk.ac.kcl.inf.promodsl.tests (test suite)
4. Import all four. Wait for the workspace to build.
5. If there are build errors, right-click uk.ac.kcl.inf.promodsl > Run As > MWE2 Workflow on GeneratePromoDSL.mwe2 to regenerate the language infrastructure.

Try the editor

1. Right-click uk.ac.kcl.inf.promodsl > Run As > Eclipse Application. A second Eclipse instance opens.
2. In the new instance: File > New > Project > General > Project. Name it promo-demo.
3. Copy the files from examples/ into the new project.
4. Open full-store.promo. You should see syntax highlighting and code completion (Ctrl+Space).
5. Open conflict-scenario.promo. You should see validation markers (errors, warnings, info) in the editor. Hover over them to read the messages. Click the lightbulb icon to apply quick-fixes.

Run the interpreter

The interpreter evaluates a .promo file against simulated order scenarios.

1. In the main Eclipse instance, open PromoDSLRunner.java in uk.ac.kcl.inf.promodsl/src/.../interpreter/.
2. Run As > Java Application.
3. By default it loads examples/full-store.promo and runs four order scenarios, printing a breakdown of which promotions applied, which were skipped, and why.

To run against a different file, pass the path as a command-line argument in the Run Configuration.

View the generated code

The code generator produces a standalone PromotionEngine.java from any .promo file.

1. In the runtime Eclipse instance, open any .promo file in the promo-demo project.
2. On save, the generator runs automatically. Check the src-gen/ folder for promodsl/generated/PromotionEngine.java.
3. The generated file has no runtime dependencies and includes a main method you can run directly.

Run the tests

1. In the main Eclipse instance, right-click uk.ac.kcl.inf.promodsl.tests > Run As > JUnit Plug-in Test.
2. Four test suites should pass: parsing, validation, interpreter, and code generator.

Project structure

uk.ac.kcl.inf.promodsl/
  src/.../PromoDSL.xtext          Grammar definition
  src/.../validation/              Validator (well-formedness + semantic checks)
  src/.../interpreter/             Interpreter + conflict resolver + runner
  src/.../generator/               M2T code generator (Xtend)
  src/.../scoping/                 Custom cross-reference scoping
  src/.../util/                    Shared utilities (model traversal, date parsing)
  examples/                        Example .promo files
  model/generated/PromoDSL.ecore   Generated metamodel

uk.ac.kcl.inf.promodsl.ui/
  src/.../quickfix/                Quick-fix provider

uk.ac.kcl.inf.promodsl.tests/
  src/.../tests/                   JUnit 5 test suites

Example

category Electronics
segment StudentDiscount

campaign "Summer Sale 2026"
    from 2026-06-01 until 2026-08-31
{
    promotion "Student Electronics Deal"
        priority 5
        applies-when customer.segment is StudentDiscount
            and product.category is Electronics
            and order.total > 100
        discount 15%
        max-per-customer 2
        channels website, app
        stackable
}