* Documented most function plugins

lib/plugins/builtin/functions/cycle.php

 <?php
 
 /**
- * TOCOM
+ * Cycles between several values and returns one of them on each call
+ * 
+ *  * name : the cycler name, specify if you need to have multiple concurrent cycles running
+ *  * values : an array of values or a string of values delimited by $delimiter
+ *  * print : if false, the pointer will go to the next one but not print anything
+ *  * advance : if false, the pointer will not advance to the next value
+ *  * delimiter : the delimiter used to split values if they are provided as a string
+ *  * assign : if set, the value is saved in that variable instead of being output
+ *  * reset : if true, the pointer is reset to the first value
  *
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.

lib/plugins/builtin/functions/date_format.php

 <?php
 
 /**
- * TOCOM
+ * Formats a date
+ * 
+ *  * value : the date, as a unix timestamp, mysql datetime or whatever strtotime() can parse
+ *  * format : output format, see {@link http://php.net/strftime} for details
+ *  * default : a default timestamp value, if the first one is empty
  *
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.

lib/plugins/builtin/functions/default.php

 <?php
 
 /**
- * TOCOM
+ * Returns a variable or a default value if it's empty
+ * 
+ *  * value : the variable to check
+ *  * default : fallback value if the first one is empty
  *
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.

lib/plugins/builtin/functions/dump.php

 <?php
 
 /**
- * TOCOM
+ * Dumps values of the given variable, or the entire data if nothing provided
+ *  
+ *  * var : the variable to display
  *
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.

lib/plugins/builtin/functions/eol.php

 <?php
 
 /**
- * TOCOM
+ * Returns the correct end of line character for the current operating system
  *
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.

lib/plugins/builtin/functions/escape.php

 <?php
 
 /**
- * TOCOM
+ * Applies various escaping schemes on the given string
+ * 
+ *  * value : the string to process
+ *  * format : escaping format to use, valid formats are : html, htmlall, url, urlpathinfo, quotes, hex, hexentity, javascript and mail
+ *  * charset : character set to use for the conversion (applies to some formats only), defaults to the current Dwoo charset
  *
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.

lib/plugins/builtin/functions/eval.php

 <?php
 
 /**
- * TOCOM
- *
+ * Evaluates the given string as if it was a template
+ * 
+ * Although this plugin is kind of optimized and will 
+ * not recompile your string each time, it is still not
+ * a good practice to use it. If you want to have templates
+ * stored in a database or something you should probably use
+ * the Dwoo_Template_String class or make another class that
+ * extends it
+ * 
+ *  * var : the string to use as a template
+ *  * assign : if set, the output of the template will be saved in this variable instead of being output
+ * 
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.
  *
@@ -21,7 +31,6 @@
  */
 function Dwoo_Plugin_eval(Dwoo $dwoo, $var, $assign = null)
 {
-	// TOCOM eval is bad, warn people that they should not use it as a full template for DB-templates, they better extend Dwoo_ITemplate for that
 	if($var == '')
 		return;
 

lib/plugins/builtin/functions/extends.php

 <?php
 
 /**
- * TOCOM
+ * Extends another template, read more about template inheritance at {@link http://wiki.dwoo.org/index.php/TemplateInheritance}
+ * 
+ *  * file : the template to extend
  *
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.

lib/plugins/builtin/functions/extendsCheck.php

 <?php
 
 /**
- * TOCOM
+ * Checks whether an extended file has been modified, and if so recompiles the current template. This is for internal use only, do not use.
  *
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.

lib/plugins/builtin/functions/fetch.php

 <?php
 
 /**
- * TOCOM
+ * Reads a file
+ * 
+ *  * file : path or URI of the file to read (however reading from another website is not recommended for performance reasons)
+ *  * assign : if set, the file will be saved in this variable instead of being output
  *
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.

lib/plugins/builtin/functions/include.php

 <?php
 
 /**
- * TOCOM
+ * Inserts another template into the current one
+ * 
+ *  * file : the resource name of the template
+ *  * cache_time : cache length in seconds
+ *  * cache_id : cache identifier for the included template
+ *  * compile_id : compilation identifier for the included template
+ *  * data : data to feed into the included template, it can be any array and will default to $_root (the current data)
+ *  * assign : if set, the output of the included template will be saved in this variable instead of being output
+ *  * rest : any additional parameter/value provided will be added to the data array
  *
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.

lib/plugins/builtin/functions/indent.php

 <?php
 
 /**
- * TOCOM
+ * Indents every line of a text by the given amount of characters
+ * 
+ *  * value : the string to indent
+ *  * by : how many characters should be inserted before each line
+ *  * char : the character(s) to insert
  *
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.

lib/plugins/builtin/functions/isset.php

 <?php
 
 /**
- * TOCOM
+ * Checks whether a variable is not null
+ * 
+ *  * var : variable to check
  *
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.

lib/plugins/builtin/functions/lower.php

 <?php
 
 /**
- * TOCOM
+ * Makes the input string lower cased
+ *
+ *  * value : the string to process 
  *
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.

lib/plugins/builtin/functions/mailto.php

 <?php
 
 /**
- * TOCOM
+ * Outputs a mailto link with optional spam-proof (okay probably not) encoding
+ * 
+ *  * address : target email address
+ *  * text : display text to show for the link, defaults to the address if not provided 
+ *  * subject : the email subject
+ *  * encode : one of the available encoding (none, js, jscharcode or hex)
+ *  * cc : address(es) to carbon copy, comma separated
+ *  * bcc : address(es) to blind carbon copy, comma separated
+ *  * newsgroups : newsgroup(s) to post to, comma separated
+ *  * followupto : address(es) to follow up, comma separated
+ *  * extra : additional attributes to add to the &lt;a&gt; tag
  *
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.

lib/plugins/builtin/functions/math.php

 <?php
 
 /**
- * TOCOM
+ * Computes a mathematical equation
+ * 
+ *  * equation : the equation to compute, it can include normal variables with $foo or special math variables without the dollar sign 
+ *  * format : output format, see {@link http://php.net/sprintf} for details
+ *  * assign : if set, the output is assigned into the given variable name instead of being output
+ *  * rest : all math specific variables that you use must be defined, see the example
+ * 
+ * Example :
+ * 
+ * <code>
+ * {$c=2}
+ * {math "(a+b)*$c/4" a=3 b=5}
+ * 
+ * output is : 4 ( = (3+5)*2/4)
+ * </code>
  *
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.

lib/plugins/builtin/functions/nl2br.php

 <?php
 
 /**
- * TOCOM
+ * Converts line breaks into <br /> tags
+ * 
+ *  * value : the string to process 
  *
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.

lib/plugins/builtin/functions/regex_replace.php

 <?php
 
 /**
- * TOCOM
+ * Replaces the search string by the replace string using regular expressions
+ * 
+ *  * value : the string to search into
+ *  * search : the string to search for, must be a complete regular expression including delimiters
+ *  * replace : the string to use as a replacement, must be a complete regular expression including delimiters
  *
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.

lib/plugins/builtin/functions/replace.php

 <?php
 
 /**
- * TOCOM
+ * Replaces the search string by the replace string
+ * 
+ *  * value : the string to search into
+ *  * search : the string to search for
+ *  * replace : the string to use as a replacement
  *
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.

lib/plugins/builtin/functions/reverse.php

 <?php
 
 /**
- * TOCOM
- *
+ * Reverses a string or an array 
+ * 
+ *  * value : the string or array to reverse
+ *  * preserve_keys : if value is an array and this is true, then the array keys are left intact
+ * 
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.
  *
@@ -21,7 +24,7 @@
  */
 function Dwoo_Plugin_reverse(Dwoo $dwoo, $value, $preserve_keys=false)
 {
-	if(is_array($value) || ($value instanceof Iterator && $value instanceof ArrayAccess))
+	if(is_array($value))
 		return array_reverse($value, $preserve_keys);
 	else
 		return implode('',array_reverse(str_split((string) $value,1)));

lib/plugins/builtin/functions/safe.php

 <?php
 
 /**
- * TOCOM
+ * Marks the variable as safe and removes the auto-escape function, only useful if you turned auto-escaping on
+ * 
+ *  * var : the variable to pass through untouched
  *
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.

lib/plugins/builtin/functions/spacify.php

 <?php
 
 /**
- * TOCOM
+ * Adds spaces (or the given character(s)) between every character of a string
+ * 
+ *  * value : the string to process
+ *  * space_char : the character(s) to insert between each character
  *
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.

lib/plugins/builtin/functions/string_format.php

 <?php
 
 /**
- * TOCOM
+ * Formats a string using the sprintf function
+ * 
+ *  * value : the string to format
+ *  * format : the format to use, see {@link http://php.net/sprintf} for details
  *
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.

lib/plugins/builtin/functions/strip.php

 <?php
 
 /**
- * TOCOM
+ * Replaces all white-space characters with the given string
+ * 
+ *  * value : the text to process
+ *  * with : the replacement string, note that any number of consecutive white-space characters will be replaced by a single replacement string
+ * 
+ * Example :
+ * 
+ * <code>
+ * {"a    b  c		d
+ * 
+ * e"|strip}
+ * 
+ * results in : a b c d e
+ * </code>
  *
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.

lib/plugins/builtin/functions/strip_tags.php

 <?php
 
 /**
- * TOCOM
+ * Removes all html tags
+ * 
+ *  * value : the string to process
+ *  * addspace : if true, a space is added in place of every removed tag
  *
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.

lib/plugins/builtin/functions/truncate.php

 <?php
 
 /**
- * TOCOM
+ * Truncates a string at the given length
+ * 
+ *  * value : text to truncate
+ *  * length : the maximum length for the string
+ *  * etc : the characters that are added to show that the string was cut off
+ *  * break : if true, the string will be cut off at the exact length, instead of cutting at the nearest space
+ *  * middle : if true, the string will contain the beginning and the end, and the extra characters will be removed from the middle
  *
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.

lib/plugins/builtin/functions/upper.php

 <?php
 
 /**
- * TOCOM
+ * Makes a string uppercased
+ * 
+ *  * value : the text to uppercase
  *
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.

lib/plugins/builtin/functions/wordwrap.php

 <?php
 
 /**
- * TOCOM
+ * Wraps a text at the given line length
+ * 
+ *  * value : the text to wrap
+ *  * length : maximum line length
+ *  * break : the character(s) to use to break the line
+ *  * cut : if true, the line is cut at the exact length instead of breaking at the nearest space
  *
  * This software is provided 'as-is', without any express or implied warranty.
  * In no event will the authors be held liable for any damages arising from the use of this software.