API Reference by Class

API Reference by Class

This reference covers the current stable public API for RuleScript v1.10.0. It is organized by class so host applications can choose the correct entry point without reading release history.

Which Class Should I Use?

Class	Use it for
RuleScriptEngine	Execute scripts, analyze code, create Host Trigger runtimes, register Host Functions, configure imports, breakpoints, and runtime events.
RuntimeContext	Exchange variables between the host and a script.
RuleScriptRuntime	Start, trigger, stop, and inspect a long-running Host Trigger runtime.
RuleScriptDebugSession	Run, pause, continue, step, inspect, stop, or create debug-enabled runtimes.
RuleScriptAnalysisResult	Read diagnostics and symbols returned by strict static analysis.
RuleScriptAnalysisAttempt	Read partial symbols and diagnostics from incomplete code.
RuleScriptFunctionSymbol	Read unified user, imported, host, built-in, and Host Trigger function metadata.
RuleScriptAnalysisCache	Reuse per-document parse and analysis results in editor integrations.
RuleScriptLanguageService	Read regions, documentation, definitions, references, and reusable document analysis.
RuleScriptFormatter	Format valid RuleScript source.
IImportResolver	Load scripts from custom storage.

RuleScriptEngine

Namespace: RuleScript.Core.Runtime

Execution

Member	Function
Execute(string) / Execute(string, RuntimeContext)	Execute script text synchronously.
ExecuteAsync(...)	Execute script text asynchronously; required for async Host Functions.
ExecuteFile(string)	Resolve and execute a script file.
ExecuteFileAsync(...)	Resolve and execute a script file asynchronously.
Stop()	Request cancellation of the current engine execution.

Host Trigger Runtime Creation

Member	Function
CreateRuntime(string, RuntimeContext?)	Create a long-running runtime from script text.
CreateRuntimeFromFile(string, RuntimeContext?)	Create a long-running runtime from a script file.

CreateRuntimeFromFile follows the same WorkingDirectory, ScriptFileExtension, ImportResolver, and import behavior as ExecuteFile.

Configuration

Property	Function
MaxLoopIterations / LoopIterationLimitEnabled	Loop iteration limit.
ExecutionTimeout / ExecutionTimeoutEnabled	Elapsed execution timeout.
MaxCallDepth / CallDepthLimitEnabled	User function call-depth limit.
MaxExecutedStatements / StatementExecutionLimitEnabled	Total statement execution limit.
WorkingDirectory	Base directory for relative files and imports.
ScriptFileExtension	Extension appended to extensionless paths; default is .rules.
ImportResolver	Resolver used by file execution, runtime creation, imports, and analysis.
StepExecution	Pause before executable statements when handlers request stepping.

Host Functions

Member	Function
RegisterFunction(...)	Register or replace a synchronous Host Function.
RegisterFunctionAsync(...)	Register or replace an asynchronous Host Function.
RegisterFunctions(object)	Register decorated public instance methods.
UnregisterFunction(string)	Remove sync and async registrations with the name.
ClearFunctions()	Remove all Host Functions.
RegisteredFunctionNames	Snapshot of registered Host Function names.
RegisteredFunctionSymbols	Unified function symbols for registered Host Functions.

RegisteredHostFunctions remains available as a compatibility projection. New code should prefer RegisteredFunctionSymbols.

Analysis

Member	Function
Analyze(string)	Strictly parse and analyze source; throws on syntax errors.
Analyze(string, line, column)	Strict analysis plus cursor-visible variables.
TryAnalyze(string)	Best-effort analysis with partial symbols and diagnostics.
TryAnalyze(string, line, column)	Best-effort cursor-aware analysis.
SetKnownVariable(name, type)	Add or replace a host-provided analysis variable.
RemoveKnownVariable(name)	Remove one known variable.
ClearKnownVariables()	Remove all known variables.
KnownVariables	Snapshot of host-provided analysis variables.

Breakpoints and Events

Member	Function
AddBreakpoint(...)	Add a line breakpoint, optionally scoped to a file and condition.
RemoveBreakpoint(...)	Remove breakpoints at a file and line.
ClearBreakpoints()	Remove every breakpoint.
Breakpoints	Snapshot of registered breakpoints.
RuntimeEventHandler	Synchronous runtime-event callback.
RuntimeEventHandlerAsync	Asynchronous runtime-event callback.

RuleScriptRuntime

Namespace: RuleScript.Core.Runtime

public sealed class RuleScriptRuntime
{
    public RuntimeContext Context { get; }
    public RuleScriptRuntimeState State { get; }
    public IReadOnlyList<RuleScriptFunctionSymbol> HostTriggers { get; }

    public Task StartAsync(CancellationToken cancellationToken = default);
    public Task StopAsync();
    public ValueTask<RuleScriptTriggerReceipt> TriggerAsync(
        string name,
        IReadOnlyList<object?>? args = null,
        CancellationToken cancellationToken = default);
}

StartAsync begins execution. TriggerAsync enqueues a named Host Trigger request. StopAsync cancels the runtime and waits for shutdown.

TriggerAsync throws when the runtime is not running, the script has no active trigger task, or the requested Host Trigger name is not registered.

RuleScriptRuntimeState

Values: Created, Running, Stopping, Stopped, Faulted.

RuleScriptTriggerReceipt

public sealed record RuleScriptTriggerReceipt(long SequenceId, string Name);

Returned after a trigger request is accepted into the runtime queue.

RuntimeContext

Namespace: RuleScript.Core.Runtime

