/ 
Text-TemplateLite-Standard-0.03
River stage zero No dependents
/ Text::TemplateLite::Standard

NAME

Text::TemplateLite::Standard - Standard function library for templates using Text::TemplateLite

VERSION

Version 0.03

SYNOPSIS

use Text::TemplateLite;
use Text::TemplateLite::Standard;

my $ttl = Text::TemplateLite->new;

# Register basic functions
Text::TemplateLite::Standard::register($ttl, ':basic');

# Register all functions
Text::TemplateLite::Standard::register($ttl, ':all');

# Register specific functions
Text::TemplateLite::Standard::register($ttl, @list);

DESCRIPTION

This module provides a library of standard functions for templates using Text::TemplateLite.

PERL FUNCTIONS

The functions in this section can be called from Perl code. The other sections describe functions that can be added to and called from Text::TemplateLite template engines.

register($template, @list)

This registers the specified functions or function-group tags with the specified template engine. It returns the template engine.

The template engine must respond to the method "register($name, $definition)", where $definition is a coderef expecting three parameters: the name of the function as called from the template, an arrayref of parameter code sequences, and an object instance compatible with Text::TemplateLite::Renderer.

get_numbers($args, $renderer)

This is a helper function to evaluate and return parameters as numbers. (Non-numbers are returned as 0.)

FUNCTION GROUP TAGS

Use these tags to conveniently register groups of related functions.

:logical

&&, !!, and !

:conditional

?, ifea, ??, and ifel

:iteration

?*, wh, *?, and dowh

:character

cr ("\r"), gg (">>"), ht ("\t"), lf ("\n"), ll ("<<"), nl ("\n"), and sp (" ")

:string

$;, join, $;;, join4, len, $-, substr, cmp, eq, ge, gt, le, lt, and ne

:numeric

+, -, *, /, %, int, max, min, <=>, =, >=, >, <=, <, and !=

:bitwise

&, |, and !

:template

tpl, <$>

:misc or :miscellaneous

$=, void

:basic

:conditional, :logical, :character, :string, :numeric, :bitwise, and :misc

:all

:basic, x, :iteration, and :template

LOGICAL FUNCTIONS

&&(condition, ...)

This function, "logical and", evaluates each condition in turn. If any condition is empty or zero, evaluation stops and "0" is returned. If all conditions are true, "1" is returned.

||(condition, ...)

This function, "logical or", evaluates each condition in turn. If any condition is non-empty and non-zero, evaluation stops and "1" is returned. If all conditions are false, "0" is returned.

!(condition)

This function, "logical not", evaluates the condition. If it is non-empty and non-zero, the result is "0". Otherwise, the result is "1".

CONDITIONAL FUNCTIONS

?(expression, ...)

ifea(expression, ...)

This function, "if each", returns each non-empty expression. Expressions may be multi-valued.

tpl('dear', 'Dear ' $;;(' and ', ', ', ', ', ', and ',
  ?($1, $2, $3, $4, $5, $6, $7, $8, $9)) ',')
$dear('Dick', 'Jane') /* Dear Dick and Jane, */
$dear('Tom', 'Dick', 'Harry') /* Dear Tom, Dick, and Harry, */

??(condition, expression, ..., default?)

ifel(condition, expression, ..., default?)

This function, "if else", takes any number of (condition, expression) pairs, optionally followed by a default. Each condition is evaluated in turn. The (possibly multi-valued) expression corresponding to the first non-empty, non-zero condition is evaluated and returned. If no conditions are satisifed, the (possibly multi-valued) default expression is evaluated and returned (if supplied).

ITERATION FUNCTIONS

?*(condition, code)

wh(condition, code)

This function, "while", executes the specified code repeatedly as long as the condition remains true (non-empty and non-zero). If the condition is not initially true, the code will never be executed.

It returns a list (in array context) or the concatenation of the results of executing the code.

*?(code, condition)

dowh(code, condition)

This function, "do-while", executes the specified code repeatedly as long as the condition remains true (non-empty and non-zero). The code is executed before the condition is evaluated and so will run at least once.

It returns a list (in array context) or the concatenation of the results of executing the code.

CHARACTERS

cr ("\r"), gg (">>"), ht ("\t"), ll ("<<"), nl ("\n"), and sp (" ")

STRING FUNCTIONS

$;(separator, expression, ...)

join(separator, expression, ...)

This function returns the concatenation of all the values of all the (possibly multi-valued) expression parameters, separated by separator.

$;(',', 'a', 'b', 'c') /* a,b,c */
$;(',', 'a', ?('b', 'c')) /* a,b,c */
$;(',', 'a', ''?('b', 'c')) /* a,bc */

$;;(sep2, first_sep, middle_sep, last_sep, expression, ...)

join4(sep2, first_sep, middle_sep, last_sep, expression, ...)

This function returns the concatenation of all values of all expression parameters, separated by separators. If there are exactly two values, only the "sep2" separator is used. If there are three or more values, "first_sep" is used first, "last_sep" is used last, and "middle_sep" is used between all other values.

