Editing API:EPrints/Utils

<!-- Pod2Wiki=_preamble_ 
This page has been automatically generated from the EPrints 3.2 source. Any wiki changes made between the 'Pod2Wiki=*' and 'Edit below this comment' comments will be lost.
 -->{{API}}{{Pod2Wiki}}{{API:Source|file=perl_lib/EPrints/Utils.pm|package_name=EPrints::Utils}}[[Category:API|UTILS]][[Category:API:EPrints/Utils|UTILS]]<div><!-- Edit below this comment -->


<!-- Pod2Wiki=_private_ --><!-- Pod2Wiki=head_name -->
==NAME==
'''EPrints::Utils''' - Utility functions for EPrints.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_synopsis -->
==SYNOPSIS	==
<source lang="perl">$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"</source>

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_description -->
==DESCRIPTION==
This package contains functions which don't belong anywhere else.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_methods -->
==METHODS==
<!-- Pod2Wiki=head_make_name_string -->
===make_name_string===

<source lang="perl">$string = EPrints::Utils::make_name_string( $name, [$familylast] )

</source>
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"

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_wrap_text -->
===wrap_text===

<source lang="perl">$str = EPrints::Utils::wrap_text( $text, [$width], [$init_tab], [$sub_tab] )

</source>
Wrap $text to be at most $width (or 80 if undefined) characters per line. As a special case $width may be <code>console</code>, in which case the width used is the current console width ({{API:PodLink|file=Term/ReadKey|package_name=Term::ReadKey|section=|text=Term::ReadKey}}).

$init_tab and $sub_tab allow indenting on the first and subsequent lines respectively (see {{API:PodLink|file=Text/Wrap|package_name=Text::Wrap|section=|text=Text::Wrap}} for more information).

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_is_set -->
===is_set===

<source lang="perl">$boolean = EPrints::Utils::is_set( $r )

</source>
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.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_tree_to_utf8 -->
===tree_to_utf8===

<source lang="perl">$string = EPrints::Utils::tree_to_utf8( $tree, $width, [$pre], [$whitespace_before], [$ignore_a] )

</source>
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:

&lt;br /&gt; is converted to a newline.

&lt;p&gt;...&lt;/p&gt; will have a blank line above and below.

&lt;img /&gt; will be replaced with the content of the alt attribute.

&lt;hr /&gt; will, if a width was specified, insert a line of dashes.

&lt;a href="foo"&gt;bar&lt;/a&gt; will be converted into "bar &lt;foo&gt;" unless ignore_a is set.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_wget -->
===wget===

<source lang="perl">$response = EPrints::Utils::wget( $session, $source, $target )

</source>
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-&gt;is_success to check whether the copy succeeded.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_get_input_hidden -->
===get_input_hidden===

<source lang="perl">EPrints::Utils::get_input_hidden( $regexp, [$prompt], [$default] )

</source>
Get input from the console without echoing the entered characters  (mostly useful for getting passwords). Uses {{API:PodLink|file=Term/ReadKey|package_name=Term::ReadKey|section=|text=Term::ReadKey}}.

Identical to get_input except the characters don't appear.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_crypt -->
===crypt===

<source lang="perl">$crypt = EPrints::Utils::crypt( $value [, $method ] )

</source>
Generate a one-way crypt of $value e.g. for storing passwords.

For available methods see [[API:EPrints/Const|EPrints::Const]]. Defaults to EP_CRYPT_SHA512.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_crypt_equals -->
===crypt_equals===

<source lang="perl">$bool = EPrints::Utils::crypt_equals( $crypt, $value )

</source>
Test whether the $crypt as previously returned by [[API:EPrints/Utils#crypt|crypt]] for $value matches $value.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_url_escape -->
===url_escape===

<source lang="perl">$string = EPrints::Utils::url_escape( $url )

</source>
Escape the given $url, so that it can appear safely in HTML.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_uri_escape_utf8 -->
===uri_escape_utf8===

<source lang="perl">$url = EPrints::Utils::uri_escape_utf8( $str [, $ptn ] )

</source>
Escape utf8 encoded string $str for use in a URI.

Valid characters are [A-Za-z0-9\-\._~"].

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_escape_filename -->
===escape_filename===

<source lang="perl">$esc_string = EPrints::Utils::escape_filename( $string )

</source>
Take a value and escape it to be a legal filename to go in the /view/ section of the site.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_unescape_filename -->
===unescape_filename===

<source lang="perl">$string = EPrints::Utils::unescape_filename( $esc_string )

</source>
Unescape a string previously escaped with escape_filename().

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_human_filesize -->
===human_filesize===

<source lang="perl">$filesize_text = EPrints::Utils::human_filesize( $size_in_bytes )

</source>
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

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_cmp_deeply -->
===cmp_deeply===

<source lang="perl">$ok = cmp_deeply(LEFT, RIGHT)

</source>
Compare structures LEFT and RIGHT using <code>eq</code>, but descend into any array or hash references.

Note: this calls the [[API:EPrints/DataObj#_equal|EPrints::DataObj/_equal]] internal method.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=head_copyright -->
==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/.

<!-- Edit below this comment -->


<!-- Pod2Wiki= -->
<!-- Pod2Wiki=_postamble_ -->
<!-- Edit below this comment -->