Extension:Scribunto/zh

Scribunto (Latin: "they shall write/let them write (in the future)") 扩展可以在MediaWiki软件中嵌入脚本.

目前唯一被-{zh-hans:支持; zh-hant:支援;}-的脚本语言是Lua. Scribunto Lua脚本在一个名为-{zh:Module; zh-hans:模块; zh-hant:模組;}-的命名空间里. Modules are run on normal wiki pages using the #invoke parser function and each module has a collection of functions, which can be called using wikitext syntax such as:

许可协议
该扩展包含使用GNU通用公共许可证v2.0或更高版本（GPL-2.0+）的代码以及使用MIT许可证（MIT）的代码.

需求


PCRE版本兼容性
推荐使用PCRE 8.33+. PCRE 8.33 was released in May 2013. 你可以通过以下方法看到PHP所使用的PCRE的版本：查看phpinfo页面，或在命令行使用以下命令.


 * Scribunto不兼容8.10版本以下的PCRE
 * PCRE 8.31 在 JIT 模式方面存在缺陷，研究发现与HHVM一起使用时会破坏各种模式.
 * PCRE 8.32 有一个BUG，这将导致它拒绝某些 非字符代码点，这将导致 mw.html 模块出现错误.

CentOS 6 和 RHEL 6 卡在 PCRE 7 上，需要升级.

在使用旧版本的服务器上更新到 8.33 可能比较复杂. 更多细节在.

PHP pcntl (LTS)
MediaWiki 1.25 至 1.28 的 Scribunto 版本需要 PHP 的 pcntl扩展，如果您想使用“LuaStandalone”（即在单独的子进程中运行），该扩展名仅在 Unix/Linux 平台上可用. 在针对MediaWiki 1.29发布的Scribunto中这个依赖被移除.

你可以访问phpinfo网页以检查pcntl的支持是否已经启用，或者在命令行输入以下命令：



PHP mbsting 扩展
PHP需要启用 mbstring 扩展.

您可以通过查看phpinfo网页或使用以下命令从命令行检查是否启用了mbstring支持：



Lua 二进制


捆绑的二进制文件
Scribunto与Linux（x86和x86-64）、Mac OS X Lion和Windows（32位和64位）的Lua二进制发行版捆绑在一起.

Scribunto应该在以下情况下为您提供开箱即用的服务：

P.S. Check your version of the extension to see if the name of the engines folder is capitalised or fully lowercase.
 * 1) 您的web服务器在上述平台之一上运行.
 * 2) PHP的 函数不受限制.
 * 3) 你的网络浏览器已被配置为允许MediaWiki树中的二进制文件的执行.
 * 可能需要设置执行权限，例如，在Linux使用：
 * If you are using SELinux in "Enforcing" mode on your server, you might need to set a proper context for the binaries. Example for RHEL/CentOS 7:



额外的二进制
如果您的Web服务器的操作系统不在上面的列表中，则可能需要额外的Lua二进制发行版，可以从http://luabinaries.sourceforge.net/或从你的Linux发行中获得.

只支持Lua 5.1.x的二进制文件.

在你的web浏览器中安装了适当的二进制文件后，使用如下代码配置文件的地址：

注意你不应该添加上面的行，除非你确认Scribunto的内置二进制对你来说不起作用.

LuaJIT，尽管理论上兼容，但并不受支持.

不再支持是因为幽灵漏洞和比特腐烂的问题（T184156）.

安裝


可选安装


为能使用有语法高亮和自动缩进的代码编辑器，提供更舒适的用户界面，请安装下列扩展：

然后在所有插件注册后，在你的 中，添加：

Lua 沙盒
我们开发了一个用C语言编写的PHP扩展，称为LuaSandbox. 可以用作独立二进制文件的替代，并且性能更佳. 详细信息和安装指引，参见.

如果你最初安装扩展以使用Lua独立二进制文件，请务必使用以下配置设置更新 ：

-{zh-hans:配置; zh-hant:組態;}-
有以下几个用于配置的变量：
 * $wgScribuntoDefaultEngine
 * 选择默认引擎. 有效值为中的键，默认为 或.


 * $wgScribuntoUseGeSHi
 * 安装了后，将此设为true以在显示模块页面时使用它. （MediaWiki 1.30或更早. ）


 * $wgScribuntoUseCodeEditor
 * 安装了后，将此设为 以在编辑模块页面时使用它. （MediaWiki 1.30或更早. ）


 * $wgScribuntoEngineConf
 * 引擎配置的关联数组. 键时的有效值，值是配置数据的关联数组.  每个配置数组都必须包含一个 键，命名要使用的 子类.

