= LuaD tutorial =
=== Introduction ===

The goal of LuaD is to be able to take full advantage of Lua and embed it in your application quickly and effortlessly, without touching the Lua stack or any other unessecary detail you would have to think about in a relatively low-level language like C.

=== ''LuaD is not an object-oriented wrapper around the Lua stack'' ===

The Lua stack might be an excellent approach in a language like C; but in a modern language like D, it's a very cumbersome and error-prone way to work. Additionally, D's advanced template capabilities allow us to abstract the Lua stack without compromising performance. LuaD is an easy, safe and seamless way to work with Lua.

This tutorial assumes no previous knowledge regarding the embedding of Lua, but assumes basic knowledge of Lua and D. If you already know D, Lua and have embedded Lua before; you might want to jump right to the [wiki:Example examples].

----
== The Lua State and Setting Variables ==
Lua has the wonderful capability of being able to have any number of "interpreters", or ''Lua state's'' inside a single program. There are no global variables involved, and everything is tied to one object: the ''Lua state''. In LuaD, this takes the form of the LuaState class.

Creating a new Lua state is very simple:
{{{
#!d
auto lua = new LuaState;
}}}
We now have ''lua'' as our Lua interpreter object. In most applications embedding Lua, only a single Lua state is needed. By default; all the core Lua libraries are opened in our new Lua state. We can now start setting global variables in our Lua environment:
{{{
#!d
lua["SomeGlobal"] = "Hello world!";
}}}
In LuaD, a LuaState is synonymous to its global table when it comes to indexing operations. So the above is the equivalent of doing the following in Lua:
{{{ SomeGlobal = "Hello world!" }}}

This works for all the types you'd expect, including arrays for tables:
{{{
#!d
lua["SomeNumber"] = 12.3;
lua["SomeBool"] = true;
lua["SomeArray"] = [1,2,3,4,5];
lua["SomeHashTable"] = ["SomeField"[]: 123, "OtherField"[]: 321];
}}}

It also works for D functions!
{{{
#!d
lua["SomeFunction"] = (char[] message, int[] array){
    Stdout("Message: " ~ message).newline;
    Stdout("Array has ")(array.length)(" integer members!").newline;

    return "You can return anything that works elsewhere in LuaD :)";
};
}}}
If you want to see all the possible conversions; click [wiki:TypeConversions here].

----
== Getting Variables ==
If you want to get any variable from Lua (including ''nil'') regardless of type:
{{{
#!d
auto value = lua["SomeField"];
}}}
This is the equivalent of doing the following in Lua:
{{{
local value = SomeField
}}}
Say you just wanted to see what the value of our variable is; you could do:
{{{
#!d
auto value = lua["SomeField"];
Stdout(value.typeName)(": ")(value.toString).newline;
}}}
This would print the type of the object and its value.

=== Type Safety ===

== More on Tables ==
So far we've only really been working with the global table. Other tables work exactly the same:
{{{
#!d
auto table = lua.newTable;
table[1] = "hello,";
table[2] = " world";
lua["OurTable"] = table;

//The above can also be written as:

lua["OurTable"] = ["hello,", " world"];
}}}

----
TODO: Finish this tutorial