内容

• 名称
• 概要
• 描述
• 访问器
• 方法
  • $ff = File::Fetch->new( uri => 'http://some.where.com/dir/file.txt' );
  • $where = $ff->fetch( [to => /my/output/dir/ | \$scalar] )
  • $ff->error([BOOL])
• 工作原理
• 全局变量
  • $File::Fetch::FROM_EMAIL
  • $File::Fetch::USER_AGENT
  • $File::Fetch::FTP_PASSIVE
  • $File::Fetch::TIMEOUT
  • $File::Fetch::WARN
  • $File::Fetch::DEBUG
  • $File::Fetch::BLACKLIST
  • $File::Fetch::METHOD_FAIL
• 映射
• 常见问题解答
  • 那么如何使用代理与 File::Fetch?
  • 我使用 'lynx' 获取文件，但其内容完全错误！
  • 我尝试获取的文件包含保留字符或非 ASCII 字符。我该怎么办？
• 待办事项
• 错误报告
• 作者
• 版权

#名称

File::Fetch - 通用文件获取机制

#概要

use File::Fetch;

### build a File::Fetch object ###
my $ff = File::Fetch->new(uri => 'http://some.where.com/dir/a.txt');

### fetch the uri to cwd() ###
my $where = $ff->fetch() or die $ff->error;

### fetch the uri to /tmp ###
my $where = $ff->fetch( to => '/tmp' );

### parsed bits from the uri ###
$ff->uri;
$ff->scheme;
$ff->host;
$ff->path;
$ff->file;

#描述

File::Fetch 是一个通用的文件获取机制。

它允许您通过多种方式获取指向 ftp、http、file、git 或 rsync uri 的任何文件。

有关详细信息，请参阅下面“工作原理”部分。

#访问器

一个 File::Fetch 对象具有以下访问器

#$ff->uri

您传递给构造函数的 uri

#$ff->scheme

uri 中的方案（如 'file'、'http' 等）

#$ff->host

uri 中的主机名。如果主机最初是 'localhost' 用于 'file://' url，则为空。

#$ff->vol

在具有卷概念的操作系统上，file:// 的第二个元素被认为是文件的卷规范。因此，在 Win32 上，此例程返回卷，在其他操作系统上，此例程不返回任何内容。

在 Windows 上，如果 uri 指向网络共享，则此值可能为空，在这种情况下，将定义 'share' 属性。此外，使用 '|' 作为 ':' 的卷规范将在读取时转换为使用 ':'。

在具有卷概念的 VMS 上，此字段将为空，因为 VMS 文件规范将转换为绝对 UNIX 格式，并且卷信息将透明地包含在内。

#$ff->share

在具有网络共享概念的系统上（目前仅限 Windows）从 file://// url 返回共享名。在其他操作系统上返回空。

#$ff->path

uri 中的路径，至少为单个 '/'。

#$ff->file

远程文件的名称。对于本地文件名，将使用 $ff->output_file 的结果。

#$ff->file_default

如果 $ff->output_file 无法返回文件名，则会回退到此默认本地文件名。例如，当获取类似 http://www.abc.net.au/ 的 URI 时，检索到的内容可能来自名为 'index.html' 的远程文件。此属性的默认值为 'file_default'。

#$ff->output_file

输出文件的名称。这与 $ff->file 相同，但会去除所有查询参数。例如

http://example.com/index.html?x=y

将使输出文件为 index.html 而不是 index.html?x=y。

#METHODS

#$ff = File::Fetch->new( uri => 'http://some.where.com/dir/file.txt' );

解析 uri 并创建一个相应的 File::Fetch::Item 对象，该对象已准备好进行 fetch 操作并返回它。

失败时返回 false。

#$where = $ff->fetch( [to => /my/output/dir/ | \$scalar] )

获取您请求的文件并返回文件的完整路径。

默认情况下，它写入 cwd()，但您可以通过指定 to 参数来覆盖它。

### file fetch to /tmp, full path to the file in $where
$where = $ff->fetch( to => '/tmp' );

### file slurped into $scalar, full path to the file in $where
### file is downloaded to a temp directory and cleaned up at exit time
$where = $ff->fetch( to => \$scalar );

成功时返回下载文件的完整路径，失败时返回 false。

#$ff->error([BOOL])

返回最后遇到的错误作为字符串。传递一个真值以获取 Carp::longmess() 输出。

#HOW IT WORKS

File::Fetch 可以通过使用多个外部程序和模块来获取各种 uri。

以下是针对哪些方案将按什么顺序使用哪些实用程序的映射，如果可用。

file    => LWP, lftp, file
http    => LWP, HTTP::Tiny, wget, curl, lftp, fetch, HTTP::Lite, lynx, iosock
ftp     => LWP, Net::FTP, wget, curl, lftp, fetch, ncftp, ftp
rsync   => rsync
git     => git

如果您想禁用一个或多个这些实用程序和/或模块的使用，请参阅下面的 $BLACKLIST 变量。

如果实用程序或模块不可用，它将在缓存中标记（参见下面的 $METHOD_FAIL 变量），因此不会再次尝试。fetch 方法只有在所有选项都用尽并且无法检索文件时才会失败。

fetch 实用程序在 FreeBSD 上可用。NetBSD 和 Dragonfly BSD 也可能从 pkgsrc 获得它。我们只在这三个平台上检查 fetch。

