Click here to Skip to main content
Click here to Skip to main content
Go to top

NeoLua (Lua for the .NET Dynamic Language Runtime)

, 22 Aug 2014
Rate this:
Please Sign up or sign in to vote.
NeoLua implements Lua as a .NET dynamic language.

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

  • Handling of upvalues is not possible. DLR uses closures.
  • Debugging is more complicated, because we have to deal with machine code, but NeoLua supports stack traces (and I'm planning to support runtime traces).
  • It is not 100% compatible with Lua.

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 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");
      }
    }
  }
}

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; // 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"]);
}

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); // 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());
}

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

Strict 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 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 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 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)); // the cast is needed because of the dynamic call

  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())
      {
        // 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 information 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("Exception: {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, " / ");

Performance

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 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,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 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 source, documentation and releases.

Changes

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:

  • Bug fixing

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.

License

This article, along with any associated source code and files, is licensed under The Apache License, Version 2.0

Share

About the Author

neolithos
Software Developer
Germany Germany
No Biography provided

Comments and Discussions

 
GeneralMy vote of 5 PinmemberEmile van Gerwen14-Aug-14 2:37 
GeneralRe: My vote of 5 Pinmemberneolithos14-Aug-14 12:45 
Questiontoo bad there is no vote of 6 PinmemberJorge Varas22-Jun-14 9:01 
AnswerRe: too bad there is no vote of 6 Pinmemberneolithos23-Jun-14 11:16 
QuestionDoString with Nlua, Is it possible? PinprofessionalPapyRef27-Mar-14 5:44 
AnswerRe: DoString with Nlua, Is it possible? Pinmemberneolithos27-Mar-14 6:36 
GeneralRe: DoString with Nlua, Is it possible? PinprofessionalPapyRef27-Mar-14 7:22 
GeneralRe: DoString with Nlua, Is it possible? Pinmemberneolithos27-Mar-14 7:35 
GeneralRe: DoString with Nlua, Is it possible? PinprofessionalPapyRef27-Mar-14 7:44 
GeneralMy vote of 5 PinprofessionalPapyRef26-Mar-14 22:59 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

| Advertise | Privacy | Mobile
Web01 | 2.8.140921.1 | Last Updated 22 Aug 2014
Article Copyright 2013 by neolithos
Everything else Copyright © CodeProject, 1999-2014
Terms of Service
Layout: fixed | fluid