TagLib Perl binding
===================

PREFACE

Almost ALL the docus are commented by the original C/C++ lib authors
Scott Wheeler at http://developer.kde.org/~wheeler/ , Allan Sandfeld
Jenson at kde@carewolf.org and Ismael Orenstein at orenstein@kde.org.

Of course, I modified some parts slightly :-)

DESCRIPTION

TagLib -  a library for reading and editing audio meta data, commonly 
know as tags.

Some goals of TagLib:
 - A clean, high level, C++ API to handling audio meta data.
 - Support for at least ID3v1, ID3v2 and Ogg Vorbis comments.
 - A generic, simple API for the most common tagging related functions.
 - Binary compatibility between minor releases using the standard
KDE/Qt techniques for C++ binary compatibility.
 - Make the tagging framework extensible by library users; i.e. it
will be possible for libarary users to implement  additional ID3v2
frames, without modifying the TagLib source (through the use of
Abstract Factories and such.

Because TagLib desires to be toolkit agnostic, in hope of being widely
adopted and the most flexible in licensing
TagLib provides many of its own toolkit classes; in fact the only
external dependancy that TagLib has, it a semi-sane STL implementation.

INSTALLATION

To install this module type the following:

   perl Makefile.PL
   make
   make test
   make install

Refer to INSTALL for more details.

DEPENDENCIES

This module requires these other modules and libraries:

  libtag.so and taglib-config
  The latter is provided by the taglib-devel package

Note this well It has not been tested with later versions.

TESTING

Testing has been conducted with the taglib versions 1.5 and 1.7.2. It's assumed
that versions inbetween will work as well :-) Functionality of this package has not
been updated to match 1.7.2. Contributions are welcome.

PROBLEMS WITH do_open.

Here's the problem.

g++ ... TagLib.c
In file included from /usr/include/c++/4.2/bits/basic_ios.h:44,
                 from /usr/include/c++/4.2/ios:50,
                 from /usr/include/c++/4.2/ostream:45,
                 from /usr/local/include/taglib/tbytevector.h:33,
                 from /usr/local/include/taglib/tbytevectorlist.h:30,
                 from TagLib.c:178:
/usr/include/c++/4.2/bits/locale_facets.h:4420:40: error: macro "do_open"
requires 7 arguments, but only 2 given
/usr/include/c++/4.2/bits/locale_facets.h:4486:55: error: macro "do_open"
requires 7 arguments, but only 2 given

and the analysis (from the module-authors list)

The problem has nothing to do with perl versions. It is simple and
highly annoying: perl has a do_open macro, but libstdc++ has do_open
methods. This clashes in ugly ways. The simplest way to deal with this
is to undefine do_open before loading any C++ headers, but you may hit
other defines (in particular do_close). Perl's API is made for the
flat namespaces of C, not the hierarchical namespacese of C++. Macro's
that are almost sane in C turn out to be highly problematic in C++.

It gets even worse on Windows, where perl will define short macros
such as read() and write() by default. The NO_XSLOCKS define is your
friend there.

The solution is found in the definitions in TagLib.xs

COPYRIGHT AND LICENCE

Copyright (C) 2005 - 2010 by Dongxu Ma
Copyright (C) 2011- 2012 Geoffrey Leach

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.7 or,
at your option, any later version of Perl 5 you may have available.