Extension:Winter/Documentation/Winter v1

From MediaWiki.org
Jump to: navigation, search

This is the language specification for Winter v1.0 - v1.5

Syntax[edit | edit source]

Winter functions follow a similar syntax to Wikipedia templates. The only difference is Winter functions are preceded by a #. The following is an example:

{{#command|param1|param2}}

Like templates, whitespace surrounding the | character is ignored. However, unlike templates, you may also use quotation marks (") to demarcate a string. This is useful when you would like to end or begin a parameter with whitespace. In the following example, param1 and param3 are equivalent.

{{#command|param1| " param2 " | param3 }}

After execution, the text of the function will be replaced with its return value. This allows for nesting of functions.

{{#command | param1 | {{#command2 | param1 | param2 }}}}

Commands that have a single parameter whose value is nothing can be written as

{{#command}}

Commands that take parameters which do not contain white space can be written as

{{#command param1 param2 param3}}

Variables, once defined, can be written as

{{#varname}}

Variables[edit | edit source]

#setvar[edit | edit source]

Variables are defined by the command setvar Syntax:

{{#setvar | x |value}}

After execution, variable x would contain value.

#var[edit | edit source]

Syntax:

{{#var | x }}

#var would return value if the previous setvar command had been issued.


#var and #setvar also provide simple assignment arithmetic. Syntax:

{{#var | x | operator | value }}
operator Action
= Assign value to var x and return the value. (Note: this differs from setvar in that var returns the value assigned, while setvar returns nothing)
+= Assign the sum of var x and value to var x and return the value.
-= Assign the difference of var x and value to var x and return the value.
*= Assign the product of var x and value to var x and return the value.
/= Assign the quotient of var x and value to var x and return the value.
.= Assign the concatenation of var x and value to var x and return the value.
The following operators do not take a third parameter
++ Increment var x by one and return the value.
-- Decrement var x by one and return the value.
#var also supports all operators supported by #op

Shortcut #var syntax[edit | edit source]

  • This feature was added in v1.2

The following pairs are now equivalent, assuming foo has already been defined by a #setvar or #var command:

{{#foo}}                 =  {{#var|foo}}
{{#foo|operator|value}}  =  {{#var|foo|operator|value}}

Variable names must meet the qualifications as a function name to use the shortcut syntax. For example:

{{#var | Var Name | = | 1 }}  ---> valid 
{{#var | VarName | = |1 }}    ---> valid 
{{#Var Name | = | 1 }}        ---> not valid
{{#VarName | = | 1 }}         ---> valid

#unsetvar[edit | edit source]

Syntax:

{{{#unsetvar| variable }}

Removes variable from the list of variables.

#isset[edit | edit source]

Syntax:

{{#isset| variable }}

Returns 1 if variable is set, otherwise returns 0

If/then/else and Logical Operators[edit | edit source]

#if[edit | edit source]

Syntax:

{{#if | expression | true statement }}
{{#if | expression | true statement | falsestatement }}

If expression evaluates to 0, nothing (no space between | characters), or whitespace, it is considered false. Everything else is considered true. If expression is true, true statement is returned. If expression is false, false statement is returned. The third parameter may be omitted if nothing is to be returned if expression is false.


Logical comparisons using #op[edit | edit source]

Syntax:

{{#op | a | operator | b}}
operator Action
== Returns 1 if a is equal to b, otherwise returns 0
 != Returns 1 if a is not equal to b, otherwise returns 0
< Returns 1 if a is less than to b, otherwise returns 0
> Returns 1 if a is greater than to b, otherwise returns 0
<= Returns 1 if a is less than or equal to b
>= Returns 1 if a is greater than or equal to b
and Returns 1 if a and b are true
or Returns 1 if a or b are true

#not[edit | edit source]

Syntax:

{{#not | param1 }}

If param1 is true, returns 0, otherwise returns 1


#ifeq and #ifneq[edit | edit source]

Syntax

{{#ifeq | value1 | value2 | equalstatement  }}
{{#ifeq | value1 | value2 | equalstatement  | notequalstatement }}

There are also two shortcut functions, ifeq and ifneq, to make common logic tests easier to type. The following pairs are equivalent

{{#ifeq | value1 | value2 | equalstatement | notequalstatement }}
{{#if | {{#op | value1 | == | value2 }} | equalstatement | notequalstatement }}
{{#ifneq | value1 | value2 | notequalstatement | equalstatement }}
{{#if | {{#op | value1 | != | value2 }} | notequalstatement | equalstatement }}

Loops[edit | edit source]

Please note that #while, #for, #repeat and #function use modified syntax: They require double pipes (||) in between parameters.

#while[edit | edit source]

Syntax: Media file link| expression || statement }}

Repeats and returns the statement as long as expression evaluates to true (ie, anything other than 0, nothing, or whitespace). expression is evaluated before statement is executed.

#for[edit | edit source]

Syntax:

{{#for | expr1 || expr2 || expr3 || statement}}

Executes expr1, then repeats statement and exp3 until exp2 is not true.

#repeat[edit | edit source]

Syntax:

{{#repeat | times || statement }}

Repeats and returns the statement times times.

Defining Functions[edit | edit source]

#function[edit | edit source]

Syntax:

{{#function | functionname || command block }}

A function, once defined, can be called just like any other function in Winter. Variables set inside a command block are local to the function, and the function cannot access the variables of the main script. To access the parameters of the function, use {{#var|1}}, {{#var|2}}, .. {{#var|n}}

Example:

{{#function | foo || foo{{#var|1}}bar{{#var|2}} }}
{{#foo|123|ABC}}

returns

foo123barABC

Please note that #while, #for and #function use modified syntax.. they require double pipes (||) in between parameters.

Arithmetic[edit | edit source]

Arithmetic using #op[edit | edit source]

{{#op | a | operator | b }}

In 1.5.0 and higher, you may have any amount of operations. {{#op | 1 | + | 2 | +| 3 | + | 4... etc}}. The order of operations is from left to right.

operator can be any of the following:

operator Action
+ returns a + b
- returns a - b
* returns a * b
/ returns a / b
mod returns the remainder of a / b

#formula[edit | edit source]

Syntax:

{{#formula | formula}}

formula is a string made up of values, operators, and parentheses. There must be whitespace on either side of all operators. The order of operations is parentheses, then left to right.

Valid formulas:

1 + 2             
1 + ( 3 * 4 )     
(1 + 2) - (3 + 4)

Invalid:

1+ 2
1 +( 3 + 4)
(1+2)-(3+4)

Strings[edit | edit source]

Strings can be used in Winter without quotation marks. The first non-whitespace character after a pipe (|) is considered the beginning of the string, and the end of the string is the last non-white character before a pipe or closing double brace (}}).

If you would like to start or end the string with a whitespace, use a quotation marks. Quotation marks do not need to be matched.

Valid string syntax:

{{#setval| a | This is a string }}      => a == "This is a string"
{{#setval| a | "This is a string" }}    => a == "This is a string"
{{#setval| a | " This is a string }}    => a == " This is a string"
{{#setval| a | This is a string " }}    => a == "This is a string "
{{#setval| a | " This is a string " }}  => a == " This is a string "

The string functions are analogs of the php functions which share their names.

#substr[edit | edit source]

Syntax:

{{#substr | string | start }}
{{#substr | string | start | end }}

If no end is specified, will return to the end of the string. Negative values may be used.

#strpos[edit | edit source]

Syntax

{{#strpos | haystack | needle }}

Returns the position of the first occurence of needle in haystack. If needle doesn't occur in haystack, nothing will be returned (not even a space).

#str_replace[edit | edit source]

Syntax:

{{#str_replace | search | replace | subject }}

Replaces search with replace in string subject and returns the value

#strlen[edit | edit source]

Syntax:

{{#strlen | string }}

Returns the length of the string

#preg_replace[edit | edit source]

Syntax:

{{#preg_replace | reg_expression | replace | subject }}

Perform a regular expression search and replace. See [PHP's preg_replace] for more info

Other functions[edit | edit source]

#nocache[edit | edit source]

Syntax:

{{#nocache}}

Stops the generated output from being cached. This is useful for pages which must alway be generated when they are viewed, such as those that include time or date information or other dynamic content.

#define[edit | edit source]

Syntax:

{{#define | text | macro }}

Similar to the #DEFINE function in C, #define replaces all instances of text with macro. Unlike C macros, they can be defined anywhere and affect both output and program code. text and macro are not evaluated before being applied.

#default[edit | edit source]

Syntax:

{{#default | varname | value}}

Assigns template parameters (eg {{{1}}} a default value. This value will only be assigned if the parameter is not set when the template is called.

#urlvar[edit | edit source]

Syntax:

{{#urlvar | varname }}

Returns the value of the variable defined in the url. For example, if a page was called like thisTemplate:nonexistent?var1=value1, value1 would be returned by:

{{#urlvar | var1 }}

#null[edit | edit source]

Syntax:

{{#null | statement }}

Executes the statement and returns NULL. Useful for executing commands without returning a value, or for text comments. If you wish stop a block of code from executing, use {{#if|0|block of code}} instead.

#noeval[edit | edit source]

Syntax:

{{#noeval | text }}

Returns text, with the characters { | } converted to html entities (&123; &124; and &125; respectively) which allows Winter code to be displayed without being evaluated. #noeval will stop at the first unmatched }} so if you wish to display invalid code you may need to use escape characters or html entities.

(#noeval was added in version 1.4.0, but is depreciated in 1.4.1 in favor of the <nowinter> tag)

Escape Characters[edit | edit source]

The following escape characters may be used in any expression. They are evaluated after the expression is read but before it is parsed.

Version 1.4.0 and higher

Escape Char  Equivalent
-----------  ----------
^!           |
^(           {
^)           }
^[           {{
^]           }}
^_           ^

Version 1.3 and lower

^^!          |
^^(          {
^^)          }
^^_          ^^


If used inside nested functions, you must escape the character for the level at which you want it to evaluate. For example:

{{#if | 1 | ^_! {{#if | 1 | ^__! {{#if | 1 | ^___! }} }} }}

returns

| | |

<nowinter>[edit | edit source]

Syntax:

<nowinter>
{{#if|1|Hello World}}
</nowinter>

Text placed between <nowinter> and </nowinter> will not be evaluated by Winter. The above code would display

{{#if|1|Hello World}}

(<nowinter> added in version 1.4.1)