Member	Function
Set(name, value)	Add or replace a variable.
Get(name) / Get<T>(name)	Read a variable; throws when missing.
TryGet(name, out value)	Read without throwing.
GetOrDefault(...)	Read with fallback.
Contains(name)	Test whether a variable exists.
Remove(name) / Clear()	Remove one or all variables.
Variables	Read-only snapshot of runtime values.
VariableNames	Sorted name snapshot.
CurrentLocation	Last source location reported during execution.

RuleScriptDebugSession

Namespace: RuleScript.Core.Runtime

Member	Function
RunAsync(...)	Run script text on a background task.
RunFileAsync(...)	Run a script file on a background task.
CreateRuntime(string, RuntimeContext?)	Create a debug-enabled Host Trigger runtime from text.
CreateRuntimeFromFile(string, RuntimeContext?)	Create a debug-enabled Host Trigger runtime from file.
WaitForPauseAsync(...)	Wait for breakpoint or step pause.
Continue()	Resume execution.
StepOver()	Execute one statement and pause before the next.
Stop()	Cancel a running or paused session.
CurrentPause	Most recent pause event.
CurrentSnapshot	Globals, locals, and call stack at pause.
RuntimeEvent	Event raised for runtime notifications seen by the session.

Analysis Results

RuleScriptAnalysisResult

Property	Content
Variables / VariableNames	Discovered variables and names.
VisibleVariables / VisibleVariableNames	Cursor-visible variables.
Functions	Unified function symbols for user, imported, host, and built-in functions.
HostTriggers	User functions marked with @HostTrigger.
ImportAliases	Import aliases declared by source.
Diagnostics	Semantic diagnostics.

Compatibility projections such as UserFunctions, HostFunctions, BuiltinFunctions, and name-only lists remain available, but new integrations should use Functions.

RuleScriptAnalysisAttempt

Property	Content
Success	True when analysis has no error diagnostics.
Symbols	Partial or complete RuleScriptAnalysisResult.
Diagnostics	Non-throwing syntax and semantic diagnostics.

Function Symbols

RuleScriptFunctionSymbol

Important properties include:

• Name
• Signature
• Parameters
• ReturnType
• DeclaredReturnType
• IsReturnTypeDeclared
• IsReturnTypeNullable
• IsExported
• Documentation
• Kind
• Location
• Range
• HostMetadata
• BuiltinMetadata
• ImportMetadata
• HostTriggerMetadata

RuleScriptFunctionKind values are User, Imported, Host, and Builtin.

RuleScriptHostTriggerMetadata is:

public sealed record RuleScriptHostTriggerMetadata(string Name);

Parameter and Type Symbols

Class	Content
RuleScriptParameterSymbol	Parameter Name and Type.
RuleScriptVariableSymbol	Variable Name, Type, IsReadOnly, and IsExported.
RuleScriptValueType	Unknown, Any, Null, Number, String, Boolean, Array, Object.

Editor APIs

Member	Function
RuleScriptFormatter.Format(source)	Format valid source.
RuleScriptLanguageService.GetRegions(source)	Return #region ranges.
RuleScriptLanguageService.GetFunctionDocumentation(source, name)	Return attached /// documentation.
RuleScriptLanguageService.GetDefinition(...)	Return definition metadata at a one-based source position.
RuleScriptLanguageService.FindReferences(...)	Return references at a one-based source position.
RuleScriptLanguageService.AnalyzeDocument(...)	Parse and analyze once for reuse.
RuleScriptAnalysisCache.GetOrAnalyze(path, source)	Cache per-document analysis.

Diagnostics and Source Classes

Class	Function
RuleScriptDiagnostic	Editor diagnostic with message, code, severity, token, file, location, and range.
RuleScriptDiagnosticCodes	Stable diagnostic constants.
RuleScriptDiagnosticSeverity	Info, Warning, and Error.
RuleScriptException	Base class for thrown RuleScript failures.
SyntaxException	Lexer or parser failure.
RuntimeException	Runtime or Host Function failure.
RuleScriptSourceLocation	File plus optional 1-based line and column.
RuleScriptSourceRange	Half-open start/end source range.

Runtime Event and Debug Classes

RuleScriptRuntimeEvent exposes Kind, Location, Message, Value, Exception, Range, and DebugSnapshot.

RuleScriptRuntimeEventKind values are:

• CurrentLineChanged
• Print
• BreakpointHit
• StepPaused
• Error

RuleScriptExecutionDirective values are Continue and StepOver.

RuleScriptBreakpoint contains file, line, and optional condition. RuleScriptDebugSnapshot contains location, globals, locals, and call stack.

Import Classes

IImportResolver loads files from custom storage:

public interface IImportResolver
{
    string GetFullPath(string path);
    bool Exists(string path);
    string ReadAllText(string path);
}

FileSystemImportResolver is the default local-file implementation.

Low-Level Language Classes

Most hosts should use RuleScriptEngine. Lower-level tooling can use:

• Lexer
• Token
• TokenType
• Parser
• RuleScriptParseResult
• Interpreter
• BuiltinFunctions
• RuntimeValue
• AST records such as Statement, Expression, FunctionDeclarationStatement, ParallelStatementSyntax, ParallelExpressionSyntax, and TaskBlockSyntax

TaskBlockSyntax can represent ordinary tasks and trigger tasks.

Related Documentation

• Getting Started
• Language Guide
• Host Trigger
• Host Integration
• Built-in Function Reference
• Typed Functions and Analysis
• Debugging and Analysis