Module:Random

Module documentation[view] [edit] [history] [purge]

This module contains a number of functions that use random numbers. It can output random numbers, select a random item from a list, and reorder lists randomly. The randomly reordered lists can be output inline, or as various types of ordered and unordered lists. The available functions are outlined in more detail below.

Number

The number function outputs a random number.

{{#invoke:random|number|m|n|same=yes}} 

The arguments m and n may be omitted, but if specified must be convertible to integers.

• With no arguments, returns a real number in the range $[0,1)$.
• With one argument, returns an integer in the range $[1,m]$, or, if m is negative, $(-m,0]$. If m is equal to 0 or 1, returns 1 (or 0 if $m=-1$).
• With two arguments, returns an integer in the range $[m,n]$. m and n can be either positive or negative. If m is greater than n, returns an integer in the range $[n,m]$ instead.
• If the |same= parameter is set to "yes", "y", "true", or "1", the same random number is returned for each module call on a given page.

Examples()

• {{#invoke:random|number}} → 0.71782873511213
• {{#invoke:random|number|100}} → 42
• {{#invoke:random|number|-100|-50}} → -94
• {{#invoke:random|number|100|same=yes}} → 75
• {{#invoke:random|number|100|same=yes}} → 75

The documentation for this function is partly taken from the Scribunto Lua reference manual, which is in turn based on the Lua 5.1 Reference Manual, available under the MIT License.

Date

The date function outputs a random date.

{{#invoke:random|date|timestamp1|timestamp2|format=date format|same=yes}} 

• If no timestamp arguments are specified, the module outputs a random date in the current year.
• If timestamp1 and timestamp2 are specified, the module outputs a random date between the two timestamps. timestamp1 must be earlier than timestamp2.
• If only timestamp1is specified, the module outputs a random date between the Unix epoch (1 Jan 1970) and the timestamp. timestamp1 must not be earlier than 1 Jan 1970.
• Formatting can be specified with the |format= parameter. The default formatting is "hh:mm, DD Month YYYY (UTC)" (the same as the default Wikipedia timestamp).
• The timestamps and the |format= parameter accept values compatible with the #time parser function. Please see the #time documentation for the full range of possible input values and formatting options.
• If the |same= parameter is set to "yes", "y", "true", or "1", the same date is returned for each module call on a given page.

Examples()

• {{#invoke:random|date}} → 12:50, 09 March 2025 (UTC)
• {{#invoke:random|date|format=F j}} → August 11
• {{#invoke:random|date|1 Jan 1980|31 Dec 1999}} → 08:34, 02 January 1992 (UTC)
• {{#invoke:random|date|1st January 1500|1st January 3000|format=g:i a, l d M Y}} → 6:55 am, Thursday 04 Dec 2081
• {{#invoke:random|date|1970/06/01}} → 20:54, 21 April 1970 (UTC)
• {{#invoke:random|date|same=yes}} → 13:50, 28 September 2025 (UTC)
• {{#invoke:random|date|same=yes}} → 13:50, 28 September 2025 (UTC)

Item

The item function outputs a random item from a list.

{{#invoke:random|item|list item 1|list item 2|list item 3|...|same=yes}} 

If the |same= parameter is set to "yes", "y", "true", or "1", the same item is returned for each module call on a given page.

Example()

• {{#invoke:random|item|egg|beans|sausage|bacon|spam}} → bacon
• {{#invoke:random|item|egg|beans|sausage|bacon|spam|same=yes}} → beans
• {{#invoke:random|item|egg|beans|sausage|bacon|spam|same=yes}} → beans

Setting "same" will make the template select the same number item from each list, even if the things in them are different.

• My {{#invoke:random|item|egg |bean |sausage |bacon |spam |same=yes}} is {{#invoke:random|item|quail |pinto |kielbasa |canadian |spammy|same=yes}} and my {{#invoke:random|item|blegg |blean |blausage |blacon |blam |same=yes}} is {{#invoke:random|item|blail |blinto|blielbasa|blanadian|blammy|same=yes}}

→ My bean is pinto and my blean is blinto.

List

The list function outputs a list in a random order.

{{#invoke:random|list|list item 1|list item 2|list item 3|...|sep=separator|limit=number of items to display|same=yes}} 

Named parameters

• |sep= or |separator= - an optional separator for the list items. Some values are special; see the table below.
• |limit= - the maximum number of list items to display. The lowest possible is 0 and the highest possible is the length of the list.
• |same= - if this is set to "yes", "y", "true", or "1", the list order is the same for each module call on a given page.

Possible separator values

Code	Output
dot	·
pipe	|
comma	,
tpt-languages	⧼tpt-languages-separator⧽
space	a space
newline	a newline character
any other value	other values are used without modification

You cannot input spaces directly to the |sep= parameter due to limitations in MediaWiki's template syntax. However, it is possible to work around this by using HTML entities. You can use   to represent a normal space, and   to represent a non-breaking space.

Examples()

• {{#invoke:random|list|egg|beans|sausage|bacon|spam}} → beanssausagespambaconegg
• {{#invoke:random|list|egg|beans|sausage|bacon|spam|sep=dot}} → spam · bacon · beans · egg · sausage
• {{#invoke:random|list|egg|beans|sausage|bacon|spam|sep=space}} → beans bacon sausage egg spam
• {{#invoke:random|list|egg|beans|sausage|bacon|spam|sep=; }} → beans; bacon; spam; egg; sausage
• {{#invoke:random|list|egg|beans|sausage|bacon|spam|sep=foo}} → eggfoobeansfoobaconfoospamfoosausage
• {{#invoke:random|list|egg|beans|sausage|bacon|spam|limit=3}} → spameggbacon
• {{#invoke:random|list|egg|beans|sausage|bacon|spam|same=yes}} → eggbaconspamsausagebeans
• {{#invoke:random|list|egg|beans|sausage|bacon|spam|same=yes}} → eggbaconspamsausagebeans

Text list

The text_list function outputs a list in a random order, text-style. In other words, it is like the list function, but with a different separator before the last item.

{{#invoke:random|text_list|list item 1|list item 2|list item 3|...|sep=separator|conj=conjunction|limit=number of items to display|same=yes}} 

The separator can be specified with either the |sep= or |separator= parameters; its default value is ", ". The conjunction can be specified with either the |conj= or |conjunction= parameters; its default value is " and ". The separator and the conjunction can be specified with the same values as the separator in the list function.

The maximum number of list items to display can be set with the |limit= parameter. The lowest possible is 0 and the highest possible is the length of the list.

If the |same= parameter is set to "yes", "y", "true", or "1", the list order is the same for each module call on a given page.

Examples()

• {{#invoke:random|text_list|egg|beans|sausage|bacon|spam}} → beans, spam, egg, sausage and bacon
• {{#invoke:random|text_list|egg|beans|sausage|bacon|spam|sep=; }} → bacon; sausage; beans; egg and spam
• {{#invoke:random|text_list|egg|beans|sausage|bacon|spam|sep=; |conj= or }} → egg; beans; sausage; spam or bacon
• {{#invoke:random|text_list|egg|beans|sausage|bacon|spam|limit=3}} → bacon, spam and sausage
• {{#invoke:random|text_list|egg|beans|sausage|bacon|spam|same=yes}} → egg, bacon, spam, sausage and beans
• {{#invoke:random|text_list|egg|beans|sausage|bacon|spam|same=yes}} → egg, bacon, spam, sausage and beans

HTML lists

If you wish to output an HTML list in a random order, you can choose between five different functions: bulleted_list, unbulleted_list, horizontal_list, ordered_list, and horizontal_ordered_list. These functions all use Module:List.

Function name	Produces	Example code	Example output ()
bulleted_list	Bulleted lists	{{#invoke:random|bulleted_list|egg|sausage|spam}}	spam egg sausage
unbulleted_list	Unbulleted lists	{{#invoke:random|unbulleted_list|egg|sausage|spam}}	sausage spam egg
horizontal_list	Horizontal bulleted lists	{{#invoke:random|horizontal_list|egg|sausage|spam}}	egg sausage spam
ordered_list	Ordered lists (numbered lists and alphabetical lists)	{{#invoke:random|ordered_list|egg|sausage|spam}}	egg spam sausage
horizontal_ordered_list	Horizontal ordered lists	{{#invoke:random|horizontal_ordered_list|egg|sausage|spam}}	egg sausage spam

Basic usage

{{#invoke:random|function|list item 1|list item 2|list item 3|...|limit=number of items to display|same=yes}} 

All parameters

{{#invoke:random|function |first item|second item|third item|... |start = start number for ordered lists |type = type of marker for ordered lists |list_style_type = type of marker for ordered lists (uses CSS) |class = class |style = style |list_style = style for the list |item_style = style for all list items |item_style1 = style for the first list item |item_style2 = style for the second list item |... |indent = indent for horizontal lists }}

The maximum number of list items to display can be set with the |limit= parameter. The lowest possible is 0 and the highest possible is the length of the list.

If the |same= parameter is set to "yes", "y", "true", or "1", the list order is the same for each module call on a given page.

Please see Module:List for a full explanation of the other parameters.

The above documentation is transcluded from Module:Random/doc. (edit | history)
Editors can experiment in this module's sandbox(edit | diff) and testcases(edit) pages.
Subpages of this module.

-- This module contains a number of functions that make use of random numbers.localcfg={}---------------------------------------------------------------------------------------- Configuration---------------------------------------------------------------------------------------- Set this to true if your wiki has a traffic rate of less than one edit every two minutes or so.-- This will prevent the same "random" number being generated many times in a row until a new edit is made-- to the wiki. This setting is only relevant if the |same= parameter is set.cfg.lowTraffic=false-- If cfg.lowTraffic is set to true, and the |same= parameter is set, this value is used for the refresh rate of the random seed.-- This is the number of seconds until the seed is changed. Getting this right is tricky. If you set it too high, the same number-- will be returned many times in a row. If you set it too low, you may get different random numbers appearing on the same page,-- particularly for pages that take many seconds to process.cfg.seedRefreshRate=60---------------------------------------------------------------------------------------- End configuration--------------------------------------------------------------------------------------localp={}-- For functions available from other Lua modules.locall={}-- For functions not available from other Lua modules, but that need to be accessed using table keys.localyesno=require('Module:Yesno')localmakeList=require('Module:List').makeList---------------------------------------------------------------------------------------- Helper functions--------------------------------------------------------------------------------------localfunctionraiseError(msg)-- This helps to generate a wikitext error. It is the calling function's responsibility as to how to include it in the output.returnmw.ustring.format('<b class="error">[[Module:Random]] error: %s.</b>',msg)end---------------------------------------------------------------------------------------- random number function--------------------------------------------------------------------------------------localfunctiongetBigRandom(l,u)-- Gets a random integer between l and u, and is not limited to RAND_MAX.localr=0localn=2^math.random(30)-- Any power of 2.locallimit=math.ceil(53/(math.log(n)/math.log(2)))fori=1,limitdor=r+math.random(0,n-1)/(n^i)endreturnmath.floor(r*(u-l+1))+lendfunctionl.number(args)-- Gets a random number.first=tonumber(args[1])second=tonumber(args[2])-- This needs to use if statements as math.random won't accept explicit nil values as arguments.iffirstthenifsecondtheniffirst>secondthen-- Second number cannot be less than the first, or it causes an error.first,second=second,firstendreturngetBigRandom(first,second)elsereturngetBigRandom(1,first)endelsereturnmath.random()endend---------------------------------------------------------------------------------------- Date function--------------------------------------------------------------------------------------functionl.date(args)-- This function gets random dates, and takes timestamps as positional arguments.-- With no arguments specified, it outputs a random date in the current year.-- With two arguments specified, it outputs a random date between the timestamps.-- With one argument specified, the date is a random date between the unix epoch (1 Jan 1970) and the timestamp.-- The output can be formatted using the "format" argument, which works in the same way as the #time parser function.-- The default format is the standard Wikipedia timestamp.locallang=mw.language.getContentLanguage()localfunctiongetDate(format,ts)localsuccess,date=pcall(lang.formatDate,lang,format,ts)ifsuccessthenreturndateendendlocalfunctiongetUnixTimestamp(ts)localunixts=getDate('U',ts)ifunixtsthenreturntonumber(unixts)endendlocalt1=args[1]localt2=args[2]-- Find the start timestamp and the end timestamp.localstartTimestamp,endTimestampifnott1then-- Find the first and last second in the current year.localcurrentYear=tonumber(getDate('Y'))localcurrentYearStartUnix=tonumber(getUnixTimestamp('1 Jan '..tostring(currentYear)))localcurrentYearEndUnix=tonumber(getUnixTimestamp('1 Jan '..tostring(currentYear+1)))-1startTimestamp='@'..tostring(currentYearStartUnix)-- @ is used to denote Unix timestamps with lang:formatDate.endTimestamp='@'..tostring(currentYearEndUnix)elseift1andnott2thenstartTimestamp='@0'-- the Unix epoch, 1 January 1970endTimestamp=t1elseift1andt2thenstartTimestamp=t1endTimestamp=t2end-- Get Unix timestamps and return errors for bad input (or for bugs in the underlying PHP library, of which there are unfortunately a few)localstartTimestampUnix=getUnixTimestamp(startTimestamp)localendTimestampUnix=getUnixTimestamp(endTimestamp)ifnotstartTimestampUnixthenreturnraiseError('"'..tostring(startTimestamp)..'" was not recognised as a valid timestamp')elseifnotendTimestampUnixthenreturnraiseError('"'..tostring(endTimestamp)..'" was not recognised as a valid timestamp')elseifstartTimestampUnix>endTimestampUnixthenreturnraiseError('the start date must not be later than the end date (start date: "'..startTimestamp..'", end date: "'..endTimestamp..'")')end-- Get a random number between the two Unix timestamps and return it using the specified format.localrandomTimestamp=getBigRandom(startTimestampUnix,endTimestampUnix)localdateFormat=args.formator'H:i, d F Y (T)'localresult=getDate(dateFormat,'@'..tostring(randomTimestamp))ifresultthenreturnresultelsereturnraiseError('"'..dateFormat..'" is not a valid date format')endend---------------------------------------------------------------------------------------- List functions--------------------------------------------------------------------------------------localfunctionrandomizeArray(t,limit)-- Randomizes an array. It works by iterating through the list backwards, each time swapping the entry-- "i" with a random entry. Courtesy of Xinhuan at http://forums.wowace.com/showthread.php?p=279756-- If the limit parameter is set, the array is shortened to that many elements after being randomized.-- The lowest possible value is 0, and the highest possible is the length of the array.locallen=#tfori=len,2,-1dolocalr=math.random(i)t[i],t[r]=t[r],t[i]endiflimitandlimit<lenthenlocalret={}fori,vinipairs(t)doifi>limitthenbreakendret[i]=vendreturnretelsereturntendendlocalfunctionremoveBlanks(t)-- Removes blank entries from an array so that it can be used with ipairs.localret={}fork,vinpairs(t)doiftype(k)=='number'thentable.insert(ret,k)endendtable.sort(ret)fori,vinipairs(ret)doret[i]=t[v]endreturnretendlocalfunctionmakeSeparator(sep)ifsep=='space'then-- Include an easy way to use spaces as separators.return' 'elseifsep=='newline'then-- Ditto for newlinesreturn'\n'elseiftype(sep)=='string'then-- If the separator is a recognised MediaWiki separator, use that. Otherwise use the value of sep if it is a string.localmwseparators={'dot','pipe','comma','tpt-languages'}for_,mwsepinipairs(mwseparators)doifsep==mwsepthenreturnmw.message.new(sep..'-separator'):plain()endendreturnsependendlocalfunctionmakeRandomList(args)locallist=removeBlanks(args)list=randomizeArray(list,tonumber(args.limit))returnlistendfunctionl.item(args)-- Returns a random item from a numbered list.locallist=removeBlanks(args)locallen=#listiflen>=1thenreturnlist[math.random(len)]endendfunctionl.list(args)-- Randomizes a list and concatenates the result with a separator.locallist=makeRandomList(args)localsep=makeSeparator(args.seporargs.separator)returntable.concat(list,sep)endfunctionl.text_list(args)-- Randomizes a list and concatenates the result, text-style. Accepts separator and conjunction arguments.locallist=makeRandomList(args)localsep=makeSeparator(args.seporargs.separator)localconj=makeSeparator(args.conjorargs.conjunction)returnmw.text.listToText(list,sep,conj)endfunctionl.array(args)-- Returns a Lua array, randomized. For use from other Lua modules.returnrandomizeArray(args.t,args.limit)end---------------------------------------------------------------------------------------- HTML list function--------------------------------------------------------------------------------------functionl.html_list(args,listType)-- Randomizes a list and turns it into an HTML list. Uses [[Module:List]].listType=listTypeor'bulleted'locallistArgs=makeRandomList(args)-- Arguments for [[Module:List]].fork,vinpairs(args)doiftype(k)=='string'thenlistArgs[k]=vendendreturnmakeList(listType,listArgs)end---------------------------------------------------------------------------------------- The main function. Called from other Lua modules.--------------------------------------------------------------------------------------functionp.main(funcName,args,listType)-- Sets the seed for the random number generator and passes control over to the other functions.localsame=yesno(args.same)ifnotsamethen-- Generates a different number every time the module is called, even from the same page.-- This is because of the variability of os.clock (the time in seconds that the Lua script has been running for).math.randomseed(mw.site.stats.edits+mw.site.stats.pages+os.time()+math.floor(os.clock()*1000000000))elseifnotcfg.lowTrafficthen-- Make the seed as random as possible without using anything time-based. This means that the same random number-- will be generated for the same input from the same page - necessary behaviour for some wikicode templates that-- assume bad pseudo-random-number generation.localstats=mw.site.statslocalviews=stats.viewsor0-- This is not always available, so we need a backup.localseed=views+stats.pages+stats.articles+stats.files+stats.edits+stats.users+stats.activeUsers+stats.admins-- Make this as random as possible without using os.time() or os.clock()math.randomseed(seed)else-- Make the random seed change every n seconds, where n is set by cfg.seedRefreshRate.-- This is useful for low-traffic wikis where new edits may not happen very often.math.randomseed(math.floor(os.time()/cfg.seedRefreshRate))endendiftype(args)~='table'thenerror('the second argument to p.main must be a table')endreturnl[funcName](args,listType)end---------------------------------------------------------------------------------------- Process arguments from #invoke--------------------------------------------------------------------------------------localfunctionmakeWrapper(funcName,listType)-- This function provides a wrapper for argument-processing from #invoke.-- listType is only used with p.html_list, and is nil the rest of the time.returnfunction(frame)-- If called via #invoke, use the args passed into the invoking template, or the args passed to #invoke if any exist.-- Otherwise assume args are being passed directly in from the debug console or from another Lua module.localorigArgsifframe==mw.getCurrentFrame()thenorigArgs=frame:getParent().argsfork,vinpairs(frame.args)doorigArgs=frame.argsbreakendelseorigArgs=frameend-- Trim whitespace and remove blank arguments.localargs={}fork,vinpairs(origArgs)doiftype(v)=='string'thenv=mw.text.trim(v)endifv~=''thenargs[k]=vendendreturnp.main(funcName,args,listType)endend-- Process arguments for HTML list functions.localhtmlListFuncs={bulleted_list='bulleted',unbulleted_list='unbulleted',horizontal_list='horizontal',ordered_list='ordered',horizontal_ordered_list='horizontal_ordered'}forfuncName,listTypeinpairs(htmlListFuncs)dop[funcName]=makeWrapper('html_list',listType)end-- Process arguments for other functions.localotherFuncs={'number','date','item','list','text_list'}for_,funcNameinipairs(otherFuncs)dop[funcName]=makeWrapper(funcName)endreturnp