Extension:Winter/Documentation

Welcome to Winter 2.0
This is the documentation for Winter v2.0+. 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

 * 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 four 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.

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

Syntax
Winter functions follow a similar syntax to MediaWiki templates, beginning with double braces .The following is an example of how all functions must be formatted:

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 '

Shortcuts
Winter's syntax is very regular to facilitate quick processing, but sometimes this slows down the coding process. All shortcuts are converted into their proper Winter code before being sent to the Winter engine.

No parameters
All functions and variable calls normally require at least one parameter, even if the value is not needed. The following shortcut is available as a work around.

; shortcut for

Single word parameters
If all the parameters of a function are a single word (ie a string bounded by whitespace), the following shortcut may be used:

; shortcut for

#setvar
Variables are created and set by the command setvar Syntax:

After execution, variable x would contain value.


 * Setvar has been mostly depreciated by the @ operator modifier (see below)

#var
Undefined variables called by var will be created and set to empty string.

Syntax: Returns the value of variable x.

#var and #setvar also provide simple assignment arithmetic. Setvar will not return a value, while var will. Syntax:

Shortcut #var syntax
If an unknown function name is encountered, it will be converted into a variable reference.

The following pairs are equivalent: =    =  {#var| foo | @= | value}}

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

Arrays
Arrays of up to two dimensions are currently supported. Arrays are made of up of pairs of keys and values.

#array
Syntax:

You may explicitly define a key by using an => in between the key and the value