LuaCmd is a interactive program to test NeoLua. Check it out. Just write lua code and execute it with a empty line.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 a lot parts of Lua 5.3. The goal is to follow the reference of the C-Lua implementation and combine this with 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.
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.
So, this could be reliable partner for your compiled .NET application or engine (e.g. Game Engines).
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
or download the zip-file from this site.
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)
{
// Create the Lua script engine
using (Lua l = new Lua())
{
// create a Lua script environment (global)
var g = l.CreateEnvironment();
// run a chunk, first the code, than the name of the code
g.DoChunk("print('Hello World!');", "test.lua");
}
}
}
}
LuaCmd is a interactive program to test NeoLua. Check it out. Just write lua code and execute it with a empty line.
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);
}
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.
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; // dynamic way to set a variable
g["b"] = 4; // second way to access variable
g.DoChunk("c = a + b", "test.lua");
Console.WriteLine(dg.c);
Console.WriteLine(g["c"]);
}
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.
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);
}
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]);
}
using (Lua l = new Lua())
{
dynamic dg = l.CreateEnvironment();
dg.myadd = new Func<int, int, int>((a, b) => a + b); // define a new function in c#
dg.dochunk("function Add(a, b) return myadd(a, b) end;", "test.lua"); // define a new function in lua that calls the C# function
Console.WriteLine((int)dg.Add(2, 4)); //call the Lua function
var f = (Func<object,>)dg.Add;// get the Lua function
Console.WriteLine(f(2, 4).ToInt32());
}
The next example defines three members.
a , b are members, they are holding a 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());
}
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]);
}
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;"));
}
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);
}
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 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 can not have typed members, they are by implementation always of the type object.
Example without strict type:
// create a new instance of StringBuilder
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 the documentation of the DLR.
Same example with strict type:
// define a shortcut to a type, this line is only seen by the parser
const StringBuilder typeof clr.System.Text.StringBuilder;
// create a new instance of StringBuilder
local sb : StringBuilder = StringBuilder();
sb:Append('Hello '):Append('World!');
return sb:ToString();
This script is compiled like it will done from e.g. C#
StringBuilder sb = new StringBuilder();
sb.Append(("Hello (").Append(("World!(");
return sb.ToString();
Types are very useful to create a 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)); // the cast is needed because of the dynamic call
var f = (Func<int,int,int>)dg.Add;
Console.WriteLine(f(2, 4));
}
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 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.
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));
}
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.
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())
{
// create an environment that is associated with the Lua scripts
dynamic g = l.CreateEnvironment();
// register new functions
g.print = new Action<object[]>(Print);
g.read = new Func<string,>(Read);
foreach (string c in args)
{
using (LuaChunk chunk = l.CompileChunk(c, true)) // compile the script with debug informations which is needed for a complete stack trace
try
{
object[] r = g.dochunk(chunk); // execute the 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("Expception: {0}", e.InnerException.Message);
LuaExceptionData d = LuaExceptionData.GetData(e.InnerException); // get stack trace
Console.WriteLine("StackTrace: {0}", d.GetStackTrace(0, false));
Console.ForegroundColor = ConsoleColor.Gray;
}
}
}
} // Main
private static void Print(object[] texts)
{
foreach (object o in texts)
Console.Write(o);
Console.WriteLine();
} // proc Print
private static string Read(string sLabel)
{
Console.Write(sLabel);
Console.Write(": ");
return Console.ReadLine();
} // func Read
}
}
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, " / ");
I compared the performance to the LuaInterface project.
Not pre-compiled:
Empty : LuaInterface 1,8 ms NeoLua 0,4 ms 4,268
Sum : LuaInterface 0,0 ms NeoLua 1,4 ms 0,021
Sum_strict : LuaInterface 0,0 ms NeoLua 1,1 ms 0,019
Sum_echo : LuaInterface 2,2 ms NeoLua 3,2 ms 0,697
String : LuaInterface 1,6 ms NeoLua 1,2 ms 1,376
String_echo : LuaInterface 4,2 ms NeoLua 3,0 ms 1,404
Delegate : LuaInterface 2,0 ms NeoLua 2,0 ms 1,005
StringBuilder : LuaInterface 3,2 ms NeoLua 4,3 ms 0,727
What this table show is that they 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,0 ms 1,000
Sum_strict : LuaInterface 0,0 ms NeoLua 0,0 ms NaN
Sum_echo : LuaInterface 1,6 ms NeoLua 0,1 ms 18,111
String : LuaInterface 1,2 ms NeoLua 0,4 ms 2,951
String_echo : LuaInterface 3,8 ms NeoLua 0,4 ms 8,884
Delegate : LuaInterface 1,5 ms NeoLua 0,1 ms 25,000
StringBuilder : LuaInterface 2,4 ms NeoLua 0,1 ms 48,000
Pre compiled (debug):
Empty : LuaInterface 0,0 ms NeoLua 0,0 ms NaN
Sum : LuaInterface 0,0 ms NeoLua 0,0 ms 0,667
Sum_strict : LuaInterface 0,0 ms NeoLua 0,0 ms NaN
Sum_echo : LuaInterface 1,6 ms NeoLua 0,1 ms 15,500
String : LuaInterface 1,2 ms NeoLua 0,4 ms 3,132
String_echo : LuaInterface 3,6 ms NeoLua 0,5 ms 7,160
Delegate : LuaInterface 1,5 ms NeoLua 0,1 ms 16,444
StringBuilder : LuaInterface 2,5 ms NeoLua 0,1 ms 35,000
These values show that NeoLua is strong in repetititive tasks and interacting with the framework. E.g. in game engines or service application these attributes should be interesting.
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 thay might be implemented in the future:
doubles Things that most likely will never be implemented:
NeoLua is hosted on CodePlex: neolua.codeplex.com. There you can find the source, documentation and releases.
0.8.9:
0.8.2:
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.