NAME
Image::Grab - Perl extension for Grabbing images off the Internet.
SYNOPSIS
use Image::Grab;
$pic = new Image::Grab;
# The simplest case of a grab
$pic->url('http://www.example.com/someimage.jpg')
$pic->grab;
# How to get at the image
open(DISPLAY, "| display -");
print DISPLAY $pic->image;
close(DISPLAY)
# A slightly more complicated case
$pic->url('.*logo.*\.gif');
$pic->refer('http://www.example.com');
$pic->grab;
# Get a weather forecast
$pic->url('msy.*\.gif');
$pic->refer('http://www.example.com/weather/msy/content.shtml');
$pic->grab;DESCRIPTION
Image::Grab is a simple way to get images with URLs that change constantly.
The "change constantly" part is important here. If this module did nothing but grab an image off the net, then it would be nothing more than a silly convenience module. But this module is not silly.
This module was born from a script. The script was born when a certain Comics Syndicate stopped having a static (or even predictable) url for their comics. I generalized the code for a friend when he needed to do something similar.
Hopefully, others will find this module useful as well.
Accessor Methods
The following are the accessor methods available for any Image::Grab object. Accessor methods are used to get or set information for an object. For example,
$img->refer("http://www.example.com");would set the refer field and
$img->refer;would return the information contained in the refer field.
refer, regexp, and url all have POSIX time string expansion performed on the by getRealURL. Thus, if you wish to have a '%' character in your URL, you must put '%%'.
cookiefile
Where the cookiefile is located. Set this to the file containing the cookies if you wish to use the cookie file for the image.
cookiejar
Usually only used internally. The cookiejar for the image.
date
The date that the image was last updated. The date is represented in the number of seconds from epoch where epoch is January 1, 1970. This is normally not set by the user.
image
The actual image. Usually, you should't try to set this field.
md5
The md5 sum for the image. Usually, you shouldn't try to set this field.
refer
When you do a grab, this url will be given as the referring URL. If the url method is not used to specify an image (and the regexp or index methods are used instead) then the information from the URL in the refer field will be used to find the image. For example, if regexp="mac.*\.gif" and refer="http://www.example.com", then when a grab is performed, the page at www.example.com is searched to see if any images on the page match the regular expression.
CAUTION! POSIX time string expansion is performed.
type
The type of information. Usually it will be a MIME type such as "image/jpeg".
ua
Usually only used internally. The user agent used to get the image.
Methods for specifying the image
One of the following should be set to specify the image. If either regexp or index are used to specify the image, then refer must be set to specify the page to be searched for the image.
Image::Grab will the data in the following order: url, regexp, index.
index
An integer indicating the image on the page to grab. For instance, '1' would find the second image on the page pointed to by the refer. Used in conjunction with regexp, it specifies which image to grab that the regular expression matches.
Example:
$image->refer("http://www.example.com/index.html"); $image->regexp(1);
regexp
A regular expression that will match the URL of the image. If index is not set, then the first image that matches will be used. If index is set, then the nth image that matches will be used.
CAUTION! POSIX time string expansion is performed.
Example:
$image->refer("http://www.example.com/index.html"); $image->regexp(".*\.gif");
url
The fully qualified URL of the image.
CAUTION! POSIX time string expansion is performed.
Example:
$image->url("http://www.example.com/%Y/%m/%d.gif");
Other Methods
realm($user, $password)
Provides a username/password pair for the realm the image is in.
getAllURLs ([$tries])
Returns a list of URLs pointing to images from the page pointed to by refer. Of course, refer must be set for this method to be of any use.
If $tries is specified, then $tries are attempted before giving up. $tries defaults to 10.
Returns undef if no connection is made in $tries attempts or if the URL is not of type text/html.
getRealURL ([$tries])
Returns the actual URL of the image specified. Performs POSIX time string expansion (see strftime) using the current time.
You can use this method to get the URL for an image if that is all you need.
If $tries is specified, then $tries are attempted before giving up. $tries defaults to 10.
Returns undef if no connection is made in $tries attempts, if the refer URL is not of type text/html, or if no image that matches the specs is found.
If url is given a full URL, then it is returned with POSIX time string expansion performed.
loadCookieJar
Usually used only internally. Loads up the cookiejar with cookies.
grab ([$tries])
Grab the image. If the url method is not used to give an absolute url, then getRealURL is called before the image is fetched.
If $tries is specified, then $tries are attempted before giving up. $tries defaults to 10.
grab_new
Not Yet Implemented. Currently, it acts just like grab.
BUGS
getAllURLs and getRealURL should really be fixed so that they go out to the 'net only once if they need to.
Ummm... I am sure there are others...
AUTHOR
Mark A. Hershberger <mah@everybody.org>
SEE ALSO
perl(1), strftime(3).
3 POD Errors
The following errors were encountered while parsing the POD:
- Around line 169:
=back doesn't take any parameters, but you said =back 4
- Around line 186:
=back doesn't take any parameters, but you said =back 4
- Around line 200:
=back doesn't take any parameters, but you said =back 4