User:Frantik~metawiki/Winter/Language Specification: Difference between revisions

Revision as of 01:14, 30 January 2006

Latest revision as of 05:38, 20 April 2015

(2 intermediate revisions by 2 users not shown)

Line 1:

{{MovedToMediaWiki|Extension:Winter/Language Specification}}

== Syntax ==

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}}

Moved with full history --[[User:HappyDog|HappyDog]] 22:46, 18 December 2006 (UTC)

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 ==

=== #setvar ===

Variables are defined by the command '''setvar'''

Syntax:

{{#'''setvar''' | ''x'' |''value''}}

After execution, variable ''x'' would contain ''value''.

=== #var ===

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'' }}

{| style="border:1px solid black; padding:.5em"

! ''operator'' || Action

|-

| colspan="2" style="background-color:black" |

|-

| = || 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.

|-

| colspan="2" style="background-color:black" |

|-

| colspan="2" | 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.

|-

| colspan="2" style="background-color:black" |

|-

| colspan=2|'''#var''' also supports all operators supported by '''#op'''

|}

==== Shortcut #var syntax ====

*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 ===

Syntax:

{{{#'''unsetvar'''| ''variable'' }}

Removes ''variable'' from the list of variables.

===#isset===

Syntax:

{{#'''isset'''| ''variable'' }}

Returns 1 if ''variable'' is set, otherwise returns 0

== If/then/else and Logical Operators ==

=== #if ===

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 ===

Syntax:

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

{| style="border:1px solid black;padding:.5em"

! ''operator'' || Action

|-

| colspan="2" style="background-color:black" |

|-

| == || 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 ===

Syntax:

{{#'''not''''' | ''param1'' }}

If ''param1'' is true, returns 0, otherwise returns 1

=== #ifeq and #ifneq ===

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 ==

=== #while ===

Syntax:

{{#'''while''' | ''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 ===

Syntax:

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

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

=== #repeat ===

Syntax:

{{#'''repeat''' | ''times'' || ''statement'' }}

Repeats and returns the ''statement'' ''times'' times.

== Defining Functions ==

=== #function ===

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 ==

=== Arithmetic using #op ===

{{#'''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:

{| style="border:1px solid black; padding:.5em"

! ''operator'' || Action

|-

| colspan="2" style="background-color:black" |

|-

| + || returns ''a'' + ''b''

|-

| - || returns ''a'' - ''b''

|-

| * || returns ''a'' * ''b''

|-

| / || returns ''a'' / ''b''

|-

| mod || returns the remainder of ''a'' / ''b''

|}

=== #formula ===

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 from left to right.

Valid formulas:

1 + 2

1 + ( 3 * 4 )

(1 + 2) - (3 + 4)

Invalid:

1+ 2

1 +( 3 + 4)

(1+2)-(3+4)

== String Functions ==

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

=== #substr ===

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 ===

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 ===

Syntax:

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

Replaces ''search'' with ''replace'' in string ''subject'' and returns the value

=== #strlen ===

Syntax:

{{#'''strlen''' | ''string'' }}

Returns the length of the ''string''

=== #preg_replace ===

Syntax:

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

Perform a regular expression search and replace. See [[http://www.php.net/preg_replace PHP's preg_replace]] for more info

==Other functions==

=== #nocache===

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 tome or date information or other dynamic content.

=== #define ===

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 ===

Syntax:

{{#'''default''' | ''varname'' | ''value''}}

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

=== #urlvar ===

Syntax:

{{#'''urlvar''' | ''varname'' }}

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

{{#urlvar | var1 }}

=== #null ===

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 ===

Syntax:

{{#'''noeval''' | ''text'' }}

Returns ''text'', with the characters '''{ | }''' converted to html entities (&amp;123; &amp;124; and &amp;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 &lt;nowinter> tag)

== Escape Characters ==

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

| | |

== &lt;nowinter> ==

Syntax:

&lt;nowinter>

{{#if|1|Hello World}}

&lt;/nowinter>

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

{{#if|1|Hello World}}

(&lt;nowinter> added in version 1.4.1)