The intent is to support "a and b" and "a, b, and c" styles of context-dependent joins while working either left-to-right or right-to-left.

len(value)

This function returns the length (in characters) of the specified value.

$/(separator, string, nth?)

split(separator, string, nth?)

This function splits the string into parts using the specified separator. If nth is specified, that part (counting from 0) is returned. Otherwise, all the parts are returned (as separate values).

x(string, count)

This function returns the concatenation of count copies of string. Extra care is taken to avoid exceeding the step_length limit (see "limit($type, $limit)" in Text::TemplateLite::Renderer).

x('-#',5)'-' /* -#-#-#-#-#- */

$-(string, offset?, length?)

substr(string, offset?, length?)

This function returns the substring of length length beginning at offset offset. It uses Perl's substr, so negative offsets and lengths work the same way.

trim(string, ...)

This function returns each string parameter with leading and trailing white space removed.

cmp(string1, string2)

This function returns -1, 0, or 1 depending on whether string1 is less than, equal to, or greater than string2 (using the cmp operator in Perl).

eq(string1, string2)

ge(string1, string2)

gt(string1, string2)

le(string1, string2)

lt(string1, string2)

ne(string1, string2)

These functions return true if string1 is equal to (eq), greater than or equal to (ge), greater than (gt), less than or equal to (le), less than (le), or not equal to (ne) string2.

NUMERIC FUNCTIONS

+(number, ...)

This function returns the sum of its numeric parameters (or 0 if there aren't any).

-(number)

The "unary minus" form of this function returns the negative of the number.

-(number1, number2)

The "binary minus" form of this function returns the difference number1 - number2.

*(number, ...)

This function returns the product of its numeric parameters (or 1 if there aren't any).

/(number1, number2)

This function returns the quotient of number1 divided by number2. It returns an empty string if number2 is zero.

%(number1, number2)

This function returns the remainder of number1 divided by number2. It returns an empty string if number2 is zero.

&(number, ...)

This function returns the binary "and" of its numeric parameters (or ~0 if there aren't any).

|(number, ...)

This function returns the binary "or" of its parameters (or 0 if there aren't any).

^(number, ...)

This function returns the binary "exclusive-or" ("xor") of its parameters (or 0 if there aren't any).

~(number)

This function returns the one's complement of number.

int(number)

This function returns the integer portion of number.

max(number, ...)

This function returns the maximum of its numeric parameters (or any empty string if there aren't any).

min(number, ...)

This function returns the minimum of its numeric parameters (or any empty string if there aren't any).

<=>(number1, number2)

This function returns -1, 0, or 1 depending on whether number1 is less than, equal to, or greater than number2 (using the <=> operator in Perl).

=(number1, number2)

>=(number1, number2)

>(number1, number2)

<=(number1, number2)

<(number1, number2)

!=(number1, number2)

These functions return true if number1 is equal to (=), greater than or equal to (>=), greater than (>), less than or equal to (<=), less than (<), or not equal to (!=) number2.

TEMPLATE FUNCTIONS

tpl(name, code)

This function creates a template within the template. The code is stored in the variable with the specified name and can be called later within the main template as $name or $name(parameters). The parameters will appear as variables $1, $2, etc. Parameter $0 will be set to the number of parameters supplied.

It returns no value.

<$>(int_name1, ext_name1, ..., ext_name?)

This function allows you to retrieve variable values from the most recent external template call.

Parameters are interpreted as as many pairs as possible. The first parameter in each pair is a variable name in the current template; the second is a variable name in the external template whose value will be assigned to the variable in the current template.

If there are an odd number of parameters, the value of the external variable named last will be the return value of the function call. Otherwise, no value is returned.

<$>('my_a', 'a', 'my_b', 'b', 'c')
/* Copies the values of $a and $b in the last external template
   into $my_a and $my_b in the current template. Returns the
   value of $c from the external template. */

If there has been no external template call, nothing happens and nothing is returned.

MISCELLANEOUS FUNCTIONS

$=(name1, expr1, ..., ret_name?)

This function takes any number of (possibly multi-valued) parameters. The maximum even number of resulting values are interpreted as (name, value) pairs, assigning each value to the variable with the preceding name.

If there are an odd number of parameters, the value of the variable named by the last parameter is returned. Otherwise, no value is returned.

$=('prev', $var, 'var', +($var, 1))
/* sets $prev to the current value of $var,
   adds 1 to $var, and returns nothing */

$=('a', 2, 'b'$a, 3, 'b'$a)
/* sets $a to 2, sets $b2 to 3, and returns $b2 */

void(expression, ...)

This function evaluates each expression but returns nothing.

You probably won't need this unless you add functions with side effects that return something when they shouldn't.

AUTHOR

Brian Katzung, <briank at kappacs.com>

BUGS

Please report any bugs or feature requests to bug-text-templatelite at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Text-TemplateLite-Standard. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Text::TemplateLite::Standard

You can also look for information at:

LICENSE AND COPYRIGHT

Copyright 2012 Brian Katzung.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.