Introduction
NeoLua is an implementation of the Lua language that totally started from scratch. Currently, the implementation is on the level of Lua 5.2 (http://www.lua.org/manual/5.2/manual.html) with many parts of Lua 5.3. The goal is to follow the reference of the C-Lua implementation and combine this with the full .NET Framework support. That means it should be easy to call .NET functions/classes/interfaces/events from Lua and it should be easy to access variables and functions of Lua from a .NET language (e.g. C#, VB.NET, ...).
NeoLua is implemented in C# and uses the Dynamic Language Runtime. At the time, NeoLua has only one dependency to the .NET framework 4 and it also works under the current mono framework.
Background
The idea of NeoLua was born because I needed Lua as a scripting language in a service application. In the first release, I used LuaInterface. But it turned out that it is really hard to use LuaInterface as a bridge between .NET and C-Lua correctly.
I got a lot of memory leaks! During debugging, I discovered that I did not de-reference the Lua variables correctly and learned that to do this right is really hard.
Principles
What NeoLua is Useful For
- Outsource the logic of your application into scripts
- Structuring of logic
- Build a dynamic configuration system, with functions and variables
- As a formula parser
- ...
So, this could be reliable partner for your compiled .NET application or engine (e.g. Game Engines).
What I Did Not Have In Mind
- Compiling libraries
- Standalone applications
Advantages of NeoLua
- Dynamic access between Lua script and the host application/.NET framework and vice-versa.
- NeoLua is based on the DLR. So you get compiled code that is collectable and well-optimized.
- It is possible to write strict scripts. Runtime speed is like e.g. C#.
- It is compatible with the .NET world (e.g. C#, VB.NET, IronPython, ...).
- Full and easy access to the .NET framework or your own libraries (with no stub code).
- A .NET Framework Garbage Collector that is well-tested and very fast.
- Pure IL (x86,x64 support)
Drawbacks of NeoLua
Drawbacks of Bridges to C-lua, that are Solved with NeoLua
- With C-Lua, you have to deal with two memory managers and so you have to marshal all data between these two worlds. That takes time and there are a lot of pitfalls to get memory leaks.
- C-Lua interprets its own bytecode. The code is not compiled to machine code.
Hello World
To get started with NeoLua is very easy. At first, you have to add a reference to the Neo.Lua-Assembly. There are two ways to get NeoLua. First, download it from neolua.codeplex.com.
The second way is to use the nuget package.
Next, create an instance of the Neo.IronLua.Lua (called Lua-Script-Engine) and get a fresh environment to execute Lua code.
Here is an example that prints "Hello World!" in the debug output:
using Neo.IronLua;
namespace Test
{
public static class Program
{
public static void Main(string[] args)
{
using (Lua l = new Lua())
{
var g = l.CreateEnvironment();
g.DoChunk("print('Hello World!');", "test.lua");
}
}
}
}
Playing with NeoLua
LuaCmd is a interactive program to test NeoLua. Check it out. Just write Lua code and execute it with a empty line.
Running Lua-Snippets
To run a small snippet, just execute it via DoChunk. Scripts can have parameters, like in example a and b. Every script can return values. The return value of scripts are always LuaResult of objects, because in Lua, it is possible to return more than one result.
using (Lua l = new Lua())
{
var g = l.CreateEnvironment();
var r = g.DoChunk("return a + b", "test.lua",
new KeyValuePair<string, object>("a", 2),
new KeyValuePair<string, object>("b", 4));
Console.WriteLine(r[0]);
}
Because NeoLua is a dynamic language, there is also a way to do it dynamically. Also LuaResult has a dynamic interface.
using (Lua l = new Lua())
{
dynamic g = l.CreateEnvironment();
dynamic dr = dg.dochunk("return a + b", "test.lua", "a", 2, "b", 4);
Console.WriteLine((int)dr);
}
Values and Types
NeoLua is not a dynamically typed language, it just looks like it is. Variables always have a type (at least System.Object).
NeoLua supports all CLR types. If there is type conversion necessary, it is done automatically. Dynamic types are also supported.
local a = "5"; -- a string is assigned to a local variable of the type object
local b = {}; -- object assigned with an empty table
b.c = a + 8; -- the variable "a" is converted into an integer and assigned to the dynamic member of a table
A nice feature of NeoLua is strict typing. But more in a later section.
Working with Globals
The environment is a special Lua table. Set or get the variables on the environment and they are accessible in the script-code as global variables.
using (Lua l = new Lua())
{
var g = l.CreateEnvironment();
dynamic dg = g;
dg.a = 2;
g["b"] = 4;
g.DoChunk("c = a + b", "test.lua");
Console.WriteLine(dg.c);
Console.WriteLine(g["c"]);
}
Working with LuaTables
The implementation of NeoLua supports the dynamic class LuaTable. This class is used by the script-code as it is. The next examples hopefully show the idea.
Member
using (Lua l = new Lua())
{
dynamic dg = l.CreateEnvironment();
dg.t = new LuaTable();
dg.t.a = 2;
dg.t.b = 4;
dg.dochunk("t.c = t.a + t.b", "test.lua");
Console.WriteLine(dg.t.c);
}
Index Access
using (Lua l = new Lua())
{
dynamic dg = l.CreateEnvironment();
dg.t = new LuaTable();
dg.t[0] = 2;
dg.t[1] = 4;
dg.dochunk("t[2] = t[0] + t[1]", "test.lua");
Console.WriteLine(dg.t[2]);
}
Functions
Defining a function feels natural. It is basically a delegate that is assigned to a member.
using (Lua l = new Lua())
{
dynamic dg = l.CreateEnvironment();
dg.myadd = new Func<int, int, int>((a, b) => a + b);
dg.dochunk("function Add(a, b) return myadd(a, b) end;", "test.lua");
Console.WriteLine((int)dg.Add(2, 4));
var f = (Func<object,>)dg.Add;
Console.WriteLine(f(2, 4).ToInt32());
}
Methods (Host Application)
The next example defines three members.
a , b are members, they are holding an ordinary integer. And add is holding a function, but this definition is not a method. Because if you try to call the function like a method in e.g. C#, it will throw a NullReferenceException. You must always pass the table as a first parameter to it. To declare a real method, you have to call the explicit method DefineMethod. Lua does not care about the difference, but C# or VB.NET do.
using (Lua l = new Lua())
{
dynamic dg = l.CreateEnvironment();
dg.t = new LuaTable();
dg.t.a = 2;
dg.t.b = 4;
dg.t.add = new Func<dynamic, int>(self =>
{
return self.a + self.b;
});
((LuaTable)dg.t).DefineMethod("add2", (Delegate)dg.t.add);
Console.WriteLine(dg.dochunk("return t:add()", "test.lua")[0]);
Console.WriteLine(dg.dochunk("return t:add2()", "test.lua")[0]);
Console.WriteLine(dg.t.add(dg.t));
Console.WriteLine(dg.t.add2());
}
Methods (Lua)
add is a normal function, created from a delegate.add1 is declared as a function.add2 is a method, that is created from a delegate. Be aware that a delegate definition doesn't know anything about the concept of methods, so you have to declare the self parameter.add3 shows a method declaration.
using (Lua l = new Lua())
{
dynamic dg = l.CreateEnvironment();
LuaResult r = dg.dochunk("t = { a = 2, b = 4 };" +
"t.add = function(self)" +
" return self.a + self.b;" +
"end;" +
"function t.add1(self)" +
" return self.a + self.b;" +
"end;" +
"t:add2 = function (self)" +
" return self.a + self.b;" +
"end;" +
"function t:add3()" +
" return self.a + self.b;" +
"end;" +
"return t:add(), t:add2(), t:add3(), t.add(t), t.add2(t), t.add3(t);",
"test.lua");
Console.WriteLine(r[0]);
Console.WriteLine(r[1]);
Console.WriteLine(r[2]);
Console.WriteLine(r[3]);
Console.WriteLine(r[4]);
Console.WriteLine(r[5]);
Console.WriteLine(dg.t.add(dg.t)[0]);
Console.WriteLine(dg.t.add2()[0]);
Console.WriteLine(dg.t.add3()[0]);
}
Metatables
If you define a metatable on a table, you can also use this in the host language like C#.
using (Lua l = new Lua())
{
dynamic g = l.CreateEnvironment();
dynamic r = g.dochunk(String.Join(Environment.NewLine,
"tm = {};",
"tm.__add = function (t, a) return t.n + a; end;",
"t = { __metatable = tm, n = 4 };",
"return t + 2"));
LuaTable t = g.t;
Console.WriteLine((int)r);
Console.WriteLine(t + 2);
}
And vice versa.
using (Lua l = new Lua())
{
dynamic g = l.CreateEnvironment();
LuaTable t = new LuaTable();
t["n"] = 4;
t.MetaTable = new LuaTable();
t.MetaTable["__add"] = new Func<LuaTable, int, int>((_t, a) => (int)(_t["n"]) + a);
g.t = t;
dynamic r = g.dochunk("return t + 2");
Console.WriteLine((int)r);
Console.WriteLine(t + 2);
}
NeoLua does not support setting metatables on userdata, because there is no definition of userdata. But NeoLua uses the operator definitions of a type. That is the same result.
public class ClrClass
{
private int n = 4;
public static int operator +(ClrClass c, int a)
{
return c.n + a;
}
}
using (Lua l = new Lua())
{
dynamic g = l.CreateEnvironment();
g.c = new ClrClass();
Console.WriteLine((int)g.dochunk("return c + 2;"));
}
Classes/Objects
To create a class, you have to write a function that creates a new object. The function is by definition the class and the result of the function is the object.
using (Lua l = new Lua())
{
dynamic dg = l.CreateEnvironment();
dg.dochunk("function classA()" +
" local c = { sum = 0 };" +
" function c:add(a)" +
" self.sum = self.sum + a;" +
" end;" +
" return c;" +
"end;", "classA.lua");
dynamic o = dg.classA()[0];
o.add(1);
o.add(2);
o.add(3);
Console.WriteLine(o.sum);
}
Explicit Typing
A nice feature of NeoLua is its use of strict typing. That means you can give your local variables or parameters a strict type (like in C#). A big advantage of this feature is that the parser can do a lot of stuff during compile time. This will short-cut a lot of the dynamic parts they are normally in a NeoLua script (so the script should run pretty fast).
Globals and Tables cannot have typed dynamic members, they are by implementation always of the type object. One exception is the explicit declarion in a .net class that is inherited from LuaTable.
Example without explicit type:
local sb = clr.System.Text.StringBuilder();
sb:Append('Hello '):Append('World!');
return sb:ToString();
The script will be translated to something like this:
object sb = InvokeConstructor(clr["System"]
["Text"]""StringBuilder"], new object[0]);
InvokeMethod(InvokeMethod(sb, "Append", new string[]
{ "Hello " }), "Append", new string[]{ "World!"});
return InvokeMethod(sb, "ToString", new object[0]);
The code is not the exact code that gets executed, in reality it is a litte bit more complicated, but way more efficient (e.g. Append will only resolve once during runtime, not twice like in this example). If you are interested in how this is done, I can recommend reading the documentation of the DLR.
Same example with strict type:
const StringBuilder typeof clr.System.Text.StringBuilder;
local sb : StringBuilder = StringBuilder();
sb:Append('Hello '):Append('World!');
return sb:ToString();
This script is compiled like it will be done from e.g. C#:
StringBuilder sb = new StringBuilder();
sb.Append(("Hello (").Append(("World!(");
return sb.ToString();
Types are very useful to create functions with a strict signature.
using (Lua l = new Lua())
{
dynamic dg = l.CreateEnvironment();
dg.dochunk("function Add(a : int, b : int) : int return a + b; end;", "test.lua");
Console.WriteLine((int)dg.Add(2, 4));
var f = (Func<int,int,int>)dg.Add;
Console.WriteLine(f(2, 4));
}
Compiled Code
Executing a script in NeoLua always means that it will be compiled and the result will be executed. If the result e.g. is a function and you call the function, it is not interpreted.
If you want to use a script multiple times, pre-compile the script-code with CompileChunk and run it on different environments. That saves compile time and memory.
using (Lua l = new Lua())
{
LuaChunk c = l.CompileChunk("return a;", "test.lua", false);
var g1 = l.CreateEnvironment();
var g2 = l.CreateEnvironment();
g1["a"] = 2;
g2["a"] = 4;
Console.WriteLine((int)(g1.DoChunk(c)[0]) + (int)(g2.DoChunk(c)[0]));
}
The third parameter of the CompileChunk function decides if NeoLua should create a Dynamic-Function (false) or Runtime-Function (true). Dynamic functions are available for garbage collection, but they are not debuggable. They are the most efficient choice for small code blocks. A runtime function is compiled in a dynamic assembly in a dynamic type. The assembly/type/function is discarded when the script engine (Lua-Class) is disposed. Runtime-Functions are a good choice for scripts - they are big, often used and need debug information.
Lambda Support
A delegate that is generated by this function has no debug information and no environment. It is not allowed to use global variables or Lua functions/libraries in the code. Only the CLR package is useable. It is always compiled as a dynamic function.
using (Lua l = new Lua())
{
var f = l.CreateLambda<Func<double, double>>("f", "return clr.System.Math:Abs(x) * 2", "x");
Console.WriteLine("f({0}) = {1}", 2, f(2));
Console.WriteLine("f({0}) = {1}", 2, f(-2));
}
.NET
To access the .NET Framework classes, there is a package that is called clr. This package references namespaces and classes.
This example shows how to call the static String.Concat function:
function a()
return 'Hello ', 'World', '!';
end;
return clr.System.String:Concat(a());
Behind clr is the class LuaType, that tries to give access to classes, interfaces, methods, events and members in the most efficient way.
-- Load Forms
clr.System.Reflection.Assembly:Load("System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089");
local Forms = clr.System.Windows.Forms; -- create a local variable with a namespace
local iClicked : int = 0;
Forms.Application:EnableVisualStyles(); -- call a static method
do (frm, cmd = Forms.Form(), Forms.Button()) -- create a from and button in a using block
frm.Text = 'Hallo Welt!';
cmd.Text = 'Click';
cmd.Left = 16;
cmd.Top = 16;
cmd.Click:add( -- add a event the counter part is 'remove'
function (sender, e) : void
iClicked = iClicked + 1;
Forms.MessageBox:Show(frm, clr.System.String:Format('Clicked {0:N0} times!', iClicked), 'Lua', Forms.MessageBoxButtons.OK, Forms.MessageBoxIcon.Information);
end);
frm.Controls:Add(cmd);
Forms.Application:Run(frm);
end;
A nice example of what is possible:
local writeLine = clr.System.Console.WriteLine;
writeLine('Calc:');
writeLine('{0} + {1} = {2}', 2, 4, 6);
writeLine();
But it is more efficient to use the member call clr.System.Console:WriteLine(). That's because NeoLua creates an instance of the LuaOverloadedMethod-Class to manage the methods behind in the example above.
This is a point you should always have in mind when you use getmember (.) on none .NET members. Classes, interfaces return LuaType. Methods/functions return LuaOverloadedMethod or LuaMethod. And events return LuaEvent.
Complex Example
This example reads Lua script files and executes them once. The example shows how to compile a script and catch exceptions and how to retrieve the stack trace. The stack trace can only be retrieved if the script is compiled with debug information. To turn this switch on, set the second parameter of CompileChunk to true.
using System;
using System.Collections.Generic;
using System.Diagnostics;
using System.Reflection;
using System.Threading;
namespace Neo.IronLua
{
public static class Program
{
public static void Main(string[] args)
{
using (Lua l = new Lua())
{
dynamic g = l.CreateEnvironment();
g.print = new Action<object[]>(Print);
g.read = new Func<string,>(Read);
foreach (string c in args)
{
using (LuaChunk chunk = l.CompileChunk(c, true))
try
{
object[] r = g.dochunk(chunk);
if (r != null && r.Length > 0)
{
Console.WriteLine(new string('=', 79));
for (int i = 0; i < r.Length; i++)
Console.WriteLine("[{0}] = {1}", i, r[i]);
}
}
catch (TargetInvocationException e)
{
Console.ForegroundColor = ConsoleColor.DarkRed;
Console.WriteLine("Exception: {0}", e.InnerException.Message);
LuaExceptionData d = LuaExceptionData.GetData(e.InnerException);
Console.WriteLine("StackTrace: {0}", d.GetStackTrace(0, false));
Console.ForegroundColor = ConsoleColor.Gray;
}
}
}
}
private static void Print(object[] texts)
{
foreach (object o in texts)
Console.Write(o);
Console.WriteLine();
}
private static string Read(string sLabel)
{
Console.Write(sLabel);
Console.Write(": ");
return Console.ReadLine();
}
}
}
The Lua-script is as follows:
local a, b = tonumber(read("a")), tonumber(read("b"));
function PrintResult(o, op)
print(o .. ' = ' .. a .. op .. b);
end;
PrintResult(a + b, " + ");
PrintResult(a - b, " - ");
PrintResult(a * b, " * ");
PrintResult(a / b, " / ");
Performance
I compared the performance to the LuaInterface project.
Not pre-compiled:
Empty : LuaInterface 0,7 ms NeoLua 2,0 ms 0,358
Sum : LuaInterface 0,2 ms NeoLua 0,3 ms 0,581
Sum_strict : LuaInterface 0,3 ms NeoLua 0,0 ms 12,500
Sum_echo : LuaInterface 2,2 ms NeoLua 1,4 ms 1,586
String : LuaInterface 2,0 ms NeoLua 0,2 ms 11,941
String_echo : LuaInterface 5,0 ms NeoLua 2,0 ms 2,518
Delegate : LuaInterface 2,1 ms NeoLua 1,0 ms 2,099
StringBuilder : LuaInterface 3,5 ms NeoLua 0,4 ms 8,262
CallStd : LuaInterface 4,0 ms NeoLua 4,2 ms 0,952
TableIntSet : LuaInterface 1,8 ms NeoLua 2,4 ms 0,721
TableIntGet : LuaInterface 96,3 ms NeoLua 8,7 ms 11,021
TableVsList : LuaInterface 2,8 ms NeoLua 7,5 ms 0,373
TableString : LuaInterface 34,4 ms NeoLua 36,5 ms 0,941
What this table shows is that they are more complex and more often you have to interact with the .NET Framework NeoLua gains a benefit over the compile overhead.
The next table shows the results with pre-compiled scripts.
Pre compiled:
Empty : LuaInterface 0,0 ms NeoLua 0,0 ms NaN
Sum : LuaInterface 0,0 ms NeoLua 0,1 ms 0,333
Sum_strict : LuaInterface 0,0 ms NeoLua 0,0 ms NaN
Sum_echo : LuaInterface 1,6 ms NeoLua 0,3 ms 4,727
String : LuaInterface 1,2 ms NeoLua 0,6 ms 2,000
String_echo : LuaInterface 3,8 ms NeoLua 0,7 ms 5,846
Delegate : LuaInterface 1,5 ms NeoLua 0,3 ms 5,654
StringBuilder : LuaInterface 2,8 ms NeoLua 0,0 ms 275,00
CallStd : LuaInterface 3,3 ms NeoLua 3,3 ms 1,006
TableIntSet : LuaInterface 1,2 ms NeoLua 1,7 ms 0,704
TableIntGet : LuaInterface 94,1 ms NeoLua 3,9 ms 23,876
TableVsList : LuaInterface 2,3 ms NeoLua 1,9 ms 1,214
TableString : LuaInterface 30,4 ms NeoLua 33,7 ms 0,903
Pre compiled (debug):
Empty : LuaInterface 0,0 ms NeoLua 0,0 ms NaN
Sum : LuaInterface 0,0 ms NeoLua 0,1 ms 0,429
Sum_strict : LuaInterface 0,0 ms NeoLua 0,0 ms NaN
Sum_echo : LuaInterface 1,5 ms NeoLua 0,4 ms 4,108
String : LuaInterface 1,2 ms NeoLua 0,4 ms 3,105
String_echo : LuaInterface 4,0 ms NeoLua 0,7 ms 5,812
Delegate : LuaInterface 1,5 ms NeoLua 0,3 ms 5,179
StringBuilder : LuaInterface 2,7 ms NeoLua 0,0 ms 90,667
CallStd : LuaInterface 3,3 ms NeoLua 3,2 ms 1,022
TableIntSet : LuaInterface 1,2 ms NeoLua 1,8 ms 0,670
TableIntGet : LuaInterface 94,6 ms NeoLua 4,3 ms 22,056
TableVsList : LuaInterface 2,2 ms NeoLua 2,1 ms 1,077
TableString : LuaInterface 30,8 ms NeoLua 34,1 ms 0,903
These values show that NeoLua is strong in repetitive tasks and interacting with the framework. E.g. in game engines or service application, these attributes should be interesting.
Parts That Are Not Implemented
Not all Lua functionality is implemented yet, and some parts may be never be implemented. However, most parts of the Lua reference work just fine.
Things that might be implemented in the future:
Hex representation for doubles- Missing runtime parts
Debugging (hard)
Things that most likely will never be implemented:
Working with upvalues- Lua-Byte-Code support
Resources
NeoLua is hosted on CodePlex: neolua.codeplex.com. There you can find the releases and a forum there.
The source is hosted on GitHub: https://github.com/neolithos/neolua
Changes
0.9.9:
- New: Manipulating closures/upvalues
- New: TraceLine debugging
- New: Array initializer
- New: Support for extension methods
- Chg: chunks can run on LuaTable's
- Chg: total rewrite of lua table (speed, size, combatiblity)
- Chg: Redesign for the c#/vb.net/lua operators
- Chg: RtInvoke can invoke all what is callable, now
- Chg: Correction of the arithmetic (it is not full compatible to Lua, but compatible to .net)
- Chg: Class part for lua table
0.8.18:
- New: rewrite of table package
- New: Lexer is public, now
- Bug fixing
0.8.17:
- Added: require
- Bug fixing
0.8.12:
0.8.9:
- Changed: Redesign type system (
LuaType, LuaMethod, LuaEvent) - Added: Strict parsing, when it is possible
- Added: Operator support
- Added: Metatable support
- Added: More units tests
- Bug fixing
0.8.2:
- Add: coroutine package
- Add: io package
Next Steps
In the next months, I will stabilize the language before I introduce new features. I hope I get a lot of bug reports. After this, I will investigate debugging/tracing for NeoLua, maybe with the support of the debug package.
