跟着 Lua 5.1 官方参考文档学习 Lua (1)

1 – Introduction

Lua is an extension programming language designed to support general procedural programming with data description facilities. It also offers good support for object-oriented programming, functional programming, and data-driven programming. Lua is intended to be used as a powerful, light-weight scripting language for any program that needs one. Lua is implemented as a library, written in clean C (that is, in the common subset of ANSI C and C++).

例子：安装LuaJIT

LuaJIT is a Just-In-Time Compiler (JIT) for the Lua programming language.

官方页面：https://luajit.org/luajit.html

安装步骤

git clone https://github.com/LuaJIT/LuaJIT.git
make 
make install

安装后的头文件路径：/usr/local/include/luajit-2.1/

ls -lh /usr/local/include/luajit-2.1/
total 44K
-rw-r--r-- 1 root root 5.9K Dec 24 12:27 lauxlib.h
-rw-r--r-- 1 root root 4.5K Dec 24 12:27 luaconf.h
-rw-r--r-- 1 root root  13K Dec 24 12:27 lua.h
-rw-r--r-- 1 root root  135 Dec 24 12:27 lua.hpp
-rw-r--r-- 1 root root 3.0K Dec 24 12:27 luajit.h
-rw-r--r-- 1 root root 1.2K Dec 24 12:27 lualib.h

安装后的库文件路径：/usr/local/lib/libluajit-5.1.so

root@ubuntu:~/luajit# ls -lh /usr/local/lib/libluajit-5.1.so
lrwxrwxrwx 1 root root 31 Dec 24 12:27 /usr/local/lib/libluajit-5.1.so -> libluajit-5.1.so.2.1.1736781742

Being an extension language, Lua has no notion of a “main” program: it only works embedded in a host client, called the embedding program or simply the host.

This host program can invoke functions to execute a piece of Lua code, can write and read Lua variables, and can register C functions to be called by Lua code.

例子：执行 Lua 代码并读取 Lua 变量

#include <stdio.h>
#include <lua.h>
#include <lauxlib.h>
#include <lualib.h>

int main() {
    lua_State *L = luaL_newstate();  // 创建一个新的 Lua 状态
    luaL_openlibs(L);  // 打开 Lua 标准库

    // 执行 Lua 代码定义一个变量
    const char *lua_code = "x = 42";
    if (luaL_dostring(L, lua_code) != LUA_OK) {
        printf("Error: %s\n", lua_tostring(L, -1));
        return 1;
    }

    // 获取 Lua 中的变量 x
    lua_getglobal(L, "x");  // 将 Lua 全局变量 x 的值压入栈

    // 检查栈顶的数据类型并获取其值
    if (lua_isnumber(L, -1)) {
        double x = lua_tonumber(L, -1);
        printf("Value of x: %f\n", x);  // 输出 x 的值
    }

    lua_pop(L, 1);  // 弹出栈顶的 x 变量

    lua_close(L);  // 关闭 Lua 状态
    return 0;
}

编译程序

gcc -o test test.c -I/usr/local/include/luajit-2.1 -lluajit-5.1

输出

Value of x: 42.000000

例子：在 Lua 中修改宿主程序的变量

#include <stdio.h>
#include <lua.h>
#include <lauxlib.h>
#include <lualib.h>

int main() {
    lua_State *L = luaL_newstate();  // 创建 Lua 状态
    luaL_openlibs(L);  // 打开 Lua 标准库

    // 定义一个变量
    int value = 10;
    
    // 将 C 变量传递给 Lua
    lua_pushnumber(L, value);  // 将 value 压栈
    lua_setglobal(L, "value");  // 将栈顶的值设置为 Lua 中的全局变量 value

    // 在 Lua 中修改变量
    if (luaL_dostring(L, "value = value * 2") != LUA_OK) {
        printf("Error: %s\n", lua_tostring(L, -1));
        return 1;
    }

    // 获取 Lua 中修改后的变量值
    lua_getglobal(L, "value");
    if (lua_isnumber(L, -1)) {
        value = lua_tonumber(L, -1);
        printf("Modified value: %d\n", value);  // 输出修改后的值
    }

    lua_close(L);  // 关闭 Lua 状态
    return 0;
}

