This latest release modifies the interface in incompatible ways.
Specifically, the url method no longer is used for indices and regular
expressions.  See the documentation.  

Also, I've added support for POSIX time strings (%y, %d, etc.).  That
can cause trouble if you want to have percent signs in your URLs.  If
you do, then you need to 'quote' them, like this: %%

A couple of new methods as well.

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 *n*th 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).

