File::Dropbox(3pm)

🌸 NAME 🌸

File::Dropbox — the convenient + fast Dropbox API abstraction, bestie. It's giving "just let me read and write files already" energy and honestly? iconic.

---

✨ 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 hands you a high-level Dropbox API abstraction built on top of Tie::Handle. The code you need to actually get access_token and access_secret for signed OAuth 1.0 requests, or access_token for OAuth 2.0 requests — yeah, that is not included in this module, sorry bestie. And to get app_key and app_secret you gotta register your application with Dropbox first. No skipping that step. 🎀

Right now the Dropbox API is not fully supported — File::Dropbox covers file read/write and directory listing methods. If you're out here needing full API support, go take a look at WebService::Dropbox. File::Dropbox's whole main character purpose is not 100% API coverage, it's simple and high-performance file operations. periodt.

Due to API limitations and design you literally can not do read and write operations on one file at the same time. So a handle lives in either read-only or write-only state, depending on the 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, and for more accurate timeouts Net::DNS::Lite is used, as described in Furl::HTTP. Furl settings can be overridden using furlopts. slay.

---

🔥 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 — it takes a key-value pairs list. Obsessed with a clean constructor ngl.

• 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 the 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 the 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 they can be exported on demand:

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

The first argument for all functions should be a GLOB reference, returned by new. iykyk.

🍓 contents

Arguments: $dropbox [, $path]

This function returns a list of hashrefs representing directory content. Hash fields are described in the Dropbox API docs at https://www.dropbox.com/developers/core/docs#metadata. $path defaults to "/". If there's an unfinished chunked upload sitting on the handle, it will be committed.

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

🧚 metadata

Arguments: $dropbox

This function returns stored metadata for a read-only handle, a closed write handle, or after a 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

This function is useful for uploading small files (up to 150MB possible) in one request — chunked upload needs at least two API requests, which is what's used in the open-write-close sequence. If there's an unfinished chunked upload on the 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

This function copies a file or directory from one location to another. Metadata for the copy can be accessed using the 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

This function moves a file or directory from one location to another. Metadata for the moved file can be accessed using the 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

This function deletes a file or folder at the specified path. Metadata for the deleted item is accessible via the metadata function.

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

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

🎀 createfolder

Arguments: $dropbox, $path

This function creates a folder at the specified path. Metadata for the created folder is accessible via the 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 at 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.

---

okay bestie that's the whole page, mwah 🫶 This lil masterpiece ships as perl v5.34.0, dated 2022-06-13, and it's filed under File::Dropbox(3pm) — go read some files, you got this 💅✨