输出

Modified value: 20

例子：从 Lua 中调用 C 函数

#include <stdio.h>
#include <lua.h>
#include <lauxlib.h>
#include <lualib.h>

// 定义一个 C 函数
int add_numbers(lua_State *L) {
    // 获取 Lua 中传入的参数
    int a = luaL_checknumber(L, 1);
    int b = luaL_checknumber(L, 2);
    
    // 将返回值压栈
    lua_pushnumber(L, a + b);
    return 1;  // 返回 1 个值
}

int main() {
    lua_State *L = luaL_newstate();  // 创建 Lua 状态
    luaL_openlibs(L);  // 打开 Lua 标准库

    // 注册 C 函数到 Lua
    lua_register(L, "add_numbers", add_numbers);

    // 在 Lua 中调用 C 函数
    if (luaL_dostring(L, "result = add_numbers(10, 20)") != LUA_OK) {
        printf("Error: %s\n", lua_tostring(L, -1));
        return 1;
    }

    // 获取 Lua 中的返回值
    lua_getglobal(L, "result");
    if (lua_isnumber(L, -1)) {
        double result = lua_tonumber(L, -1);
        printf("Result from Lua: %f\n", result);  // 输出返回的值
    }

    lua_close(L);  // 关闭 Lua 状态
    return 0;
}

输出

Result from Lua: 30.000000

Through the use of C functions, Lua can be augmented to cope with a wide range of different domains, thus creating customized programming languages sharing a syntactical framework. The Lua distribution includes a sample host program called lua, which uses the Lua library to offer a complete, stand-alone Lua interpreter.

例子：使用 LuaJIT 交互式地执行Lua代码

luajit
LuaJIT 2.1.1736781742 -- Copyright (C) 2005-2025 Mike Pall. https://luajit.org/
JIT: ON SSE3 SSE4.1 fold cse dce fwd dse narrow loop abc sink fuse
> print('hello world')
hello world
> x = 10
> print(x)
10

Lua is free software, and is provided as usual with no guarantees, as stated in its license. The implementation described in this manual is available at Lua’s official web site, www.lua.org.

Like any other reference manual, this document is dry in places. For a discussion of the decisions behind the design of Lua, see the technical papers available at Lua’s web site. For a detailed introduction to programming in Lua, see Roberto’s book, Programming in Lua (Second Edition).

2 – The Language

This section describes the lexis, the syntax, and the semantics of Lua. In other words, this section describes which tokens are valid, how they can be combined, and what their combinations mean.

