NAME
   MQUL - General purpose, MongoDB-style query and update language

VERSION
   version 0.002

SYNOPSIS
           use MQUL qw/doc_matches update_doc/;

           my $doc = {
                   title => 'Freaks and Geeks',
                   genres => [qw/comedy drama/],
                   imdb_score => 9.4,
                   seasons => 1,
                   starring => ['Linda Cardellini', 'James Franco', 'Jason Segel'],
           };

           if (doc_matches($doc, {
                   title => qr/geeks/i,
                   genres => 'comedy',
                   imdb_score => { '$gte' => 5, '$lte' => 9.5 },
                   starring => { '$type' => 'array', '$size' => 3 },
           })) {
                   # will be true in this example
           }

           update_doc($doc, {
                   '$set' => { title => 'Greeks and Feaks' },
                   '$pop' => { genres => 1 },
                   '$inc' => { imdb_score => 0.6 },
                   '$unset' => { seasons => 1 },
                   '$push' => { starring => 'John Francis Daley' },
           });

           # $doc will now be:
           {
                   title => 'Greeks and Feaks',
                   genres => ['comedy'],
                   imdb_score => 10,
                   starring => ['Linda Cardellini', 'James Franco', 'Jason Segel', 'John Francis Daley'],
           }

DESCRIPTION
   MQUL (for MongoDB-style Query & Update Language; pronounced *"umm,
   cool"*; yeah, I know, that's the dumbest thing ever), is a general
   purpose implementation of MongoDB's query and update language. The
   implementation is not 100% compatible, but it only slightly deviates
   from MongoDB's behavior, actually extending it a bit.

   The module exports two functions: "doc_matches()" and "update_doc()".
   The first method takes a document, which is really just a hash-ref (of
   whatever complexity), and a query hash-ref built in the MQUL query
   language. The method will return a true value if the document matches
   the query, and a false value otherwise. The second method takes a
   document and an update hash-ref built in the MQUL update language. The
   method modifies the document (in-place) according to the update
   hash-ref.

   You can use this module for whatever purpose you see fit. It was
   actually written for Giddy, my Git-database, and was extracted from its
   original code. Outside of the database world, I plan to use it in an
   application that performs tests (such as process monitoring for
   example), and uses the query language to determine whether the results
   are valid or not (in our monitoring example, that could be CPU usage
   above a certain threshold and stuff like that).

 THE LANGUAGE
   The language itself is described in MQUL::Reference. This document only
   describes the interface of this module.

   The reference document also details MQUL's current differences from the
   original MongoDB language.

INTERFACE
 doc_matches( \%document, [ \%query ] )
   Receives a document hash-ref and possibly a query hash-ref, and returns
   true if the document matches the query, false otherwise. If no query is
   given (or an empty hash-ref is given), true will be returned (every
   document will match an empty query - in accordance with MongoDB).

   See "QUERY STRUCTURE" in MQUL::Reference to learn about the structure of
   query hash-refs.

 update_doc( \%document, \%update )
   Receives a document hash-ref and an update hash-ref, and updates the
   document in-place according to the update hash-ref. Also returns the
   document after the update. If the update hash-ref doesn't have any of
   the update modifiers described by the language, then the update hash-ref
   is considered as what the document should now be, and so will simply
   replace the document hash-ref (once again, in accordance with MongoDB).

   See "UPDATE STRUCTURE" in MQUL::Reference to learn about the structure
   of update hash-refs.

DIAGNOSTICS
   "MQUL::doc_matches() requires a document hash-ref."
       This error means that you've either haven't passed the
       "doc_matches()" method any parameters, or given it a non-hash-ref
       document.

   "MQUL::doc_matches() expects a query hash-ref."
       This error means that you've passed the "doc_matches()" attribute a
       non-hash-ref query variable. While you don't actually have to pass a
       query variable, if you do, it has to be a hash-ref.

   "MQUL::update_doc() requires a document hash-ref."
       This error means that you've either haven't passed the
       "update_doc()" method any parameters, or given it a non-hash-ref
       document.

   "MQUL::update_doc() requires an update hash-ref."
       This error means that you've passed the "update_doc()" method a
       non-hash-ref update variable.

   "The %s attribute is not an array in the doc."
       This error means that your update hash-ref tries to modify an array
       attribute (with $push, $pushAll, $addToSet, $pull, $pullAll, $pop,
       $shift and $splice), but the attribute in the document provided to
       the "update_doc()" method is not an array.

CONFIGURATION AND ENVIRONMENT
   MQUL requires no configuration files or environment variables.

DEPENDENCIES
   MQUL depends on the following modules:

   *   Data::Compare

   *   Data::Types

   *   DateTime::Format::W3CDTF

   *   Scalar::Util

   *   Try::Tiny

INCOMPATIBILITIES
   None reported.

BUGS AND LIMITATIONS
   No bugs have been reported.

   Please report any bugs or feature requests to "[email protected]", or
   through the web interface at
   <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=MQUL>.

AUTHOR
   Ido Perlmuter <ido at ido50 dot net>

LICENSE AND COPYRIGHT
   Copyright (c) 2011, Ido Perlmuter "ido at ido50 dot net".

   This module is free software; you can redistribute it and/or modify it
   under the same terms as Perl itself, either version 5.8.1 or any later
   version. See perlartistic and perlgpl.

   The full text of the license can be found in the LICENSE file included
   with this module.

DISCLAIMER OF WARRANTY
   BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
   FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
   OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
   PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
   EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
   WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
   ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
   YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
   NECESSARY SERVICING, REPAIR, OR CORRECTION.

   IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
   WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
   REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
   TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
   CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
   SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
   RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
   FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
   SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
   DAMAGES.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.