NAME "Net::Async::FTP" - Asynchronous FTP client 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.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->loop_stop; }, ); }, 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 arguments: 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 * - FILE TRANSFER PROTOCOL (FTP) AUTHOR Paul Evans