The language constructs will be explained using the usual extended BNF notation, in which {a} means 0 or more a’s, and [a] means an optional a. Non-terminals are shown like non-terminal, keywords are shown like kword, and other terminal symbols are shown like `**=**´. The complete syntax of Lua can be found in §8 at the end of this manual.

2.1 – Lexical Conventions

Names (also called identifiers) in Lua can be any string of letters, digits, and underscores, not beginning with a digit. This coincides with the definition of names in most languages. (The definition of letter depends on the current locale: any character considered alphabetic by the current locale can be used in an identifier.) Identifiers are used to name variables and table fields.

例子：有效的变量名

i j i10 _ij
aSomewhatLongName _INPUT

The following keywords are reserved and cannot be used as names:

     and       break     do        else      elseif
     end       false     for       function  if
     in        local     nil       not       or
     repeat    return    then      true      until     while

Lua is a case-sensitive language: and is a reserved word, but And and AND are two different, valid names.

As a convention, names starting with an underscore followed by uppercase letters (such as _VERSION) are reserved for internal global variables used by Lua.

例子：Lua 内部使用的全局变量

print(_VERSION) -- 版本号

print(_G) -- 保存全局变量的表

输出

Lua 5.1
table: 0x7f20e252bd78

The following strings denote other tokens:

     +     -     *     /     %     ^     #
     ==    ~=    <=    >=    <     >     =
     (     )     {     }     [     ]
     ;     :     ,     .     ..    ...

Literal strings can be delimited by matching single or double quotes, and can contain the following C-like escape sequences: ‘\a’ (bell), ‘\b’ (backspace), ‘\f’ (form feed), ‘\n’ (newline), ‘\r’ (carriage return), ‘\t’ (horizontal tab), ‘\v’ (vertical tab), ‘\\’ (backslash), ‘\"’ (quotation mark [double quote]), and ‘\'’ (apostrophe [single quote]).

Moreover, a backslash followed by a real newline results in a newline in the string.

例子：字符串

print('"hello"')
print("'hello'")
print("hello\"")
print('hello\'')
print("hello\n")
print("hello\
")

输出

"hello"
'hello'
hello"
hello'
hello

hello

A character in a string can also be specified by its numerical value using the escape sequence \ddd, where ddd is a sequence of up to three decimal digits.(Note that if a numerical escape is to be followed by a digit, it must be expressed using exactly three digits.)

例子：使用转义序列表示字符

print("alo\n123\"")

print('\97lo\10\04923"')

输出

alo
123"
alo
123"

这两个字符串是一样的。字符’a’可以使用转义序列’\97’表示，‘a’的ASCII码是十进制数97。同样的，换行符’\n’的ASCII码是十进制数10。字符’1’的ASCII码是十进制数49。

由于字符’1’后面跟着数字字符’23’，所以必须使用3位十进制数’\049’来表示字符’1’，否则’\492’会导致报错无效的转义序列。

invalid escape sequence near ''alo
'

Strings in Lua can contain any 8-bit value, including embedded zeros, which can be specified as ‘\0’.

例子：字符串中包含’\0’

local str = '123\0abc'
print(str)
print(#str) -- 长度为7，包含了字符'\0'的长度

输出

123abc
7

Literal strings can also be defined using a long format enclosed by long brackets. We define an opening long bracket of level n as an opening square bracket followed by n equal signs followed by another opening square bracket. So, an opening long bracket of level 0 is written as [[, an opening long bracket of level 1 is written as [=[, and so on. A closing long bracket is defined similarly; for instance, a closing long bracket of level 4 is written as ]====]. A long string starts with an opening long bracket of any level and ends at the first closing long bracket of the same level. Literals in this bracketed form can run for several lines, do not interpret any escape sequences, and ignore long brackets of any other level. They can contain anything except a closing bracket of the proper level.

例子：使用长括号的形式定义字符串

page = [[
<html>
<head>
<title>An HTML Page</title>
</head>
<body>
<a href="http://www.lua.org">Lua</a>
</body>
</html>
]]

print(page)

输出

<html>
<head>
<title>An HTML Page</title>
</head>
<body>
<a href="http://www.lua.org">Lua</a>
</body>
</html>

For convenience, when the opening long bracket is immediately followed by a newline, the newline is not included in the string. As an example, in a system using ASCII (in which ‘a’ is coded as 97, newline is coded as 10, and ‘1’ is coded as 49), the five literal strings below denote the same string:

     a = 'alo\n123"'
     a = "alo\n123\""
     a = '\97lo\10\04923"'
     a = [[alo
     123"]]
     a = [==[
     alo
     123"]==]

A numerical constant can be written with an optional decimal part and an optional decimal exponent. Lua also accepts integer hexadecimal constants, by prefixing them with 0x. Examples of valid numerical constants are

     3   3.0   3.1416   314.16e-2   0.31416E1   0xff   0x56

A comment starts with a double hyphen (--) anywhere outside a string. If the text immediately after -- is not an opening long bracket, the comment is a short comment, which runs until the end of the line. Otherwise, it is a long comment, which runs until the corresponding closing long bracket. Long comments are frequently used to disable code temporarily.

例子：短注释和长注释

-- 短注释

-- 长注释，注释一个函数
--[[
print(10) -- no action (comment)
--]]

---[[ 取消函数注释
print(10) --> 10
--]]

输出

10

小技巧：在长注释前添加-可将长注释变成两个短注释，从而取消注释

2.2 – Values and Types

Lua is a dynamically typed language. This means that variables do not have types; only values do. There are no type definitions in the language. All values carry their own type.

All values in Lua are first-class values. This means that all values can be stored in variables, passed as arguments to other functions, and returned as results.

There are eight basic types in Lua: nil, boolean, number, string, function, userdata, thread, and table.

例子：Lua 的七种数据类型

print(type("Hello world")) --> string
print(type(10.4*3)) --> number
print(type(print)) --> function
print(type(true)) --> boolean
print(type(nil)) --> nil
print(type({})) --> table
print(type(coroutine.create(function () end))) --> thread

输出

string
number
function
boolean
nil
table
thread

userdata 类型的数据只能使用 C API 创建。

Nil is the type of the value nil, whose main property is to be different from any other value; it usually represents the absence of a useful value.

Boolean is the type of the values false and true.

Both nil and false make a condition false; any other value makes it true.

例子：0和空字符串使条件表达式的值为true

if 0 then
    print('true')
end

if "" then
    print("true")
end

输出

true
true

Number represents real (double-precision floating-point) numbers. (It is easy to build Lua interpreters that use other internal representations for numbers, such as single-precision float or long integers; see file luaconf.h.)

String represents arrays of characters. Lua is 8-bit clean: strings can contain any 8-bit character, including embedded zeros (‘\0’) (see §2.1).

Lua can call (and manipulate) functions written in Lua and functions written in C (see §2.5.8).

例子：Lua 中调用 C 模块的函数

C模块代码

#include "lua.h"
#include "lualib.h"
#include "lauxlib.h"
#include <stdio.h>
#include <string.h>
#include <errno.h>
#include <dirent.h>

static int l_dir (lua_State *L) {
    DIR *dir;
    struct dirent *entry;
    int i;
    const char *path = luaL_checkstring(L, 1);
    /* open directory */
    dir = opendir(path);
    if (dir == NULL) { /* error opening the directory? */
        lua_pushnil(L); /* return nil */
        lua_pushstring(L, strerror(errno)); /* and error message */
        return 2; /* number of results */
    }
    /* create result table */
    lua_newtable(L);
    i = 1;
    while ((entry = readdir(dir)) != NULL) {
        lua_pushnumber(L, i++); /* push key */
        lua_pushstring(L, entry->d_name); /* push value */
        lua_settable(L, -3);
    }
    closedir(dir);
    return 1; /* table is already on top */
}

static const luaL_Reg mylib[] = {
    {"dir", l_dir},
    {NULL, NULL} 
};

int luaopen_mylib (lua_State *L) {
    luaL_register(L, "mylib", mylib);
    return 1; 
}

编译成动态库

gcc -o mylib.so -shared mylib.c -fPIC -I/usr/local/include/luajit-2.1 -lluajit-5.1

lua中调用C模块的dir函数

require "mylib"

a = mylib.dir("/usr")
for i=1, #a do
    print(a[i])
end

程序输出/usr目录下的所有目录名

The type userdata is provided to allow arbitrary C data to be stored in Lua variables. This type corresponds to a block of raw memory and has no pre-defined operations in Lua, except assignment and identity test. However, by using metatables, the programmer can define operations for userdata values (see §2.8). Userdata values cannot be created or modified in Lua, only through the C API. This guarantees the integrity of data owned by the host program.

例子：使用C API 创建 userdata 并在 Lua 中使用

#include <lua.h>
#include <lualib.h>
#include <lauxlib.h>

typedef struct {
    int value;
} MyData;

// 创建一个简单的 `userdata`
static int new_value(lua_State *L) {
    // 创建一个新的 userdata（MyData 类型）
    MyData *ud = (MyData *)lua_newuserdata(L, sizeof(MyData));

    // 初始化数据
    ud->value = 0;

    // 创建并设置元表
    luaL_getmetatable(L, "MyDataMetaTable");
    lua_setmetatable(L, -2);

    return 1; // 返回 userdata
}

// 获取 userdata 的值
static int get_value(lua_State *L) {
    MyData *ud = (MyData *)luaL_checkudata(L, 1, "MyDataMetaTable");
    lua_pushinteger(L, ud->value);
    return 1;
}

// 设置 userdata 的值
static int set_value(lua_State *L) {
    MyData *ud = (MyData *)luaL_checkudata(L, 1, "MyDataMetaTable");
    ud->value = luaL_checkinteger(L, 2);
    return 0;
}

// 定义模块方法
static const struct luaL_Reg mydata_methods[] = {
    {"new", new_value},
    {"get", get_value},
    {"set", set_value},
    {NULL, NULL}
};

// 打开模块并注册类型
int luaopen_mydata(lua_State *L) {
    // 创建并注册元表
    luaL_newmetatable(L, "MyDataMetaTable");

    // 注册模块方法
    luaL_register(L, "mydata", mydata_methods);

    return 1;
}

编译成动态库

gcc -o mydata.so -shared mydata.c -fPIC -I/usr/local/include/luajit-2.1 -lluajit-5.1

在Lua中使用userdata

local mydata = require("mydata")

-- 创建一个MyData类型的userdata
local data = mydata.new()

print(data)

-- 打印userdata的值
print(mydata.get(data))

-- 修改userdata的值
mydata.set(data, 100)
-- 打印新值
print(mydata.get(data))

输出

userdata: 0x7f9868901a80
0
100

The type thread represents independent threads of execution and it is used to implement coroutines (see §2.11). Do not confuse Lua threads with operating-system threads. Lua supports coroutines on all systems, even those that do not support threads.

例子：使用 C API 创建协程

#include <stdio.h>
#include <lua.h>
#include <lauxlib.h>
#include <lualib.h>

int main() {
    // 初始化 Lua 状态
    lua_State *L = luaL_newstate();
    luaL_openlibs(L);

    // 创建一个新的协程
    lua_State *co = lua_newthread(L);

    // 定义 Lua 脚本
    const char *lua_code = 
        "function my_func() \n"
        "    for i = 1, 5 do \n"
        "        print('Coroutine step: ' .. i) \n"
        "        coroutine.yield() \n"
        "    end \n"
        "end \n";

    // 加载并执行 Lua 脚本
    if (luaL_dostring(L, lua_code) != LUA_OK) {
        fprintf(stderr, "Error loading Lua script: %s\n", lua_tostring(L, -1));
        lua_close(L);
        return 1;
    }

    // 获取 my_func 函数并传递给协程
    lua_getglobal(L, "my_func");
    lua_xmove(L, co, 1);  // 将函数传递给协程

    // 启动协程，传递 0 个参数
    int status;
    while (1) {
        status = lua_resume(co, 0);  // 每次执行一次协程
        if (status == LUA_YIELD) {
            printf("LUA_YIELD\n");
        } else if (status == LUA_OK) {
            // 协程执行完毕
            printf("Coroutine finished\n");
            break;
        } else {
            // 出现错误
            printf("Error or coroutine finished with error\n");
            break;
        }
    }


    // 清理
    lua_close(L);
    return 0;
}

输出

Coroutine step: 1
LUA_YIELD
Coroutine step: 2
LUA_YIELD
Coroutine step: 3
LUA_YIELD
Coroutine step: 4
LUA_YIELD
Coroutine step: 5
LUA_YIELD
Coroutine finished

例子：Lua 中调用 C 函数，C 函数执行 yield

#include <stdio.h>
#include <lua.h>
#include <lauxlib.h>
#include <lualib.h>

int my_c_function(lua_State *L) {
    printf("in c function, yield\n");
    return lua_yield(L, 0);
}

int main() {
    // 初始化 Lua 状态
    lua_State *L = luaL_newstate();
    luaL_openlibs(L);

    // 注册 C 函数
    lua_register(L, "my_c_function", my_c_function);

    // 创建一个新的协程
    lua_State *co = lua_newthread(L);

    // 定义 Lua 脚本。在 Lua 中调用 C 函数，在 C 函数中 yield
    const char *lua_code = 
        "function my_func() \n"
        "    for i = 1, 5 do \n"
        "        print('Coroutine step: ' .. i) \n"
        "        my_c_function() \n"
        "        print('Coroutine continue') \n"
        "    end \n"
        "end \n";

    // 加载并执行 Lua 脚本
    if (luaL_dostring(L, lua_code) != LUA_OK) {
        fprintf(stderr, "Error loading Lua script: %s\n", lua_tostring(L, -1));
        lua_close(L);
        return 1;
    }

    // 获取 my_func 函数并传递给协程
    lua_getglobal(L, "my_func");
    lua_xmove(L, co, 1);  // 将函数传递给协程

    // 启动协程，传递 0 个参数
    int status;
    while (1) {
        status = lua_resume(co, 0);  // 每次执行一次协程
        if (status == LUA_YIELD) {
        } else if (status == LUA_OK) {
            // 协程执行完毕
            printf("Coroutine finished\n");
            break;
        } else {
            // 出现错误
            printf("Error or coroutine finished with error\n");
            break;
        }
    }

    // 清理
    lua_close(L);
    return 0;
}

输出

Coroutine step: 1
in c function, yield
Coroutine continue
Coroutine step: 2
in c function, yield
Coroutine continue
Coroutine step: 3
in c function, yield
Coroutine continue
Coroutine step: 4
in c function, yield
Coroutine continue
Coroutine step: 5
in c function, yield
Coroutine continue
Coroutine finished

注意：C 函数 yield 后，后续就不能继续进入 C 函数执行！

The type table implements associative arrays, that is, arrays that can be indexed not only with numbers, but with any value (except nil). Tables can be heterogeneous; that is, they can contain values of all types (except nil).

Tables are the sole data structuring mechanism in Lua; they can be used to represent ordinary arrays, symbol tables, sets, records, graphs, trees, etc.

补充：Lua uses tables to represent modules, packages, and objects as well. When we write io.read, we mean “the read function from the io module”. For Lua, this means “index the table io using the string “read” as the key”.

To represent records, Lua uses the field name as an index. The language supports this representation by providing a.name as syntactic sugar for a["name"]. There are several convenient ways to create tables in Lua (see §2.5.7).

Like indices, the value of a table field can be of any type (except nil). In particular, because functions are first-class values, table fields can contain functions. Thus tables can also carry methods (see §2.5.9).

Tables, functions, threads, and (full) userdata values are objects: variables do not actually contain these values, only references to them. Assignment, parameter passing, and function returns always manipulate references to such values; these operations do not imply any kind of copy.

The library function type returns a string describing the type of a given value.

2.2.1 – Coercion

Lua provides automatic conversion between string and number values at run time. Any arithmetic operation applied to a string tries to convert this string to a number, following the usual conversion rules. Conversely, whenever a number is used where a string is expected, the number is converted to a string, in a reasonable format.

例子：字符串和数字的自动转换

print("10" + 1) --> 11
print("10 + 1") --> 10 + 1
print("-5.3e-10"*"2") --> -1.06e-09
print(10 .. 20) --> 1020
print("hello" + 1) -- ERROR (cannot convert "hello")

输出

11
10 + 1
-1.06e-09
1020
luajit: 3.lua:5: attempt to perform arithmetic on a string value
stack traceback:
        3.lua:5: in main chunk
        [C]: at 0x00404b20

For complete control over how numbers are converted to strings, use the format function from the string library (see string.format).