13.1 基本库 (Basic Library)

13.1 基本库 (Basic Library)

Lua基本库 (Basic Library) 详解与实践指南

Lua 的强大之处不仅在于其简洁高效的语言核心，还在于其丰富的标准库 (Standard Libraries)。标准库为 Lua 提供了各种常用的功能，极大地扩展了语言的能力，让开发者能够高效地完成各种任务。 在标准库这座宝库中，基本库 (Basic Library) 是最核心、也是最基础的部分。它包含了 Lua 语言最基本、最常用的函数，是所有 Lua 程序的基础。

1. 基本库概述

Lua 的基本库，也称为 base 库，默认情况下在 Lua 解释器启动时自动加载。这意味着你无需显式地 require 即可直接使用基本库中的所有函数。这些函数构成了 Lua 语言的核心功能，涵盖了：

• 核心函数: 例如 print, type, error, assert 等，用于基本的输入输出、类型检查、错误处理等。

• 数据类型操作: 例如 tonumber, tostring，用于类型转换。

• 迭代器: 例如 pairs, ipairs，用于遍历表 (table)。

• 环境和执行: 例如 loadstring, dofile, require, module, pcall, xpcall, collectgarbage，用于代码加载、模块管理、错误捕获、垃圾回收等。

• 元表操作: 例如 getmetatable, setmetatable，用于访问和修改对象的元表。

• 其他工具函数: 例如 next, select, unpack, _VERSION 等，提供各种实用功能。

基本库中的函数通常以全局函数的形式存在，可以直接在任何 Lua 代码中使用。 它们被设计得非常精简和高效，是构建更复杂 Lua 程序的基础模块。

2. 基本库函数详解与代码实践

接下来，我们将逐一深入探讨基本库中的关键函数，并通过代码示例来演示它们的用法和应用场景。

2.1 核心函数

• print (...): 最常用的输出函数，将参数转换为字符串并输出到标准输出。可以接受任意数量的参数，并用制表符分隔输出。

  print("Hello", "Lua!")       -- 输出: Hello	Lua!
  print(10, 20, 30)         -- 输出: 10	20	30
  print(true, nil)          -- 输出: true	nil
  print()                    -- 输出: (空行)
  ​

• type (v): 返回参数 v 的类型名称，以字符串形式返回。可能的返回值包括 "nil", "number", "string", "boolean", "table", "function", "thread", "userdata"。

  print(type(10))             -- 输出: number
  print(type("hello"))         -- 输出: string
  print(type(true))           -- 输出: boolean
  print(type(nil))            -- 输出: nil
  print(type({}))             -- 输出: table
  print(type(function() end)) -- 输出: function
  ​

• error (message [, level]): 引发一个错误。message 参数是错误消息，level 参数（可选）指定错误报告级别。level 为 1 (默认) 指示错误发生在 error 函数被调用的位置；level 为 2 指示错误发生在调用 error 函数的函数的函数的位置，依此类推。 error 函数通常用于在程序遇到不可恢复的错误时终止执行。

  function divide(a, b)
      if b == 0 then
          error("除数不能为零！")  -- 引发错误
      end
      return a / b
  end
  divide(10, 0)  -- 运行时会报错，并显示 "除数不能为零！"
  ​

• assert (v [, message]): 用于断言。如果 v 的值为真 (true 或非 nil)，则 assert 函数不做任何事情，直接返回 v。如果 v 的值为假 (nil 或 false)，则 assert 函数引发一个错误，错误消息为 message 参数（如果提供）。 assert 常用于在开发和调试阶段检查程序中的条件是否满足预期。

  local age = 25
  assert(age >= 18, "未成年人禁止入内") -- 断言年龄必须大于等于 18，否则报错
  local name = "Alice"
  assert(name ~= nil)  -- 断言 name 不为 nil，正常执行
  ​

• getmetatable (object): 返回给定 object 的元表。如果 object 没有元表，则返回 nil。 只能获取 Lua 设置的元表。无法获取 C 代码或其他方式设置的元表。

  local myTable = {}
  local meta = { __index = { value = 10 } }
  setmetatable(myTable, meta)
  print(getmetatable(myTable) == meta) -- 输出: true
  print(getmetatable(10))            -- 输出: nil (number 类型没有默认元表)
  ​

