This first edition was written for Lua 5.0. While still largely relevant for later versions, there are some differences.
The fourth edition targets Lua 5.3 and is available at Amazon and other bookstores.
By buying the book, you also help to support the Lua project.

Lua C Executor
Lua C Api
Cin Launch
Using C In Lua

Programming in Lua

Part IV. The C APIChapter 24. An Overview of the C API

Lua is an embedded language.That means that Lua is not a stand-alone package,but a library that can be linked with other applicationsso as to incorporate Lua facilities into these applications.

Lua C Executor

You may be wondering:If Lua is not a stand-alone program,how come we have been using Lua stand alone through the whole book?The solution to this puzzle is the Lua interpreter(the executable lua).This interpreter is a tiny application(with less than five hundred lines of code)that uses the Lua library to implement the stand-alone interpreter.This program handles the interface with the user,taking her files and strings to feed them to the Lua library,which does the bulk of the work (such as actually running Lua code).

This ability to be used as a library to extend an applicationis what makes Lua an extension language.At the same time, a program that uses Lua can register newfunctions in the Lua environment;such functions are implemented in C (or another language)and can add facilities that cannot bewritten directly in Lua.This is what makes Lua an extensible language.

Why Lua is great and why you should use it. Writing simple wrapper/binding and using Lua for configuration files. Getting arrays and calling Lua functions from C. Template getArray function and other modifications. Calling C functions and creating C objects. Lua as well provides a proper C API to it's Virtual Machine. In contrary to VM itself, C API interface is stack based. So, most of the functions intended to be used with data is either adding some stuff on-top of virtual stack, or removing from it. Also, all the API calls must.

IUP is a multi-platform toolkit for building graphical user interfaces. It offers a simple API in three basic languages: C, Lua and LED. IUP's purpose is to allow a program source code to be compiled in different systems without any modification. After creating your file, you will need to import 2 main libraries in your C code, the lua lib, and the lua auxiliary lib: #include lua.h. Optional reading for this tutorial (You will need that for writing more complex functions) After that, you will want to study some specifications on chapters: 26 to 28 from the lua.

These two views of Lua(as an extension language and as an extensible language)correspond to two kinds of interaction between C and Lua.In the first kind, C has the control and Lua is the library.The C code in this kind of interactionis what we call application code.In the second kind, Lua has the control and C is the library.Here, the C code is called library code.Both application code and library code usethe same API to communicate with Lua,the so called C API.

The C API is the set of functions that allow C codeto interact with Lua.It comprises functions to read and write Lua global variables,to call Lua functions,to run pieces of Lua code,to register C functions so that they can later be called by Lua code,and so on.(Throughout this text, the term 'function' actually means'function or macro'.The API implements several facilities as macros.)

The C API follows the C modus operandi,which is quite different from Lua.When programming in C,we must care about type checking (and type errors),error recovery, memory-allocation errors,and several other sources of complexity.Most functions in the API do not check the correctness of their arguments;it is your responsibility to make sure that the argumentsare valid before calling a function.If you make mistakes,you can get a 'segmentation fault' error or something similar,instead of a well-behaved error message.Moreover, the API emphasizes flexibility and simplicity,sometimes at the cost of ease of use.Common tasks may involve several API calls.This may be boring,but it gives you full control over all details,such as error handling, buffer sizes, and the like.

As its title says,the goal of this chapter is to give an overview of what isinvolved when you use Lua from C.Do not bother understanding all the details of what is going on now.Later we will fill in the details.Nevertheless,do not forget that you can find more details about specific functionsin the Lua reference manual.Moreover, you can find several examples of the use of the API in theLua distribution itself.The Lua stand-alone interpreter (lua.c)provides examples of application code,while the standard libraries (lmathlib.c, lstrlib.c, etc.)provide examples of library code.

From now on, we are wearing a C programmers' hat.When we talk about 'you', we mean you when programming in C,or you impersonated by the C code you write.

A major component in the communication between Lua and C is anomnipresent virtual stack.Almost all API calls operate on values on this stack.All data exchange from Lua to C and from C to Lua occursthrough this stack.Moreover, you can use the stack to keep intermediateresults too.The stack helps to solve two impedance mismatches between Lua and C:The first is caused by Lua being garbage collected,whereas C requires explicit deallocation;the second results from the shock between dynamic typing in Luaversus the static typing of C.We will discuss the stack in more detail in Section 24.2.

EDIT: Part 2

Long time without posting, busy at work, family, etc.

Today I decided to write a bit on Lua and how to integrate it with C++.

Lua is a scripting language with an emphasis on being easily embeddable. Lua isused as the scripting language in Photoshop CS, and World of Warcraft, forexample. So if you are looking into adding scriptability to your C or C++applications Lua is quite suited for the task.

In order to learn Lua (both the language itself and how to embed it into yourapp) I recommend you Programming in Luaby one of the Luaauthors.

You can find tons of tutorials on how to get started with Lua. So I will focushere on how to integrate with C++. Most of the sources I’ve found about Lua -C++ integrations take the approach of frameworks to automatically wrap yourobjects/classes to be usable from within Lua. I find this approach confusing, Ithink it’s better to learn how to do it manually, and that’s what I will dohere.

Step 0. Compile Lua itself

Download Lua 5.2.1 and compile it. Usually it enough with make macosx ormake linux. That will generate liblua.a, the library that we will link to.

Step 1. Create a simple host app

We need a simple host app. Our host app will simply setup Lua and run a scriptfrom it. This script will have access to a std::queue from the host app. Thiswill illustrate how you can share objects with the Lua part. Later we will takea more complex example.

Let’s start with the basic skeleton of a lua environment with somecommunication with its host:

The Makefile

It uses LUAHOME that should point to the directory containing both liblua.a and the lua*.h files.

The samplehost application

The Lua script

The code explained step by step:

Initialization

That creates a lua_State loads the standard libs in it and also loads the code in luascript.lua.

Adding variables from C++ into Lua

Then it sets a global variable in Lua from C++ code using lua_setglobal. Ifyou don’t know what are the lua_pushxxxx and the Lua stack, etc. I recomentthat you take a look at the Lua Reference Manual and Programming in Lua.More or less Lua and the C++ communicate through the stack that livesin lua_State and there is bunch of function to manipulate that stack. So inorder to set a global in Lua from C++ you must push the value into the stackand call lua_setglobal that will pop the value in the stack and assign it tothe identifier provided inside the Lua environment.

C In Lua