【审核】Lua Scripting

语笑嫣然

Rainmeter可以加载执行由函数式编程语言Lua编写的脚本文件。Rainmeter涵盖了Lua 5.1标准库，具有读写文件、格式化字符串、执行运算操作等一系列强大的功能。
这里脚本指的是与Script类型Measure关联的一系列Lua函数。这些函数可以在皮肤加载，皮肤更新或被Bang指令触发时运行。

本节内容只是挑选了Rainmeter内置Lua环境的一些特别调整与新的函数。更多关于Lua本身的文档见：
Lua 5.1 参考手册
Lua教程
Programming in Lua
《Programming in Lua》
《Lua程序设计》
Lua函数速查

---

本节下面的内容将假定你已经具备Lua的基本知识。

Script Measure
Script类型Measure用于从文件加载Lua脚本并与脚本交互。脚本文件必须为纯文本文档，通常扩展名为 .lua。
与Plugin类型Measure相似，每一个脚本Measure都将创建独立的实例，彼此不会影响。也就是说一个皮肤可以同时加载多个脚本——即使是加载同一个脚本文件。（脚本执行的顺序由Measure书写的顺序决定。）不同实例间的全局变量不会被公用。

1. [MeasureName]
   
2. Measure=Script
   
3. ScriptFile=MyScript.lua

复制代码

---

选项
除了通用Measure选项和选项ScriptFile外，脚本Measure同样允许用户自定义的选项。这些选项可以为任何名字具有任何值，也可以被!SetOption改变。脚本可以通过使用SELF对象函数实现对这些选项值的读取和使用。这使得同一个脚本文件可以根据皮肤文件的内容不同而使用不同的参数设置。

1. [MeasureName]
   
2. Measure=Script
   
3. ScriptFile=MyScript.lua
   
4. MyOption=Hello, world!

复制代码

---

动态变量
动态变量在脚本Measure中通常是不需要的。这是因为Rainmeter提供给Lua中函数的变量值、Measure值和选项值全部为当前时刻的动态值。如果函数被使用在Update()函数中，函数将使用当函数被执行时刻的变量、Measure、选项的动态值。

1. !CommandMeasure

复制代码

!CommandMeasure在这里用于在某个特定的脚本实例中执行一段Lua代码。

1. !CommandMeasure "MyScriptMeasure" "MyFunction()"

复制代码

多句声明可以使用英文分号来分隔。所有的声明都是全局声明。

1. !CommandMeasure "MyScriptMeasure" "a = b; print(SKIN:ParseFormula('2+2'))"

复制代码

所有的代码声明在Bang指令中必须作为一个参数来传递。因为英文单引号和双引号在Lua中都是有效的字符串分隔符，而Rainmeter的Bang指令只识别双引号，因此建议在!CommandMeasure引用字符串时使用单引号。

1. Initialize( )

复制代码

如果任何脚本中定义了Initialize函数，那么在皮肤被加载或刷新时函数将被执行一次（不含参数）。即使脚本Measure被无效（Disabled=1），这一函数仍然会被执行。

1. function Initialize()
   
2.     MyVariable = 'Hello, world!'
   
3. end

复制代码

任何关于脚本初始化的代码，例如全局变量的声明，都应当书写在Initialize函数中。

这里提醒一下，脚本文件其实在被加载后在Initialize函数执行前，进行一次语法检查和全局执行，这甚至发生在SKIN等对象的声明前。因此像MyVariable = 'Hello, world!'这样简单的全局变量声明直接书写在任何函数之外也是有效的。

1. MyVariable = 'Hello, world!'
   
2. 
   
3. function Initialize()
   
4.     ...
   
5. end
   
6. Update( )

复制代码

如果任何脚本定义了Update函数（这一检查发生在脚本加载时），那么在脚本Measure每次更新时会被执行（不含参数）。脚本Measure在这里会正常响应Disabled选项、UpdateDivider选项和所有Measure Bang。

1. function Update()
   
2.     MyVariable = 'Hello, world!'
   
3.     return MyVariable
   
4. end

复制代码

Update函数的返回值将决定脚本Measure的返回值。Lua中的字符串和数字将自行拟合成Rainmeter中Measure的文本值和数值。
例如：

1. return

