API:EPrints/Utils

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

NAME

EPrints::Utils - Utility functions for EPrints.

DESCRIPTION

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

df_dir

 $space =  EPrints::Utils::df_dir( $dir )

Return the number of bytes of disk space available in the directory $dir or undef if we can't find out.

DEPRECATED - use EPrints::Platform::free_space instead.

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.

join_path

 $path = EPrints::Utils::join_path(@PARTS)

Join a path together in an OS-safe manner. Currently this just joins using '/'. If EPrints is adapted to work under WinOS it will need to use '\' to join paths together.

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.

copy

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

Copy $source file to $target file without alteration.

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

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.

mkdir

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

Create the specified directory.

Return true on success.

rmtree

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

Unlinks the path and everything in it.

Return true on success.

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.

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.

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.

get_input_confirm

 EPrints::Utils::get_input_confirm( [$prompt], [$quick] )

Asks the user for confirmation (yes/no). If $quick is true only checks for a single-character input ('y' or 'n').

Returns true if the user answers 'yes' or false for any other value.

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.

crypt_password

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

Apply the crypt encoding to the given $value.

url_escape

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

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

ip2long

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

Convert quad-dotted notation to long

long2ip

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

Convert long to quad-dotted notation

cmd_version

 EPrints::Utils::cmd_version( $progname )

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

$progname is the name of the current script.

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

UNDOCUMENTED METHODS

These methods were found in the source code but didn't have any POD associated with them. This may be because we haven't got around to documenting them yet or it could be because they are internal to the API and not intended for use by other parts of EPrints.