Paul Evans > Net-Async-FTP-0.07 > Net::Async::FTP

Download:
Net-Async-FTP-0.07.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  1
Open  1
View/Report Bugs
Module Version: 0.07   Source   Latest Release: Net-Async-FTP-0.08

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 ^

AUTHOR ^

Paul Evans <leonerd@leonerd.org.uk>

syntax highlighting: