The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
WWW-ImagebinCa-Retrieve-0.01
River stage zero No dependents
++
/ WWW::ImagebinCa::Retrieve

NAME

WWW::ImagebinCa::Retrieve - retrieve uploaded images from http://imagebin.ca

SYNOPSIS

    use strict;
    use warnings;

    use WWW::ImagebinCa::Retrieve;

    my $bin = WWW::ImagebinCa::Retrieve->new;

    my $full_info_ref = $bin->retrieve('MfUHEPkH') # can be a full URI
        or die "Error: " . $bin->error;

    printf "Page ID:%s\nImage located on: %s\nImage URI: %s\n"
            . "Image Description: %s\nSaved image locally as: %s\n",
                @$full_info_ref{ qw(
                    page_id      page_uri  image_uri
                    description  where
                )};

DESCRIPTION

The module provides means of downloading images from http://imagebin.ca along with their description and direct URI for the image.

CONSTRUCTOR

new

    my $bin = WWW::ImagebinCa::Retrieve->new;

    my $bin = WWW::ImagebinCa::Retrieve->new(
        timeout => 10,
    );

    my $bin = WWW::ImagebinCa::Retrieve->new(
        ua => LWP::UserAgent->new(
            timeout => 10,
            agent   => 'PasterUA',
        ),
    );

Constructs and returns a brand new WWW::ImagebinCa::Retrieve object. Takes two arguments, both are optional. Possible arguments are as follows:

timeout

    ->new( timeout => 10 );

Optional. Specifies the timeout argument of LWP::UserAgent's constructor, which is used for retrieving. Defaults to: 30 seconds.

ua

    ->new( ua => LWP::UserAgent->new( agent => 'Foos!' ) );

Optional. If the timeout argument is not enough for your needs of mutilating the LWP::UserAgent object used for retrieving, feel free to specify the ua argument which takes an LWP::UserAgent object as a value. Note: the timeout argument to the constructor will not do anything if you specify the ua argument as well. Defaults to: plain boring default LWP::UserAgent object with timeout argument set to whatever WWW::ImagebinCa::Retrieve's timeout argument is set to as well as agent argument is set to mimic Firefox.

METHODS

retrieve

    $bin->retrieve('1FEgcOol')
        or die 'Error: ' . $bin->error;

    my $full_info = $bin->retrieve(
        what              => 'http://imagebin.ca/view/1FEgcOol.html',
        do_download_image => 1, 
        save_as           => 'pic',
        where             => '/tmp',
    ) or die 'Error: ' . $bin->error;

Instructs the object to retrieve a certain image from http://imagebin.ca given its ID or full URI. Takes either one standalone or several paired arguments. On success returns a hashref of information about retrieved image, see the full_info() method's description for the keys in the returned hashref. If an error occured during the retrieving process returns either undef or an empty list depending on the context and the error will be available via error() method.

When called with a single non-paired argument it will be interpreted as a value for the mandatory what argument. When called with two or more arguments they will be interpreted as follows:

what

    # all these are the SAME
    $bin->retrieve('1FEgcOol');
    $bin->retrieve('http://imagebin.ca/view/1FEgcOol.html');
    $bin->retrieve( what => '1FEgcOol' );
    $bin->retrieve( what => 'http://imagebin.ca/view/1FEgcOol.html' );

Mandatory. As a value takes either the page ID or the full URI to the page with the image you wish to retrieve.

do_download_image

    $bin->retrieve( what => '1FEgcOol', do_download_image => 0 );

Optional Specifies whether or not to download the image. When set to a true value the image represented by what argument will be downloaded, see save_as and where arguments for information on local image filename. When set to a false value, the object will not download the image but will process information about it (such us direct URI to the image and its description). Defaults to: 1

where

    $bin->retrieve( what => '1FEgcOol', where => '/tmp' );

Optional. Specifies the directory into which to download the image. Defaults to: undef (current directory).

save_as

    $bin->retrieve( what => '1FEgcOol', save_as => 'pic' );

Optional. Specifies the name of the file representing the downloaded image. Note: do NOT specify the extension, it will be determined from the page the image is on. In other words, if page with ID 1FEgcOol contains an image of PNG format and you specify save_as argument as pic the image will be stored as pic.png. Defaults to: the ID of the imagebin.ca page the image belongs to.

error

    $bin->retrieve('1FEgcOol')
        or die 'Error: ' . $bin->error;

If an error occured during the call to retrieve() it will return either undef or an empty list depending on the context and the reason for the error will be available via error() method. Takes no arguments, returns a human readable error message.

page_id

    my $image_page_id = $bin->page_id;

