Make your code scriptable

You might ask me: “Tyler, in which situations can I integrate Lua into my app?” And the answer is “Yes.”

Any app that sits on top of C plays well with Lua. This directly applies to C (derp), C++ and Objective-C. It applies to languages that make C-calls easy, like Swift or C# . Some languages, like Go, Java, and Python, also support C integration, but with caveats. If you’re writing for the browser, then technically you could use some black magic like emscripten to essentially convert C to JavaScript but for the love of the flying spaghetti monster don’t do that (too often).

You can do fun things by adding Lua. (Adding Lua means that your existing code can call out to Lua, and Lua can call back.) You can make a game mod-able by setting up an API — for example, letting users define custom spells in an RPG. Adobe Lightroom empowers advanced photo-editing with user-written Lua scripts. Or you can split your dev work between hardware-intensive low-level code and easy-to-write high-level Lua.

Some folks start off with a “hello, world!” thingy, but sometimes you can quickly create a more impressive result. So let’s make an interpreter. Albeit a minimalistic one, weighing in at 25 lines of C.

Both allocation and cleanup of a Lua run-time state is simple. Allocation looks like this:

The result value L is a black box. We don’t ask questions about the actual fields of L, and no one gets hurt. This value is sent in as the first parameter to virtually every C function that works with Lua.

Finishing up your use of a Lua state works like so:

That deallocation includes garbage collection of all values used from within Lua.

The full interpreter uses only 3 other functions from Lua’s C API. We’ll take a brief look at those after seeing the full interpreter code here:

Here are complete macOS steps to download this file along with Lua’s source, assuming you have some standard tools like curl and gcc already installed:

Let’s take a look at the 3 Lua C API functions we used in the interpreter but didn’t explain yet. Here’s the short version:

If you’re like me, you’re probably asking a few great questions right about now:

If you have not already been blow away by writing a 25-line Lua interpreter in C, then this next example is certain to overwhelm your impressive capacity for sheer awesome. Prepare your brain… for in our next example, we will create a lua module that is capable of drawing a cow who will say whatever you want. [Note: most of the heavy lifting here is performed by the cowsay command, which you can install on macOS via brew install cowsay].

There are multiple ways of sharing a Lua API with users. In this section, I’ll stick with a common setup, which is to simply create a Lua module written in C. The advantages of this approach are:

The general structure of a Lua C module looks like this:

That’s the general idea. Here’s a specific working example:

Compiling a C module is a bit platform-dependent. I’ll assume you’ll run this from the same directory as earlier, where we put all those scrumptious Lua header files. Here’s a way to build the C module on macOS:

[Compilation tips specific to Windows and Ubuntu are in the book, by the way.]

Once you’ve done that, you’ll have a shiny new file called cow.so. The so stands for shared object, as this is executable object code that is designed to be used by possibly different binaries; hence it’s shared (or at least shareable in principle). It’s essentially the same as a DLL file on Windows (in fact this same source, compiled on Windows, would result in cow.dll).

Here’s an example use of our cow module from Lua’s official interpreter (which ought to be in the same directory right now if you’ve done all the above steps!):

I hope the above examples gave you a fun peek into the expressive power and ease of integration Lua offers. Creating Solid APIs with Lua is structured around a running example that I particularly like (completely unbiased here): Over the course of 6 chapters, we build a minimalistic game engine in C for games written in Lua, along with a somewhat mod-able ASCII-art game on top of that game engine; this game is called EatyGuy because it’s a guy who eats little dots all over the place:

If you like this stuff, here are a couple other resources I’ve put together:

Finally, you can probably read Solid APIs with Lua for free 😯🙀🎉. Here’s how:

Related posts:

Pulling out memories. “Timemory” is published by ..

It means that you believe, as if it is a fact, that there is always something, someone for you out there, so there is no rush in anything. You won’t settle for the next person you meet, and you won’t…

I have to admit that I am a driven individual that likes to work on myself with the hope that I will become my optimal self!. The past 6 months of my life has been one adventure after another. I’m an…