Difference between revisions of "Module:Random/doc"
blackwiki>Mr. Stradivarius (add limit parameter) |
blackwiki>Mr. Stradivarius (add |same= parameter) |
||
| Line 7: | Line 7: | ||
The <code>number</code> function outputs a random number. | The <code>number</code> function outputs a random number. | ||
| − | {{#invoke:random|number|''m''|''n''}} | + | {{#invoke:random|number|''m''|''n''|same=''yes''}} |
The arguments <code>m</code> and <code>n</code> may be omitted, but if specified must be convertible to integers. | The arguments <code>m</code> and <code>n</code> may be omitted, but if specified must be convertible to integers. | ||
| Line 13: | Line 13: | ||
* With one argument, returns an integer in the range <math>[1,m]</math>. <code>''m''</code> must be positive. | * With one argument, returns an integer in the range <math>[1,m]</math>. <code>''m''</code> must be positive. | ||
* With two arguments, returns an integer in the range <math>[m,n]</math>. <code>''m''</code> and <code>''n''</code> can be either positive or negative. If <code>''m''</code> is greater than <code>''n''</code>, returns an integer in the range <math>[n,m]</math> instead. | * With two arguments, returns an integer in the range <math>[m,n]</math>. <code>''m''</code> and <code>''n''</code> can be either positive or negative. If <code>''m''</code> is greater than <code>''n''</code>, returns an integer in the range <math>[n,m]</math> instead. | ||
| + | * If the {{para|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''' <small>({{purge|refresh|anchor=Number}})</small> | '''Examples''' <small>({{purge|refresh|anchor=Number}})</small> | ||
| Line 19: | Line 20: | ||
* <code><nowiki>{{#invoke:random|number|100}}</nowiki></code> → {{#invoke:random|number|100}} | * <code><nowiki>{{#invoke:random|number|100}}</nowiki></code> → {{#invoke:random|number|100}} | ||
* <code><nowiki>{{#invoke:random|number|-100|-50}}</nowiki></code> → {{#invoke:random|number|-100|-50}} | * <code><nowiki>{{#invoke:random|number|-100|-50}}</nowiki></code> → {{#invoke:random|number|-100|-50}} | ||
| + | * <code><nowiki>{{#invoke:random|number|100|same=yes}}</nowiki></code> → {{#invoke:random|number|100|same=yes}} | ||
| + | * <code><nowiki>{{#invoke:random|number|100|same=yes}}</nowiki></code> → {{#invoke:random|number|100|same=yes}} | ||
<small>The documentation for this function is partly taken from the [[mw:Extension:Scribunto/Lua reference manual#math.random|Scribunto Lua reference manual]], which is in turn based on the [http://www.lua.org/manual/5.1/index.html Lua 5.1 Reference Manual], available under the [[MIT License]].</small> | <small>The documentation for this function is partly taken from the [[mw:Extension:Scribunto/Lua reference manual#math.random|Scribunto Lua reference manual]], which is in turn based on the [http://www.lua.org/manual/5.1/index.html Lua 5.1 Reference Manual], available under the [[MIT License]].</small> | ||
| Line 26: | Line 29: | ||
The <code>date</code> function outputs a random date. | The <code>date</code> function outputs a random date. | ||
| − | {{#invoke:random|date|''timestamp1''|''timestamp2''|format=''date format''}} | + | {{#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 no timestamp arguments are specified, the module outputs a random date in the current year. | ||
| Line 33: | Line 36: | ||
* Formatting can be specified with the {{para|format}} parameter. The default formatting is "hh:mm, DD Month YYYY (UTC)" (the same as the default Wikipedia timestamp). | * Formatting can be specified with the {{para|format}} parameter. The default formatting is "hh:mm, DD Month YYYY (UTC)" (the same as the default Wikipedia timestamp). | ||
* The timestamps and the {{para|format}} parameter accept values compatible with the [[mw:Help:Extension:ParserFunctions##time|#time parser function]]. Please see the #time documentation for the full range of possible input values and formatting options. | * The timestamps and the {{para|format}} parameter accept values compatible with the [[mw:Help:Extension:ParserFunctions##time|#time parser function]]. Please see the #time documentation for the full range of possible input values and formatting options. | ||
| + | * If the {{para|same}} parameter is set to "yes", "y", "true", or "1", the same date is returned for each module call on a given page. | ||
'''Examples''' <small>({{purge|refresh|anchor=Date}})</small> | '''Examples''' <small>({{purge|refresh|anchor=Date}})</small> | ||
| Line 41: | Line 45: | ||
* <code><nowiki>{{#invoke:random|date|1st January 1500|1st January 3000|format=g:i a, l d M Y}}</nowiki></code> → {{#invoke:random|date|1st January 1500|1st January 3000|format=g:i a, l d M Y}} | * <code><nowiki>{{#invoke:random|date|1st January 1500|1st January 3000|format=g:i a, l d M Y}}</nowiki></code> → {{#invoke:random|date|1st January 1500|1st January 3000|format=g:i a, l d M Y}} | ||
* <code><nowiki>{{#invoke:random|date|1970/06/01}}</nowiki></code> → {{#invoke:random|date|1970/06/01}} | * <code><nowiki>{{#invoke:random|date|1970/06/01}}</nowiki></code> → {{#invoke:random|date|1970/06/01}} | ||
| + | * <code><nowiki>{{#invoke:random|date|same=yes}}</nowiki></code> → {{#invoke:random|date|same=yes}} | ||
| + | * <code><nowiki>{{#invoke:random|date|same=yes}}</nowiki></code> → {{#invoke:random|date|same=yes}} | ||
== Item == | == Item == | ||
| Line 46: | Line 52: | ||
The <code>item</code> function outputs a random item from a list. | The <code>item</code> function outputs a random item from a list. | ||
| − | {{#invoke:random|item|''list item 1''|''list item 2''|''list item 3''|...}} | + | {{#invoke:random|item|''list item 1''|''list item 2''|''list item 3''|...|same=''yes''}} |
| + | |||
| + | If the {{para|same}} parameter is set to "yes", "y", "true", or "1", the same item is returned for each module call on a given page. | ||
'''Example''' <small>({{purge|refresh|anchor=Item}})</small> | '''Example''' <small>({{purge|refresh|anchor=Item}})</small> | ||
* <code><nowiki>{{#invoke:random|item|egg|beans|sausage|bacon|spam}}</nowiki></code> → {{#invoke:random|item|egg|beans|sausage|bacon|spam}} | * <code><nowiki>{{#invoke:random|item|egg|beans|sausage|bacon|spam}}</nowiki></code> → {{#invoke:random|item|egg|beans|sausage|bacon|spam}} | ||
| + | * <code><nowiki>{{#invoke:random|item|egg|beans|sausage|bacon|spam|same=yes}}</nowiki></code> → {{#invoke:random|item|egg|beans|sausage|bacon|spam|same=yes}} | ||
| + | * <code><nowiki>{{#invoke:random|item|egg|beans|sausage|bacon|spam|same=yes}}</nowiki></code> → {{#invoke:random|item|egg|beans|sausage|bacon|spam|same=yes}} | ||
== List == | == List == | ||
| Line 56: | Line 66: | ||
The <code>list</code> function outputs a list in a random order. | The <code>list</code> 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''}} | + | {{#invoke:random|list|''list item 1''|''list item 2''|''list item 3''|...|sep=''separator''|limit=''number of items to display''|same=''yes''}} |
'''Named parameters''' | '''Named parameters''' | ||
* {{para|sep}} or {{para|separator}} - an optional separator for the list items. Some values are special; see the table below. | * {{para|sep}} or {{para|separator}} - an optional separator for the list items. Some values are special; see the table below. | ||
* {{para|limit}} - the maximum number of list items to display. The lowest possible is 0 and the highest possible is the length of the list. | * {{para|limit}} - the maximum number of list items to display. The lowest possible is 0 and the highest possible is the length of the list. | ||
| + | * {{para|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. | ||
{| class="wikitable" | {| class="wikitable" | ||
| Line 91: | Line 102: | ||
* <code><nowiki>{{#invoke:random|list|egg|beans|sausage|bacon|spam|sep=foo}}</nowiki></code> → {{#invoke:random|list|egg|beans|sausage|bacon|spam|sep=foo}} | * <code><nowiki>{{#invoke:random|list|egg|beans|sausage|bacon|spam|sep=foo}}</nowiki></code> → {{#invoke:random|list|egg|beans|sausage|bacon|spam|sep=foo}} | ||
* <code><nowiki>{{#invoke:random|list|egg|beans|sausage|bacon|spam|limit=3}}</nowiki></code> → {{#invoke:random|list|egg|beans|sausage|bacon|spam|limit=3}} | * <code><nowiki>{{#invoke:random|list|egg|beans|sausage|bacon|spam|limit=3}}</nowiki></code> → {{#invoke:random|list|egg|beans|sausage|bacon|spam|limit=3}} | ||
| + | * <code><nowiki>{{#invoke:random|list|egg|beans|sausage|bacon|spam|same=yes}}</nowiki></code> → {{#invoke:random|list|egg|beans|sausage|bacon|spam|same=yes}} | ||
| + | * <code><nowiki>{{#invoke:random|list|egg|beans|sausage|bacon|spam|same=yes}}</nowiki></code> → {{#invoke:random|list|egg|beans|sausage|bacon|spam|same=yes}} | ||
== Text list == | == Text list == | ||
| Line 96: | Line 109: | ||
The <code>text_list</code> function outputs a list in a random order, text-style. In other words, it is like the <code>list</code> function, but with a different separator before the last item. | The <code>text_list</code> function outputs a list in a random order, text-style. In other words, it is like the <code>list</code> 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''}} | + | {{#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 {{para|sep}} or {{para|separator}} parameters; its default value is "{{int:comma-separator}}". The conjunction can be specified with either the {{para|conj}} or {{para|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|list function]]. | The separator can be specified with either the {{para|sep}} or {{para|separator}} parameters; its default value is "{{int:comma-separator}}". The conjunction can be specified with either the {{para|conj}} or {{para|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|list function]]. | ||
The maximum number of list items to display can be set with the {{para|limit}} parameter. The lowest possible is 0 and the highest possible is the length of the list. | The maximum number of list items to display can be set with the {{para|limit}} parameter. The lowest possible is 0 and the highest possible is the length of the list. | ||
| + | |||
| + | If the {{para|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''' <small>({{purge|refresh|anchor=Text list}})</small> | '''Examples''' <small>({{purge|refresh|anchor=Text list}})</small> | ||
| Line 108: | Line 123: | ||
* <code><nowiki>{{#invoke:random|text_list|egg|beans|sausage|bacon|spam|sep=;&#32;|conj=&#32;or&#32;}}</nowiki></code> → {{#invoke:random|text_list|egg|beans|sausage|bacon|spam|sep=; |conj= or }} | * <code><nowiki>{{#invoke:random|text_list|egg|beans|sausage|bacon|spam|sep=;&#32;|conj=&#32;or&#32;}}</nowiki></code> → {{#invoke:random|text_list|egg|beans|sausage|bacon|spam|sep=; |conj= or }} | ||
* <code><nowiki>{{#invoke:random|text_list|egg|beans|sausage|bacon|spam|limit=3}}</nowiki></code> → {{#invoke:random|text_list|egg|beans|sausage|bacon|spam|limit=3}} | * <code><nowiki>{{#invoke:random|text_list|egg|beans|sausage|bacon|spam|limit=3}}</nowiki></code> → {{#invoke:random|text_list|egg|beans|sausage|bacon|spam|limit=3}} | ||
| + | * <code><nowiki>{{#invoke:random|text_list|egg|beans|sausage|bacon|spam|same=yes}}</nowiki></code> → {{#invoke:random|text_list|egg|beans|sausage|bacon|spam|same=yes}} | ||
| + | * <code><nowiki>{{#invoke:random|text_list|egg|beans|sausage|bacon|spam|same=yes}}</nowiki></code> → {{#invoke:random|text_list|egg|beans|sausage|bacon|spam|same=yes}} | ||
== HTML lists == | == HTML lists == | ||
| Line 148: | Line 165: | ||
; Basic usage | ; Basic usage | ||
| − | {{#invoke:random|''function''|''list item 1''|''list item 2''|''list item 3''|...|limit=''number of items to display''}} | + | {{#invoke:random|''function''|''list item 1''|''list item 2''|''list item 3''|...|limit=''number of items to display''|same=''yes''}} |
; All parameters | ; All parameters | ||
| Line 168: | Line 185: | ||
The maximum number of list items to display can be set with the {{para|limit}} parameter. The lowest possible is 0 and the highest possible is the length of the list. | The maximum number of list items to display can be set with the {{para|limit}} parameter. The lowest possible is 0 and the highest possible is the length of the list. | ||
| + | |||
| + | If the {{para|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. | Please see [[Module:List]] for a full explanation of the other parameters. | ||
Revision as of 07:55, 2 December 2013
| This module is rated as alpha. It is ready for third-party input, and may be used on a few pages to see if problems arise, but should be watched. Suggestions for new features or changes in their input and output mechanisms are welcome. |
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.
Contents
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 <math>[0,1)</math>.
- With one argument, returns an integer in the range <math>[1,m]</math>.
mmust be positive. - With two arguments, returns an integer in the range <math>[m,n]</math>.
mandncan be either positive or negative. Ifmis greater thann, returns an integer in the range <math>[n,m]</math> 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 (Script error: No such module "Purge".)
{{#invoke:random|number}}→ 0.80099995471584{{#invoke:random|number|100}}→ 92{{#invoke:random|number|-100|-50}}→ -98{{#invoke:random|number|100|same=yes}}→ 33{{#invoke:random|number|100|same=yes}}→ 33
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
timestamp1andtimestamp2are specified, the module outputs a random date between the two timestamps.timestamp1must be earlier thantimestamp2. - If only
timestamp1is specified, the module outputs a random date between the Unix epoch (1 Jan 1970) and the timestamp.timestamp1must 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 (Script error: No such module "Purge".)
{{#invoke:random|date}}→ 02:07, 26 December 2025 (UTC){{#invoke:random|date|format=F j}}→ August 18{{#invoke:random|date|1 Jan 1980|31 Dec 1999}}→ 17:38, 02 October 1981 (UTC){{#invoke:random|date|1st January 1500|1st January 3000|format=g:i a, l d M Y}}→ 1:39 am, Thursday 19 Oct 1606{{#invoke:random|date|1970/06/01}}→ 20:43, 18 January 1970 (UTC){{#invoke:random|date|same=yes}}→ 15:33, 30 April 2025 (UTC){{#invoke:random|date|same=yes}}→ 15:33, 30 April 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 (Script error: No such module "Purge".)
{{#invoke:random|item|egg|beans|sausage|bacon|spam}}→ sausage{{#invoke:random|item|egg|beans|sausage|bacon|spam|same=yes}}→ beans{{#invoke:random|item|egg|beans|sausage|bacon|spam|same=yes}}→ beans
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.
| Code | Output |
|---|---|
dot |
⧼dot-separator⧽ |
pipe
|
| |
comma |
, |
tpt-languages |
• |
space |
a space |
| 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 (Script error: No such module "Purge".)
{{#invoke:random|list|egg|beans|sausage|bacon|spam}}→ sausagespameggbaconbeans{{#invoke:random|list|egg|beans|sausage|bacon|spam|sep=dot}}→ egg⧼dot-separator⧽sausage⧼dot-separator⧽spam⧼dot-separator⧽bacon⧼dot-separator⧽beans{{#invoke:random|list|egg|beans|sausage|bacon|spam|sep=space}}→ sausage spam beans bacon egg{{#invoke:random|list|egg|beans|sausage|bacon|spam|sep=; }}→ bacon; beans; sausage; egg; spam{{#invoke:random|list|egg|beans|sausage|bacon|spam|sep=foo}}→ spamfoobeansfoosausagefoobaconfooegg{{#invoke:random|list|egg|beans|sausage|bacon|spam|limit=3}}→ eggbaconsausage{{#invoke:random|list|egg|beans|sausage|bacon|spam|same=yes}}→ eggbaconsausagespambeans{{#invoke:random|list|egg|beans|sausage|bacon|spam|same=yes}}→ eggbaconsausagespambeans
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 (Script error: No such module "Purge".)
{{#invoke:random|text_list|egg|beans|sausage|bacon|spam}}→ sausage, beans, egg, spam and bacon{{#invoke:random|text_list|egg|beans|sausage|bacon|spam|sep=; }}→ bacon; egg; beans; sausage and spam{{#invoke:random|text_list|egg|beans|sausage|bacon|spam|sep=; |conj= or }}→ sausage; beans; bacon; egg or spam{{#invoke:random|text_list|egg|beans|sausage|bacon|spam|limit=3}}→ spam, bacon and egg{{#invoke:random|text_list|egg|beans|sausage|bacon|spam|same=yes}}→ egg, bacon, sausage, spam and beans{{#invoke:random|text_list|egg|beans|sausage|bacon|spam|same=yes}}→ egg, bacon, sausage, spam 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 (Script error: No such module "Purge".) |
|---|---|---|---|
bulleted_list
|
Bulleted lists | {{#invoke:random|bulleted_list|egg|sausage|spam}}
|
|
unbulleted_list
|
Unbulleted lists | {{#invoke:random|unbulleted_list|egg|sausage|spam}}
|
|
horizontal_list
|
Horizontal bulleted lists | {{#invoke:random|horizontal_list|egg|sausage|spam}}
|
|
ordered_list
|
Ordered lists (numbered lists and alphabetical lists) | {{#invoke:random|ordered_list|egg|sausage|spam}}
|
|
horizontal_ordered_list
|
Horizontal ordered lists | {{#invoke:random|horizontal_ordered_list|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
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.