Difference between revisions of "API:EPrints/Utils"

From EPrints Documentation
Jump to: navigation, search
 
(8 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
<!-- Pod2Wiki=_preamble_  
 
<!-- 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.
 
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 -->
__NOTOC__
 
{{API}}{{Pod2Wiki}}{{API:Source|file=EPrints/Utils.pm|package_name=EPrints::Utils}}[[Category:API|Utils]]<div><!-- Edit below this comment -->
 
  
  
<!-- Pod2Wiki=head_name --></div>
+
<!-- Pod2Wiki=_private_ --><!-- Pod2Wiki=head_name -->
 
==NAME==
 
==NAME==
 
'''EPrints::Utils''' - Utility functions for EPrints.
 
'''EPrints::Utils''' - Utility functions for EPrints.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=head_synopsis --></div>
+
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_synopsis -->
 
==SYNOPSIS ==
 
==SYNOPSIS ==
  $boolean = EPrints::Utils::is_set( $object )  
+
<source lang="perl">$boolean = EPrints::Utils::is_set( $object )  
  # return true if an object/scalar/array has any data in it
+
# return true if an object/scalar/array has any data in it
 
+
 
  # copy the contents of the url to a file
+
# copy the contents of the url to a file
  $response = EPrints::Utils::wget(  
+
$response = EPrints::Utils::wget(  
    $handle,  
+
$handle,  
    "http://www.eprints.org/index.php",  
+
"http://www.eprints.org/index.php",  
    "temp_dir/my_file" )  
+
"temp_dir/my_file" )  
  if($response-&gt;is_sucess()){ do something...}
+
if($response->is_sucess()){ do something...}
 
 
  $name = { given=&gt;"Wendy", family=&gt;"Hall", honourific=&gt;"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=&lt;foo&gt;" );
 
 
 
  $esc_string = EPrints::Utils::escape_filename( $string );
 
  $string = EPrints::Utils::unescape_filename( $esc_string );
 
 
 
  $filesize_text = EPrints::Utils::human_filesize( 3300 );
 
  # returns "3kb"
 
 
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
  
 +
$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 );
  
<!-- Pod2Wiki=head_description --></div>
+
# returns http://www.eprints.org?var=%3Cfoo%3E
==DESCRIPTION==
+
$string = EPrints::Utils::url_escape( "http://www.eprints.org?var=<foo>" );
This package contains functions which don't belong anywhere else.
 
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
$esc_string = EPrints::Utils::escape_filename( $string );
<h4><span style='display:none'>User Comments</span></h4>
+
$string = EPrints::Utils::unescape_filename( $esc_string );
<!-- Edit below this comment -->
 
  
 +
$filesize_text = EPrints::Utils::human_filesize( 3300 );
 +
# returns "3kB"</source>
  
<!-- Pod2Wiki=for --></div>
 
InternalDoc<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_prepare_cmd --></div>
+
<!-- Pod2Wiki= -->
===$cmd = EPrints::Utils::prepare_cmd($cmd,%VARS)===
+
<!-- Pod2Wiki=head_description -->
 +
==DESCRIPTION==
 +
This package contains functions which don't belong anywhere else.
  
Prepare command string $cmd by substituting variables (specified by <tt>$(varname)</tt>) with their value from %VARS (key is <tt>varname</tt>). All %VARS are quoted before replacement to make it shell-safe.
+
<!-- Edit below this comment -->
  
If a variable is specified in $cmd, but not present in %VARS a die is thrown.
 
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
<!-- Pod2Wiki= -->
<h4><span style='display:none'>User Comments</span></h4>
+
<!-- Pod2Wiki=head_methods -->
<!-- Edit below this comment -->
+
==METHODS==
 +
<!-- Pod2Wiki=head_make_name_string -->
 +
===make_name_string===
  
 +
<source lang="perl">$string = EPrints::Utils::make_name_string( $name, [$familylast] )
  
<!-- Pod2Wiki=item_make_name_string --></div>
+
</source>
===$string = EPrints::Utils::make_name_string( $name, [$familylast] )===
 
 
 
 
Return a string containing the name described in the hash reference $name.  
 
