view release on metacpan or  search on metacpan

lib/Class/DBI/AsXML.pm  view on Meta::CPAN

package Class::DBI::AsXML;
# $Id: AsXML.pm,v 1.2 2005/01/15 15:32:32 cwest Exp $
use strict;

=head1 NAME

Class::DBI::AsXML - Format CDBI Objects as XML

=head1 SYNOPSIS

  # As you do...
  package MyApp::User;
  use base qw[Class::DBI];
  
  __PACKAGE__->connection('dbi:SQLite:dbfile', '', '');
  __PACKAGE__->table(q[users]);
  __PACKAGE__->columns(Primary => 'id');
  __PACKAGE__->columns(Essential => qw[username password]);
  __PACKAGE__->columns(Others    => qw[email zip_code phone]);
  __PACKAGE__->has_a(pref => 'MyApp::Pref');

  # Enter XML Support!
  use Class::DBI::AsXML;
  __PACKAGE__->to_xml_columns([qw[username email zip_code]]);

  # Elsewhere...
  my $user = MyApp::User->retrieve(shift);
  my $user_and_prefs_xml = $user->to_xml(depth => 1);

  # Or... override defaults
  my $uname_pwd_xml = $user->to_xml( columns => {
      ref($user) => [qw[username password]],
  });
  
  # Create from XML
  my $new_user = MyApp::User->create_from_xml(<<__XML__);
  <user>
    <username>new_user</username>
    <password>new_pass</password>
    <email>&lt;casey@geeknest.com%gt;</email>
  </user>
  __XML__

=cut

use base qw[Exporter];
use vars qw[@EXPORT $VERSION];
$VERSION = sprintf "%d.%02d", split m/\./, (qw$Revision: 1.2 $)[1];
@EXPORT  = qw[to_xml create_from_xml _to_xml_stringify];

use XML::Simple;
use overload;

=head1 DESCRIPTION

This software adds XML output support to C<Class::DBI> based objects.

=head2 to_xml_columns

  Class->to_xml_columns([qw[columns to dump with xml]]);

This class method sets the default columns this class should dump
when calling C<to_xml()> on an object. The single parameter is a
list reference with column names listed.

=head2 to_xml

  my $xml = $object->to_xml(
                columns => {
                    MyApp::User  => [ qw[username email zip_code] ],
                    MyApp::File  => [ qw[user filename size]      ],
                    MyApp::Pref  => [ MyApp::Pref->columns        ],
                },
                depth => 10,
                xml => {
                    NoAttr => 0,
                },
            );

All arguments are optional.

C<columns> - A hash reference containing key/value pairs associating
class names to a list of columns to dump as XML when the class is
serialized. They keys are class names and values are list references
containing column names, just as they'd be sent to C<to_xml_columns()>.
Passing a C<columns> parameter to this instance method will override
any defaults associated with this object. Failing that, C<to_xml_colunms()>
is checked and failing that, the C<Primary> and C<Essential> columns