Extension:Winter/Documentation

= Welcome to Winter 2.0 =

This is the documentation for Winter v2.0+ and is currently incomplete. The documentation for Winter v1.5 and below is also available.

= Introduction = Winter was created in late 2005 to fill a need for simple scripting on wiki pages. It has since grown to become a full fledged language in its own right. Mostly reminiscent of PHP, it also has a bit of a LISP feel. Version 2.0.0 adds true array capability as well as many new functions (mostly direct wrappers of their PHP namesakes) and operations.

= Installation and Configuration =

Installation

 * 1) Place Winter.php in your wiki's the extensions directory.
 * 2) Add require_once("extensions/Winter.php"); to the bottom of LocalSettings.php.

Configuration
Winter has five options which may be set by defining variables in LocalSettings.php. These options must be set before the require_once(... call is made. The default settings should be acceptable for an average blog, though depending on your needs you may wish to modify them. This is especially if your wiki is heavily used and/or faces risk of DoS attacks.

$wgWinterNamespaces
Allows you to define in which namespaces Winter shall be enabled. Winter is enabled in all namespaces by default. See the list of namespaces to find out which number corresponds to which namespace.

This example disables Winter on Talk and User_talk pages: $wgWinterNamespaces = array( 2 => false, 3 => false);

$wgWinterMaxNesting
Sets the maximum number of nesting levels allowed. Default is 50

$wgWinterMaxNesting = 50;

$wgWinterMaxOperations
Sets the maximum number of operations per script allowed. Default is 10000.

$wgWinterMaxOperations = 10000;

$wgWinterMaxIterations
Set the maximum number of per-loop iterations allowed. Default is 1000

$wgWinterMaxIterations = 1000;

$wgWinterNotAllowed
Defines which functions are now allowed to be used. No functions are blocked by default.

// Default $wgWinterNotAllowed = ""; // Example $wgWinterNotAllowed = "preg_match xml_xpath html_to_xml";

Extending Winter with custom PHP functions
Winter also allows for functions written in PHP to be defined via LocalSettings.php. These functions must be defined after requiring the Winter php file.

$wgWinter->addFunction
Use the method $wgWinter->addFunction to add a custom function definition.

$wgWinter->addFunction('WinterFunction','PHPFunction');

When WinterFunction is called within the Winter script, it will trigger PHP to call the PHP function named PHPFunction. PHPFunction will be passed an array begining with the Winter function name followed by the parameter values.

$wgWinter->showError
$wgWinter->showError returns text formatted like other Winter error messages.

return $wgWinter->showError("There was a problem with a parameter");

Take care to ensure all data is properly formatted so that your script does not cause PHP errors. A Winter error message will appear in line with the rest of the text, as opposed to PHP error messages with end up at the top left (usually underneath the site logo) making the site look very broken.

Example
$wgWinter->addFunction('WinterFunction','PHPFunction');

function PHPFunction($params) {  if (count($params) == 3) {     if ($params[1] == 5) {          // show custom error message global $wgWinter; return $wgWinter->showError("First parameter in $params[0] can't be 5!"); }     else { return "Function $params[0] has two parameters: $params[1] and $params[2]"; }  }   else {  return false // will display general syntax error } }

= Language Specification =

Syntax
Winter functions follow a similar syntax to MediaWiki templates, beginning with double braces.

Any parameter may include nested functions, however the function name may not have nested functions within its text. After execution, the text of the function call will be replaced with its return value.

Like templates, white space surrounding the | character is ignored. Unlike templates, you may also use quotation marks (") to demarcate the beginning and ending of a string. This is useful when you would like to end or begin a parameter with whitespace. Only quotation marks at the end or beginning of a parameter string will have any effect on the string.

---> 'param' ---> 'param' ---> ' param ' ---> ' param' ---> 'par"am '

If all the parameters of a function are a single word without white space or nested functions, the following shortcut may be used:

--->   ---> invalid

Alphanumeric string
Generally speaking, almost all data in Winter is alphanumeric or can be expressed alphanumerically.

Boolean
Not a true data type. The following correspond to false:
 * 0
 * An empty string
 * An empty array

All other values evaluate to true. Functions which return a boolean value will return 0 for false and 1 for true.

List
Not a true data type, but rather an alphanumeric string which is a collection of alphanumeric strings delineated by pipe | characters; the alphanumeric expression of an array.

Array
Arrays are a compound data type consisting of one or more alphanumeric strings or arrays which have a an associated key by which the element is referenced. Arrays can have a maximum of 2 dimensions. Any arrays created having more than 2 dimensions (by copying a 2D array into another array for example) will have the additional dimensions 'flattened' or imploded into a list inside the array.

When an array is used where a string is expected, it is flattened and returned as a list.

Variables
Variables are defined, retrieved and operated on using #var. Undefined variables referenced with #var will be created and set to empty string.

Returns the value of variable var.

Performs an operation

Sets the value and returns it

Sets the value and returns nothing

Array data can also be accessed using #var.

You may also use the new []= operator to assign values to array. Again you may use @ to suppress the return value.

You may also use the depreciated #setvar to set variables and arrays.

Scope
Variables defined within function are local to the function. Variables defined outside of the function cannot be accessed directly inside the function; you must pass the value via function parameter.

Variable shortcut syntax
Variable names can have any characters excluding {. |, and }, though it is recommended to only use characters that are valid for functions in order to use variable shorthand: If an unknown function name is encountered, it will be converted into a variable reference.

The following pairs are equivalent: converted to --> converted to -->

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

Operators
Both #op and #var support all of these operators, exluding the variable assignment operators which are supported by #var only.

{| style="border:1px solid black; padding:.5em" ! operator || Action
 * colspan="2" style="background-color:black" |
 * colspan="2" |
 * colspan="2" |
 * colspan="2" |

Variable assignment operators

 * colspan="2" style="background-color:black" |
 * @ || All of the following assignment operators may be preceded with the @ modifier, which will cause the operation to be silent (ie not return a value).
 * = || Assign value b to variable a and return the value.
 * += || Assign the sum of variable a and value b to variable a and return the value.
 * -= || Assign the difference of variable a and value b to variable a and return the value.
 * *= || Assign the product of variable a and value b to variable a and return the value.
 * /= || Assign the quotient of variable a and value b to variable a and return the value.
 * .= || Assign the concatenation of variable a and value b to variable a and return the value.
 * <- || Copy the contents of var value b to variable a and return value of value b (Useful for copying arrays)
 * <=> || variable a will become an alias for variable value b. In effect they are the same variable with two names.  Returns value.
 * colspan="2" style="background-color:black" |
 * colspan="2" | The following operators do not take a third parameter and do not use the @ modifier
 * ++ || Increment variable a by one and return the value.
 * -- || Decrement variable a by one and return the value.
 * colspan="2" style="background-color:black" |
 * colspan="2" |
 * <- || Copy the contents of var value b to variable a and return value of value b (Useful for copying arrays)
 * <=> || variable a will become an alias for variable value b. In effect they are the same variable with two names.  Returns value.
 * colspan="2" style="background-color:black" |
 * colspan="2" | The following operators do not take a third parameter and do not use the @ modifier
 * ++ || Increment variable a by one and return the value.
 * -- || Decrement variable a by one and return the value.
 * colspan="2" style="background-color:black" |
 * colspan="2" |
 * ++ || Increment variable a by one and return the value.
 * -- || Decrement variable a by one and return the value.
 * colspan="2" style="background-color:black" |
 * colspan="2" |
 * colspan="2" style="background-color:black" |
 * colspan="2" |
 * colspan="2" |
 * colspan="2" |

Arithmetic operators



 * colspan="2" style="background-color:black" |
 * + ||  returns a + b
 * - ||  returns a - b
 * * ||  returns a * b
 * / ||  returns a / b
 * ^ ||  returns the a to the bth power
 * mod || returns the remainder of a / b
 * / ||  returns a / b
 * ^ ||  returns the a to the bth power
 * mod || returns the remainder of a / b
 * ^ ||  returns the a to the bth power
 * mod || returns the remainder of a / b
 * mod || returns the remainder of a / b


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

Bitwise operators

 * colspan="2" style="background-color:black" |
 * & ||  returns bits that are set in both a and b
 * | ||  returns bits that are set in either a or b
 * xor ||  returns bits that are set in either a or b but not both
 * << ||  returns bits of a shifted b steps to the left (each step means "multiply by two")
 * << ||  returns bits of a shifted b steps to the right (each step means "divide by two")
 * colspan="2" style="background-color:black" |
 * colspan="2" |
 * << ||  returns bits of a shifted b steps to the left (each step means "multiply by two")
 * << ||  returns bits of a shifted b steps to the right (each step means "divide by two")
 * colspan="2" style="background-color:black" |
 * colspan="2" |
 * colspan="2" style="background-color:black" |
 * colspan="2" |
 * colspan="2" |
 * colspan="2" |

Logic operators

 * 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
 * }
 * <= || 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
 * }
 * and || Returns 1 if a and b are true
 * or || Returns 1 if a or b are true
 * }
 * }

Control Structures
Control structures affect program flow. The syntax for these commands isslightly modified; instead of using one pipe to delineate fields, a double pipe is used. Begining with Winter 2.0, any field of a structure may contain nested structures.

The following control structures are available in Winter:

#if #for
 * 1) while
 * 2) repeat
 * 1) foreach

