RuneScape:Lua/Helper modules

From Old School RuneScape Wiki
Jump to navigation Jump to search

This is a table of modules and functions that were created specifically for facilitating the creation of other modules. Documentation for modules here is done in the source code with Template:Helper module.

ModuleFunctionTypeUse
Addcommas_add(arg)NumberFormats the number arg with commas
_strip(arg)NumberRemoves all commas from arg
Chart data_main( args )table/chartTurns a table/chart object into a json string.
convertToXYFormat( ys, [xs|{}] )table, tableConverts the ys array into an array of {x = n, y = y[n]} tables. If xs is already partially filled it will use {x = x[n], y = y[n]} until all values in xs are used, then it will use {x = n, y = y[n]} again for the remaining values in ys.
generateXYFromFunc( func, start_x, end_x, [step|1] )function, number, number, numberReturns an arry of {x = n, y = fun(n)} tables where n ranges from start_x to end_x in step increments. Be careful when using decimal step values as floating point error can cause the generator to stop one element too soon.
jagexInterpolation( low_chance, high_chance, start_level, end_level )number, number, number, number
newChart( [options] )tableReturns a new chart object. options is a table with options in the Chart.js format. Most options will be set automatically or will be set later with other functions if not already defined. Usually all you need to define here is the chart type e.g. newChart{ type = 'scatter' }. Check the modules documentation for more info.
chart:addDataSets( ... )table/dataSet objectAppends all given data sets to the chart.data.datasets table.
chart:addDataLabels( labels )tableAppends all items in labels to the chart.data.labels table.
chart:setDimensions( width, [height|width], [minWidth|400], [minHeight|400], [resizable|false] )number/string, number/string, number/string, number/string, booleanSets the dimensions of the chart. If a number is given to width, height, minWidth and minHeight it will be assumed you meant pixels. You can also use strings like 100% to fill the available space, 40vw/40vh to dynamically scale the simensions to the viewport size (i.e. 40vw = 40% of browser's window width). If resizable is true, the chart can be dragged by the lower right corner to change its size.
chart:setTitle( [text|nil], [position|'top'] )string, stringSets the label title of the chart. A value of nil will remove the current title.
chart:setXLabel( [label|nil] )stringSets the label for the x axis. Only works on chart types 'line', 'bar', 'horizontalBar', 'bubble' and 'scatter'. If used without arguments it will remove the current label.
chart:setYLabel( [label|nil] )stringSets the label for the y axis. Only works on chart types 'line', 'bar', 'horizontalBar', 'bubble' and 'scatter'. If used without arguments it will remove the current label.
chart:setXLimits( [min|nil], [max|nil], [step|nil] )number, number, numberSets the start, stop and step size of the x axis. Any argument with a value of nil will remove that setting. Only works on chart types 'horizontalBar', 'bubble' and 'scatter'.
chart:setYLimits( [min|nil], [max|nil], [step|nil] )number, number, numberSets the start, stop and step size of the y axis. Any argument with a value of nil will remove that setting. Only works on chart types 'line', 'bar', 'bubble' and 'scatter'.
chart:setRadialLimits( [min|nil], [max|nil], [step|nil] )number, number, numberSets the start, stop and step size of the r axis on polar plots. Any argument with a value of nil will remove that setting. Only works on chart types 'radar' and 'polarArea'.
chart:setXAxisType( [type|nil] )stringSets the axis type. Supported values are 'linear', 'logarithmic', 'category' and 'time'. If called without arguments it will reset back to the default value 'linear'. Only works on chart types 'bubble', 'scatter' and 'horizontalBar'.
chart:setYAxisType( [type|nil] )stringSame as chart:setXAxisType() but for the y axis. Only works on chart types 'line', 'bubble', 'scatter' and 'bar'.
chart:setOptions( options )tableSets options using Chart.js format but makes sure you only change the given settings and not accidentally delete already existing settings. i.e. using chart:setOptions{ options = {scales = {ticks = {max = 100}}} } while {options = {scales = {ticks = {min = 0}}}} already exists will result in {options = {scales = {ticks = {min = 0, max = 100}}}}.
chart:makeMwLoadDataCompatible()N/AStrips metatables so that it can be loaded by mw.loadData()making it possible to display the table using {{Chart data|<module name>}}. This should only be used at the very end when you are done creating your chart.
chart:newDataSet( [options] )tableReturns a new dataSet object which is also automatically added to the chart datasets table.
dataSet:addData( data )tableAppends the values of data to the already existing data stored in the dataSet.data array. Using dataset.data = data will overwrite any stored data.
dataSet:addDataPoint( data )number/tableAppend a single value to the dataSet.data array. Same as table.insert( dataSet.data, data ).
dataSet:setOptions( options )tableSets options using Chart.js format.
Clean imageclean(args)stringInput args is a table with fields:
  • file - the full wikitext to be cleaned. All processing is skipped if file is empty or is the string no.
  • width - width to resize the file to; no default
  • height - height to resize the file to, can be combined with width; no default
  • link - what page to link the file to; no default (file will link to file page), 'no' to link to nothing
Coins_amount(coins)NumberReturns a formatted string with a coins icon and the amount of coins. See Template:Coins for examples.
Combat level_calc(attack, strength, defence, ranged, magic, hitpoints, prayer)Number, String, TableReturns three values:
  1. The combat level given the entered stats (Number),
  2. The primary combat type (String: one of 'melee', 'ranged', 'magic'),
  3. And a Table containing the required attackStrength, hitpointsDefence, ranged, magic and prayer levels for the next combat level. These given values will be nil if these levels cannot give another combat levelup on their own.
Currency_amount(num, type)stringTakes the number and formats it with the currency type (coins, nocoins).
DPLluaask( ... )tablesask takes a series of tables each containing the settings for a DPL query; it will return the same number of result tables as input tables. All formatting settings are stripped from the config. If the config does not contains include, the result will be a simple list of page names.
{
	<pagename#1>,
	<pagename#2>,
	<pagename#3>,
}

A query with an include of the form include = '{template#1}:1:2:param1:param2, {template#2}:3:param1, %0' will give a result like

{
	['include'] = {
		['template#1'] = {
			[1] = val#1,
			[2] = val#2,
			['param1'] = val#3,
			['param2'] = val#4,
		},
		['template#2'] = {
			[3] = val#5,
			['param1'] = val#6,
		},
		['%0'] = val#7
	},
	['title'] = <pagename>
}

You can also do include = '{some template}' which will include all parameters of that template in their unexpanded form (templates are not expanded but some content in parser tags is placed in strip markers).

If the config value count is larger than 500 it will automatically generate multiple DPL queries with offsets and their outputs will be combined in the returned result.

The output contains a time field so you don't need to use %DPLTIME%.

If the DPL throws an error it will be available in the error field of the output.

Differences with normal DPL:

  • All formatting options are ignored
  • Surrogate templates (e.g. include = '{template|other template}' are ignored
  • Using include = '{template}' will include all the arguments of that template instead of expanding the template
  • The parameter count can go higher than 500
  • When the value of a parameter is a table it will be expanded into multiple lines. E.g. doing notcategory = {val#1, val#2} will expand into
|notcategory = val#1
|notcategory = val#2
Note of warning, if you include content containing § symbols the result may be unreliable. If you include a whole template (e.g. include = '{some template}'), content inside strip markers (not nowiki) can't be cleaned up inside lua so pipe characters (|) will be replaced with § characters and the { and } characters are replaced by (U+2774) and (U+2775). Use include = '{some template}, {some template}:1:2:3' instead for the problem parameters.
Edit button(text)stringCreates an edit button for the current page that the module is invoked on

text defaults to "edit"
Enumany(enum, [fn], [clone|false])table, function/nil, boolean/nilLoops over the array part of enum and passes each element as the first argument to fn. If fn returns true for at least one element then any() returns true, otherwise false. If no function is given function(item) return item end is used. If clone is true the input enum is deep copied using mw.clone() before use.
all(enum, [fn], [clone|false])table, function/nil, boolean/nilLoops over the array part of enum and passes each element as the first argument to fn. If fn returns true for all elements then all() returns true, otherwise false. If no function is given function(item) return item end is used.
each(enum, fn, [clone|false])table, function, boolean/nilLoops over the array part of enum and passes each element as the first argument to fn. This function returns nothing.
sum(enum, [clone|false])table, boolean/nilReturns the sum of all array elements in enum.
reduce(enum, fn, [accumulator|enum[1]], [clone|false])table, function, any, boolean/nilLoops over the array part of enum and passes each element as the first argument and accumulator as the second to fn. The return value of fn becomes the new accumulator. The final value of accumulator is returned. If no accumulator is given then the first element in enum is used.
scan(enum, fn, [accumulator|enum[1]], [clone|false])table, function, any, boolean/nilSame as reduce() but each step is appended to a table. This table is then returned.
find(enum, fn, [default|nil], [clone|false])table, function, any, boolean/nilLoops over the array part of enum and passes each element as the first argument to fn. The first element where fn returns true is returned. If no elements passes the test, default is returned.
find_index(enum, fn, [default|nil], [clone|false])table, function, any, boolean/nilLoops over the array part of enum and passes each element as the first argument to fn. The index of the first element where fn returns true is returned. If no elements passes the test, default is returned.
max_by(enum, fn, [clone|false])table, function, boolean/nilLoops over the array part of enum and passes each element as the first argument to fn. max_by() returns two values, the first is the element where fn returned the largest value, the second is this largest value. The > operator is used for the comparisons.
map(enum, fn, [clone|false])table, function, boolean/nilLoops over the array part of enum and passes each element as the first argument to fn. The return value of fn is appended to a new table. This new table is returned.
filter(enum, [fn], [clone|false])table, function/nil, boolean/nilLoops over the array part of enum and passes each element as the first argument to fn. If fn returns true the corresponding element is copied to a new table which is then returned. If no function is given function(item) return item end is used.
reject(enum, [fn], [clone|false])table, function, boolean/nilThe opposite of filter().
split(enum, count, [clone|false])table, number, boolean/nilReturns two tables where the first is equivalent to slice(enum, 1, count) and the second slice(enum, count+1, #enum).
slice(enum, [start|1], [stop|#enum], [clone|false])table, number/nil, number/nil, boolean/nilReturns a table containing all the elements of enum between the start and stop indices. The start and stop indices are inclusive.
take(enum, count, [clone|false])table, number, boolean/nilReturns only the first table of split(enum, count).
take_every(enum, n, [clone|false])table, number, boolean/nilReturns a table containing every nth element of enum.
unique(enum, [fn], [clone|false])table, function/nil, boolean/nilReturns a new table where all duplicate values in enum are removed. In case a duplicate is present, the element with the lowest index will be kept and every subsequent duplicate element is removed. fn can be used to create a custom id for every element so that the result is a table with elements which all create a unique id. If no function is given function(item) return item end is used.
zip(enums, [clone|false])table, boolean/nilGroups elements with the same indexes from different arrays together, i.e. zip{ {a1, a2, a3}, {b1, b2, b3}, {c1, c2} } -> {{a1, b1, c1}, {a2, b2, c2}, {a3, b3}}
intersect(enum1, enum2, [clone|false])table, table, boolean/nilReturns true if both sets have at least one element with equal values.
contains(enum, elem, [clone|false])table, any, boolean/nilReturns true if enum contains elem, otherwise returns false.
take_from(enum, index, count)table, number, numberReturns count number of elements, starting at index
Exchange_price(arg)StringGets the current GE price of item named arg
_price(arg, multi, format, round, default)StringGets the current GE price of item named arg, multiplied by [multi] (default 1), rounded to [round] decimal places (default unrounded), and if [format] is true, formatted with thousands separators (default false). If the item does not exist, an error is thrown, unless [default] is set, in which case it will return the given [default] value.
_value(arg)StringGets the value of item named arg
_highalch(arg)StringGets the high alch value of item named arg, accounting for alch multipliers
_lowalch(arg)StringGets the low alch value of item named arg, accounting for alch multipliers
_alchable(arg)StringGets the alchablility (boolean) of item named arg
_alchmultiplier(arg)StringGets the alchemy multiplier of item named arg (default 0.6)
_limit(arg)StringGets the GE limit of item named arg
_diff(arg, format)StringGets the difference of the current GE price and the previous GE price for item named arg. If format is true, formats the number with thousands separators
_exists(arg)StringChecks if the module for item named arg exists, returns a boolean
FetchItemStatsdefaultVersion(pagename)String, StringReturns a string of the default version (format: Pagename#Versionname) that can be used for further SMW searches. Also returns a wikilink to the matched page name (following redirects from the given pagename, as the second return value.
value(item_smwname)NumberReturns the item value for either the specified SMW version (if the given name links to a specific item), or the version that is shown on the page by default (the same version as returned by defaultVersion.
equipmentStats(
{item1_smwname, ...},
{sort_key1, ...},
{sort_order1, ...}
)
{ Table1, Table2, ... }Fetches all item stats for a list of given SMW names. If an ambiguous item name is given anywhere in this list (i.e. one that has different versions), this function will not automatically pick the one that would otherwise be chosen by defaultVersion. A specific SMW name needs to be entered for this function.

Sort keys and sort orders may be provided as optional second and third arguments. No custom sorting will be applied if these arrays are empty or nil. Note that Semantic MediaWiki queries automatically sort the output pages based on alphabetical pagename order. If no sorting should be applied whatsoever, set sort_key1 to something recognised as being falsy (e.g. {'no'}).

Possible sorting orders are: 'ascending', 'asc', 'descending', 'desc', 'reverse', 'random' and 'rand'.

The returned stats are formatted as a Table containing a single Table for each of the items, in the order given by the sort keys, or the default SMW sorting. The stats that are returned in each of these Tables are:

{
    astab  = 'Stab attack bonus',
    aslash = 'Slash attack bonus',
    acrush = 'Crush attack bonus',
    amagic = 'Magic attack bonus',
    arange = 'Range attack bonus',
    dstab  = 'Stab defence bonus',
    dslash = 'Slash defence bonus',
    dcrush = 'Crush defence bonus',
    dmagic = 'Magic defence bonus',
    drange = 'Range defence bonus',
    str    = 'Strength bonus',
    mdmg   = 'Magic Damage bonus',
    rstr   = 'Ranged Strength bonus',
    prayer = 'Prayer bonus',
    weight = 'Weight',
    image  = 'Image',
    subobj = 'Has subobject'
}
Mainonly_main(arg)Any valueIf the module is invoked in the content namespace, it will return arg, otherwise, it will return an empty string
on_main()N/AReturns true if invoked in the content namespace, otherwise false
MergeArgsmergeFrameMerges the parent and frame args returning a table containing the arg values instead of an empty table with an attached metatable. Parent args overwrite invoke args allowing invoke args to be used as a "default" value for an argument.
Mw.html extensionaddClassIf(cond, class)boolean, stringIf cond = true it behaves the same as the normal addClass function, otherwise it's a no-op. Ex.: mw.html.create('div'):addClassIf(true, 'align-left-1')
attrIf(cond, name, value)boolean, string/table, string/nilSimilar to addClassIf
cssIf(cond, name, value)boolean, string/table, string/nilSimilar to addClassIf
doneIf(cond)booleanSimilar to addClassIf
tagIf(cond, tag)boolean, stringSimilar to addClassIf
wikitextIf(cond, text)boolean, stringSimilar to addClassIf
na()N/AShortcut for :tag('td'):attr('data-sort-value', 0):attr('class','table-na'):wikitext('<small>N/A</small>'):done()
naIf(cond)booleanSimilar to addClassIf
tr([settings])table/nilShortcut for :tag('tr') but also auto closes the previous 'tr', 'th' or 'td' tag (so you don't need to add :done() before it). settings is a table with keys:
  • class or addClass - A string passed to :addClass()
  • attr - A table passed to :attr()
  • css - A table passed to :css()
  • cssText - A string passed to :cssText()
th([settings])string/table/nilShortcut for :tag('th'):wikitext(settings) if settings is a string. Also auto closes the previous 'th' or 'td' tag. settings can also be a table with keys:
  • [1] (array) or wikitext - A string passed to :wikitext()
  • class or addClass - A string passed to :addClass()
  • attr - A table passed to :attr()
  • css - A table passed to :css()
  • cssText - A string passed to :cssText()
td([settings])string/table/nilSame as :th(). Example:
local tbl = mw.html.create('table')
tbl:tr{ class='sortable' }
        :th{'foo', attr={'data-sort-type', 'number'}}
        :th('bar')
    :tr()
        :td('buz')
            :attr('data-sort-value', 10)
        :td{'N/A', class='table-na'}
IF(cond)booleanAllows for if-blocks without breaking the chain. If the condition is true it is a no-op, if false everything inside the balanced IF-END block will be ignored. Can be nested. Ex.:
mw.html.create('div')
    :IF(true)
        :wikitext('Conditional text')
    :END()
    :...

Note: This only prevents elements from being added to your html object, it does not protect against statements that throw errors. I.e

mw.html.create('div')
    :IF(false)
        :wikitext(5 * nil) -- This will still throw an error
    :END()
ELSEIF(cond)booleanUsed together with IF().
ELSE()N/AUsed together with IF().
END()N/AUsed together with IF(). Make sure the IF-END tags are balanced, it wont throw an error if they are not.
exec(func, ...)function, anyCall a function without breaking the chain. See module docs for more info.
addFunction(func, name)function, stringAdd a function to the mw.html class that can then be used on mw.html object. See module docs for more info.
Number_round(num, dp)float, intRounds num to a precision given by dp, if dp is not specified, it defaults to zero. Rounds half up.
_short(str)StringConvert numbers ending in k, m or b to the actual correct number. Example: 3.5k -> 3500
PageListToolspageswithcats(cats, [logging])table, boolean/nilReturns a list of pages with the specified categories. Uses SMW.
Each entry can consist of several categories AND-ed together with ' '.
pageswithconditions(conditions, [logging])string, boolean/nilReturns a list of pages that satisfies the given SMW conditions.
pagelistchecks(pages, [logging])table, boolean/nilGiven a list of pages, this function returns lists of pages that are either non-existing (invalid), redirects or duplicates.
pageswithcatsdpl(cats, [logging])table, boolean/nilReturns a list of pages with the specified categories. Uses DPL.
Each entry can consist of several categories AND-ed together with '&'.
pageswithconditionsdpl(conditions, [logging])table, boolean/nilReturns a list of pages that satisfies the given DPL conditions.
Paramtestis_empty(arg)StringReturns true if arg is not defined or contains only whitespace
has_content(arg)StringReturns true if arg exists and does not only contain whitespace
default_to(arg1,arg2)String, Any valueIf arg1 exists and does not only contain whitespace, the function returns arg1, otherwise returns arg2
defaults{ {arg1,arg2},...}{String, Any value}...Does the same as default_to() run over every table passed; for technical reasons, all nil are replaced with false
Quantity box_main(quantity)StringTakes inputs and gives outputs like Template:Quantity box. See the template documentation for more info.
Reftag{attr}tableTable of attributes may include:
  • name - A defined name for the ref
  • group - A defined group for the ref
  • text - The text inside the ref tags
  • selfClosing - true or false; whether or not the tag will close itself
Rgbanew( red, [green|0], [blue|0], [alpha|1] );; new( hex )number/string, number/nil, number/nil, number/nilReturns a new rgba object. Values red, green and blue are in the range 0-255; alpha is 0-1. It is also possible to give a hex string e.g. #112233 or #11223344. When converted to a string with tostring( rgba ) it will return a string in the form rgba(r,b,g,a) where r, g, b and a are filled in with numbers.
rgba:lighten( val )numberReturns a new rgba object with its brightness changed. 1 is no change, 0 is complete black, 2 is double brightness, 1.1 is 10% more, 0.5 is halve, etc.
rgba:darken( val )numberReturns a new rgba object with its brightness changed. 1 is no change, 0 is complete white, 2 is halve brightness, 1.1 is 10% darker, 0.5 is double brightness, etc.
rgba:hueRotate( num )numberReturns a new rgba object with its hue num degrees rotated. Decimal values are allowed.
rgba:saturate( val )numberReturns a new rgba object with its saturation changed. 1 is no change, 0 is greyscale, 2 is double saturation, 1.5 is 50% more, etc.
rgba:fade( val )numberReturns a new rgba object with its alpha value set to val. val is clipped to the range 0-1.
rgba:clone()N/AReturns a copy with the same values.
SCP_main(skill, level, link, sort)StringTakes inputs and gives outputs like Template:SCP. See the template documentation for more info.
Tabbertabber({
{"tab 1 label", "tab 1 content"},
{"tab 2 label", "tab 2 content"},
{"etc", "..."},
})
Table, BooleanReturns a preprocessed string of a <tabber> containing each of the specified tabs.
If preprocess is explicitly set to false the tabber will not be processed and instead return a mw.html object. If it is not specified or set to true the tabber will be preprocessed.
Tables_row(row, elts, header)mw.html object, table/string, booleanAdds td or th cells to the html object with the cells data specified by elts. If header = true then all cells added will have the th tag.
_table(table, data)mw.html object, tableAdds tr rows and td/th cells to the html object, the data for the rows and cells is specified by data.
Top icons_main(args)StringReturns a string that adds top icons to the page. args must be a table of arguments. Numbered arguments must have values of rs, rsc, meta or wp. To provide a specific pagename on the top icon link, specify named arguments with those same indices, with the value being the external pagename.
Yesno(arg)Any valueReads arg for yes/no and returns the appropriate boolean or nil
(arg1,arg2)Any value, Any valueReads arg1 for yes/no and returns the appropriate boolean; returns arg2 if arg1 was not an applicable value