NAME
"Net::Async::FTP" - Use FTP with "IO::Async"
SYNOPSIS
use IO::Async::Loop;
use Net::Async::FTP;
my $loop = IO::Async::Loop->new();
my $ftp = Net::Async::FTP->new();
$loop->add( $ftp );
$ftp->connect(
host => "ftp ftp.example.com",
on_connected => sub {
$ftp->login(
user => "username",
pass => "password",
on_login => sub {
$ftp->retr(
path => "README.txt",
on_data => sub {
my ( $data ) = @;
print "README.txt says:\n";
print $data;
$loop->loopstop;
},
);
},
on_error => sub { die shift() },
);
},
on_error => sub { die shift() },
);
$loop->loop_forever;
DESCRIPTION
This object class implements an asynchronous FTP client, for use in IO::Async-based programs.
The code in this module is not particularly complete. It contains a minimal implementation of a few FTP commands, not even the full minimal set the RFC suggests all clients should support. I am releasing it anyway, because it is still useful as it stands, and could easily support extra commands being added if anyone would find it useful.
The (undocumented) "do_command()" method provides a generic base for the currently-implemented commands, and would be the basis for new commands.
As they say so often in the open-source world; Patches Welcome.
CONSTRUCTOR
$ftp = Net::Async::FTP->new( %args )
This function returns a new instance of a "Net::Async::FTP" object. As
it is a subclass of "IO::Async::Stream" its constructor takes any
arguments for that class.
METHODS
$ftp->connect( %args )
Connects to the FTP server. Takes the following arguments:
host => STRING
Hostname of the server
service => STRING or INT
Optional. Service name or port number to connect to. If not
supplied, will use "ftp".
family => INT
Optional. Socket family to use. Will default to whatever
"getaddrinfo()" returns if not supplied.
on_connected => CODE
Continuation to call when connection is successful
$on_connected->()
on_error => CODE
Continuation to call on an error
$on_error->( $message )
$ftp->login( %args )
Sends a "USER" and optionally "PASS" command. Takes the following
user => STRING
Username for the "USER" command
pass => STRING
Password for the "PASS" command if required
on_login => CODE
Continuation to invoke on successful login.
$on_login->()
on_error => CODE
Continuation to invoke on an error.
$on_error->( $message )
$ftp->rename( %args )
Renames a file on the remote server. Takes the following arguments
oldpath => STRING
Path to file to rename
newpath => STRING
Desired new path for the file
on_done => CODE
Continuation to invoke on success.
$on_done->()
on_error => CODE
Continuation to invoke on an error.
$on_error->( $message )
$ftp->dele( %args )
Deletes a file on the remote server. Takes the following arguments
path => STRING
Path to file to delete
on_done => CODE
Continuation to invoke on success.
$on_done->()
on_error => CODE
Continuation to invoke on an error.
$on_error->( $message )
$ftp->list( %args )
Runs a "LIST" command on a path on the remote server; which requests
details on the file, or contents of the directory. Takes the following
arguments
path => STRING
Path to "LIST"
on_list => CODE
Continuation to invoke on success. Is passed a list of lines
from the "LIST" result in a single string.
$on_list->( $list )
on_error => CODE
Continuation to invoke on an error.
$on_error->( $message )
The "list_parsed" method may be easier to use as it parses the lines.
$ftp->list_parsed( %args )
Runs a "LIST" command on a path on the remote server; and parse the
result lines. Takes the following arguments
path => STRING
Path to "LIST"
on_list => CODE
Continuation to invoke on success. Is passed a list of files
from the "LIST" result, one line per element.
$on_list->( @list )
on_error => CODE
Continuation to invoke on an error.
$on_error->( $message )
The @list array will be passed a list of "HASH" references, each formed like
name => STRING
The filename
type => STRING
A single character; "f" for files, "d" for directories
size => INT
The size in bytes
mtime => INT
The item's last modify timestamp, as a UNIX epoch time
mode => INT
The access mode, as a number
$ftp->nlist( %args )
Runs a "NLST" command on a path on the remote server; which requests a
list of filenames in a directory. Takes the following arguments
path => STRING
Path to "NLST"
on_list => CODE
Continuation to invoke on success. Is passed a list of names
from the "NLST" result in a single string.
$on_list->( $list )
on_error => CODE
Continuation to invoke on an error.
$on_error->( $message )
The "namelist" method may be easier to use as it splits the lines.
$ftp->namelist( %args )
Runs a "NLST" command on a path on the remote server; which requests a
list of filenames in a directory. Takes the following arguments
path => STRING
Path to "NLST"
on_names => CODE
Continuation to invoke on success. Is passed a list of names
from the "NLST" result in a list, one name per entry
$on_name->( @names )
on_error => CODE
Continuation to invoke on an error.
$on_error->( $message )
$ftp->retr( %args )
Retrieves a file on the remote server. Takes the following arguments
path => STRING
Path to file to retrieve
on_data => CODE
Continuation to invoke on success. Is passed the contents of the
file as a single string.
$on_data->( $content )
on_error => CODE
Continuation to invoke on an error.
$on_error->( $message )
$ftp->stat( %args )
Runs a "STAT" command on a path on the remote server; which requests
details on the file, or contents of the directory. Takes the following
arguments
path => STRING
Path to "STAT"
on_stat => CODE
Continuation to invoke on success. Is passed a list of lines
from the "STAT" result, one line per element.
$on_stat->( @stat )
on_error => CODE
Continuation to invoke on an error.
$on_error->( $message )
The "stat_parsed" method may be easier to use as it parses the lines.
$ftp->stat_parsed( %args )
Runs a "STAT" command on a path on the remote server; and parse the
result lines. Takes the following arguments
path => STRING
Path to "STAT"
on_stat => CODE
Continuation to invoke on success. Is passed a list of lines
from the "STAT" result, one line per element.
$on_stat->( @stat )
on_error => CODE
Continuation to invoke on an error.
$on_error->( $message )
The @stat array will be passed a list of "HASH" references, each formed like
name => STRING
The filename
type => STRING
A single character; "f" for files, "d" for directories
size => INT
The size in bytes
mtime => INT
The item's last modify timestamp, as a UNIX epoch time
mode => INT
The access mode, as a number
If "STAT" is invoked on a file, then @stat will contain a single reference to represent it. If invoked on a directory, the @stat will start with a reference about the directory itself (whose name will be "."), then one per item in the directory, in the order the server returned the lines.
$ftp->stor( %args )
Stores a file on the remote server. Takes the following arguments
path => STRING
Path to file to store
data => STRING
New contents for the file
on_stored => CODE
Continuation to invoke on success.
$on_stored->()
on_error => CODE
Continuation to invoke on an error.
$on_error->( $message )
SEE ALSO
AUTHOR
Paul Evans <leonerd@leonerd.org.uk>