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
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.
InternalDoc
$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.
$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"
$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).
$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.
$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.
InternalDoc
$ok = EPrints::Utils::copy( $source, $target )
Copy $source file to $target file without alteration.
Return true on success (sets $! on error).
$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.
InternalDoc
$ok = EPrints::Utils::rmtree( $full_path )
Unlinks the path and everything in it.
Return true on success.
InternalDoc
$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.
InternalDoc
$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.
InteralDoc
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.
InternalDoc
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.
InternalDoc
$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.
InternalDoc
$crypted_value = EPrints::Utils::crypt_password( $value, $session )
Apply the crypt encoding to the given $value.
$string = EPrints::Utils::url_escape( $url )
Escape the given $url, so that it can appear safely in HTML.
InternalDoc
$long = EPrints::Utils::ip2long( $ip )
Convert quad-dotted notation to long
$ip = EPrints::Utils::long2ip( $ip )
Convert long to quad-dotted notation
InternalDoc
EPrints::Utils::cmd_version( $progname )
Print out a "--version" style message to STDOUT.
$progname is the name of the current script.
$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.
$string = EPrints::Utils::unescape_filename( $esc_string )
Unescape a string previously escaped with escape_filename().
$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
