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 }
)

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,
} );

• 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.

@janearc, jane@cpan.org