Skip to content

Latest commit

 

History

History
187 lines (128 loc) · 5.37 KB

README.md

File metadata and controls

187 lines (128 loc) · 5.37 KB
Raw

matchme

This is an experimental library that will allow object matching based on a simple query language plus chainable function interface.

NPM

browser support

unstable Build Status Dependency Status

2.0 Breaking Changes

  • The equality operator == is now a case-senstive match
  • A loose equality operator ~= can be used for case insensitive matches.
  • Regex operators are now implemented using =? for a match and !? for not.

Operator Summary

  • == - equality
  • != - inequality
  • =~ - loose equality (case insensitive string matching)
  • !~ - loose inequality
  • > - greater than
  • >= - greater or equal to
  • < - less than
  • <= - less than or equal to
  • =? - regex equality
  • !? - regex inequality

Simple Example

Matching is done at an object level against object properties, e.g.

var matchme = require('matchme');
var test = { name: 'Ted', age: 40 };

console.log(matchme(test, 'name == Ted'));
// --> true

console.log(matchme(test, 'name == ted'));
// --> false

console.log(matchme(test, 'name ~= ted'));
// --> true

console.log(matchme(test, 'age > 25'));
// --> true

console.log(matchme(test, 'name ~= ted && age > 45'));
// --> false

In addition matchme can be used in conjunction the filter function (both the native JS implemenation or underscores):

var matchme = require('matchme');
var people = [
  { name: 'Ted', age: 40 },
  { name: 'Bill', age: 42 }
];

console.log(people.filter(matchme.filter('age > 40')));
// --> [ { name: 'Bill', age: 42 }]

Pull-Stream Example

An example using the pull-stream module is shown below. This example reads data from a data file downloaded from geonames and loaded in through the geonames module which provides a pull-stream source.

var geonames = require('geonames');
var pull = require('pull-stream');
var matchme = require('matchme');

console.log('Places with a population > 500,000 (limited to first 10):');

pull(
  geonames.read(__dirname + '/data/AU.txt'),
  pull.filter(matchme.filter('featureClass == P && population > 500000')),
  pull.take(10),
  pull.drain(function(place) {
    console.log(place.name);
  })
);

Additionally, here is another example that uses a matchme regex to identify places that are named as Islands but are classified as something else:

var geonames = require('geonames');
var pull = require('pull-stream');
var matchme = require('matchme');

pull(
  geonames.read(__dirname + '/data/AU.txt'),
  pull.filter(matchme.filter('name =? /Island$/ && featureCode != ISL')),
  pull.drain(function(place) {
    console.log(place.name + ' might seem like an island but is in fact a ' + place.featureCode);
  })
);

A Note regarding Eval

The matchme module uses eval as it's highly pragmatic in this situation. Feel free to create breaking tests if you think there are exploite introduced from it's use.

Matcher prototype reference

gt(prop, value, result?)

Check whether the specified property of the target object is greater than the specified value. If the optional result argument is passed to the function then the result is passed back in that object. If not the result is stored in the local ok property of the matcher instance. Other comparison methods use the same principle as this function.

gte(prop, value, result?)

Greater than or equal to check.

lt(prop, value, result?)

Less than property value check

lte(prop, value, result?)

Less than or equal to check

equals(prop, value, result?)

Equality check

looseEquals(prop, value, result?)

Equality check (case insensitive)

not(prop, value, result?)

regex(prop, value, result?)

query(text)

Internal Helpers

_evaluateExpressions(text, expr)

_val(prop)

License(s)

MIT

Copyright (c) 2014 Damon Oehlman damon.oehlman@gmail.com

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.