Help:Modules: Difference between revisions
>OmegaK2 No edit summary |
No edit summary |
||
(23 intermediate revisions by 7 users not shown) | |||
Line 1: | Line 1: | ||
[[wikipedia:Lua (programming language)|Lua]] is a programming language that is available, via the [[mw:Extension:Scribunto|Scribunto]] MediaWiki extension. Lua code can now be embedded into wiki templates by employing the "<nowiki>{{#invoke:}}</nowiki>" functionality of Scribunto. The Lua source is stored in pages called '''modules''' (e.g., [[Module:Skill]]). These individual modules are then invoked (by code <code><nowiki>{{#invoke:}}</nowiki></code>) on template page. Modules are used when more advanced functions with high performance are required. | |||
==Writing modules== | |||
===General=== | |||
* Use underscore_naming for variables and functions | |||
* Use 4 spaces for indentation | |||
* Add extension documentation to /doc if possible, however this is not required if the code is readable | |||
* If implementing a template in lua | |||
** Add to the lua comments which template(s) are implemented by the function | |||
** Add to the /doc page which templates are implemented | |||
** Add to a link from the template's /doc page using [[:Template:Lua]] | |||
===Module documenation=== | |||
* Add appropriate categories to the template (NOT the /doc subpage, i.e. use <nowiki><includeonly></includeonly></nowiki> tags) | |||
** For templates for inclusion in other templates add [[:Template:ProgrammingModule]] | |||
===Coding style=== | |||
====Define variables as local unless they are otherwise needed==== | |||
As the title suggest try to define locally in the scope they are needed. | |||
====Compress boolean statements if possible==== | |||
This may be require some basic familiarity with [[wikipedia:Boolean algebra|Boolean algebra]]. | |||
<ul> | |||
<li class="mw-collapsible mw-collapsed">Examples | |||
<syntaxhighlight lang="lua" class="mw-collapsible-content"> | |||
-- Bad | |||
not (a == b) | |||
-- Good | |||
a ~= b | |||
-- Bad | |||
not (a ~= b) | |||
-- Good | |||
a == b | |||
-- Bad | |||
a and (a or b) | |||
-- Good | |||
a | |||
-- Bad | |||
a or (a and b) | |||
-- Good | |||
a | |||
</syntaxhighlight></li> | |||
</ul> | |||
====Strings connecting==== | |||
There are 3 basic rules: | |||
<ul> | |||
<li class="mw-collapsible mw-collapsed">If the string is very long to connect, use a table and <code>table.concat</code>. This is faster and more readable | |||
<syntaxhighlight lang="lua" class="mw-collapsible-content"> | |||
-- Don't | |||
local out = '' | |||
out = out .. 'a' | |||
out = out .. 'b' | |||
out = out .. 'c' | |||
out = out .. 'd' | |||
out = out .. 'e' | |||
out = out .. 'f' | |||
return out | |||
-- Do | |||
local out = {} | |||
out[#out+1] = 'a' | |||
out[#out+1] = 'b' | |||
out[#out+1] = 'c' | |||
out[#out+1] = 'd' | |||
out[#out+1] = 'e' | |||
out[#out+1] = 'f' | |||
return table.concat(out, '') | |||
</syntaxhighlight></li> | |||
<li class="mw-collapsible mw-collapsed">If the string is short, but has multiple arguments, use <code>string.format</code>, while it may be a bit slower, it is much more readable | |||
<syntaxhighlight lang="lua" class="mw-collapsible-content"> | |||
-- Hard to read | |||
"#ask:[[Is event::" .. args.type .. "]] [[Has release date::<" .. args.release_date .. "]]" | |||
-- Better to read | |||
string.format("#ask:[[Is event::%s]] [[Has release date::<%s]]", args.type, args.release_date) | |||
</syntaxhighlight></li> | |||
<li class="mw-collapsible mw-collapsed">Use .. for other simple cases | |||
<syntaxhighlight lang="lua" class="mw-collapsible-content"> | |||
-- This is ok | |||
myvar .. other_var .. whatever | |||
</syntaxhighlight></li> | |||
</ul> | |||
====Avoid code duplication==== | |||
Please try to avoid any form of repeated (in particular 'spaghetti') code. | |||
Minor repeats where required are, but large portions of the code repeating itself should be avoided. | |||
Consider the following techniques: | |||
* Use [[mediawikiwiki:Extension:Scribunto/Lua_reference_manual#Standard_libraries|library modules]] to reduce code duplication | |||
* Use poe wiki library modules like [[Module:Util]], [[Module:Game]] to reduce code duplication | |||
* Move code that is used regularly into a function; if the code is used...: | |||
** ... only used in that module, add as local, non callable function to the module | |||
** ... used primarily in that module, but may be used in others, add it to the return table | |||
** ... is generally useful for a lot of various modules consider adding it to [[Module:Util]] (discuss on talk page first) | |||
* For formatting strings based on conditions, consider moving the formatting itself outside of the conditions if it is the same | |||
* For long <code>if ... elseif ... elseif ... elseif ... end</code> that execute similar code create a table and loop trough the table | |||
==For editors== | ==For editors== | ||
* [[Module: | * Items | ||
* [[Module: | ** [[Module:Item2]] - Responsible for the item info boxes and lists. Use this instead of [[Module:Item]]. Defines and stores Cargo tables. The game data can be exported with [[PyPoE]]. | ||
* [[Module: | ** [[Module:Skill]] - Skill related templates; also included by [[Module:Item2]] for [[skill gem]] support. The game data can be exported with [[PyPoE]]. | ||
* [[Module: | ** [[Module:Item table]] - Item related tables. | ||
* [[Module: | ** [[Module:Item link]] - Links for items. | ||
* [[Module: | * Modifiers | ||
* [[Module: | ** [[Module:Mod]] - Defines [[modifier]] related templates. The game data can be exported with [[PyPoE]]. | ||
* [[Module: | ** [[Module:Modifier table]] - Modifier related tables. | ||
* [[Module:Miscellaneous]] | * [[Module:Data tables]] - Various infoboxes that defines and stores cargo tables. | ||
* [[Module:Quest]] - [[Quest]] related templates. | |||
* [[Module:Quest reward]] - [[Quest reward]] related templates and data. | |||
* [[Module:Miscellaneous]] - Minor templates that don't need their own module. | |||
* [[Module:Queries]] - Create tables from powerful data queries. | |||
==For other modules== | ==For other modules== | ||
* [[Module:Util]] | * [[Module:Util]] - Various utility functions to simplify coding new modules. | ||
* [[Module:Arguments]] | * [[Module:Arguments]] - Parses arguments passed to module calls. | ||
* [[Module:Game]] | * [[Module:Game]] - Contains various game-related constants and data. | ||
* [[Module:Table]] | * [[Module:Table]] - Extended Table functionality. | ||
==See also== | ==See also== | ||
* [[Path of Exile Wiki: | * [[mw:Help:Lua|MediaWiki:Help:Lua]] | ||
* [[Help:Templates]] | |||
[[Category:Help]] | |||
[[ru:Path of Exile Wiki:Обзор модулей]] |
Latest revision as of 13:12, 4 June 2023
Lua is a programming language that is available, via the Scribunto MediaWiki extension. Lua code can now be embedded into wiki templates by employing the "{{#invoke:}}" functionality of Scribunto. The Lua source is stored in pages called modules (e.g., Module:Skill). These individual modules are then invoked (by code {{#invoke:}}
) on template page. Modules are used when more advanced functions with high performance are required.
Writing modules
General
- Use underscore_naming for variables and functions
- Use 4 spaces for indentation
- Add extension documentation to /doc if possible, however this is not required if the code is readable
- If implementing a template in lua
- Add to the lua comments which template(s) are implemented by the function
- Add to the /doc page which templates are implemented
- Add to a link from the template's /doc page using Template:Lua
Module documenation
- Add appropriate categories to the template (NOT the /doc subpage, i.e. use <includeonly></includeonly> tags)
- For templates for inclusion in other templates add Template:ProgrammingModule
Coding style
Define variables as local unless they are otherwise needed
As the title suggest try to define locally in the scope they are needed.
Compress boolean statements if possible
This may be require some basic familiarity with Boolean algebra.
- Examples
-- Bad not (a == b) -- Good a ~= b -- Bad not (a ~= b) -- Good a == b -- Bad a and (a or b) -- Good a -- Bad a or (a and b) -- Good a
Strings connecting
There are 3 basic rules:
- If the string is very long to connect, use a table and
table.concat
. This is faster and more readable-- Don't local out = '' out = out .. 'a' out = out .. 'b' out = out .. 'c' out = out .. 'd' out = out .. 'e' out = out .. 'f' return out -- Do local out = {} out[#out+1] = 'a' out[#out+1] = 'b' out[#out+1] = 'c' out[#out+1] = 'd' out[#out+1] = 'e' out[#out+1] = 'f' return table.concat(out, '')
- If the string is short, but has multiple arguments, use
string.format
, while it may be a bit slower, it is much more readable-- Hard to read "#ask:[[Is event::" .. args.type .. "]] [[Has release date::<" .. args.release_date .. "]]" -- Better to read string.format("#ask:[[Is event::%s]] [[Has release date::<%s]]", args.type, args.release_date)
- Use .. for other simple cases
-- This is ok myvar .. other_var .. whatever
Avoid code duplication
Please try to avoid any form of repeated (in particular 'spaghetti') code. Minor repeats where required are, but large portions of the code repeating itself should be avoided.
Consider the following techniques:
- Use library modules to reduce code duplication
- Use poe wiki library modules like Module:Util, Module:Game to reduce code duplication
- Move code that is used regularly into a function; if the code is used...:
- ... only used in that module, add as local, non callable function to the module
- ... used primarily in that module, but may be used in others, add it to the return table
- ... is generally useful for a lot of various modules consider adding it to Module:Util (discuss on talk page first)
- For formatting strings based on conditions, consider moving the formatting itself outside of the conditions if it is the same
- For long
if ... elseif ... elseif ... elseif ... end
that execute similar code create a table and loop trough the table
For editors
- Items
- Module:Item2 - Responsible for the item info boxes and lists. Use this instead of Module:Item. Defines and stores Cargo tables. The game data can be exported with PyPoE.
- Module:Skill - Skill related templates; also included by Module:Item2 for skill gem support. The game data can be exported with PyPoE.
- Module:Item table - Item related tables.
- Module:Item link - Links for items.
- Modifiers
- Module:Mod - Defines modifier related templates. The game data can be exported with PyPoE.
- Module:Modifier table - Modifier related tables.
- Module:Data tables - Various infoboxes that defines and stores cargo tables.
- Module:Quest - Quest related templates.
- Module:Quest reward - Quest reward related templates and data.
- Module:Miscellaneous - Minor templates that don't need their own module.
- Module:Queries - Create tables from powerful data queries.
For other modules
- Module:Util - Various utility functions to simplify coding new modules.
- Module:Arguments - Parses arguments passed to module calls.
- Module:Game - Contains various game-related constants and data.
- Module:Table - Extended Table functionality.