Xenharmonic Wiki

User:Ganaram inukshuk/Provisional style guide for Lua: Difference between revisions

← Older editNewer edit →
VisualWikitext
Ganaram inukshuk (talk | contribs)
autopatrolled, emailconfirmed
6,211 edits
No edit summary
Ganaram inukshuk (talk | contribs)
autopatrolled, emailconfirmed
6,211 edits
No edit summary
Line 16: Line 16:
=== Strings ===
=== Strings ===


Strings are enclosed in double quotes <code>" "</code>. If a string contains double quotes, do not escape them while enclosing the string in double quotes, as this reduces readability; instead, enclose the string in single quotes <code>' '</code>. Escape characters are only necessary if the string contains both single and double quotes.
Strings are enclosed in double quotes <code>" "</code>. If a string contains double quotes, do not escape them while enclosing the string in double quotes, as this reduces readability; instead, enclose the string in single quotes <code>' '</code>. Escape characters for quotes should only be used if the string contains both single and double quotes.


'''Preferred'''
'''Preferred'''
Line 48: Line 48:
=== Naming, declaring, and calling functions ===
=== Naming, declaring, and calling functions ===


As with variables, functions are named using <code>snake_case</code>.
As with variables, functions are named using <code>snake_case</code>. Functions that return a boolean variable are prefixed with <code>is_</code>''.''


''tbd''
''tbd''
Line 62: Line 62:
Only block comments <code> --[[  ]]-- </code> should only be used for commented-out code. This can be hard to do if a string contains a <code>]]</code>, so <code>--</code> may be used instead.
Only block comments <code> --[[  ]]-- </code> should only be used for commented-out code. This can be hard to do if a string contains a <code>]]</code>, so <code>--</code> may be used instead.


== Conventions for lua modules ==
== Conventions for Lua modules ==


=== Boilerplate code ===
=== Boilerplate code ===
Alphabetize dependencies, except for p, which goes last and separated by a line. Equals signs may be lined up. Placement of comments to be determined.
Alphabetize dependencies, except for p, which goes last and separated by a line. Equals signs may be lined up.


'''Preferred order'''<syntaxhighlight lang="lua" line="1">
'''Preferred order'''<syntaxhighlight lang="lua" line="1">local mos    = require("Module:MOS")
local rat    = require("Module:Rational")
local utils  = require("Module:Utils")
 
local p = {}</syntaxhighlight>'''Avoid'''<syntaxhighlight lang="lua" line="1">
local p = {}
local mos    = require("Module:MOS")
local mos    = require("Module:MOS")
local rat    = require("Module:Rational")
local rat    = require("Module:Rational")
local utils  = require("Module:Utils")
local utils  = require("Module:Utils")
local et      = require("Module:ET")
</syntaxhighlight><syntaxhighlight lang="lua" line="1">
local tip    = require("Module:Template input parse")
local tamnams = require("Module:TAMNAMS")
local yesno  = require("Module:Yesno")
 
local p = {}
local p = {}
</syntaxhighlight>'''Avoid'''<syntaxhighlight lang="lua" line="1">
local rat = require("Module:Rational")
local mos = require("Module:MOS")
local mos = require("Module:MOS")
local rat = require("Module:Rational")
local utils = require("Module:Utils")
local utils = require("Module:Utils")
local et = require("Module:ET")
</syntaxhighlight>
local tip = require("Module:Template input parse")
 
local tamnams = require("Module:TAMNAMS")
=== Placement of comments and TODO comments ===
local yesno = require("Module:Yesno")
Comments may be placed before modules as a preface, inline with modules to describe what each module does, and after the boilerplate code as a descripion. TODO comments should be placed before the code's description for ease of access.
 
TODO comments should not be confused with the todo categories, nor should such code-based TODOs ever be placed in [[Template:Todo]]; placing such tasks in the template makes it harder to maintain code and mixes up code-based tasks with wiki-based tasks.<syntaxhighlight lang="lua" line="1">-- Preface goes here
local mos    = require("Module:MOS")       -- For mos scale functions
local rat    = require("Module:Rational") -- For JI ratio calculations
local utils  = require("Module:Utils")     -- Contains the gcd function
 
local p = {}
local p = {}
</syntaxhighlight>


-- TODO goes here, if any
-- Description goes here</syntaxhighlight>
=== Use of functions ===
=== Use of functions ===


Line 93: Line 101:
Templates should consist of at least two functions: a "main" function prefixed with an underscore, and a wrapper function without an underscore.
Templates should consist of at least two functions: a "main" function prefixed with an underscore, and a wrapper function without an underscore.


