Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/n4kz/file-dropbox

Convenient and fast Dropbox API abstraction
https://github.com/n4kz/file-dropbox

Last synced: 2 days ago
JSON representation

Convenient and fast Dropbox API abstraction

Awesome Lists containing this project

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

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

    



AUTHOR

    Alexander Nazarov 



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.