Must be called after a successful call to retrieve(). Takes no arguments, returns the ID of the page the image was retrieved from. In other words, after calling either one of:

    $bin->retrieve('1FEgcOol');
    $bin->retrieve('http://imagebin.ca/view/1FEgcOol.html');

The page_id() will return 1FEgcOol in both cases.

image_uri

    printf qq|<div style="background: url(%s)">FOOS!</div>\n|,
                $bin->image_uri;

Must be called after a successful call to retrieve(). Takes no arguments, returns a URI object representing the direct URI to the image itself.

page_uri

    printf "You can see your image on: %s\n",
                $bin->page_uri;

Must be called after a successful call to retrieve(). Takes no arguments, returns a URI object representing the http://imagebin.ca page on which your image is present. In other words, after calling either one of:

    $bin->retrieve('1FEgcOol');
    $bin->retrieve('http://imagebin.ca/view/1FEgcOol.html');

The page_uri() will return http://imagebin.ca/view/1FEgcOol.html in both cases.

description

    my $pic_description = $bin->description;

Must be called after a successful call to retrieve(). Takes no arguments, returns the description of your image or N/A if no description is available.

where

    printf "I have saved your image locally as: %s\n",
                $bin->where;

Must be called after a successful call to retrieve(). Takes no arguments, returns the location (or possible location if do_download_image argument to retrieve() was set to a false value) of the local copy of the image. Note: this is NOT the same as where argument to retrieve() method. This will include the save_as and where arguments to retrieve() as well as the extension of the image.

what

    printf "You've asked me to fetch %s\n",
                $bin->what;

Must be called after a successful call to retrieve(). Takes no arguments, returns whatever you have specified in the what argument to the retrieve() method.

full_info

    my $full_info_ref = $bin->full_info;

    use Data::Dumper;
    print Dumper($full_info_ref);
    # prints:
    {
        'page_id' => '1FEgcOol',
        'page_uri' => bless( do{\(my $o = 'http://imagebin.ca/view/1FEgcOol.html')}, 'URI::http' ),
        'image_uri' => bless( do{\(my $o = 'http://imagebin.ca/img/1FEgcOol.jpg')}, 'URI::http' ),
        'description' => 'Bored Cat_ZZZDescription',
        'where' => '/home/zoffix/Desktop/1FEgcOol.jpg',
        'what'  => '1FEgcOol',
    },

Must be called after a successful call to retrieve(). Instead of calling each of the above methods you may fish to call full_info(). The hashref which full_info() returns is the same as a hashref which retrieve() returns on success. Takes no arguments, returns a hashref keys/values of which are as follows:

page_id

    { 'page_id' => '1FEgcOol', }

The page ID, see page_id() method for description.

page_uri

    { 'page_uri' => bless( do{\(my $o = 'http://imagebin.ca/view/1FEgcOol.html')}, 'URI::http' ), }

The URI object representing the URI of the page. See page_uri() method for description.

image_uri

    {image_uri' => bless( do{\(my $o = 'http://imagebin.ca/img/1FEgcOol.jpg')}, 'URI::http' ), }

The URI object representing the direct URI to the image. See image_uri() method for description.

description

    { 'description' => 'Bored Cat_ZZZDescription', }

The description of your image if available. See description() method for more information.

where

    { 'where' => '/home/zoffix/Desktop/1FEgcOol.jpg', }

Where the image was saved as locally (or would have been saved as if do_download_image argument to retrieve() was set to a false value). See where() method for description.

what

    { 'what'  => '1FEgcOol' }

The what argument which you have specified to the retrieve() method call. See what() method for more information.

PREREQUISITES

For healthy operation this module requires the following modules/versions:

        'Carp'                     => 1.04,
        'URI'                      => 1.35,
        'LWP::UserAgent'           => 2.036,
        'File::Spec'               => 3.2701,
        'HTML::TokeParser::Simple' => 3.15,
        'Class::Data::Accessor'    => 0.04001,

Earlier versions might work, but were not tested.

AUTHOR

Zoffix Znet, <zoffix at cpan.org> (http://zoffix.com, http://haslayout.net)

BUGS

The module relies on HTML parsing thus one day when the author of http://imagebin.ca will decide to recode his or her site the WWW::ImagebinCa::Retrieve will send billions of children to bed hungry.

Please report any bugs or feature requests to bug-www-imagebinca-retrieve at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WWW-ImagebinCa-Retrieve. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc WWW::ImagebinCa::Retrieve

You can also look for information at:

COPYRIGHT & LICENSE

Copyright 2008 Zoffix Znet, all rights reserved.

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