.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "POD2::JA::KiokuDB::Tutorial 3pm"
.TH POD2::JA::KiokuDB::Tutorial 3pm "2014-03-25" "perl v5.18.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
POD2::JA::KiokuDB::Tutorial \- KiokuDBXXXXX
.SH "Install"
.IX Header "Install"
(\s-1XXXXXX\s0)
.PP
KiokuDB\s-1XXXXXXXXXXXXXXXXXXXXXX\s0Task::KiokuDB\s-1XXXXXXXXXXXXXXXXXX\s0
.PP
KiokuDBXMoose\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXX\s0
.PP
KiokuDB\s-1XXXXXXXXXXXXXXXXXXXXX
\&\s0\s-1DBI\s0\s-1XXXXXXXXXXXXXXXDBDXXXXXXXXXXXXXX\s0
.PP
\&\s-1XXXXXXXXXXXXXXXXXXX\s0KiokuDB::Backend::Hash\s-1XXXXXXXXXXXXXXXXX
XXXXXXXXXX\s0KiokuDB::Backend::DBDXKiokuDB::Backend::DBIXKiokuDB::Backend::BDB
\&\s-1XXXXXXXXXXXXXXXX\s0
.PP
KiokuDB::Backend::DBD\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\s0
.SH "CREATING A DIRECTORY HANDLE"
.IX Header "CREATING A DIRECTORY HANDLE"
(\s-1XXXXXXXXXXXXX\s0)
.PP
KiokuDBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
.PP
\&\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXX:\s0
.PP
.Vb 3
\&    my $dir = KiokuDB\->new(
\&        backend => KiokuDB::Backend::Hash\->new
\&    );
.Ve
.PP
\&\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXX\s0
.PP
\&\s-1XXXXXXXXXXXXXXXXXXXDSNXXXXXXXXXXXXXX\s0
.PP
.Vb 1
\&    KiokuDB\->connect("hash");
\&
\&    KiokuDB\->connect("dbi:SQLite:dbname=foo", create => 1);
\&
\&    KiokuDB\->connect("bdb:dir=foo", create => 1);
.Ve
.PP
\&\s-1XXXXXXXXXXXXXXXXX\s0
.PP
.Vb 1
\&    KiokuDB\->connect("/path/to/my_db.yml");
.Ve
.PP
\&\s-1XXYAMLXXXXXX:\s0
.PP
.Vb 6
\&    \-\-\-
\&    # these are basically the arguments for \*(Aqnew\*(Aq
\&    backend:
\&      class: KiokuDB::Backend::DBI
\&      dsn: dbi:SQLite:dbname=/tmp/test.db
\&      create: 1
.Ve
.SH "USING THE DBI BACKEND"
.IX Header "USING THE DBI BACKEND"
(\s-1DBIXXXXXXXXX\s0)
.PP
2XXXXXXXXXXXXXXXXXDBIXXXXXXXXXXXX
1XXXXXXX\s-1DBI\s0\s-1XXXXXXXXXXXXX
2XXXXXXXXXXXXXXXXXXXXXXXXXXX
\&\s0KiokuDB\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\s0
.PP
\&\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXX\s0
.PP
\&\s-1XXXXX\s0\f(CW$dir\fR\s-1XXXXXXXXXXXXXX:\s0
.PP
.Vb 4
\&    my $dir = KiokuDB\->connect(
\&        "dbi:SQLite:dbname=kiokudb_tutorial.db",
\&        create => 1, # this causes the tables to be created
\&    );
.Ve
.PP
\&\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:\s0
.PP
.Vb 5
\&    my $dir = KiokuDB\->connect(
\&        $dsn,
\&        user     => $user,
\&        password => $password,
\&    );
.Ve
.SH "INSERTING OBJECTS"
.IX Header "INSERTING OBJECTS"
(\s-1XXXXXXXXXXXX\s0)
.PP
Moose\s-1XXXXXXXXXXXXXXXXXXXX:\s0
.PP
.Vb 2
\&    package Person;
\&    use Moose;
\&
\&    has name => (
\&        isa => "Str",
\&        is  => "rw",
\&    );
.Ve
.PP
\&\s-1XXXXXXXXXXXXX:\s0
.PP
.Vb 1
\&    my $obj = Person\->new( name => "Homer Simpson" );
.Ve
.PP
\&\s-1XXXXXXXXXXXXXXXXXXXXXXXX:\s0
.PP
.Vb 1
\&    my $scope = $dir\->new_scope;
\&
\&    my $homer_id = $dir\->store($obj);
.Ve
.PP
\&\s-1XXXX\s0KiokuDB\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\s0
.PP
1XXXXXXXXXXXXXXXXXKiokuDB\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXX\s0Moose\s-1XXXXXXXXXXX\s0
.PP
2XXXXXXXXXXXXXXXXXXXXXXXXXXXXIDXXXXXX
\&\s-1XXXXXXXIDXXXXXXXXX\s0KiokuDB\s-1XXXXXUUIDXXXXXXXX\s0
.PP
\&\s-1IDXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\s0
.PP
\&\s-1XXXXXXXXXXIDXXXXXXXXXXXXXXXXXXXXXX:\s0
.PP
.Vb 1
\&    $dir\->store( homer => $obj );
.Ve
.PP
3XXXXXXXXKiokuDB\s-1XXX\s0\fBscope\fR\s-1XXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\s0
XXXXXweakXXXXXXXXXXXXXXXXXXXXXXXXXX
\&\s-1XXXXXXXXXXXXXX\s0
.SH "LOADING OBJECTS"
.IX Header "LOADING OBJECTS"
(\s-1XXXXXXXXXXX\s0)
.PP
XXXXXXXXXXHomerXXXXXXX\f(CW\*(C`store\*(C'\fR\s-1XXXXIDXXXXXXXX\s0
.PP
.Vb 1
\&    my $homer = $dir\->lookup($homer_id);
.Ve
.PP
\&\f(CW$scope\fRX\f(CW$obj\fR\s-1XXXXXXXXXXXXXXX\s0\f(CW$homer\fRX\f(CW$obj\fR\s-1XXXXXXXXXXXXXXXXXXX\s0
.PP
.Vb 2
\&    # this is true:
\&    refaddr($homer) == refaddr($obj)
.Ve
.PP
\&\fB\s-1XXXXXXXXXXXXXXX\s0\fR (KiokuDB::LiveObjects)XXXXXXXXX
\&\*(L"\s-1XX\*(R"XXXXXX\s0KiokuDB\s-1XXXXXXXXXXXX\s0
.PP
\&\s-1XXXXXXXXXXXXXXXXX\s0KiokuDB\s-1XXXXXXXX
XXXXXXXXXXXXXX\s0
.SH "WHAT WAS STORED"
.IX Header "WHAT WAS STORED"
(\s-1XXXXXXXX\s0)
.PP
\&\s-1XXXXXXXXXXXXXXX:\s0
.PP
.Vb 4
\&    % sqlite3 kiokudb_tutorial.db
\&    SQLite version 3.4.0
\&    Enter ".help" for instructions
\&    sqlite>
.Ve
.PP
\&\s-1XXXXXXXXXXXXX2XXXXXXXXXXXX\s0\f(CW\*(C`entries\*(C'\fRX\f(CW\*(C`gin_index\*(C'\fR\s-1XX:\s0
.PP
.Vb 2
\&    sqlite> .tables
\&    entries    gin_index
.Ve
.PP
\&\f(CW\*(C`gin_index\*(C'\fR\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\s0
.PP
\&\s-1XXX\s0\f(CW\*(C`entries\*(C'\fR\s-1XXXXXXXXXXXX:\s0
.PP
.Vb 9
\&    sqlite> .schema entries
\&    CREATE TABLE entries (
\&      id varchar NOT NULL,
\&      data blob NOT NULL,
\&      class varchar,
\&      root boolean NOT NULL,
\&      tied char(1),
\&      PRIMARY KEY (id)
\&    );
.Ve
.PP
\&\s-1XXXXXXXX\s0\f(CW\*(C`id\*(C'\fRX\f(CW\*(C`data\*(C'\fR\s-1XXX\s0KiokuDB\s-1XXXXXXXXXXXXXXXXIDXXXX
XXXXXXXXBLOBXXXXXXXXXXXXXXX\s0
.PP
\&\s-1DBIXXXXXXXXXXXXXXXXXXXXX\s0KiokuDB::Serializer::JSON\s-1XXXXX
XXXXXXXXXXX\s0
.PP
\&\s-1XXXX\s0\f(CW\*(C`sqlite\*(C'\fR\s-1XXXXXXX\s0\f(CW\*(C`line\*(C'\fR\s-1XXXXXXXXXXXXXXXXXX
XXXXXXXX:\s0
.PP
.Vb 1
\&    sqlite> .mode line
.Ve
.PP
\&\s-1XXXXXXXXXXXXXXX:\s0
.PP
.Vb 3
\&    sqlite> select id, data from entries;
\&       id = 201C5B55\-E759\-492F\-8F20\-A529C7C02C8B
\&     data = {"_\|_CLASS_\|_":"Person","data":{"name":"Homer Simpson"},"id":"201C5B55\-E759\-492F\-8F20\-A529C7C02C8B","root":true}
.Ve
.PP
\&\s-1XXXXXXX\s0\f(CW\*(C`name\*(C'\fRXXXblobXX\f(CW\*(C`data\*(C'\fR\s-1XXXXXXXXXXXXXXXXXXXXXXXXX\s0
.PP
\&\f(CW\*(C`data\*(C'\fR\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\s0
.PP
\&\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXX\s0
.PP
KiokuDB::Backend::DBD\s-1XXXXXXXXXXXXXXXXXXXXXX\s0\f(CW\*(C`id\*(C'\fR\s-1XX\s0\f(CW\*(C`data\*(C'\fR\s-1XXXXXXXXX
XXXXXXXXXXXXXXX\s0
.SH "OBJECT RELATIONSHIPS"
.IX Header "OBJECT RELATIONSHIPS"
(\s-1XXXXXXXXXXXXXXXX\s0)
.PP
\&\f(CW\*(C`Person\*(C'\fR\s-1XXXX\s0\f(CW\*(C`name\*(C'\fR\s-1XXXXXXXXXXXXXXXXXXXXXXX:\s0
.PP
.Vb 1
\&    package Person;
\&
\&    has spouse => (
\&        isa => "Person",
\&        is  => "rw",
\&        weak_ref => 1,
\&    );
.Ve
.PP
\&\f(CW\*(C`spouse\*(C'\fRXXXXXPersonXXXXXXXXXXXXXXXXXXX
.PP
\&\s-1XXXXXXXXXXXXXXXXXXX:\s0
.PP
.Vb 3
\&    my $marge_id = $dir\->store(
\&        Person\->new( name => "Marge Simpson" ),
\&    );
.Ve
.PP
\&\s-1XXXXXXXXXXXXXXXXXXXXXXX2XXXXXXXXXXXXX:\s0
.PP
.Vb 2
\&    {
\&        my $scope = $dir\->new_scope;
\&
\&        my ( $marge, $homer ) = $dir\->lookup( $marge_id, $homer_id );
\&
\&        $marge\->spouse($homer);
\&        $homer\->spouse($marge);
\&
\&        $dir\->store( $marge, $homer );
\&    }
.Ve
.PP
\&\s-1XXXXXX\s0\fB\s-1XXXXXXXXX\s0\fR\s-1XXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXX\s0
.PP
\&\f(CW\*(C`spouse\*(C'\fR\s-1XX\s0\f(CW\*(C`weak_ref\*(C'\fR\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXX\s0
.PP
\&\s-1XXXXXXXXXXXXXXXXXXXXX\s0LinkDBX\f(CW\*(C`spouse\*(C'\fR\s-1XXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXIDXXXXXXXXXXXXXX\s0
.PP
\&\s-1XXXXXXXXXXXXXXXXXXXXXXXX:\s0
.PP
.Vb 2
\&    {
\&        my $scope = $dir\->new_scope;
\&
\&        my $homer = $dir\->lookup($homer_id);
\&
\&        print $homer\->spouse\->name; # Marge Simpson
\&    }
\&
\&    {
\&        my $scope = $dir\->new_scope;
\&
\&        my $marge = $dir\->lookup($marge_id);
\&
\&        print $marge\->spouse\->name; # Homer Simpson
\&
\&        refaddr($marge) == refaddr($marge\->spouse\->spouse); # true
\&    }
.Ve
.PP
KiokuDB\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXX\s0\f(CW\*(C`spouse\*(C'\fR\s-1XXXXXXXXXXXX\s0(\s-1IDX\s0)
\&\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\s0
.ie n .SS "The purpose of ""new_scope"""
.el .SS "The purpose of \f(CWnew_scope\fP"
.IX Subsection "The purpose of new_scope"
(\f(CW\*(C`new_scope\*(C'\fR\s-1XXX\s0)
.PP
\&\f(CW\*(C`new_scope\*(C'\fR\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\s0
.PP
\&\s-1XXXXXXXXXXXX\s0\f(CW\*(C`lookup\*(C'\fR\s-1XX\s0\f(CW$homer\fR\s-1XXXXXXXXXXX
\&\s0\f(CW\*(C`spouse\*(C'\fR\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\s0
.PP
\&\s-1XXXXXXXXXXXXXXXXXXXX:\s0
.PP
.Vb 3
\&    sub get_homer {
\&        my $homer = Person\->new( name => "Homer Simpson" );
\&        my $marge = Person\->new( name => "Marge Simpson" );
\&
\&        $homer\->spouse($marge);
\&        $marge\->spouse($homer);
\&
\&        return $homer;
\&
\&        # at this point $homer and $marge go out of scope
\&        # $homer has a refcount of 1 because it\*(Aqs the return value
\&        # $marge has a refcount of 0, and gets destroyed
\&        # the weak reference in $homer\->spouse is cleared
\&    }
\&
\&    my $homer = get_homer();
\&
\&    $homer\->spouse; # this returns undef
.Ve
.PP
\&\s-1XXXXXXXXXXX:\s0
.PP
.Vb 2
\&    {
\&        my $scope = $dir\->new_scope;
\&
\&        # do all KiokuDB work in here
\&    }
.Ve
.PP
\&\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\s0
.PP
WebXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
\&\s-1XXX\s0Catalyst::Model::KiokuDB\s-1XXXXXXXXXXXXXX\s0
.SH "REFERENCES IN THE DATABASE"
.IX Header "REFERENCES IN THE DATABASE"
(\s-1XXXXXXXXXXXXXX\s0)
.PP
\&\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\s0
.PP
.Vb 3
\&    sqlite> select id, data from entries;
\&       id = 201C5B55\-E759\-492F\-8F20\-A529C7C02C8B
\&     data = {"_\|_CLASS_\|_":"Person","data":{"name":"Homer Simpson","spouse":{"$ref":"05A8D61C\-6139\-4F51\-A748\-101010CC8B02.data"}},"id":"201C5B55\-E759\-492F\-8F20\-A529C7C02C8B","root":true}
\&
\&       id = 05A8D61C\-6139\-4F51\-A748\-101010CC8B02
\&     data = {"_\|_CLASS_\|_":"Person","data":{"name":"Marge Simpson","spouse":{"$ref":"201C5B55\-E759\-492F\-8F20\-A529C7C02C8B.data"}},"id":"05A8D61C\-6139\-4F51\-A748\-101010CC8B02","root":true}
.Ve
.PP
\&\f(CW\*(C`spouse\*(C'\fR\s-1XXXXXXJSONXXXXXXXXXXXXXXXXXXXX
XXXXXXXXX\s0\f(CW$ref\fR\s-1XXXXXXXXXXXXXXXXXXUUIDXXXXXX\s0
.PP
\&\s-1XXXXXXXXXXXX\s0KiokuDB\s-1XXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\s0
.PP
\&\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXX\s0\f(CW\*(C`JPSON\*(C'\fRX JavaScript Persistent Object notation(<http://www.jpson.org>)XXXXXXXXX
KiokuDB::Backend::Storable\s-1XXXXX\s0KiokuDB::EntryXKiokuDB::Reference\s-1XXXXXXXX\s0
XXXXXstorableXXXXXXXXXXXXXXX
.SH "OBJECT SETS"
.IX Header "OBJECT SETS"
(\s-1XXXXXXXXX\s0)
.PP
\&\s-1XXXXXXXXXXXXXX\s0(1X1XXXXX)XXSet::Object\s-1XXXXXXXXXXXXXXXX\s0
.PP
\&\f(CW\*(C`Person\*(C'\fR\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:\s0
.PP
.Vb 1
\&    package Person;
\&
\&    has children => (
\&        does => "KiokuDB::Set",
\&        is   => "rw",
\&    );
.Ve
.PP
KiokuDB::Set\s-1XXXXXXXX\s0Set::ObjectXKiokuDB\s-1XXXXXXXXX\s0
.PP
.Vb 1
\&    my @kids = map { Person\->new( name => $_ ) } qw(maggie lisa bart);
\&
\&    use KiokuDB::Util qw(set);
\&
\&    my $set = set(@kids);
\&
\&    $homer\->children($set);
\&
\&    $dir\->store($homer);
.Ve
.PP
\&\f(CW\*(C`set\*(C'\fR\s-1XXXXXXXXXXXX\s0KiokuDB::Set::Transient\s-1XXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXX
\&\s0(\s-1XXXXXXXXXXXXXXXXXXXXXX\s0)X
.PP
\&\f(CW\*(C`weak_set\*(C'\fR\s-1XXXXXXXXXXXXXX
XXXX\s0(\s-1XXXXXXXX\s0\f(CW\*(C`parent\*(C'\fR\s-1XXXXXXX\s0)XXXXXXXXXXXXXXXXX
Set::Object::Weak\s-1XXXXXXXXXXXXXX\s0
.PP
\&\s-1XXXXXXXXXXXX\s0Set::Object\s-1XXXXXXXXXXXXXXXXX\s0
.PP
.Vb 1
\&    my @kids = $dir\->lookup($homer_id)\->children\->members;
.Ve
.PP
\&\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
\&\s0\f(CW@kids\fR\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\s0
.PP
\&\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXX\s0KiokuDB::Set::DefferedXKiokuDB::Set::Loaded\s-1XXXXXXXXXX\s0
.PP
\&\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXX2XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\s0
.SH "THE TYPEMAP"
.IX Header "THE TYPEMAP"
KiokuDB\s-1XXXXXXXXXXXXXXXX\s0KiokuDB::Collapser\s-1XXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXX\s0KiokuDB::Entry\s-1XX
\&\*(L"XXX\*(R"XXXXXXXXXXXXXXX\s0
.PP
collapserXXXKiokuDB::TypeMap\s-1XXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\s0
.PP
\&\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\s0
XXXXXXXXXXXXXXXXXXXtypemapXXXXXXX
.PP
typemapXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
\&\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\s0(\s-1XXXX
\&\s0\f(CW\*(C`DBI\*(C'\fR\s-1XXXXXXXXXXXXXXSXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\s0)X
\&\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\s0
.PP
\&\s-1XXXXXXXXXX\s0Moose\s-1XXXXXXXXXXXXX\s0Moose\s-1XXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXX\s0
.PP
\&\s-1XXXXXXXXXXXXXXXXXXXXXXX\s0(DateTime, Path::Class\s-1XX\s0>)XX
XXXXXXtypemapXXXXXXXXXKiokuDBXXXXXXXXXtypemapXXXXXXX
\&\s-1XXXXXXXXXXXXXX\s0
.PP
\&\s-1XXXXXXX\s0KiokuDBXClass::Accessor\s-1XXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXX:\s0
.PP
.Vb 4
\&    KiokuDB\->new(
\&        backend => $backend,
\&        allow_classes => [qw(My::Object)],
\&    );
.Ve
.PP
\&\s-1XXXXXXXXXX:\s0
.PP
.Vb 8
\&    my $dir = KiokuDB\->new(
\&        backend => $backend,
\&        typemap => KiokuDB::TypeMap\->new(
\&            entries => {
\&                "My::Object" => KiokuDB::TypeMap::Entry::Naive\->new,
\&            },
\&        ),
\&    );
.Ve
.PP
KiokuDB::TypeMap::Entry::Naive\s-1XXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXX\s0
.PP
collapser \s-1XXXXXXXXXXXXXXX\s0KiokuDB::TypeMap::Resolver\s-1XX
XXXXXXXXXXXXXXXXXXXXXXXXXXX\s0
.PP
\&\s-1XXXXXXXXXXXX\s0\f(CW\*(C`ref $object\*(C'\fR\s-1XXXXXXXXXXXXXX\s0
XXXXXXXXXXXXXXXXXtypemapXXXXXXX
\&\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXX\s0\fB\s-1XXX\s0\fR\s-1XXX\s0\f(CW\*(C`isa_entries\*(C'\fR\s-1XXXXXXXXXX\s0
.PP
.Vb 5
\&    KiokuDB::TypeMap\->new(
\&        isa_entries => {
\&            "My::Object" => KiokuDB::TypeMap::Entry::Naive\->new,
\&        },
\&    );
.Ve
.PP
\&\s-1XXXXXXXXXX\s0(\f(CW\*(C`ref\*(C'\fR keyed)XXXXXXXXXXXXXXX
isaXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
\&\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\s0
.SS "Typemap Entries"
.IX Subsection "Typemap Entries"
\&\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXX\s0
.PP
.Vb 3
\&    KiokuDB::TypeMap::Entry::Callback\->new(
\&        collapse => sub {
\&            my $object = shift;
\&
\&            ...
\&
\&            return @some_args;
\&        },
\&        expand => sub {
\&            my ( $class, @some_args ) = @_;
\&
\&            ...
\&
\&            return $object;
\&        },
\&    );
.Ve
.PP
\&\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\s0
.PP
XXXXtypemapXISAXXXXXPath::ClassX:
.PP
.Vb 5
\&    \*(AqPath::Class::Entity\*(Aq => KiokuDB::TypeMap::Entry::Callback\->new(
\&        intrinsic => 1,
\&        collapse  => "stringify",
\&        expand    => "new",
\&    );
.Ve
.PP
\&\f(CW\*(C`intrinsic\*(C'\fR\s-1XXXXXXXXXXXXXXXXX\s0
.PP
typemapXXXXXXXXXXXXXKiokuDB::Typemap::Entry::Passthrough\s-1XXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXX\s0
.PP
\&\s-1XXXXXXXXXXXXXX\s0Storable\s-1XXXXXX\s0(\s-1XXXXXXXXXXXXXXXXXXXXXX\s0)X
\&\s-1XXXXXXXXX\s0KiokuDB::Backend::Serialize::Storable\s-1XXXXXXXX
\&\s0DateTimeXXXXXXstorableXXXXXXXXXX:
.PP
.Vb 1
\&    \*(AqDateTime\*(Aq => KiokuDB::Backend::Entry::Passthrough\->new( intrinsic => 1 )
.Ve
.SS "Intrinsic vs. First Class"
.IX Subsection "Intrinsic vs. First Class"
KiokuDB\s-1XXXXXXXXXXXXXXXXXXIDXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\s0
.PP
\&\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXX\s0DateTime\s-1XX\s0Path::Class\s-1XXXXX\s0\s-1URI\s0\s-1XXXXXXXXXXXXXX
XXXXXXXX\s0
.PP
KiokuDBX\fBintrinsicly\fR\s-1XXXXXXXXXXXXXXX
XXXXXXXXXXXXXXIDXXXX\s0KiokuDB::Entry\s-1XXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\s0
.PP
\&\s-1XXXXXXXXXXXXXXXXXXXXXX2XXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXX\s0
.PP
\&\s-1XXXXXXXXXXXXXXXXXXXXX:\s0
.PP
.Vb 1
\&    use Path::Class;
\&
\&    my $path = file(qw(path to foo));
\&
\&    $obj_1\->file($path);
\&
\&    $obj_2\->file($path);
\&
\&    $dir\->store( $obj_1, $obj_2 );
.Ve
.PP
\&\s-1XXXXXXXXXXXXXXXXXXXXXXXXX
\&\s0\f(CW$obj_1\fRX\f(CW$obj_2\fR\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXX:\s0
.PP
.Vb 1
\&    refaddr($obj_1\->file) == refaddr($obj_2\->file)
.Ve
.PP
\&\f(CW$obj_1\fRX\f(CW$obj_2\fR\s-1XXXX\s0\f(CW$path\fR\s-1XXXXXXXXXX\s0
.PP
\&\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXIDXXXXXXXXXXXXXXX
XXXXXXXXXXXX\s0
.SS "The Default Typemap"
.IX Subsection "The Default Typemap"
XXXXXXXXXXXXXXXXXXXXtypemapXXXXXXXX
\&\s-1XXXXXXXXCPANXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
\&\s0KiokuDB::TypeMap::Default\s-1XXXXXXXXXXX\s0
.SH "SIMPLE SEARCHES"
.IX Header "SIMPLE SEARCHES"
(\s-1XXXXX\s0)
.PP
\&\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\s0
.PP
\&\s-1XXAPIXXXXXXXX\s0KiokuDB::Backend::DBI\s-1XXXXXXXXXXXXXX\s0
XXXXXXSQLXwhereXXXXXXXXXXXXXXXXXXXXX
(\s-1XXXXXXXXXXXXXXXXXXXXXXXXXX\s0)
.PP
\&\f(CW\*(C`search\*(C'\fR\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXX\s0Data::Stream::Bulk\s-1XXXXXXXXXXXXX:\s0
.PP
.Vb 1
\&    my $stream = $dir\->search({ name => "Homer Simpson" });
\&
\&    while ( my $block = $stream\->next ) {
\&        foreach my $object ( @$block ) {
\&            # $object\->name eq "Homer Simpson"
\&       }
\&    }
.Ve
.PP
\&\s-1XXXAPIXXXXXXXXXXXXXXXXXX\s0DBIx::Class 0.09XXXXXXXX
\&\s-1XXXXXXXXXXX\s0
.SS "\s-1DBI SEARCH COLUMNS\s0"
.IX Subsection "DBI SEARCH COLUMNS"
\&\s-1XXXXXXXAPIXXXXXXDBIXXXXXXXXXXXXXXXXXXXXXXXX\s0
.PP
\&\s-1XXXXXXXX\s0'name'\s-1XXXXXXXXXX:\s0
.PP
.Vb 5
\&    my $dir = KiokuDB\->connect(
\&        "dbi:SQLite:dbname=foo",
\&        columns => [
\&            # specify extra columns for the \*(Aqentries\*(Aq table
\&            # in the same format you pass to DBIC\*(Aqs add_columns
\&
\&            name => {
\&                data_type => "varchar",
\&                is_nullable => 1, # probably important
\&            },
\&        ],
\&    );
.Ve
.PP
\&\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\s0\f(CW\*(C`kioku dump\*(C'\fR\s-1XXXX
XXXXXXXXXXX\s0\f(CW\*(C`create => 1\*(C'\fR\s-1XXXXX\s0\f(CW\*(C`kioku load\*(C'\fR\s-1XXXXXXXXXXX\s0
.PP
XXXXXXXXXXXXXXHomerXXXXXXXXXXXXXXXXXX:
.PP
.Vb 4
\&    {
\&        my $s = $dir\->new_scope;
\&        $dir\->update( $dir\->lookup( $homer_id ) );
\&    }
.Ve
.PP
\&\s-1XXXXXXXXXXXXXXXXX:\s0
.PP
.Vb 2
\&       id = 201C5B55\-E759\-492F\-8F20\-A529C7C02C8B
\&     name = Homer Simpson
.Ve
.SH "GETTING STARTED WITH BDB"
.IX Header "GETTING STARTED WITH BDB"
(\s-1BDBXXXXX\s0)
.PP
KiokuDB\s-1XXXXXXXXXXXXXXXXX\s0KiokuDB::Backend::DBD\s-1XX\s0(XX:DBIXXXXXXXXXXXYAPC::Asia 2009XXXXXX)X
\&\s-1XXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
\&\s0Search::GIN\s-1XXXXXXXXXXXXXXXXXXX\s0
.PP
KiokuDB::Backend::DBI\s-1XXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXX\s0Search::GIN\s-1XXXXXX
XXXXXXXXXXXXXXXXXXX\s0KiokuDB::Backend::BDB\s-1XXXXXXXXXXXXXX
\&\s0(XX:YAPC::Asia 2009XXXXXXXXXXXXXXXX)
.SS "Installing KiokuDB::Backend::BDB"
.IX Subsection "Installing KiokuDB::Backend::BDB"
KiokuDB::Backend::BDB\s-1XX\s0BerkeleyDB\s-1XXXXXXXXXXX\s0
XXXXXXXXXXXXBerkeley DBXXXXXXXXBerkeley \s-1DBXXXXXURLXXXXXX
\&\s0<http://www.oracle.com/technology/software/products/berkeley\-db/db/index.html>.
.PP
BerkeleyDB(\s-1XXXXX\s0)XXXX\f(CW\*(C`/usr/local/BerkeleyDB.4.7\*(C'\fR\s-1XXXXXXXXXXXX
XXXX\s0BerkeleyDB(\s-1XXXXX\s0)XX\f(CW\*(C`/usr/local/BerkeleyDB\*(C'\fR\s-1XXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\s0
.PP
BerkeleyDB\s-1XXXXXXXXXXXX\s0KiokuDB::Backend::BDB\s-1XXXXXXXXXXXXXXXXXXX
\&\s0KiokuDB\s-1XXXXXXXXXXXXXX\s0
.SS "Using KiokuDB::Backend::BDB"
.IX Subsection "Using KiokuDB::Backend::BDB"
\&\s-1BDBXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXX\s0\f(CW\*(C`create\*(C'\fR\s-1XXXXXXXXXXXXXXXX\s0
.PP
.Vb 6
\&    my $backend = KiokuDB::Backend::BDB\->new(
\&        manager => {
\&            home   => Path::Class::Dir\->new(qw(path to storage)),
\&            create => 1,
\&        },
\&    );
.Ve
.PP
\&\s-1BDBXXXXXXXX\s0BerkeleyDB::Manager\s-1XXXXXXXXXX\s0BerkeleyDB\s-1XXXXXXXXXX
\&\s0BerkeleyDB::Manager\s-1XXXXXXX\s0\f(CW\*(C`manager\*(C'\fR\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXX\s0
.PP
\&\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\s0
.PP
.Vb 1
\&    my $dir = KiokuDB\->new( backend => $backend );
.Ve
.PP
\&\s-1XXXXXXXXXXX\s0\f(CW\*(C`create\*(C'\fR\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\s0
.PP
\&\s-1XX\s0\f(CW\*(C`connect\*(C'\fR\s-1XXXXXXXXXXX:\s0
.PP
.Vb 1
\&    my $dir = KiokuDB\->connect( "bdb:dir=path/to/storage", create => 1 );
.Ve
.SH "TRANSACTIONS"
.IX Header "TRANSACTIONS"
(\s-1XXXXXXXX\s0)
.PP
\&\s-1XXXXXXXXXXX\s0(KiokuDB::Backend::Role::TXN\s-1XXXXXXXX\s0)XXXXXXXXXXXXXXXXXXXXXX
.PP
DBIx::Class\s-1XXXXXXXXXXXXXXXXXX:\s0
.PP
.Vb 3
\&    $dir\->txn_do(sub {
\&        $dir\->store($obj);
\&    });
.Ve
.PP
BerkeleyDB\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXX\s0
.PP
\&\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXX\s0
.PP
KiokuDB\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\s0
.PP
.Vb 2
\&    $dir\->txn_do(sub {
\&        my $scope = $dir\->new_scope;
\&
\&        $obj\->name("Dancing Hippy");
\&        $dir\->store($obj);
\&
\&        die "an error";
\&    });
.Ve
.PP
\&\f(CW\*(C`name\*(C'\fR\s-1XXXXXXXXX\s0\fB\s-1XXXXX\s0\fRX\f(CW\*(C`store\*(C'\fR\s-1XXXXXXXXXXXXXXXXXX\s0
.PP
\&\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXX\s0
.SH "QUERIES"
.IX Header "QUERIES"
(\s-1XXX\s0)
.PP
KiokuDB::Backend::BDB::GINXKiokuDB::Backend::BDB\s-1XXXXXXXX
\&\s0Serach::GIN\s-1XXXXXXXXXXXXXXXXXX\s0
.PP
Search::GIN\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXX\s0
PostgresXXXGIN apiXXXXXXXXXXXXX
GINXXGeneralized Inverted Indexes(\s-1XX:XXXXXX\s0)XXXXX
.PP
Search::GIN\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXXXXXXX\s0
.PP
\&\s-1XXXX\s0Search::GIN\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
\&\s0Search::GIN::Extract::Callback \s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:\s0
.PP
.Vb 5
\&    my $dir = KiokuDB\->new(
\&        backend => KiokuDB::Backend::BDB::GIN\->new(
\&            extract => Search::GIN::Extract::Callback\->new(
\&                extract => sub {
\&                    my ( $obj, $extractor, @args ) = @_;
\&
\&                    if ( $obj\->isa("Person") ) {
\&                        return {
\&                            type => "user",
\&                            name => $obj\->name,
\&                        };
\&                    }
\&
\&                    return;
\&                },
\&            ),
\&        ),
\&    );
\&
\&    $dir\->store( @random_objects );
.Ve
.PP
\&\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:\s0
.PP
.Vb 5
\&    my $query = Search::GIN::Query::Manual\->new(
\&        values => {
\&            type => "person",
\&        },
\&    );
\&
\&    my $stream = $dir\->search($query);
.Ve
.PP
\&\s-1XXXXXXXXXXXXX\s0Data::Stream::Bulk\s-1XXXXXXXXXXXX
XXXXXXXXXXXXXXX\s0
.PP
.Vb 5
\&    while ( my $block = $stream\->next ) {
\&        foreach my $person ( @$block ) {
\&            print "found a person: ", $person\->name;
\&        }
\&    }
.Ve
.PP
\&\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:\s0
.PP
.Vb 1
\&    my @people = $stream\->all;
.Ve
.PP
Search::GIN\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXX
XXXXXXXXXXXXXXXXXXXXX\s0Search::GIN::Extract::Class\s-1XXXX
XXXXXXXXXXXXXX\s0
.PP
\&\s-1XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\s0
.SH "XXXXXX"
.IX Header "XXXXXX"
\&\s-1XXXXXXX \s0(ktat@cpan.org)
.PP
PerlXXXXXXXXXX Project \s-1XXX\s0
PerlXXXXXXXXXXXXXXXXXXXXXXXX
.PP
.Vb 4
\& http://perldocjp.sourceforge.jp/
\& http://sourceforge.jp/projects/perldocjp/
\& http://www.freeml.com/ctrl/html/MLInfoForm/perldocjp@freeml.com
\& http://www.perldoc.jp/
.Ve