复制代码

返回数值0和文本值 "(空)"。如果return没有声明也是这样。
return 99 或 return '99'
返回数值99和文本值 "99"。

1. return '九九'

复制代码

返回数值0（因为这段字符串不能转换成数值）和文本值 "九九"。
脚本Measure返回的值可以像其他Measure返回值一样使用。
（提示：Measure返回值只在Measure本身更新时更新，在Lua内执行Update()并不会更新Measure返回值）

1. Log

复制代码

Lua的错误信息将反馈在Rainmeter的“关于”窗口中。同时print函数也会把信息输出到Rainmeter日志中。这种反馈在编写和调试脚本时非常有帮助。

1. print

复制代码

('MyVariable当前的值是' .. MyVariable)

---

函数
Rainmeter提供函数将Meter、Measure或当前皮肤识别为Lua的对象。此外另一些函数则是用于对这些对象进行不同的操作（注意大小写）

SKIN 对象
SKIN对象代表当前皮肤，由Rainmeter自动创建。
GetMeasure                                                    参数：Measure名
为指定的Measure建立对象。当Measure没有找到时返回nil。

示例：

1. MyMeasure = SKIN:GetMeasure('MeasureName')

复制代码

GetMeter                                                    参数：Meter名
为指定的Meter建立对象。当Meter没有找到时返回nil。

示例：

1. MyMeasure = SKIN:GetMeter('MeterName')

复制代码

GetVariable                                                参数：变量名, 默认值
将指定变量的当前值作为字符串返回。当变量不存在时，返回默认值，若默认值未设定返回nil。

示例：

1. MyVariable = SKIN:GetVariable('VariableName', 'n/a')

复制代码

等价于MyVariable = SKIN:GetVariable('VariableName') or 'n/a'

Bang                                    参数：Bang或Bang名, 参数1, 参数2, …
执行一个Bang指令。Bang指令可以有两种格式：

1. 将整个Bang作为一个字符串。
   示例：

1. SKIN:Bang('!SetOption "MyMeter" "Text" "Hello, world!"')

复制代码

多个Bang也可以这样书写。
   示例：

1. SKIN:Bang('[!UpdateMeter "MyMeter"][!Redraw]')

复制代码

2. 各个Bang参数分别做为函数的各个参数。
   示例：

1. SKIN:Bang('!SetOption', 'MyMeter', 'Text', 'Hello, world!')

复制代码

MakePathAbsolute                                            参数：文件/文件夹
将一个相对地址转换成绝对地址，与Path选项中的处理方式相同。

示例：

1. MyPath = SKIN:MakePathAbsolute('MyImage.png')

复制代码

等价于MyPath = SKIN:GetVariable('CurrentPath')..'MyImage.png'

ReplaceVariables                                                    参数：字符串
将一段字符串中所有有效的Rainmeter变量替换成变量值并返回。节点变量有效。

示例：

1. MyString = SKIN:ReplaceVariables

复制代码

(' MyVariable的值是 #MyVariable# 。')

ParseFormula                                            参数：一段公式的字符串
如果给定的字符串时一个有效的公式，那么公式的计算值将被作为数字返回。否则返回nil。

示例：

1. MyNumber = SKIN:ParseFormula('2+2')

复制代码

Measure对象
Measure对象通过GetMeasure函数来建立。它代表着皮肤中的一个特定Measure。
示例：

1. MyMeasure = SKIN:GetMeasure('MeasureName')

复制代码

GetValue
返回Measure当前的数值。
示例：

1. MyMeasureValue = MyMeasure:GetValue()

复制代码

GetStringValue
返回Measure当前的文本值。
示例：

1. MyMeasureValue = MyMeasure:GetStringValue()

复制代码

GetOption                                                参数：选项名, 默认值
将指定选项的当前值作为字符串返回。当选项不存在时，返回默认值，若默认值未设定返回 ''。
示例：

1. MyGroup = MyMeasure:GetOption('Group', 'None')

复制代码

GetNumberOption                                        参数：选项名, 默认值
将指定选项的当前值作为数字返回。当选项不存在时或者不是有效的数字或公式时，返回默认值，若默认值未设定返回 0。
示例：

1. MyUpdateDivider = MyMeasure:GetNumberOption(UpdateDivider, 1)

