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.example.com", )->then( sub { $ftp->login( user => "username", pass => "password", ) })->then( sub { $ftp->retr( path => "README.txt", ) })->then( sub { my ( $data ) = @_; print "README.txt says:\n"; print $data; })->get; 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 Optional when returning a Future. Continuation to call when connection is successful. $on_connected->() on_error => CODE Optional when returning a Future. 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 Optional when returning a future. Continuation to invoke on successful login. $on_login->() on_error => CODE Optional when returning a future. 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 Optional when returning a future. Continuation to invoke on success. $on_done->() on_error => CODE Optional. 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 Optional when returning a future. Continuation to invoke on success. $on_done->() on_error => CODE Optional. Continuation to invoke on an error. $on_error->( $message ) $ftp->list( %args ) ==> $list 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 Optional when returning a future. 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 Optional. 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 ) ==> @list 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 Optional when returning a future. 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 Optional. 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 ) ==> $list 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 Optional when returning a future. 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 Optional. 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 ) ==> @names 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 Optional when returning a future. 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 Optional. Continuation to invoke on an error. $on_error->( $message ) $ftp->retr( %args ) ==> $content Retrieves a file on the remote server. Takes the following arguments path => STRING Path to file to retrieve on_data => CODE Optional when returning a future. Continuation to invoke on success. Is passed the contents of the file as a single string. $on_data->( $content ) on_error => CODE Optional. Continuation to invoke on an error. $on_error->( $message ) $ftp->stat( %args ) ==> @stat 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 Optional when not returning a future. 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 Optional. 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 ) ==> @stat 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 Optional when returning a future. 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 Optional. 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 Optional when returning a future. Continuation to invoke on success. $on_stored->() on_error => CODE Optional. Continuation to invoke on an error. $on_error->( $message ) SEE ALSO * http://tools.ieft.org/html/rfc959 - FILE TRANSFER PROTOCOL (FTP) AUTHOR Paul Evans