Add examples to readme page

README.md

@@ -10,6 +10,135 @@ repository and add its `lib/` folder to your include path.
 
 Have a question? Simply [ask](https://gitter.im/vapourismo/luwra) or open an issue.
 
+## Examples
+In the following examples `lua` refers to an instance of `lua_State*`.
+
+Easily push values onto the stack:
+
+```c++
+// Push an integer
+luwra::push(lua, 1338);
+
+// Push a number
+luwra::push(lua, 13.37);
+
+// Push a boolean
+luwra::push(lua, false);
+
+// Push a string
+luwra::push(lua, "Hello World");
+```
+
+Or retrieve them:
+
+```c++
+// Your function
+int my_fun(int a, int b) {
+    return a + b;
+}
+
+// Prepare stack
+luwra::push(lua, 13);
+luwra::push(lua, 37);
+
+// Apply your function
+int result = luwra::apply(lua, my_fun);
+
+// which is equivalent to
+int result = luwra::apply(lua, 1, my_fun);
+
+// and equivalent to
+int result = luwra::apply(lua, -2, my_fun);
+
+// All of this is essentially syntactic sugar for
+int result = my_fun(luwra::read<int>(lua, 1), luwra::read<int>(lua, 2));
+```
+
+Generate a C function which can be used by Lua:
+
+```c++
+// Assuming your function looks something like this
+int my_function(const char* a, int b) {
+    // ...
+}
+
+// Convert to lua_CFunction
+lua_CFunction cfun = LUWRA_WRAP(my_function);
+
+// Do something with it, for example set it as a Lua global function
+luwra::setGlobal(lua, "my_function", cfun);
+```
+
+```lua
+-- Invoke the registered function
+local my_result = my_function("Hello World", 1337)
+print(my_result)
+```
+
+Or register your own class:
+
+```c++
+struct Point {
+    double x, y;
+
+    Point(double x, double y):
+        x(x), y(y)
+    {
+        std::cout << "Construct Point(" << x << ", " << y << ")" << std::endl;
+    }
+
+    ~Point() {
+        std::cout << "Destruct Point(" << x << ", " << y << ")" << std::endl;
+    }
+
+    void scale(double f) {
+        x *= f;
+        y *= f;
+    }
+
+    std::string __tostring() {
+        return "<Point(" + std::to_string(x) + ", " + std::to_string(y) + ")>";
+    }
+};
+
+// Register the metatable and constructor
+luwra::registerUserType<Point(double, double)>(
+    lua,
+
+    // Constructor name
+    "Point",
+
+    // Methods need to be declared here
+    {
+        LUWRA_MEMBER(Point, scale),
+        LUWRA_MEMBER(Point, x),
+        LUWRA_MEMBER(Point, y)
+    },
+
+    // Meta methods may be registered aswell
+    {
+        LUWRA_MEMBER(Point, __tostring)
+    }
+);
+```
+
+```lua
+-- Instantiate 'Point'
+local point = Point(13, 37)
+
+-- Invoke 'scale' method
+point:scale(1.5)
+
+-- Convert to string via '__tostring' meta method
+print(point)
+
+-- Read properties 'x' and 'y'
+print(point:x(), point:y())
+
+-- Set property 'x'
+point:x(4.2)
+```
+
 ## Requirements
 You need a C++14-compliant compiler and at least Lua 5.1 to get this library to work. I recommend
 using Lua 5.3 or later, to avoid the messy `lua_Integer` situation. LuaJIT 2.0 seems to work aswell.