复制代码

GetName
将Measure的名字作为字符串返回。
示例：

1. MyMeasureName = MyMeasure:GetName()

复制代码

GetMinValue
将Measure的当前最小值作为数字返回。
示例：

1. MyMeasureMin = MyMeasure:GetMinValue()

复制代码

GetMaxValue
将Measure的当前最大值作为数字返回。
示例：

1. MyMeasureMax = MyMeasure:GetMaxValue()

复制代码

GetRelativeValue   
将Measure的当前百分值作为数字返回，从 0.0到1.0。
示例：

1. MyMeasureValue = MyMeasure:GetRelativeValue()

复制代码

GetValueRange
将Measure的当前取值范围作为数字返回。
示例：

1. MyMeasureRange = MyMeasure:GetValueRange()

复制代码

Disable
禁用当前Measure。
示例：

1. MyMeasure:Disable()

复制代码

Enable
启用当前Measure。
示例：

1. MyMeasure:Enable()

复制代码

SELF对象
SELF对象是一个Measure对象，代表当前脚本Measure，由Rainmeter自动创建。所有Measure对象的函数对SELF对象都是有效的。

1. MyScriptMeasureName = SELF:GetName()

复制代码

Meter对象
Meter对象通过GetMeter函数来建立。它代表着皮肤中的一个特定Meter。
示例：

1. MyMeter = SKIN:GetMeter('MeterName')

复制代码

GetOption                                                参数：选项名, 默认值
将指定选项的当前值作为字符串返回。当选项不存在时，返回默认值，若默认值未设定返回 ''。
示例：

1. MySolidColor = MyMeter:GetOption('SolidColor', '000000')

复制代码

GetName
将Meter的名字作为字符串返回。
示例：

1. MyMeterName = MyMeter:GetName()

复制代码

GetX                                                            参数：Absolute
将Meter当前的X坐标作为数字返回。当可选参数Absolute值为真，则返回“真实”X坐标（见节点变量）。
示例：

1. MyX = MyMeter:GetX()

复制代码

GetY                                                            参数：Absolute
将Meter当前的Y坐标作为数字返回。当可选参数Absolute值为真，则返回“真实”Y坐标（见节点变量）。
示例：

1. MyY = MyMeter:GetY()
   

复制代码

GetW
将Meter当前的“真实”宽度作为数字返回（见节点变量）。
示例：

1. MyW = MyMeter:GetW()

复制代码

GetH
将Meter当前的“真实”高度作为数字返回（见节点变量）。
示例：

1. MyH = MyMeter:GetH()

复制代码

SetX                                                            参数：X坐标
设置Meter的X坐标。
示例：

1. MyMeter:SetX(15)

复制代码

SetY                                                                参数：Y坐标
设置Meter的Y坐标。
示例：

1. MyMeter:SetY(15)

复制代码

SetW                                                            参数：宽度
设置Meter的宽度。
示例：

1. MyMeter:SetW(15)

复制代码

SetH                                                            参数：高度
设置Meter的高度。
示例：

1. MyMeter:SetH(15)

复制代码

Hide
隐藏Meter。
示例：

1. MyMeter:Hide()

复制代码

Show
显示Meter。
示例：

1. MyMeter:Show()

复制代码

---

环境限制
下面的Lua功能目前在Rainmeter的内置环境中是不可用的：
调试库
外部库，如LuaCURL
Require函数
Dofile函数

---

废弃功能
下面的这些Rainmeter特定的功能已经被废弃。虽然现在Rainmeter仍然支持，但在以后的Rainmeter版本可能会清除。

1. PROPERTIES = { ... }

复制代码

这个表是之前用于读取脚本Measure的选项。现在已被
SELF:GetOption('MyOption') 和SELF:GetNumberOption('MyOption')取代。

1. MyMeter:SetText('...')

复制代码

这个函数曾被用作改变String类型Meter的文本。现在已被SKIN:Bang('!SetOption', 'MeterName', 'Text', '...')取代。

1. function GetStringValue()

复制代码

这一函数曾被用于设置脚本Measure的返回值。现在已被function Update() return ... end取代。

傻大个牌纯碱

花仔，怎么是你审查？梧桐树呢？

lechce