ini — INI 配置文件

模块名：ini

读写 INI 格式的配置文件，基于 SimpleIni。适合保存人类可读、可手工编辑的配置（分节 + 键值）。相比 fdb 的键值库，INI 的优点是格式直观、能整段导入导出。

ini.new 返回一个对象，其余都是对象方法。由于内部把函数表同时用作 __index，ini.get_value(o, ...) 和 o:get_value(...) 都能用。

函数总览

库级函数

函数	作用
ini.new()	创建一个 INI 对象

对象方法

方法	作用
o:load_file	从文件加载
o:load_data	从字符串加载
o:get_value	读一个键值
o:set_value	写一个键值
o:delete	删除键或整节
o:save_file	保存到文件
o:save	保存到字符串
o:get_all_sections	列出所有节名
o:get_all_keys	列出某节的所有键
o:get_all_values	列出某键的所有值

返回码 rc 是 SimpleIni 的错误码，0 表示成功。本模块不注册常量。

---

ini.new

ini.new() --> ini

创建一个空的 INI 对象。

参数

无参数。

返回值

类型	说明
userdata	INI 对象

示例

local cfg = ini.new()

---

o:load_file

o:load_file(filename) --> rc

从文件加载 INI 内容。

参数

#	参数	类型	必填	默认值	说明
1	filename	string	是	—	文件名，不是完整路径。固件自动加前缀（ESP32 为 /spiffs/，Windows 模拟器为 .../Simulator/）

返回值

类型	说明
integer	返回码，0 成功

示例

local cfg = ini.new()
if cfg:load_file("device.ini") == 0 then
    print("配置已加载")
end

说明

• 传相对文件名即可，不要写成 /spiffs/device.ini，前缀会被重复添加。

---

o:load_data

o:load_data(data) --> rc

从字符串加载 INI 内容。

参数

#	参数	类型	必填	默认值	说明
1	data	string	是	—	INI 格式的文本

返回值

类型	说明
integer	返回码，0 成功

---

o:get_value

o:get_value(section, key, [default]) --> value, has_multi

读取一个键的值。

参数

#	参数	类型	必填	默认值	说明
1	section	string	是	—	节名
2	key	string	是	—	键名
3	default	string	否	nil	键不存在时返回的默认值

返回值

类型	说明
string	键值；不存在且未给默认值时为 nil
boolean	has_multi，该键是否有多个同名值

示例

local ip = cfg:get_value("network", "ip", "192.168.1.100")

说明

• INI 里所有值都是字符串，数字要自己 tonumber。

---

o:set_value

o:set_value(section, key, value) --> boolean

写入一个键值，节和键不存在会自动创建。

参数

#	参数	类型	必填	默认值	说明
1	section	string	是	—	节名
2	key	string	是	—	键名
3	value	string	是	—	值。数字要先 tostring

返回值

类型	说明
boolean	是否成功

说明

• 只改内存中的对象，要落盘必须再调 save_file。

---

o:delete

o:delete(section, [key]) --> boolean

删除一个键；省略 key 则删除整节。

参数

#	参数	类型	必填	默认值	说明
1	section	string	是	—	节名
2	key	string	否	nil	键名。省略时删除整个节

返回值

类型	说明
boolean	是否成功

---

o:save_file

o:save_file(filename) --> rc

保存到文件。

参数

#	参数	类型	必填	默认值	说明
1	filename	string	是	—	文件名，前缀规则同 load_file

返回值

类型	说明
integer	返回码，0 成功

---

o:save

o:save() --> rc, data

把当前内容序列化为字符串，不写文件。

参数

无参数。

返回值

类型	说明
integer	返回码，0 成功
string	INI 文本

---

o:get_all_sections

o:get_all_sections() --> table

列出所有节名。

参数

无参数。

返回值

类型	说明
table	节名字符串数组

---

o:get_all_keys

o:get_all_keys(section) --> table

列出某节下的所有键名。

参数