LuaStandalone
中使用以下键用于. 通常你会将其设为类似于以下内容


 * luaPath
 * 指定到Lua解释器的路径.


 * errorFile
 * 指定文件的路径，可由Web服务器用户写入，其中将记录来自独立解释器的错误和调试输出.
 * 默认情况下不记录独立解释器产生的错误输出. 配置输出：


 * memoryLimit
 * 为Linux上的独立解释器指定内存限制，以字节为单位（使用ulimit强制执行）.


 * cpuLimit
 * 为Linux上的独立解释器指定CPU时间限制，以秒为单位（使用ulimit强制执行）.


 * allowEnvFuncs
 * 设为true以允许在模块内使用setfenv和getfenv.

LuaSandbox
中使用以下键用于. 通常你会将其设为类似于以下内容


 * memoryLimit
 * 指定内存限制，以字节为单位.


 * cpuLimit
 * 指定CPU时间限制，以秒为单位.


 * profilerPeriod
 * 在Lua分析器的部分中指定轮询之间的时间.


 * allowEnvFuncs
 * 设为true以允许在模块内使用setfenv和getfenv.

用法
脚本在称为模块的命名空间中. 每个模块都有一系列函数，可以在像这样的维基文本语法中调用：

Lua


学习Lua
Lua是一种简单的编程语言，用于让初学者可以使用. Lua的快速速成课程，可以尝试Learn Lua in 15 Minutes.

Lua语言的最全面的介绍是书籍《Programming in Lua》. 第一版（适用于Lua 5.0）可在线获得，主要与Scribunto使用的Lua 5.1版本相关：


 * Programming in Lua（滑到书本广告底下以查找文本）

参考手册也比较有用：



Lua环境
在Lua中，所有全局变量和函数的集合称为环境（environment）.

每个 调用会在一个单独的环境中运行. 一个 中定义的变量不会在另一个中有效. 这种限制是必要的，以维持维基文本解析器实现的灵活性.



调试控制台



 * 参见： 

编辑Lua模块时，编辑框底部会有一个“调试控制台”. 在这个调试控制台内，不需要保存或者甚至实际上创建一个Lua模块，就可以执行Lua代码.

故障排除


注意，红色的 消息是可点击的，且会提供详细信息.

When using the LuaStandalone engine (this is the default), errors along the lines of "" may be generated if the standalone Lua interpreter cannot be executed or runs into various runtime errors. To obtain more information, assign a file path to. The interpreter's error output will be logged to the specified file, which should prove more helpful in tracking down the issue. The information in the debug log includes debugging information, which is why there is so much of it. You should be able to ignore any line beginning with "TX" or "RX".

If you're setting up Scribunto and are using IIS/Windows, this appears to be solved by commenting out a particular line.

When using the LuaStandalone engine (this is the default), status 2 suggests memory allocation errors, probably caused by settings that allocate inadequate memory space for PHP or Lua, or both. Assigning a file path to  and examining that output can be valuable in diagnosing memory allocation errors.

Increase PHP allocation in your PHP configuration; add the line. This allocation of 200MB is often sufficient (as of MediaWiki 1.24) but can be increased as required. Set Scribunto's memory allocation in  as a line: Finally, depending on the server configuration, some installations may be helped by adding another  line

Note that all 3 memory limits are given in different units.

Lua error: Internal error: 2. on ARM architecture
If you're using an ARM architecture processor like on a RaspberryPi you'll face the error  due to wrong delivered binary format of the Lua interpreter.

Check your Lua interpreter in: /path/to/webdir/Scribunto/includes/Engines/LuaStandalone/binaries/lua5_1_5_linux_32_generic

Check the interpreter by using: file lua The result should look like : lua: ELF 32-bit LSB executable, ARM, EABI5 version 1 (SYSV), dynamically linked, interpreter /lib/ld-linux-armhf.so.3, for GNU/Linux 3.2.0 The installed default Lua interpreter shows: lua: ELF 32-bit LSB pie executable, Intel 80386, version 1 (SYSV), dynamically linked, interpreter /lib/ld-linux.so.2, for GNU/Linux 2.6.9, look at the "Intel 80386" part what definitely is not correct.

Check in  what version of Lua is installed on your system. If you have lua5.1 installed, you can either copy the interpreter to your  directory or set in your LocalSettings.php:

At present don't set  to /usr/bin/lua5.3, it'll lead to the "Internal error 1".

When using the LuaStandalone engine (this is the default), status 24 suggests CPU time limit errors, although those should be generating a "The time allocated for running scripts has expired" message instead. It would be useful to file a task in and participate in determining why the XCPU signal isn't being caught.

