/ 
TUWF-0.1
River stage zero No dependents
/ TUWF::Misc

NAME

TUWF::Misc - Miscellaneous utility functions and methods for TUWF

DESCRIPTION

This module provides a few methods for the main TUWF object and optionally exports a few handy functions. The methods can be used from within any TUWF website without requiring any additional magic, TUWF automatically loads this module at initialization.

The exported functions can be imported through TUWF (use TUWF 'uri_escape';) or by using this module directly (use TUWF::Misc 'uri_escape';). The latter form is useful if you wish to use a function outside of the TUWF framework.

METHODS

formValidate(@fields)

Shorthand for calling kv_validate() with the following sources:

Name    TUWF Method
 post    reqPost()
 get     reqGet()
 param   reqParam()
 cookie  reqCookie()

The validate_templates configuration setting is passed as the templates option.

mail(body, header => value, ..)

Very simple email sending function. The Content-Type header defaults to text/plain; charset='UTF-8', and the From header to the mail_from configuration setting. The mail is sent using the sendmail program configured with mail_sendmail, you should make sure both that option is correct and the server is configured to allow using the sendmail program to actually send mail.

FUNCTIONS

uri_escape(string)

Percent-encodes the given string and returns a string suitable for use as a parameter value in a URI. The given string is assumed to be in Perls native unicode format, and the escaped string will have UTF-8 encoded percent-escaping.

This function is equivalent to uri_escape_utf8() provided by URI::Escape, and the encodeURIComponent() function in JavaScript.

kv_validate(sources, templates, fields)

Validates a set of key/value pairs against a list of constraints and data definitions. Returns the (optionally modified) key/value pairs and, if a field did not validate, an error indication. This function was designed to validate form input data, and can as such also validate keys (or fields) which represent multiple values. This function is rarely used directly, formValidate() does everything you need when validating common input data.

sources is a hashref explaining where the values should be fetched from. Each key in the hash represents the name of the source, and it's value is a subroutine reference. This subroutine should accept one argument: the name of the field, and is expected return a list of values, or an empty list if there are no values with that key. The following example defines a source by the name "param", and tells kv_validate() to fetch the values using reqParam().

kv_validate(
  { param => sub { $TUWF::OBJ->reqParam(shift) } },
  ..
);

The templates argument should be reference to a (possibly empty) hash providing templates for commonly used constraints and data definitions.

The fields argument should be an arrayref, where each item in the array represents a single field. Each field should be a hashref with options. The following options are accepted:

<source name> => <field name>

String, indicates from which source the field should be fetched, and which name to use. Note that even though kv_validate() accepts validating data from multiple sources, each field should only have one source option, and there should not be a field from a different source with the same name.

Using the sources example above, specifying param => 'foo' as field option tells kv_validate() to fetch the value(s) for this field from reqParam('foo').

required

0/1. Indicates whether the field is required or not. Default: 1.

default

Specifies the default value to return when the field is not present or left empty. Only makes sense for fields that are not required.

rmwhitespace

0/1. Removes any whitespace before and after the value before doing any other validation. All occurences of \r are also removed from the value. Default: 1.

maxlength

Number. Maximum length (in number of characters) of the value.

minlength

Number. Minimum length of the value.

enum

Arrayref. The value must be equal to any of the strings in the array. Note that even though a string comparison is used, this works fine numbers as well.

max

Number. The value must be lower than the indicated number (using numeric comparison). This option implies that the value must be a number.

min

Number. See max.

regex

Validate the value against a regular expression. For identification, this option can also be set to an arrayref, of which the first item contains the regular expression. All other elements in the array are ignored by kv_validate(), but are still returned in the error structure and can therefore be used in your code.

func

Subroutine reference. Validate the value against a function. The subroutine should return false if the value is invalid. Since the actual value variable is passed to the subroutine, it is allowed to modify it in-place. This can be useful for normalizing or de-serializing values. This constraint is always executed last. This option can also be set to an arrayref, which works the same as with the regex option.

template

String, refers to a key in the templates hash. Validates the value against the options in %{$templates{$string}}, which may contain any of the above mentioned options (except <source name>).

multi

0/1, indicates whether there should be only one value or multiple values. If this option is disabled (as is the default), only the first value will be validated and returned. Otherwise, each value is validated separately against the above options and an arrayref with values is returned. Validating this field is stopped when one value does not match. The required and default options are also evaluated per-value: if required is true, each value should be non-empty. Empty values are set to the default.

maxcount

Number. When multi is true, specifies the maximum number of values to be present. Whether they are empty or not is ignored in this count.

mincount

Number. See mincount.

kv_validate() returns a hashref with field name to value mappings. When one or more fields did not validate, a special _err field is added. Its value is an arrayref where each item represents an invalid field. Each invalid field is represented again by an arrayref containing three items: the name of the field, the option that caused it to fail and the value of that option.

Example:

my $r = kv_validate(
  # sources
  { param => sub { $TUWF::OBJ->reqParam(shift) } },
  # templates
  { crc32_hex => {
    regex => qr/^[0-9a-f]+$/i,
    maxlength => 8,
    minlength => 8,
  } },
  # field definitions
  [
    { param => 'name', maxlength => 100 },
    { param => 'age',  min => 18, max => 120 },
    { param => 'crc',  required => 0, template => 'crc32_hex' },
  ],
);

# $r will look something like:
{
  name => 'John Doe',
  age => 28,
  crc => 'This does not look like a CRC32 string',
  _err => [
    [ 'crc', 'template', 'crc32_hex' ]
  ]
}

SEE ALSO

TUWF, URI::Escape.

COPYRIGHT

Copyright (c) 2008-2011 Yoran Heling.

This module is part of the TUWF framework and is free software available under the liberal MIT license. See the COPYING file in the TUWF distribution for the details.

AUTHOR

Yoran Heling <projects@yorhel.nl>