NAME
    MongoX - DSL sugar for MongoDB

VERSION
    version 0.004

SYNOPSIS
        # quick bootstrap, add connection and switch to db:'test'
        use MongoX ( host => 'mongodb://127.0.0.1',db => 'test' );

        # common way
        use MongoX;
        #register default connection;
        add_connection host => '127.0.0.1';
        # switch to default connection;
        use_connection;
        # use database 'test'
        use_db 'test';
    
        #add/register another connection with id "remote2"
        add_connection host => '192.168.1.1',id => 'remote2';
    
        # switch to this connection
        use_connection 'remote2';
    
        #get a collection object (from the db in current context)
        my $foo = get_collection 'foo';
    
        # use 'foo' as default context collection
        use_collection 'foo';
    
        # use context's db/collection
        say 'total rows:',context_collection->count();
    
        my $id = context_collection->insert({ name => 'Pan', home => 'Beijing' });
        my $gridfs = context_db->get_gridfs;
    
        # loop dbs/collections
        for_dbs{
            for_collections {
                db_ensure_index {created_on => 1};
            } context_db->collection_names;
        } 'db1','db2';

DESCRIPTION
    MongoX is a light wrapper to MongoDB driver, it provide a very simple
    but handy DSL syntax. It also will provide some usefull helpers like
    builtin mongoshell, you can quick work with MongoDB.

OVERVIEW
    MongoX takes a set of options for the class construction at compile time
    as a HASH parameter to the "use" line.

    As a convenience, you can pass the default connection parameters and
    default database, then when MongoX import, it will apply these options
    to "add_connection" and "use_db", so the following code:

        use MongoX ( host => 'mongodb://127.0.0.1',db => 'test' );

    is equivalent to:

        use MongoX;
        add_connection host => 'mongodb://127.0.0.1';
        use_connection;
        use_db 'test';

    "context_connection","context_db", "context_collection" are implicit
    MongoDB::Connection, MongoDB::Database and MongoDB::Collection.

  Options
    host => mongodb server, mongodb connection scheme
    db => default database
    utf8 => Turn on/off UTF8 flag. default is turn on utf8 flag.

  DSL keywords
    use_connection
    use_db
    use_collection
    with_context

    use_* keywords can make/switch implicit MongoDB object in context.

    with_context allow build a sanbox to execute code block and do
    something, the context be restored when out the block.

    for_connections
    for_dbs
    for_collections

    These are loop keywords, it will switch related context object in the
    given list and loop run the code block.

ATTRIBUTES
  context_db
        my $db = context_db;

    Return current MongoDB::Database object in context;

  context_connection
        my $con = context_connection;

    Return current MongoDB::Connection object in context.

  context_collection
        my $col = context_collection;

    Return current MongoDB::Collection object in context, you can replace
    the object with "use_collection".

METHODS
  use_connection
        # create a default connection
        use_connection;
        # use another connection with id:'con2'
        use_connection 'con2';

    Switch to given connection, set the context connection to this
    connection.

  use_db
        use_db 'foo';

    Switch to the database, set the context database to this database;

  use_collection
        use_collection 'user'

    Set 'user' collection as context collection.

  add_connection
        add_connection id => 'default', host => 'mongodb://127.0.0.1:27017'

    Register a connnection with the id, if omit, will add as default
    connection. All options exclude 'id' will direct pass to
    MongoDB::Connection. The host accept standard mongoDB uri scheme:

    mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:p
    ortN]]][/database]

    More about, see <http://www.mongodb.org/display/DOCS/Connections>.

  boot
        boot host => 'mongodb://127.0.0.1',db => 'test'
        # same as:
        add_connection host => 'mongodb://127.0.0.1', id => 'default';
        use_connection;
        use_db 'test';

    Boot is equivalent to call add_connection,use_connection,use_db.

  with_context BLOCK db => 'dbname', connection => 'connection_id', collection => 'foo'
        # sandbox
        use_db 'test';
        with_context {
            use_db 'tmp_db';
            # now context db is 'tmp_db'
            ...
        };
        # context db auto restor to 'test'
    
        # temp context
        with_context {
            context_collection->do_something;
        } connection => 'id2', db => 'test2', 'collection' => 'user';
    
        # alternate style
        my $db2 = context_connection->get_database('test2');
        with_context {
            # context db is $db2,collection is 'foo'
            print context_collection->count;
        } db => $db2, 'collection' => 'foo';

    "with_context" let you create a temporary context(sandbox) to invoke the
    code block. Before execute the code block, current context will be
    saved, them build a temporary context to invoke the code, after code
    executed, saved context will be restored.

    You can explicit setup the sandbox context include
    connection,db,collection, or just applied from parent
    container(context).

    with_context allow nested, any with_context will build its context
    sanbox to run the attached code block.

        use_db 'test';

        with_context {
            # context db is 'db1'
            with_context {
                # context db is 'db2'
            } db => 'db2';
            # context db restore to 'db1'
        } db => 'db1';

        # context db restore to 'test'

    with_context options key:

    connection => connection id or MongoDB::Connection
    db => database name or MongoDB::Database
    collection => collection name or MongoDB::Collection

  for_dbs BLOCK, database List
        for_dbs {
            print context_db->name;
        } 'test1','test2','test3;

        for_dbs {

            print context_db->name;

        } context_connection->database_names;

    Evaluates the code BLOCK for each database of the list. In block scope,
    context_db will switch to the list value, and $_ is alias of this
    context_db value.

  for_connections BLOCK connection_id_list
        for_connections {
            for_dbs { map { print $_ } context_db->collection_names } $_->database_names;
        } 'con_id1', 'con_id2'

    Evaluates the code BLOCK against each connection of connection id list.
    In block scope, context_connection will switch to the list value, and $_
    is alais of the current context_connection.

  for_collections BLOCK collection_list
        # print out all collection's count in the db
        for_collections {
            say $_->name, ' count:', db_count;
        } context_db->collection_names;

        # reindex some collections
        for_collections { db_re_index } 'foo','foo2','foo3';

        # alternate
        for_collections { db_re_index } qw(foo foo2 foo3);
        # alternate
        for_collections { db_re_index } ('foo','foo2','foo3');

Repository
    Github: <http://github.com/nightsailer/mongo-x>

SEE ALSO
    MongoDB manual: <http://www.mongodb.org/display/DOCS/Manual>

    Official MongoDB driver: MongoDB or
    <http://github.com/mongodb/mongo-perl-driver>

    My fork: <http://github.com/nightsailer/mongo-perl-driver>

    My blog about this project (Chinese only!):
    <http://nightsailer.com/mongox>

AUTHOR
    Pan Fan(nightsailer) <nightsailer at gmail dot com>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2010 by Pan Fan(nightsailer).

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.