Provided by: lire-devel-doc_2.1.1-2.1_all 
NAME
Lire::Utils - Various general-purpose function.
SYNOPSIS
use Lire:Utils qw/ xml_encode /;
DESCRIPTION
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.
xml_encode( $str )
Converts standard the characters <,>,&," and ' to their XML entities.
Example
print XML_STREAM xml_encode( $value );
latex_encode( $str )
Returns $str with all LaTeX special characters escaped.
tilde_expand( $path )
Does tilde-expansion on a path, if possible. This means that paths of the form ~/foo are
transformed to something like /home/user/foo, where "/home/user" is the content of the
$HOME variable. Paths of the form ~otheruser/foo are translated similary by a passwd
lookup.
diff_lists( $list1, $list2 )
Compare two list, if the two list contains the same items (even if in different order) it
returns undef. Otherwise an hash reference is returned which contains the list of new
items in the 'new' key and the list of items to remove (to $list1 to make $list2) in the
'remove' key.
PORTABILITY FUNCTIONS
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).
tmpdir()
This method (provided by recent versions of File::Spec) returns where temporary files
should go.
tempfile()
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
$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.
tempdir()
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
$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.
min()
my $least = min(@values);
my $least = min($a,$b,$c);
max()
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.
ratio( $dividend, $divisor )
Returns $divivend / $divisor and returns "NaN" when $divisor is equals to 0. It rounds the
result to the second decimal.
ratio100( $part, $total )
Returns as a percentage $part on $total. This function is safe to use when $total is equal
to 0 (it will returns NaN). The percentage is rounded to the first decimal.
shell_quote($string)
Return $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 $string wrapped
in single quotes and escaping the single quotes contained in the $string.
indent( $string, [ $count ] )
Return $string, indented by $count spaces. If $count is not specified, a default of 2 will
be assumed.
check_param( $param, $name, [ $regex | $coderef, $msg ] )
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 $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" );
check_param( $instance, $name, $class )
Check that param "$instance" is a valid of one or more classes specified in the 'class'
parameter. The latter being either a string or a reference to an array containing one or
more such strings.
Examples:
check_param( $object, 'object', 'Wawa::Class' );
check_param( $object, 'object', [ 'Wawa::Class', 'Other::Class' ] );
sql_quote_name( $name )
tree_apply( $root, $children_func, $apply_func )
Preorder processsing
item_index( $array_ref, $item )
Returns the index of $item in $array. It returns undef if the item isn't found. $array_ref
should be an ARRAY reference and $item should be a non-null scalar.
deep_copy( $object, [$exclusion] )
Makes a recursive copy of $object. Cyclic references are maintained in the copy.
Optionnally, an array ref of packages for which the objects shouldn't be deeply copied can
be provided.
unique( $list )
Returns an array reference with the duplicates elements of $list removed.
text_for_width( $text, $width )
Returns a stripped-down representation of 'text', ensuring its length is shorter or equal
to 'width'. If the original text already fits the given width, it is returned unchanged,
otherwise, it is shortened and '...' is put in the middle to indicate the cut.
is_url( $string )
Determines whether $string is a url or not, returning 'true' or 'false' as result code.
parse_url( $string )
Returns an hash reference containing keys for the following URL parts: 'scheme', 'host',
'port', 'path', 'query', 'fragment'. The value will be empty if this wasn't present in the
URL. This function is somewhat 'http' biased and one should use the URI module for full
blown URI parsing.
The function dies if the URL cannot be parsed.
file_content( $filename )
Returns the content of $filename. Dies if an error occurs.
create_file( $filename, [$content], [$utf8_encoding] )
Creates file $filename with $content. The $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).
period_range( $period, $time )
Returns an array reference containing the starting and ending boundaries for the $period
that includes $time. $period should be one of 'hourly', 'daily', 'weekly', 'monthly' or
'yearly'. $time should be in seconds since epoch.
AUTHORS
Francis J. Lacoste <flacoste@logreport.org>
Joost van Baal <joostvb@logreport.org>
Wessel Dankers <wsl@logreport.org>
Wolfgang Sourdeau <wolfgang@logreport.org>
VERSION
$Id: Utils.pm,v 1.67 2006/07/23 13:16:30 vanbaal Exp $
COPYRIGHT
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.