• setmetatable (table, metatable): 为给定的 table 设置元表。如果 metatable 为 nil，则移除 table 的元表。如果原表有 __metatable 字段，则不能设置元表，会引发错误。

  local myTable = {}
  local meta = { __index = { value = 20 } }
  setmetatable(myTable, meta)
  print(getmetatable(myTable) == meta) -- 输出: true
  setmetatable(myTable, nil)
  print(getmetatable(myTable) == nil)  -- 输出: true
  ​

2.2 数据类型操作函数

• tonumber (e [, base]): 尝试将参数 e 转换为数字。如果 e 已经是数字，则直接返回 e。如果 e 是可以转换为数字的字符串，则将其转换为数字并返回。可选参数 base 指定转换的进制，默认为 10。如果转换失败，则返回 nil。

  print(tonumber("123"))      -- 输出: 123
  print(tonumber("3.14"))     -- 输出: 3.14
  print(tonumber("0xFF", 16)) -- 输出: 255 (十六进制)
  print(tonumber("abc"))      -- 输出: nil (无法转换为数字)
  print(tonumber(10))         -- 输出: 10 (已经是数字)
  ​

• tostring (v): 将参数 v 转换为字符串。对于数字、字符串、布尔值，会返回其字符串表示。对于表、函数、userdata 等类型，会返回类型名称和内存地址的字符串表示。 如果 v 有 __tostring 元方法，则会调用该元方法进行转换。

  print(tostring(123))      -- 输出: 123
  print(tostring("hello"))    -- 输出: hello
  print(tostring(true))     -- 输出: true
  print(tostring({}))       -- 输出: table: 0x... (内存地址)
  print(tostring(function() end)) -- 输出: function: 0x... (内存地址)
  local myTable = { value = 42, __tostring = function(self) return "My Table: " .. self.value end }
  print(tostring(myTable))  -- 输出: My Table: 42 (调用了 __tostring 元方法)
  ​

2.3 迭代器函数

• pairs (t): 返回三个值：next 函数、表 t 本身、以及 nil。 用于迭代表 t 的所有键值对。 迭代顺序是不确定的，不保证按照任何特定顺序遍历表中的元素。

  local myTable = { a = 10, b = 20, c = 30 }
  for key, value in pairs(myTable) do
      print(key, value)
  end
  -- 可能输出 (顺序不确定):
  -- a	10
  -- b	20
  -- c	30
  ​

• ipairs (t): 返回三个值：next 函数、表 t 本身、以及 0。 用于迭代表 t 的数值索引键值对。 从索引 1 开始，直到遇到第一个索引值为空 (nil) 的元素为止。 ipairs 保证按照数值索引顺序遍历。

  local myArray = { "apple", "banana", "orange", [5] = "grape" }
  for index, value in ipairs(myArray) do
      print(index, value)
  end
  -- 输出:
  -- 1	apple
  -- 2	banana
  -- 3	orange
  -- (注意：索引 5 的 "grape" 没有被 ipairs 遍历到，因为 ipairs 只遍历数值索引连续的部分)
  ​

2.4 环境和执行函数

• loadstring (chunk [, chunkname]): 加载一段字符串形式的 Lua 代码块 (chunk)。如果加载成功，返回一个函数，调用该函数即可执行代码块。如果加载失败，返回 nil 和错误消息。 chunkname 参数（可选）用于指定代码块的名称，用于错误信息和调试。

  local codeString = "print('Hello from loadstring!')"
  local loadResult, func = loadstring(codeString)
  if loadResult then
      func()  -- 执行加载的代码，输出: Hello from loadstring!
  else
      print("加载代码失败:", func) -- func 此时是错误消息
  end
  ​

• dofile ([filename]): 打开指定文件并将其内容作为 Lua 代码块执行。 如果没有提供 filename，则 dofile 执行当前 Lua 文件。 如果执行成功，返回代码块的返回值（如果有）；如果执行失败，返回 nil 和错误消息。 dofile 每次调用都会重新加载并执行文件内容。

  假设有一个文件 my_script.lua 内容如下:

  print("Executing my_script.lua")
  return 100
  ​

  在另一个 Lua 文件中:

  local result = dofile("my_script.lua") -- 执行 my_script.lua, 输出: Executing my_script.lua
  print("dofile result:", result)        -- 输出: dofile result: 100
  ​