The use of a wrapper and "main" function allows for a module to be used directly in another module or indirectly through its corresponding template. This rule may be disregarded for simple modules, or modules whose use is to provide a single function for other modules.
The use of a wrapper and "main" function allows for a module to be used directly in another module or indirectly through its corresponding template.


For testing purposes, a tester function may be added, which is itself a wrapper that calls the main function.<syntaxhighlight lang="lua">
For testing purposes, a tester function may be added, which is itself a wrapper that calls the main function.<syntaxhighlight lang="lua">
Line 111: Line 119:
     return p._call_me(args)
     return p._call_me(args)
end
end
</syntaxhighlight>
</syntaxhighlight>These guidelines do not apply for simple modules, or modules that only provide one function.


==== Helper functions ====
==== Helper functions ====
For code readability, the use of helper functions is recommended.
For code readability and code reusability within the module, the use of helper functions is recommended.


Helper functions may be nested within the calling function if those helpers only serve that function. This rule may be disregarded for testing purposes. Nested functions have access to the variables and parameters of the outer function, so an equivalent nested function may require fewer parameters.<syntaxhighlight lang="lua">function some_function(args)
Helper functions may be nested within the calling function if those helpers only serve that function. This rule may be disregarded for testing purposes. Nested functions have access to the variables and parameters of the outer function, so an equivalent nested function may require fewer parameters.<syntaxhighlight lang="lua">function some_function(args)
Line 126: Line 134:
     end
     end
end</syntaxhighlight>
end</syntaxhighlight>
===== Modules that serve as libraries for other modules =====
Modules that serve to provide functions to other libraries do not need any wrapper functions apart from a tester function.
==== Modules that provide wrappers for more than one template ====
Unless the wrapper functions encapsulate very simple tasks, a module should only ever provide '''one''' wrapper function for '''one''' template.
=== Concatenating strings ===
When concatenating long strings, it is best practice to insert constituent strings into a table, then concatenate afterwards. https://www.lua.org/pil/11.6.html
This rule does not apply to concatenating a few small strings together.
'''Preferred'''<syntaxhighlight lang="lua">
local lines = {}
table.insert(lines, '{| class="wikitable"')
table.insert(lines, '|+ Caption text')
table.insert(lines, '|-')
table.insert(lines, '! Header 1')
table.insert(lines, '! Header 2')
table.insert(lines, '! Header 3')
table.insert(lines, '|-')
table.insert(lines, '| aa')
table.insert(lines, '| bb')
table.insert(lines, '| cc')
table.insert(lines, '|-')
table.insert(lines, '| dd')
table.insert(lines, '| ee')
table.insert(lines, '| ff')
table.insert(lines, '|}')
return table.concat(lines, '\n')
</syntaxhighlight>'''Avoid'''<syntaxhighlight lang="lua">
local result = '{| class="wikitable"\n'
    .. '|+ Caption text\n'
    .. '|-\n'
    .. '! Header 1\n'
    .. '! Header 2\n'
    .. '! Header 3\n'
    .. '|-\n'
    .. '| aa\n'
    .. '| bb\n'
    .. '| cc\n'
    .. '|-\n'
    .. '| dd\n'
    .. '| ee\n'
    .. '| ff\n'
    .. '|}\n'
</syntaxhighlight>'''Allowed''' (although an alternative to this exists by using <code>string.format()</code>)<syntaxhighlight lang="lua">
local table_line = "Number of steps: " .. tonumber(num_steps) .. " steps"
</syntaxhighlight>


=== Mediawiki table formatting ===
=== Mediawiki table formatting ===
Line 155: Line 214:
|}
|}


</syntaxhighlight>
=== Concatenating strings ===
'''Experimental; yet to be fully adopted'''
Brought up when trying to make example code; turns out, this is recommended practice for large tables: https://www.lua.org/pil/11.6.html<syntaxhighlight lang="lua">
    table.insert(lines, '{| class="wikitable"')
    table.insert(lines, '|+ Caption text')
    table.insert(lines, '|-')
    table.insert(lines, '! Header 1')
    table.insert(lines, '! Header 2')
    table.insert(lines, '! Header 3')
    table.insert(lines, '|-')
    table.insert(lines, '| aa')
    table.insert(lines, '| bb')
    table.insert(lines, '| cc')
    table.insert(lines, '|-')
    table.insert(lines, '| dd')
    table.insert(lines, '| ee')
    table.insert(lines, '| ff')
    table.insert(lines, '|}')
   
    return table.concat(lines, '\n')
</syntaxhighlight>
</syntaxhighlight>


Retrieved from "https://en.xen.wiki/w/User:Ganaram_inukshuk/Provisional_style_guide_for_Lua"