內容

• 名稱
• 語法
• 說明
• 存取器
• 方法
  • $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 指出的任何檔案。

請參閱下方 HOW IT WORKS 區段以取得詳細資訊。

#ACCESSORS

一個 File::Fetch 物件具有下列存取器

#$ff->uri

傳遞給建構函式的 uri

#$ff->scheme

來自 uri 的 scheme（例如 'file', 'http' 等）

#$ff->host

uri 中的主機名稱。如果主機名稱原本是 'file://' URL 的 'localhost'，則會為空。

#$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。

#方法

#$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])

回傳最後遇到的錯誤訊息。傳遞 true 值給它，以取得 Carp::longmess() 輸出。

#運作原理

File::Fetch 能夠取得各種 uri，方法是使用幾個外部程式和模組。

以下是可用時，會按什麼順序使用哪些工具程式來處理哪些 scheme 的對應表

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 scheme 的 url。例如，它不會追蹤重新導向。

git 只支援 git:// 樣式的 url。

特別注意從 ftp uri 取得檔案

預設情況下，所有 ftp 連線都是以被動模式進行。如要變更，請參閱下方的 $FTP_PASSIVE 變數。

此外，ftp uri 只支援匿名連線，因此無法傳遞命名使用者/密碼配對。

/bin/ftp 預設會加入黑名單；請參閱下方的 $BLACKLIST 變數。

#全域變數

變更下列全域變數可以改變 File::Fetch 的行為

#$File::Fetch::FROM_EMAIL

這是會作為您的匿名 FTP 密碼傳送的電子郵件地址。

預設為 File-Fetch@example.com。

#$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

此變數控制 File::Fetch 內部遇到的錯誤是否應 carp。

設為 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 的註解。

#對應

以下是公用程式/模組的快速對應，以及它們在 $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 模組，並在將其傳遞給 File::Fetch 之前預先編碼您的 URI。您可以在此處閱讀有關 URI 和 URI 編碼的詳細資料

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

#待辦事項

#實作 $PREFER_BIN

用於指示要使用命令列工具而非模組

#錯誤回報

請將錯誤或其他問題回報至 <bug-file-fetch@rt.cpan.org<gt>。

#作者

此模組由 Jos Boumans <kane@cpan.org> 製作。

#版權

此函式庫是免費軟體；您可以在與 Perl 相同的條款下重新散布和/或修改它。

Perldoc 瀏覽器由 Dan Book (DBOOK) 維護。請透過 GitHub 問題追蹤器 或 電子郵件 聯絡他，反映網站本身、搜尋或文件呈現的任何問題。

Perl 文件由 Perl 5 Porters 在 Perl 的開發中維護。請透過 Perl 問題追蹤器、郵件清單 或 IRC 聯絡他們，反映文件內容或格式的任何問題。