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 )

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 )

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>

To install Net::Async::FTP, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Net::Async::FTP

CPAN shell

perl -MCPAN -e shell
install Net::Async::FTP

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

CONSTRUCTOR

$ftp = Net::Async::FTP->new( %args )

METHODS

$ftp->connect( %args ) ==> ()

$ftp->login( %args ) ==> ()

$ftp->rename( %args ) ==> ()

$ftp->dele( %args ) ==> ()

$ftp->list( %args ) ==> $list

$ftp->list_parsed( %args ) ==> @list

$ftp->nlist( %args ) ==> $list

$ftp->namelist( %args ) ==> @names

$ftp->retr( %args ) ==> $content

$ftp->stat( %args ) ==> @stat

$ftp->stat_parsed( %args ) ==> @stat

$ftp->stor( %args ) ==> ()

SEE ALSO

AUTHOR

Module Install Instructions