Path filter format - DarthJDG/Mangler.js GitHub Wiki

Path filters are used in Mangler.js when traversing an object or an array. Depending on the method used, when a filter matches the object could be added to the result list or a callback function may be called.

Path filters are checked against a path string that's generated by Mangler.js as it is traversing and examining each key/value pair.

var data = {
	mobile_os: [
		{ id: '001', name: 'Android' },
		{ id: '002', name: 'iOS' }
	],
	desktop_os: [
		{ id: '003', name: 'Windows' },
		{ id: '004', name: 'Linux', sub_os: [
			{ id: '005', name: 'CentOS' },
			{ id: '006', name: 'Ubuntu' }
		]}
	]
};

var m = Mangler(data);

As m.items is processed, the following path strings are generated for each key/value pair:

[0]
[0].mobile_os
[0].mobile_os[0]
[0].mobile_os[0].id
[0].mobile_os[0].name
[0].mobile_os[1]
[0].mobile_os[1].id
[0].mobile_os[1].name
[0].desktop_os
[0].desktop_os[0]
[0].desktop_os[0].id
[0].desktop_os[0].name
[0].desktop_os[1]
[0].desktop_os[1].id
[0].desktop_os[1].name
[0].desktop_os[1].sub_os
[0].desktop_os[1].sub_os[0]
[0].desktop_os[1].sub_os[0].id
[0].desktop_os[1].sub_os[0].name
[0].desktop_os[1].sub_os[1]
[0].desktop_os[1].sub_os[1].id
[0].desktop_os[1].sub_os[1].name

Note that path strings are generated relative to the .items array. Filters are transformed into a regular expression and tested against the end of these strings to decide the outcome of the operation. The following is a list of selectors that you can use to filter the data.

Property selector

The simplest selector, matches a property name. The filter 'name' will match the following items:

[0].mobile_os[0].name
[0].mobile_os[1].name
[0].desktop_os[0].name
[0].desktop_os[1].name
[0].desktop_os[1].sub_os[0].name
[0].desktop_os[1].sub_os[1].name

If only matches whole property names, for example 'name' would not match firstname.

Array selector

An empty array selector can be used to match all items in an array. While 'mobile_os' matches the whole array, 'mobile_os[]' matches all items within the array:

[0].mobile_os[0]
[0].mobile_os[1]

You can also match a specific array item by including the index in the selector. The filter 'mobile_os[1]' will match only the second array item:

[0].mobile_os[1]

To match all mobile OS names, include add a property selector to the end: 'mobile_os[].name' will match:

[0].mobile_os[0].name
[0].mobile_os[1].name

Wildcards

Sub-string wildcard

To match exactly one property with any name, use the ? wildcard character.

'desktop_os[].?' matches:

[0].desktop_os[0].id
[0].desktop_os[0].name
[0].desktop_os[1].id
[0].desktop_os[1].name
[0].desktop_os[1].sub_os

'?[].name' matches:

[0].mobile_os[0].name
[0].mobile_os[1].name
[0].desktop_os[0].name
[0].desktop_os[1].name
[0].desktop_os[1].sub_os[0].name
[0].desktop_os[1].sub_os[1].name

You can also use ? to match partial property names.

'?_os' matches:

[0].mobile_os
[0].desktop_os
[0].desktop_os[1].sub_os

The name property is matched by either '?me', 'na?' or 'n?e'.

Multi-level wildcard

The wildcard .* will match of zero or more levels of array or property references. Use it to match items only within the sub-tree of matching parents. The filter 'desktop_os.*.name' will match the following:

[0].desktop_os([0]).name
[0].desktop_os([1]).name
[0].desktop_os([1].sub_os[0]).name
[0].desktop_os([1].sub_os[1]).name

Parentheses indicate which part was matched by .*.

Prefixing with the multi-level wildcard matches direct properties as well, 'desktop_os[].*.name' will match the same items:

[0].desktop_os[0]().name
[0].desktop_os[1]().name
[0].desktop_os[1](.sub_os[0]).name
[0].desktop_os[1](.sub_os[1]).name

Passing multiple filters

To pass multiple filters, separate them with the | (pipe) character. Conditions will be met if any of the listed filter matches.

'id|name' matches:

[0].mobile_os[0].id
[0].mobile_os[0].name
[0].mobile_os[1].id
[0].mobile_os[1].name
[0].desktop_os[0].id
[0].desktop_os[0].name
[0].desktop_os[1].id
[0].desktop_os[1].name
[0].desktop_os[1].sub_os[0].id
[0].desktop_os[1].sub_os[0].name
[0].desktop_os[1].sub_os[1].id
[0].desktop_os[1].sub_os[1].name

'mobile_os[]|sub_os[1]' matches:

[0].mobile_os[0]
[0].mobile_os[1]
[0].desktop_os[1].sub_os[1]

Alternatively, you can also pass an array of strings, the filters above are equivalent to passing ['id', 'name'] and ['mobile_os[]', 'sub_os[1]'].