NAME
    File::Dropbox - Convenient and fast Dropbox API abstraction

SYNOPSIS
        use File::Dropbox;
        use Fcntl;

        # Application credentials
        my %app = (
            app_key       => 'app key',
            app_secret    => 'app secret',
            access_token  => 'access token',
            access_secret => 'access secret',
        );

        my $dropbox = File::Dropbox->new(%app);

        # Open file for writing
        open $dropbox, '>', 'example' or die $!;

        while (<>) {
            # Upload data using 4MB chunks
            print $dropbox $_;
        }

        # Commit upload (optional, close will be called on reopen)
        close $dropbox or die $!;

        # Open for reading
        open $dropbox, '<', 'example' or die $!;

        # Download and print to STDOUT
        # Buffered, default buffer size is 4MB
        print while <$dropbox>;

        # Reset file position
        seek $dropbox, 0, Fcntl::SEEK_SET;

        # Get first character (unbuffered)
        say getc $dropbox;

        close $dropbox;

DESCRIPTION
    `File::Dropbox' provides high-level Dropbox API abstraction based on
    Tie::Handle. Code required to get `access_token' and `access_secret' for
    signed OAuth 1.0 requests is not included in this module. To get
    `app_key' and `app_secret' you need to register your application with
    Dropbox.

    At this moment Dropbox API is not fully supported, `File::Dropbox'
    covers file read/write and directory listing methods. If you need full
    API support take look at WebService::Dropbox. `File::Dropbox' main
    purpose is not 100% API coverage, but simple and high-performance file
    operations.

    Due to API limitations and design you can not do read and write
    operations on one file at the same time. Therefore handle can be in
    read-only or write-only state, depending on last call to open. Supported
    functions for read-only state are: open, close, seek, tell, readline,
    read, sysread, getc, eof. For write-only state: open, close, syswrite,
    print, printf, say.

    All API requests are done using Furl module. For more accurate timeouts
    Net::DNS::Lite is used, as described in Furl::HTTP. Furl settings can be
    overriden using `furlopts'.

METHODS
  new
        my $dropbox = File::Dropbox->new(
            access_secret => 'secret',
            access_token  => 'token',
            app_secret    => 'app secret',
            app_key       => 'app key',
            chunk         => 8 * 1024 * 1024,
            root          => 'dropbox',
            furlopts      => {
                timeout => 20
            }
        );

    Constructor, takes key-value pairs list

    access_secret
        OAuth 1.0 access secret

    access_token
        OAuth 1.0 access token

    app_secret
        OAuth 1.0 app secret

    app_key
        OAuth 1.0 app key

    chunk
        Upload chunk size in bytes. Also buffer size for `readline'.
        Optional. Defaults to 4MB.

    root
        Access type, `sandbox' for app-folder only access and `dropbox' for
        full access.

    furlopts
        Parameter hash, passed to Furl constructor directly. Default options

            timeout   => 10,
            inet_aton => \&Net::DNS::Lite::inet_aton,
            ssl_opts  => {
                SSL_verify_mode => SSL_VERIFY_PEER(),
            }

FUNCTIONS
    All functions are not exported by default but can be exported on demand.

        use File::Dropbox qw{ contents metadata putfile };

    First argument for all functions should be GLOB reference, returned by
    new.

  contents
    Arguments: $dropbox [, $path]

    Function returns list of hashrefs representing directory content. Hash
    fields described in Dropbox API docs. `$path' defaults to `/'. If there
    is unfinished chunked upload on handle, it will be commited.

        foreach my $file (contents($dropbox, '/data')) {
            next if $file->{'is_dir'};
            say $file->{'path'}, ' - ', $file->{'bytes'};
        }

  metadata
    Arguments: $dropbox

    Function returns stored metadata for read-only handle, closed write
    handle or after call to contents or putfile.

        open $dropbox, '<', '/data/2013.dat' or die $!;

        my $meta = metadata($dropbox);

        if ($meta->{'bytes'} > 1024) {
            # Do something
        }

  putfile
    Arguments: $dropbox, $path, $data

    Function is useful for uploading small files (up to 150MB possible) in
    one request (at least two API requests required for chunked upload, used
    in open-write-close sequence). If there is unfinished chunked upload on
    handle, it will be commited.

        local $/;
        open my $data, '<', '2012.dat' or die $!;

        putfile($dropbox, '/data/2012.dat', <$data>) or die $!;

        say 'Uploaded ', metadata($dropbox)->{'bytes'}, ' bytes';

        close $data;

SEE ALSO
    Furl, Furl::HTTP, WebService::Dropbox, Dropbox API

AUTHOR
    Alexander Nazarov <nfokz@cpan.org>

COPYRIGHT AND LICENSE
    Copyright 2013 Alexander Nazarov

    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.