Core Lua runtime type definitions for a RoleplayFramework embedded Lua interpreter. Declares the LuaFunction base type, the C#-backed LuaNativeClosure, the script LuaClosure (prototype, upvalues, environment), a boxed Cell for upvalue capture, and the LuaException hierarchy (syntax, runtime with LuaValue error object and traceback, and the uncaughtable instruction-budget exception).
using System;
using RoleplayFramework.Lua.Compiler;
namespace RoleplayFramework.Lua;
/// <summary>Signature for host (C#) functions callable from Lua.</summary>
public delegate LuaValue[] LuaNativeFunction( LuaState state, LuaValue[] args );
public abstract class LuaFunction
{
public abstract string Name { get; }
}
/// <summary>A function implemented in C# and exposed to Lua.</summary>
public sealed class LuaNativeClosure : LuaFunction
{
readonly string _name;
public LuaNativeFunction Body { get; }
public LuaNativeClosure( string name, LuaNativeFunction body )
{
_name = name;
Body = body ?? throw new ArgumentNullException( nameof( body ) );
}
public override string Name => _name;
}
/// <summary>A Lua function: compiled prototype + captured upvalues + environment table.</summary>
public sealed class LuaClosure : LuaFunction
{
internal FunctionProto Proto { get; }
internal Cell[] Upvalues { get; }
public LuaTable Env { get; }
internal LuaClosure( FunctionProto proto, Cell[] upvalues, LuaTable env )
{
Proto = proto;
Upvalues = upvalues;
Env = env;
}
public override string Name => Proto.Name;
public string ChunkName => Proto.ChunkName;
public int LineDefined => Proto.Line;
}
/// <summary>A boxed variable. Each execution of a local declaration creates a fresh cell so closures capture per-iteration values.</summary>
internal sealed class Cell
{
public LuaValue Value;
public Cell() { }
public Cell( LuaValue v ) { Value = v; }
}
/// <summary>Base for all script errors surfaced to the host.</summary>
public class LuaException : Exception
{
public LuaException( string message ) : base( message ) { }
}
/// <summary>Compile-time error with chunk and line.</summary>
public sealed class LuaSyntaxException : LuaException
{
public string ChunkName { get; }
public int Line { get; }
public LuaSyntaxException( string chunk, int line, string message )
: base( $"{chunk}:{line}: {message}" )
{
ChunkName = chunk;
Line = line;
}
}
/// <summary>
/// A Lua runtime error. <see cref="Value"/> is the error object (catchable with pcall).
/// </summary>
public class LuaRuntimeException : LuaException
{
public LuaValue Value { get; internal set; }
public string LuaTraceback { get; internal set; }
public override string Message => Value.IsString ? Value.AsString
: Value.IsNumber ? Value.ToString()
: $"(error object is a {Value.TypeName} value)";
/// <summary>True once the "chunk:line:" position prefix has been applied.</summary>
internal bool PositionApplied { get; set; }
public LuaRuntimeException( string message ) : base( message )
{
Value = LuaValue.FromString( message );
}
public LuaRuntimeException( LuaValue value, bool positionApplied ) : base( value.IsString ? value.AsString : $"(error object is a {value.TypeName} value)" )
{
Value = value;
PositionApplied = positionApplied;
}
}
/// <summary>
/// Thrown when a script exceeds its instruction budget. Deliberately NOT catchable by pcall,
/// so a script cannot trap the watchdog in an infinite loop.
/// </summary>
public sealed class LuaBudgetExceededException : LuaException
{
public LuaBudgetExceededException( string message ) : base( message ) { }
}