User:Ganaram inukshuk/Provisional style guide for Lua - Revision history

Ganaram inukshuk at 21:14, 6 November 2025

2025-11-06T21:14:11Z

← Older revision		Revision as of 21:14, 6 November 2025
Line 2:		Line 2:

	Parts of it are adapted for use on the wiki, with details on specific conventions. If a specific convention is missing, fall back to that described in the Luarocks style guide.		Parts of it are adapted for use on the wiki, with details on specific conventions. If a specific convention is missing, fall back to that described in the Luarocks style guide.

			== Provisional additions for version 2 ==
			Consistency with param names, including spelling:

			* Define all param names at the module level, not the template level
			* Use snake_case for all param names throughout; anything remotely close to snake_case is normalized to snake_case
			* "debug" and "nocat" are reserved for toggling categories; the use of "debug" this way has already been the standard

	== Preliminaries ==		== Preliminaries ==

Ganaram inukshuk at 00:21, 21 October 2025

2025-10-21T00:21:50Z

← Older revision		Revision as of 00:21, 21 October 2025
Line 10:		Line 10:
	=== Naming and declaring variables ===		=== Naming and declaring variables ===

	Variable names should be short and descriptive, written in <code>snake_case</code>. Exceptions to this include counter variables, like with <code>i</code> in for loops. Boolean variables are prefixed with <code>is_</code> wherever possible. Constants are named using <code>TRAIN_CASE</code>.		Variable names should be short and descriptive, written in <code>snake_case</code>. Exceptions to this include counter variables, like with <code>i</code> in for loops. Boolean variables are prefixed with <code>is_</code> or <code>has_</code> wherever possible. Constants are named using <code>TRAIN_CASE</code>.

	All variable declarations should start with <code>local</code>.		All variable declarations should start with <code>local</code>.
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>. Functions that return a boolean variable are prefixed with <code>is_</code>''.''		As with variables, functions are named using <code>snake_case</code>. Functions that return a boolean variable are prefixed with <code>is_</code> or <code>has_</code>.

	''tbd''		''tbd''

Ganaram inukshuk at 22:32, 17 October 2025

2025-10-17T22:32:24Z

← Older revision		Revision as of 22:32, 17 October 2025
Line 10:		Line 10:
	=== Naming and declaring variables ===		=== Naming and declaring variables ===

	Variable names should be short and descriptive, written <code>snake_case</code>. Exceptions to this include counter variables, like with <code>i</code> in for loops. Boolean variables are prefixed with <code>is_</code>. Constants are named using <code>TRAIN_CASE</code>.		Variable names should be short and descriptive, written in <code>snake_case</code>. Exceptions to this include counter variables, like with <code>i</code> in for loops. Boolean variables are prefixed with <code>is_</code> wherever possible. Constants are named using <code>TRAIN_CASE</code>.

	All variable declarations should start with <code>local</code>.		All variable declarations should start with <code>local</code>.

Ganaram inukshuk: /* Modules that implement templates */

2025-10-16T10:19:34Z

Modules that implement templates

← Older revision		Revision as of 10:19, 16 October 2025
Line 102:		Line 102:

	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. A module should only provide '''one''' wrapper for '''one''' template. If the "main" function is short enough, its code may be merged with the wrapper function.		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. A module should only provide '''one''' wrapper for '''one''' template. If the "main" function is short enough, its code may be merged with the wrapper function.



	A tester function may be added for testing purposes, which is itself a wrapper that also calls the "main" function. This allows it to be tested using the in-browser console by calling mw.logObject(p.tester()). Tester functions may be removed if the "main" function is determined to be functional under expected conditions.<syntaxhighlight lang="lua">-- "Main" function to be called by wrapper or another module		A tester function may be added for testing purposes, which is itself a wrapper that also calls the "main" function. This allows it to be tested using the in-browser console by calling mw.logObject(p.tester()). Tester functions may be removed if the "main" function is determined to be functional under expected conditions.<syntaxhighlight lang="lua">-- "Main" function to be called by wrapper or another module
Line 134:		Line 132:
	-- Usable by other modules		-- Usable by other modules

	function p.~~_clamp~~(arg1, arg2, arg3)		function p._call_me(arg1, arg2, arg3)
	-- Code goes here		-- Code goes here
	end		end