#	参数	类型	必填	默认值	说明
1	section	string	是	—	节名

返回值

类型	说明
table	键名字符串数组

---

o:get_all_values

o:get_all_values(section, key) --> table

列出某键的所有值（同名键有多个值时用）。

参数

#	参数	类型	必填	默认值	说明
1	section	string	是	—	节名
2	key	string	是	—	键名

返回值

类型	说明
table	值字符串数组

---

常见用法

读取配置

local cfg = ini.new()
cfg:load_file("device.ini")

local ip   = cfg:get_value("network", "ip", "192.168.1.100")
local port = tonumber(cfg:get_value("network", "port", "502"))

修改并保存

local cfg = ini.new()
cfg:load_file("device.ini")
cfg:set_value("network", "ip", "192.168.1.200")
cfg:set_value("device", "name", plc.plc_name())
cfg:save_file("device.ini")

遍历全部内容

local cfg = ini.new()
cfg:load_file("device.ini")
for _, sec in ipairs(cfg:get_all_sections()) do
    print("[" .. sec .. "]")
    for _, key in ipairs(cfg:get_all_keys(sec)) do
        print(key, "=", cfg:get_value(sec, key))
    end
end

注意事项

• load_file / save_file 传文件名而非绝对路径，前缀由固件自动加。
• 所有值都是字符串，数字自行 tonumber / tostring。
• set_value / delete 只改内存，要持久化必须 save_file。
• 频繁读写单个键的场景用 fdb 更合适；INI 更适合整份可读配置。

例程

统一模板「场景 / 完整代码 / 要点 / 验证方法 / 注意事项」。

例程 1：读取配置（load_file + get_value）

适用：LP3201 / LP3202 / LP3203 / LP3222 / LP3232 / LP3288 / 软PLC模拟器 / 上位机 ｜ 依赖模块：ini ｜ 难度：★☆☆

场景：设备从 device.ini 读取 IP 和端口，读不到用默认值。

完整代码（可直接下载运行）：

local cfg = ini.new()
if cfg:load_file("device.ini") == 0 then
    print("配置已加载")
end
local ip   = cfg:get_value("network", "ip", "192.168.1.100")
local port = tonumber(cfg:get_value("network", "port", "502"))
print("连接", ip, port)

要点：load_file 传文件名（非绝对路径，前缀固件自动加）；get_value 第三参是默认值。

验证方法：放一个 device.ini 到设备存储，重启后读到文件里的值。

注意事项：INI 值全是字符串，数字必须 tonumber；文件不存在时返回 nil，要用默认值兜底。

---

例程 2：修改并保存配置

适用：同上 ｜ 依赖模块：ini plc ｜ 难度：★☆☆

场景：上位机下发新 IP，改完写回文件。

完整代码（可直接下载运行）：

local cfg = ini.new()
cfg:load_file("device.ini")
cfg:set_value("network", "ip", "192.168.1.200")
cfg:set_value("device", "name", plc.plc_name())
cfg:save_file("device.ini")   -- 必须 save，否则改动只留内存

要点：set_value 第 3 参必须是字符串，数字先 tostring。

验证方法：重新 load_file 或导出文件，确认值已更新。

注意事项：set_value/delete 只改内存，不调 save_file 不会落盘。

---

例程 3：遍历整份配置

适用：同上 ｜ 依赖模块：ini ｜ 难度：★☆☆

场景：打印所有节与键，做配置自检。

完整代码（可直接下载运行）：

local cfg = ini.new()
cfg:load_file("device.ini")
for _, sec in ipairs(cfg:get_all_sections()) do
    print("[" .. sec .. "]")
    for _, key in ipairs(cfg:get_all_keys(sec)) do
        print(key, "=", cfg:get_value(sec, key))
    end
end

要点：get_all_sections / get_all_keys 返回 table 数组。

验证方法：控制台看到完整配置树。

注意事项：值都是字符串，数字需 tonumber；频繁读写单键用 fdb 更轻量。