.\" 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 "MongoDBx::Class::Moose 3pm" .TH MongoDBx::Class::Moose 3pm "2014-02-04" "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" MongoDBx::Class::Moose \- Extends Moose with common relationships for MongoDBx::Class documents .SH "VERSION" .IX Header "VERSION" version 1.030002 .SH "PROVIDES" .IX Header "PROVIDES" Moose .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& # create a document class \& package MyApp::Schema::Novel; \& \& use MongoDBx::Class::Moose; # use this instead of Moose; \& use namespace::autoclean; \& \& with \*(AqMongoDBx::Class::Document\*(Aq; \& \& has \*(Aqtitle\*(Aq => (is => \*(Aqro\*(Aq, isa => \*(AqStr\*(Aq, required => 1, writer => \*(Aqset_title\*(Aq); \& \& holds_one \*(Aqauthor\*(Aq => (is => \*(Aqro\*(Aq, isa => \*(AqMyApp::Schema::PersonName\*(Aq, required => 1, writer => \*(Aqset_author\*(Aq); \& \& has \*(Aqyear\*(Aq => (is => \*(Aqro\*(Aq, isa => \*(AqInt\*(Aq, predicate => \*(Aqhas_year\*(Aq, writer => \*(Aqset_year\*(Aq); \& \& has \*(Aqadded\*(Aq => (is => \*(Aqro\*(Aq, isa => \*(AqDateTime\*(Aq, traits => [\*(AqParsed\*(Aq], required => 1); \& \& holds_many \*(Aqtags\*(Aq => (is => \*(Aqro\*(Aq, isa => \*(AqMyApp::Schema::Tag\*(Aq, predicate => \*(Aqhas_tags\*(Aq); \& \& joins_one \*(Aqsynopsis\*(Aq => (is => \*(Aqro\*(Aq, isa => \*(AqSynopsis\*(Aq, coll => \*(Aqsynopsis\*(Aq, ref => \*(Aqnovel\*(Aq); \& \& has_many \*(Aqrelated_novels\*(Aq => (is => \*(Aqro\*(Aq, isa => \*(AqNovel\*(Aq, predicate => \*(Aqhas_related_novels\*(Aq, writer => \*(Aqset_related_novels\*(Aq, clearer => \*(Aqclear_related_novels\*(Aq); \& \& joins_many \*(Aqreviews\*(Aq => (is => \*(Aqro\*(Aq, isa => \*(AqReview\*(Aq, coll => \*(Aqreviews\*(Aq, ref => \*(Aqnovel\*(Aq); \& \& sub print_related_novels { \& my $self = shift; \& \& foreach my $other_novel ($self\->related_novels) { \& print $other_novel\->title, \*(Aq, \*(Aq, \& $other_novel\->year, \*(Aq, \*(Aq, \& $other_novel\->author\->name, "\en"; \& } \& } \& \& around \*(Aqreviews\*(Aq => sub { \& my ($orig, $self) = (shift, shift); \& \& my $cursor = $self\->$orig; \& \& return $cursor\->sort([ year => \-1, title => 1, \*(Aqauthor.last_name\*(Aq => 1 ]); \& }; \& \& _\|_PACKAGE_\|_\->meta\->make_immutable; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module provides some relationship types (i.e. database references) for MongoDB documents and embedded documents, in the form of Moose attributes. It also provides everything Moose provides, and so is to replace \f(CW\*(C`use Moose\*(C'\fR when creating document classes. .SH "RELATIONSHIP TYPES" .IX Header "RELATIONSHIP TYPES" This module provides the following relationship types. The differences between different relationships stem from the different ways in which references can be represented in the database. .SS "belongs_to" .IX Subsection "belongs_to" Specifies that the document has an attribute which references another, supposedly parent, document. The reference is in the form documented by MongoDBx::Class::Reference. .PP .Vb 1 \& belongs_to \*(Aqparent\*(Aq => (is => \*(Aqro\*(Aq, isa => \*(AqArticle\*(Aq, required => 1) .Ve .PP In the database, this relationship is represented in the referencing document like this: .PP .Vb 1 \& { ... parent => { \*(Aq$ref\*(Aq => \*(Aqcoll_name\*(Aq, \*(Aq$id\*(Aq => $mongo_oid } ... } .Ve .PP Calling \f(CW\*(C`parent()\*(C'\fR on the referencing document returns the parent document after expansion: .PP .Vb 1 \& $doc\->parent\->title; .Ve .SS "has_one" .IX Subsection "has_one" Specifies that the document has an attribute which references another document. The reference is in the form documented by MongoDBx::Class::Reference. This is entirely equivalent to \*(L"belongs_to\*(R", the two are provided merely for convenience, the difference is purely semantic. .SS "has_many" .IX Subsection "has_many" Specifies that the document has an attribute which holds a list (array) of references to other documents. These references are in the form documented by MongoDBx::Class::Reference. .PP .Vb 1 \& has_many \*(Aqrelated_articles\*(Aq => (is => \*(Aqro\*(Aq, isa => \*(AqArticle\*(Aq, predicate => \*(Aqhas_related_articles\*(Aq) .Ve .PP In the database, this relationship is represented in the referencing document like this: .PP .Vb 1 \& { ... related_articles => [{ \*(Aq$ref\*(Aq => \*(Aqcoll_name\*(Aq, \*(Aq$id\*(Aq => $mongo_oid_1 }, { \*(Aq$ref\*(Aq => \*(Aqother_coll_name\*(Aq, \*(Aq$id\*(Aq => $mongo_oid_2 }] ... } .Ve .PP Calling \f(CW\*(C`related_articles()\*(C'\fR on the referencing document returns an array of all referenced documents, after expansion: .PP .Vb 3 \& foreach ($doc\->related_articles) { \& print $_\->title, "\en"; \& } .Ve .SS "holds_one" .IX Subsection "holds_one" Specifies that the document has an attribute which holds an embedded document (a.k.a sub-document) in its entirety. The embedded document is represented by a class that \f(CW\*(C`does\*(C'\fR MongoDBx::Class::EmbeddedDocument. .PP .Vb 1 \& holds_one \*(Aqauthor\*(Aq => (is => \*(Aqro\*(Aq, isa => \*(AqMyApp::Schema::PersonName\*(Aq, required => 1) .Ve .PP Note that the \f(CW\*(C`holds_one\*(C'\fR relationship has the unfortunate constraint of having to pass the full package name of the foreign document (e.g. MyApp::Schema::PersonName above), whereas other relationship types (except \f(CW\*(C`holds_many\*(C'\fR which has the same constraint) require the class name only (e.g. Novel). .PP In the database, this relationship is represented in the referencing (i.e. holding) document like this: .PP .Vb 1 \& { ... author => { first_name => \*(AqArthur\*(Aq, middle_name => \*(AqConan\*(Aq, last_name => \*(AqDoyle\*(Aq } ... } .Ve .PP Calling \f(CW\*(C`author()\*(C'\fR on the referencing document returns the embedded document, after expansion: .PP .Vb 1 \& $doc\->author\->first_name; # returns \*(AqArthur\*(Aq .Ve .SS "holds_many" .IX Subsection "holds_many" Specifies that the document has an attribute which holds a list (array) of embedded documents (a.k.a sub-documents) in their entirety. These embedded documents are represented by a class that \f(CW\*(C`does\*(C'\fR MongoDBx::Class::EmbeddedDocument. .PP .Vb 1 \& holds_many \*(Aqtags\*(Aq => (is => \*(Aqro\*(Aq, isa => \*(AqMyApp::Schema::Tag\*(Aq, predicate => \*(Aqhas_tags\*(Aq) .Ve .PP Note that the \f(CW\*(C`holds_many\*(C'\fR relationship has the unfortunate constraint of having to pass the full package name of the foreign document (e.g. MyApp::Schema::Tag above), whereas other relationship types (except \f(CW\*(C`holds_one\*(C'\fR which has the same constraint) require the class name only (e.g. Novel). .PP In the database, this relationship is represented in the referencing (i.e. holding) document like this: .PP .Vb 1 \& { ... tags => [ { category => \*(Aqmystery\*(Aq, subcategory => \*(Aqthriller\*(Aq }, { category => \*(Aqmystery\*(Aq, subcategory => \*(Aqdetective\*(Aq } ] ... } .Ve .SS "defines_many" .IX Subsection "defines_many" Specifies that the document has an attribute which holds a hash (a.k.a associative array or dictionary) of embedded documents in their entirety. These embedded documents are represented by a class that \f(CW\*(C`does\*(C'\fR MongoDBx::Class::EmbeddedDocument. .PP .Vb 1 \& defines_many \*(Aqthings\*(Aq => (is => \*(Aqro\*(Aq, isa => \*(AqMyApp::Schema::Thing\*(Aq, predicate => \*(Aqhas_things\*(Aq); .Ve .PP When calling \f(CW\*(C`things()\*(C'\fR on a document, a hash-ref is returned (not a hash!). .PP Like \f(CW\*(C`holds_many\*(C'\fR and \f(CW\*(C`holds_one\*(C'\fR, this relationship has the unfortunate constraint of having to pass the full package name of the foreign document (e.g. MyApp::Schema::Thing above), whereas other relationship types require the class name only (e.g. Novel). .PP In the database, this relationship is represented in the referencing (i.e. holding) document like this: .PP .Vb 8 \& { ... \& things => { \& "mine" => { _class => \*(AqMyApp::Schema::Thing\*(Aq, ... }, \& "his" => { _class => \*(AqMyApp::Schema::Thing\*(Aq, ... }, \& "hers" => { _class => \*(AqMyApp::Schema::Thing\*(Aq, ... }, \& } \& ... \& } .Ve .SS "joins_one" .IX Subsection "joins_one" Specifies that the document is referenced by one other document. The reference in the other document to this document is in the form documented by MongoDBx::Class::Reference. This \*(L"pseudo-attribute\*(R" requires two new options: 'coll', with the name of the collection in which the referencing document is located, and 'ref', with the name of the attribute which is referencing the document. If 'coll' isn't provided, the referencing document is searched in the same collection. .PP .Vb 1 \& joins_one \*(Aqsynopsis\*(Aq => (is => \*(Aqro\*(Aq, isa => \*(AqSynopsis\*(Aq, coll => \*(Aqsynopsis\*(Aq, ref => \*(Aqnovel\*(Aq) .Ve .PP In the database, this relationship is represented in the referencing document (located in the 'synopsis' collection) like this: .PP .Vb 1 \& { ... novel => { \*(Aq$ref\*(Aq => \*(Aqnovels\*(Aq, \*(Aq$id\*(Aq => $mongo_oid } ... } .Ve .PP When calling \f(CW\*(C`synopsis()\*(C'\fR on a Novel document, a \f(CW\*(C`find_one()\*(C'\fR query is performed like so: .PP .Vb 1 \& $db\->get_collection(\*(Aqsynopsis\*(Aq)\->find_one({ \*(Aqnovel.$id\*(Aq => $doc\->_id }) .Ve .PP Note that passing a 'required' option to \f(CW\*(C`joins_one\*(C'\fR has no effect at all, the existence of the referencing document is never enforced, so \f(CW\*(C`undef\*(C'\fR can be returned. .SS "joins_many" .IX Subsection "joins_many" Specifies that the document is referenced by other documents. The references in the other document to this document are in the form documented by MongoDBx::Class::Reference. This \*(L"pseudo-attribute\*(R" requires two new options: 'coll', with the name of the collection in which the referencing documents are located, and 'ref', with the name of the attribute which is referncing the document. If 'coll' isn't provided, the referencing documents are searched in the same collection. .PP .Vb 1 \& joins_many \*(Aqreviews\*(Aq => (is => \*(Aqro\*(Aq, isa => \*(AqReview\*(Aq, coll => \*(Aqreviews\*(Aq, ref => \*(Aqnovel\*(Aq) .Ve .PP In the database, this relationship is represented in the referencing documents (located in the 'reviews' collection) like this: .PP .Vb 1 \& { ... novel => { \*(Aq$ref\*(Aq => \*(Aqnovels\*(Aq, \*(Aq$id\*(Aq => $mongo_oid } ... } .Ve .PP When calling \f(CW\*(C`reviews()\*(C'\fR on a Novel document, a \f(CW\*(C`find()\*(C'\fR query is performed like so: .PP .Vb 1 \& $db\->get_collection(\*(Aqreviews\*(Aq)\->find({ \*(Aqnovel.$id\*(Aq => $doc\->_id }) .Ve .PP And thus a MongoDBx::Class::Cursor is returned. .PP Note that passing the 'required' option to \f(CW\*(C`joins_many\*(C'\fR has no effect at all, and the existance of referncing documents is never enforced, so the cursor can have a count of zero. .SH "AUTHOR" .IX Header "AUTHOR" Ido Perlmuter, \f(CW\*(C`\*(C'\fR .SH "BUGS" .IX Header "BUGS" Please report any bugs or feature requests to \f(CW\*(C`bug\-mongodbx\-class at rt.cpan.org\*(C'\fR, or through the web interface at . I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. .SH "SUPPORT" .IX Header "SUPPORT" You can find documentation for this module with the perldoc command. .PP .Vb 1 \& perldoc MongoDBx::Class::Moose .Ve .PP You can also look for information at: .IP "\(bu" 4 \&\s-1RT: CPAN\s0's request tracker .Sp .IP "\(bu" 4 AnnoCPAN: Annotated \s-1CPAN\s0 documentation .Sp .IP "\(bu" 4 \&\s-1CPAN\s0 Ratings .Sp .IP "\(bu" 4 Search \s-1CPAN\s0 .Sp .SH "SEE ALSO" .IX Header "SEE ALSO" MongoDBx::Class::Document, MongoDBx::Class::EmbeddedDocument, Moose. .SH "LICENSE AND COPYRIGHT" .IX Header "LICENSE AND COPYRIGHT" Copyright 2010\-2014 Ido Perlmuter. .PP This program is free software; you can redistribute it and/or modify it under the terms of either: the \s-1GNU\s0 General Public License as published by the Free Software Foundation; or the Artistic License. .PP See http://dev.perl.org/licenses/ for more information.