README

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

SYNOPSIS
        use File::Dropbox;
        use Fcntl;

        # Application credentials
        my %app = (
            oauth2        => 1,
            access_token  => $access_token,
        );

        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 or "access_token" for OAuth 2.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
    overridden using "furlopts".

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

        my $dropbox = File::Dropbox->new(
            access_token => $access_token,
            oauth2       => 1
        );

    Constructor, takes key-value pairs list

    access_secret
        OAuth 1.0 access secret

    access_token
        OAuth 1.0 access token or OAuth 2.0 access token

    app_secret
        OAuth 1.0 app secret

    app_key
        OAuth 1.0 app key

    oauth2
        OAuth 2.0 switch, defaults to false.

    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
    <https://www.dropbox.com/developers/core/docs#metadata>. $path defaults
    to "/". If there is unfinished chunked upload on handle, it will be
    committed.

        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 committed.

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

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

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

        close $data;

  copyfile
    Arguments: $dropbox, $source, $target

    Function copies file or directory from one location to another. Metadata
    for copy can be accessed using "metadata" function.

        copyfile($dropbox, '/data/2012.dat', '/data/2012.dat.bak') or die $!;

        say 'Created backup with revision ', metadata($dropbox)->{'revision'};

  movefile
    Arguments: $dropbox, $source, $target

    Function moves file or directory from one location to another. Metadata
    for moved file can be accessed using "metadata" function.

        movefile($dropbox, '/data/2012.dat', '/data/2012.dat.bak') or die $!;

        say 'Created backup with size ', metadata($dropbox)->{'size'};

  deletefile
    Arguments: $dropbox, $path

    Function deletes file or folder at specified path. Metadata for deleted
    item is accessible via "metadata" function.

        deletefile($dropbox, '/data/2012.dat.bak') or die $!;

        say 'Deleted backup with last modification ', metadata($dropbox)->{'modification'};

  createfolder
    Arguments: $dropbox, $path

    Function creates folder at specified path. Metadata for created folder
    is accessible via "metadata" function.

        createfolder($dropbox, '/data/backups') or die $!;

        say 'Created folder at path ', metadata($dropbox)->{'path'};

SEE ALSO
    Furl, Furl::HTTP, WebService::Dropbox, Dropbox API
    <https://www.dropbox.com/developers/core/docs>

AUTHOR
    Alexander Nazarov <nfokz@cpan.org>

COPYRIGHT AND LICENSE
    Copyright 2013-2016 Alexander Nazarov

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