NAME
    Pixie - The magic data pixie

SYNOPSIS
      use Pixie;

      my $pixie = Pixie->new->connect( 'memory' );
      my $obj   = SomeObject->new;

      # Note: this API will be changing! See below for details.

      # Store an object
      my $cookie = $pixie->insert( $obj );

      undef( $obj );

      # Fetch it back
      my $obj = $pixie->get( $cookie );

      # Give it a name
      $pixie->bind_name( "Some Name" => $obj );
      my $obj2 = $pixie->get_object_named( "Some Name" );

      # Delete it
      $pixie->delete( $cookie ) || warn "eek!";

      # some stores need deploying before you can use them:
      $pixie = Pixie->deploy( 'dbi:mysql:dbname=px_test' );

DESCRIPTION
    Pixie is yet another object persistence tool. The basic goal of Pixie is
    that it should be possible to throw any object you want at a data pixie
    and the pixie will just tuck it away in its magic sack, giving you a
    cookie in exchange. Then, minutes, hours or days later, you can show the
    pixie your cookie and get the object back.

    No schemas. No complex querying. No refusing to handle blessed arrays.

    How does pixie do this? Well... when we said 'any object' we were being
    slightly disingenuous. As far as Pixie is concerned 'any object' means
    'any object that satisfies any of these criteria':

    *   The inserted object is a blessed hash.

    *   The inserted object is a blessed array

    *   The inserted object is 'complicit' with Pixie, see Pixie::Complicity

    You'll note that we don't include 'blessed arbitrary scalars' in this
    list. This is because, during testing we found that the majority of
    objects that are represented as blessed scalars are often using XS to
    store extra data that Storable and Data::Dumper can't see, which leads
    to all sorts of problems later. So, if you use a blessed scalar as your
    object representation then you'll have to use the complicity features.
    Sorry.

    Pixie can additionally be used to name objects in the store, and fetch
    them later on with that name.

AVAILABLE STORE TYPES
    At the time of writing the following stores were available:

    Memory
        Simple memory store, good for testing. See Pixie::Store::Memory.

          $pixie->connect( 'memory' );

    Berkeley DB
        A Berkeley DB store, also good for testing (especially if you want
        to store values across tests). See Pixie::Store::BerkeleyDB.

          $pixie->connect( "bdb:$path_to_dbfile" );

    DBI DBI-based stores are good for production. See Pixie::Store::DBI and
        subclasses, and DBI for details on DSN specs to use.

        In general:

          $pixie->connect( $dbi_spec, %args );

        For example:

          $pixie->connect( "dbi:SQLite:dbname=$path_to_dbfile" );
          $pixie->connect( 'dbi:mysql:dbname=test', user => 'foo', pass => 'bar' );
          $pixie->connect( 'dbi:Pg:dbname=test;user=foo;pass=bar' );

    See Pixie::Store and its sub-classes for more details on the available
    types of stores and the DSN's to use.

CONSTRUCTOR
    $px = Pixie->new
        Create a new Pixie. You'll have to connect() to a data store before
        you can really do anything.

METHODS
    $px->deploy( $dsn [, @args ] )
        Deploy a Pixie store to the specified $dsn. This is not required for
        all types of store (see Pixie::Store and subclasses), but deploying
        to those stores won't hurt so if you want to make your code generic
        then go for it.

    $px->connect( $dsn [, @args ] )
        Connect the pixie to a store specified by $dsn. Note that you may
        need to deploy() the store before connecting to it.

    $cookie = $px->insert( $object );
        Stores the $object and returns a $cookie which you can use to
        retrieve the $object in the future.

    $obj = $px->get( $cookie )
        Get the object associated with $cookie from the pixie's store.

    $px->delete( $obj || $cookie )
        Delete an object from the pixie's store given a $cookie, or the
        $object itself.

    $px->bind_name( $name => $object )
        Gives a $name to the $object you've specified, so that you can
        retrieve it in the future using get_object_named().

        Returns the cookie of the "Pixie::Name" associated with the $object,
        though this usage is deprecated and will likely be removed in the
        next release.

    $obj = $px->get_object_named( $name )
        Gets the named object from the pixie's store.

    $bool = $px->unbind_name( $name )
        Stop associating $name with an object in the pixie's store. This
        doesn't delete the object itself from the store (see delete() for
        that).

        Returns true if the $name was unbound, false if not (ie: if it
        wasn't bound in the first place).

PLANNED API CHANGES
    Some methods will be deprecated in the near future in an effort to
    create a more consistent API. Here is an overview of the planned
    changes:

    $cookie = $px->store( [ $name => ] $object )
        This will replace insert(), and will make naming objects easier.

    $obj = $px->fetch( $name || $cookie )
        This will replace get() and get_object_named().

    $obj->remove( $obj || $cookie || $name )
        This will replace delete() and unbind_name().

SEE ALSO
    Pixie::Complicity -- Sometimes Pixie can't make an object persistent
    without help from the object's class. In that case you need to make the
    class 'complicit' with Pixie. You'll typically need to do this with XS
    based classes that use a simple scalar as their perl visible object
    representation, or with closure based classes.

    Pixie::FinalMethods -- There are some methods that Pixie requires to
    behave in a particular way, not subject to the vagaries of overloading.
    One option would be to write a bunch of private subroutines and methods
    within Pixie, but very often it makes sense to move the behaviour onto
    the objects being stored. Pixie::FinalMethods describes how we achieve
    this.

    Pixie::Store is the abstract interface to physical storage. If you want
    to write a new backend for pixie, start here.

WITH THANKS
    Jean Louis Leroy, author of Tangram, for letting us use ideas and code
    from the Tangram test suite.

AUTHORS
    Pixie sprang from the mind of James Duncan <james@fotango.com>. Piers
    Cawley <pdcawley@bofh.org.uk> and Leon Brocard <acme@astray.org> are his
    co conspiritors.

    Steve Purkis <spurkis@cpan.org> is helping to maintain the module.

COPYRIGHT
    Copyright (c) 2002-2004 Fotango Ltd.

    This software is released under the same license as Perl itself.