The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Mango-0.001_01
River stage two • 9 direct dependents • 10 total dependents
43 ++
/ Mango::Document::Sugar

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 object

embed

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 toys

file

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 brain

index

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 set

is_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.