# 模块与包

URL: https://caijiao.org/lua/modules
Source: docs/lua/modules.md
Description: 学习 Lua 的模块化编程方法，包括如何创建模块、使用 'require' 导入模块，以及包路径管理。

Lua 提供了简洁的 **模块化机制**，便于将代码拆分为独立文件和逻辑单元，  

通过 `require` 可以方便地导入和复用模块。

## 🧩 创建模块

假设我们创建一个模块文件 `math_utils.lua`：

```lua
-- math_utils.lua
local M = {}

function M.add(a, b)
  return a + b
end

function M.sub(a, b)
  return a - b
end

return M
````

> 模块内部通常使用局部表 `M` 保存函数，最后 `return M` 导出。

## 🔗 导入模块

在主程序中使用 `require` 导入模块：

```lua
local math_utils = require("math_utils")

print(math_utils.add(3, 5))  -- 输出 8
print(math_utils.sub(10, 4)) -- 输出 6
```

## 📦 包路径

Lua 根据 **`package.path`** 搜索模块文件：

```lua
print(package.path)
```

默认路径中使用 `?` 占位符匹配模块名，例如：

```txt
./?.lua; /usr/local/share/lua/5.4/?.lua; ...
```

> 如果模块在其他目录，可通过修改 `package.path` 或将模块放到标准路径中。

## 🧱 嵌套模块

模块可以嵌套形成命名空间：

```lua
-- utils/string_utils.lua
local M = {}

function M.upper(str)
  return string.upper(str)
end

return M
```

```lua
local string_utils = require("utils.string_utils")
print(string_utils.upper("lua"))  -- LUA
```

## 🧩 简化导入

模块也可以直接返回函数，适用于单一功能模块：

```lua
-- square.lua
return function(x)
  return x * x
end
```

```lua
local square = require("square")
print(square(5))  -- 25
```

## 🧠 小结

* 使用模块可以将代码拆分为独立文件
* `require("模块名")` 导入模块
* 模块内部通常使用表 `M` 保存函数，并 `return M`
* 通过包路径 `package.path` 管理模块搜索位置
* 模块可以嵌套或直接返回函数，实现灵活封装