Difference between revisions of "API:EPrints/Utils"

From EPrints Documentation
Jump to: navigation, search
Line 1: Line 1:
werer
+
<!-- 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.
 +
-->
 +
__NOTOC__
 +
{{Pod2Wiki}}{{API:Source|file=EPrints/Utils.pm|package_name=EPrints::Utils}}[[Category:API|Utils]]<div><!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki=head_name --></div>
 +
==NAME==
 +
'''EPrints::Utils''' - Utility functions for EPrints.
 +
 
 +
<div style='background-color: #eef; 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=head_synopsis --></div>
 +
==SYNOPSIS==
 +
$boolean = EPrints::Utils::is_set( $object ) #returns true if an object/scalar/array has any data in it
 +
 
 +
$response = EPrints::Utils::wget( $handle, "http://www.eprints.org/index.php", "temp_dir/my_file" ) # copy the contents of the url to a file if($response-&gt;is_sucess()){ do something...}
 +
 
 +
$string = EPrints::Utils::make_name_string( given=&gt;"Bob", family=&gt;"Smith",honourific=&gt;"Mr", 1 ) returns "Mr Bob Smith" $string = EPrints::Utils::make_name_string( given=&gt;"Bob", family=&gt;"Smith",honourific=&gt;"Mr", 0 ) returns Mr Smith, Bob
 +
 
 +
$string = EPrints::Utils::url_escape( "http://www.eprints.org?var=1&amp;var2=2" ); # returns http://www.eprints.org?var=1&amp;ampvar2=2
 +
 
 +
$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: #eef; 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=head_description --></div>
 +
==DESCRIPTION==
 +
This package contains functions which don't belong anywhere else.
 +
 
 +
<div style='background-color: #eef; 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_make_name_string --></div>
 +
===$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"
 +
 
 +
<div style='background-color: #eef; 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_wrap_text --></div>
 +
===$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 <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}}).
 +
 
 +
$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: #eef; 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_is_set --></div>
 +
===$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.
 +
 
 +
<div style='background-color: #eef; 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_tree_to_utf8 --></div>
 +
===$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:
 +
 
 +
&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.
 +
 
 +
<div style='background-color: #eef; 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>
 +
===$response = EPrints::Utils::wget( $handle, $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-&gt;is_success to check whether the copy succeeded.
 +
 
 +
<div style='background-color: #eef; 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_url_escape --></div>
 +
===$string = EPrints::Utils::url_escape( $url )===
 +
 
 +
Escape the given $url, so that it can appear safely in HTML.
 +
 
 +
<div style='background-color: #eef; 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: #eef; 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_unescape_filename --></div>
 +
===$string = EPrints::Utils::unescape_filename( $esc_string )===
 +
 
 +
Unescape a string previously escaped with escape_filename().
 +
 
 +
<div style='background-color: #eef; 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_human_filesize --></div>
 +
===$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
 +
 
 +
<div style='background-color: #eef; 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=_postamble_ --><!-- Edit below this comment -->

Revision as of 16:01, 19 August 2009


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


NAME

EPrints::Utils - Utility functions for EPrints.

User Comments


SYNOPSIS

$boolean = EPrints::Utils::is_set( $object ) #returns true if an object/scalar/array has any data in it

$response = EPrints::Utils::wget( $handle, "http://www.eprints.org/index.php", "temp_dir/my_file" ) # copy the contents of the url to a file if($response->is_sucess()){ do something...}

$string = EPrints::Utils::make_name_string( given=>"Bob", family=>"Smith",honourific=>"Mr", 1 ) returns "Mr Bob Smith" $string = EPrints::Utils::make_name_string( given=>"Bob", family=>"Smith",honourific=>"Mr", 0 ) returns Mr Smith, Bob

$string = EPrints::Utils::url_escape( "http://www.eprints.org?var=1&var2=2" ); # returns http://www.eprints.org?var=1&ampvar2=2

$esc_string = EPrints::Utils::escape_filename( $string );

$string = EPrints::Utils::unescape_filename( $esc_string );

$filesize_text = EPrints::Utils::human_filesize( 3300 ); # returns "3kb"

User Comments


DESCRIPTION

This package contains functions which don't belong anywhere else.

User Comments


$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"

User Comments


$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).

User Comments


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

User Comments


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

User Comments


$response = EPrints::Utils::wget( $handle, $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.

User Comments


$string = EPrints::Utils::url_escape( $url )

Escape the given $url, so that it can appear safely in HTML.

User Comments


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

User Comments


$string = EPrints::Utils::unescape_filename( $esc_string )

Unescape a string previously escaped with escape_filename().

User Comments


$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

User Comments