• require (modname): 加载并运行指定的模块 modname。 require 函数是 Lua 模块化编程的核心。它会查找、加载和缓存模块，确保同一个模块只被加载一次。 require 返回模块的返回值（通常是一个表，表示模块导出的内容）。 模块搜索路径可以通过 package.path 配置。

  假设有一个模块文件 my_module.lua 内容如下:

  local M = {}
  M.greet = function(name)
      print("Hello, " .. name .. " from my_module!")
  end
  return M
  ​

  在另一个 Lua 文件中:

  local myModule = require("my_module") -- 加载模块
  myModule.greet("World")             -- 调用模块中的函数，输出: Hello, World from my_module!
  ​

• module (modname [, ...]) (Lua 5.1 引入，Lua 5.2+ 已废弃，推荐使用 _ENV 或 package.loaded 手动管理模块): 在 Lua 5.1 中用于创建模块。它会创建一个表作为模块，并将模块名绑定到全局环境 package.loaded 和 _M 变量。 在 Lua 5.2 及更高版本中，module 函数已被废弃，推荐使用 _ENV 或 package.loaded 手动管理模块的作用域和加载。 在现代 Lua 开发中，应避免使用 module 函数，并采用更灵活的模块管理方式。

• pcall (f, arg1, arg2, ...) (protected call): 以保护模式调用函数 f。 pcall 会捕获函数 f 执行过程中发生的任何错误，并返回一个状态码和一个结果。 如果函数 f 执行成功且没有错误，pcall 返回 true 和函数 f 的返回值。 如果函数 f 执行过程中发生错误，pcall 返回 false 和错误消息。

  function riskyFunction(x)
      if x < 0 then
          error("输入不能为负数")
      end
      return math.sqrt(x)
  end
  local status, result = pcall(riskyFunction, 16)
  if status then
      print("计算结果:", result)   -- 输出: 计算结果: 4
  else
      print("发生错误:", result)   -- 不会执行到这里
  end
  status, result = pcall(riskyFunction, -1)
  if status then
      print("计算结果:", result)   -- 不会执行到这里
  else
      print("发生错误:", result)   -- 输出: 发生错误: 输入不能为负数
  end
  ​

• xpcall (f, errh, arg1, arg2, ...) (extended protected call): 类似于 pcall，以保护模式调用函数 f。 xpcall 增加了第二个参数 errh，用于指定错误处理函数 (error handler)。 当函数 f 内部发生错误时，xpcall 会调用 errh 函数，并将错误对象作为参数传递给 errh。 errh 函数的返回值将作为 xpcall 的第二个返回值返回 (代替默认的错误消息)。 xpcall 允许自定义错误处理逻辑，例如记录更详细的错误信息、进行错误恢复等。

  function myErrorHandler(err)
      print("自定义错误处理函数被调用:", err)
      return "Custom Error Message: " .. err
  end
  function riskyFunction()
      error("Something went wrong!")
  end
  local status, result = xpcall(riskyFunction, myErrorHandler)
  if status then
      print("执行成功，结果:", result) -- 不会执行到这里
  else
      print("xpcall 返回状态:", status) -- 输出: xpcall 返回状态: false
      print("自定义错误消息:", result) -- 输出: 自定义错误消息: Custom Error Message: Something went wrong!
      -- 同时会输出 "自定义错误处理函数被调用: Something went wrong!" (由 myErrorHandler 函数内的 print 输出)
  end
  ​

• collectgarbage ([opt [, arg]]): 垃圾回收器函数。用于控制 Lua 的垃圾回收机制。 可选参数 opt 指定垃圾回收操作类型，可选值包括:

  • "collect": 执行一次完整的垃圾回收周期。

  • "count": 返回 Lua 使用的总内存量 (KB)。

  • "restart": 重启垃圾回收器。

  • "setpause": 设置垃圾回收器的暂停率 (pause rate)，arg 参数为新的暂停率值 (百分比)。

  • "setstepmul": 设置垃圾回收器的步进倍率 (step multiplier)，arg 参数为新的步进倍率值 (百分比)。

  • "isrunning": 返回垃圾回收器是否正在运行 (布尔值)。

  • "generational" (Lua 5.4+): 切换到分代垃圾回收模式。

  • "incremental" (Lua 5.4+): 切换到增量垃圾回收模式。

  通常情况下，Lua 的垃圾回收器会自动运行，无需手动调用 collectgarbage。但在某些特殊场景下，例如需要手动释放大量不再使用的内存，或者需要调整垃圾回收器的行为，可以使用 collectgarbage 函数。

  print("内存使用量 (KB):", collectgarbage("count")) -- 获取当前内存使用量
  collectgarbage("collect") -- 手动执行垃圾回收
  collectgarbage("setpause", 200) -- 设置暂停率为 200%
  collectgarbage("setstepmul", 200) -- 设置步进倍率为 200%
  ​

