| WWW::Yahoo::Briefcase - interface to Yahoo Briefcase services |
WWW::Yahoo::Briefcase - interface to Yahoo Briefcase services
require WWW::Yahoo::Briefcase;
my $cookies =
WWW::Yahoo::Credentials::File->new( subdir => '.yahoo',
filename => 'cookies.txt' );
my $ybc = WWW::Yahoo::Briefcase->new( cookie_jar => $cookies,
overwrite => 1 );
$ybc->signin( $id, $pw );
$ybc->create( '/', 'My Backups' ); # create 'My Backups' folder in '/'
$ybc->upload( 'My Backups', '/var/backups/dump.bz2' );
$ybc->upload( 'My Photos', 'picture.jpg' );
$ybc->rename( 'My Backups', 'dump.bz2' => 'backup.bz2' );
$ybc->move( 'My Photos' => 'My Backups', 'picture.jpg' );
$ybc->copy( 'My Photos' => 'My Backups', 'picture.jpg' );
$ybc->delete( 'My Photos', 'picture.jpg' );
$ybc->delete( '/', 'My Photos' ); # delete all photos
my @backups = $ybc->list( 'My Backups' );
This module provides access to your Yahoo Briefcase. You can upload and download files and perform other operations such as list, rename, move, copy, delete, and create new folders.
Errors may be caught using ``eval'', for example,
See WWW::Yahoo::Briefcase::Exceptions for a list of exceptions (they are thrown using the Exception::Class module).
eval { $ybc->upload( $folder, @objects ) };
if ( $@ ) {
if ( $@->isa( 'WWW::Yahoo::Briefcase::Exception::List' ) ) {
my @errors = map { ucfirst( $_->description ) . $_ } $@->errors;
die join( "\n", @errors ) . "\n";
}
else {
die ucfirst( $@->description ) . ": $@";
}
}
my $ybc = new WWW::Yahoo::Briefcase;
my $ybc = WWW::Yahoo::Briefcase->new( cookie_jar => $cookies,
overwrite => 1, sleep => 3,
debug => 0, maxsize => 10_485_760 );
Creates a new object. Options may be specified when the object is created. The following options have default values:
cookie_jar: {}
overwrite: undef
sleep: 3 seconds
debug: off
maxsize: 5,242,880 bytes
The cookie jar can be an already-initialized HTTP::Cookies object, for example: my $cookies = HTTP::Cookies->new( file => $cookie_file, autosave => 1 ); Alternatively, the cookie file can be specified in which case a new HTTP::Cookies object will be initialized from that file, for example: my $ybc = WWW::Yahoo::Briefcase->new( cookie_jar => $cookie_file ); If the file does not exist, it will be created with the umask set to 077 to protect it (the umask will be reset to its original value after the cookie file is created). If no cookie jar is specified, then an in-memory cookie jar will be used ({}).
Any other options specified are passed to the superclasses, WWW::Mechanize and LWP::UserAgent, see their documentation for more information.
my $old = $ybc->overwrite( undef ); # do not overwrite my $old = $ybc->overwrite( '' ); # do not overwrite my $old = $ybc->overwrite( 0 ); # do not overwrite my $old = $ybc->overwrite( 1 ); # overwrite (pre-delete) my $old = $ybc->overwrite( 'NEW' ); # overwrite with prefix (post-delete) my $overwrite = $ybc->overwrite;
If given a parameter, it sets the overwrite flag. With no parameter specified the current setting of the prefix is returned. If the overwrite prefix is true, then existing objects will be overwritten on upload, download, create, rename, move, or copy.
If the overwrite flag is set to 1, then existing objects with the same name will be deleted before the operation is preformed. For example, if the file 'backup.tar.bz2' is being uploaded and there already existed such a file in the destination folder, then that file would be deleted before 'backup.tar.bz2' is uploaded.
One caveat with this approach is that if the upload fails, then you've
lost the previous backup. So, to avoid this problem, you can set the
overwrite flag to any true value other than 1 and it will be used as a
prefix for the filename. If set to 'NEW', for example, then the file
in the above example would be uploaded as 'NEW-backup.tar.bz2', and
only if the upload succeeded would the original file 'backup.tar.bz2'
be deleted and 'NEW-backup.tar.bz2 renamed to 'backup.tar.bz2'. One
caveat with this approach is that it takes up twice the space while
the new file(s) are being uploaded (all files are uploaded before any
files are deleted).
If you would like to specify a prefix of 0 or 1 for post-delete, then specify the full prefix including the dash as '0-' or '1-'.
my $old = $ybc->sleep( 3 ); my $sleep = $ybc->sleep;
If given a parameter, it sets the numbers of seconds to sleep.
Otherwise, it returns the number. If sleep is set, then
get, click, and submit (and anything else that calls LWP's
request method which we've overridden) will sleep for the
specified period before each fetch. I ran into problems when setting
sleep to zero--only about half of the files were uploaded
successfully.
my $old = $ybc->debug( 0 ); # turn off debugging my $old = $ybc->debug( 1 ); # show informational messages my $old = $ybc->debug( 2 ); # also show requests and responses my $debug = $ybc->debug;
Sets debugging level. When enabled, information is printed to STDERR.
my $old = $ybc->maxsize( 10_485_760 ); my $maxsize = $ybc->maxsize;
If given a parameter, it sets the maximum size of a file upload. Otherwise, it returns the size. Note that this setting is not a user preference but is instead a limitation imposed on uploads to your briefcase. That is, you have no control over it. This method exists solely so that you can inform this class what your limit is, so that the class will not attempt to upload files larger than the limit.
The standard file size limit is 5MB, but with Premium Service it is 10MB.
my @commands = $WWW::Yahoo::Briefcase->do; $ybc->do( $command, @arguments ); $ybc->do( 'signin', $id, $pw ); $ybc->do( 'signout' ); $ybc->do( 'upload', $folder, @files ); $ybc->do( 'download', $folder, @files ); $ybc->do( 'create', $folder, @subfolders ); $ybc->do( 'rename', $folder, $object => $newname ); $ybc->do( 'delete', $folder, @objects ); $ybc->do( 'move', $folder => $destination, @objects ); $ybc->do( 'copy', $folder => $destination, @objects ); my @objects = $ybc->do( 'list', $folder );
Return list of supported commands or perform specified command.
$ybc->signin( $id, $pw );
Sign in if not already signed in. Gets/updates cookie and grabs a few links that will be needed.
$ybc->signout;
Sign out. If you are using a cookie file, then do not call this function unless you want to invalidate your cookies. The cookie file allows you to access your briefcase more quickly because the login form is bypassed (assuming your cookie has not timed out).
$ybc->upload( $folder, @files ); $ybc->upload( $folder, $file ); $ybc->upload( $folder, [ $file1 => $newfilename1 ], $file2, ... );
$ybc->upload( 'My Backups', '/var/backups/dump.bz2' ); $ybc->upload( 'My Backups', [ '/var/backups/dump.bz2' => '20030415.bz2' ] );
Upload file(s) to specified folder. The full path name of the
existing folder on the remote system must be specified, and the full
path name of each existing file you wish to upload from your local
system must be specified (or the relative path name of an existing
file if it is reachable from the current directory). You can give
each file a new name, but be sure to include the extension.
Note that if an existing object of the same name is found in the destination folder, it will automatically be renamed (for example, 'pic.jpg' might become 'pic---1.jpg'), unless you have enabled the overwrite flag, in which case the object will be overwritten. Note well that if the pre-existing object to be overwritten is a folder then all its contents are deleted!
$ybc->download( $folder, @files ); $ybc->download( $folder, $file ); $ybc->download( $folder, [ $file => $localdir ] ); $ybc->download( $folder, [ $file => $localfile ], $file2, ... );
$ybc->download( 'My Backups', 'dump.bz2' ); $ybc->download( 'My Backups', [ 'dump.bz2' => '/var/backups' ] ); $ybc->download( 'My Backups', [ '20030415.bz2' => '/var/backups/dump.bz2' ] );
Download specified file(s) from specified folder. The full path name
of the existing folder on the remote system must be specified.
Optionally you can specify the name (and/or location) for the local
file.
Note that if the local file exists, the download will fail, unless you have enabled the overwrite flag, in which case the file will be overwritten. If a local directory exists with the same name as the file being downloaded, then the download will fail even if the overwrite flag is set.
$ybc->create( $folder, @newsubfolders ); $ybc->create( $folder, $newsubfolder );
$ybc->create( '/', 'Backups' ); $ybc->create( 'My Photos', 'Vacation', 'Party' );
Create new subfolder(s) in an existing folder. The full path of the
existing folder must be specified.
Note that if an existing object of the same name is found in the folder, an error will be raised, unless you have enabled the overwrite flag, in which case the object will be overwritten. Note well that if the pre-existing object to be overwritten is a folder then all its contents are deleted!
$ybc->rename( $folder, $object => $newname );
$ybc->rename( 'My Photos', 'pic.jpg' => 'picture' );
Renames an existing object. The full path of the folder containing the object must be specified. Do not include the extension on the new name.
If an object with the new name already exists, an error will occur, unless you have enabled the overwrite flag, in which case the object will be overwritten. Note well that if the pre-existing object to be overwritten is a folder then all its contents are deleted!
$ybc->delete( $folder, @objects ); $ybc->delete( $folder, $objects ); # $objects is an array ref $ybc->delete( $folder, $object );
$ybc->delete( 'My Photos', 'pic.jpg' ); $ybc->delete( '/', 'backups' );
Delete the specified objects from the specified folder. The full path of the containing folder must be specified. Note that for folder objects, this method will recursively delete all subfolders and files contained within it.
$ybc->move( $folder => $destination, @objects ); $ybc->move( $folder => $destination, $objects ); # $objects is an array ref $ybc->move( $folder => $destination, $object );
$ybc->move( 'My Photos' => 'Old Photos', 'pic.jpg' );
Move objects to another folder. The full path of the original folder and the destination folder must be specified in $folder and $destination, respectively.
Note that if an existing object of the same name is found in the destination folder, it will automatically be renamed (for example, 'pic.jpg' might become 'pic---1.jpg'), unless you have enabled the overwrite flag, in which case the object will be overwritten. Note well that if the pre-existing object to be overwritten is a folder then all its contents are deleted! Unlike upload and create, it is not possible to use an overwrite-prefix, instead, the pre-existing object is deleted before the move.
$ybc->copy( $folder => $destination, @objects ); $ybc->copy( $folder => $destination, $objects ); # $objects is an array ref $ybc->copy( $folder => $destination, $object );
$ybc->copy( 'My Photos' => 'Old Photos', 'pic.jpg' );
Copy objects to another folder. The full path of the original folder and the destination folder must be specified in $folder and $destination, respectively.
Note that if an existing object of the same name is found in the destination folder, it will automatically be renamed (for example, 'pic.jpg' might become 'pic---1.jpg'), unless you have enabled the overwrite flag, in which case the object will be overwritten. Note well that if the pre-existing object to be overwritten is a folder then all its contents are deleted! Unlike upload and create, it is not possible to use an overwrite-prefix, instead, the pre-existing object is deleted before the copy.
my @contents = $ybc->list( $folder ); my @contents = $ybc->list; my @contents = $ybc->list( '' );
my @photos = $ybc->list( 'My Photos' ); my @vacation_photos = $ybc->list( 'My Photos/Vacation' );
List contents of an existing folder. The full path of the existing folder must be specified. Specify '', '/' or undef for a top-level listing.
The returned list contains objects from the class WWW::Yahoo::Briefcase::Object. You can access details of each object as follows:
foreach my $object ( @contents ) {
my $location = $object->location; # parent folder
my $name = $object->name;
my $fullname = $object->fullname;
my $fullname = "$object"; # stringification returns fullname of object
my $type = $object->type;
my $size = $object->size; # in bytes
my $time = $object->time; # last-modified-time (seconds since epoch)
}
Note that the size is rounded off to the nearest kilobyte (it is reported that way in the folder listing) and the time is rounded off to midnight GMT (only the date is reported in the folder listing).
Ken Neighbors, Ph.D. ken@nsds.com
Copyright 2003 by Ken Neighbors
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.000 or (at your option) any later version of Perl. That is, you can redistribute this module and/or modify it under the terms of either:
a) the GNU General Public License as published by the Free Software
Foundation; either version 1, or (at your option) any later version,
or
b) the "Artistic License" which comes with Perl, or
c) the license terms of Perl versions later than 5.000
| WWW::Yahoo::Briefcase - interface to Yahoo Briefcase services |