YesNt-Interpreter/docs/library-api.md

YesNt Library API

The YesNt.Interpreter project is a .NET 8 class library. You can reference it from any C# project to embed the YesNt interpreter and run scripts programmatically.

---

Table of contents

1. Adding the reference
2. Running a script file
3. Running an in-memory script
4. Capturing output (debug mode)
5. Adding custom statements
6. Stopping a script
7. Reading registered statements
8. API reference

---

Adding the reference

Add a project reference to YesNt.Interpreter in your .csproj:

<ItemGroup>
  <ProjectReference Include="..\YesNt.Interpreter\YesNt.Interpreter.csproj" />
</ItemGroup>

Then add the using directive:

using YesNt.Interpreter.Runtime;

---

Running a script file

var interpreter = new YesNtInterpreter();
interpreter.Execute("path/to/script.ynt");

Execute is synchronous - it returns when the script finishes (or terminates with an error).

---

Running an in-memory script

Supply a List<string> instead of a file path:

var lines = new List<string>
{
    "var x = 42",
    "print_line The answer is ${x}",
};

var interpreter = new YesNtInterpreter();
interpreter.Execute(lines);

---

Capturing output (debug mode)

Pass isDebugMode: true to suppress direct console writes. Output is delivered through the OnDebugOutput event instead, and OnLineExecuted fires after executed lines.

var interpreter = new YesNtInterpreter();
var output = new System.Text.StringBuilder();

interpreter.OnDebugOutput += text => output.Append(text);
interpreter.OnLineExecuted += args =>
{
    if (args is null)
    {
        // null means execution reached end-of-file (EOF)
        Console.WriteLine("Script reached EOF.");
        return;
    }
    Console.WriteLine($"Line {args.LineNumber}: {args.CurrentLine}");
};

interpreter.Execute(new List<string> { "print_line hello" }, isDebugMode: true);
Console.Write(output);

OnLineExecuted receives a DebugEventArgs with:

Property	Type	Description
LineNumber	int	1-based line number
OriginalLine	string	Raw source text
CurrentLine	string	Text after all substitutions
IsTask	bool	true if executed inside a background task
TaskId	int	Task identifier (0 for the main thread)

OnLineExecuted is invoked with null only when execution reaches end-of-file (EOF). If execution stops via exit, throw, error, or Stop(), no terminal null event is emitted.

---

Adding custom statements

Use AddStatement to register keywords before calling Execute.

Simple keyword at the start of a line

using YesNt.Interpreter.Enums;

var interpreter = new YesNtInterpreter();

interpreter.AddStatement("log", SearchMode.StartOfLine, SpaceAround.End, args =>
{
    Console.WriteLine($"[LOG] {args}");
});

interpreter.Execute(new List<string> { "log Hello from custom statement" });

With a syntax-highlight colour

interpreter.AddStatement("log", SearchMode.StartOfLine, SpaceAround.End,
    ConsoleColor.Cyan,
    args => Console.WriteLine($"[LOG] {args}"));

Using a pre-built StatementAttribute

using YesNt.Interpreter.Attributes;

var attr = new StatementAttribute("log", SearchMode.StartOfLine, SpaceAround.End)
{
    Priority = Priority.VeryLow,
};

interpreter.AddStatement(attr, args => Console.WriteLine($"[LOG] {args}"));

SearchMode values

Value	The keyword matches when…
StartOfLine	the line starts with the keyword
EndOfLine	the line ends with the keyword
Contains	the keyword appears anywhere in the line
Exact	the line is exactly the keyword

SpaceAround values

Value	Space requirement
None	No surrounding spaces required
Start	A space must precede the keyword
End	A space must follow the keyword
StartEnd	Spaces required on both sides

Custom statements run at Priority.Normal by default. Lower priority values run first. Use StatementAttribute.Priority to control ordering relative to built-in statements.

---

Stopping a script

var interpreter = new YesNtInterpreter();

// Start the script on a background thread so we can stop it from this thread.
var thread = new System.Threading.Thread(() =>
    interpreter.Execute(new List<string> { "while True:", "sleep 100", "end_while" }));

thread.Start();
System.Threading.Thread.Sleep(500);
interpreter.Stop();   // signals the script to terminate at the next line boundary
thread.Join();

---

Reading registered statements

StatementInformation returns a read-only snapshot of every registered statement. This is useful for building syntax highlighters or tooling.

var interpreter = new YesNtInterpreter();

foreach (var info in interpreter.StatementInformation)
{
    Console.WriteLine($"{info.Name,-20} {info.SearchMode,-12} color={info.Color}");
}

Each StatementInformation object exposes:

Property	Type	Description
Name	string	The keyword
SearchMode	SearchMode	Where the keyword is matched
SpaceAround	SpaceAround	Required surrounding spaces
Color	ConsoleColor	Syntax-highlight colour
IgnoreSyntaxHighlighting	bool	Whether to skip highlighting
Separator	string?	Optional required sub-string

---

API reference

YesNtInterpreter

public class YesNtInterpreter

Constructor

public YesNtInterpreter()

Creates a new interpreter instance and registers all built-in statements.

Events

public event Action<string>        OnDebugOutput;
public event Action<DebugEventArgs> OnLineExecuted;

Only raised in debug mode (isDebugMode: true). OnLineExecuted receives null only on EOF completion.

Methods

// Execute a .ynt file
public void Execute(string path, bool isDebugMode = false);

// Execute in-memory lines
public void Execute(List<string> lines, bool isDebugMode = false);

// Register a custom statement (full control)
public void AddStatement(StatementAttribute attribute, Action<string> handler);

// Register a custom statement (convenience overloads)
public void AddStatement(string name, SearchMode searchMode, SpaceAround spaceAround, Action<string> handler);
public void AddStatement(string name, SearchMode searchMode, SpaceAround spaceAround, ConsoleColor color, Action<string> handler);

// Request graceful stop
public void Stop();

Properties

// Read-only snapshot of all registered statements
public ReadOnlyCollection<StatementInformation> StatementInformation { get; }