Difference between revisions of "API:EPrints/Utils"

From EPrints Documentation
Jump to: navigation, search
Line 53: Line 53:
 
This package contains functions which don't belong anywhere else.
 
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%; '>
 +
<span style='display:none'>User Comments</span>
 +
<!-- Edit below this comment -->
 +
 +
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=head_methods -->
 +
==METHODS==
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
<span style='display:none'>User Comments</span>
Line 61: Line 70:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_prepare_cmd -->
 
<!-- Pod2Wiki=item_prepare_cmd -->
−
===$cmd = EPrints::Utils::prepare_cmd($cmd,%VARS)===
+
===prepare_cmd===
  
 +
$cmd = EPrints::Utils::prepare_cmd($cmd,%VARS)
 
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.
 
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.
  
Line 75: Line 85:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_make_name_string -->
 
<!-- Pod2Wiki=item_make_name_string -->
−
===$string = EPrints::Utils::make_name_string( $name, [$familylast] )===
+
===make_name_string===
  
 +
$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 97: Line 108:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_wrap_text -->
 
<!-- Pod2Wiki=item_wrap_text -->
−
===$str = EPrints::Utils::wrap_text( $text, [$width], [$init_tab], [$sub_tab] )===
+
===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 <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}}).
 
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}}).
  
Line 111: Line 123:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_is_set -->
 
<!-- Pod2Wiki=item_is_set -->
−
===$boolean = EPrints::Utils::is_set( $r )===
+
===is_set===
  
 +
$boolean = EPrints::Utils::is_set( $r )
 
Recursive function.  
 
Recursive function.  
  
Line 131: Line 144:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_tree_to_utf8 -->
 
<!-- Pod2Wiki=item_tree_to_utf8 -->
−
===$string = EPrints::Utils::tree_to_utf8( $tree, $width, [$pre], [$whitespace_before], [$ignore_a] )===
+
===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.
 
Convert a XML DOM tree to a utf-8 encoded string.
  
Line 157: Line 171:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_copy -->
 
<!-- Pod2Wiki=item_copy -->
−
===$ok = EPrints::Utils::copy( $source, $target )===
+
===copy===
  
 +
$ok = EPrints::Utils::copy( $source, $target )
 
Copy $source file to $target file without alteration.
 
Copy $source file to $target file without alteration.
  
Line 171: Line 186:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_wget -->
 
<!-- Pod2Wiki=item_wget -->
−
===$response = EPrints::Utils::wget( $session, $source, $target )===
+
===wget===
  
 +
$response = EPrints::Utils::wget( $session, $source, $target )
 
Copy $source file or URL to $target file without alteration.
 
Copy $source file or URL to $target file without alteration.
  
Line 187: Line 203:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_rmtree -->
 
<!-- Pod2Wiki=item_rmtree -->
−
===$ok = EPrints::Utils::rmtree( $full_path )===
+
===rmtree===
  
 +
$ok = EPrints::Utils::rmtree( $full_path )
 
Unlinks the path and everything in it.
 
Unlinks the path and everything in it.
  
Line 201: Line 218:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_field_from_config_string -->
 
<!-- Pod2Wiki=item_field_from_config_string -->
−
===$metafield = EPrints::Utils::field_from_config_string( $dataset, $fieldname )===
+
===field_from_config_string===
  
 +
$metafield = EPrints::Utils::field_from_config_string( $dataset, $fieldname )
 
Return the EPrint::MetaField from $dataset with the given name.
 
Return the EPrint::MetaField from $dataset with the given name.
  
Line 215: Line 233:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_get_input -->
 
<!-- Pod2Wiki=item_get_input -->
−
===$string = EPrints::Utils::get_input( $regexp, [$prompt], [$default] )===
+
===get_input===
  
 +
$string = EPrints::Utils::get_input( $regexp, [$prompt], [$default] )
 
Read input from the keyboard.
 
Read input from the keyboard.
  
Line 236: Line 255:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_get_input_hidden -->
 
<!-- Pod2Wiki=item_get_input_hidden -->
−
===EPrints::Utils::get_input_hidden( $regexp, [$prompt], [$default] )===
+
===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 {{API:PodLink|file=Term/ReadKey|package_name=Term::ReadKey|section=|text=Term::ReadKey}}.
 
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}}.
  
Line 250: Line 270:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_get_input_confirm -->
 
<!-- Pod2Wiki=item_get_input_confirm -->
−
===EPrints::Utils::get_input_confirm( [$prompt], [$quick], [$default] )===
+
===get_input_confirm===
  
 +
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').
 
Asks the user for confirmation (yes/no). If $quick is true only checks for a single-character input ('y' or 'n').
  
Line 266: Line 287:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_clone -->
 
<!-- Pod2Wiki=item_clone -->
−
===$clone_of_data = EPrints::Utils::clone( $data )===
+
===clone===
  
 +
$clone_of_data = EPrints::Utils::clone( $data )
 
Deep copies the data structure $data, following arrays and hashes.
 
Deep copies the data structure $data, following arrays and hashes.
  
Line 282: Line 304:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_crypt_password -->
 
<!-- Pod2Wiki=item_crypt_password -->
−
===$crypted_value = EPrints::Utils::crypt_password( $value, $session )===
+
===crypt_password===
  
 +