Return a string containing the name described in the hash reference $name.  
  
Line 89: Line 71:
 
"honourific given family lineage"
 
"honourific given family lineage"
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_wrap_text --></div>
+
<!-- Pod2Wiki= -->
===$str = EPrints::Utils::wrap_text( $text, [$width], [$init_tab], [$sub_tab] )===
+
<!-- Pod2Wiki=head_wrap_text -->
 +
===wrap_text===
  
Wrap $text to be at most $width (or 80 if undefined) characters per line. As a special case $width may be <tt>console</tt>, in which case the width used is the current console width ({{API:PodLink|file=Term/ReadKey|package_name=Term::ReadKey|section=|text=Term::ReadKey}}).
+
<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).
 
$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).
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_is_set --></div>
+
<!-- Pod2Wiki= -->
===$boolean = EPrints::Utils::is_set( $r )===
+
<!-- Pod2Wiki=head_is_set -->
 +
===is_set===
  
 +
<source lang="perl">$boolean = EPrints::Utils::is_set( $r )
 +
 +
</source>
 
Recursive function.  
 
Recursive function.  
  
Line 119: Line 105:
 
This is used to see if a complex data structure actually has any data in it.
 
This is used to see if a complex data structure actually has any data in it.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_tree_to_utf8 --></div>
+
<!-- Pod2Wiki= -->
===$string = EPrints::Utils::tree_to_utf8( $tree, $width, [$pre], [$whitespace_before], [$ignore_a] )===
+
<!-- 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.
 
Convert a XML DOM tree to a utf-8 encoded string.
  
Line 143: Line 131:
 
&lt;a href="foo"&gt;bar&lt;/a&gt; will be converted into "bar &lt;foo&gt;" unless ignore_a is set.
 
&lt;a href="foo"&gt;bar&lt;/a&gt; will be converted into "bar &lt;foo&gt;" unless ignore_a is set.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=for --></div>
+
<!-- Pod2Wiki= -->
InternalDoc<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
<!-- Pod2Wiki=head_wget -->
<h4><span style='display:none'>User Comments</span></h4>
+
===wget===
<!-- Edit below this comment -->
 
 
 
 
 
<!-- Pod2Wiki=item_copy --></div>
 
===$ok = EPrints::Utils::copy( $source, $target )===
 
 
 
Copy $source file to $target file without alteration.
 
 
 
Return true on success (sets $! on error).
 
 
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
 
 
  
<!-- Pod2Wiki=item_wget --></div>
+
<source lang="perl">$response = EPrints::Utils::wget( $session, $source, $target )
===$response = EPrints::Utils::wget( $session, $source, $target )===
 
  
 +
</source>
 
Copy $source file or URL to $target file without alteration.
 
Copy $source file or URL to $target file without alteration.
  
Line 175: Line 147:
 
Returns the HTTP response object: use $response-&gt;is_success to check whether the copy succeeded.
 
Returns the HTTP response object: use $response-&gt;is_success to check whether the copy succeeded.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=for --></div>
+
<!-- Pod2Wiki= -->
InternalDoc<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
<!-- Pod2Wiki=head_get_input_hidden -->
<h4><span style='display:none'>User Comments</span></h4>
+
===get_input_hidden===
<!-- Edit below this comment -->
 
  
 +
<source lang="perl">EPrints::Utils::get_input_hidden( $regexp, [$prompt], [$default] )
  
<!-- Pod2Wiki=item_rmtree --></div>
+
</source>
===$ok = EPrints::Utils::rmtree( $full_path )===
+
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}}.
  
Unlinks the path and everything in it.
+
Identical to get_input except the characters don't appear.
 
 
Return true on success.
 
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=for --></div>
+
<!-- Pod2Wiki= -->
InternalDoc<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
<!-- Pod2Wiki=head_crypt -->
<h4><span style='display:none'>User Comments</span></h4>
+
===crypt===
<!-- Edit below this comment -->
 
  
 +
<source lang="perl">$crypt = EPrints::Utils::crypt( $value [, $method ] )
  
