Repository files navigation

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

    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'],            likes => { up => 45, down => 11 }    };    if (doc_matches($doc, {            title => qr/geeks/i,            genres => 'comedy',            imdb_score => { '$gte' => 5, '$lte' => 9.5 },            starring => { '$type' => 'array', '$size' => 3 },            'likes.up' => { '$gt' => 40 }    })) {            # 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'],            likes => { up => 45, down => 11 }    }

MQUL (forMongoDB-styleQuery &UpdateLanguage; pronounced"umm, cool"; yeah, I know, that's the dumbest thing ever), is a generalpurpose implementation ofMongoDB's query and update language. Theimplementation is not 100% compatible, but it only slightly deviates fromMongoDB's behavior, actually extending it a bit.

The module exports two subroutines:doc_matches() andupdate_doc().The first subroutine takes a document, which is really just a hash-ref (ofwhatever complexity), and a query hash-ref built in the MQUL query language.It returns a true value if the document matches the query, and afalse value otherwise. The second subroutine takes a document and an updatehash-ref built in the MQUL update language. The subroutine modifies the document(in-place) according to the update hash-ref.

You can use this module for whatever purpose you see fit. It was actuallywritten forGiddy, my Git-database, and was extracted from itsoriginal code. Outside of the database world, I plan to use it in an applicationthat performs tests (such as process monitoring for example), and uses thequery language to determine whether the results are valid or not (in ourmonitoring example, that could be CPU usage above a certain threshold andstuff like that). It is also used byMorboDB, an in-memory clone ofMongoDB.

My distributions follow thesemantic versioning scheme,so whenever the major version changes, that means that API changes incompatiblewith previous versions have been made. Always read the Changes file before upgrading.

The language itself is described inMQUL::Reference. This documentonly describes the interface of this module.

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

Receives a document hash-ref and possibly a query hash-ref, and returnstrue if the document matches the query, false otherwise. If no queryis given (or an empty hash-ref is given), true will be returned (everydocument will match an empty query - in accordance with MongoDB).

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

Optionally, an even-numbered array reference of dynamically calculatedattribute definitions can be provided. For example:

    [ min_val => { '$min' => ['attr1', 'attr2', 'attr3' ] },      max_val => { '$max' => ['attr1', 'attr2', 'attr3' ] },      difference => { '$diff' => ['max_val', 'min_val'] } ]

This defines three dynamic attributes:min_val,max_val anddifference, which is made up of the first two.

See"DYNAMICALLY CALCULATED ATTRIBUTES" in MQUL::Reference for more informationabout dynamic attributes.

Receives a document hash-ref and an update hash-ref, and updates thedocument in-place according to the update hash-ref. Also returns the documentafter the update. If the update hash-ref doesn't have any of the updatemodifiers described by the language, then the update hash-ref is consideredas what the document should now be, and so will simply replace the documenthash-ref (once again, in accordance with MongoDB).

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

• MQUL::doc_matches() requires a document hash-ref.

  This error means that you've either haven't passed thedoc_matches()subroutine 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 thedoc_matches() attribute anon-hash-ref query variable. While you don't actually have to pass aquery 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 theupdate_doc()subroutine 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 theupdate_doc() subroutine anon-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 documentprovided to theupdate_doc() subroutine is not an array.

MQUL requires no configuration files or environment variables.

MQUL depends on the following modules:

• Data::Compare
• Data::Types
• DateTime::Format::W3CDTF
• Scalar::Util
• Try::Tiny

None reported.

No bugs have been reported.

Please report any bugs or feature requests tobug-MQUL@rt.cpan.org, or through the web interface athttp://rt.cpan.org/NoAuth/ReportBug.html?Queue=MQUL.

Ido Perlmuter <ido at ido50 dot net>

Copyright (c) 2011-2025, Ido Perlmuterido at ido50 dot net.

Licensed under the Apache License, Version 2.0 (the "License");you may not use this file except in compliance with the License.The full License is included in the LICENSE file. You may alsoobtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, softwaredistributed under the License is distributed on an "AS IS" BASIS,WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.See the License for the specific language governing permissions andlimitations under the License.