FTP(ファイル転送プロトコル)はホスト間でファイルを転送するのに使用されるプロトコルです。
ftpネームスペースは簡単なインタフェースを通してFTPのサポートを提供します。

高レベルの関数はほとんど共通の操作をサポートするように提供されます。
これら高レベルの関数は低レベルインターフェースを使用して実装されています。
低レベルインターフェースを使用することで、ユーザはFTPプロトコルがサポートするあらゆる操作にアクセスするような関数を簡単に作成することができます。
実装をチェックしてください。


このモジュールを本当に役立てるには、LTN012のフィルターソース・シンクを理解することが必要になります。

ftpネームスペースを取得するには、次のように行います。

-- FTPモジュールを読み込む
local ftp = require("socket.ftp")

URLはRFC1738の形式に従う必要があります。
それは次のような文字列になります。

[ftp://][<user>[:<password>]@]<host>[:<port>][/<path>][type=a|i]

ネームスペースの中の以下のような定数を設定することで、FTPモジュールのデフォルトの動作を指定することができます。

• PASSWORD : デフォルトのanonymousパスワード
• PORT : 接続に使用されるデフォルトのポート番号
• TIMEOUT : すべてのI/O操作のタイムアウトを
• USER : デフォルトのanonymousユーザ

ftp.get(url)
ftp.get{
  host = string,
  sink = LTN12 sink,
  argument or path = string,
  [user = string,]
  [password = string]
  [command = string,]
  [port = number,]
  [type = string,]
  [step = LTN12 pump step,]
  [create = function]
}

get関数は2つの形式があります。
簡単な形式はURLからダウンロードして、文字列として返します。
一般的な形式は以下で説明するようにより多くの操作ができるようになっています。

get関数の引数がテーブルの場合、最低でもhost,sink,argumentもしくはpath(argumentが優先される)要素が存在する必要があります。
hostは接続するサーバです。sinkはただのLTN12シンクでダウンロードしたデータを受け取ります。
argumentもしくはpathは対象のサーバ上のリソースのパスです。
オプションの引数として以下のようなものがあります。

• user,password : 認証用のユーザ名とパスワードです。デフォルトは"ftp:anonymous@anonymous.org"です。
• command : データを取得するのに使用するFTPコマンドです。デフォルトは"retr"です。以下の例を参照してください。
• port : 接続に使用する、制御用ポート番号です。デフォルトは21です。
• type : 転送モードです。"i"もしくは"a"を指定します。デフォルトはサーバ側の設定に従います。
• step : サーバからシンクにデータを渡すのに使用される、LTN12のpump.step関数です。デフォルトはLTN12のpump.step関数です。
• create : 通信用ソケットが生成されたときにsocket.tcpの代わりに使用されるオプションの関数です。

成功した場合、簡単な形式ではURLからダウンロードした内容を文字列として返します。一般的な形式では、1を返します。
エラーの場合、両方の形式でnilを返し、続けてエラーメッセージを返します。

-- FTPモジュールを読み込む
local ftp = require("socket.ftp")

-- サーバ "ftp.tecgraf.puc-rio.br" に "anonymous" ユーザでログインします。
-- そして "pub/lua" から "lua.tar.gz" をバイナリファイルとして取得します。
f, e = ftp.get("ftp://ftp.tecgraf.puc-rio.br/pub/lua/lua.tar.gz;type=i")

-- 必要なモジュールを読み込む
local ftp = require("socket.ftp")
local ltn12 = require("ltn12")
local url = require("socket.url")

-- ディレクトリ内の一覧を返す関数
function nlst(u)
    local t = {}
    local p = url.parse(u)
    p.command = "nlst"
    p.sink = ltn12.sink.table(t)
    local r, e = ftp.get(p)
    return r and table.concat(t), e
end

ftp.put(url, content)
ftp.put{
  host = string,
  source = LTN12 sink,
  argument or path = string,
  [user = string,]
  [password = string]
  [command = string,]
  [port = number,]
  [type = string,]
  [step = LTN12 pump step,]
  [create = function]
}

put関数には2つの形式があります。
簡単な形式では指定したURLに文字列をアップロードします。
一般的な形式では以下で説明するようにより多くの制御ができるようになっています。

put関数の引数がテーブルの場合、最低でもhost,source,argumentもしくはpath(argumentが優先されます)要素が必要になります。
hostは接続するサーバです。sourceはただのLTN12ソースでアップロードする内容を提供します。
argumentもしくはサーバのリソースの位置になります。
オプションの引数としては以下のようなものがあります。

• user,password : 認証用のユーザ名とパスワードです。デフォルトは"ftp:anonymous@anonymous.org"です。
• command : データを送信するのに使用するFTPコマンドです。デフォルトは"stor"です。以下の例を参照してください。
• port : 接続に使用する、制御用ポート番号です。デフォルトは21です。
• type : 転送モードです。"i"もしくは"a"を指定します。デフォルトはサーバ側の設定に従います。
• step : サーバからシンクにデータを渡すのに使用される、LTN12のpump.step関数です。デフォルトはLTN12のpump.step関数です。
• create : 通信用ソケットが生成されたときにsocket.tcpの代わりに使用されるオプションの関数です。

両関数共に成功した場合1を返し、エラーの場合nilとエラーメッセージを返します。

-- FTPモジュールを読み込む
local ftp = require("socket.ftp")

-- サーバ "ftp.example.com" にユーザ "fulano" 、パスワード "silva" でログイン
-- 文字列を "README" ファイルとして保存
-- "wrong password, of course"
f, e = ftp.put("ftp://fulano:silva@ftp.example.com/README", 
    "wrong password, of course")

-- 必要なモジュールをロード
local ftp = require("socket.ftp")
local ltn12 = require("ltn12")

-- サーバ "ftp.example.com" にユーザ "fulano" 、パスワード "silva" でログイン
-- ローカルファイル "LOCAL-LOG" を送信して、リモートファイル "LOG" に追記する
f, e = ftp.put{
  host = "ftp.example.com", 
  user = "fulano",
  password = "silva",
  command = "appe",
  argument = "LOG",
  source = ltn12.source.file(io.open("LOCAL-LOG", "r"))
}