Line 145:		Line 143:
	-- Usable by templates with {{#invoke}}		-- Usable by templates with {{#invoke}}

	function p.~~clamp~~(frame)		function p._call_me(frame)
	return p._clamp(frame.args["arg1"], frame.args["arg2"], frame.args["arg3"])		return p._clamp(frame.args["arg1"], frame.args["arg2"], frame.args["arg3"])
	end		end
Line 156:		Line 154:
	For code readability and code reusability within the module, the use of helper functions is recommended.		For code readability and code reusability within the module, the use of helper functions is recommended.

	Ideally, helper functions should be nested within the calling function if those helpers only serve that function, but 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)		Ideally, helper functions should be nested within the calling function if those helpers only serve that function, but this rule may be disregarded for testing purposes, or for helper functions needed by more than one function. 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 p._call_me(args)
	-- Get args here		-- Get args here
	local arg1 = args["Arg 1"]		local arg1 = args["Arg 1"]
Line 168:		Line 166:

	==== What to pass into a "main" function ====		==== What to pass into a "main" function ====
	For an underscore-prefixed "main" function, if its expected inputs is determined to be fixed (for example, no new features are expected to ever be added), the function may accept them individually.<syntaxhighlight lang="lua">		For an underscore-prefixed "main" function, if its expected inputs is determined to be fixed (for example, no new features are expected to ever be added), the function may accept them individually.<syntaxhighlight lang="lua">-- "Main" function to be called by wrapper or another module
	-- "Main" function to be called by wrapper or another module		-- Function signature consists of three args and the return value (not shown)
	function p._call_me(arg1, arg2, arg3)		function p._call_me(arg1, arg2, arg3)
	-- Code goes here		-- Code goes here
	end		end</syntaxhighlight>If there is large amounts of input, or if the number of inputs is not known, the function should have a single parameter that is a table of passed-in arguments. This allows for expansion of the template's inputs without making the function signature any larger.<syntaxhighlight lang="lua">
	</syntaxhighlight>If there is large amounts of input, or if the number of inputs is not known, the function should have a single parameter that is a table of passed-in arguments.<syntaxhighlight lang="lua">
	-- "Main" function to be called by wrapper or another module		-- "Main" function to be called by wrapper or another module
			-- Function signature consists of one table and the output (not shown)
	function p._call_me(args)		function p._call_me(args)
	-- Get args here		-- Get args here
Line 184:		Line 182:
	end		end
	</syntaxhighlight>		</syntaxhighlight>

			==== What to get out of a function ====
			Most functions should return something (a value, a string, a table, or more than one of those things), with the exception of functions that change the contents of a table. Modules that implement templates typically return a string that represents something that can be interpreted as wikitext. Guidance on how to create such strings is explained in later sections.

	=== Concatenating strings ===		=== Concatenating strings ===

Ganaram inukshuk at 10:01, 16 October 2025

2025-10-16T10:01:45Z

← Older revision		Revision as of 10:01, 16 October 2025
Line 98:		Line 98:
	=== Use of functions ===		=== Use of functions ===

	===== ~~"Main", wrapper, and tester functions~~ =====		===== Modules that implement templates =====
	~~Templates~~ should consist of at least two functions: a "main" function prefixed with an underscore, and a wrapper function of the same name but without an underscore.		Modules that implement templates should consist of at least two functions: a "main" function prefixed with an underscore, and a wrapper function of the same name but 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. A module should only provide '''one''' wrapper for '''one''' template. If the "main" function is short enough, its code may be merged with the wrapper function.


	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. A module should only provide '''one''' wrapper for '''one''' template.

	A tester function may be added for testing purposes, which is itself a wrapper that also calls the "main" function. This allows it to be tested using the in-browser console by calling mw.logObject(p.tester()). Tester functions may be removed if the "main" function is determined to be functional under expected conditions.<syntaxhighlight lang="lua">-- "Main" function to be called by wrapper or another module		A tester function may be added for testing purposes, which is itself a wrapper that also calls the "main" function. This allows it to be tested using the in-browser console by calling mw.logObject(p.tester()). Tester functions may be removed if the "main" function is determined to be functional under expected conditions.<syntaxhighlight lang="lua">-- "Main" function to be called by wrapper or another module
Line 108:		Line 110:
	end		end

	-- Wrapper function; to be called by template		-- Wrapper function; to be called by template using {{#invoke}}
	function p.call_me(frame)		function p.call_me(frame)
	return p._call_me(frame.args)		return p._call_me(frame.args)
Line 117:		Line 119:
	local args = { ["something"] = 123 }		local args = { ["something"] = 123 }
	return p._call_me(args)		return p._call_me(args)
	end</syntaxhighlight>~~The guidelines stated above~~ do not ~~apply to~~ the ~~following~~:		end</syntaxhighlight><syntaxhighlight lang="lua">-- Wrapper function; to be called by template
			function p.call_me(frame)
			local arg = frame.args["arg"]

			-- Code goes here

			return call_me(arg)
			end</syntaxhighlight>

			==== Modules that serve as libraries ====
			Modules that serve as libraries for other modules do not need a wrapper function, apart from the tester. Examples include [[Module:MOS]], [[Module:Rational]], and [[Module:Utils]].

			Modules that serve as libraries for multiple, related templates may provide multiple wrapper functions. If a module provides multiple wrappers that each call a corresponding function, the name of the function called within the wrapper must be prefixed with an underscore.<syntaxhighlight lang="lua">-- MAIN FUNCTIONS
			-- Usable by other modules

			function p._clamp(arg1, arg2, arg3)
			-- Code goes here
			end

			function p._truncate(arg1)
			-- Code goes here
			end

			-- WRAPPER FUNCTIONS
			-- Usable by templates with {{#invoke}}

			function p.clamp(frame)
			return p._clamp(frame.args["arg1"], frame.args["arg2"], frame.args["arg3"])
			end

	* Modules that serve as libraries for other modules; in such cases, there is no wrapper function other than the tester function. ~~Example: [[Module:MOS]] and [[Module:Rational]]~~		function p.truncate(frame)
	* Modules that provide multiple functions, including wrapper functions, meant to be invoked by multiple templates; in such cases, the rule regarding one wrapper for one template does not apply. ~~Example:~~ [~~[Module:Rational]] and [[Module:Utils]~~]		return p._truncate(frame.args["arg1"])
	* Modules that provide ~~only~~ one function ~~for other modules; in such cases, no wrapper functions are necessary. Example: [[Module:Yesno]]~~		end</syntaxhighlight>Modules that only provide one function may simply consist of that function as a return value. Example: [[Module:Yesno]].
	* Template-based modules where writing a separate "main" function ~~produces~~ a ~~short function; in such cases, the code for that function may be merged with the wrapper function~~. Example: [[Module:~~MOS scalesig~~]]
	* Template-based modules whose wrapper function calls another module's functions; in such cases, no other functions are necessary. ~~Example: [[Module:MOS scalesig]]~~

	==== Helper functions ====		==== Helper functions ====

Ganaram inukshuk: /* Line lengths */

2025-10-16T01:09:30Z

Line lengths

← Older revision		Revision as of 01:09, 16 October 2025
Line 29:		Line 29:
	=== Line lengths ===		=== Line lengths ===

	The 80-column limit ~~is to~~ be observed wherever possible for both comments and code, except for cases where strings, inline comments, or function calls are too long.		The 80-column limit should be observed wherever possible for both comments and code, except for cases where strings, inline comments, or function calls are too long.

	<syntaxhighlight lang="lua">		<syntaxhighlight lang="lua">

Ganaram inukshuk: /* What to pass into a "main" function */

2025-10-16T01:03:36Z

What to pass into a "main" function

← Older revision		Revision as of 01:03, 16 October 2025
Line 103:		Line 103:
	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. A module should only provide '''one''' wrapper for '''one''' template.		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. A module should only provide '''one''' wrapper for '''one''' template.

	~~For testing purposes, a~~ tester function may be added, which is itself a wrapper that calls the "main" function. This allows it to be tested in the in-browser console by calling mw.logObject(p.tester()). Tester functions may be removed if the "main" function is determined to be functional under expected conditions.<syntaxhighlight lang="lua">-- "Main" function to be called by wrapper or another module		A tester function may be added for testing purposes, which is itself a wrapper that also calls the "main" function. This allows it to be tested using the in-browser console by calling mw.logObject(p.tester()). Tester functions may be removed if the "main" function is determined to be functional under expected conditions.<syntaxhighlight lang="lua">-- "Main" function to be called by wrapper or another module
	function p._call_me(args)		function p._call_me(args)
	return "something" .. args["something"]		return "something" .. args["something"]
Line 119:		Line 119:
	end</syntaxhighlight>The guidelines stated above do not apply to the following:		end</syntaxhighlight>The guidelines stated above do not apply to the following:

	* Modules that serve as libraries for other modules; in such cases, there is no wrapper function other than the tester function.		* Modules that serve as libraries for other modules; in such cases, there is no wrapper function other than the tester function. Example: [[Module:MOS]] and [[Module:Rational]]
	* Modules that provide ~~wrappers~~ to ~~several related~~ templates; in such cases, the rule regarding one wrapper for one template does not apply.		* Modules that provide multiple functions, including wrapper functions, meant to be invoked by multiple templates; in such cases, the rule regarding one wrapper for one template does not apply. Example: [[Module:Rational]] and [[Module:Utils]]
	* Modules that provide only one function for other modules; in such cases, no wrapper functions are necessary.		* Modules that provide only one function for other modules; in such cases, no wrapper functions are necessary. Example: [[Module:Yesno]]
	* Template-based modules whose wrapper function calls another module's functions; in such cases, no other functions are necessary.		* Template-based modules where writing a separate "main" function produces a short function; in such cases, the code for that function may be merged with the wrapper function. Example: [[Module:MOS scalesig]]
			* Template-based modules whose wrapper function calls another module's functions; in such cases, no other functions are necessary. Example: [[Module:MOS scalesig]]

	==== Helper functions ====		==== Helper functions ====
Line 139:		Line 140:

	==== What to pass into a "main" function ====		==== What to pass into a "main" function ====
	For an underscore-prefixed "main" function, if its expected inputs is determined to be fixed (for example, no new features are expected to ever be added), the ~~inputs~~ may ~~be passed in one-by-one~~.<syntaxhighlight lang="lua">		For an underscore-prefixed "main" function, if its expected inputs is determined to be fixed (for example, no new features are expected to ever be added), the function may accept them individually.<syntaxhighlight lang="lua">
	-- "Main" function to be called by wrapper or another module		-- "Main" function to be called by wrapper or another module
	function p._call_me(arg1, arg2, arg3)		function p._call_me(arg1, arg2, arg3)
	-- Code goes here		-- Code goes here
	end		end
	</syntaxhighlight>If there is large amounts of input, or if the number of inputs is not known, it should ~~be entered as~~ a table of arguments.<syntaxhighlight lang="lua">		</syntaxhighlight>If there is large amounts of input, or if the number of inputs is not known, the function should have a single parameter that is a table of passed-in arguments.<syntaxhighlight lang="lua">
	-- "Main" function to be called by wrapper or another module		-- "Main" function to be called by wrapper or another module
	function p._call_me(args)		function p._call_me(args)

Ganaram inukshuk: /* What to pass */

2025-10-16T00:37:54Z

What to pass

← Older revision		Revision as of 00:37, 16 October 2025
Line 99:		Line 99:

	===== "Main", wrapper, and tester functions =====		===== "Main", wrapper, and tester functions =====
	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 of the same name but 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. A module should only provide '''one''' wrapper for '''one''' template~~, unless that module is a common library for related templates, or the functions provided are short~~.		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. A module should only provide '''one''' wrapper for '''one''' 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. This allows it to be tested in the in-browser console by calling mw.logObject(p.tester()). Tester functions may be removed if the "main" function is determined to be functional under expected conditions.<syntaxhighlight lang="lua">-- "Main" function to be called by wrapper or another module
	-- "Main" function to be called by wrapper or another module
	function p._call_me(args)		function p._call_me(args)
	return "something" .. args["something"]		return "something" .. args["something"]
Line 118:		Line 117:
	local args = { ["something"] = 123 }		local args = { ["something"] = 123 }
	return p._call_me(args)		return p._call_me(args)
	end		end</syntaxhighlight>The guidelines stated above do not apply to the following:
	</syntaxhighlight>The guidelines stated above do not apply to the following:

	* Modules that serve as libraries for other modules~~. A~~ tester function ~~may still be included~~.		* Modules that serve as libraries for other modules; in such cases, there is no wrapper function other than the tester function.
	* Modules ~~whose functions are short~~, ~~or modules~~ that only ~~provide~~ one function. ~~For such~~ modules ~~used by its corresponding template, the code for the "main" function may be combined with the~~ wrapper function.		* Modules that provide wrappers to several related templates; in such cases, the rule regarding one wrapper for one template does not apply.
			* Modules that provide only one function for other modules; in such cases, no wrapper functions are necessary.
			* Template-based modules whose wrapper function calls another module's functions; in such cases, no other functions are necessary.

	==== Helper functions ====		==== Helper functions ====
Line 138:		Line 138:
	end</syntaxhighlight>		end</syntaxhighlight>

	==== What to pass ====		==== What to pass into a "main" function ====
	~~If a~~ function's expected inputs is determined to be fixed (~~that is~~, no new features are expected to ever be added), the ~~underscore~~-~~prefixed function can accept them in sequence~~.<syntaxhighlight lang="lua">		For an underscore-prefixed "main" function, if its expected inputs is determined to be fixed (for example, no new features are expected to ever be added), the inputs may be passed in one-by-one.<syntaxhighlight lang="lua">
	-- "Main" function to be called by wrapper or another module		-- "Main" function to be called by wrapper or another module
	function p._call_me(arg1, arg2, arg3)		function p._call_me(arg1, arg2, arg3)
	-- Code goes here		-- Code goes here
	end		end
	</syntaxhighlight>If ~~a function expects~~ large amounts of input, or if the number of inputs is not known, it should be entered as a table of arguments ~~into the underscore-prefixed function~~.<syntaxhighlight lang="lua">		</syntaxhighlight>If there is large amounts of input, or if the number of inputs is not known, it should be entered as a table of arguments.<syntaxhighlight lang="lua">
	-- "Main" function to be called by wrapper or another module		-- "Main" function to be called by wrapper or another module
	function p._call_me(args)		function p._call_me(args)

Ganaram inukshuk: /* What to pass */

2025-10-15T21:57:53Z

What to pass

← Older revision		Revision as of 21:57, 15 October 2025
Line 148:		Line 148:
	function p._call_me(args)		function p._call_me(args)
	-- Get args here		-- Get args here
	local ~~args1~~ = args["args1"]		local arg1 = args["args1"]
	local ~~args2~~ = args["args2"]		local arg2 = args["args2"]
	local ~~args3~~ = args["args3"]		local arg3 = args["args3"]

	-- Code goes here		-- Code goes here

Ganaram inukshuk: /* Helper functions */

2025-10-15T21:48:32Z

Helper functions

← Older revision		Revision as of 21:48, 15 October 2025
Line 101:		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.		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. A module should only provide '''one''' wrapper for '''one''' template, unless that module is a common library for related templates, or the functions provided are short.

	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 109:		Line 109:
	end		end

	-- ~~Function~~ to be called by template		-- Wrapper function; to be called by template
	function p.call_me(frame)		function p.call_me(frame)
	return p._call_me(frame.args)		return p._call_me(frame.args)
Line 119:		Line 119:
	return p._call_me(args)		return p._call_me(args)
	end		end
	</syntaxhighlight>~~These~~ guidelines do not apply for ~~simple~~ modules, or modules that only provide one function.		</syntaxhighlight>The guidelines stated above do not apply to the following:

			* Modules that serve as libraries for other modules. A tester function may still be included.
			* Modules whose functions are short, or modules that only provide one function. For such modules used by its corresponding template, the code for the "main" function may be combined with the wrapper function.

	==== Helper functions ====		==== Helper functions ====
	For code readability and code reusability within the module, 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)		Ideally, helper functions should be nested within the calling function if those helpers only serve that function, but 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)
	-- Get args here		-- Get args here
	local arg1 = args["Arg 1"]		local arg1 = args["Arg 1"]
Line 134:		Line 137:
	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.~~

	==== What to pass ====		==== What to pass ====