API:EPrints/Utils
EPrints 3 Reference: Directory Structure - Metadata Fields - Repository Configuration - XML Config Files - XML Export Format - EPrints data structure - Core API - Data Objects
Latest Source Code (3.4, 3.3) | Revision Log | Before editing this page please read Pod2Wiki
Contents
NAME
EPrints::Utils - Utility functions for EPrints.
SYNOPSIS
$boolean = EPrints::Utils::is_set( $object )
# return true if an object/scalar/array has any data in it
# copy the contents of the url to a file
$response = EPrints::Utils::wget(
$handle,
"http://www.eprints.org/index.php",
"temp_dir/my_file" )
if($response->is_sucess()){ do something...}
$name = { given=>"Wendy", family=>"Hall", honourific=>"Dame" };
# return Dame Wendy Hall
$string = EPrints::Utils::make_name_string( $name, 1 );
# return Dame Hall, Wendy
$string = EPrints::Utils::make_name_string( $name, 0 );
# returns http://www.eprints.org?var=%3Cfoo%3E
$string = EPrints::Utils::url_escape( "http://www.eprints.org?var=<foo>" );
$esc_string = EPrints::Utils::escape_filename( $string );
$string = EPrints::Utils::unescape_filename( $esc_string );
$filesize_text = EPrints::Utils::human_filesize( 3300 );
# returns "3kB"
DESCRIPTION
This package contains functions which don't belong anywhere else.
METHODS
make_name_string
$string = EPrints::Utils::make_name_string( $name, [$familylast] )
Return a string containing the name described in the hash reference $name.
The keys of the hash are one or more of given, family, honourific and lineage. The values are utf-8 strings.
Normally the result will be:
"family lineage, honourific given"
but if $familylast is true then it will be:
"honourific given family lineage"
wrap_text
$str = EPrints::Utils::wrap_text( $text, [$width], [$init_tab], [$sub_tab] )
Wrap $text to be at most $width (or 80 if undefined) characters per line. As a special case $width may be console, in which case the width used is the current console width (Term::ReadKey).
$init_tab and $sub_tab allow indenting on the first and subsequent lines respectively (see Text::Wrap for more information).
is_set
$boolean = EPrints::Utils::is_set( $r )
Recursive function.
Return false if $r is not set.
If $r is a scalar then returns true if it is not an empty string.
For arrays and hashes return true if at least one value of them is_set().
This is used to see if a complex data structure actually has any data in it.
tree_to_utf8
$string = EPrints::Utils::tree_to_utf8( $tree, $width, [$pre], [$whitespace_before], [$ignore_a] )
Convert a XML DOM tree to a utf-8 encoded string.
If $width is set then word-wrap at that many characters.
XHTML elements are removed with the following exceptions:
<br /> is converted to a newline.
<p>...</p> will have a blank line above and below.
<img /> will be replaced with the content of the alt attribute.
<hr /> will, if a width was specified, insert a line of dashes.
<a href="foo">bar</a> will be converted into "bar <foo>" unless ignore_a is set.
wget
$response = EPrints::Utils::wget( $session, $source, $target )
Copy $source file or URL to $target file without alteration.
Will fail if $source is a "file:" and "enable_file_imports" is false or if $source is any other scheme and "enable_web_imports" is false.
Returns the HTTP response object: use $response->is_success to check whether the copy succeeded.
EPrints::Utils::get_input_hidden( $regexp, [$prompt], [$default] )
Get input from the console without echoing the entered characters (mostly useful for getting passwords). Uses Term::ReadKey.
Identical to get_input except the characters don't appear.
crypt
$crypt = EPrints::Utils::crypt( $value [, $method ] )
Generate a one-way crypt of $value e.g. for storing passwords.
For available methods see EPrints::Const. Defaults to EP_CRYPT_SHA512.
crypt_equals
$bool = EPrints::Utils::crypt_equals( $crypt, $value )
Test whether the $crypt as previously returned by crypt for $value matches $value.
url_escape
$string = EPrints::Utils::url_escape( $url )
Escape the given $url, so that it can appear safely in HTML.
uri_escape_utf8
$url = EPrints::Utils::uri_escape_utf8( $str [, $ptn ] )
Escape utf8 encoded string $str for use in a URI.
Valid characters are [A-Za-z0-9\-\._~"].
escape_filename
$esc_string = EPrints::Utils::escape_filename( $string )
Take a value and escape it to be a legal filename to go in the /view/ section of the site.
unescape_filename
$string = EPrints::Utils::unescape_filename( $esc_string )
Unescape a string previously escaped with escape_filename().
human_filesize
$filesize_text = EPrints::Utils::human_filesize( $size_in_bytes )
Return a human readable version of a filesize. If 0-4095B then show as bytes, if 4-4095KB show as KB otherwise show as MB.
eg. Input of 5234 gives "5KB", input of 3234 gives "3234B".
This is not internationalised, I don't think it needs to be. Let me know if this is a problem. support@eprints.org
cmp_deeply
$ok = cmp_deeply(LEFT, RIGHT)
Compare structures LEFT and RIGHT using eq, but descend into any array or hash references.
Note: this calls the EPrints::DataObj/_equal internal method.
COPYRIGHT
- Copyright 2000-2011 University of Southampton.
- This file is part of EPrints http://www.eprints.org/.
- EPrints is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
- EPrints 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 Lesser General Public License for more details.
- You should have received a copy of the GNU Lesser General Public License along with EPrints. If not, see http://www.gnu.org/licenses/.
