Framework/Lua/Runtime/LuaFunction.cs

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 ) { }
}