NEW VS. CREATE

  $info = new Image::IPTCInfo('file-name-here.jpg');
  $info = create Image::IPTCInfo('file-name-here.jpg');

new() will create a new object only if the file had IPTC data in it. It will return undef otherwise, and you can check Error() to see what the reason was. Using create(), on the other hand, always returns a new IPTCInfo object if there was data or not. If there wasn't any IPTC info there, calling Attribute() on anything will just return undef; i.e. the info object will be more-or-less empty.

If you're only reading IPTC data, call new(). If you want to add or change info, call create(). Even if there's no useful stuff in the info object, you can then start adding attributes and save the file. That brings us to the next topic....

MODIFYING IPTC DATA

  # Set a given attribute
  $info->SetAttribute('iptc attribute here', 'new value here');

  # Clear the keywords or supp. categories list
  $info->ClearKeywords();
  $info->ClearSupplementalCategories();
  $info->ClearContacts();

  # Add keywords or supp. categories
  $info->AddKeyword('frob');

  # You can also add a list reference
  $info->AddKeyword(['frob', 'nob', 'widget']);

SAVING FILES

  $info->Save();
  $info->SaveAs('new-file-name.jpg');

This will save the file with the updated IPTC info. Please only run this on *copies* of your images -- not your precious originals! -- because I'm not liable for any corruption of your images. (If you read software license agreements, nobody else is liable, either. Make backups of your originals!)

If you're into image wizardry, there are a couple handy options you can use on saving. One feature is to trash the Adobe block of data, which contains IPTC info, color settings, Photoshop print settings, and stuff like that. The other is to trash all application blocks, including stuff like EXIF and FlashPix data. This can be handy for reducing file sizes. The options are passed as a hashref to Save() and SaveAs(), e.g.:

  $info->Save({'discardAdobeParts' => 'on'});
  $info->SaveAs('new-file-name.jpg', {'discardAppParts' => 'on'});

Note that if there was IPTC info in the image, or you added some yourself, the new image will have an Adobe part with only the IPTC information.

XML AND SQL EXPORT FEATURES

  $xml = $info->ExportXML('entity-name', \%extra-data,
                          'optional output file name');

This returns XML containing all image metadata. Attribute names are translated into XML tags, making adjustments to spaces and slashes for compatibility. (Spaces become underbars, slashes become dashes.) You provide an entity name; all data will be contained within this entity. You can optionally provides a reference to a hash of extra data. This will get put into the XML, too. (Example: you may want to put info on the image's location into the XML.) Keys must be valid XML tag names. You can also provide a filename, and the XML will be dumped into there. See the "demo.pl" script for examples.

For SQL, it goes like this:

  my %mappings = (
       'IPTC dataset name here' => 'your table column name here',
       'caption/abstract'       => 'caption',
       'city'                   => 'city',
       'province/state'         => 'state); # etc etc etc.
    
  $statement = $info->ExportSQL('mytable', \%mappings, \%extra-data);

This returns a SQL statement to insert into your given table name a set of values from the image. You pass in a reference to a hash which maps IPTC dataset names into column names for the database table. As with XML export, you can also provide extra information to be stuck into the SQL.