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.