<!-- Pod2Wiki=item_field_from_config_string --></div>
+
</source>
===$metafield = EPrints::Utils::field_from_config_string( $dataset, $fieldname )===
+
Generate a one-way crypt of $value e.g. for storing passwords.
  
Return the EPrint::MetaField from $dataset with the given name.
+
For available methods see [[API:EPrints/Const|EPrints::Const]]. Defaults to EP_CRYPT_SHA512.
  
If fieldname has a semicolon followed by render options then these are passed as render options to the new EPrints::MetaField object.
 
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=for --></div>
+
<!-- Pod2Wiki= -->
InternalDoc<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
<!-- Pod2Wiki=head_crypt_equals -->
<h4><span style='display:none'>User Comments</span></h4>
+
===crypt_equals===
<!-- Edit below this comment -->
 
  
 +
<source lang="perl">$bool = EPrints::Utils::crypt_equals( $crypt, $value )
  
<!-- Pod2Wiki=item_get_input --></div>
+
</source>
===$string = EPrints::Utils::get_input( $regexp, [$prompt], [$default] )===
+
Test whether the $crypt as previously returned by [[API:EPrints/Utils#crypt|crypt]] for $value matches $value.
  
Read input from the keyboard.
 
 
Prints the promp and default value, if any. eg.
 
How many fish [5] &gt;
 
 
Return the value the user enters at the keyboard.
 
 
If the value does not match the regexp then print the prompt again and try again.
 
 
If a default is set and the user just hits return then the default value is returned.
 
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=for --></div>
+
<!-- Pod2Wiki= -->
InteralDoc<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
<!-- Pod2Wiki=head_url_escape -->
<h4><span style='display:none'>User Comments</span></h4>
+
===url_escape===
<!-- Edit below this comment -->
 
  
 +
<source lang="perl">$string = EPrints::Utils::url_escape( $url )
  
<!-- Pod2Wiki=item_get_input_hidden --></div>
+
</source>
===EPrints::Utils::get_input_hidden( $regexp, [$prompt], [$default] )===
+
Escape the given $url, so that it can appear safely in HTML.
 
 
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.
 
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=for --></div>
+
<!-- Pod2Wiki= -->
InternalDoc<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
<!-- Pod2Wiki=head_uri_escape_utf8 -->
<h4><span style='display:none'>User Comments</span></h4>
+
===uri_escape_utf8===
<!-- Edit below this comment -->
 
 
 
 
 
<!-- Pod2Wiki=item_get_input_confirm --></div>
 
===EPrints::Utils::get_input_confirm( [$prompt], [$quick], [$default] )===
 
 
 
Asks the user for confirmation (yes/no). If $quick is true only checks for a single-character input ('y' or 'n').
 
 
 
If $default is '1' defaults to yes, if '0' defaults to no.
 
  
Returns true if the user answers 'yes' or false for any other value.
+
<source lang="perl">$url = EPrints::Utils::uri_escape_utf8( $str [, $ptn ] )
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
</source>
<h4><span style='display:none'>User Comments</span></h4>
+
Escape utf8 encoded string $str for use in a URI.
<!-- Edit below this comment -->
 
  
 +
Valid characters are [A-Za-z0-9\-\._~"].
  
<!-- Pod2Wiki=for --></div>
 
InternalDoc<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_clone --></div>
+
<!-- Pod2Wiki= -->
===$clone_of_data = EPrints::Utils::clone( $data )===
+
<!-- Pod2Wiki=head_escape_filename -->
 +
===escape_filename===
  
Deep copies the data structure $data, following arrays and hashes.
+
<source lang="perl">$esc_string = EPrints::Utils::escape_filename( $string )
  
Does not handle blessed items.
+
</source>
 +
Take a value and escape it to be a legal filename to go in the /view/ section of the site.
  
Useful when we want to modify a temporary copy of a data structure  that came from the configuration files.
 
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=for --></div>
+
<!-- Pod2Wiki= -->
InternalDoc<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
<!-- Pod2Wiki=head_unescape_filename -->
<h4><span style='display:none'>User Comments</span></h4>
+
===unescape_filename===
<!-- Edit below this comment -->
 
  
 +
<source lang="perl">$string = EPrints::Utils::unescape_filename( $esc_string )
  
<!-- Pod2Wiki=item_crypt_password --></div>
+
</source>
===$crypted_value = EPrints::Utils::crypt_password( $value, $session )===
+
Unescape a string previously escaped with escape_filename().
  
Apply the crypt encoding to the given $value.
 
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_url_escape --></div>
+
<!-- Pod2Wiki= -->
===$string = EPrints::Utils::url_escape( $url )===
+
<!-- Pod2Wiki=head_human_filesize -->
 +
===human_filesize===
  
Escape the given $url, so that it can appear safely in HTML.
+
<source lang="perl">$filesize_text = EPrints::Utils::human_filesize( $size_in_bytes )
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
</source>
<h4><span style='display:none'>User Comments</span></h4>
+
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.
<!-- Edit below this comment -->
 
  
 +
eg. Input of 5234 gives "5KB", input of 3234 gives "3234B".
  
<!-- Pod2Wiki=for --></div>
+
This is not internationalised, I don't think it needs to be. Let me know if this is a problem. support@eprints.org
InternalDoc<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
 
 
 
 
<!-- Pod2Wiki=item_ip2long --></div>
 
===$long = EPrints::Utils::ip2long( $ip )===
 
  
Convert quad-dotted notation to long
 
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_long2ip --></div>
+
<!-- Pod2Wiki= -->
===$ip = EPrints::Utils::long2ip( $ip )===
+
<!-- Pod2Wiki=head_cmp_deeply -->
 +
===cmp_deeply===
  
Convert long to quad-dotted notation
+
<source lang="perl">$ok = cmp_deeply(LEFT, RIGHT)
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
</source>
<h4><span style='display:none'>User Comments</span></h4>
+
Compare structures LEFT and RIGHT using <code>eq</code>, but descend into any array or hash references.
<!-- Edit below this comment -->
 
  
 +
Note: this calls the [[API:EPrints/DataObj#_equal|EPrints::DataObj/_equal]] internal method.
  
<!-- Pod2Wiki=for --></div>
 
InternalDoc<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_cmd_version --></div>
+
<!-- Pod2Wiki= -->
===EPrints::Utils::cmd_version( $progname )===
+
<!-- Pod2Wiki=head_copyright -->
 
+
==COPYRIGHT==
Print out a "--version" style message to STDOUT.
+
: Copyright 2000-2011 University of Southampton.
 
 
$progname is the name of the current script.
 
 
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
 
 
 
 
<!-- Pod2Wiki=item_escape_filename --></div>
 
===$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.
 
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
: This file is part of EPrints http://www.eprints.org/.
<h4><span style='display:none'>User Comments</span></h4>
 
<!-- Edit below this comment -->
 
  
 +
: 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.
  
<!-- Pod2Wiki=item_unescape_filename --></div>
+
: 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.
===$string = EPrints::Utils::unescape_filename( $esc_string )===
 
  
Unescape a string previously escaped with escape_filename().
+
: You should have received a copy of the GNU Lesser General Public License along with EPrints.  If not, see http://www.gnu.org/licenses/.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
<!-- Pod2Wiki=item_human_filesize --></div>
+
<!-- Pod2Wiki= -->
===$filesize_text = EPrints::Utils::human_filesize( $size_in_bytes )===
+
<!-- Pod2Wiki=_postamble_ -->
 
 
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
 
 
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<h4><span style='display:none'>User Comments</span></h4>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
 
 
<!-- Pod2Wiki=_postamble_ --><!-- Edit below this comment -->
 

Latest revision as of 09:56, 22 January 2013

EPrints 3 Reference: Directory Structure - Metadata Fields - Repository Configuration - XML Config Files - XML Export Format - EPrints data structure - Core API - Data Objects


API: Core API

Latest Source Code (3.3, 3.2) | Revision Log | Before editing this page please read Pod2Wiki


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.


get_input_hidden

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