OutWit.Engine.Parser 1.0.1

OutWit.Engine.Parser

ANTLR-based parser for WitEngine job scripts.

Overview

This package provides the script parser for WitEngine. It converts WitJob script text into executable job objects using ANTLR4 for lexing and parsing.

Installation

dotnet add package OutWit.Engine.Parser

Features

• Full WitJob script syntax support
• Job parameters and variables
• Activity calls with arguments
• Composite activities with blocks
• Transform expressions (arrow syntax)
• Conditions and arrays
• Comments

Script Syntax

Job Definition

Job:JobName(Type:param1, Type:param2)
{
    ~ Job body ~
}

Variable Declaration

Int:counter = 0;
String:message = "Hello";
Boolean:flag = true;
Object:data;

Activity Calls

~ Simple activity ~
Trace("Message", false);

~ Activity with return value ~
Int:result = Calculate(10, 20);

~ Composite activity with block ~
Loop(5)
{
    Trace("Iteration", false);
}

Transform Expressions

~ Arrow syntax for transforms ~
IntCollection:output = ForEach(x in input) => Transform(x);

Conditions

If(value > 10)
{
    Trace("Greater", false);
}

Arrays

IntCollection:list = IntCollection([1, 2, 3, 4, 5]);

Comments

~ This is a comment ~

Usage

Basic Parsing

var parser = new ParsingManager(controllerManager, jobFactory, logger);

string script = @"
    Job:Example()
    {
        Int:x = 42;
        Trace(""Value is "" + x, false);
    }
";

IWitJob job = parser.Parse(script);

Integration with WitEngine

The parser is automatically used by WitEngine.Compile():

WitEngine.Instance.Reload();

var job = WitEngine.Instance.Compile(@"
    Job:MyJob()
    {
        Int:result = Calculate(10);
    }
");

Grammar

The parser uses ANTLR4 with the WitJob.g4 grammar file. Key grammar rules:

Architecture

Script Text
    |
    v
[ANTLR Lexer] --> Tokens
    |
    v
[ANTLR Parser] --> Parse Tree
    |
    v
[JobBuilderVisitor] --> IWitJob
    |
    +-- Uses IWitControllerManager to create activities
    +-- Uses IWitJobFactory to create job instances

Project Structure

OutWit.Engine.Parser/
  Grammars/
    WitJob.g4              - ANTLR grammar definition
  Managers/
    ParsingManager.cs      - Public parsing API
  Visitors/
    JobBuilderVisitor.cs   - Parse tree to job converter (internal)
  Utils/
    ParsingUtils.cs        - Helper extensions (internal)
  MakeInternal.ps1         - Script to make ANTLR code internal

Build Process

ANTLR code generation happens during build:

1. Antlr4Compile target generates C# code from .g4 files
2. MakeAntlrGeneratedCodeInternal target runs MakeInternal.ps1
3. PowerShell script changes public to internal for obfuscation

Dependencies

• OutWit.Engine.Data
• Antlr4.Runtime.Standard
• Antlr4BuildTasks (build-time only)

License

This software is licensed under the Non-Commercial License (NCL).

• Free for personal, educational, and research purposes
• Commercial use requires a separate license agreement
• Contact licensing@ratner.io for commercial licensing inquiries

See the full LICENSE file for details.