deep-grep

Too many haystacks, not enough needles — or, "when you have a grep, everything looks like a list."

var needles = dg.deeply( [
	foo, [
		bar, baz, [
			bletch, [
				qip
			]
		]
	] ], function (t) { if t == qip return t }
)

usage

For grep on simple, flat (non-nested) lists:

• dg.in()
  • dg.in( list, 'value' ) - returns true or false depending upon whether list contains value.
• dg.all_in()
  • dg.all_in( list_a, list_b ) - returns a list of all values in list_a that exist in list_b.
• dg.unique()
  • dg.unique( list ) - returns all unique values of list. Note: flattens.
• dg.flatten( )
  • dg.flatten( nested_list ) - returns a list of all the lists contained in nested_list, concatenated into a single scope.

For doing greppy things on nested lists:

var haystack = [
	'zebra', 'lion', [
		'tiger', 'unicorn', 'emperor penguin'
	],
	'leprechaun',
	'cockerel'
];

var needles  = dg.deeply( list, function (t) {
	if (new RegExp( ('(unicorn|leprechaun)s?' ).test(t))) return true
} );

For more complex data, options are available to you:

var needles  = dg.deeply( arks['Noah'], function (t) { ... }, {
	// Any of these may be defined
	//

	// If items in the provided object have methods, check these methods for
	// return values that evaluate as true in the provided function.
	//
	'check-object-methods': [ 'get_species', 'list_passengers' ],

	// Provide optionally as argument to calls from check-object-methods, above
	//
	'object-method-arguments': [ argument, function, 'etc' ],

	// Return hash keys that evaluate true also?
	//   default: false
	//
	'check-keys': true,

	// Return hash values that evaluate true?
	//   default: false
	//
	'check-values': true,

	// Return key/value tuples rather than just keys or just values?
	//   default: false
	//
	'return-hash-tuples': true,
} );

deprecated methods

• dg.sync()
  • dg.sync( list, expression ) - evaluates list, returning a new list of every element that matches expression.test (like RegExp).
  • dg.sync( list, func ) - same as above, only executes func for every element of list, returning a new list.
• dg.async()
  • dg.async( list, expression ) - same as with sync(), above, only returns a promise to the list of matches.
  • dg.async( list, func, callback ) - same as sync(), above, except the callback is called with a promise to the list of matches.

author

@janearc, [email protected]