Edit D:\app\Administrator\product\11.2.0\dbhome_1\perl\html\lib\File\Fetch.html
<?xml version="1.0" ?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <title>File::Fetch - A generic file fetching mechanism</title> <meta http-equiv="content-type" content="text/html; charset=utf-8" /> <link rev="made" href="mailto:" /> </head> <body style="background-color: white"> <table border="0" width="100%" cellspacing="0" cellpadding="3"> <tr><td class="block" style="background-color: #cccccc" valign="middle"> <big><strong><span class="block"> File::Fetch - A generic file fetching mechanism</span></strong></big> </td></tr> </table> <!-- INDEX BEGIN --> <div name="index"> <p><a name="__index__"></a></p> <ul> <li><a href="#name">NAME</a></li> <li><a href="#synopsis">SYNOPSIS</a></li> <li><a href="#description">DESCRIPTION</a></li> <li><a href="#accessors">ACCESSORS</a></li> <li><a href="#methods">METHODS</a></li> <ul> <li><a href="#_ff___file__fetch__new__uri_____http___some_where_com_dir_file_txt____">$ff = File::Fetch->new( uri => 'http://some.where.com/dir/file.txt' );</a></li> <li><a href="#_ff__fetch___to_____my_output_dir____">$ff->fetch( [to => /my/output/dir/] )</a></li> <li><a href="#_ff__error__bool__">$ff->error([BOOL])</a></li> </ul> <li><a href="#how_it_works">HOW IT WORKS</a></li> <li><a href="#global_variables">GLOBAL VARIABLES</a></li> <ul> <li><a href="#_file__fetch__from_email">$File::Fetch::FROM_EMAIL</a></li> <li><a href="#_file__fetch__user_agent">$File::Fetch::USER_AGENT</a></li> <li><a href="#_file__fetch__ftp_passive">$File::Fetch::FTP_PASSIVE</a></li> <li><a href="#_file__fetch__timeout">$File::Fetch::TIMEOUT</a></li> <li><a href="#_file__fetch__warn">$File::Fetch::WARN</a></li> <li><a href="#_file__fetch__debug">$File::Fetch::DEBUG</a></li> <li><a href="#_file__fetch__blacklist">$File::Fetch::BLACKLIST</a></li> <li><a href="#_file__fetch__method_fail">$File::Fetch::METHOD_FAIL</a></li> </ul> <li><a href="#mapping">MAPPING</a></li> <li><a href="#frequently_asked_questions">FREQUENTLY ASKED QUESTIONS</a></li> <ul> <li><a href="#so_how_do_i_use_a_proxy_with_file__fetch">So how do I use a proxy with File::Fetch?</a></li> <li><a href="#i_used__lynx__to_fetch_a_file__but_its_contents_is_all_wrong_">I used 'lynx' to fetch a file, but its contents is all wrong!</a></li> <li><a href="#files_i_m_trying_to_fetch_have_reserved_characters_or_non_ascii_characters_in_them__what_do_i_do">Files I'm trying to fetch have reserved characters or non-ASCII characters in them. What do I do?</a></li> </ul> <li><a href="#todo">TODO</a></li> <li><a href="#bug_reports">BUG REPORTS</a></li> <li><a href="#author">AUTHOR</a></li> <li><a href="#copyright">COPYRIGHT</a></li> </ul> <hr name="index" /> </div> <!-- INDEX END --> <p> </p> <h1><a name="name">NAME</a></h1> <p>File::Fetch - A generic file fetching mechanism</p> <p> </p> <hr /> <h1><a name="synopsis">SYNOPSIS</a></h1> <pre> use File::Fetch;</pre> <pre> ### build a File::Fetch object ### my $ff = File::Fetch->new(uri => '<a href="http://some.where.com/dir/a.txt">http://some.where.com/dir/a.txt</a>');</pre> <pre> ### fetch the uri to cwd() ### my $where = $ff->fetch() or die $ff->error;</pre> <pre> ### fetch the uri to /tmp ### my $where = $ff->fetch( to => '/tmp' );</pre> <pre> ### parsed bits from the uri ### $ff->uri; $ff->scheme; $ff->host; $ff->path; $ff->file;</pre> <p> </p> <hr /> <h1><a name="description">DESCRIPTION</a></h1> <p>File::Fetch is a generic file fetching mechanism.</p> <p>It allows you to fetch any file pointed to by a <code>ftp</code>, <code>http</code>, <a href="#file"><code>file</code></a>, or <code>rsync</code> uri by a number of different means.</p> <p>See the <code>HOW IT WORKS</code> section further down for details.</p> <p> </p> <hr /> <h1><a name="accessors">ACCESSORS</a></h1> <p>A <code>File::Fetch</code> object has the following accessors</p> <dl> <dt><strong><a name="uri" class="item">$ff->uri</a></strong> <dd> <p>The uri you passed to the constructor</p> </dd> </li> <dt><strong><a name="scheme" class="item">$ff->scheme</a></strong> <dd> <p>The scheme from the uri (like 'file', 'http', etc)</p> </dd> </li> <dt><strong><a name="host" class="item">$ff->host</a></strong> <dd> <p>The hostname in the uri. Will be empty if host was originally 'localhost' for a 'file://' url.</p> </dd> </li> <dt><strong><a name="vol" class="item">$ff->vol</a></strong> <dd> <p>On operating systems with the concept of a volume the second element of a file:// is considered to the be volume specification for the file. Thus on Win32 this routine returns the volume, on other operating systems this returns nothing.</p> </dd> <dd> <p>On Windows this value may be empty if the uri is to a network share, in which case the 'share' property will be defined. Additionally, volume specifications that use '|' as ':' will be converted on read to use ':'.</p> </dd> <dd> <p>On VMS, which has a volume concept, this field will be empty because VMS file specifications are converted to absolute UNIX format and the volume information is transparently included.</p> </dd> </li> <dt><strong><a name="share" class="item">$ff->share</a></strong> <dd> <p>On systems with the concept of a network share (currently only Windows) returns the sharename from a file://// url. On other operating systems returns empty.</p> </dd> </li> <dt><strong><a name="path" class="item">$ff->path</a></strong> <dd> <p>The path from the uri, will be at least a single '/'.</p> </dd> </li> <dt><strong><a name="file" class="item">$ff->file</a></strong> <dd> <p>The name of the remote file. For the local file name, the result of $ff->output_file will be used.</p> </dd> </li> <dt><strong><a name="output_file" class="item">$ff->output_file</a></strong> <dd> <p>The name of the output file. This is the same as $ff->file, but any query parameters are stripped off. For example:</p> </dd> <dd> <pre> <a href="http://example.com/index.html?x=y">http://example.com/index.html?x=y</a></pre> </dd> <dd> <p>would make the output file be <code>index.html</code> rather than <code>index.html?x=y</code>.</p> </dd> </li> </dl> <p> </p> <hr /> <h1><a name="methods">METHODS</a></h1> <p> </p> <h2><a name="_ff___file__fetch__new__uri_____http___some_where_com_dir_file_txt____">$ff = File::Fetch->new( uri => 'http://some.where.com/dir/file.txt' );</a></h2> <p>Parses the uri and creates a corresponding File::Fetch::Item object, that is ready to be <code>fetch</code>ed and returns it.</p> <p>Returns false on failure.</p> <p> </p> <h2><a name="_ff__fetch___to_____my_output_dir____">$ff->fetch( [to => /my/output/dir/] )</a></h2> <p>Fetches the file you requested. By default it writes to <code>cwd()</code>, but you can override that by specifying the <code>to</code> argument.</p> <p>Returns the full path to the downloaded file on success, and false on failure.</p> <p> </p> <h2><a name="_ff__error__bool__">$ff->error([BOOL])</a></h2> <p>Returns the last encountered error as string. Pass it a true value to get the <code>Carp::longmess()</code> output instead.</p> <p> </p> <hr /> <h1><a name="how_it_works">HOW IT WORKS</a></h1> <p>File::Fetch is able to fetch a variety of uris, by using several external programs and modules.</p> <p>Below is a mapping of what utilities will be used in what order for what schemes, if available:</p> <pre> file => LWP, file http => LWP, wget, curl, lynx ftp => LWP, Net::FTP, wget, curl, ncftp, ftp rsync => rsync</pre> <p>If you'd like to disable the use of one or more of these utilities and/or modules, see the <code>$BLACKLIST</code> variable further down.</p> <p>If a utility or module isn't available, it will be marked in a cache (see the <code>$METHOD_FAIL</code> variable further down), so it will not be tried again. The <code>fetch</code> method will only fail when all options are exhausted, and it was not able to retrieve the file.</p> <p>A special note about fetching files from an ftp uri:</p> <p>By default, all ftp connections are done in passive mode. To change that, see the <code>$FTP_PASSIVE</code> variable further down.</p> <p>Furthermore, ftp uris only support anonymous connections, so no named user/password pair can be passed along.</p> <p><code>/bin/ftp</code> is blacklisted by default; see the <code>$BLACKLIST</code> variable further down.</p> <p> </p> <hr /> <h1><a name="global_variables">GLOBAL VARIABLES</a></h1> <p>The behaviour of File::Fetch can be altered by changing the following global variables:</p> <p> </p> <h2><a name="_file__fetch__from_email">$File::Fetch::FROM_EMAIL</a></h2> <p>This is the email address that will be sent as your anonymous ftp password.</p> <p>Default is <code>File-Fetch@example.com</code>.</p> <p> </p> <h2><a name="_file__fetch__user_agent">$File::Fetch::USER_AGENT</a></h2> <p>This is the useragent as <code>LWP</code> will report it.</p> <p>Default is <code>File::Fetch/$VERSION</code>.</p> <p> </p> <h2><a name="_file__fetch__ftp_passive">$File::Fetch::FTP_PASSIVE</a></h2> <p>This variable controls whether the environment variable <code>FTP_PASSIVE</code> and any passive switches to commandline tools will be set to true.</p> <p>Default value is 1.</p> <p>Note: When $FTP_PASSIVE is true, <code>ncftp</code> will not be used to fetch files, since passive mode can only be set interactively for this binary</p> <p> </p> <h2><a name="_file__fetch__timeout">$File::Fetch::TIMEOUT</a></h2> <p>When set, controls the network timeout (counted in seconds).</p> <p>Default value is 0.</p> <p> </p> <h2><a name="_file__fetch__warn">$File::Fetch::WARN</a></h2> <p>This variable controls whether errors encountered internally by <code>File::Fetch</code> should be <code>carp</code>'d or not.</p> <p>Set to false to silence warnings. Inspect the output of the <code>error()</code> method manually to see what went wrong.</p> <p>Defaults to <code>true</code>.</p> <p> </p> <h2><a name="_file__fetch__debug">$File::Fetch::DEBUG</a></h2> <p>This enables debugging output when calling commandline utilities to fetch files. This also enables <code>Carp::longmess</code> errors, instead of the regular <code>carp</code> errors.</p> <p>Good for tracking down why things don't work with your particular setup.</p> <p>Default is 0.</p> <p> </p> <h2><a name="_file__fetch__blacklist">$File::Fetch::BLACKLIST</a></h2> <p>This is an array ref holding blacklisted modules/utilities for fetching files with.</p> <p>To disallow the use of, for example, <code>LWP</code> and <code>Net::FTP</code>, you could set $File::Fetch::BLACKLIST to:</p> <pre> $File::Fetch::BLACKLIST = [qw|lwp netftp|]</pre> <p>The default blacklist is [qw|ftp|], as <code>/bin/ftp</code> is rather unreliable.</p> <p>See the note on <code>MAPPING</code> below.</p> <p> </p> <h2><a name="_file__fetch__method_fail">$File::Fetch::METHOD_FAIL</a></h2> <p>This is a hashref registering what modules/utilities were known to fail for fetching files (mostly because they weren't installed).</p> <p>You can reset this cache by assigning an empty hashref to it, or individually remove keys.</p> <p>See the note on <code>MAPPING</code> below.</p> <p> </p> <hr /> <h1><a name="mapping">MAPPING</a></h1> <p>Here's a quick mapping for the utilities/modules, and their names for the $BLACKLIST, $METHOD_FAIL and other internal functions.</p> <pre> LWP => lwp Net::FTP => netftp wget => wget lynx => lynx ncftp => ncftp ftp => ftp curl => curl rsync => rsync</pre> <p> </p> <hr /> <h1><a name="frequently_asked_questions">FREQUENTLY ASKED QUESTIONS</a></h1> <p> </p> <h2><a name="so_how_do_i_use_a_proxy_with_file__fetch">So how do I use a proxy with File::Fetch?</a></h2> <p><code>File::Fetch</code> currently only supports proxies with LWP::UserAgent. You will need to set your environment variables accordingly. For example, to use an ftp proxy:</p> <pre> $ENV{ftp_proxy} = 'foo.com';</pre> <p>Refer to the LWP::UserAgent manpage for more details.</p> <p> </p> <h2><a name="i_used__lynx__to_fetch_a_file__but_its_contents_is_all_wrong_">I used 'lynx' to fetch a file, but its contents is all wrong!</a></h2> <p><code>lynx</code> can only fetch remote files by dumping its contents to <code>STDOUT</code>, which we in turn capture. If that content is a 'custom' error file (like, say, a <code>404 handler</code>), you will get that contents instead.</p> <p>Sadly, <code>lynx</code> doesn't support any options to return a different exit code on non-<code>200 OK</code> status, giving us no way to tell the difference between a 'successfull' fetch and a custom error page.</p> <p>Therefor, we recommend to only use <code>lynx</code> as a last resort. This is why it is at the back of our list of methods to try as well.</p> <p> </p> <h2><a name="files_i_m_trying_to_fetch_have_reserved_characters_or_non_ascii_characters_in_them__what_do_i_do">Files I'm trying to fetch have reserved characters or non-ASCII characters in them. What do I do?</a></h2> <p><code>File::Fetch</code> is relatively smart about things. When trying to write a file to disk, it removes the <code>query parameters</code> (see the <a href="#output_file"><code>output_file</code></a> method for details) from the file name before creating it. In most cases this suffices.</p> <p>If you have any other characters you need to escape, please install the <code>URI::Escape</code> module from CPAN, and pre-encode your URI before passing it to <code>File::Fetch</code>. You can read about the details of URIs and URI encoding here:</p> <pre> <a href="http://www.faqs.org/rfcs/rfc2396.html">http://www.faqs.org/rfcs/rfc2396.html</a></pre> <p> </p> <hr /> <h1><a name="todo">TODO</a></h1> <dl> <dt><strong><a name="implement_prefer_bin" class="item">Implement $PREFER_BIN</a></strong> <dd> <p>To indicate to rather use commandline tools than modules</p> </dd> </li> </dl> <p> </p> <hr /> <h1><a name="bug_reports">BUG REPORTS</a></h1> <p>Please report bugs or other issues to <<a href="mailto:bug-file-fetch@rt.cpan.org<gt>">bug-file-fetch@rt.cpan.org<gt></a>.</p> <p> </p> <hr /> <h1><a name="author">AUTHOR</a></h1> <p>This module by Jos Boumans <<a href="mailto:kane@cpan.org">kane@cpan.org</a>>.</p> <p> </p> <hr /> <h1><a name="copyright">COPYRIGHT</a></h1> <p>This library is free software; you may redistribute and/or modify it under the same terms as Perl itself.</p> <table border="0" width="100%" cellspacing="0" cellpadding="3"> <tr><td class="block" style="background-color: #cccccc" valign="middle"> <big><strong><span class="block"> File::Fetch - A generic file fetching mechanism</span></strong></big> </td></tr> </table> </body> </html>
Ms-Dos/Windows
Unix
Write backup
jsp File Browser version 1.2 by
www.vonloesch.de