iosock 是一种非常有限的基于 IO::Socket::INET 的机制，用于检索 http 协议的 URL。例如，它不支持重定向。

git 只支持 git:// 样式的 URL。

关于从 ftp URI 获取文件的特别说明

默认情况下，所有 ftp 连接都使用被动模式。要更改此设置，请参阅下面介绍的 $FTP_PASSIVE 变量。

此外，ftp URI 只支持匿名连接，因此无法传递任何命名用户/密码对。

/bin/ftp 默认情况下被列入黑名单；请参阅下面介绍的 $BLACKLIST 变量。

#全局变量

可以通过更改以下全局变量来改变 File::Fetch 的行为

#$File::Fetch::FROM_EMAIL

这是将作为您的匿名 ftp 密码发送的电子邮件地址。

默认值为 [email protected]。

#$File::Fetch::USER_AGENT

这是 LWP 将报告的用户代理。

默认值为 File::Fetch/$VERSION。

#$File::Fetch::FTP_PASSIVE

此变量控制是否将环境变量 FTP_PASSIVE 和命令行工具的任何被动开关设置为 true。

默认值为 1。

注意：当 $FTP_PASSIVE 为 true 时，ncftp 将不会用于获取文件，因为被动模式只能为该二进制文件交互式设置。

#$File::Fetch::TIMEOUT

设置后，控制网络超时（以秒为单位）。

默认值为 0。

#$File::Fetch::WARN

此变量控制是否应该 carp File::Fetch 内部遇到的错误。

设置为 false 以静默警告。手动检查 error() 方法的输出以查看发生了什么错误。

默认为 true。

#$File::Fetch::DEBUG

这在调用命令行实用程序来获取文件时启用调试输出。这也启用 Carp::longmess 错误，而不是常规的 carp 错误。

有助于跟踪为什么某些操作在您的特定设置中不起作用。

默认值为 0。

#$File::Fetch::BLACKLIST

这是一个数组引用，包含用于获取文件的黑名单模块/实用程序。

例如，要禁止使用 LWP 和 Net::FTP，可以将 $File::Fetch::BLACKLIST 设置为

$File::Fetch::BLACKLIST = [qw|lwp netftp|]

默认黑名单是 [qw|ftp|]，因为 /bin/ftp 非常不可靠。

请参阅下方关于MAPPING的说明。

#$File::Fetch::METHOD_FAIL

这是一个哈希引用，记录了哪些模块/工具在获取文件时已知会失败（主要是因为它们未安装）。

您可以通过将空哈希引用分配给它来重置此缓存，或单独删除键。

请参阅下方关于MAPPING的说明。

#MAPPING

以下是对工具/模块及其在 $BLACKLIST、$METHOD_FAIL 和其他内部函数中的名称的简要映射。

LWP         => lwp
HTTP::Lite  => httplite
HTTP::Tiny  => httptiny
Net::FTP    => netftp
wget        => wget
lynx        => lynx
ncftp       => ncftp
ftp         => ftp
curl        => curl
rsync       => rsync
lftp        => lftp
fetch       => fetch
IO::Socket  => iosock

#常见问题解答

#如何使用代理与 File::Fetch 一起使用？

File::Fetch 目前仅支持使用 LWP::UserAgent 的代理。您需要相应地设置环境变量。例如，要使用 ftp 代理

$ENV{ftp_proxy} = 'foo.com';

有关更多详细信息，请参阅 LWP::UserAgent 手册页。

#我使用 'lynx' 获取文件，但其内容完全错误！

lynx 只能通过将其内容转储到 STDOUT 来获取远程文件，我们反过来捕获它。如果该内容是“自定义”错误文件（例如，404 处理程序），您将获得该内容。

遗憾的是，lynx 不支持任何选项在非200 OK 状态下返回不同的退出代码，这使我们无法区分“成功”获取和自定义错误页面。

因此，我们建议仅将lynx 作为最后的手段。这就是为什么它在我们尝试的方法列表的最后面。

#我尝试获取的文件包含保留字符或非 ASCII 字符。我该怎么办？

File::Fetch 相对智能。在尝试将文件写入磁盘时，它会在创建文件之前从文件名中删除查询参数（有关详细信息，请参阅output_file 方法）。在大多数情况下，这已经足够了。

如果您需要转义其他字符，请从 CPAN 安装 URI::Escape 模块，并在将 URI 传递给 File::Fetch 之前对其进行预编码。您可以在此处了解有关 URI 和 URI 编码的详细信息

https://datatracker.ietf.org/doc/html/rfc2396

#TODO

#实现 $PREFER_BIN

指示使用命令行工具而不是模块

#错误报告

请将错误或其他问题报告给 <[email protected]<gt>。

#作者

此模块由 Jos Boumans <[email protected]> 编写。

#版权

此库是免费软件；您可以在与 Perl 本身相同的条款下重新分发和/或修改它。

Perldoc 浏览器由 Dan Book (DBOOK) 维护。如果您遇到有关网站本身、搜索或文档渲染的任何问题，请通过 GitHub 问题跟踪器 或 电子邮件 与他联系。

Perl 文档由 Perl 5 移植者在 Perl 开发过程中维护。如果您遇到有关文档内容或格式的任何问题，请通过 Perl 问题跟踪器、邮件列表 或 IRC 与他们联系。