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",

        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
    *   http://tools.ieft.org/html/rfc959 - FILE TRANSFER PROTOCOL (FTP)

AUTHOR
    Paul Evans <leonerd@leonerd.org.uk>