NAME
Mango::Document::Sugar - Syntactic Sugar For Defining Mango Document Classes
VERSION
version 0.001_01
SYNOPSIS
package Child;
use Mango::Document;
store 'children';
key 'ssn', is_id, is_req; # unique index, auto-incrementing
key 'full_name', is_str, is_req;
embed 'goals', class => 'Child::Goal', type => 'multiple';
belongs_to 'mom', class => 'Child::Parent';
has_one 'best_friend', class => 'Child::Friend';
has_many 'ideas', class => 'Child::Idea';
1;DESCRIPTION
Mango::Document::Sugar provides the DSL (domain-specific-language) used to define your Moose-based MongoDB document classes. It is important to note that the underlying structure of your class is provided by Moose and you can and should capitalize on this in the development of your classes.
EXPORTS
belongs_to
The belongs_to keyword is a relationship identifier that creates a 1-1 (one-to-one) relationship between the current class and the class specified by the required class attribute. This is accomplished by wrapping the class specified by the class attribute with a Mango::Document::Relative instance. Please read the documentation at Mango::Document::Relative for more information on using this object.
package Child;
use Mango::Document;
belongs_to 'father', class => 'Father';
belongs_to 'mother', class => 'Mother';
package main;
my $child = Child->new(...);
$child->father->add(...); # see M::D::Relative for more info
# embed can't append an array, this replaces old dad with a new dad
$child->father->add(...);
$child->mother->add(...);config
The config keyword provides direct access to the configuration object which includes functionality from Mango::Document::Config. You will most likely never need to make use of this keyword within your application classes. This keyword should not be confused with the config method with which you will likely use to configure your database connection, made available via Mango::Document::Base.
package main;
my $config = Child->config; # direct access to the configuration objectembed
The embed keyword is a relationship identifier that creates a 1<->1 (one-to-one - document-in-document) relationship between the current class and the class specified by the required class attribute. This is accomplished by wrapping the class specified by the class attribute with a Mango::Document::Child instance. Please read the documentation at Mango::Document::Child for more information on using this object.
The embed keyword can be provided an optional argument ("multiple") that if true will instruct the relationship management class (M::D::Child) to allow an array of objects to be created, ... otherwise calling the add method a second time will simply replace the existing object.
package Child;
use Mango::Document;
embeds 'room', class => 'Child::Room';
embeds 'toys', class => 'Child::Toy', multiple => 1;
package main;
my $child = Child->new(...);
$child->room->add(...); # assign a room to the child
$child->toys->add(...);
$child->toys->add(...);
$child->toys->add(...); # a child with three toysfile
The file keyword is a relationship identifier that creates a 1-1 (one-to-one) relationship between the current class and file stored within the MongoDB GridFS. This is accomplished by wrapping the specified attribute with a Mango::Document::GridFile instance. Please read the documentation at Mango::Document::GridFile for more information on using this object.
The file keyword can be provided an optional argument ("multiple") that if true will instruct the relationship management class (M::D::GridFile) to allow an array of file objects to be created, ... otherwise calling the add method a second time will simply replace the existing file object.
package Child;
use Mango::Document;
file 'photo';
package main;
my $child = Child->new(...);
$child->photo->add($file_path, ...); # attach a photo to the child record
# file can append an array if multiple arg is set, else replaces
$child->photo->add($file_path, ...); filter
The filter keyword registers class related filters for quickly composing a chainable Mango::Document::Storage::Criterion search object which is the main Mango query abstraction layer. Please see the documentation available with Mango::Document::Storage::Criterion for more information on querying.
package Child;
use Mango::Document;
filter 'is_in_school' => sub {
shift->where('school.name' => qr/./);
};
filter 'is_under_age' => sub {
shift->where('age$lt' => 21);
};
filter 'is_something_special' => sub {
my ($filter, $self, @args) = @_;
...
};
package main;
# search made simple
my $results = Child->search('is_under_age', 'is_in_school')->query;
while (my $child = $results->next) {
...
}has_many
The has_many keyword is a relationship identifier that creates a 1-* (one-to-many) relationship between the current class and the class specified by the required class attribute. This is accomplished by wrapping the class specified by the class attribute with a Mango::Document::Relative instance. Please read the documentation at Mango::Document::Relative for more information on using this object.
package Child;
use Mango::Document;
has_many 'sisters', class => 'Child::Sibling';
has_many 'brothers', class => 'Child::Sibling';
package main;
my $child = Child->new(...);
$child->sisters->add(...); # see M::D::Relative for more info
$child->sisters->add(...); # has_many can append an array
$child->sisters->add(...);
$child->brothers->add(...);has_one
The has_one keyword is a relationship identifier that creates a 1-1 (one-to-one) relationship between the current class and the class specified by the required class attribute. This is accomplished by wrapping the class specified by the class attribute with a Mango::Document::Relative instance. Please read the documentation at Mango::Document::Relative for more information on using this object.
package Child;
use Mango::Document;
has_one 'brain', class => 'Child::Brain';
package main;
my $child = Child->new(...);
$child->brain->add(...); # give the child a brain
$child->brain->add(...); # replace the child's brainindex
The index keyword queues-up an index rule to be executed when a connection to the database is made. The index method will intelligently separate your fields and option arguments. Please try to avoid using "name" as a field (indexing a field label "name" will not function properly).
package Child;
use Mango::Document;
key 'first_name';
key 'last_name';
index first_name => 1, last_name => -1, unique => 1;
package main;
my $child = Child;
$child->config->set_database('test');
$child->connect; # indexes are now setis_any
The is_any keyword is Moose attribute shorthand for the following:
package Child;
use Mango::Document;
key 'first_name', is_any;
# is the equivalent of:
key 'first_name' => (
is => 'rw',
isa => 'Any'
);
# overwrite the default access attribute
key 'first_name', is_any is => 'ro';is_array
The is_array keyword is Moose attribute shorthand for the following:
package Child;
use Mango::Document;
key 'favorite_movies', is_array;
# is the equivalent of:
key 'favorite_movies' => (
is => 'rw',
isa => 'Array'
);
# overwrite the default access attribute
key 'favorite_movies', is_array is => 'ro';is_bool
The is_bool keyword is Moose attribute shorthand for the following:
package Child;
use Mango::Document;
key 'attending_school', is_bool;
# is the equivalent of:
key 'attending_school' => (
is => 'rw',
isa => 'Bool'
);
# overwrite the default access attribute
key 'attending_school', is_bool is => 'ro';is_date
The is_date keyword is Moose attribute shorthand for the following:
package Child;
use Mango::Document;
key 'date_of_birth', is_date;
# is the equivalent of:
key 'date_of_birth' => (
is => 'rw',
isa => 'DateTime'
);
# overwrite the default access attribute
key 'date_of_birth', is_date is => 'ro';is_hash
The is_hash keyword is Moose attribute shorthand for the following:
package Child;
use Mango::Document;
key 'facebook_stream', is_hash;
# is the equivalent of:
key 'facebook_stream' => (
is => 'rw',
isa => 'HashRef'
);
# overwrite the default access attribute
key 'facebook_stream', is_hash is => 'ro';is_id
The is_id keyword is Moose attribute shorthand for the following:
package Child;
use Mango::Document;
key 'student_id', is_id;
# is the equivalent of:
key 'student_id' => (
is => 'rw',
isa => 'MongoDB::OID'
);
# overwrite the default access attribute
key 'student_id', is_id is => 'ro', default => sub { ... };is_inc
The is_inc keyword is Moose attribute shorthand for the following:
package Child;
use Mango::Document;
key 'child_id', is_inc;
# is the equivalent of:
key 'child' => (
is => 'rw',
isa => 'Int',
lazy => 1,
default => sub {
... # count documents + 1
}
);is_int
The is_int keyword is Moose attribute shorthand for the following:
package Child;
use Mango::Document;
key 'student_id', is_int;
# is the equivalent of:
key 'student_id' => (
is => 'rw',
isa => 'Int'
);
# overwrite the default access attribute
key 'student_id', is_int is => 'ro';is_num
The is_num keyword is Moose attribute shorthand for the following:
package Child;
use Mango::Document;
key 'school_dues', is_num;
# is the equivalent of:
key 'school_dues' => (
is => 'rw',
isa => 'Num'
);
# overwrite the default access attribute
key 'school_dues', is_num is => 'ro';is_req
The is_req keyword is Moose attribute shorthand for the following:
package Child;
use Mango::Document;
key 'ssn', is_req;
# is the equivalent of:
key 'ssn' => (
is => 'rw',
isa => 'Str', # unless an additional type shorthand is used
required => 1
);
# overwrite the default access attribute
key 'ssn', is_req is => 'ro';
# combine attribute shorthands
key 'ssn', is_req, is_num;is_str
The is_str keyword, used by default if no other type shorthand is given, is Moose attribute shorthand for the following:
package Child;
use Mango::Document;
key 'nickname', is_str;
# is the equivalent of:
key 'nickname' => (
is => 'rw',
isa => 'Str'
);
# overwrite the default access attribute
key 'nickname', is_str is => 'ro';is_unique
The is_unique keyword simply signals the key keyword to create a unique ascending index (with drop_dups on) on the associated field. The following is an example.
package Child;
use Mango::Document;
key 'ssn', is_num, is_unique;
# is the equivalent of:
key 'ssn' => (
is => 'rw',
isa => 'Num'
);
index 'ssn' => 1, unique => 1, drop_dups => 1;key
The key keyword operates much in the same way the Moose has() method does with the added behavior of registering the field in the class's configuration for later use by Mango.
The key and has keywords can be used side-by-side ... with the understanding that the Moose has() method doesn't register a Mango field so when expanding and collapsing data (which occurs in practically ever method that interacts with the database) happens the field/attribute create by the Moose has() method will not be saved to the database.
The key keyword accepts all key/values pairs that its Moose counterpart does and the following is an example of that:
package Child;
use Mango::Document;
key 'first_name', is_req;
key 'last_name', is_req;
key 'nickname' => (
is => 'rw',
isa => 'Str'
);
has 'skill_level' => (
is => 'rw',
isa => 'Num'
);
key 'attitude', is_int, default => 1;store
The store keyword sets the MongoDB collection name for the current class, it accepts the same parameters allowed by the set_collection() method in the Mango::Document::Config module. The following is an example of that:
package Child;
use Mango::Document;
store 'children';AUTHORS
Al Newkirk <awncorp@cpan.org>
Robert Grimes <buu@erxz.com>
COPYRIGHT AND LICENSE
This software is copyright (c) 2012 by awncorp.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.