#if and #iff
If provides the basic program branching needed in any programming language.

The #if statement is now a true control structure in Winter 2.0 and double pipes must be used. Previously single pipes were used because #if was a function, but all function parameters are evaluated before being passed to the function, so both parameters were evaluated, but only one returned. If you desire this functionality you may use the #iff function, or simply use single pipes with the #if statement; #if will rewrite the statement as an #iff function.

#repeat
A very simple type of loop. #repeat evaluates and returns the expression for count iterations.

#while
Evaluates and returns the expression as long as bool evaluates to true. If the initial value of bool is false the expression will not be evaluated.

#for

 * 1) for is a special kind of while loop. First initialize is evaluated.  Then while bool evaluates to true, expression is evaluated and returned.  Before bool is tested again, step is evaluated.

#foreach
Foreach is for traversing arrays and is similar to its PHP counterpart.

The expression will be evaluated for each value contained within the array. During each iteration certain "magic variables" will be set. The names of those variables depend on if value var name and key var name are set.

Magic variables _key                ---> always contains the text of the key name _value              ---> always contains the value of the specific array item _k OR key var name  ---> contains the text of the key name _v OR value var name ---> contains the value of the specific array item

Functions
Functions are defined using #function.

Any valid Winter code may be contained within a function declaration, including other function declarations. If a function name is already defined, it will be overwritten by the new declaration Variables defined within a function are local to the function only.

