Lire::Utils - Various general-purpose function.

  use Lire:Utils qw/ xml_encode /;

This module defines several general purpose functions. No functions are exported by default, you have to specify the one you want to import in your namespace when you use the module. Converts standard the characters <,>,&," and ' to their XML entities.

Example

    print XML_STREAM xml_encode( $value );

For portability across Perl versions, this module defines some functions that are usually found in the latest version of Perl but that may not be present in some old ones (the oldest version of Perl we support is 5.00503).

This method (provided by recent versions of File::Spec) returns where temporary files should go.

    my $fh = tempfile();
    my $fh = tempfile( $template, 'SUFFIX' => ".txt" )
    my ( $fh, $name ) = tempfile( $template, 'SUFFIX' => ".dlf" );

This is a wrapper around the File::Temp::tempfile Perl function when available, and it offers a home grown version which should be safe when it isn't available. The only difference is that the file will always be created in the directory specified in CW$ENV{'TMPDIR'} or /tmp when unset.

The first argument to the function should be a template name containing at least 6 X (i.e. tempXXXXXX) which will get replaced to generate a random name. When no arguments are passed, a default template of tempfileXXXXXX will be use.

Other options can be passed to the function by using 'key' => value pairs. The only option understood by the home grown version is SUFFIX which will be appended to the filename. (The Perl version understands more options, but you shouldn't use them for compatibility.)

The function takes precautions against symlink attacks (and creates the file with readwrite permission for the owner only). It will die(), if it fails to create a temporary file after 10 attempts. (This shouldn't happen unless someone is seriously trying to race with us.)

The function will return in scalar context an anonymous file handle opened on the temporary file. The temporary file was unlinked after creation and will thus be deleted automatically when you close the file handle.

When used in an array context, the function will return a file handle and the path to the temporary file (this can be useful for debugging purpose or when you can't pass the file by file handle to another process). In this case, the file should be deleted manually.

    my $dir = tempdir();
    my $dir = tempdir( $template )

This is a wrapper around the File::Temp::tempdir Perl function when available, and it offers a home grown version which should be safe when itsn't available. The only difference is that the directory will always be created in the directory specified in CW$ENV{'TMPDIR'} or /tmp when unset.

The first argument to the function should be a template name containing at least 6 X (i.e. tempXXXXXX) which will get replaced to generate a random name. When no arguments are passed, a default template of tempdirXXXXXX will be used.

Other options can be passed to the function by using 'key' => value pairs. The only option understood by the home grown version is DIR which specifies where the directory will be created (The Perl version understands more options, but you shouldn't use them for compatibility.)

The function takes precautions against symlink attacks (and create the file with readwrite permission for the owner only). It will die(), if it fails to create a temporary directory after 10 attempts. (This shouldn't happen unless someone is seriously trying to race with us.)

The function will return the name of the directory that was created.

    my $least = min(@values);
    my $least = min($a,$b,$c);

    my $greatest = max(@values);
    my $greatest = max($a,$b,$c);

These find the smallest or largest value in a list of numbers. An empty list will return undef. Undef values are ignored and will only be returned if the list is empty or contains only undefined value. Returns CW$divivend / CW$divisor and returns NaN when CW$divisor is equals to 0. It rounds the result to the second decimal. Returns as a percentage CW$part on CW$total. This function is safe to use when CW$total is equal to 0 (it will returns NaN). The percentage is rounded to the first decimal.

Return CW$string in a format that make it safe to hand out to the shell so that metacharacters are not interpreted by the shell. This is done by returning CW$string wrapped in single quotes and escaping the single quotes contained in the CW$string. Return CW$string, indented by CW$count spaces. If CW$count is not specified, a default of 2 will be assumed. Check that param $name is not undefined, and that it optionally match the given regexp. Validation can also be achieved through a code reference passed as the third parameter. The convention in this case is that the subroutine will return a boolean indicating whether CW$param is valid or not.

Examples:

    check_param( $req_param, 'req_param' );
    check_param( $param_string, 'param_string', qr/^[a-z]+$/ );
    check_param( $integer, 'integer', qr/^[0-9]+$/, "not a valid integer" );
    check_param( $bool, 'bool', sub { return $_[0] }, "boolean was false" );

Examples:

    check_param( $object, 'object', 'Wawa::Class' );
    check_param( $object, 'object', [ 'Wawa::Class', 'Other::Class' ] );

The function dies if the URL cannot be parsed. Returns the content of CW$filename. Dies if an error occurs. Creates file CW$filename with CW$content. The CW$utf8_encoding flag specifies whether you want to keep strings in their UTF-8 encoding with versions of Perl that supports it (5.8.0 and above). Returns an array reference containing the starting and ending boundaries for the CW$period that includes CW$time. CW$period should be one of 'hourly', 'daily', 'weekly', 'monthly' or 'yearly'. CW$time should be in seconds since epoch.

  Francis J. Lacoste <flacoste@logreport.org>
  Joost van Baal <joostvb@logreport.org>
  Wessel Dankers <wsl@logreport.org>
  Wolfgang Sourdeau <wolfgang@logreport.org>

$Id: Utils.pm,v 1.63 2004/09/01 15:12:04 flacoste Exp $

Copyright (C) 2001, 2002, 2004 Stichting LogReport Foundation LogReport@LogReport.org

This file is part of Lire.

Lire is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program (see COPYING); if not, check with http://www.gnu.org/copyleft/gpl.html or write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111, USA.