$crypted_value = EPrints::Utils::crypt_password( $value, $session )
 
Apply the crypt encoding to the given $value.
 
Apply the crypt encoding to the given $value.
  
Line 294: Line 317:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_url_escape -->
 
<!-- Pod2Wiki=item_url_escape -->
−
===$string = EPrints::Utils::url_escape( $url )===
+
===url_escape===
  
 +
$string = EPrints::Utils::url_escape( $url )
 
Escape the given $url, so that it can appear safely in HTML.
 
Escape the given $url, so that it can appear safely in HTML.
  
Line 306: Line 330:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_ip2long -->
 
<!-- Pod2Wiki=item_ip2long -->
−
===$long = EPrints::Utils::ip2long( $ip )===
+
===ip2long===
  
 +
$long = EPrints::Utils::ip2long( $ip )
 
Convert quad-dotted notation to long
 
Convert quad-dotted notation to long
  
Line 318: Line 343:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_long2ip -->
 
<!-- Pod2Wiki=item_long2ip -->
−
===$ip = EPrints::Utils::long2ip( $ip )===
+
===long2ip===
  
 +
$ip = EPrints::Utils::long2ip( $ip )
 
Convert long to quad-dotted notation
 
Convert long to quad-dotted notation
  
Line 330: Line 356:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_cmd_version -->
 
<!-- Pod2Wiki=item_cmd_version -->
−
===EPrints::Utils::cmd_version( $progname )===
+
===cmd_version===
  
 +
EPrints::Utils::cmd_version( $progname )
 
Print out a "--version" style message to STDOUT.
 
Print out a "--version" style message to STDOUT.
  
Line 344: Line 371:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_escape_filename -->
 
<!-- Pod2Wiki=item_escape_filename -->
−
===$esc_string = EPrints::Utils::escape_filename( $string )===
+
===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.
 
Take a value and escape it to be a legal filename to go in the /view/ section of the site.
  
Line 356: Line 384:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_unescape_filename -->
 
<!-- Pod2Wiki=item_unescape_filename -->
−
===$string = EPrints::Utils::unescape_filename( $esc_string )===
+
===unescape_filename===
  
 +
$string = EPrints::Utils::unescape_filename( $esc_string )
 
Unescape a string previously escaped with escape_filename().
 
Unescape a string previously escaped with escape_filename().
  
Line 368: Line 397:
 
</div>
 
</div>
 
<!-- Pod2Wiki=item_human_filesize -->
 
<!-- Pod2Wiki=item_human_filesize -->
−
===$filesize_text = EPrints::Utils::human_filesize( $size_in_bytes )===
+
===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.
 
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.
  

Revision as of 13:43, 25 February 2010

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.4, 3.3) | 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 ) 
 # 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"

User Comments


DESCRIPTION

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

User Comments


METHODS

User Comments


prepare_cmd

$cmd = EPrints::Utils::prepare_cmd($cmd,%VARS)

Prepare command string $cmd by substituting variables (specified by $(varname)) with their value from %VARS (key is varname). All %VARS are quoted before replacement to make it shell-safe.

If a variable is specified in $cmd, but not present in %VARS a die is thrown.

User Comments


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"

User Comments


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

User Comments


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.

User Comments


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.

User Comments


copy

$ok = EPrints::Utils::copy( $source, $target )

Copy $source file to $target file without alteration.

Return true on success (sets $! on error).

User Comments


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.

User Comments


rmtree

$ok = EPrints::Utils::rmtree( $full_path )

Unlinks the path and everything in it.

Return true on success.

User Comments


field_from_config_string

$metafield = EPrints::Utils::field_from_config_string( $dataset, $fieldname )

Return the EPrint::MetaField from $dataset with the given name.

If fieldname has a semicolon followed by render options then these are passed as render options to the new EPrints::MetaField object.

User Comments


get_input

$string = EPrints::Utils::get_input( $regexp, [$prompt], [$default] )

Read input from the keyboard.

Prints the promp and default value, if any. eg. 

How many fish [5] >

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.

User Comments


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.

User Comments


get_input_confirm

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.

User Comments


clone

$clone_of_data = EPrints::Utils::clone( $data )

Deep copies the data structure $data, following arrays and hashes.

Does not handle blessed items.

Useful when we want to modify a temporary copy of a data structure that came from the configuration files.

User Comments


crypt_password

$crypted_value = EPrints::Utils::crypt_password( $value, $session )

Apply the crypt encoding to the given $value.

User Comments


url_escape

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

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

User Comments


ip2long

$long = EPrints::Utils::ip2long( $ip )

Convert quad-dotted notation to long

User Comments


long2ip

$ip = EPrints::Utils::long2ip( $ip )

Convert long to quad-dotted notation

User Comments


cmd_version

EPrints::Utils::cmd_version( $progname )

Print out a "--version" style message to STDOUT.

$progname is the name of the current script.

User Comments


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.

User Comments


unescape_filename

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

Unescape a string previously escaped with escape_filename().

User Comments


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

User Comments


Retrieved from ‘https://wiki.eprints.org/w/index.php?title=API:EPrints/Utils&oldid=8762’