When using the LuaStandalone engine (this is the default), errors along the lines of "" may be generated if the standalone Lua interpreter cannot be executed. This generally arises from either of two causes:

Set permissions as described under #Installation. This often occurs with shared hosted servers. Remedies include adjusting  to point to a Lua 5.1 binary installed in an executable location, or adjusting or convincing the shared host to adjust the setting preventing execution.
 * The Lua executable file's permissions do not include Execute.
 * The server does not allow execution of files from the place where the executable is installed, e.g. the filesystem is mounted with the  flag.

Error condition such as: Fatal exception of type MWException
Check the MediaWiki, PHP, or webserver logs for more details on the exception, or temporarily set to.

version 'GLIBC_2.11' not found
If the above gives you errors such as "version 'GLIBC_2.11' not found", it means the version of the standard C library on your system is too old for the binaries provided with Scribunto. You should upgrade your C library, or use a version of Lua 5.1 compiled for the C library you do have installed. To upgrade your C library, your best option is usually to follow your distribution's instructions for upgrading packages (or for upgrading to a new release of the distribution, if applicable).

If you copy the lua binaries from Scribunto master (or from 77905), that should suffice, if you can't or don't want to upgrade your C library. The distributed binaries were recently recompiled against an older version of glibc, so the minimum is now 2.3 rather than 2.11.



Scribunto文件中的Lua错误
这里的错误包括：
 * attempt to index field 'text' (a nil value)（尝试访问'text'字段，其值为nil）
 * 位于mw.html.lua的253行的Lua错误：提供了无效类：

如果你在尝试使用从WMF wiki导入的模块时遇到此类错误，则很可能你的Scribunto版本已过期.

如有可能，请升级，对于高级用户，你可能需要找到需要的新提交，然后将其优选到你的本地安装中.

preg_replace_callback: Compilation failed: unknown property name after \P or \p at offset 7

 * this usually indicates an incompatible version of PCRE; you'll need to update to >= 8.10
 * @todo: link to instructions on how to upgrade



Lua错误
如果你从维基百科复制模板，然后在Scribunto调用（例如，使用了 的模板）的位置收到大红色“Lua错误：x”的消息，这可能意味着你没有导入所需的所有内容. 确保在zh:Special:Export导出时勾选“包括模板”.

从另一个wiki导入页面时，导入数据中的模板或模块也可能覆盖具有相同标题的现有模板或模块，这可能会破坏依赖于覆盖版本的现有页面、模板和模块.



空白屏幕
确保你的扩展版本可以适用于你的MediaWiki版本.



设计文档

 * Linux.conf.au 2014 - Scribunto presentation.webm's presentation at linux.conf.au 2014 discussing the motivations, implementation challenges and results of deploying Scribunto and Lua. ]]



其他页面

 * - 描述维基媒体站点部署计划的维基媒体活动页面.
 * - Lua语言的参考，以及维基媒体站点支持的标准库和常见Scribunto模块.
 * - Lua 5.2中可能导致用5.1编写的代码意外运行的已知更改列表.
 * - 扩展Scribunto库的示例扩展代码.
 * - Lua 5.2中可能导致用5.1编写的代码意外运行的已知更改列表.
 * - 扩展Scribunto库的示例扩展代码.
 * - 扩展Scribunto库的示例扩展代码.



參見

 * General
 * - Scribunto扩展的功能.
 * Commons:Lua - 在Wikimedia Commons上可能有使用Lua模块的具体说明，包括安装的额外Lua扩展（例如，用于国际化的本地支持以及解析或播放媒体）. 一些通用模块可以在其他wiki中以各种语言重新使用（除了针对具有专用名称的方针、命名空间或项目/维护页面的特定调整）.  如果可能，应该在Wikimedia Commons上测试和国际化可以在wiki中广泛重新使用的模块.
 * w:Help:Lua - 维基百科可能有使用Lua模块的具体说明，包括安装的附加Lua扩展（包括用于集成维基数据和维基共享资源内容、生成复杂的信息框和导航框，或根据适用方针促进wiki内容的一般管理/维护）. 其他一些本地化的维基百科版本（或其他项目，如维基词典、维基共享资源或维基新闻）也可能有自己的需求和Lua模块.
 * d:Help:Lua - 可能会有关于在维基数据上使用Lua模块的具体说明，包括安装的额外Lua扩展（例如，用于国际化的本地支持和数据库查询）
 * Extensions
 * - 提供基本的信息框功能以用于Scribunto扩展.
 * - 为Scribunto扩展使用提供原生支持
 * - 为Variables扩展提供Scribunto Lua接口
 * - 提供（维基数据项目的一部分）


 * Gadgets
 * Widgets