Difference between revisions of "API:EPrints/Utils"

From EPrints Documentation
Jump to: navigation, search
(New page: <!-- Pod2Wiki=_preamble_ This page has been automatically generated from the EPrints source. Any wiki changes made between the 'Pod2Wiki=*' and 'End of Pod2Wiki' comments will be lost. -...)
(Removing all content from page)
Line 1: Line 1:
<!-- Pod2Wiki=_preamble_
This page has been automatically generated from the EPrints source. Any wiki changes made between the 'Pod2Wiki=*' and 'End of Pod2Wiki' comments will be lost.
-->{{Pod2Wiki}}{{API:Source|file=EPrints/Utils.pm|package_name=EPrints::Utils}}[[Category:API|Utils]]<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=head_name -->=NAME=
'''EPrints::Utils''' - Utility functions for EPrints.
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=head_description -->=DESCRIPTION=
This package contains functions which don't belong anywhere else.
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_df_dir -->==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.
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_prepare_cmd -->==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.
If a variable is specified in $cmd, but not present in %VARS a die is thrown.
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_join_path -->==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.
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_make_name_string -->==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"
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_wrap_text -->==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}}).
$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).
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_is_set -->==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.
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_tree_to_utf8 -->==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:
&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.
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_copy -->==copy==
  $ok = EPrints::Utils::copy( $source, $target )
Copy $source file to $target file without alteration.
Return true on success (sets $! on error).
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_wget -->==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-&gt;is_success to check whether the copy succeeded.
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_mkdir -->==mkdir==
  $ok = EPrints::Utils::mkdir( $full_path )
Create the specified directory.
Return true on success.
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_rmtree -->==rmtree==
  $ok = EPrints::Utils::rmtree( $full_path )
Unlinks the path and everything in it.
Return true on success.
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_field_from_config_string -->==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.
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_get_input -->==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] &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.
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_get_input_hidden -->==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}}.
Identical to get_input except the characters don't appear.
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_get_input_confirm -->==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.
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_clone -->==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.
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_crypt_password -->==crypt_password==
  $crypted_value = EPrints::Utils::crypt_password( $value, $session )
Apply the crypt encoding to the given $value.
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_url_escape -->==url_escape==
  $string = EPrints::Utils::url_escape( $url )
Escape the given $url, so that it can appear safely in HTML.
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_ip2long -->==ip2long==
  $long = EPrints::Utils::ip2long( $ip )
Convert quad-dotted notation to long
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_long2ip -->==long2ip==
  $ip = EPrints::Utils::long2ip( $ip )
Convert long to quad-dotted notation
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_cmd_version -->==cmd_version==
  EPrints::Utils::cmd_version( $progname )
Print out a "--version" style message to STDOUT.
$progname is the name of the current script.
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_escape_filename -->==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.
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_unescape_filename -->==unescape_filename==
  $string = EPrints::Utils::unescape_filename( $esc_string )
Unescape a string previously escaped with escape_filename().
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_human_filesize -->==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
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=head_undocumented_methods -->=UNDOCUMENTED METHODS=
{{API:Undocumented Methods}}<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_chown_for_eprints -->==chown_for_eprints==
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_collapse_conditions -->==collapse_conditions==
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_datestring_to_timet -->==datestring_to_timet==
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_destroy -->==destroy==
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_get_date -->==get_date==
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_get_date_array -->==get_date_array==
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_get_datestamp -->==get_datestamp==
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_get_iso_date -->==get_iso_date==
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_get_iso_timestamp -->==get_iso_timestamp==
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_get_month_label -->==get_month_label==
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_get_month_label_short -->==get_month_label_short==
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_get_timestamp -->==get_timestamp==
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_gmt_off -->==gmt_off==
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_human_delay -->==human_delay==
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_human_time -->==human_time==
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_js_string -->==js_string==
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_mtime -->==mtime==
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_render_citation -->==render_citation==
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_render_date -->==render_date==
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_render_short_date -->==render_short_date==
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_render_xhtml_field -->==render_xhtml_field==
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_require_if_exists -->==require_if_exists==
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_send_mail -->==send_mail==
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_send_mail_via_sendmail -->==send_mail_via_sendmail==
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=item_send_mail_via_smtp -->==send_mail_via_smtp==
<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=_postamble_ --><!-- End of Pod2Wiki -->

Revision as of 15:41, 12 August 2009