Parameters
Parameters are passed to functions via "magic variables" which are set when the program code is evaluated. The variable names are cardinal numbers corresponding to their order in the function call, eg the first parameter is named 1, the 2nd is named 2, and so on.

This example displays a familiar message:

= Function Reference =

#add, #subtract, #multiply, #divide
Each of these four functions have the same syntax and general operation principle; they expect a list of numeric values and perform simple arithmetic on them from left to right.

---> returns sum ---> returns difference {{#multiply | value 1 | value 2 | ... | value n } ---> returns product ---> returns quotient

#op
Performs an operation or operations.

Op also supports a very simple expression syntax (This is identical to #formula in Winter v1)

{#op | simple expression}}

Simple expression is a mathematical expression which expects a very rigid structure:
 * There must be a value on each side of each operator.
 * Each operator and value must be separated by white space.
 * There are only two orders of operations:
 * Operations within matched parentheses are evaluated first, from the innermost set outward.
 * Then operators are evaluated from left to right.

All 3 of these pairs of examples are equivalent:

#array
Creates an array and sets its values

Any element in the list may also define the array key using the => operator.

Examples:

Array foo will contain [0] => "abc" [1] => "123" [yellow] => "banana" [ red ] => " apple "

#array_rand and #array_rand_value
Returns random elements from an array. #array_rand returns the elements as keys, #array_rand_values returns them as values. Both use the same syntax.

---> Returns a single element ---> Returns a list of count number of elements

#count
Returns the number of elements in the array

#sort and other sorting functions
Winter has a number of sorting functions available, all of which operate similarly.

Sorts the contents array variable array name. Returns nothing on success and will display an error message on failure. Sort flags will tell the function to sort primarily either numerically or alphabetically. The two acceptable values are #string or #number.

You may also sort lists which have more than one element. In this case the sorted list will be returned. {{#sort | list })

List of sorting functions
arsort - Reverse sort an array and maintain index association asort  - Sort an array and maintain index association natsort - Natural order sort krsort - Reverse sort an array by key ksort  - Sort an array by key sort   - Sort an array rsort  - Reverse sort an array

Logic Functions
Note: These functions evaluate all parameters regardless of the value returned. They should only be used for simple text substitution.

#iff
Simple if/then/else function. Depreciated in favor of #if

#ifeq and #ifneq
These functions test for equality. Depreciated in favor of #if

#not
Returns the boolean opposite of the value.

#str_replace
Replaces part of a string with another string

Replaces each occurance of needle in haystack with ''replacement.

#strlen
Returns the lenth of the string.

#strpos
Returns the location of a substring in a string

On success a numeric value will be returned. On failure an empty string will be returned.

#strtolower and #strtoupper
Returns a strings with the letters set to the specified case -- specifically lower or upper case

#substr
Returns a specified substring

If the end is not specified, everything from start to the end of the string will be returned. You may also use negative numbers to indicate the counting should be done from the right side of the string, not the left.

#trim, #ltrim and #rtrim
Trims whitespace from the end of a string ---> removes whitespace at the beginning and end of the string ---> removes whitespace at the beginning of the string ---> removes whitespace at the end of the string

#ucfirst
Capitalizes the first letter of the string. {{#ucfirst | string ]}

#isset
Returns 1 if the variable is set, 0 if it is not set

#setvar
Sets the value of a variable or array element. Depreciated in Winter 2.0 in favor of #var operators.

#unsetvar
Destroys a variable.

#var
Returns a variable or array value.

Performs an operation on a variable.

#comment
Alias for #null; evaluates text but returns nothing.

Note: Since the text is still evaluated take care when Winter code is included within the comment.

#debug
Returns some information on the state of the Winter engine including current operation count, nesting level, defined functions and defined variables. Primarily for use while debugging program code.

#default
Sets the default wiki template parameter value if it has not been set by the calling page.

Depreciated in Winter 2.0 in favor of #set_param_default.

#define
Performs a substring replace across the entire wiki page.

Depreciated in Winter 2.0 in favor of #str_replace_all.

#error
Returns a standard formatted Winter error message.

#eval
Evaluates the code contained within. Useful for evaluating complex code which was generated at runtime.

#html_to_xml
Converts HTML tags to tags which are readable using #xml_xpath; specifically it prepends xml_ to the front of any html tag (eg &lt;b> becomes &lt;xml_b>)

#nocache
Prevents the page from being cached so that each time the page is viewed the code must be evaluated again. Necessary for dynamic pages.

#noeval
Converts { | } tags to their html entities, causing Winter to ignore the code but allow it to display correctly on the page.

#null
Evaluates any parameters but returns nothing.

#rand
Returns a random number

The default lower limit is 0 and the default upper limit is the server side PHP configuration setting RAND_MAX.

#set_param_default
Sets the default wiki template parameter value if it has not been set by the calling page.

This function takes the place of #default which has been depreciated in Winter 2.0

#str_replace_all
Performs a substring replace across the entire wiki page text.

This function takes the place of #define which has been depreciated in Winter 2.0

#xml_xpath
Runs an XPath query on XML data and returns the results as a list.