Lua 5.1 參考手冊
by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes
Copyright ? 2006 Lua.org, PUC-Rio. All rights reserved.
1 -介紹
Lua 是一個擴展式程序設計語言犯祠，它被設計成支持通用的過程式編程，并有相關數(shù)據(jù)描述的設施募寨。 Lua 也能對面向?qū)ο缶幊糖阻耄瘮?shù)式編程啸驯，數(shù)據(jù)驅(qū)動式編程提供很好的支持。 它可以作為一個強大、輕量的腳本語言辙谜，供任何需要的程序使用问欠。 Lua 以一個用 clean C 寫成的庫形式提供肝匆。（所謂 Clean C ，指的 ANSI C 和 C++ 中共通的一個子集）
作為一個擴展式語言顺献，Lua 沒有 "main" 程序的概念：它只能嵌入 一個宿主程序中工作旗国，這個宿主程序被稱作 embedding program 或簡稱為 host 。 宿主程序可以通過調(diào)用函數(shù)執(zhí)行一小段 Lua 代碼滚澜，可以讀寫 Lua 變量粗仓，可以注入 C 函數(shù)讓 Lua 代碼調(diào)用。 這些擴展的 C 函數(shù)设捐，可以大大的擴展了 Lua 可以處理事務的領域借浊，這樣就可以訂制出各種語言， 而它們共享一個統(tǒng)一的句法格式的框架萝招。 Lua 的官方發(fā)布版就包含了一個叫做 lua 的簡單的宿主程序蚂斤，它用 Lua 庫提供了一個保證獨立的 Lua 解釋器。
Lua 是一個自由軟件槐沼，它的使用許可決定了對它的使用過程一般沒有任何保證曙蒸。 這份手冊中描述的東西的實現(xiàn)捌治，可以在 Lua 的官方網(wǎng)站 www.lua.org 找到，
跟其它的許多參考手冊一樣纽窟，這份文檔有些地方比較枯燥肖油。關于Lua 的設計想法的探討，可以看看 Lua 網(wǎng)站上提供的技術(shù)論文臂港。 有關用 Lua 編程的細節(jié)介紹森枪，可以讀一下 Roberto 的書，Programming in Lua (Second Edition) 审孽。
2 -語言
這一節(jié)從詞法县袱、語法、句法上描述Lua 佑力。 換句話說式散，這一節(jié)描述了哪些 token （符記）是有效的，它們?nèi)绾伪唤M合起來打颤，這些組合方式有什么含義暴拄。
關于語言的構(gòu)成概念將用常見的擴展BNF 表達式寫出。也就是這個樣子： {a} 意思是 0 或多個 a 编饺， [a] 意思是一個可選的 a 揍移。 非最終的符號會保留原來的樣子，關鍵字則看起來像這樣 kword 反肋， 其它最終的符號則寫成 `=′ 那伐。 完整的 Lua 語法可以在本手冊最后找到。
2.1 -詞法約定
Lua 中用到的 名字（也稱作標識符）可以是任何非數(shù)字開頭的字母石蔗、數(shù)字罕邀、下劃線組成的字符串。這符合幾乎所有編程語言中關于名字的定義养距。（字母的定義依賴于當前環(huán)境：系統(tǒng)環(huán)境中定義的字母表中的字母都可以被用于標識符诉探。）標識符用來命名變量竹宋，或作為表的域名丰滑。
下面的關鍵字是保留的，不能用作名字：
? ? and? ? ? break? ? do? ? ? ? else? ? ? elseif
? ? end? ? ? false? ? for? ? ? function? if
? ? in? ? ? ? local? ? nil? ? ? not? ? ? or
? ? repeat? ? return? ? then? ? ? true? ? ? until? ? while
Lua 是一個大小寫敏感的語言： and 是一個保留字旬蟋，但是 And 和 AND 則是兩個不同的合法的名字耘纱。 一般約定敬肚，以下劃線開頭連接一串大寫字母的名字（比如 _VERSION）被保留用于Lua 內(nèi)部全局變量。
下面這些是其它的token ：
? ? +? ? -? ? *? ? /? ? %? ? ^? ? #
? ? ==? ? ~=? ? <=? ? >=? ? <? ? >? ? =
? ? (? ? )? ? {? ? }? ? [? ? ]
? ? ;? ? :? ? ,? ? .? ? ..? ? ...
字符串既可以用一對單引號引起束析，也可以是雙引號艳馒，里面還可以包含類似C 的轉(zhuǎn)義符： '\a' （響鈴）， '\b' （退格）， '\f' （表單）弄慰， '\n' （換行）第美， '\r' （回車）， '\t' （橫向制表）陆爽， '\v' （縱向制表）什往， '\\' （反斜杠）， '\"' （雙引號）慌闭， 以及 '\'' （單引號)恶守。 而且，如果在一個反斜杠后跟了一個真正的換行符贡必，其結(jié)果就是在字符串中產(chǎn)生一個換行符。 我們還可以用反斜杠加數(shù)字的形式 \ddd 來描述一個字符庸毫。這里仔拟， ddd 是一串最多三位的十進制數(shù)字。（注意飒赃，如果需要在這種描述方法后接一個是數(shù)字的字符利花， 那么反斜杠后必須寫滿三個數(shù)字。）Lua 中的字符串可以包含任何 8 位的值载佳。包括用 '\0' 表示的零炒事。
只有在你需要把不同的引號、換行蔫慧、反斜杠挠乳、或是零結(jié)束符這些字符置入字符串時，你才必須使用轉(zhuǎn)義符姑躲。別的任何字符都可以直接寫在文本里睡扬。（一些控制符可以會影響文件系統(tǒng)造成某些問題，但是不會引起Lua 的任何問題黍析。）
字符串還可以用一種長括號括起來的方式定義卖怜。我們把兩個正的方括號間插入n 個等號定義為第 n 級正長括號。 就是說阐枣，0 級正的長括號寫作[[ 马靠， 一級正的長括號寫作 [=[ ，如此等等蔼两。 反的長擴展也作類似定義甩鳄； 舉個例子，4 級反的長括號寫作 ]====] 额划。 一個長字符串可以由任何一級的正的長括號開始娩贷，而由第一個碰到的同級反的長括號結(jié)束。 整個詞法分析過程將不受分行限制锁孟，不處理任何轉(zhuǎn)意符彬祖，并且忽略掉任何不同級別的長括號茁瘦。 這種方式描述的字符串可以包含任何東西，當然特定級別的反長括號除外储笑。
另一個約定是甜熔，當正的長括號后面立即跟了一個換行符，這個換行符就不包含在這個字符串內(nèi)突倍。舉個例子腔稀，假設一個系統(tǒng)使用ASCII 碼 （這時，'a' 編碼為 97 羽历，換行符編碼為 10 焊虏，'1' 編碼為 49 ）， 下面五種方式描述了完全相同的字符串：
? ? a = 'alo\n123"'
? ? a = "alo\n123\""
? ? a = '\97lo\10\04923"'
? ? a = [[alo
? ? 123"]]
? ? a = [==[
? ? alo
? ? 123"]==]
數(shù)字常量可以分兩部分寫秕磷，十進制底數(shù)部分和十進制的指數(shù)部分诵闭。指數(shù)部分是可選的。Lua 也支持十六進制整數(shù)常量澎嚣，只需要在前面加上前綴0x 疏尿。 下面是一些合法的數(shù)字常量的例子：
? ? 3? 3.0? 3.1416? 314.16e-2? 0.31416E1? 0xff? 0x56
注釋可以在除字符串內(nèi)的任何地方是以兩橫(--) 開始。 如果跟在兩橫后面的不是一個長括號易桃，這就是一個短注釋褥琐，它的作用范圍直到行末； 否則就是一個長注釋晤郑，其作用范圍直到遇到反的長括號敌呈。 長注釋通常被用來臨時屏蔽代碼塊。
2.2 -值與類型
Lua 是一種 動態(tài)類型語言造寝。這意味著變量沒有類型驱富，只有值才有類型。語言中不存在類型定義匹舞。而所有的值本身攜帶它們自己的類型信息褐鸥。
Lua 中的所有值都是一致 (first-class) 的。 這意味著所有的值都可以被放在變量里赐稽，當作參數(shù)傳遞到另一個函數(shù)中叫榕，并被函數(shù)作為結(jié)果返回。
Lua 中有八種基本類型： nil, boolean, number, string, function, userdata, thread, and table. Nil 類型只有一種值 nil 姊舵，它的主要用途用于標表識和別的任何值的差異晰绎； 通常，當需要描述一個無意義的值時會用到它括丁。 Boolean 類型只有兩種值：false 和 true荞下。nil和false 都能導致條件為假；而另外所有的值都被當作真。 Number 表示實數(shù)（雙精度浮點數(shù)）尖昏。 （編譯一個其它內(nèi)部數(shù)字類型的 Lua 解釋器是件很容易的事仰税；比如把內(nèi)部數(shù)字類型改作 單精度浮點數(shù)或長整型。參見文件 luaconf.h 抽诉。） String 表示一串字符的數(shù)組陨簇。 Lua 是 8-bit clean 的： 字符串可以包含任何 8 位字符， 包括零結(jié)束符 ('\0') （參見 §2.1）迹淌。
Lua 可以調(diào)用（和處理）用 Lua 寫的函數(shù)以及用 C 寫的函數(shù)（參見 §2.5.8）.
userdata 類型用來將任意 C 數(shù)據(jù)保存在 Lua 變量中河绽。 這個類型相當于一塊原生的內(nèi)存，除了賦值和相同性判斷唉窃，Lua 沒有為之預定義任何操作耙饰。 然而，通過使用 metatable （元表） 纹份，程序員可以為 userdata 自定義一組操作 （參見 §2.8）苟跪。userdata 不能在 Lua 中創(chuàng)建出來，也不能在 Lua 中修改矮嫉。這樣的操作只能通過 C API。 這一點保證了宿主程序完全掌管其中的數(shù)據(jù)牍疏。
thread 類型用來區(qū)別獨立的執(zhí)行線程蠢笋，它被用來實現(xiàn) coroutine （協(xié)同例程）（參見 §2.11）。不要把Lua 線程跟操作系統(tǒng)的線程搞混鳞陨。 Lua 可以在所有的系統(tǒng)上提供對 coroutine 的支持昨寞，即使系統(tǒng)并不支持線程。
table 類型實現(xiàn)了一個關聯(lián)數(shù)組篮洁。也就是說蔑鹦， 數(shù)組可以用任何東西（除了nil）做索引遍坟，而不限于數(shù)字。table 可以以不同類型的值構(gòu)成享怀；它可以包含所有的類型的值（除nil 外）。 table 是 lua 中唯一的一種數(shù)據(jù)結(jié)構(gòu)趟咆；它可以用來描述原始的數(shù)組添瓷、符號表、集合值纱、 記錄鳞贷、圖、樹虐唠、等等搀愧。 用于表述記錄時，lua 使用域名作為索引。 語言本身采用一種語法糖咱筛，支持以 a.name 的形式表示 a["name"]搓幌。有很多形式用于在lua 中創(chuàng)建一個 table （參見§2.5.7）。
跟索引一樣眷蚓，table 每個域中的值也可以是任何類型（除nil外）鼻种。特別的，因為函數(shù)本身也是值沙热，所以table 的域中也可以放函數(shù)叉钥。 這樣 table 中就可以有一些methods 了 （參見see §2.5.9）。
table篙贸， function 投队，thread ，和 (full) userdata 這些類型的值是所謂的對象： 變量本身并不會真正的存放它們的值爵川，而只是放了一個對對象的引用敷鸦。 賦值，參數(shù)傳遞寝贡，函數(shù)返回扒披，都是對這些對象的引用進行操作； 這些操作不會做暗地里做任何性質(zhì)的拷貝圃泡。
庫函數(shù)type 可以返回一個描述給定值的類型的字符串碟案。
2.2.1 -強制轉(zhuǎn)換
Lua 提供運行時字符串到數(shù)字的自動轉(zhuǎn)換。 任何對字符串的數(shù)學運算操作都會嘗試用一般的轉(zhuǎn)換規(guī)則把這個字符串轉(zhuǎn)換成一個數(shù)字颇蜡。 相反价说，無論何時，一個數(shù)字需要作為字符串來使用時风秤，數(shù)字都會以合理的格式轉(zhuǎn)換為字符串鳖目。 需要完全控制數(shù)字怎樣轉(zhuǎn)換為字符串，可以使用字符串庫中的 format 函數(shù) （參見 string.format）缤弦。
2.3 -變量
寫上變量的地方意味著當以其保存的值來替代之领迈。Lua 中有三類變量：全局變量，局部變量碍沐，還有 table 的域惦费。
一個單一的名字可以表示一個全局變量，也可以表示一個局部變量（或者是一個函數(shù)的參數(shù)抢韭，這是一種特殊形式的局部變量）：
var ::= Name
Name 就是 §2.1 中所定義的標識符薪贫。
任何變量都被假定為全局變量，除非顯式的以local 修飾定義 （參見§2.4.7）刻恭。局部變量有其作用范圍：局部變量可以被定義在它作用范圍中的函數(shù)自由使用（參見§2.6）瞧省。
在變量的首次賦值之前扯夭，變量的值均為nil。
方括號被用來對table 作索引：
var ::= prefixexp `[′ exp `]′
對全局變量以及table 域之訪問的含義可以通過 metatable 來改變鞍匾。 以取一個變量下標指向的量t[i] 等價于調(diào)用 gettable_event(t,i)交洗。（參見§2.8 ，有一份完整的關于 gettable_event 函數(shù)的說明橡淑。 這個函數(shù)并沒有在 lua 中定義出來构拳，也不能在 lua 中調(diào)用。 這里我們把它列出來只是方便說明梁棠。）
var.Name 這種語法只是一個語法糖置森，用來表示 var["Name"]：
var ::= prefixexp `.′ Name
所有的全局變量都是放在一個特定lua table 的諸個域中，這個特定的 table 叫作environment （環(huán)境）table 或者簡稱為 環(huán)境 （參見 §2.9）符糊。每個函數(shù)都有對一個環(huán)境的引用凫海，所以一個函數(shù)中可見的所有全局變量都放在這個函數(shù)所引用的環(huán)境表（environment table）中。 當一個函數(shù)被創(chuàng)建出來男娄，它會從創(chuàng)建它的函數(shù)中繼承其環(huán)境行贪，你可以調(diào)用getfenv 取得其環(huán)境。 如果想改變環(huán)境模闲，可以調(diào)用 setfenv建瘫。（對于C 函數(shù)，你只能通過 debug 庫來改變其環(huán)境尸折； 參見§5.9）啰脚。
對一個全局變量x 的訪問 等價于 _env.x，而這又可以等價于
? ? gettable_event(_env, "x")
這里翁授，_env 是當前運行的函數(shù)的環(huán)境拣播。 （函數(shù) gettable_event 的完整說明參見 §2.8晾咪。這個函數(shù)并沒有在lua 中定義出來收擦，也不能調(diào)用。 當然谍倦，_env 這個變量也同樣沒有在 Lua 中定義出來塞赂。 我們在這里使用它們，僅僅只是方便解釋而已昼蛀。）
2.4 -語句段（Statement）
Lua 支持慣例形式的語句段宴猾，它和 Pascal 或是 C 很相象。 這個集合包括賦值叼旋，控制結(jié)構(gòu)仇哆，函數(shù)調(diào)用，還有變量聲明夫植。
2.4.1 -Chunk（語句組）
Lua 的一個執(zhí)行單元被稱作 chunk讹剔。一個chunk 就是一串語句段油讯，它們會被循序的執(zhí)行。 每個語句段可以以一個分號結(jié)束：
chunk ::= {stat [`;′]}
這兒不允許有空的語句段延欠，所以';;' 是非法的陌兑。
lua 把一個 chunk 當作一個擁有不定參數(shù)的匿名函數(shù) （參見 §2.5.9）處理。正是這樣由捎，chunk 內(nèi)可以定義局部變量兔综，接收參數(shù)，并且返回值狞玛。
chunk 可以被保存在一個文件中软驰，也可以保存在宿主程序的一個字符串中。 當一個 chunk 被執(zhí)行为居，首先它會被預編譯成虛擬機中的指令序列碌宴， 然后被虛擬機解釋運行這些指令。
chunk 也可以被預編譯成二進制形式蒙畴；細節(jié)參考程序 luac贰镣。用源碼形式提供的程序和被編譯過的二進制形式的程序是可以相互替換的；Lua 會自動識別文件類型并做正確的處理膳凝。
2.4.2 -語句塊
語句塊是一列語句段碑隆；從語法上來說，一個語句塊跟一個chunk 相同：
block ::= chunk
一個語句塊可以被顯式的寫成一個單獨的語句段：
stat ::= do block end
顯式的語句塊對于控制變量的作用范圍很有用蹬音。有時候逆航，顯式的語句塊被用來在另一個語句塊中插入return 或是 break （參見 §2.4.4）岛琼。
2.4.3 -賦值
Lua 允許多重賦值。 因此，賦值的語法定義是等號左邊放一系列變量艺普， 而等號右邊放一系列的表達式。 兩邊的元素都用逗號間開：
stat ::= varlist1 `=′ explist1
varlist1 ::= var {`,′ var}
explist1 ::= exp {`,′ exp}
表達式放在§2.5 里討論依鸥。
在作賦值操作之前啰挪，那一系列的右值會被對齊到左邊變量需要的個數(shù)。如果右值比需要的更多的話苔埋，多余的值就被扔掉懦砂。如果右值的數(shù)量不夠需求，將會按所需擴展若干個nil组橄。如果表達式列表以一個函數(shù)調(diào)用結(jié)束荞膘，這個函數(shù)所返回的所有值都會在對齊操作之前被置入右值序列中。（除非這個函數(shù)調(diào)用被用括號括了起來玉工；參見§2.5）羽资。
賦值段首先會做運算完所有的表達式，然后僅僅做賦值操作遵班。因此屠升，下面這段代碼
? ? i = 3
? ? i, a[i] = i+1, 20
會把a[3] 設置為 20瞄勾，而不會影響到 a[4] 。 這是因為 a[i] 中的 i 在被賦值為 4 之前就被拿出來了（那時是 3 ）弥激。 簡單說 进陡，這樣一行
? ? x, y = y, x
可以用來交換x 和 y 中的值。
對全局變量以及table 中的域的賦值操作的含義可以通過 metatable 來改變微服。 對變量下標指向的賦值趾疚，即t[i] = val 等價于 settable_event(t,i,val)。（關于函數(shù)settable_event 的詳細說明以蕴，參見 §2.8糙麦。這個函數(shù)并沒有在Lua 中定義出來，也不可以被調(diào)用丛肮。 這里我們列出來赡磅，僅僅出于方便解釋的目的）
對于全局變量的賦值x = val 等價于 _env.x = val，這個又可以等價于
? ? settable_event(_env, "x", val)
這里宝与，_env 指的是正在運行中的函數(shù)的環(huán)境焚廊。 （變量 _env 并沒有在 Lua 中定義出來。 我們僅僅出于解釋的目的在這里寫出來习劫。）
2.4.4 -控制結(jié)構(gòu)
if咆瘟、while、以及repeat 這些控制結(jié)構(gòu)符合通常的意義诽里，而且也有類似的語法：
stat ::= while exp do block end
stat ::= repeat block until exp
stat ::= if exp then block {elseif exp then block} [else block] end
Lua 也有一個 for 語句袒餐，它有兩種形式（參見 §2.4.5）。
控制結(jié)構(gòu)中的條件表達式可以返回任何值谤狡。false 和 nil 兩者都被認為是假條件灸眼。 所有不同于 nil 和 false 的其它值都被認為是真 （特別需要注意的是，數(shù)字 0 和空字符串也被認為是真）墓懂。
在repeat–until 循環(huán)中焰宣， 內(nèi)部語句塊的結(jié)束點不是在 until 這個關鍵字處， 它還包括了其后的條件表達式拒贱。 因此宛徊，條件表達式中可以使用循環(huán)內(nèi)部語句塊中的定義的局部變量佛嬉。
return 被用于從函數(shù)或是 chunk（其實它就是一個函數(shù)）中 返回值逻澳。 函數(shù)和 chunk 可以返回不只一個值， 所以 return 的語法為
stat ::= return [explist1]
break 被用來結(jié)束 while暖呕、repeat斜做、或for 循環(huán)， 它將忽略掉循環(huán)中下面的語句段的運行：
stat ::= break
break 跳出最內(nèi)層的循環(huán)湾揽。
return 和 break 只能被寫在一個語句塊的最后一句瓤逼。 如果你真的需要從語句塊的中間 return 或是 break 笼吟， 你可以使用顯式的聲名一個內(nèi)部語句塊。 一般寫作 do return end 或是 do break end霸旗，可以這樣寫是因為現(xiàn)在return 或 break 都成了一個語句塊的最后一句了贷帮。
2.4.5 -For 語句
for 有兩種形式：一種是數(shù)字形式，另一種是一般形式诱告。
數(shù)字形式的for 循環(huán)撵枢，通過一個數(shù)學運算不斷的運行內(nèi)部的代碼塊。 下面是它的語法：
stat ::= for Name `=′ exp `,′ exp [`,′ exp] do block end
block 將把 name 作循環(huán)變量精居。從第一個 exp 開始起锄禽，直到第二個 exp 的值為止，其步長為 第三個 exp 靴姿。 更確切的說沃但，一個 for 循環(huán)看起來是這個樣子
? ? for v = e1, e2, e3 do block end
這等價于代碼：
? ? do
? ? ? local var, limit, step = tonumber(e1), tonumber(e2), tonumber(e3)
? ? ? if not (var and limit and step) then error() end
? ? ? while (step > 0 and var <= limit) or (step <= 0 and var >= limit) do
? ? ? ? local v = var
? ? ? ? block
? ? ? ? var = var + step
? ? ? end
? ? end
注意下面這幾點：
[if !supportLists]· [endif]所有三個控制表達式都只被運算一次，表達式的計算在循環(huán)開始之前佛吓。這些表達式的結(jié)果必須是數(shù)字宵晚。
[if !supportLists]· [endif]var 、limit 维雇、以及 step 都是一些不可見的變量坝疼。 這里給它們起的名字都僅僅用于解釋方便。
[if !supportLists]· [endif]如果第三個表達式（步長）沒有給出谆沃，會把步長設為1 钝凶。
[if !supportLists]· [endif]你可以用break 來退出 for 循環(huán)。
[if !supportLists]· [endif]循環(huán)變量v 是一個循環(huán)內(nèi)部的局部變量唁影； 當 for 循環(huán)結(jié)束后耕陷，你就不能在使用它。 如果你需要這個值据沈，在退出循環(huán)前把它賦給另一個變量哟沫。
一般形式的for 通過一個叫作迭代器（iterators）的函數(shù)工作。每次迭代锌介，迭代器函數(shù)都會被調(diào)用以產(chǎn)生一個新的值嗜诀，當這個值為nil 時，循環(huán)停止孔祸。 一般形式的 for 循環(huán)的語法如下：
stat ::= for namelist in explist1 do block end
namelist ::= Name {`,′ Name}
for 語句好似這樣
? ? for var_1, ···, var_n in explist do block end
它等價于這樣一段代碼：
? ? do
? ? ? local f, s, var = explist
? ? ? while true do
? ? ? ? local var_1, ···, var_n = f(s, var)
? ? ? ? var = var_1
? ? ? ? if var == nil then break end
? ? ? ? block
? ? ? end
? ? end
注意以下幾點：
[if !supportLists]· [endif]explist 只會被計算一次隆敢。 它返回三個值， 一個迭代器函數(shù)崔慧，一個狀態(tài)拂蝎，一個迭代器的初始值。
[if !supportLists]· [endif]f惶室、s温自、以及var 都是不可見的變量玄货。 這里給它們起的名字都只是為了解說方便。
[if !supportLists]· [endif]你可以使用break 來跳出 for 循環(huán)悼泌。
[if !supportLists]· [endif]循環(huán)變量var_i 對于循環(huán)來說是一個局部變量松捉； 你不可以在 for 循環(huán)結(jié)束后繼續(xù)使用。 如果你需要保留這些值馆里，那么就在循環(huán)結(jié)束前賦值到別的變量里去惩坑。
2.4.6 -把函數(shù)調(diào)用作為語句段
為了允許使用可能的副作用，函數(shù)調(diào)用可以被作為一個語句段執(zhí)行：
stat ::= functioncall
在這種情況下也拜，所有的返回值都被舍棄以舒。函數(shù)調(diào)用在§2.5.8 中解釋。
2.4.7 -局部變量聲名
局部變量可以在語句塊中任何地方聲名慢哈。聲名可以包含一個初始化賦值操作：
stat ::= local namelist [`=′ explist1]
如果有的話蔓钟，初始化賦值操作的行為等同于賦值操作（參見§2.4.3）。否則卵贱，所有的變量將被初始化為nil改衩。
一個chunk 同時也是一個語句塊（參見§2.4.1）敷燎，所以局部變量可以放在chunk 中那些顯式注明的語句塊之外坛增。 這些局部變量的作用范圍從聲明起一直延伸到 chunk 末尾搪柑。
局部變量的可見規(guī)則在§2.6 中解釋。
2.5 -表達式
Lua 中有這些基本表達式：
exp ::= prefixexp
exp ::= nil | false | true
exp ::= Number
exp ::= String
exp ::= function
exp ::= tableconstructor
exp ::= `...′
exp ::= exp binop exp
exp ::= unop exp
prefixexp ::= var | functioncall | `(′ exp `)′
數(shù)字和字符串在§2.1 中解釋编振； 變量在 §2.3 中解釋缀辩； 函數(shù)定義在 §2.5.9 中解釋； 函數(shù)調(diào)用在 §2.5.8 中解釋踪央； table 的構(gòu)造在 §2.5.7 中解釋臀玄； 可變參數(shù)的表達式寫作三個點 ('...') ，它只能被用在有可變參數(shù)的函數(shù)中畅蹂； 這些在 §2.5.9 中解釋健无。
二元操作符包含有數(shù)學運算操作符（參見§2.5.1），比較操作符（參見§2.5.2）液斜，邏輯操作符（參見§2.5.3）累贤，以及連接操作符（參見§2.5.4）。一元操作符包括負號（參見see§2.5.1）少漆，取反not（參見§2.5.3）臼膏，和取長度操作符（參見§2.5.5）。
函數(shù)調(diào)用和可變參數(shù)表達式都可以放在多重返回值中检疫。如果表達式作為一個獨立語句段出現(xiàn)（參見§2.4.6）（這只能是一個函數(shù)調(diào)用）讶请，它們的返回列表將被對齊到零個元素祷嘶，也就是忽略所有返回值屎媳。如果表達式用于表達式列表的最后（或者是唯一）的元素夺溢，就不會有任何的對齊操作（除非函數(shù)調(diào)用用括號括起來）。在任何其它的情況下烛谊，Lua 將把表達式結(jié)果看成單一元素风响， 忽略除第一個之外的任何值。
這里有一些例子：
? ? f()? ? ? ? ? ? ? ? -- 調(diào)整到 0 個結(jié)果
? ? g(f(), x)? ? ? ? ? -- f() 被調(diào)整到一個結(jié)果
? ? g(x, f())? ? ? ? ? -- g 被傳入 x 加上所有 f() 的返回值
? ? a,b,c = f(), x? ? -- f() 被調(diào)整到一個結(jié)果 （ c 在這里被賦為 nil ）
? ? a,b = ...? ? ? ? ? -- a 被賦值為可變參數(shù)中的第一個丹禀，
? ? ? ? ? ? ? ? ? ? ? ? -- b 被賦值為第二個 （如果可變參數(shù)中并沒有對應的值状勤，
-- 這里 a 和 b 都有可能被賦為 nil）
? ? a,b,c = x, f()? ? -- f() 被調(diào)整為兩個結(jié)果
? ? a,b,c = f()? ? ? ? -- f() 被調(diào)整為三個結(jié)果
? ? return f()? ? ? ? -- 返回 f() 返回的所有結(jié)果
? ? return ...? ? ? ? -- 返回所有從可變參數(shù)中接收來的值
? ? return x,y,f()? ? -- 返回 x, y, 以及所有 f() 的返回值
? ? {f()}? ? ? ? ? ? ? -- 用 f() 的所有返回值創(chuàng)建一個列表
? ? {...}? ? ? ? ? ? ? -- 用可變參數(shù)中的所有值創(chuàng)建一個列表
? ? {f(), nil}? ? ? ? -- f() 被調(diào)整為一個結(jié)果
被括號括起來的表達式永遠被當作一個值。所以双泪，(f(x,y,z)) 即使 f 返回多個值持搜，這個表達式永遠是一個單一值。 （(f(x,y,z)) 的值是 f 返回的第一個值焙矛。如果 f 不返回值的話葫盼，那么它的值就是 nil 。）
2.5.1 -數(shù)學運算操作符
Lua 支持常見的數(shù)學運算操作符： 二元操作 + （加法）村斟， - （減法）贫导，* （乘法）， / （除法）蟆盹， % （取模）孩灯，以及 ^ （冪）； 和一元操作 - （取負）逾滥。 如果對數(shù)字操作峰档，或是可以轉(zhuǎn)換為數(shù)字的字符串（參見 §2.2.1），所有這些操作都依賴它通常的含義寨昙。冪操作可以對任何冪值都正常工作面哥。比如，x^(-0.5) 將計算出 x 平方根的倒數(shù)毅待。 取模操作被定義為
? ? a % b == a - math.floor(a/b)*b
這就是說尚卫，其結(jié)果是商相對負無窮圓整后的余數(shù)。（譯注：負數(shù)對正數(shù)取模的結(jié)果為正數(shù)）
2.5.2 -比較操作符
Lua 中的比較操作符有
? ? ==? ? ~=? ? <? ? >? ? <=? ? >=
這些操作的結(jié)果不是false 就是 true尸红。
等于操作(==) 首先比較操作數(shù)的類型吱涉。 如果類型不同，結(jié)果就是 false外里。否則怎爵，繼續(xù)比較值。數(shù)字和字符串都用常規(guī)的方式比較盅蝗。對象（table 鳖链，userdata ，thread ，以及函數(shù)）以引用的形式比較： 兩個對象只有在它們指向同一個東西時才認為相等芙委。 每次你創(chuàng)建一個新對象（一個 table 或是 userdata 逞敷，thread 函數(shù)）， 它們都各不相同灌侣，即不同于上次創(chuàng)建的東西推捐。
你可以改變Lua 比較 table 和 userdata 的方式，這需要使用 "eq" 這個原方法 （參見§2.8）侧啼。
§2.2.1 中提及的轉(zhuǎn)換規(guī)則并不作用于比較操作牛柒。 所以， "0"==0 等于 false痊乾，而且t[0] 和 t["0"] 描述的是 table 中不同的域皮壁。
操作符~= 完全等價于 (==) 操作的反值。
大小比較操作以以下方式進行哪审。如果參數(shù)都是數(shù)字闪彼，那么就直接做數(shù)字比較。否則协饲，如果參數(shù)都是字符串畏腕，就用字符串比較的方式進行。再則茉稠，Lua 就試著調(diào)用 "lt" 或是 "le" 元方法 （參見§2.8）描馅。
2.5.3 -邏輯操作符
Lua 中的邏輯操作符有 and, or, 以及 not。和控制結(jié)構(gòu)（參見§2.4.4）一樣而线，所有的邏輯操作符把false 和 nil 都作為假铭污， 而其它的一切都當作真。
取反操作not 總是返回 false 或 true 中的一個膀篮。 與操作符 and 在第一個參數(shù)為 false 或 nil 時 返回這第一個參數(shù)嘹狞； 否則，and 返回第二個參數(shù)誓竿。 或操作符 or 在第一個參數(shù)不為 nil 也不為 false 時磅网， 返回這第一個參數(shù)，否則返回第二個參數(shù)筷屡。 and 和 or 都遵循短路規(guī)則涧偷； 也就是說，第二個操作數(shù)只在需要的時候去求值毙死。 這里有一些例子：
? ? 10 or 20? ? ? ? ? ? --> 10
? ? 10 or error()? ? ? --> 10
? ? nil or "a"? ? ? ? ? --> "a"
? ? nil and 10? ? ? ? ? --> nil
? ? false and error()? --> false
? ? false and nil? ? ? --> false
? ? false or nil? ? ? ? --> nil
? ? 10 and 20? ? ? ? ? --> 20
（在這本手冊中燎潮，--> 指前面表達式的結(jié)果。）
2.5.4 -連接符
Lua 中字符串的連接操作符寫作兩個點 ('..')扼倘。 如果兩個操作數(shù)都是字符串或都是數(shù)字确封，連接操作將以 §2.2.1 中提到的規(guī)則把其轉(zhuǎn)換為字符串。 否則，會取調(diào)用元方法 "concat" （參見 §2.8）爪喘。
2.5.5 -取長度操作符
取長度操作符寫作一元操作#颜曾。字符串的長度是它的字節(jié)數(shù)（就是以一個字符一個字節(jié)計算的字符串長度）。
table t 的長度被定義成一個整數(shù)下標 n 腥放。 它滿足 t[n] 不是 nil 而 t[n+1] 為 nil泛啸；此外绿语，如果t[1] 為 nil 秃症，n 就可能是零。 對于常規(guī)的數(shù)組吕粹，里面從 1 到 n 放著一些非空的值的時候种柑， 它的長度就精確的為 n，即最后一個值的下標匹耕。如果數(shù)組有一個“空洞” （就是說聚请，nil 值被夾在非空值之間）， 那么 #t 可能是指向任何一個是 nil 值的前一個位置的下標 （就是說，任何一個 nil 值都有可能被當成數(shù)組的結(jié)束）。
2.5.6 -優(yōu)先級
Lua 中操作符的優(yōu)先級寫在下表中煤惩，從低到高優(yōu)先級排序：
? ? or
? ? and
? ? <? ? >? ? <=? ? >=? ? ~=? ? ==
? ? ..
? ? +? ? -
? ? *? ? /? ? %
? ? not? #? ? - (unary)
? ? ^
通常察藐，你可以用括號來改變運算次序。連接操作符('..') 和冪操作 ('^') 是從右至左的区丑。 其它所有的操作都是從左至右。
2.5.7 -Table 構(gòu)造
table 構(gòu)造子是一個構(gòu)造 table 的表達式。 每次構(gòu)造子被執(zhí)行蚯姆，都會構(gòu)造出一個新的 table 。 構(gòu)造子可以被用來構(gòu)造一個空的 table洒敏， 也可以用來構(gòu)造一個 table 并初始化其中的一些域龄恋。 一般的構(gòu)造子的語法如下
tableconstructor ::= `{′ [fieldlist] `}′
fieldlist ::= field {fieldsep field} [fieldsep]
field ::= `[′ exp `]′ `=′ exp | Name `=′ exp | exp
fieldsep ::= `,′ | `;′
每個形如[exp1] = exp2 的域向 table 中增加新的一項， 其鍵值為 exp1 而值為 exp2凶伙。形如name = exp 的域等價于 ["name"] = exp郭毕。最后，形如exp 的域等價于 [i] = exp 函荣， 這里的 i 是一個從 1 開始不斷增長的數(shù)字铣卡。 這這個格式中的其它域不會破壞其記數(shù)。 舉個例子：
? ? a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 }
等價于
? ? do
? ? ? local t = {}
? ? ? t[f(1)] = g
? ? ? t[1] = "x"? ? ? ? -- 1st exp
? ? ? t[2] = "y"? ? ? ? -- 2nd exp
? ? ? t.x = 1? ? ? ? ? ? -- t["x"] = 1
? ? ? t[3] = f(x)? ? ? ? -- 3rd exp
? ? ? t[30] = 23
? ? ? t[4] = 45? ? ? ? ? -- 4th exp
? ? ? a = t
? ? end
如果表單中最后一個域的形式是exp 偏竟， 而且其表達式是一個函數(shù)調(diào)用或者是一個可變參數(shù)煮落， 那么這個表達式所有的返回值將連續(xù)的進入列表 （參見 §2.5.8）。為了避免這一點踊谋，你可以用括號把函數(shù)調(diào)用（或是可變參數(shù)）括起來（參見§2.5）蝉仇。
初始化域表可以在最后多一個分割符，這樣設計可以方便由機器生成代碼。
2.5.8 -函數(shù)調(diào)用
Lua 中的函數(shù)調(diào)用的語法如下：
functioncall ::= prefixexp args
函數(shù)調(diào)用時轿衔，第一步沉迹，prefixexp 和 args 先被求值。 如果 prefixexp 的值的類型是function害驹，那么這個函數(shù)就被用給出的參數(shù)調(diào)用鞭呕。否則prefixexp 的元方法 "call" 就被調(diào)用， 第一個參數(shù)就是 prefixexp 的值宛官，跟下來的是原來的調(diào)用參數(shù) （參見§2.8）葫松。
這樣的形式
functioncall ::= prefixexp `:′ Name args
可以用來調(diào)用"方法"。 這是 Lua 支持的一種語法糖底洗。像v:name(args) 這個樣子腋么，被解釋成 v.name(v,args)，這里v 只會被求值一次亥揖。
參數(shù)的語法如下：
args ::= `(′ [explist1] `)′
args ::= tableconstructor
args ::= String
所有參數(shù)的表達式求值都在函數(shù)調(diào)用之前珊擂。這樣的調(diào)用形式f{fields} 是一種語法糖用于表示 f({fields})；這里指參數(shù)列表是一個單一的新創(chuàng)建出來的列表费变。而這樣的形式f'string' （或是 f"string" 亦或是 f[[string]]）也是一種語法糖摧扇，用于表示f('string')；這里指參數(shù)列表是一個單獨的字符串挚歧。
因為表達式語法在Lua 中比較自由扛稽， 所以你不能在函數(shù)調(diào)用的 '(' 前換行。 這個限制可以避免語言中的一些歧義昼激。 比如你這樣寫
? ? a = f
? ? (g).x(a)
Lua 將把它當作一個單一語句段庇绽， a = f(g).x(a) 。 因此橙困，如果你真的想作為成兩個語句段瞧掺，你必須在它們之間寫上一個分號。 如果你真的想調(diào)用 f凡傅，你必須從(g) 前移去換行辟狈。
這樣一種調(diào)用形式：return functioncall 將觸發(fā)一個尾調(diào)用。 Lua 實現(xiàn)了適當?shù)奈膊空{(diào)用（或是適當?shù)奈策f歸）： 在尾調(diào)用中夏跷， 被調(diào)用的函數(shù)重用調(diào)用它的函數(shù)的堆棧項哼转。 因此，對于程序執(zhí)行的嵌套尾調(diào)用的層數(shù)是沒有限制的槽华。 然而壹蔓，尾調(diào)用將刪除調(diào)用它的函數(shù)的任何調(diào)試信息。 注意猫态，尾調(diào)用只發(fā)生在特定的語法下佣蓉， 這時披摄， return 只有單一函數(shù)調(diào)用作為參數(shù)； 這種語法使得調(diào)用函數(shù)的結(jié)果可以精確返回勇凭。 因此疚膊，下面這些例子都不是尾調(diào)用：
? ? return (f(x))? ? ? ? -- 返回值被調(diào)整為一個
? ? return 2 * f(x)
? ? return x, f(x)? ? ? -- 最加若干返回值
? ? f(x); return? ? ? ? -- 無返回值
? ? return x or f(x)? ? -- 返回值被調(diào)整為一個
2.5.9 -函數(shù)定義
函數(shù)定義的語法如下：
function ::= function funcbody
funcbody ::= `(′ [parlist1] `)′ block end
另外定義了一些語法糖簡化函數(shù)定義的寫法：
stat ::= function funcname funcbody
stat ::= local function Name funcbody
funcname ::= Name {`.′ Name} [`:′ Name]
這樣的寫法：
? ? function f () body end
被轉(zhuǎn)換成
? ? f = function () body end
這樣的寫法：
? ? function t.a.b.c.f () body end
被轉(zhuǎn)換成
? ? t.a.b.c.f = function () body end
這樣的寫法：
? ? local function f () body end
被轉(zhuǎn)換成
? ? local f; f = function () body end
注意，并不是轉(zhuǎn)換成
? ? local f = function () body end
（這個差別只在函數(shù)體內(nèi)需要引用f 時才有虾标。）
一個函數(shù)定義是一個可執(zhí)行的表達式寓盗，執(zhí)行結(jié)果是一個類型為function 的值。 當 Lua 預編譯一個 chunk 的時候璧函， chunk 作為一個函數(shù)傀蚌，整個函數(shù)體也就被預編譯了。 那么柳譬，無論何時 Lua 執(zhí)行了函數(shù)定義喳张， 這個函數(shù)本身就被實例化了（或者說是關閉了）续镇。 這個函數(shù)的實例（或者說是 closure（閉包））是表達式的最終值美澳。相同函數(shù)的不同實例有可能引用不同的外部局部變量，也可能擁有不同的環(huán)境表摸航。
形參（函數(shù)定義需要的參數(shù)）是一些由實參（實際傳入?yún)?shù)）的值初始化的局部變量：
parlist1 ::= namelist [`,′ `...′] | `...′
當一個函數(shù)被調(diào)用制跟，如果函數(shù)沒有被定義為接收不定長參數(shù)，即在形參列表的末尾注明三個點('...')酱虎， 那么實參列表就會被調(diào)整到形參列表的長度雨膨， 變長參數(shù)函數(shù)不會調(diào)整實參列表； 取而代之的是读串，它將把所有額外的參數(shù)放在一起通過變長參數(shù)表達式傳遞給函數(shù)聊记， 其寫法依舊是三個點。 這個表達式的值是一串實參值的列表恢暖，看起來就跟一個可以返回多個結(jié)果的函數(shù)一樣排监。 如果一個變長參數(shù)表達式放在另一個表達式中使用，或是放在另一串表達式的中間杰捂， 那么它的返回值就會被調(diào)整為單個值舆床。 若這個表達式放在了一系列表達式的最后一個，就不會做調(diào)整了（除非用括號給括了起來）嫁佳。
我們先做如下定義挨队，然后再來看一個例子：
? ? function f(a, b) end
? ? function g(a, b, ...) end
? ? function r() return 1,2,3 end
下面看看實參到形參數(shù)以及可變長參數(shù)的映射關系：
? ? CALL? ? ? ? ? ? PARAMETERS
? ? f(3)? ? ? ? ? ? a=3, b=nil
? ? f(3, 4)? ? ? ? ? a=3, b=4
? ? f(3, 4, 5)? ? ? a=3, b=4
? ? f(r(), 10)? ? ? a=1, b=10
? ? f(r())? ? ? ? ? a=1, b=2
? ? g(3)? ? ? ? ? ? a=3, b=nil, ... -->? (nothing)
? ? g(3, 4)? ? ? ? ? a=3, b=4,? ... -->? (nothing)
? ? g(3, 4, 5, 8)? ? a=3, b=4,? ... -->? 5? 8
? ? g(5, r())? ? ? ? a=5, b=1,? ... -->? 2? 3
結(jié)果由return 來返回（參見 §2.4.4）。如果執(zhí)行到函數(shù)末尾依舊沒有遇到任何return 語句蒿往， 函數(shù)就不會返回任何結(jié)果盛垦。
冒號語法可以用來定義方法，就是說瓤漏，函數(shù)可以有一個隱式的形參self腾夯。因此省撑，如下寫法：
? ? function t.a.b.c:f (params) body end
是這樣一種寫法的語法糖：
? ? t.a.b.c.f = function (self, params) body end
2.6 -可視規(guī)則
Lua 是一個有詞法作用范圍的語言。 變量的作用范圍開始于聲明它們之后的第一個語句段俯在， 結(jié)束于包含這個聲明的最內(nèi)層語句塊的結(jié)束點竟秫。 看下面這些例子：
? ? x = 10? ? ? ? ? ? ? ? -- 全局變量
? ? do? ? ? ? ? ? ? ? ? ? -- 新的語句塊
? ? ? local x = x? ? ? ? -- 新的一個 'x', 它的值現(xiàn)在是 10
? ? ? print(x)? ? ? ? ? ? --> 10
? ? ? x = x+1
? ? ? do? ? ? ? ? ? ? ? ? -- 另一個語句塊
? ? ? ? local x = x+1? ? -- 又一個 'x'
? ? ? ? print(x)? ? ? ? ? --> 12
? ? ? end
? ? ? print(x)? ? ? ? ? ? --> 11
? ? end
? ? print(x)? ? ? ? ? ? ? --> 10? （取到的是全局的那一個）
注意這里，類似local x = x 這樣的聲明跷乐， 新的 x 正在被聲明肥败，但是還沒有進入它的作用范圍， 所以第二個 x 指向的是外面一層的變量愕提。
因為有這樣一個詞法作用范圍的規(guī)則馒稍，所以可以在函數(shù)內(nèi)部自由的定義局部變量并使用它們。當一個局部變量被更內(nèi)層的函數(shù)中使用的時候浅侨，它被內(nèi)層函數(shù)稱作upvalue（上值）纽谒，或是外部局部變量。
注意如输，每次執(zhí)行到一個local 語句都會定義出一個新的局部變量鼓黔。 看看這樣一個例子：
? ? a = {}
? ? local x = 20
? ? for i=1,10 do
? ? ? local y = 0
? ? ? a[i] = function () y=y+1; return x+y end
? ? end
這個循環(huán)創(chuàng)建了十個closure（這指十個匿名函數(shù)的實例）。 這些 closure 中的每一個都使用了不同的y 變量， 而它們又共享了同一份 x。
2.7 -錯誤處理
因為Lua 是一個嵌入式的擴展語言召边， 所有的 Lua 動作都是從宿主程序的 C 代碼調(diào)用 Lua 庫 （參見lua_pcall）中的一個函數(shù)開始的。在Lua 編譯或運行的任何時候發(fā)生了錯誤缎谷，控制權(quán)都會交還給 C ， 而 C 可以來做一些恰當?shù)拇胧ū热绱蛴〕鲆粭l錯誤信息）灶似。
Lua 代碼可以顯式的調(diào)用 error 函數(shù)來產(chǎn)生一條錯誤列林。 如果你需要在 Lua 中捕獲發(fā)生的錯誤， 你可以使用 pcall 函數(shù)酪惭。
2.8 -Metatable（元表）
Lua 中的每個值都可以用一個 metatable希痴。這個metatable 就是一個原始的 Lua table ， 它用來定義原始值在特定操作下的行為撞蚕。 你可以通過在 metatable 中的特定域設一些值來改變擁有這個 metatable 的值 的指定操作之行為润梯。 舉例來說，當一個非數(shù)字的值作加法操作的時候甥厦， Lua 會檢查它的 metatable 中 "__add" 域中的是否有一個函數(shù)纺铭。 如果有這么一個函數(shù)的話，Lua 調(diào)用這個函數(shù)來執(zhí)行一次加法刀疙。
我們叫metatable 中的鍵名為事件(event) 舶赔，把其中的值叫作 元方法(metamethod)。在上個例子中谦秧，事件是"add" 而元方法就是那個執(zhí)行加法操作的函數(shù)竟纳。
你可以通過getmetatable 函數(shù)來查詢到任何一個值的 metatable撵溃。
你可以通過setmetatable 函數(shù)來替換掉 table 的 metatable 。 你不能從 Lua 中改變其它任何類型的值的 metatable （使用 debug 庫例外）锥累； 要這樣做的話必須使用 C API 缘挑。
每個table 和 userdata 擁有獨立的 metatable （當然多個 table 和 userdata 可以共享一個相同的表作它們的 metatable）； 其它所有類型的值桶略，每種類型都分別共享唯一的一個 metatable语淘。 因此，所有的數(shù)字一起只有一個 metatable 际歼，所有的字符串也是惶翻，等等。
一個metatable 可以控制一個對象做數(shù)學運算操作鹅心、比較操作吕粗、連接操作、取長度操作旭愧、取下標操作時的行為颅筋， metatable 中還可以定義一個函數(shù)，讓 userdata 作垃圾收集時調(diào)用它榕茧。 對于這些操作垃沦，Lua 都將其關聯(lián)上一個被稱作事件的指定健客给。 當 Lua 需要對一個值發(fā)起這些操作中的一個時用押， 它會去檢查值中 metatable 中是否有對應事件。 如果有的話靶剑，鍵名對應的值（元方法）將控制 Lua 怎樣做這個操作蜻拨。
metatable 可以控制的操作已在下面列出來。 每個操作都用相應的名字區(qū)分桩引。 每個操作的鍵名都是用操作名字加上兩個下劃線 '__' 前綴的字符串缎讼； 舉例來說，"add" 操作的鍵名就是字符串 "__add"坑匠。這些操作的語義用一個Lua 函數(shù)來描述解釋器如何執(zhí)行更為恰當血崭。
這里展示的用Lua 寫的代碼僅作解說用； 實際的行為已經(jīng)硬編碼在解釋器中厘灼，其執(zhí)行效率要遠高于這些模擬代碼夹纫。 這些用于描述的的代碼中用到的函數(shù) （rawget ， tonumber 设凹，等等舰讹。） 都可以在 §5.1 中找到。 特別注意闪朱，我們使用這樣一個表達式來從給定對象中提取元方法
? ? metatable(obj)[event]
這個應該被解讀作
? ? rawget(getmetatable(obj) or {}, event)
這就是說月匣，訪問一個元方法不再會觸發(fā)任何的元方法钻洒，而且訪問一個沒有metatable 的對象也不會失敗（而只是簡單返回nil）锄开。
[if !supportLists]· [endif]"add": + 操作素标。
下面這個getbinhandler 函數(shù)定義了 Lua 怎樣選擇一個處理器來作二元操作。 首先萍悴，Lua 嘗試第一個操作數(shù)糯钙。 如果這個東西的類型沒有定義這個操作的處理器，然后 Lua 會嘗試第二個操作數(shù)退腥。
[if !supportLists]· [endif]
? ? function getbinhandler (op1, op2, event)
? ? ? return metatable(op1)[event] or metatable(op2)[event]
? ? end
[if !supportLists]· [endif]
通過這個函數(shù)任岸，op1 + op2 的行為就是
[if !supportLists]· [endif]
? ? function add_event (op1, op2)
? ? ? local o1, o2 = tonumber(op1), tonumber(op2)
? ? ? if o1 and o2 then? -- 兩個操作數(shù)都是數(shù)字？
? ? ? ? return o1 + o2? -- 這里的 '+' 是原生的 'add'
? ? ? else? -- 至少一個操作數(shù)不是數(shù)字時
? ? ? ? local h = getbinhandler(op1, op2, "__add")
? ? ? ? if h then
? ? ? ? ? -- 以兩個操作數(shù)來調(diào)用處理器
? ? ? ? ? return h(op1, op2)
? ? ? ? else? -- 沒有處理器：缺省行為
? ? ? ? ? error(···)
? ? ? ? end
? ? ? end
? ? end
[if !supportLists]· [endif]
[if !supportLists]· [endif]
[if !supportLists]· [endif]"sub": - 操作狡刘。 其行為類似于 "add" 操作享潜。
[if !supportLists]· [endif]"mul": * 操作。 其行為類似于 "add" 操作嗅蔬。
[if !supportLists]· [endif]"div": / 操作剑按。 其行為類似于 "add" 操作。
[if !supportLists]· [endif]"mod": % 操作澜术。 其行為類似于 "add" 操作艺蝴， 它的原生操作是這樣的 o1 - floor(o1/o2)*o2
[if !supportLists]· [endif]"pow": ^ （冪）操作。 其行為類似于 "add" 操作鸟废， 它的原生操作是調(diào)用 pow 函數(shù)（通過 C math 庫）猜敢。
[if !supportLists]· [endif]"unm": 一元 - 操作。
? ? function unm_event (op)
? ? ? local o = tonumber(op)
? ? ? if o then? -- 操作數(shù)是數(shù)字盒延？
? ? ? ? return -o? -- 這里的 '-' 是一個原生的 'unm'
? ? ? else? -- 操作數(shù)不是數(shù)字缩擂。
? ? ? ? -- 嘗試從操作數(shù)中得到處理器
? ? ? ? local h = metatable(op).__unm
? ? ? ? if h then
? ? ? ? ? -- 以操作數(shù)為參數(shù)調(diào)用處理器
? ? ? ? ? return h(op)
? ? ? ? else? -- 沒有處理器：缺省行為
? ? ? ? ? error(···)
? ? ? ? end
? ? ? end
? ? end
[if !supportLists]· [endif]
[if !supportLists]· [endif]
[if !supportLists]· [endif]"concat": .. （連接）操作，
? ? function concat_event (op1, op2)
? ? ? if (type(op1) == "string" or type(op1) == "number") and
? ? ? ? ? (type(op2) == "string" or type(op2) == "number") then
? ? ? ? return op1 .. op2? -- 原生字符串連接
? ? ? else
? ? ? ? local h = getbinhandler(op1, op2, "__concat")
? ? ? ? if h then
? ? ? ? ? return h(op1, op2)
? ? ? ? else
? ? ? ? ? error(···)
? ? ? ? end
? ? ? end
? ? end
[if !supportLists]· [endif]
[if !supportLists]· [endif]
[if !supportLists]· [endif]"len": # 操作添寺。
? ? function len_event (op)
? ? ? if type(op) == "string" then
? ? ? ? return strlen(op)? ? ? ? -- 原生的取字符串長度
? ? ? elseif type(op) == "table" then
? ? ? ? return #op? ? ? ? ? ? ? ? -- 原生的取 table 長度
? ? ? else
? ? ? ? local h = metatable(op).__len
? ? ? ? if h then
? ? ? ? ? -- 調(diào)用操作數(shù)的處理器
? ? ? ? ? return h(op)
? ? ? ? else? -- 沒有處理器：缺省行為
? ? ? ? ? error(···)
? ? ? ? end
? ? ? end
? ? end
[if !supportLists]· [endif]
關于table 的長度參見§2.5.5 胯盯。
[if !supportLists]· [endif]
[if !supportLists]· [endif]"eq": == 操作。 函數(shù) getcomphandler 定義了 Lua 怎樣選擇一個處理器來作比較操作计露。 元方法僅僅在參于比較的兩個對象類型相同且有對應操作相同的元方法時才起效博脑。
? ? function getcomphandler (op1, op2, event)
? ? ? if type(op1) ~= type(op2) then return nil end
? ? ? local mm1 = metatable(op1)[event]
? ? ? local mm2 = metatable(op2)[event]
? ? ? if mm1 == mm2 then return mm1 else return nil end
? ? end
[if !supportLists]· [endif]
"eq" 事件按如下方式定義：
[if !supportLists]· [endif]
? ? function eq_event (op1, op2)
? ? ? if type(op1) ~= type(op2) then? -- 不同的類型？
? ? ? ? return false? -- 不同的對象
? ? ? end
? ? ? if op1 == op2 then? -- 原生的相等比較結(jié)果票罐？
? ? ? ? return true? -- 對象相等
? ? ? end
? ? ? -- 嘗試使用元方法
? ? ? local h = getcomphandler(op1, op2, "__eq")
? ? ? if h then
? ? ? ? return h(op1, op2)
? ? ? else
? ? ? ? return false
? ? ? end
? ? end
[if !supportLists]· [endif]
a ~= b 等價于 not (a == b) 叉趣。
[if !supportLists]· [endif]
[if !supportLists]· [endif]"lt": < 操作。
? ? function lt_event (op1, op2)
? ? ? if type(op1) == "number" and type(op2) == "number" then
? ? ? ? return op1 < op2? -- 數(shù)字比較
? ? ? elseif type(op1) == "string" and type(op2) == "string" then
? ? ? ? return op1 < op2? -- 字符串按逐字符比較
? ? ? else
? ? ? ? local h = getcomphandler(op1, op2, "__lt")
? ? ? ? if h then
? ? ? ? ? return h(op1, op2)
? ? ? ? else
? ? ? ? ? error(···);
? ? ? ? end
? ? ? end
? ? end
[if !supportLists]· [endif]
a > b 等價于 b < a.
[if !supportLists]· [endif]
[if !supportLists]· [endif]"le": <= 操作胶坠。
? ? function le_event (op1, op2)
? ? ? if type(op1) == "number" and type(op2) == "number" then
? ? ? ? return op1 <= op2? -- 數(shù)字比較
? ? ? elseif type(op1) == "string" and type(op2) == "string" then
? ? ? ? return op1 <= op2? -- 字符串按逐字符比較
? ? ? else
? ? ? ? local h = getcomphandler(op1, op2, "__le")
? ? ? ? if h then
? ? ? ? ? return h(op1, op2)
? ? ? ? else
? ? ? ? ? h = getcomphandler(op1, op2, "__lt")
? ? ? ? ? if h then
? ? ? ? ? ? return not h(op2, op1)
? ? ? ? ? else
? ? ? ? ? ? error(···);
? ? ? ? ? end
? ? ? ? end
? ? ? end
? ? end
[if !supportLists]· [endif]
a >= b 等價于 b <= a 君账。 注意，如果元方法 "le" 沒有提供沈善，Lua 就嘗試 "lt" 乡数， 它假定 a <= b 等價于 not (b < a) 椭蹄。
[if !supportLists]· [endif]
[if !supportLists]· [endif]"index": 取下標操作用于訪問 table[key] 。
? ? function gettable_event (table, key)
? ? ? local h
? ? ? if type(table) == "table" then
? ? ? ? local v = rawget(table, key)
? ? ? ? if v ~= nil then return v end
? ? ? ? h = metatable(table).__index
? ? ? ? if h == nil then return nil end
? ? ? else
? ? ? ? h = metatable(table).__index
? ? ? ? if h == nil then
? ? ? ? ? error(···);
? ? ? ? end
? ? ? end
? ? ? if type(h) == "function" then
? ? ? ? return h(table, key)? ? ? -- 調(diào)用處理器
? ? ? else return h[key]? ? ? ? ? -- 或是重復上述操作
? ? ? end
? ? end
[if !supportLists]· [endif]
[if !supportLists]· [endif]
[if !supportLists]· [endif]"newindex": 賦值給指定下標 table[key] = value 净赴。
? ? function settable_event (table, key, value)
? ? ? local h
? ? ? if type(table) == "table" then
? ? ? ? local v = rawget(table, key)
? ? ? ? if v ~= nil then rawset(table, key, value); return end
? ? ? ? h = metatable(table).__newindex
? ? ? ? if h == nil then rawset(table, key, value); return end
? ? ? else
? ? ? ? h = metatable(table).__newindex
? ? ? ? if h == nil then
? ? ? ? ? error(···);
? ? ? ? end
? ? ? end
? ? ? if type(h) == "function" then
? ? ? ? return h(table, key,value)? ? -- 調(diào)用處理器
? ? ? else h[key] = value? ? ? ? ? ? -- 或是重復上述操作
? ? ? end
? ? end
[if !supportLists]· [endif]
[if !supportLists]· [endif]
[if !supportLists]· [endif]"call": 當 Lua 調(diào)用一個值時調(diào)用绳矩。
? ? function function_event (func, ...)
? ? ? if type(func) == "function" then
? ? ? ? return func(...)? -- 原生的調(diào)用
? ? ? else
? ? ? ? local h = metatable(func).__call
? ? ? ? if h then
? ? ? ? ? return h(func, ...)
? ? ? ? else
? ? ? ? ? error(···)
? ? ? ? end
? ? ? end
? ? end
[if !supportLists]· [endif]
[if !supportLists]· [endif]
2.9 -環(huán)境
類型為thread ，function 玖翅，以及 userdata 的對象翼馆，除了 metatable 外還可以用另外一個與之關聯(lián)的被稱作 它們的環(huán)境的一個表， 像 metatable 一樣金度，環(huán)境也是一個常規(guī)的 table 应媚，多個對象可以共享 同一個環(huán)境。
userdata 的環(huán)境在 Lua 中沒有意義猜极。 這個東西只是為了在程序員想把一個表關聯(lián)到一個 userdata 上時提供便利中姜。
關聯(lián)在線程上的環(huán)境被稱作全局環(huán)境。全局環(huán)境被用作它其中的線程以及線程創(chuàng)建的非嵌套函數(shù)（通過loadfile 跟伏， loadstring 或是 load ）的缺省環(huán)境丢胚。 而且它可以被 C 代碼直接訪問（參見 §3.3）。
關聯(lián)在C 函數(shù)上的環(huán)境可以直接被 C 代碼訪問（參見§3.3）受扳。它們會作為這個C 函數(shù)中創(chuàng)建的其它函數(shù)的缺省環(huán)境携龟。
關聯(lián)在Lua 函數(shù)上的環(huán)境用來接管在函數(shù)內(nèi)對全局變量（參見§2.3）的所有訪問氏义。它們也會作為這個函數(shù)內(nèi)創(chuàng)建的其它函數(shù)的缺省環(huán)境虚青。
你可以通過調(diào)用setfenv 來改變一個 Lua 函數(shù) 或是正在運行中的線程的環(huán)境。 而想操控其它對象（userdata钧汹、C 函數(shù)相满、其它線程）的環(huán)境的話层亿，就必須使用 C API 。
2.10 -垃圾收集
Lua 提供了一個自動的內(nèi)存管理立美。 這就是說你不需要關心創(chuàng)建新對象的分配內(nèi)存操作，也不需要在這些對象不再需要時的主動釋放內(nèi)存方灾。 Lua 通過運行一個垃圾收集器來自動管理內(nèi)存建蹄，以此一遍又一遍的回收死掉的對象 （這是指 Lua 中不再訪問的到的對象）占用的內(nèi)存。 Lua 中所有對象都被自動管理裕偿，包括： table, userdata洞慎、 函數(shù)、線程嘿棘、和字符串劲腿。
Lua 實現(xiàn)了一個增量標記清除的收集器。 它用兩個數(shù)字來控制垃圾收集周期： garbage-collector pause 和 garbage-collector step multiplier 鸟妙。
garbage-collector pause 控制了收集器在開始一個新的收集周期之前要等待多久焦人。 隨著數(shù)字的增大就導致收集器工作工作的不那么主動挥吵。 小于 1 的值意味著收集器在新的周期開始時不再等待。 當值為 2 的時候意味著在總使用內(nèi)存數(shù)量達到原來的兩倍時再開啟新的周期花椭。
step multiplier 控制了收集器相對內(nèi)存分配的速度忽匈。 更大的數(shù)字將導致收集器工作的更主動的同時，也使每步收集的尺寸增加矿辽。 小于 1 的值會使收集器工作的非常慢丹允，可能導致收集器永遠都結(jié)束不了當前周期。 缺省值為 2 袋倔，這意味著收集器將以內(nèi)存分配器的兩倍速運行雕蔽。
你可以通過在C 中調(diào)用lua_gc 或是在 Lua 中調(diào)用 collectgarbage 來改變這些數(shù)字。 兩者都接受百分比數(shù)值（因此傳入?yún)?shù) 100 意味著實際值 1 ）宾娜。 通過這些函數(shù)萎羔，你也可以直接控制收集器（例如，停止或是重啟）碳默。
2.10.1 -垃圾收集的元方法
使用C API 贾陷， 你可以給 userdata （參見§2.8）設置一個垃圾收集的元方法。這個元方法也被稱為結(jié)束子嘱根。結(jié)束子允許你用額外的資源管理器和Lua 的內(nèi)存管理器協(xié)同工作 （比如關閉文件髓废、網(wǎng)絡連接、或是數(shù)據(jù)庫連接该抒，也可以說釋放你自己的內(nèi)存）慌洪。
一個userdata 可被回收，若它的 metatable 中有__gc 這個域 凑保， 垃圾收集器就不立即收回它冈爹。 取而代之的是，Lua 把它們放到一個列表中欧引。 最收集結(jié)束后频伤，Lua 針對列表中的每個 userdata 執(zhí)行了下面這個函數(shù)的等價操作：
? ? function gc_event (udata)
? ? ? local h = metatable(udata).__gc
? ? ? if h then
? ? ? ? h(udata)
? ? ? end
? ? end
在每個垃圾收集周期的結(jié)尾，每個在當前周期被收集起來的userdata 的結(jié)束子會以 它們構(gòu)造時的逆序依次調(diào)用芝此。 也就是說憋肖，收集列表中，最后一個在程序中被創(chuàng)建的 userdata 的 結(jié)束子會被第一個調(diào)用婚苹。
2.10.2 -Weak Table（弱表）
weak table 是一個這樣的 table岸更，它其中的元素都被弱引用。 弱引用將被垃圾收集器忽略掉膊升， 換句話說怎炊， 如果對一個對象的引用只有弱引用， 垃圾收集器將回收這個對象。
weak table 的鍵和值都可以是 weak 的评肆。 如果一個 table 只有鍵是 weak 的债查，那么將運行收集器回收它們的鍵， 但是會阻止回收器回收對應的值糟港。 而一個 table 的鍵和值都是 weak 時攀操，就即允許收集器回收鍵又允許收回值。 任何情況下秸抚，如果鍵和值中任一個被回收了速和，整個鍵值對就會從 table 中拿掉。 table 的 weak 特性可以通過在它的 metatable 中設置 __mode 域來改變剥汤。 如果 __mode 域中是一個包含有字符 'k' 的字符串時颠放， table 的鍵就是 weak 的。 如果 __mode 域中是一個包含有字符 'v' 的字符串時吭敢， table 的值就是 weak 的碰凶。
在你把一個table 當作一個 metatable 使用之后， 就不能再修改__mode 域的值鹿驼。 否則欲低，受這個 metatable 控制的 table 的 weak 行為就成了未定義的。
2.11 -Coroutine （協(xié)同例程）
Lua 支持 coroutine 畜晰，這個東西也被稱為協(xié)同式多線程 (collaborative multithreading) 砾莱。 Lua 為每個 coroutine 提供一個獨立的運行線路。 然而和多線程系統(tǒng)中的線程不同凄鼻，coroutine 只在顯式的調(diào)用了 yield 函數(shù)時才會掛起腊瑟。
創(chuàng)建一個coroutine 需要調(diào)用一次coroutine.create 。 它只接收單個參數(shù)块蚌，這個參數(shù)是 coroutine 的主函數(shù)闰非。 create 函數(shù)僅僅創(chuàng)建一個新的 coroutine 然后返回它的控制器 （一個類型為 thread 的對象）； 它并不會啟動 coroutine 的運行峭范。
當你第一次調(diào)用coroutine.resume 時财松， 所需傳入的第一個參數(shù)就是 coroutine.create 的返回值。 這時虎敦，coroutine 從主函數(shù)的第一行開始運行游岳。 接下來傳入 coroutine.resume 的參數(shù)將被傳進 coroutine 的主函數(shù)。 在 coroutine 開始運行后其徙，它講運行到自身終止或是遇到一個 yields 。
coroutine 可以通過兩種方式來終止運行： 一種是正常退出喷户，指它的主函數(shù)返回（最后一條指令被運行后唾那，無論有沒有顯式的返回指令）; 另一種是非正常退出，它發(fā)生在未保護的錯誤發(fā)生的時候。 第一種情況中闹获， coroutine.resume 返回 true 期犬， 接下來會跟著 coroutine 主函數(shù)的一系列返回值。 第二種發(fā)生錯誤的情況下避诽， coroutine.resume 返回 false 龟虎， 緊接著是一條錯誤信息。
coroutine 中切換出去沙庐，可以調(diào)用 coroutine.yield鲤妥。當coroutine 切出，與之配合的coroutine.resume 就立即返回拱雏， 甚至在 yield 發(fā)生在內(nèi)層的函數(shù)調(diào)用中也可以（就是說棉安， 這不限于發(fā)生在主函數(shù)中，也可以是主函數(shù)直接或間接調(diào)用的某個函數(shù)里）铸抑。 在 yield 的情況下贡耽，coroutine.resume 也是返回 true，緊跟著那些被傳入coroutine.yield 的參數(shù)鹊汛。 等到下次你在繼續(xù)同樣的 coroutine 蒲赂，將從調(diào)用 yield 的斷點處運行下去。 斷點處 yield 的返回值將是 coroutine.resume 傳入的參數(shù)刁憋。
類似coroutine.create 滥嘴， coroutine.wrap 這個函數(shù)也將創(chuàng)建一個 coroutine ， 但是它并不返回 coroutine 本身职祷，而是返回一個函數(shù)取而代之氏涩。一旦你調(diào)用這個返回函數(shù)，就會切入 coroutine 運行有梆。 所有傳入這個函數(shù)的參數(shù)等同于傳入 coroutine.resume 的參數(shù)是尖。coroutine.wrap 會返回所有應該由除第一個（錯誤代碼的那個布爾量） 之外的由 coroutine.resume 返回的值胚吁。 和 coroutine.resume 不同旁壮， coroutine.wrap 不捕獲任何錯誤谱姓； 所有的錯誤都應該由調(diào)用者自己傳遞捶惜。
看下面這段代碼展示的一個例子：
? ? function foo (a)
? ? ? print("foo", a)
? ? ? return coroutine.yield(2*a)
? ? end
? ? co = coroutine.create(function (a,b)
? ? ? ? ? print("co-body", a, b)
? ? ? ? ? local r = foo(a+1)
? ? ? ? ? print("co-body", r)
? ? ? ? ? local r, s = coroutine.yield(a+b, a-b)
? ? ? ? ? print("co-body", r, s)
? ? ? ? ? return b, "end"
? ? end)
? ? print("main", coroutine.resume(co, 1, 10))
? ? print("main", coroutine.resume(co, "r"))
? ? print("main", coroutine.resume(co, "x", "y"))
? ? print("main", coroutine.resume(co, "x", "y"))
當你運行它宋梧，將得到如下輸出結(jié)果：
? ? co-body 1? ? ? 10
? ? foo? ? 2
? ? main? ? true? ? 4
? ? co-body r
? ? main? ? true? ? 11? ? ? -9
? ? co-body x? ? ? y
? ? main? ? true? ? 10? ? ? end
? ? main? ? false? cannot resume dead coroutine
3 -程序接口（API）
這個部分描述了Lua 的 C API 召嘶， 也就是宿主程序跟 Lua 通訊用的一組 C 函數(shù)蜻懦。 所有的 API 函數(shù)按相關的類型以及常量都聲明在頭文件lua.h 中间螟。
雖然我們說的是“函數(shù)”夸溶，但一部分簡單的 API 是以宏的形式提供的逸吵。 所有的這些宏都只使用它們的參數(shù)一次 （除了第一個參數(shù)，也就是 lua 狀態(tài)機）缝裁， 因此你不需擔心這些宏的展開會引起一些副作用扫皱。
在所有的C 庫中，Lua API 函數(shù)都不去檢查參數(shù)的有效性和堅固性。 然而韩脑，你可以在編譯 Lua 時加上打開一個宏開關來 開啟luaconf.h文件中的宏luai_apicheck 以改變這個行為氢妈。
3.1 -堆棧
Lua 使用一個虛擬棧來和 C 傳遞值。 棧上的的每個元素都是一個 Lua 值 （nil段多，數(shù)字首量，字符串，等等）进苍。
無論何時Lua 調(diào)用 C加缘，被調(diào)用的函數(shù)都得到一個新的棧， 這個棧獨立于 C 函數(shù)本身的堆棧琅捏，也獨立于以前的棧生百。 （譯注：在 C 函數(shù)里，用 Lua API 不能訪問到 Lua 狀態(tài)機中本次調(diào)用之外的堆棧中的數(shù)據(jù)） 它里面包含了 Lua 傳遞給 C 函數(shù)的所有參數(shù)柄延， 而 C 函數(shù)則把要返回的結(jié)果也放入堆棧以返回給調(diào)用者 （參見lua_CFunction）蚀浆。
方便起見，所有針對棧的API 查詢操作都不嚴格遵循棧的操作規(guī)則搜吧。 而是可以用一個索引來指向棧上的任何元素： 正的索引指的是棧上的絕對位置（從一開始）市俊； 負的索引則指從棧頂開始的偏移量。 更詳細的說明一下滤奈，如果堆棧有 n 個元素摆昧， 那么索引 1 表示第一個元素（也就是最先被壓入堆棧的元素） 而索引 n 則指最后一個元素； 索引 -1 也是指最后一個元素（即棧頂?shù)脑兀?索引 -n 是指第一個元素蜒程。 如果索引在 1 到棧頂之間（也就是绅你，1 ≤ abs(index) ≤ top）我們就說這是個有效的索引。
3.2 -堆棧尺寸
當你使用Lua API 時昭躺，就有責任保證其堅固性忌锯。 特別需要注意的是，你有責任控制不要堆棧溢出领炫。 你可以使用lua_checkstack 這個函數(shù)來擴大可用堆棧的尺寸偶垮。
無論何時Lua 調(diào)用 C ， 它都只保證LUA_MINSTACK 這么多的堆椀酆椋空間可以使用似舵。 LUA_MINSTACK 一般被定義為 20 ， 因此葱峡，只要你不是不斷的把數(shù)據(jù)壓棧砚哗，通常你不用關心堆棧大小。
所有的查詢函數(shù)都可以接收一個索引砰奕，只要這個索引是任何棧提供的空間中的值频祝。棧能提供的最大空間是通過lua_checkstack 來設置的泌参。 這些索引被稱作可接受的索引脆淹，通常我們把它定義為：
? ? (index < 0 && abs(index) <= top) ||
? ? (index > 0 && index <= stackspace)
注意常空，0 永遠都不是一個可接受的索引。（譯注：下文中凡提到的索引盖溺，沒有特別注明的話漓糙，都指可接受的索引。）
3.3 -偽索引
除了特別聲明外烘嘱，任何一個函數(shù)都可以接受另一種有效的索引昆禽，它們被稱作“偽索引”。 這個可以幫助 C 代碼訪問一些并不在棧上的 Lua 值蝇庭。 偽索引被用來訪問線程的環(huán)境醉鳖，函數(shù)的環(huán)境，注冊表哮内，還有 C 函數(shù)的 upvalue （參見§3.4）盗棵。
線程的環(huán)境（也就是全局變量放的地方）通常在偽索引LUA_GLOBALSINDEX處。 正在運行的 C 函數(shù)的環(huán)境則放在偽索引LUA_ENVIRONINDEX 之處北发。
你可以用常規(guī)的table 操作來訪問和改變?nèi)肿兞康闹滴埔颍恍枰付ōh(huán)境表的位置。 舉例而言琳拨，要訪問全局變量的值瞭恰，這樣做：
? ? lua_getfield(L, LUA_GLOBALSINDEX, varname);
3.4 -C Closure
當C 函數(shù)被創(chuàng)建出來，我們有可能會把一些值關聯(lián)在一起狱庇， 也就是創(chuàng)建一個 C closure 惊畏； 這些被關聯(lián)起來的值被叫做 upvalue ， 它們可以在函數(shù)被調(diào)用的時候訪問的到密任。 （參見lua_pushcclosure）颜启。
無論何時去調(diào)用C 函數(shù)，函數(shù)的 upvalue 都被放在指定的偽索引處批什。 我們可以用lua_upvalueindex 這個宏來生成這些偽索引农曲。 第一個關聯(lián)到函數(shù)的值放在 lua_upvalueindex(1) 位置處，依次類推驻债。 任何情況下都可以用 lua_upvalueindex(n) 產(chǎn)生一個 upvalue 的索引乳规， 即使 n 大于實際的 upvalue 數(shù)量也可以。它都可以產(chǎn)生一個可接受但不一定有效的索引合呐。
3.5 -注冊表
Lua 提供了一個注冊表暮的，這是一個預定義出來的表，可以用來保存任何 C 代碼想保存的 Lua 值淌实。 這個表可以用偽索引LUA_REGISTRYINDEX 來定位冻辩。 任何 C 庫都可以在這張表里保存數(shù)據(jù)猖腕，為了防止沖突，你需要特別小心的選擇鍵名恨闪。 一般的用法是倘感，你可以用一個包含你的庫名的字符串做為鍵名，或者可以取你自己 C 代碼 中的一個地址咙咽，以 light userdata 的形式做鍵老玛。
注冊表里的整數(shù)健被用于補充庫中實現(xiàn)的引用系統(tǒng)的工作，一般說來不要把它們用于別的用途钧敞。
3.6 -C 中的錯誤處理
在內(nèi)部實現(xiàn)中蜡豹，Lua 使用了 C 的longjmp 機制來處理錯誤。 （如果你使用 C++ 的話溉苛，也可以選擇換用異常镜廉；參見 luaconf.h 文件。） 當 Lua 碰到任何錯誤（比如內(nèi)存分配錯誤愚战、類型錯誤娇唯、語法錯誤、還有一些運行時錯誤） 它都會產(chǎn)生一個錯誤出去凤巨； 也就是調(diào)用一個 long jump 视乐。 在保護環(huán)境下，Lua 使用 setjmp 來設置一個恢復點敢茁； 任何發(fā)生的錯誤都會激活最近的一個恢復點佑淀。
幾乎所有的API 函數(shù)都可能產(chǎn)生錯誤，例如內(nèi)存分配錯誤彰檬。 但下面的一些函數(shù)運行在保護環(huán)境中（也就是說它們創(chuàng)建了一個保護環(huán)境再在其中運行）伸刃， 因此它們不會產(chǎn)生錯誤出來：lua_newstate, lua_close, lua_load, lua_pcall, and lua_cpcall。
在C 函數(shù)里逢倍，你也可以通過調(diào)用lua_error 產(chǎn)生一個錯誤捧颅。
3.7 -函數(shù)和類型
在這里我們按字母次序列出了所有C API 中的函數(shù)和類型。
typedef void * (*lua_Alloc) (void *ud,
? ? ? ? ? ? ? ? ? ? ? ? ? ? void *ptr,
? ? ? ? ? ? ? ? ? ? ? ? ? ? size_t osize,
? ? ? ? ? ? ? ? ? ? ? ? ? ? size_t nsize);
Lua 狀態(tài)機中使用的內(nèi)存分配器函數(shù)的類型较雕。 內(nèi)存分配函數(shù)必須提供一個功能類似于 realloc 但又不完全相同的函數(shù)碉哑。 它的參數(shù)有 ud ，一個由 lua_newstate 傳給它的指針亮蒋； ptr 匾乓，一個指向已分配出來或是將被重新分配或是要釋放的內(nèi)存塊指針楞黄； osize 犀呼，內(nèi)存塊原來的尺寸呻待； nsize ，新內(nèi)存塊的尺寸趁怔。 如果且只有 osize 是零時湿硝，ptr 為 NULL 薪前。 當 nsize 是零，分配器必須返回 NULL关斜；如果osize 不是零示括，分配器應當釋放掉 ptr 指向的內(nèi)存塊。 當 nsize 不是零蚤吹，若分配器不能滿足請求時例诀，分配器返回 NULL 。 當 nsize 不是零而 osize 是零時裁着，分配器應該和 malloc 有相同的行為。 當 nsize 和 osize 都不是零時拱她，分配器則應和 realloc 保持一樣的行為二驰。 Lua 假設分配器在 osize >= nsize 時永遠不會失敗。
這里有一個簡單的分配器函數(shù)的實現(xiàn)秉沼。這個實現(xiàn)被放在補充庫中桶雀，由luaL_newstate 提供。
? ? static void *l_alloc (void *ud, void *ptr, size_t osize,
? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? size_t nsize) {
? ? ? (void)ud;? (void)osize;? /* not used */
? ? ? if (nsize == 0) {
? ? ? ? free(ptr);
? ? ? ? return NULL;
? ? ? }
? ? ? else
? ? ? ? return realloc(ptr, nsize);
? ? }
這段代碼假設free(NULL) 啥也不影響唬复，而且 realloc(NULL, size) 等價于 malloc(size)矗积。這兩點是ANSI C 保證的行為。
lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);
設置一個新的panic （恐慌） 函數(shù)敞咧，并返回前一個棘捣。
如果在保護環(huán)境之外發(fā)生了任何錯誤，Lua 就會調(diào)用一個 panic 函數(shù)休建，接著調(diào)用exit(EXIT_FAILURE)乍恐，這樣就開始退出宿主程序。你的panic 函數(shù)可以永遠不返回（例如作一次長跳轉(zhuǎn)）來避免程序退出测砂。
panic 函數(shù)可以從棧頂取到出錯信息茵烈。
void lua_call (lua_State *L, int nargs, int nresults);
調(diào)用一個函數(shù)。
要調(diào)用一個函數(shù)請遵循以下協(xié)議：首先砌些，要調(diào)用的函數(shù)應該被壓入堆棧呜投；接著，把需要傳遞給這個函數(shù)的參數(shù)按正序壓棧存璃；這是指第一個參數(shù)首先壓棧仑荐。最后調(diào)用一下lua_call；nargs 是你壓入堆棧的參數(shù)個數(shù)有巧。 當函數(shù)調(diào)用完畢后释漆，所有的參數(shù)以及函數(shù)本身都會出棧。 而函數(shù)的返回值這時則被壓入堆棧篮迎。 返回值的個數(shù)將被調(diào)整為 nresults 個男图， 除非 nresults被設置成LUA_MULTRET示姿。在這種情況下，所有的返回值都被壓入堆棧中逊笆。Lua 會保證返回值都放入椪淮粒空間中。 函數(shù)返回值將按正序壓棧（第一個返回值首先壓棧）难裆， 因此在調(diào)用結(jié)束后子檀，最后一個返回值將被放在棧頂。
被調(diào)用函數(shù)內(nèi)發(fā)生的錯誤將（通過longjmp）一直上拋乃戈。
下面的例子中褂痰，這行Lua 代碼等價于在宿主程序用 C 代碼做一些工作：
? ? a = f("how", t.x, 14)
這里是C 里的代碼：
? ? lua_getfield(L, LUA_GLOBALSINDEX, "f");? ? ? ? ? /* 將調(diào)用的函數(shù) */
? ? lua_pushstring(L, "how");? ? ? ? ? ? ? ? ? ? ? ? ? /* 第一個參數(shù) */
? ? lua_getfield(L, LUA_GLOBALSINDEX, "t");? ? ? ? ? /* table 的索引 */
? ? lua_getfield(L, -1, "x");? ? ? ? /* 壓入 t.x 的值（第 2 個參數(shù)）*/
? ? lua_remove(L, -2);? ? ? ? ? ? ? ? ? ? ? ? ? /* 從堆棧中移去 't' */
? ? lua_pushinteger(L, 14);? ? ? ? ? ? ? ? ? ? ? ? ? /* 第 3 個參數(shù) */
? ? lua_call(L, 3, 1); /* 調(diào)用 'f'，傳入 3 個參數(shù)症虑，并索取 1 個返回值 */
? ? lua_setfield(L, LUA_GLOBALSINDEX, "a");? ? ? /* 設置全局變量 'a' */
注意上面這段代碼是“平衡”的： 到了最后缩歪，堆棧恢復成原由的配置谍憔。 這是一種良好的編程習慣匪蝙。
typedef int (*lua_CFunction) (lua_State *L);
C 函數(shù)的類型。
為了正確的和Lua 通訊习贫，C 函數(shù)必須使用下列 定義了參數(shù)以及返回值傳遞方法的協(xié)議： C 函數(shù)通過 Lua 中的堆棧來接受參數(shù)逛球，參數(shù)以正序入棧（第一個參數(shù)首先入棧）。 因此苫昌，當函數(shù)開始的時候颤绕，lua_gettop(L) 可以返回函數(shù)收到的參數(shù)個數(shù)。 第一個參數(shù)（如果有的話）在索引 1 的地方蜡歹，而最后一個參數(shù)在索引 lua_gettop(L) 處屋厘。 當需要向 Lua 返回值的時候，C 函數(shù)只需要把它們以正序壓到堆棧上（第一個返回值最先壓入）月而， 然后返回這些返回值的個數(shù)汗洒。 在這些返回值之下的，堆棧上的東西都會被 Lua 丟掉父款。 和 Lua 函數(shù)一樣溢谤，從 Lua 中調(diào)用 C 函數(shù)也可以有很多返回值。
下面這個例子中的函數(shù)將接收若干數(shù)字參數(shù)憨攒，并返回它們的平均數(shù)與和：
? ? static int foo (lua_State *L) {
? ? ? int n = lua_gettop(L);? ? /* 參數(shù)的個數(shù) */
? ? ? lua_Number sum = 0;
? ? ? int i;
? ? ? for (i = 1; i <= n; i++) {
? ? ? ? if (!lua_isnumber(L, i)) {
? ? ? ? ? lua_pushstring(L, "incorrect argument");
? ? ? ? ? lua_error(L);
? ? ? ? }
? ? ? ? sum += lua_tonumber(L, i);
? ? ? }
? ? ? lua_pushnumber(L, sum/n);? /* 第一個返回值 */
? ? ? lua_pushnumber(L, sum);? ? /* 第二個返回值 */
? ? ? return 2;? ? ? ? ? ? ? ? ? /* 返回值的個數(shù) */
? ? }
int lua_checkstack (lua_State *L, int extra);
確保堆棧上至少有extra 個空位世杀。 如果不能把堆棧擴展到相應的尺寸，函數(shù)返回 false 肝集。 這個函數(shù)永遠不會縮小堆棧瞻坝； 如果堆棧已經(jīng)比需要的大了，那么就放在那里不會產(chǎn)生變化杏瞻。
void lua_close (lua_State *L);
銷毀指定Lua 狀態(tài)機中的所有對象（如果有垃圾收集相關的元方法的話所刀，會調(diào)用它們）衙荐， 并且釋放狀態(tài)機中使用的所有動態(tài)內(nèi)存。 在一些平臺上浮创，你可以不必調(diào)用這個函數(shù)忧吟， 因為當宿主程序結(jié)束的時候，所有的資源就自然被釋放掉了斩披。 另一方面溜族，長期運行的程序，比如一個后臺程序或是一個 web 服務器垦沉， 當不再需要它們的時候就應該釋放掉相關狀態(tài)機煌抒。這樣可以避免狀態(tài)機擴張的過大。
void lua_concat (lua_State *L, int n);
連接棧頂?shù)膎 個值乡话， 然后將這些值出棧摧玫，并把結(jié)果放在棧頂。 如果 n 為 1 绑青，結(jié)果就是一個字符串放在棧上（即，函數(shù)什么都不做）屋群； 如果 n 為 0 闸婴，結(jié)果是一個空串。 連接依照 Lua 中創(chuàng)建語義完成（參見 §2.5.4 ）芍躏。
int lua_cpcall (lua_State *L, lua_CFunction func, void *ud);
以保護模式調(diào)用C 函數(shù)func 邪乍。 func 只有能從堆棧上拿到一個參數(shù)，就是包含有 ud 的 light userdata对竣。 當有錯誤時庇楞， lua_cpcall 返回和 lua_pcall 相同的錯誤代碼， 并在棧頂留下錯誤對象否纬； 否則它返回零吕晌，并不會修改堆棧。 所有從 func 內(nèi)返回的值都會被扔掉临燃。
void lua_createtable (lua_State *L, int narr, int nrec);
創(chuàng)建一個新的空table 壓入堆棧睛驳。 這個新 table 將被預分配narr 個元素的數(shù)組空間 以及 nrec 個元素的非數(shù)組空間。 當你明確知道表中需要多少個元素時膜廊，預分配就非常有用乏沸。 如果你不知道，可以使用函數(shù) lua_newtable爪瓜。
int lua_dump (lua_State *L, lua_Writer writer, void *data);
把函數(shù)dump 成二進制 chunk 蹬跃。 函數(shù)接收棧頂?shù)?Lua 函數(shù)做參數(shù)，然后生成它的二進制 chunk 铆铆。 若被 dump 出來的東西被再次加載蝶缀，加載的結(jié)果就相當于原來的函數(shù)丹喻。 當它在產(chǎn)生 chunk 的時候，lua_dump 通過調(diào)用函數(shù) writer （參見 lua_Writer）來寫入數(shù)據(jù)，后面的data 參數(shù)會被傳入 writer 硼砰。
最后一次由寫入器(writer) 返回值將作為這個函數(shù)的返回值返回贰逾； 0 表示沒有錯誤。
這個函數(shù)不會把Lua 返回彈出堆棧骑冗。
int lua_equal (lua_State *L, int index1, int index2);
如果依照Lua 中== 操作符語義，索引 index1 和 index2 中的值相同的話先煎，返回 1 贼涩。 否則返回 0 。 如果任何一個索引無效也會返回 0薯蝎。
int lua_error (lua_State *L);
產(chǎn)生一個Lua 錯誤遥倦。 錯誤信息（實際上可以是任何類型的 Lua 值）必須被置入棧頂。 這個函數(shù)會做一次長跳轉(zhuǎn)占锯，因此它不會再返回袒哥。 （參見luaL_error）。
int lua_gc (lua_State *L, int what, int data);
控制垃圾收集器消略。
這個函數(shù)根據(jù)其參數(shù)what 發(fā)起幾種不同的任務：
[if !supportLists]· [endif]LUA_GCSTOP: 停止垃圾收集器堡称。
[if !supportLists]· [endif]LUA_GCRESTART: 重啟垃圾收集器。
[if !supportLists]· [endif]LUA_GCCOLLECT: 發(fā)起一次完整的垃圾收集循環(huán)艺演。
[if !supportLists]· [endif]LUA_GCCOUNT: 返回 Lua 使用的內(nèi)存總量（以 K 字節(jié)為單位）却紧。
[if !supportLists]· [endif]LUA_GCCOUNTB: 返回當前內(nèi)存使用量除以 1024 的余數(shù)。
[if !supportLists]· [endif]LUA_GCSTEP: 發(fā)起一步增量垃圾收集胎撤。 步數(shù)由 data 控制（越大的值意味著越多步）晓殊， 而其具體含義（具體數(shù)字表示了多少）并未標準化。 如果你想控制這個步數(shù)伤提，必須實驗性的測試 data 的值巫俺。 如果這一步結(jié)束了一個垃圾收集周期，返回返回 1 飘弧。
[if !supportLists]· [endif]LUA_GCSETPAUSE: 把 data/100 設置為 garbage-collector pause 的新值（參見 §2.10）识藤。函數(shù)返回以前的值。
[if !supportLists]· [endif]LUA_GCSETSTEPMUL: 把 arg/100 設置成 step multiplier （參見 §2.10）次伶。函數(shù)返回以前的值痴昧。
lua_Alloc lua_getallocf (lua_State *L, void **ud);
返回給定狀態(tài)機的內(nèi)存分配器函數(shù)。如果ud 不是 NULL 冠王，Lua 把調(diào)用 lua_newstate 時傳入的那個指針放入 *ud 赶撰。
void lua_getfenv (lua_State *L, int index);
把索引處值的環(huán)境表壓入堆棧。
void lua_getfield (lua_State *L, int index, const char *k);
把t[k] 值壓入堆棧， 這里的 t 是指有效索引 index 指向的值豪娜。 在 Lua 中餐胀，這個函數(shù)可能觸發(fā)對應 "index" 事件的元方法 （參見 §2.8）。
void lua_getglobal (lua_State *L, const char *name);
把全局變量name 里的值壓入堆棧瘤载。 這個是用一個宏定義出來的：
? ? #define lua_getglobal(L,s)? lua_getfield(L, LUA_GLOBALSINDEX, s)
int lua_getmetatable (lua_State *L, int index);
把給定索引指向的值的元表壓入堆棧否灾。如果索引無效，或是這個值沒有元表鸣奔，函數(shù)將返回0 并且不會向棧上壓任何東西墨技。
void lua_gettable (lua_State *L, int index);
把t[k] 值壓入堆棧， 這里的 t 是指有效索引 index 指向的值挎狸， 而 k 則是棧頂放的值扣汪。
這個函數(shù)會彈出堆棧上的key （把結(jié)果放在棧上相同位置）。 在 Lua 中锨匆，這個函數(shù)可能觸發(fā)對應 "index" 事件的元方法 （參見§2.8）崭别。
int lua_gettop (lua_State *L);
返回棧頂元素的索引。因為索引是從1 開始編號的恐锣， 所以這個結(jié)果等于堆棧上的元素個數(shù)（因此返回 0 表示堆棧為空）茅主。
void lua_insert (lua_State *L, int index);
把棧頂元素插入指定的有效索引處，并依次移動這個索引之上的元素土榴。不要用偽索引來調(diào)用這個函數(shù)暗膜，因為偽索引不是真正指向堆棧上的位置。
typedef ptrdiff_t lua_Integer;
這個類型被用于Lua API 接收整數(shù)值鞭衩。
缺省時這個被定義為ptrdiff_t ， 這個東西通常是機器能處理的最大整數(shù)類型娃善。
int lua_isboolean (lua_State *L, int index);
當給定索引的值類型為boolean 時论衍，返回 1 ，否則返回 0 聚磺。
int lua_iscfunction (lua_State *L, int index);
當給定索引的值是一個C 函數(shù)時坯台，返回 1 ，否則返回 0 瘫寝。
int lua_isfunction (lua_State *L, int index);
當給定索引的值是一個函數(shù)（C 或 Lua 函數(shù)均可）時蜒蕾，返回 1 ，否則返回 0 焕阿。
int lua_islightuserdata (lua_State *L, int index);
當給定索引的值是一個light userdata 時咪啡，返回 1 ，否則返回 0 暮屡。
int lua_isnil (lua_State *L, int index);
當給定索引的值是nil 時撤摸，返回 1 ，否則返回 0 。
int lua_isnumber (lua_State *L, int index);
當給定索引的值是一個數(shù)字准夷，或是一個可轉(zhuǎn)換為數(shù)字的字符串時钥飞，返回1 ，否則返回 0 衫嵌。
int lua_isstring (lua_State *L, int index);
當給定索引的值是一個字符串或是一個數(shù)字（數(shù)字總能轉(zhuǎn)換成字符串）時读宙，返回1 ，否則返回 0 楔绞。
int lua_istable (lua_State *L, int index);
當給定索引的值是一個table 時结闸，返回 1 ，否則返回 0 墓律。
int lua_isthread (lua_State *L, int index);
當給定索引的值是一個thread 時膀估，返回 1 ，否則返回 0 耻讽。
int lua_isuserdata (lua_State *L, int index);
當給定索引的值是一個userdata （無論是完整的 userdata 還是 light userdata ）時察纯，返回 1 ，否則返回 0 针肥。
int lua_lessthan (lua_State *L, int index1, int index2);
如果索引index1 處的值小于 索引 index2 處的值時饼记，返回 1 ； 否則返回 0 慰枕。 其語義遵循 Lua 中的 < 操作符（就是說具则，有可能調(diào)用元方法）。 如果任何一個索引無效具帮，也會返回 0 博肋。
int lua_load (lua_State *L,
? ? ? ? ? ? ? lua_Reader reader,
? ? ? ? ? ? ? void *data,
? ? ? ? ? ? ? const char *chunkname);
加載一個Lua chunk 。 如果沒有錯誤蜂厅，lua_load 把一個編譯好的 chunk 作為一個 Lua 函數(shù)壓入堆棧匪凡。 否則，壓入出錯信息掘猿。 lua_load 的返回值可以是：
[if !supportLists]· [endif]0: 沒有錯誤病游；
[if !supportLists]· [endif]LUA_ERRSYNTAX: 在預編譯時碰到語法錯誤；
[if !supportLists]· [endif]LUA_ERRMEM: 內(nèi)存分配錯誤稠通。
這個函數(shù)僅僅加栽chunk 衬衬；而不會去運行它。
lua_load 會自動檢測 chunk 是文本的還是二進制的改橘， 然后做對應的加載操作（參見程序 luac）滋尉。
lua_load 函數(shù)使用一個用戶提供的 reader 函數(shù)來 讀取 chunk （參見 lua_Reader）。data 參數(shù)會被傳入讀取器函數(shù)唧龄。
chunkname 這個參數(shù)可以賦予 chunk 一個名字兼砖， 這個名字被用于出錯信息和調(diào)試信息（參見 §3.8）奸远。
lua_State *lua_newstate (lua_Alloc f, void *ud);
創(chuàng)建的一個新的獨立的狀態(tài)機。如果創(chuàng)建不了（因為內(nèi)存問題）返回NULL 讽挟。 參數(shù) f 是一個分配器函數(shù)懒叛； Lua 將通過這個函數(shù)做狀態(tài)機內(nèi)所有的內(nèi)存分配操作。 第二個參數(shù) ud 耽梅，這個指針將在每次調(diào)用分配器時被直接傳入薛窥。
void lua_newtable (lua_State *L);
創(chuàng)建一個空table ，并將之壓入堆棧眼姐。 它等價于lua_createtable(L, 0, 0) 诅迷。
lua_State *lua_newthread (lua_State *L);
創(chuàng)建一個新線程，并將其壓入堆棧众旗，并返回維護這個線程的lua_State 指針罢杉。 這個函數(shù)返回的新狀態(tài)機共享原有狀態(tài)機中的所有對象（比如一些 table）， 但是它有獨立的執(zhí)行堆棧贡歧。
沒有顯式的函數(shù)可以用來關閉或銷毀掉一個線程滩租。線程跟其它Lua 對象一樣是垃圾收集的條目之一。
void *lua_newuserdata (lua_State *L, size_t size);
這個函數(shù)分配分配一塊指定大小的內(nèi)存塊利朵，把內(nèi)存塊地址作為一個完整的userdata 壓入堆棧又厉，并返回這個地址课竣。
userdata 代表 Lua 中的 C 值。 完整的 userdata 代表一塊內(nèi)存赶促。 它是一個對象（就像 table 那樣的對象）： 你必須創(chuàng)建它汰蜘，它有著自己的元表捆交，而且它在被回收時茧妒，可以被監(jiān)測到姿骏。 一個完整的 userdata 只和它自己相等（在等于的原生作用下）。
當Lua 通過gc 元方法回收一個完整的 userdata 時豹悬， Lua 調(diào)用這個元方法并把 userdata 標記為已終止澈歉。 等到這個 userdata 再次被收集的時候，Lua 會釋放掉相關的內(nèi)存屿衅。
int lua_next (lua_State *L, int index);
從棧上彈出一個key（鍵）， 然后把索引指定的表中 key-value（健值）對壓入堆棧 （指定 key 后面的下一 (next) 對）莹弊。 如果表中以無更多元素涤久， 那么lua_next 將返回 0 （什么也不壓入堆棧）。
典型的遍歷方法是這樣的：
? ? /* table 放在索引 't' 處 */
? ? lua_pushnil(L);? /* 第一個 key */
? ? while (lua_next(L, t) != 0) {
? ? ? /* 用一下 'key' （在索引 -2 處） 和 'value' （在索引 -1 處） */
? ? ? printf("%s - %s\n",
? ? ? ? ? ? ? lua_typename(L, lua_type(L, -2)),
? ? ? ? ? ? ? lua_typename(L, lua_type(L, -1)));
? ? ? /* 移除 'value' 忍弛；保留 'key' 做下一次迭代 */
? ? ? lua_pop(L, 1);
? ? }
在遍歷一張表的時候响迂，不要直接對key 調(diào)用lua_tolstring ， 除非你知道這個 key 一定是一個字符串细疚。 調(diào)用 lua_tolstring 有可能改變給定索引位置的值蔗彤； 這會對下一次調(diào)用 lua_next 造成影響。
typedef double lua_Number;
Lua 中數(shù)字的類型。 確省是 double 然遏，但是你可以在 luaconf.h 中修改它贫途。
通過修改配置文件你可以改變Lua 讓它操作其它數(shù)字類型（例如：float 或是 long ）。
size_t lua_objlen (lua_State *L, int index);
返回指定的索引處的值的長度待侵。對于string 丢早，那就是字符串的長度； 對于 table 秧倾，是取長度操作符 ('#') 的結(jié)果怨酝； 對于 userdata ，就是為其分配的內(nèi)存塊的尺寸那先； 對于其它值农猬，為 0 。
lua_pcall (lua_State *L, int nargs, int nresults, int errfunc);
以保護模式調(diào)用一個函數(shù)售淡。
nargs 和 nresults 的含義與 lua_call 中的相同斤葱。 如果在調(diào)用過程中沒有發(fā)生錯誤， lua_pcall 的行為和 lua_call 完全一致勋又。 但是苦掘，如果有錯誤發(fā)生的話， lua_pcall 會捕獲它楔壤， 然后把單一的值（錯誤信息）壓入堆棧鹤啡，然后返回錯誤碼。 同 lua_call 一樣蹲嚣， lua_pcall 總是把函數(shù)本身和它的參數(shù)從棧上移除递瑰。
如果errfunc 是 0 ， 返回在棧頂?shù)腻e誤信息就和原始錯誤信息完全一致隙畜。 否則抖部，errfunc 就被當成是錯誤處理函數(shù)在棧上的索引。 （在當前的實現(xiàn)里议惰，這個索引不能是偽索引慎颗。） 在發(fā)生運行時錯誤時， 這個函數(shù)會被調(diào)用而參數(shù)就是錯誤信息言询。 錯誤處理函數(shù)的返回值將被 lua_pcall 作為出錯信息返回在堆棧上俯萎。
典型的用法中，錯誤處理函數(shù)被用來在出錯信息上加上更多的調(diào)試信息运杭，比如棧跟蹤信息(stack traceback) 夫啊。 這些信息在lua_pcall 返回后，因為棧已經(jīng)展開 (unwound) 辆憔， 所以收集不到了撇眯。
lua_pcall 函數(shù)在調(diào)用成功時返回 0 报嵌， 否則返回以下（定義在 lua.h 中的）錯誤代碼中的一個：
[if !supportLists]· [endif]LUA_ERRRUN: 運行時錯誤。
[if !supportLists]· [endif]LUA_ERRMEM: 內(nèi)存分配錯誤熊榛。 對于這種錯锚国，Lua 調(diào)用不了錯誤處理函數(shù)。
[if !supportLists]· [endif]LUA_ERRERR: 在運行錯誤處理函數(shù)時發(fā)生的錯誤来候。
void lua_pop (lua_State *L, int n);
從堆棧中彈出n 個元素跷叉。
void lua_pushboolean (lua_State *L, int b);
把b 作為一個 boolean 值壓入堆棧。
void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);
把一個新的C closure 壓入堆棧营搅。
當創(chuàng)建了一個C 函數(shù)后云挟，你可以給它關聯(lián)一些值，這樣就是在創(chuàng)建一個 C closure （參見§3.4）转质；接下來無論函數(shù)何時被調(diào)用园欣，這些值都可以被這個函數(shù)訪問到。為了將一些值關聯(lián)到一個C 函數(shù)上休蟹， 首先這些值需要先被壓入堆棧（如果有多個值沸枯，第一個先壓）。 接下來調(diào)用lua_pushcclosure 來創(chuàng)建出 closure 并把這個 C 函數(shù)壓到堆棧上赂弓。 參數(shù) n 告之函數(shù)有多少個值需要關聯(lián)到函數(shù)上绑榴。 lua_pushcclosure 也會把這些值從棧上彈出。
void lua_pushcfunction (lua_State *L, lua_CFunction f);
將一個C 函數(shù)壓入堆棧盈魁。 這個函數(shù)接收一個 C 函數(shù)指針翔怎，并將一個類型為function 的 Lua 值 壓入堆棧。當這個棧頂?shù)闹当徽{(diào)用時杨耙，將觸發(fā)對應的 C 函數(shù)赤套。
注冊到Lua 中的任何函數(shù)都必須遵循正確的協(xié)議來接收參數(shù)和返回值 （參見lua_CFunction）。
lua_pushcfunction 是作為一個宏定義出現(xiàn)的：
? ? #define lua_pushcfunction(L,f)? lua_pushcclosure(L,f,0)
const char *lua_pushfstring (lua_State *L, const char *fmt, ...);
把一個格式化過的字符串壓入堆棧珊膜，然后返回這個字符串的指針容握。它和C 函數(shù)sprintf 比較像，不過有一些重要的區(qū)別：
[if !supportLists]· [endif]摸你需要為結(jié)果分配空間：其結(jié)果是一個Lua 字符串车柠，由 Lua 來關心其內(nèi)存分配 （同時通過垃圾收集來釋放內(nèi)存）剔氏。
[if !supportLists]· [endif]這個轉(zhuǎn)換非常的受限。不支持flag 竹祷，寬度介蛉，或是指定精度。 它只支持下面這些： '%%' （插入一個 '%'）溶褪， '%s' （插入一個帶零終止符的字符串，沒有長度限制）践险， '%f' （插入一個 lua_Number）猿妈，'%p' （插入一個指針或是一個十六進制數(shù)）吹菱， '%d' （插入一個 int)， '%c' （把一個 int 作為一個字符插入）彭则。
void lua_pushinteger (lua_State *L, lua_Integer n);
把n 作為一個數(shù)字壓棧鳍刷。
void lua_pushlightuserdata (lua_State *L, void *p);
把一個light userdata 壓棧。
userdata 在 Lua 中表示一個 C 值俯抖。 light userdata 表示一個指針输瓜。 它是一個像數(shù)字一樣的值： 你不需要專門創(chuàng)建它，它也沒有獨立的 metatable 芬萍， 而且也不會被收集（因為從來不需要創(chuàng)建）尤揣。 只要表示的 C 地址相同，兩個 light userdata 就相等柬祠。
void lua_pushlstring (lua_State *L, const char *s, size_t len);
把指針s 指向的長度為 len 的字符串壓棧北戏。 Lua 對這個字符串做一次內(nèi)存拷貝（或是復用一個拷貝）， 因此 s 處的內(nèi)存在函數(shù)返回后漫蛔，可以釋放掉或是重用于其它用途嗜愈。 字符串內(nèi)可以保存有零字符。
void lua_pushnil (lua_State *L);
把一個nil 壓棧莽龟。
void lua_pushnumber (lua_State *L, lua_Number n);
把一個數(shù)字n 壓棧蠕嫁。
void lua_pushstring (lua_State *L, const char *s);
把指針s 指向的以零結(jié)尾的字符串壓棧。 Lua 對這個字符串做一次內(nèi)存拷貝（或是復用一個拷貝）毯盈， 因此 s 處的內(nèi)存在函數(shù)返回后剃毒，可以釋放掉或是重用于其它用途。 字符串中不能包含有零字符奶镶；第一個碰到的零字符會認為是字符串的結(jié)束迟赃。
int lua_pushthread (lua_State *L);
把L 中提供的線程壓棧。 如果這個線程是當前狀態(tài)機的主線程的話厂镇，返回 1 纤壁。
void lua_pushvalue (lua_State *L, int index);
把堆棧上給定有效處索引處的元素作一個拷貝壓棧。
const char *lua_pushvfstring (lua_State *L,
? ? ? ? ? ? ? ? ? ? ? ? ? ? ? const char *fmt,
? ? ? ? ? ? ? ? ? ? ? ? ? ? ? va_list argp);
等價于lua_pushfstring捺信，不過是用va_list 接收參數(shù)酌媒，而不是用可變數(shù)量的實際參數(shù)。
int lua_rawequal (lua_State *L, int index1, int index2);
如果兩個索引index1 和 index2 處的值簡單地相等 （不調(diào)用元方法）則返回 1 。 否則返回 0 肌幽。 如果任何一個索引無效也返回 0 慌盯。
void lua_rawget (lua_State *L, int index);
類似于lua_gettable，但是作一次直接訪問（不觸發(fā)元方法）雨席。
void lua_rawgeti (lua_State *L, int index, int n);
把t[n] 的值壓棧， 這里的 t 是指給定索引 index 處的一個值吠式。 這是一個直接訪問陡厘；就是說抽米，它不會觸發(fā)元方法。
void lua_rawset (lua_State *L, int index);
類似于lua_settable糙置，但是是作一個直接賦值（不觸發(fā)元方法）云茸。
void lua_rawseti (lua_State *L, int index, int n);
等價于t[n] = v，這里的t 是指給定索引 index 處的一個值谤饭， 而 v 是棧頂?shù)闹怠?/p>
函數(shù)將把這個值彈出棧标捺。賦值操作是直接的；就是說揉抵，不會觸發(fā)元方法亡容。
typedef const char * (*lua_Reader) (lua_State *L,
? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? void *data,
? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? size_t *size);
lua_load 用到的讀取器函數(shù)， 每次它需要一塊新的 chunk 的時候功舀， lua_load 就調(diào)用讀取器萍倡， 每次都會傳入一個參數(shù) data 。 讀取器需要返回含有新的 chunk 的一塊內(nèi)存的指針辟汰， 并把 size 設為這塊內(nèi)存的大小列敲。 內(nèi)存塊必須在下一次函數(shù)被調(diào)用之前一直存在。 讀取器可以通過返回一個 NULL 來指示 chunk 結(jié)束帖汞。 讀取器可能返回多個塊戴而，每個塊可以有任意的大于零的尺寸。
void lua_register (lua_State *L,
? ? ? ? ? ? ? ? ? const char *name,
? ? ? ? ? ? ? ? ? lua_CFunction f);
把C 函數(shù)f 設到全局變量 name 中翩蘸。 它通過一個宏定義：
? ? #define lua_register(L,n,f) \
? ? ? ? ? ? (lua_pushcfunction(L, f), lua_setglobal(L, n))
void lua_remove (lua_State *L, int index);
從給定有效索引處移除一個元素所意，把這個索引之上的所有元素移下來填補上這個空隙。不能用偽索引來調(diào)用這個函數(shù)催首，因為偽索引并不指向真實的棧上的位置扶踊。
void lua_replace (lua_State *L, int index);
把棧頂元素移動到給定位置（并且把這個棧頂元素彈出），不移動任何元素（因此在那個位置處的值被覆蓋掉）郎任。
int lua_resume (lua_State *L, int narg);
在給定線程中啟動或繼續(xù)一個coroutine 秧耗。
要啟動一個coroutine 的話，首先你要創(chuàng)建一個新線程 （參見lua_newthread ）舶治； 然后把主函數(shù)和若干參數(shù)壓到新線程的堆棧上分井； 最后調(diào)用 lua_resume ， 把 narg 設為參數(shù)的個數(shù)霉猛。 這次調(diào)用會在 coroutine 掛起時或是結(jié)束運行后返回尺锚。 當函數(shù)返回時，堆棧中會有傳給 lua_yield 的所有值惜浅， 或是主函數(shù)的所有返回值瘫辩。 如果 coroutine 切換時，lua_resume 返回 LUA_YIELD ， 而當 coroutine 結(jié)束運行且沒有任何錯誤時伐厌，返回 0 阅仔。 如果有錯則返回錯誤代碼（參見 lua_pcall）。在發(fā)生錯誤的情況下弧械，堆棧沒有展開，因此你可以使用debug API 來處理它空民。 出錯信息放在棧頂刃唐。 要繼續(xù)運行一個 coroutine 的話，你把需要傳給yield 作結(jié)果的返回值壓入堆棧界轩，然后調(diào)用 lua_resume 画饥。
void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);
把指定狀態(tài)機的分配器函數(shù)換成帶上指針ud 的 f 。
int lua_setfenv (lua_State *L, int index);
從堆棧上彈出一個table 并把它設為指定索引處值的新環(huán)境浊猾。 如果指定索引處的值即不是函數(shù)又不是線程或是 userdata 抖甘，lua_setfenv 會返回 0 ， 否則返回 1 葫慎。
void lua_setfield (lua_State *L, int index, const char *k);
做一個等價于t[k] = v 的操作衔彻， 這里 t 是給出的有效索引 index 處的值， 而 v 是棧頂?shù)哪莻€值偷办。
這個函數(shù)將把這個值彈出堆棧艰额。跟在Lua 中一樣，這個函數(shù)可能觸發(fā)一個 "newindex" 事件的元方法 （參見§2.8）椒涯。
void lua_setglobal (lua_State *L, const char *name);
從堆棧上彈出一個值柄沮，并將其設到全局變量name 中。 它由一個宏定義出來：
? ? #define lua_setglobal(L,s)? lua_setfield(L, LUA_GLOBALSINDEX, s)
int lua_setmetatable (lua_State *L, int index);
把一個table 彈出堆棧废岂，并將其設為給定索引處的值的 metatable 祖搓。
void lua_settable (lua_State *L, int index);
作一個等價于t[k] = v 的操作， 這里 t 是一個給定有效索引 index 處的值湖苞， v 指棧頂?shù)闹担?而 k 是棧頂之下的那個值拯欧。
這個函數(shù)會把鍵和值都從堆棧中彈出。和在Lua 中一樣袒啼，這個函數(shù)可能觸發(fā) "newindex" 事件的元方法 （參見§2.8）哈扮。
void lua_settop (lua_State *L, int index);
參數(shù)允許傳入任何可接受的索引以及0 。 它將把堆棧的棧頂設為這個索引蚓再。 如果新的棧頂比原來的大滑肉，超出部分的新元素將被填為nil 。 如果 index 為 0 摘仅，把棧上所有元素移除靶庙。
typedef struct lua_State lua_State;
一個不透明的結(jié)構(gòu)，它保存了整個Lua 解釋器的狀態(tài)娃属。 Lua 庫是完全可重入的： 它沒有任何全局變量六荒。 （譯注：從 C 語法上來說护姆，也不盡然。例如掏击，在 table 的實現(xiàn)中 用了一個靜態(tài)全局變量 dummynode_ 卵皂，但這在正確使用時并不影響可重入性。 只是萬一你錯誤鏈接了 lua 庫砚亭，不小心在同一進程空間中存在兩份 lua 庫實現(xiàn)的代碼的話灯变， 多份 dummynode_ 不同的地址會導致一些問題。） 所有的信息都保存在這個結(jié)構(gòu)中捅膘。
這個狀態(tài)機的指針必須作為第一個參數(shù)傳遞給每一個庫函數(shù)添祸。lua_newstate 是一個例外， 這個函數(shù)會從頭創(chuàng)建一個 Lua 狀態(tài)機寻仗。
int lua_status (lua_State *L);
返回線程L 的狀態(tài)刃泌。
正常的線程狀態(tài)是0 。 當線程執(zhí)行完畢或發(fā)生一個錯誤時署尤，狀態(tài)值是錯誤碼耙替。 如果線程被掛起，狀態(tài)為LUA_YIELD 沐寺。
int lua_toboolean (lua_State *L, int index);
把指定的索引處的的Lua 值轉(zhuǎn)換為一個 C 中的 boolean 值（ 0 或是 1 ）林艘。 和 Lua 中做的所有測試一樣，lua_toboolean 會把任何 不同于 false 和 nil 的值當作 1 返回混坞； 否則就返回 0 狐援。 如果用一個無效索引去調(diào)用也會返回 0 。 （如果你想只接收真正的 boolean 值究孕，就需要使用 lua_isboolean 來測試值的類型啥酱。）
lua_CFunction lua_tocfunction (lua_State *L, int index);
把給定索引處的Lua 值轉(zhuǎn)換為一個 C 函數(shù)。 這個值必須是一個 C 函數(shù)厨诸；如果不是就返回NULL 镶殷。
lua_Integer lua_tointeger (lua_State *L, int idx);
把給定索引處的Lua 值轉(zhuǎn)換為lua_Integer 這樣一個有符號整數(shù)類型。 這個 Lua 值必須是一個數(shù)字或是一個可以轉(zhuǎn)換為數(shù)字的字符串 （參見 §2.2.1）微酬；否則绘趋，lua_tointeger 返回 0 。
如果數(shù)字不是一個整數(shù)颗管，截斷小數(shù)部分的方式?jīng)]有被明確定義陷遮。
const char *lua_tolstring (lua_State *L, int index, size_t *len);
把給定索引處的Lua 值轉(zhuǎn)換為一個 C 字符串。 如果len 不為 NULL 垦江， 它還把字符串長度設到 *len 中帽馋。 這個 Lua 值必須是一個字符串或是一個數(shù)字； 否則返回返回 NULL 。 如果值是一個數(shù)字绽族，lua_tolstring 還會把堆棧中的那個值的實際類型轉(zhuǎn)換為一個字符串姨涡。 （當遍歷一個表的時候，把 lua_tolstring 作用在鍵上吧慢，這個轉(zhuǎn)換有可能導致 lua_next 弄錯涛漂。）
lua_tolstring 返回 Lua 狀態(tài)機中 字符串的以對齊指針。 這個字符串總能保證 （ C 要求的）最后一個字符為零 ('\0') 检诗， 而且它允許在字符串內(nèi)包含多個這樣的零怖喻。 因為 Lua 中可能發(fā)生垃圾收集， 所以不保證 lua_tolstring 返回的指針岁诉， 在對應的值從堆棧中移除后依然有效。
lua_Number lua_tonumber (lua_State *L, int index);
把給定索引處的Lua 值轉(zhuǎn)換為lua_Number 這樣一個 C 類型（參見 lua_Number ）跋选。 這個 Lua 值必須是一個數(shù)字或是一個可轉(zhuǎn)換為數(shù)字的字符串 （參見 §2.2.1 ）估蹄； 否則苞冯，lua_tonumber 返回 0 。
const void *lua_topointer (lua_State *L, int index);
把給定索引處的值轉(zhuǎn)換為一般的C 指針 (void*) 。 這個值可以是一個 userdata 粘昨，table ，thread 或是一個 function 圆恤； 否則赤兴，lua_topointer 返回 NULL 。 不同的對象有不同的指針俭尖。 不存在把指針再轉(zhuǎn)回原有類型的方法氢惋。
這個函數(shù)通常只為產(chǎn)生debug 信息用。
const char *lua_tostring (lua_State *L, int index);
等價于lua_tolstring 稽犁，而參數(shù) len 設為 NULL 焰望。
lua_State *lua_tothread (lua_State *L, int index);
把給定索引處的值轉(zhuǎn)換為一個Lua 線程（由lua_State* 代表）。 這個值必須是一個線程已亥；否則函數(shù)返回 NULL 熊赖。
void *lua_touserdata (lua_State *L, int index);
如果給定索引處的值是一個完整的userdata ，函數(shù)返回內(nèi)存塊的地址虑椎。 如果值是一個 light userdata 震鹉，那么就返回它表示的指針。 否則捆姜，返回NULL 传趾。
int lua_type (lua_State *L, int index);
返回給定索引處的值的類型，當索引無效時則返回LUA_TNONE （那是指一個指向堆棧上的空位置的索引）娇未。 lua_type 返回的類型是一些個在 lua.h 中定義的常量： LUA_TNIL 墨缘， LUA_TNUMBER ， LUA_TBOOLEAN ， LUA_TSTRING 镊讼， LUA_TTABLE 宽涌， LUA_TFUNCTION ， LUA_TUSERDATA 蝶棋， LUA_TTHREAD卸亮，LUA_TLIGHTUSERDATA 。
const char *lua_typename? (lua_State *L, int tp);
返回tp 表示的類型名玩裙， 這個 tp 必須是 lua_type 可能返回的值中之一兼贸。
typedef int (*lua_Writer) (lua_State *L,
? ? ? ? ? ? ? ? ? ? ? ? ? const void* p,
? ? ? ? ? ? ? ? ? ? ? ? ? size_t sz,
? ? ? ? ? ? ? ? ? ? ? ? ? void* ud);
由lua_dump 用到的寫入器函數(shù)。 每次 lua_dump 產(chǎn)生了一塊新的 chunk 吃溅，它都會調(diào)用寫入器溶诞。 傳入要寫入的緩存 (p) 和它的尺寸 (sz) ， 還有 lua_dump 的參數(shù) data 决侈。
寫入器會返回一個錯誤碼：0 表示沒有錯誤螺垢； 別的值均表示一個錯誤，并且會讓lua_dump 停止再次調(diào)用寫入器赖歌。
void lua_xmove (lua_State *from, lua_State *to, int n);
傳遞同一個 全局狀態(tài)機下不同線程中的值枉圃。
這個函數(shù)會從from 的堆棧中彈出 n 個值， 然后把它們壓入 to 的堆棧中庐冯。
int lua_yield? (lua_State *L, int nresults);
切出一個coroutine 孽亲。
這個函數(shù)只能在一個C 函數(shù)的返回表達式中調(diào)用。如下：
? ? return lua_yield (L, nresults);
當一個C 函數(shù)這樣調(diào)用lua_yield 展父， 正在運行中的 coroutine 將從運行中掛起返劲， 然后啟動這個 coroutine 用的那次對 lua_resume 的調(diào)用就返回了。 參數(shù) nresults 指的是堆棧中需要返回的結(jié)果個數(shù)栖茉，這些返回值將被傳遞給 lua_resume 旭等。
3.8 -調(diào)試接口
Lua 沒有內(nèi)建的調(diào)試設施。 取而代之的是提供了一些函數(shù)接口和鉤子衡载。 利用這些接口搔耕，可以做出一些不同類型的調(diào)試器， 性能分析器痰娱，或是其它一些需要從解釋器中取到“內(nèi)部信息”的工具弃榨。
typedef struct lua_Debug {
? int event;
? const char *name;? ? ? ? ? /* (n) */
? const char *namewhat;? ? ? /* (n) */
? const char *what;? ? ? ? ? /* (S) */
? const char *source;? ? ? ? /* (S) */
? int currentline;? ? ? ? ? ? /* (l) */
? int nups;? ? ? ? ? ? ? ? ? /* (u) upvalue 個數(shù) */
? int linedefined;? ? ? ? ? ? /* (S) */
? int lastlinedefined;? ? ? ? /* (S) */
? char short_src[LUA_IDSIZE]; /* (S) */
? /* 私有部分 */
? 其它域
} lua_Debug;
一個用來攜帶活動中函數(shù)的各種信息的結(jié)構(gòu)。lua_getstack 僅填寫這個結(jié)構(gòu)中的私有部分梨睁， 這些部分以后會用到鲸睛。 調(diào)用 lua_getinfo 則可以填上 lua_Debug 中有用信息的那些域。
lua_Debug 中的各個域有下列含義：
[if !supportLists]· [endif]source: 如果函數(shù)是定義在一個字符串中坡贺，source 就是這個字符串官辈。 如果函數(shù)定義在一個文件中箱舞， source 是一個以 '@' 開頭的文件名。
[if !supportLists]· [endif]short_src: 一個“可打印版本”的 source拳亿，用于出錯信息晴股。
[if !supportLists]· [endif]linedefined: 函數(shù)定義開始處的行號。
[if !supportLists]· [endif]lastlinedefined: 函數(shù)定義結(jié)束處的行號肺魁。
[if !supportLists]· [endif]what: 如果函數(shù)是一個 Lua 函數(shù)电湘，則為一個字符串 "Lua" ； 如果是一個 C 函數(shù)鹅经，則為 "C"寂呛；如果它是一個chunk 的主體部分，則為"main"瘾晃；如果是一個作了尾調(diào)用的函數(shù)贷痪，則為"tail" 。 別的情況下蹦误，Lua 沒有關于函數(shù)的別的信息呢诬。
[if !supportLists]· [endif]currentline: 給定函數(shù)正在執(zhí)行的那一行。 當提供不了行號信息的時候胖缤，currentline 被設為 -1 。
[if !supportLists]· [endif]name: 給定函數(shù)的一個合理的名字阀圾。 因為 Lua 中的函數(shù)也是一個值哪廓， 所以它們沒有固定的名字： 一些函數(shù)可能是全局復合變量的值， 另一些可能僅僅只是被保存在一個 table 中初烘。 lua_getinfo 函數(shù)會檢查函數(shù)是這樣被調(diào)用的涡真，以此來找到一個適合的名字。 如果它找不到名字肾筐，name 就被設置為 NULL 哆料。
[if !supportLists]· [endif]namewhat: 結(jié)實 name 域。 namewhat 的值可以是 "global", "local", "method", "field", "upvalue", 或是 "" （空串）吗铐。 這取決于函數(shù)怎樣被調(diào)用东亦。 （Lua 用空串表示其它選項都不符合）
[if !supportLists]· [endif]nups: 函數(shù)的 upvalue 的個數(shù)。
lua_Hook lua_gethook (lua_State *L);
返回當前的鉤子函數(shù)唬渗。
int lua_gethookcount (lua_State *L);
返回當前鉤子記數(shù)典阵。
int lua_gethookmask (lua_State *L);
返回當前的鉤子掩碼(mask) 。
int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);
返回一個指定的函數(shù)或函數(shù)調(diào)用的信息镊逝。
當用于取得一次函數(shù)調(diào)用的信息時壮啊，參數(shù)ar 必須是一個有效的活動的記錄。 這條記錄可以是前一次調(diào)用 lua_getstack 得到的撑蒜， 或是一個鉤子 （參見 lua_Hook）得到的參數(shù)歹啼。
用于獲取一個函數(shù)的信息時玄渗，可以把這個函數(shù)壓入堆棧，然后把what 字符串以字符 '>' 起頭狸眼。 （這個情況下藤树，lua_getinfo 從棧頂上彈出函數(shù)。） 例如份企，想知道函數(shù) f 在哪一行定義的也榄， 你可以下下列代碼：
? ? lua_Debug ar;
? ? lua_getfield(L, LUA_GLOBALSINDEX, "f");? /* 取到全局變量 'f' */
? ? lua_getinfo(L, ">S", &ar);
? ? printf("%d\n", ar.linedefined);
what 字符串中的每個字符都篩選出結(jié)構(gòu) ar 結(jié)構(gòu)中一些域用于填充，或是把一個值壓入堆棧：
[if !supportLists]· [endif]'n': 填充 name 及 namewhat 域司志；
[if !supportLists]· [endif]'S': 填充 source甜紫，short_src，linedefined骂远，lastlinedefined囚霸，以及what 域；
[if !supportLists]· [endif]'l': 填充 currentline 域激才；
[if !supportLists]· [endif]'u': 填充 nups 域拓型；
[if !supportLists]· [endif]'f': 把正在運行中指定級別處函數(shù)壓入堆棧； （譯注：一般用于獲取函數(shù)調(diào)用中的信息瘸恼， 級別是由 ar 中的私有部分來提供劣挫。 如果用于獲取靜態(tài)函數(shù)，那么就直接把指定函數(shù)重新壓回堆棧东帅， 但這樣做通常無甚意義压固。）
[if !supportLists]· [endif]'L': 壓一個 table 入棧，這個 table 中的整數(shù)索引用于描述函數(shù)中哪些行是有效行靠闭。 （有效行指有實際代碼的行帐我， 即你可以置入斷點的行。 無效行包括空行和只有注釋的行愧膀。）
這個函數(shù)出錯會返回0 （例如拦键，what 中有一個無效選項）。
const char *lua_getlocal (lua_State *L, lua_Debug *ar, int n);
從給定活動記錄中獲取一個局部變量的信息檩淋。參數(shù)ar 必須是一個有效的活動的記錄芬为。 這條記錄可以是前一次調(diào)用 lua_getstack 得到的， 或是一個鉤子 （參見 lua_Hook）得到的參數(shù)蟀悦。索引n 用于選擇要檢閱哪個局部變量 （ 1 表示第一個參數(shù)或是激活的第一個局部變量碳柱，以此類推，直到最后一個局部變量）。 lua_getlocal 把變量的值壓入堆棧并返回它的名字。
以'(' （正小括號）開始的變量指內(nèi)部變量 （循環(huán)控制變量救湖，臨時變量，C 函數(shù)局部變量）瑞侮。
當索引大于局部變量的個數(shù)時的圆，返回NULL （什么也不壓入）。
int lua_getstack (lua_State *L, int level, lua_Debug *ar);
獲取解釋器的運行時棧的信息半火。
這個函數(shù)用正在運行中的給定級別處的函數(shù)的活動記錄來填寫lua_Debug 結(jié)構(gòu)的一部分越妈。 0 級表示當前運行的函數(shù)， 而 n+1 級處的函數(shù)就是調(diào)用第 n 級函數(shù)的那一個钮糖。 如果沒有錯誤梅掠，lua_getstack 返回 1 ； 當調(diào)用傳入的級別大于堆棧深度的時候店归，返回 0 阎抒。
const char *lua_getupvalue (lua_State *L, int funcindex, int n);
獲取一個closure 的 upvalue 信息。 （對于 Lua 函數(shù)消痛，upvalue 是函數(shù)需要使用的外部局部變量且叁， 因此這些變量被包含在 closure 中。）lua_getupvalue 獲取第 n 個 upvalue 秩伞， 把這個 upvalue 的值壓入堆棧逞带，并且返回它的名字。 funcindex 指向堆棧上 closure 的位置纱新。 （ 因為 upvalue 在整個函數(shù)中都有效展氓，所以它們沒有特別的次序。 因此脸爱，它們以字母次序來編號遇汞。）
當索引號比upvalue 數(shù)量大的時候，返回NULL （而且不會壓入任何東西） 對于 C 函數(shù)阅羹，這個函數(shù)用空串 "" 表示所有 upvalue 的名字。
typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);
用于調(diào)試的鉤子函數(shù)類型教寂。
無論何時鉤子被調(diào)用捏鱼，它的參數(shù)ar 中的 event域 都被設為觸發(fā)鉤子的事件。 Lua 把這些事件定義為以下常量：LUA_HOOKCALL酪耕，LUA_HOOKRET,LUA_HOOKTAILRET导梆，LUA_HOOKLINE，andLUA_HOOKCOUNT迂烁。除此之外看尼，對于line 事件，currentline 域也被設置盟步。 要想獲得 ar 中的其他域藏斩， 鉤子必須調(diào)用 lua_getinfo。對于返回事件却盘，event 的正常值可能是 LUA_HOOKRET狰域，或者是LUA_HOOKTAILRET 媳拴。 對于后一種情況，Lua 會對一個函數(shù)做的尾調(diào)用也模擬出一個返回事件出來兆览； 對于這個模擬的返回事件屈溉，調(diào)用 lua_getinfo 沒有什么作用。
當Lua 運行在一個鉤子內(nèi)部時抬探，它將屏蔽掉其它對鉤子的調(diào)用子巾。 也就是說，如果一個鉤子函數(shù)內(nèi)再調(diào)回 Lua 來執(zhí)行一個函數(shù)或是一個 chunk 小压， 這個執(zhí)行操作不會觸發(fā)任何的鉤子线梗。
int lua_sethook (lua_State *L, lua_Hook f, int mask, int count);
設置一個調(diào)試用鉤子函數(shù)。
參數(shù)f 是鉤子函數(shù)场航。 mask指定在哪些事件時會調(diào)用： 它由下列一組位常量構(gòu)成LUA_MASKCALL缠导，LUA_MASKRET，LUA_MASKLINE溉痢，以及LUA_MASKCOUNT僻造。參數(shù)count 只在 mask 中包含有 LUA_MASKCOUNT 才有意義。 對于每個事件孩饼，鉤子被調(diào)用的情況解釋如下：
[if !supportLists]· [endif]call hook: 在解釋器調(diào)用一個函數(shù)時被調(diào)用髓削。 鉤子將于 Lua 進入一個新函數(shù)后，函數(shù)獲取參數(shù)前被調(diào)用镀娶。
[if !supportLists]· [endif]return hook: 在解釋器從一個函數(shù)中返回時調(diào)用立膛。 鉤子將于 Lua 離開函數(shù)之前的那一刻被調(diào)用。 你無權(quán)訪問被函數(shù)返回出去的那些值梯码。 （譯注：原文 (You have no access to the values to be returned by the function) 如此宝泵。 但“無權(quán)訪問”一詞值得商榷。 某些情況下你可以訪問到一些被命名為 (*temporary) 的局部變量轩娶， 那些索引被排在最后的 (*temporary) 變量指的就是返回值儿奶。 但是由于 Lua 對特殊情況做了一些優(yōu)化，比如直接返回一個被命名的局部變量鳄抒， 那么就找不到對應的 (*temporary) 變量了闯捎。本質(zhì)上，返回值一定存在于此刻的局部變量中许溅， 并且可以訪問它瓤鼻，只是無法確定是哪些罷了。至于這個時候函數(shù)體內(nèi)的其它局部變量贤重， 是不保證有效的茬祷。進入 return hook 的那一刻起，實際已經(jīng)退出函數(shù)內(nèi)部的運行環(huán)節(jié)并蝗， 返回值占用的局部變量空間以后的部分牲迫，都有可能因 hook 本身復用它們而改變耐朴。）
[if !supportLists]· [endif]line hook: 在解釋器準備開始執(zhí)行新的一行代碼時， 或是跳轉(zhuǎn)到這行代碼中時（即使在同一行內(nèi)跳轉(zhuǎn)）被調(diào)用盹憎。 （這個事件僅僅在 Lua 執(zhí)行一個 Lua 函數(shù)時發(fā)生筛峭。）
[if !supportLists]· [endif]count hook: 在解釋器每執(zhí)行 count 條指令后被調(diào)用。 （這個事件僅僅在 Lua 執(zhí)行一個 Lua 函數(shù)時發(fā)生陪每。）
鉤子可以通過設置mask 為零屏蔽影晓。
const char *lua_setlocal (lua_State *L, lua_Debug *ar, int n);
設置給定活動記錄中的局部變量的值。參數(shù)ar 與 n 和 lua_getlocal 中的一樣 （參見 lua_getlocal）檩禾。lua_setlocal 把棧頂?shù)闹蒂x給變量然后返回變量的名字挂签。 它會將值從棧頂彈出。
當索引大于局部變量的個數(shù)時盼产，返回NULL （什么也不彈出）饵婆。
const char *lua_setupvalue (lua_State *L, int funcindex, int n);
設置closure 的 upvalue 的值。 它把棧頂?shù)闹祻棾霾①x于 upvalue 并返回 upvalue 的名字戏售。 參數(shù)funcindex 與 n 和 lua_getupvalue 中的一樣 （參見 lua_getupvalue）侨核。
當索引大于upvalue 的個數(shù)時，返回NULL （什么也不彈出）灌灾。
The auxiliary library provides several convenient functions to interface C with Lua. While the basic API provides the primitive functions for all interactions between C and Lua, the auxiliary library provides higher-level functions for some common tasks.
All functions from the auxiliary library are defined in header file lauxlib.h and have a prefix luaL_.
All functions in the auxiliary library are built on top of the basic API, and so they provide nothing that cannot be done with this API.
Several functions in the auxiliary library are used to check C function arguments. Their names are always luaL_check* or luaL_opt*. All of these functions raise an error if the check is not satisfied. Because the error message is formatted for arguments (e.g., "bad argument #1"), you should not use these functions for other stack values.
4.1 -Functions and Types
Here we list all functions and types from the auxiliary library in alphabetical order.
void luaL_addchar (luaL_Buffer *B, char c);
Adds the character c to the buffer B (see luaL_Buffer).
void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);
Adds the string pointed to by s with length l to the buffer B (see luaL_Buffer). The string may contain embedded zeros.
void luaL_addsize (luaL_Buffer *B, size_t n);
Adds to the buffer B (see luaL_Buffer) a string of length n previously copied to the buffer area (see luaL_prepbuffer).
void luaL_addstring (luaL_Buffer *B, const char *s);
Adds the zero-terminated string pointed to by s to the buffer B (see luaL_Buffer). The string may not contain embedded zeros.
void luaL_addvalue (luaL_Buffer *B);
Adds the value at the top of the stack to the buffer B (see luaL_Buffer). Pops the value.
This is the only function on string buffers that can (and must) be called with an extra element on the stack, which is the value to be added to the buffer.
void luaL_argcheck (lua_State *L,
? ? ? ? ? ? ? ? ? ? int cond,
? ? ? ? ? ? ? ? ? ? int narg,
? ? ? ? ? ? ? ? ? ? const char *extramsg);
Checks whether cond is true. If not, raises an error with the following message, where func is retrieved from the call stack:
? ? bad argument # to? ()
int luaL_argerror (lua_State *L, int narg, const char *extramsg);
Raises an error with the following message, where func is retrieved from the call stack:
? ? bad argument # to? ()
This function never returns, but it is an idiom to use it in C functions as return luaL_argerror(args).
typedef struct luaL_Buffer luaL_Buffer;
Type for a string buffer.
A string buffer allows C code to build Lua strings piecemeal. Its pattern of use is as follows:
[if !supportLists]· [endif]First you declare a variable b of type luaL_Buffer.
[if !supportLists]· [endif]Then you initialize it with a call luaL_buffinit(L, &b).
[if !supportLists]· [endif]Then you add string pieces to the buffer calling any of the luaL_add* functions.
[if !supportLists]· [endif]You finish by calling luaL_pushresult(&b). This call leaves the final string on the top of the stack.
During its normal operation, a string buffer uses a variable number of stack slots. So, while using a buffer, you cannot assume that you know where the top of the stack is. You can use the stack between successive calls to buffer operations as long as that use is balanced; that is, when you call a buffer operation, the stack is at the same level it was immediately after the previous buffer operation. (The only exception to this rule is luaL_addvalue.) After calling luaL_pushresult the stack is back to its level when the buffer was initialized, plus the final string on its top.
void luaL_buffinit (lua_State *L, luaL_Buffer *B);
Initializes a buffer B. This function does not allocate any space; the buffer must be declared as a variable (see luaL_Buffer).
int luaL_callmeta (lua_State *L, int obj, const char *e);
Calls a metamethod.
If the object at index obj has a metatable and this metatable has a field e, this function calls this field and passes the object as its only argument. In this case this function returns 1 and pushes onto the stack the value returned by the call. If there is no metatable or no metamethod, this function returns 0 (without pushing any value on the stack).
void luaL_checkany (lua_State *L, int narg);
Checks whether the function has an argument of any type (including nil) at position narg.
int luaL_checkint (lua_State *L, int narg);
Checks whether the function argument narg is a number and returns this number cast to an int.
lua_Integer luaL_checkinteger (lua_State *L, int narg);
Checks whether the function argument narg is a number and returns this number cast to a lua_Integer.
long luaL_checklong (lua_State *L, int narg);
Checks whether the function argument narg is a number and returns this number cast to a long.
const char *luaL_checklstring (lua_State *L, int narg, size_t *l);
Checks whether the function argument narg is a string and returns this string; if l is not NULL fills *l with the string's length.
lua_Number luaL_checknumber (lua_State *L, int narg);
Checks whether the function argument narg is a number and returns this number.
int luaL_checkoption (lua_State *L,
? ? ? ? ? ? ? ? ? ? ? int narg,
? ? ? ? ? ? ? ? ? ? ? const char *def,
? ? ? ? ? ? ? ? ? ? ? const char *const lst[]);
Checks whether the function argument narg is a string and searches for this string in the array lst (which must be NULL-terminated). Returns the index in the array where the string was found. Raises an error if the argument is not a string or if the string cannot be found.
If def is not NULL, the function uses def as a default value when there is no argument narg or if this argument is nil.
This is a useful function for mapping strings to C enums. (The usual convention in Lua libraries is to use strings instead of numbers to select options.)
void luaL_checkstack (lua_State *L, int sz, const char *msg);
Grows the stack size to top + sz elements, raising an error if the stack cannot grow to that size. msg is an additional text to go into the error message.
const char *luaL_checkstring (lua_State *L, int narg);
Checks whether the function argument narg is a string and returns this string.
void luaL_checktype (lua_State *L, int narg, int t);
Checks whether the function argument narg has type t.
void *luaL_checkudata (lua_State *L, int narg, const char *tname);
Checks whether the function argument narg is a userdata of the type tname (see luaL_newmetatable).
int luaL_dofile (lua_State *L, const char *filename);
Loads and runs the given file. It is defined as the following macro:
? ? (luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0))
It returns 0 if there are no errors or 1 in case of errors.
int luaL_dostring (lua_State *L, const char *str);
Loads and runs the given string. It is defined as the following macro:
? ? (luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0))
It returns 0 if there are no errors or 1 in case of errors.
int luaL_error (lua_State *L, const char *fmt, ...);
Raises an error. The error message format is given by fmt plus any extra arguments, following the same rules of lua_pushfstring. It also adds at the beginning of the message the file name and the line number where the error occurred, if this information is available.
This function never returns, but it is an idiom to use it in C functions as return luaL_error(args).
int luaL_getmetafield (lua_State *L, int obj, const char *e);
Pushes onto the stack the field e from the metatable of the object at index obj. If the object does not have a metatable, or if the metatable does not have this field, returns 0 and pushes nothing.
void luaL_getmetatable (lua_State *L, const char *tname);
Pushes onto the stack the metatable associated with name tname in the registry (see luaL_newmetatable).
const char *luaL_gsub (lua_State *L,
? ? ? ? ? ? ? ? ? ? ? const char *s,
? ? ? ? ? ? ? ? ? ? ? const char *p,
? ? ? ? ? ? ? ? ? ? ? const char *r);
Creates a copy of string s by replacing any occurrence of the string p with the string r. Pushes the resulting string on the stack and returns it.
int luaL_loadbuffer (lua_State *L,
? ? ? ? ? ? ? ? ? ? const char *buff,
? ? ? ? ? ? ? ? ? ? size_t sz,
? ? ? ? ? ? ? ? ? ? const char *name);
Loads a buffer as a Lua chunk. This function uses lua_load to load the chunk in the buffer pointed to by buff with size sz.
This function returns the same results as lua_load. name is the chunk name, used for debug information and error messages.
int luaL_loadfile (lua_State *L, const char *filename);
Loads a file as a Lua chunk. This function uses lua_load to load the chunk in the file named filename. If filename is NULL, then it loads from the standard input. The first line in the file is ignored if it starts with a #.
This function returns the same results as lua_load, but it has an extra error codeLUA_ERRFILE if it cannot open/read the file.
As lua_load, this function only loads the chunk; it does not run it.
int luaL_loadstring (lua_State *L, const char *s);
Loads a string as a Lua chunk. This function uses lua_load to load the chunk in the zero-terminated string s.
This function returns the same results as lua_load.
Also as lua_load, this function only loads the chunk; it does not run it.
int luaL_newmetatable (lua_State *L, const char *tname);
If the registry already has the key tname, returns 0. Otherwise, creates a new table to be used as a metatable for userdata, adds it to the registry with key tname, and returns 1.
In both cases pushes onto the stack the final value associated with tname in the registry.
lua_State *luaL_newstate (void);
Creates a new Lua state. It calls lua_newstate with an allocator based on the standard C realloc function and then sets a panic function (see lua_atpanic) that prints an error message to the standard error output in case of fatal errors.
Returns the new state, or NULL if there is a memory allocation error.
void luaL_openlibs (lua_State *L);
Opens all standard Lua libraries into the given state.
int luaL_optint (lua_State *L, int narg, int d);
If the function argument narg is a number, returns this number cast to an int. If this argument is absent or is nil, returns d. Otherwise, raises an error.
lua_Integer luaL_optinteger (lua_State *L,
? ? ? ? ? ? ? ? ? ? ? ? ? ? int narg,
? ? ? ? ? ? ? ? ? ? ? ? ? ? lua_Integer d);
If the function argument narg is a number, returns this number cast to a lua_Integer. If this argument is absent or is nil, returns d. Otherwise, raises an error.
long luaL_optlong (lua_State *L, int narg, long d);
If the function argument narg is a number, returns this number cast to a long. If this argument is absent or is nil, returns d. Otherwise, raises an error.
const char *luaL_optlstring (lua_State *L,
? ? ? ? ? ? ? ? ? ? ? ? ? ? int narg,
? ? ? ? ? ? ? ? ? ? ? ? ? ? const char *d,
? ? ? ? ? ? ? ? ? ? ? ? ? ? size_t *l);
If the function argument narg is a string, returns this string. If this argument is absent or is nil, returns d. Otherwise, raises an error.
If l is not NULL, fills the position *l with the results's length.
lua_Number luaL_optnumber (lua_State *L, int narg, lua_Number d);
If the function argument narg is a number, returns this number. If this argument is absent or is nil, returns d. Otherwise, raises an error.
const char *luaL_optstring (lua_State *L,
? ? ? ? ? ? ? ? ? ? ? ? ? ? int narg,
? ? ? ? ? ? ? ? ? ? ? ? ? ? const char *d);
If the function argument narg is a string, returns this string. If this argument is absent or is nil, returns d. Otherwise, raises an error.
char *luaL_prepbuffer (luaL_Buffer *B);
Returns an address to a space of sizeLUAL_BUFFERSIZE where you can copy a string to be added to buffer B (see luaL_Buffer). After copying the string into this space you must call luaL_addsize with the size of the string to actually add it to the buffer.
void luaL_pushresult (luaL_Buffer *B);
Finishes the use of buffer B leaving the final string on the top of the stack.
int luaL_ref (lua_State *L, int t);
Creates and returns a reference, in the table at index t, for the object at the top of the stack (and pops the object).
A reference is a unique integer key. As long as you do not manually add integer keys into table t, luaL_ref ensures the uniqueness of the key it returns. You can retrieve an object referred by reference r by calling lua_rawgeti(L, t, r). Function luaL_unreffrees a reference and its associated object.
If the object at the top of the stack is nil, luaL_refreturns the constantLUA_REFNIL. The constantLUA_NOREF is guaranteed to be different from any reference returned by luaL_ref.
typedef struct luaL_Reg {
? const char *name;
? lua_CFunction func;
} luaL_Reg;
Type for arrays of functions to be registered by luaL_register. name is the function name and func is a pointer to the function. Any array of luaL_Reg must end with an sentinel entry in which both name and func are NULL.
void luaL_register (lua_State *L,
? ? ? ? ? ? ? ? ? ? const char *libname,
? ? ? ? ? ? ? ? ? ? const luaL_Reg *l);
Opens a library.
When called with libname equal to NULL, it simply registers all functions in the list l (see luaL_Reg) into the table on the top of the stack.
When called with a non-null libname, luaL_register creates a new table t, sets it as the value of the global variable libname, sets it as the value of package.loaded[libname], and registers on it all functions in the list l. If there is a table in package.loaded[libname] or in variable libname, reuses this table instead of creating a new one.
In any case the function leaves the table on the top of the stack.
const char *luaL_typename (lua_State *L, int idx);
Returns the name of the type of the value at index idx.
int luaL_typerror (lua_State *L, int narg, const char *tname);
Generates an error with a message like the following:
? ? location: bad argument narg to 'func' (tname expected, got rt)
where location is produced by luaL_where, func is the name of the current function, and rt is the type name of the actual argument.
void luaL_unref (lua_State *L, int t, int ref);
Releases reference ref from the table at index t (see luaL_ref). The entry is removed from the table, so that the referred object can be collected. The reference ref is also freed to be used again.
If ref is LUA_NOREF or LUA_REFNIL, luaL_unref does nothing.
void luaL_where (lua_State *L, int lvl);
Pushes onto the stack a string identifying the current position of the control at level lvl in the call stack. Typically this string has the following format:
? ? chunkname:currentline:
Level 0 is the running function, level 1 is the function that called the running function, etc.
This function is used to build a prefix for error messages.
The standard Lua libraries provide useful functions that are implemented directly through the C API. Some of these functions provide essential services to the language (e.g., type and getmetatable); others provide access to "outside" services (e.g., I/O); and others could be implemented in Lua itself, but are quite useful or have critical performance requirements that deserve an implementation in C (e.g., sort).
All libraries are implemented through the official C API and are provided as separate C modules. Currently, Lua has the following standard libraries:
[if !supportLists]· [endif]basic library;
[if !supportLists]· [endif]package library;
[if !supportLists]· [endif]string manipulation;
[if !supportLists]· [endif]table manipulation;
[if !supportLists]· [endif]mathematical functions (sin, log, etc.);
[if !supportLists]· [endif]input and output;
[if !supportLists]· [endif]operating system facilities;
[if !supportLists]· [endif]debug facilities.
Except for the basic and package libraries, each library provides all its functions as fields of a global table or as methods of its objects.
To have access to these libraries, the C host program should call the luaL_openlibsfunction, which opens all standard libraries. Alternatively, it can open them individually by callingluaopen_base(for the basic library),luaopen_package(for the package library),luaopen_string(for the string library),luaopen_table(for the table library),luaopen_math(for the mathematical library),luaopen_io(for the I/O and the Operating System libraries), andluaopen_debug(for the debug library). These functions are declared inlualib.h and should not be called directly: you must call them like any other Lua C function, e.g., by using lua_call.
5.1 -Basic Functions
The basic library provides some core functions to Lua. If you do not include this library in your application, you should check carefully whether you need to provide implementations for some of its facilities.
Issues an error when the value of its argument v is false (i.e., nil or false); otherwise, returns all its arguments. message is an error message; when absent, it defaults to "assertion failed!"
This function is a generic interface to the garbage collector. It performs different functions according to its first argument, opt:
[if !supportLists]· [endif]"stop": stops the garbage collector.
[if !supportLists]· [endif]"restart": restarts the garbage collector.
[if !supportLists]· [endif]"collect": performs a full garbage-collection cycle.
[if !supportLists]· [endif]"count": returns the total memory in use by Lua (in Kbytes).
[if !supportLists]· [endif]"step": performs a garbage-collection step. The step "size" is controlled by arg (larger values mean more steps) in a non-specified way. If you want to control the step size you must experimentally tune the value of arg. Returns true if the step finished a collection cycle.
[if !supportLists]· [endif]"setpause": sets arg/100 as the new value for the pause of the collector (see §2.10).
[if !supportLists]· [endif]"setstepmul": sets arg/100 as the new value for the step multiplier of the collector (see §2.10).
Opens the named file and executes its contents as a Lua chunk. When called without arguments, dofile executes the contents of the standard input (stdin). Returns all values returned by the chunk. In case of errors, dofile propagates the error to its caller (that is, dofile does not run in protected mode).
Terminates the last protected function called and returns message as the error message. Function error never returns.
Usually, error adds some information about the error position at the beginning of the message. The level argument specifies how to get the error position. With level 1 (the default), the error position is where the error function was called. Level 2 points the error to where the function that called error was called; and so on. Passing a level 0 avoids the addition of error position information to the message.
A global variable (not a function) that holds the global environment (that is, _G._G = _G). Lua itself does not use this variable; changing its value does not affect any environment, nor vice-versa. (Use setfenv to change environments.)
Returns the current environment in use by the function. f can be a Lua function or a number that specifies the function at that stack level: Level 1 is the function calling getfenv. If the given function is not a Lua function, or if f is 0, getfenv returns the global environment. The default for f is 1.
If object does not have a metatable, returns nil. Otherwise, if the object's metatable has a "__metatable" field, returns the associated value. Otherwise, returns the metatable of the given object.
Returns three values: an iterator function, the table t, and 0, so that the construction
? ? for i,v in ipairs(t) do body end
will iterate over the pairs (1,t[1]), (2,t[2]), ···, up to the first integer key absent from the table.
Loads a chunk using function func to get its pieces. Each call to func must return a string that concatenates with previous results. A return of nil (or no value) signals the end of the chunk.
If there are no errors, returns the compiled chunk as a function; otherwise, returns nil plus the error message. The environment of the returned function is the global environment.
chunkname is used as the chunk name for error messages and debug information.
Similar to load, but gets the chunk from file filename or from the standard input, if no file name is given.
loadstring (string [, chunkname])
Similar to load, but gets the chunk from the given string.
To load and run a given string, use the idiom
? ? assert(loadstring(s))()
Allows a program to traverse all fields of a table. Its first argument is a table and its second argument is an index in this table. next returns the next index of the table and its associated value. When called with nil as its second argument, next returns an initial index and its associated value. When called with the last index, or with nil in an empty table, next returns nil. If the second argument is absent, then it is interpreted as nil. In particular, you can use next(t) to check whether a table is empty.
The order in which the indices are enumerated is not specified, even for numeric indices. (To traverse a table in numeric order, use a numerical for or the ipairs function.)
The behavior of next is undefined if, during the traversal, you assign any value to a non-existent field in the table. You may however modify existing fields. In particular, you may clear existing fields.
Returns three values: the next function, the table t, and nil, so that the construction
? ? for k,v in pairs(t) do body end
will iterate over all key–value pairs of table t.
See function next for the caveats of modifying the table during its traversal.
Calls function f with the given arguments in protected mode. This means that any error inside f is not propagated; instead, pcall catches the error and returns a status code. Its first result is the status code (a boolean), which is true if the call succeeds without errors. In such case, pcall also returns all results from the call, after this first result. In case of any error, pcall returns false plus the error message.
Receives any number of arguments, and prints their values to stdout, using the tostring function to convert them to strings. print is not intended for formatted output, but only as a quick way to show a value, typically for debugging. For formatted output, use string.format.
Checks whether v1 is equal to v2, without invoking any metamethod. Returns a boolean.
Gets the real value of table[index], without invoking any metamethod. table must be a table; index may be any value.
Sets the real value of table[index] to value, without invoking any metamethod. table must be a table, index any value different from nil, and value any Lua value.
This function returns table.
If index is a number, returns all arguments after argument number index. Otherwise, index must be the string "#", and select returns the total number of extra arguments it received.
Sets the environment to be used by the given function. f can be a Lua function or a number that specifies the function at that stack level: Level 1 is the function calling setfenv. setfenv returns the given function.
As a special case, when f is 0 setfenv changes the environment of the running thread. In this case, setfenv returns no values.
setmetatable (table, metatable)
Sets the metatable for the given table. (You cannot change the metatable of other types from Lua, only from C.) If metatable is nil, removes the metatable of the given table. If the original metatable has a "__metatable" field, raises an error.
This function returns table.
Tries to convert its argument to a number. If the argument is already a number or a string convertible to a number, then tonumber returns this number; otherwise, it returns nil.
An optional argument specifies the base to interpret the numeral. The base may be any integer between 2 and 36, inclusive. In bases above 10, the letter 'A' (in either upper or lower case) represents 10, 'B' represents 11, and so forth, with 'Z' representing 35. In base 10 (the default), the number may have a decimal part, as well as an optional exponent part (see §2.1). In other bases, only unsigned integers are accepted.
Receives an argument of any type and converts it to a string in a reasonable format. For complete control of how numbers are converted, use string.format.
If the metatable of e has a "__tostring" field, then tostring calls the corresponding value with e as argument, and uses the result of the call as its result.
Returns the type of its only argument, coded as a string. The possible results of this function are "nil" (a string, not the value nil), "number", "string", "boolean", "table", "function", "thread", and "userdata".
Returns the elements from the given table. This function is equivalent to
? ? return list[i], list[i+1], ···, list[j]
except that the above code can be written only for a fixed number of elements. By default, i is 1 and j is the length of the list, as defined by the length operator (see §2.5.5).
A global variable (not a function) that holds a string containing the current interpreter version. The current contents of this variable is "Lua 5.1".
This function is similar to pcall, except that you can set a new error handler.
xpcall calls function f in protected mode, using err as the error handler. Any error inside f is not propagated; instead, xpcall catches the error, calls the err function with the original error object, and returns a status code. Its first result is the status code (a boolean), which is true if the call succeeds without errors. In this case, xpcall also returns all results from the call, after this first result. In case of any error, xpcall returns false plus the result from err.
The operations related to coroutines comprise a sub-library of the basic library and come inside the tablecoroutine. See §2.11 for a general description of coroutines.
Creates a new coroutine, with body f. f must be a Lua function. Returns this new coroutine, an object with type "thread".
coroutine.resume (co [, val1, ···])
Starts or continues the execution of coroutine co. The first time you resume a coroutine, it starts running its body. The values val1, ··· are passed as the arguments to the body function. If the coroutine has yielded, resume restarts it; the values val1, ··· are passed as the results from the yield.
If the coroutine runs without any errors, resume returns true plus any values passed to yield (if the coroutine yields) or any values returned by the body function (if the coroutine terminates). If there is any error, resume returns false plus the error message.
Returns the running coroutine, or nil when called by the main thread.
Returns the status of coroutine co, as a string: "running", if the coroutine is running (that is, it called status); "suspended", if the coroutine is suspended in a call to yield, or if it has not started running yet; "normal" if the coroutine is active but not running (that is, it has resumed another coroutine); and "dead" if the coroutine has finished its body function, or if it has stopped with an error.
Creates a new coroutine, with body f. f must be a Lua function. Returns a function that resumes the coroutine each time it is called. Any arguments passed to the function behave as the extra arguments to resume. Returns the same values returned by resume, except the first boolean. In case of error, propagates the error.
Suspends the execution of the calling coroutine. The coroutine cannot be running a C function, a metamethod, or an iterator. Any arguments to yield are passed as extra results to resume.
5.3 -Modules
The package library provides basic facilities for loading and building modules in Lua. It exports two of its functions directly in the global environment: require and module. Everything else is exported in a tablepackage.
Creates a module. If there is a table in package.loaded[name], this table is the module. Otherwise, if there is a global table t with the given name, this table is the module. Otherwise creates a new table t and sets it as the value of the global name and the value of package.loaded[name]. This function also initializes t._NAME with the given name, t._M with the module (t itself), and t._PACKAGE with the package name (the full module name minus last component; see below). Finally, module sets t as the new environment of the current function and the new value of package.loaded[name], so that require returns t.
If name is a compound name (that is, one with components separated by dots), module creates (or reuses, if they already exist) tables for each component. For instance, if name is a.b.c, then module stores the module table in field c of field b of global a.
This function may receive optional options after the module name, where each option is a function to be applied over the module.
Loads the given module. The function starts by looking into the package.loaded table to determine whether modname is already loaded. If it is, then require returns the value stored at package.loaded[modname]. Otherwise, it tries to find a loader for the module.
To find a loader, first require queries package.preload[modname]. If it has a value, this value (which should be a function) is the loader. Otherwise require searches for a Lua loader using the path stored in package.path. If that also fails, it searches for a C loader using the path stored in package.cpath. If that also fails, it tries an all-in-one loader (see below).
When loading a C library, require first uses a dynamic link facility to link the application with the library. Then it tries to find a C function inside this library to be used as the loader. The name of this C function is the string "luaopen_" concatenated with a copy of the module name where each dot is replaced by an underscore. Moreover, if the module name has a hyphen, its prefix up to (and including) the first hyphen is removed. For instance, if the module name is a.v1-b.c, the function name will be luaopen_b_c.
If require finds neither a Lua library nor a C library for a module, it calls the all-in-one loader. This loader searches the C path for a library for the root name of the given module. For instance, when requiring a.b.c, it will search for a C library for a. If found, it looks into it for an open function for the submodule; in our example, that would be luaopen_a_b_c. With this facility, a package can pack several C submodules into one single library, with each submodule keeping its original open function.
Once a loader is found, require calls the loader with a single argument, modname. If the loader returns any value, require assigns the returned value to package.loaded[modname]. If the loader returns no value and has not assigned any value to package.loaded[modname], then require assigns true to this entry. In any case, require returns the final value of package.loaded[modname].
If there is any error loading or running the module, or if it cannot find any loader for the module, then require signals an error.
The path used by require to search for a C loader.
Lua initializes the C path package.cpath in the same way it initializes the Lua path package.path, using the environment variableLUA_CPATH (plus another default path defined in luaconf.h).
A table used by require to control which modules are already loaded. When you require a module modname and package.loaded[modname] is not false, require simply returns the value stored there.
package.loadlib (libname, funcname)
Dynamically links the host program with the C library libname. Inside this library, looks for a function funcname and returns this function as a C function. (So, funcname must follow the protocol (see lua_CFunction)).
This is a low-level function. It completely bypasses the package and module system. Unlike require, it does not perform any path searching and does not automatically adds extensions. libname must be the complete file name of the C library, including if necessary a path and extension. funcname must be the exact name exported by the C library (which may depend on the C compiler and linker used).
This function is not supported by ANSI C. As such, it is only available on some platforms (Windows, Linux, Mac OS X, Solaris, BSD, plus other Unix systems that support the dlfcn standard).
The path used by require to search for a Lua loader.
At start-up, Lua initializes this variable with the value of the environment variableLUA_PATH or with a default path defined in luaconf.h, if the environment variable is not defined. Any ";;" in the value of the environment variable is replaced by the default path.
A path is a sequence of templates separated by semicolons. For each template, require will change each interrogation mark in the template by filename, which is modname with each dot replaced by a "directory separator" (such as "/" in Unix); then it will try to load the resulting file name. So, for instance, if the Lua path is
? ? "./?.lua;./?.lc;/usr/local/?/init.lua"
the search for a Lua loader for module foo will try to load the files ./foo.lua, ./foo.lc, and /usr/local/foo/init.lua, in that order.
A table to store loaders for specific modules (see require).
Sets a metatable for module with its __index field referring to the global environment, so that this module inherits values from the global environment. To be used as an option to function module.
5.4 -String Manipulation
This library provides generic functions for string manipulation, such as finding and extracting substrings, and pattern matching. When indexing a string in Lua, the first character is at position 1 (not at 0, as in C). Indices are allowed to be negative and are interpreted as indexing backwards, from the end of the string. Thus, the last character is at position -1, and so on.
The string library provides all its functions inside the tablestring. It also sets a metatable for strings where the __index field points to the string table. Therefore, you can use the string functions in object-oriented style. For instance, string.byte(s, i) can be written as s:byte(i).
Returns the internal numerical codes of the characters s[i], s[i+1], ···, s[j]. The default value for i is 1; the default value for j is i.
Note that numerical codes are not necessarily portable across platforms.
Receives zero or more integers. Returns a string with length equal to the number of arguments, in which each character has the internal numerical code equal to its corresponding argument.
Note that numerical codes are not necessarily portable across platforms.
Returns a string containing a binary representation of the given function, so that a later loadstring on this string returns a copy of the function. function must be a Lua function without upvalues.
string.find (s, pattern [, init [, plain]])
Looks for the first match of pattern in the string s. If it finds a match, then find returns the indices of s where this occurrence starts and ends; otherwise, it returns nil. A third, optional numerical argument init specifies where to start the search; its default value is 1 and may be negative. A value of true as a fourth, optional argument plain turns off the pattern matching facilities, so the function does a plain "find substring" operation, with no characters in pattern being considered "magic". Note that if plain is given, then init must be given as well.
If the pattern has captures, then in a successful match the captured values are also returned, after the two indices.
string.format (formatstring, ···)
Returns a formatted version of its variable number of arguments following the description given in its first argument (which must be a string). The format string follows the same rules as the printf family of standard C functions. The only differences are that the options/modifiers *, l, L, n, p, and h are not supported and that there is an extra option, q. The q option formats a string in a form suitable to be safely read back by the Lua interpreter: the string is written between double quotes, and all double quotes, newlines, embedded zeros, and backslashes in the string are correctly escaped when written. For instance, the call
? ? string.format('%q', 'a string with "quotes" and \n new line')
will produce the string:
? ? "a string with \"quotes\" and \
? ? ? new line"
The options c, d, E, e, f, g, G, i, o, u, X, and x all expect a number as argument, whereas q and s expect a string.
This function does not accept string values containing embedded zeros.
Returns an iterator function that, each time it is called, returns the next captures from pattern over string s.
If pattern specifies no captures, then the whole match is produced in each call.
As an example, the following loop
? ? s = "hello world from Lua"
? ? for w in string.gmatch(s, "%a+") do
? ? ? print(w)
? ? end
will iterate over all the words from string s, printing one per line. The next example collects all pairs key=value from the given string into a table:
? ? t = {}
? ? s = "from=world, to=Lua"
? ? for k, v in string.gmatch(s, "(%w+)=(%w+)") do
? ? ? t[k] = v
? ? end
string.gsub (s, pattern, repl [, n])
Returns a copy of s in which all occurrences of the pattern have been replaced by a replacement string specified by repl, which may be a string, a table, or a function. gsub also returns, as its second value, the total number of substitutions made.
If repl is a string, then its value is used for replacement. The character % works as an escape character: any sequence in repl of the form %n, with n between 1 and 9, stands for the value of the n-th captured substring (see below). The sequence %0stands for the whole match. The sequence %% stands for a single %.
If repl is a table, then the table is queried for every match, using the first capture as the key; if the pattern specifies no captures, then the whole match is used as the key.
If repl is a function, then this function is called every time a match occurs, with all captured substrings passed as arguments, in order; if the pattern specifies no captures, then the whole match is passed as a sole argument.
If the value returned by the table query or by the function call is a string or a number, then it is used as the replacement string; otherwise, if it is false or nil, then there is no replacement (that is, the original match is kept in the string).
The optional last parameter n limits the maximum number of substitutions to occur. For instance, when n is 1 only the first occurrence of pattern is replaced.
Here are some examples:
? ? x = string.gsub("hello world", "(%w+)", "%1 %1")
? ? --> x="hello hello world world"
? ? x = string.gsub("hello world", "%w+", "%0 %0", 1)
? ? --> x="hello hello world"
? ? x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1")
? ? --> x="world hello Lua from"
? ? x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv)
? ? --> x="home = /home/roberto, user = roberto"
? ? x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s)
? ? ? ? ? return loadstring(s)()
? ? ? ? end)
? ? --> x="4+5 = 9"
? ? local t = {name="lua", version="5.1"}
? ? x = string.gsub("$name%-$version.tar.gz", "%$(%w+)", t)
? ? --> x="lua-5.1.tar.gz"
Receives a string and returns its length. The empty string "" has length 0. Embedded zeros are counted, so "a\000bc\000" has length 5.
Receives a string and returns a copy of this string with all uppercase letters changed to lowercase. All other characters are left unchanged. The definition of what an uppercase letter is depends on the current locale.
string.match (s, pattern [, init])
Looks for the first match of pattern in the string s. If it finds one, then match returns the captures from the pattern; otherwise it returns nil. If pattern specifies no captures, then the whole match is returned. A third, optional numerical argument initspecifies where to start the search; its default value is 1 and may be negative.
Returns a string that is the concatenation of n copies of the string s.
Returns a string that is the string s reversed.
Returns the substring of s that starts at i and continues until j; i and j may be negative. If j is absent, then it is assumed to be equal to -1 (which is the same as the string length). In particular, the call string.sub(s,1,j) returns a prefix of s with length j, and string.sub(s, -i) returns a suffix of s with length i.
Receives a string and returns a copy of this string with all lowercase letters changed to uppercase. All other characters are left unchanged. The definition of what a lowercase letter is depends on the current locale.
5.4.1 -Patterns
Character Class:
A character class is used to represent a set of characters. The following combinations are allowed in describing a character class:
[if !supportLists]· [endif]x: (where x is not one of the magic characters ^$()%.[]*+-?) represents the character x itself.
[if !supportLists]· [endif].: (a dot) represents all characters.
[if !supportLists]· [endif]%a: represents all letters.
[if !supportLists]· [endif]%c: represents all control characters.
[if !supportLists]· [endif]%d: represents all digits.
[if !supportLists]· [endif]%l: represents all lowercase letters.
[if !supportLists]· [endif]%p: represents all punctuation characters.
[if !supportLists]· [endif]%s: represents all space characters.
[if !supportLists]· [endif]%u: represents all uppercase letters.
[if !supportLists]· [endif]%w: represents all alphanumeric characters.
[if !supportLists]· [endif]%x: represents all hexadecimal digits.
[if !supportLists]· [endif]%z: represents the character with representation 0.
[if !supportLists]· [endif]%x: (where x is any non-alphanumeric character) represents the character x. This is the standard way to escape the magic characters. Any punctuation character (even the non magic) can be preceded by a '%' when used to represent itself in a pattern.
[if !supportLists]· [endif][set]: represents the class which is the union of all characters in set. A range of characters may be specified by separating the end characters of the range with a '-'. All classes %x described above may also be used as components in set. All other characters in set represent themselves. For example, [%w_] (or [_%w]) represents all alphanumeric characters plus the underscore, [0-7] represents the octal digits, and [0-7%l%-] represents the octal digits plus the lowercase letters plus the '-' character.
The interaction between ranges and classes is not defined. Therefore, patterns like [%a-z] or [a-%%] have no meaning.
[if !supportLists]· [endif]
[if !supportLists]· [endif][^set]: represents the complement of set, where set is interpreted as above.
For all classes represented by single letters (%a, %c, etc.), the corresponding uppercase letter represents the complement of the class. For instance, %S represents all non-space characters.
The definitions of letter, space, and other character groups depend on the current locale. In particular, the class [a-z] may not be equivalent to %l.
Pattern Item:
A pattern item may be
[if !supportLists]· [endif]a single character class, which matches any single character in the class;
[if !supportLists]· [endif]a single character class followed by '*', which matches 0 or more repetitions of characters in the class. These repetition items will always match the longest possible sequence;
[if !supportLists]· [endif]a single character class followed by '+', which matches 1 or more repetitions of characters in the class. These repetition items will always match the longest possible sequence;
[if !supportLists]· [endif]a single character class followed by '-', which also matches 0 or more repetitions of characters in the class. Unlike '*', these repetition items will always match the shortest possible sequence;
[if !supportLists]· [endif]a single character class followed by '?', which matches 0 or 1 occurrence of a character in the class;
[if !supportLists]· [endif]%n, for n between 1 and 9; such item matches a substring equal to the n-th captured string (see below);
[if !supportLists]· [endif]%bxy, where x and y are two distinct characters; such item matches strings that start with x, end with y, and where the x and y are balanced. This means that, if one reads the string from left to right, counting +1 for an x and -1 for a y, the ending y is the first y where the count reaches 0. For instance, the item %b() matches expressions with balanced parentheses.
Pattern:
A pattern is a sequence of pattern items. A '^' at the beginning of a pattern anchors the match at the beginning of the subject string. A '$' at the end of a pattern anchors the match at the end of the subject string. At other positions, '^' and '$' have no special meaning and represent themselves.
Captures:
A pattern may contain sub-patterns enclosed in parentheses; they describe captures. When a match succeeds, the substrings of the subject string that match captures are stored (captured) for future use. Captures are numbered according to their left parentheses. For instance, in the pattern "(a*(.)%w(%s*))", the part of the string matching "a*(.)%w(%s*)" is stored as the first capture (and therefore has number 1); the character matching "." is captured with number 2, and the part matching "%s*" has number 3.
As a special case, the empty capture () captures the current string position (a number). For instance, if we apply the pattern "()aa()" on the string "flaaap", there will be two captures: 3 and 5.
A pattern cannot contain embedded zeros. Use %z instead.
5.5 -Table Manipulation
This library provides generic functions for table manipulation. It provides all its functions inside the tabletable.
Most functions in the table library assume that the table represents an array or a list. For these functions, when we talk about the "length" of a table we mean the result of the length operator.
table.concat (table [, sep [, i [, j]]])
Given an array where all elements are strings or numbers, returns table[i]..sep..table[i+1] ··· sep..table[j]. The default value for sep is the empty string, the default for i is 1, and the default for j is the length of the table. If i is greater than j, returns the empty string.
table.insert (table, [pos,] value)
Inserts element value at position pos in table, shifting up other elements to open space, if necessary. The default value for pos is n+1, where n is the length of the table (see §2.5.5), so that a call table.insert(t,x) inserts x at the end of table t.
Returns the largest positive numerical index of the given table, or zero if the table has no positive numerical indices. (To do its job this function does a linear traversal of the whole table.)
Removes from table the element at position pos, shifting down other elements to close the space, if necessary. Returns the value of the removed element. The default value for pos is n, where n is the length of the table, so that a call table.remove(t)removes the last element of table t.
Sorts table elements in a given order, in-place, from table[1] to table[n], where n is the length of the table. If comp is given, then it must be a function that receives two table elements, and returns true when the first is less than the second (so that not comp(a[i+1],a[i]) will be true after the sort). If comp is not given, then the standard Lua operator < is used instead.
The sort algorithm is not stable; that is, elements considered equal by the given order may have their relative positions changed by the sort.
This library is an interface to the standard C math library. It provides all its functions inside the tablemath.
Returns the absolute value of x.
Returns the arc cosine of x (in radians).
Returns the arc sine of x (in radians).
Returns the arc tangent of x (in radians).
Returns the arc tangent of x/y (in radians), but uses the signs of both parameters to find the quadrant of the result. (It also handles correctly the case of y being zero.)
Returns the smallest integer larger than or equal to x.
Returns the cosine of x (assumed to be in radians).
Returns the hyperbolic cosine of x.
Returns the angle x (given in radians) in degrees.
Returns the the value ex.
Returns the largest integer smaller than or equal to x.
Returns the remainder of the division of x by y.
Returns m and e such that x = m2e, e is an integer and the absolute value of m is in the range [0.5, 1) (or zero when x is zero).
The value HUGE_VAL, a value larger than or equal to any other numerical value.
Returns m2e (e should be an integer).
Returns the natural logarithm of x.
Returns the base-10 logarithm of x.
Returns the maximum value among its arguments.
Returns the minimum value among its arguments.
Returns two numbers, the integral part of x and the fractional part of x.
The value of pi.
Returns xy. (You can also use the expression x^y to compute this value.)
Returns the angle x (given in degrees) in radians.
This function is an interface to the simple pseudo-random generator function rand provided by ANSI C. (No guarantees can be given for its statistical properties.)
When called without arguments, returns a pseudo-random real number in the range [0,1). When called with a number m, math.random returns a pseudo-random integer in the range [1, m]. When called with two numbers m and n, math.random returns a pseudo-random integer in the range [m, n].
Sets x as the "seed" for the pseudo-random generator: equal seeds produce equal sequences of numbers.
Returns the sine of x (assumed to be in radians).
Returns the hyperbolic sine of x.
Returns the square root of x. (You can also use the expression x^0.5 to compute this value.)
Returns the tangent of x (assumed to be in radians).
Returns the hyperbolic tangent of x.
5.7 -Input and Output Facilities
The I/O library provides two different styles for file manipulation. The first one uses implicit file descriptors; that is, there are operations to set a default input file and a default output file, and all input/output operations are over these default files. The second style uses explicit file descriptors.
When using implicit file descriptors, all operations are supplied by tableio. When using explicit file descriptors, the operation io.open returns a file descriptor and then all operations are supplied as methods of the file descriptor.
The table ioalso provides three predefined file descriptors with their usual meanings from C:io.stdin,io.stdout, andio.stderr.
Unless otherwise stated, all I/O functions return nil on failure (plus an error message as a second result) and some value different from nil on success.
Equivalent to file:close(). Without a file, closes the default output file.
Equivalent to file:flush over the default output file.
When called with a file name, it opens the named file (in text mode), and sets its handle as the default input file. When called with a file handle, it simply sets this file handle as the default input file. When called without parameters, it returns the current default input file.
In case of errors this function raises the error, instead of returning an error code.
Opens the given file name in read mode and returns an iterator function that, each time it is called, returns a new line from the file. Therefore, the construction
? ? for line in io.lines(filename) do body end
will iterate over all lines of the file. When the iterator function detects the end of file, it returns nil (to finish the loop) and automatically closes the file.
The call io.lines() (with no file name) is equivalent to io.input():lines(); that is, it iterates over the lines of the default input file. In this case it does not close the file when the loop ends.
This function opens a file, in the mode specified in the string mode. It returns a new file handle, or, in case of errors, nil plus an error message.
The mode string can be any of the following:
[if !supportLists]· [endif]"r": read mode (the default);
[if !supportLists]· [endif]"w": write mode;
[if !supportLists]· [endif]"a": append mode;
[if !supportLists]· [endif]"r+": update mode, all previous data is preserved;
[if !supportLists]· [endif]"w+": update mode, all previous data is erased;
[if !supportLists]· [endif]"a+": append update mode, previous data is preserved, writing is only allowed at the end of file.
The mode string may also have a 'b' at the end, which is needed in some systems to open the file in binary mode. This string is exactly what is used in the standard C function fopen.
Similar to io.input, but operates over the default output file.
Starts program prog in a separated process and returns a file handle that you can use to read data from this program (if mode is "r", the default) or to write data to this program (if mode is "w").
This function is system dependent and is not available on all platforms.
Equivalent to io.input():read.
Returns a handle for a temporary file. This file is opened in update mode and it is automatically removed when the program ends.
Checks whether obj is a valid file handle. Returns the string "file" if obj is an open file handle, "closed file" if obj is a closed file handle, or nil if obj is not a file handle.
Equivalent to io.output():write.
Closes file. Note that files are automatically closed when their handles are garbage collected, but that takes an unpredictable amount of time to happen.
Saves any written data to file.
Returns an iterator function that, each time it is called, returns a new line from the file. Therefore, the construction
? ? for line in file:lines() do body end
will iterate over all lines of the file. (Unlike io.lines, this function does not close the file when the loop ends.)
Reads the file file, according to the given formats, which specify what to read. For each format, the function returns a string (or a number) with the characters read, or nil if it cannot read data with the specified format. When called without formats, it uses a default format that reads the entire next line (see below).
The available formats are
[if !supportLists]· [endif]"*n": reads a number; this is the only format that returns a number instead of a string.
[if !supportLists]· [endif]"*a": reads the whole file, starting at the current position. On end of file, it returns the empty string.
[if !supportLists]· [endif]"*l": reads the next line (skipping the end of line), returning nil on end of file. This is the default format.
[if !supportLists]· [endif]number: reads a string with up to this number of characters, returning nil on end of file. If number is zero, it reads nothing and returns an empty string, or nil on end of file.
file:seek ([whence] [, offset])
Sets and gets the file position, measured from the beginning of the file, to the position given by offset plus a base specified by the string whence, as follows:
[if !supportLists]· [endif]"set": base is position 0 (beginning of the file);
[if !supportLists]· [endif]"cur": base is current position;
[if !supportLists]· [endif]"end": base is end of file;
In case of success, function seek returns the final file position, measured in bytes from the beginning of the file. If this function fails, it returns nil, plus a string describing the error.
The default value for whence is "cur", and for offset is 0. Therefore, the call file:seek() returns the current file position, without changing it; the call file:seek("set") sets the position to the beginning of the file (and returns 0); and the call file:seek("end")sets the position to the end of the file, and returns its size.
Sets the buffering mode for an output file. There are three available modes:
[if !supportLists]· [endif]"no": no buffering; the result of any output operation appears immediately.
[if !supportLists]· [endif]"full": full buffering; output operation is performed only when the buffer is full (or when you explicitly flush the file (see io.flush)).
[if !supportLists]· [endif]"line": line buffering; output is buffered until a newline is output or there is any input from some special files (such as a terminal device).
For the last two cases, sizes specifies the size of the buffer, in bytes. The default is an appropriate size.
Writes the value of each of its arguments to the file. The arguments must be strings or numbers. To write other values, use tostring or string.format before write.
5.8 -Operating System Facilities
This library is implemented through tableos.
Returns an approximation of the amount in seconds of CPU time used by the program.
Returns a string or a table containing date and time, formatted according to the given string format.
If the time argument is present, this is the time to be formatted (see the os.time function for a description of this value). Otherwise, date formats the current time.
If format starts with '!', then the date is formatted in Coordinated Universal Time. After this optional character, if format is the string "*t", then date returns a table with the following fields: year (four digits), month (1--12), day (1--31), hour (0--23), min (0--59), sec (0--61), wday (weekday, Sunday is 1), yday (day of the year), and isdst (daylight saving flag, a boolean).
If format is not "*t", then date returns the date as a string, formatted according to the same rules as the C function strftime.
When called without arguments, date returns a reasonable date and time representation that depends on the host system and on the current locale (that is, os.date() is equivalent to os.date("%c")).
Returns the number of seconds from time t1 to time t2. In POSIX, Windows, and some other systems, this value is exactly t2-t1.
This function is equivalent to the C function system. It passes command to be executed by an operating system shell. It returns a status code, which is system-dependent. If command is absent, then it returns nonzero if a shell is available and zero otherwise.
Calls the C function exit, with an optional code, to terminate the host program. The default value for code is the success code.
Returns the value of the process environment variable varname, or nil if the variable is not defined.
Deletes the file or directory with the given name. Directories must be empty to be removed. If this function fails, it returns nil, plus a string describing the error.
Renames file or directory named oldname to newname. If this function fails, it returns nil, plus a string describing the error.
os.setlocale (locale [, category])
Sets the current locale of the program. locale is a string specifying a locale; category is an optional string describing which category to change: "all", "collate", "ctype", "monetary", "numeric", or "time"; the default category is "all". The function returns the name of the new locale, or nil if the request cannot be honored.
When called with nil as the first argument, this function only returns the name of the current locale for the given category.
Returns the current time when called without arguments, or a time representing the date and time specified by the given table. This table must have fields year, month, and day, and may have fields hour, min, sec, and isdst (for a description of these fields, see the os.date function).
The returned value is a number, whose meaning depends on your system. In POSIX, Windows, and some other systems, this number counts the number of seconds since some given start time (the "epoch"). In other systems, the meaning is not specified, and the number returned by time can be used only as an argument to date and difftime.
Returns a string with a file name that can be used for a temporary file. The file must be explicitly opened before its use and explicitly removed when no longer needed.
5.9 -The Debug Library
This library provides the functionality of the debug interface to Lua programs. You should exert care when using this library. The functions provided here should be used exclusively for debugging and similar tasks, such as profiling. Please resist the temptation to use them as a usual programming tool: they can be very slow. Moreover, several of its functions violate some assumptions about Lua code (e.g., that variables local to a function cannot be accessed from outside or that userdata metatables cannot be changed by Lua code) and therefore can compromise otherwise secure code.
All functions in this library are provided inside thedebug table. All functions that operate over a thread have an optional first argument which is the thread to operate over. The default is always the current thread.
Enters an interactive mode with the user, running each string that the user enters. Using simple commands and other debug facilities, the user can inspect global and local variables, change their values, evaluate expressions, and so on. A line containing only the word cont finishes this function, so that the caller continues its execution.
Note that commands for debug.debug are not lexically nested within any function, and so have no direct access to local variables.
Returns the environment of object o.
Returns the current hook settings of the thread, as three values: the current hook function, the current hook mask, and the current hook count (as set by the debug.sethook function).
debug.getinfo ([thread,] function [, what])
Returns a table with information about a function. You can give the function directly, or you can give a number as the value of function, which means the function running at level function of the call stack of the given thread: level 0 is the current function (getinfo itself); level 1 is the function that called getinfo; and so on. If function is a number larger than the number of active functions, then getinfo returns nil.
The returned table may contain all the fields returned by lua_getinfo, with the string what describing which fields to fill in. The default for what is to get all information available, except the table of valid lines. If present, the option 'f' adds a field named func with the function itself. If present, the option 'L' adds a field named activelines with the table of valid lines.
For instance, the expression debug.getinfo(1,"n").name returns a name of the current function, if a reasonable name can be found, and the expression debug.getinfo(print) returns a table with all available information about the print function.
debug.getlocal ([thread,] level, local)
This function returns the name and the value of the local variable with index local of the function at level level of the stack. (The first parameter or local variable has index 1, and so on, until the last active local variable.) The function returns nil if there is no local variable with the given index, and raises an error when called with a level out of range. (You can call debug.getinfo to check whether the level is valid.)
Variable names starting with '(' (open parentheses) represent internal variables (loop control variables, temporaries, and C function locals).
Returns the metatable of the given object or nil if it does not have a metatable.
Returns the registry table (see §3.5).
This function returns the name and the value of the upvalue with index up of the function func. The function returns nil if there is no upvalue with the given index.
Sets the environment of the given object to the given table. Returns object.
debug.sethook ([thread,] hook, mask [, count])
Sets the given function as a hook. The string mask and the number count describe when the hook will be called. The string mask may have the following characters, with the given meaning:
[if !supportLists]· [endif]"c": The hook is called every time Lua calls a function;
[if !supportLists]· [endif]"r": The hook is called every time Lua returns from a function;
[if !supportLists]· [endif]"l": The hook is called every time Lua enters a new line of code.
With a count different from zero, the hook is called after every count instructions.
When called without arguments, debug.sethook turns off the hook.
When the hook is called, its first parameter is a string describing the event that has triggered its call: "call", "return" (or "tail return"), "line", and "count". For line events, the hook also gets the new line number as its second parameter. Inside a hook, you can call getinfo with level 2 to get more information about the running function (level 0 is the getinfo function, and level 1 is the hook function), unless the event is "tail return". In this case, Lua is only simulating the return, and a call to getinfo will return invalid data.
debug.setlocal ([thread,] level, local, value)
This function assigns the value value to the local variable with index local of the function at level level of the stack. The function returns nil if there is no local variable with the given index, and raises an error when called with a level out of range. (You can call getinfo to check whether the level is valid.) Otherwise, it returns the name of the local variable.
debug.setmetatable (object, table)
Sets the metatable for the given object to the given table (which can be nil).
debug.setupvalue (func, up, value)
This function assigns the value value to the upvalue with index up of the function func. The function returns nil if there is no upvalue with the given index. Otherwise, it returns the name of the upvalue.
debug.traceback ([thread,] [message] [, level])
Returns a string with a traceback of the call stack. An optional message string is appended at the beginning of the traceback. An optional level number tells at which level to start the traceback (default is 1, the function calling traceback).
Although Lua has been designed as an extension language, to be embedded in a host C program, it is also frequently used as a stand-alone language. An interpreter for Lua as a stand-alone language, called simply lua, is provided with the standard distribution. The stand-alone interpreter includes all standard libraries, including the debug library. Its usage is:
? ? lua [options] [script [args]]
The options are:
[if !supportLists]· [endif]-e stat: executes string stat;
[if !supportLists]· [endif]-l mod: "requires" mod;
[if !supportLists]· [endif]-i: enters interactive mode after running script;
[if !supportLists]· [endif]-v: prints version information;
[if !supportLists]· [endif]--: stops handling options;
[if !supportLists]· [endif]-: executes stdin as a file and stops handling options.
After handling its options, lua runs the given script, passing to it the given args as string arguments. When called without arguments, lua behaves as lua -v -i when the standard input (stdin) is a terminal, and as lua - otherwise.
Before running any argument, the interpreter checks for an environment variableLUA_INIT. If its format is @filename, then lua executes the file. Otherwise, lua executes the string itself.
All options are handled in order, except -i. For instance, an invocation like
? ? $ lua -e'a=1' -e 'print(a)' script.lua
will first set a to 1, then print the value of a (which is '1'), and finally run the file script.lua with no arguments. (Here $ is the shell prompt. Your prompt may be different.)
Before starting to run the script, lua collects all arguments in the command line in a global table called arg. The script name is stored at index 0, the first argument after the script name goes to index 1, and so on. Any arguments before the script name (that is, the interpreter name plus the options) go to negative indices. For instance, in the call
? ? $ lua -la b.lua t1 t2
the interpreter first runs the file a.lua, then creates a table
? ? arg = { [-2] = "lua", [-1] = "-la",
? ? ? ? ? ? [0] = "b.lua",
? ? ? ? ? ? [1] = "t1", [2] = "t2" }
and finally runs the file b.lua. The script is called with arg[1], arg[2], ··· as arguments; it can also access these arguments with the vararg expression '...'.
In interactive mode, if you write an incomplete statement, the interpreter waits for its completion by issuing a different prompt.
If the global variable_PROMPTcontains a string, then its value is used as the prompt. Similarly, if the global variable_PROMPT2 contains a string, its value is used as the secondary prompt (issued during incomplete statements). Therefore, both prompts can be changed directly on the command line. For instance,
? ? $ lua -e"_PROMPT='myprompt> '" -i
(the outer pair of quotes is for the shell, the inner pair is for Lua), or in any Lua programs by assigning to _PROMPT. Note the use of -i to enter interactive mode; otherwise, the program would just end silently right after the assignment to _PROMPT.
To allow the use of Lua as a script interpreter in Unix systems, the stand-alone interpreter skips the first line of a chunk if it starts with #. Therefore, Lua scripts can be made into executable programs by using chmod +x and the #! form, as in
? ? #!/usr/local/bin/lua
(Of course, the location of the Lua interpreter may be different in your machine. If lua is in your PATH, then
? ? #!/usr/bin/env lua
is a more portable solution.)
7 -Incompatibilities with the Previous Version
Here we list the incompatibilities that you may found when moving a program from Lua 5.0 to Lua 5.1. You can avoid most of the incompatibilities compiling Lua with appropriate options (see file luaconf.h). However, all these compatibility options will be removed in the next version of Lua.
[if !supportLists]· [endif]The vararg system changed from the pseudo-argument arg with a table with the extra arguments to the vararg expression. (See compile-time option LUA_COMPAT_VARARG in luaconf.h.)
[if !supportLists]· [endif]There was a subtle change in the scope of the implicit variables of the for statement and for the repeat statement.
[if !supportLists]· [endif]The long string/long comment syntax ([[string]]) does not allow nesting. You can use the new syntax ([=[string]=]) in these cases. (See compile-time option LUA_COMPAT_LSTR in luaconf.h.)
[if !supportLists]· [endif]Function string.gfind was renamed string.gmatch. (See compile-time option LUA_COMPAT_GFIND in luaconf.h.)
[if !supportLists]· [endif]When string.gsub is called with a function as its third argument, whenever this function returns nil or false the replacement string is the whole match, instead of the empty string.
[if !supportLists]· [endif]Function table.setn was deprecated. Function table.getn corresponds to the new length operator (#); use the operator instead of the function. (See compile-time option LUA_COMPAT_GETN in luaconf.h.)
[if !supportLists]· [endif]Function loadlib was renamed package.loadlib. (See compile-time option LUA_COMPAT_LOADLIB in luaconf.h.)
[if !supportLists]· [endif]Function math.mod was renamed math.fmod. (See compile-time option LUA_COMPAT_MOD in luaconf.h.)
[if !supportLists]· [endif]Functions table.foreach and table.foreachi are deprecated. You can use a for loop with pairs or ipairs instead.
[if !supportLists]· [endif]There were substantial changes in function require due to the new module system. However, the new behavior is mostly compatible with the old, but require gets the path from package.path instead of from LUA_PATH.
[if !supportLists]· [endif]Function collectgarbage has different arguments. Function gcinfo is deprecated; use collectgarbage("count") instead.
7.3 -Changes in the API
[if !supportLists]· [endif]The luaopen_* functions (to open libraries) cannot be called directly, like a regular C function. They must be called through Lua, like a Lua function.
[if !supportLists]· [endif]Function lua_open was replaced by lua_newstate to allow the user to set a memory-allocation function. You can use luaL_newstate from the standard library to create a state with a standard allocation function (based on realloc).
[if !supportLists]· [endif]Functions luaL_getn and luaL_setn (from the auxiliary library) are deprecated. Use lua_objlen instead of luaL_getn and nothing instead of luaL_setn.
[if !supportLists]· [endif]Function luaL_openlib was replaced by luaL_register.
[if !supportLists]· [endif]Function luaL_checkudata now throws an error when the given value is not a userdata of the expected type. (In Lua 5.0 it returned NULL.)
Here is the complete syntax of Lua in extended BNF. (It does not describe operator precedences.)
chunk ::= {stat [`;′]} [laststat [`;′]]
block ::= chunk
stat ::=? varlist1 `=′ explist1 |
functioncall |
do block end |
while exp do block end |
repeat block until exp |
if exp then block {elseif exp then block} [else block] end |
for Name `=′ exp `,′ exp [`,′ exp] do block end |
for namelist in explist1 do block end |
function funcname funcbody |
local function Name funcbody |
local namelist [`=′ explist1]
laststat ::= return [explist1] | break
funcname ::= Name {`.′ Name} [`:′ Name]
varlist1 ::= var {`,′ var}
var ::=? Name | prefixexp `[′ exp `]′ | prefixexp `.′ Name
namelist ::= Name {`,′ Name}
explist1 ::= {exp `,′} exp
exp ::=? nil | false | true | Number | String | `...′ | function |
prefixexp | tableconstructor | exp binop exp | unop exp
prefixexp ::= var | functioncall | `(′ exp `)′
functioncall ::=? prefixexp args | prefixexp `:′ Name args
args ::=? `(′ [explist1] `)′ | tableconstructor | String
function ::= function funcbody
funcbody ::= `(′ [parlist1] `)′ block end
parlist1 ::= namelist [`,′ `...′] | `...′
tableconstructor ::= `{′ [fieldlist] `}′
fieldlist ::= field {fieldsep field} [fieldsep]
field ::= `[′ exp `]′ `=′ exp | Name `=′ exp | exp
fieldsep ::= `,′ | `;′
binop ::= `+′ | `-′ | `*′ | `/′ | `^′ | `%′ | `..′ |
`<′ | `<=′ | `>′ | `>=′ | `==′ | `~=′ |
and | or
unop ::= `-′ | not | `#′
Last update: Tue Oct 3 21:27:28 BRT 2006 譯文