2.5 元表操作函数

• getmetatable (object): 前面已经介绍过，用于获取对象的元表。

• setmetatable (table, metatable): 前面已经介绍过，用于设置表的元表。

2.6 其他工具函数

• next (table [, index]): 允许遍历表中的所有键值对。 与 pairs 迭代器类似，但 next 是一个更底层的函数。 调用 next(table) 返回表中的第一个键及其对应的值。 连续调用 next(table, previousKey)，其中 previousKey 是上一次 next 调用返回的键，会返回表中的下一个键及其对应的值。 当遍历到表的末尾时，next 返回 nil。

  local myTable = { a = 10, b = 20, c = 30 }
  local key, value = next(myTable) -- 获取第一个键值对
  while key do
      print(key, value)
      key, value = next(myTable, key) -- 获取下一个键值对，以当前键作为参数
  end
  -- 可能输出 (顺序不确定):
  -- a	10
  -- b	20
  -- c	30
  ​

• select (index, ...): 用于访问可变参数列表 (...) 中的参数。 如果 index 是数字，则返回从索引 index 开始的所有参数。 如果 index 是字符串 "#", 则返回参数的总个数。

  function processArgs(...)
      print("参数总数:", select("#", ...)) -- 获取参数个数
      print("第二个参数:", select(2, ...)) -- 获取第二个参数
      print("从第三个参数开始:", select(3, ...)) -- 获取从第三个参数开始的所有参数
  end
  processArgs(1, "hello", true, 42)
  -- 输出:
  -- 参数总数:	4
  -- 第二个参数:	hello
  -- 从第三个参数开始:	true	42
  ​

• unpack (list [, i [, j]]): 展开一个数组 (数值索引的表) 的元素，作为函数调用的参数返回。 list 是要展开的数组，i 和 j (可选) 指定展开的起始和结束索引，默认为 1 和数组的长度。 unpack 常用于将数组元素传递给需要多个参数的函数。

  local myArray = { 10, 20, 30 }
  local x, y, z = unpack(myArray) -- 将数组元素展开赋值给变量
  print(x, y, z)                -- 输出: 10	20	30
  local function sum(a, b, c)
      return a + b + c
  end
  local result = sum(unpack(myArray)) -- 将数组元素作为参数传递给 sum 函数
  print("Sum:", result)              -- 输出: Sum: 60
  ​

• _VERSION: 一个全局变量，包含当前 Lua 解释器的版本号，是一个字符串。

  print(_VERSION)  -- 输出: Lua 5.4 (或你使用的 Lua 版本)
  ​

3. 基本库的最佳实践和使用技巧

• 善用 assert 进行防御性编程: 在开发阶段，积极使用 assert 来检查代码中的前提条件和不变量。这可以帮助及早发现错误，提高代码的健壮性。

• 利用 pcall 和 xpcall 处理潜在错误: 对于可能抛出异常的代码块，使用 pcall 或 xpcall 进行保护性调用。 xpcall 配合自定义错误处理函数，可以实现更灵活的错误处理策略。

• 理解 pairs 和 ipairs 的区别: 根据表的结构和遍历需求，选择合适的迭代器。 ipairs 适用于遍历数值索引连续的数组，pairs 适用于遍历所有键值对，但顺序不确定。

• 谨慎使用 dofile: dofile 每次调用都会重新加载并执行文件，可能导致性能问题。 对于模块加载，优先使用 require，它具有模块缓存机制。

• 避免在现代 Lua 中使用 module 函数: Lua 5.2+ 推荐使用 _ENV 或 package.loaded 手动管理模块作用域，更灵活和易于维护。

• 了解 collectgarbage 的作用: 在大多数情况下，Lua 的自动垃圾回收已经足够高效。 只有在特殊场景下，才需要手动调用 collectgarbage 或调整垃圾回收器参数。

• 查阅官方文档: Lua 的官方文档是学习和深入理解基本库的最佳资源。 遇到不清楚的函数或用法，及时查阅官方文档，获取最准确的信息。