prevOpen Sourceast-comparenext

ast-compare4.0.3

Compare anything: AST, objects, arrays, strings and nested thereof

Downloads per monthChangelogMIT Licenselibera manifesto

Installation

Quick Take

Examples

Purpose

It compares data structures, especially, AST’s.

We use it to compare two parsed HTML/CSS trees or their branches, but you can compare anything, it will recursively traverse arrays too. For example, it powers ast-delete-object which also works on AST’s.

The default mode is similar to Tapopens in a new tab asserts t.match and the option opts.matchStrictly is similar to t.sameStrict.

API — compare()

The main function compare() is imported like this:

It’s a function which takes three input arguments:

Input argumentTypeObligatoryDescription
bigObj
Type: Array or Plain object or String
Obligatory: yes
bigObjArray or Plain object or StringyesSuperset, larger thing.
smallObj
Type: Array or Plain object or String
Obligatory: yes
smallObjArray or Plain object or StringyesA set of the above, smaller thing.
opts
Type: Plain object
Obligatory: no
optsPlain objectnoAn Optional Options Object.
  • If everything from smallObj matches everything within bigObj, this library returns true.
  • Otherwise, if there’s a mismatch or something wrong with input args, it returns false.

None of the input arguments will be mutated by this program, we have unit tests to prove that.

The optional options object has the following shape:

KeyTypeObligatoryDefaultDescription
hungryForWhitespace
Type: Boolean
Obligatory: no
Default: false
hungryForWhitespaceBooleannofalseAny chunk of whitespace (tabs, spaces, line breaks and so on) will match any other chunk of white space.
matchStrictly
Type: Boolean
Obligatory: no
Default: false
matchStrictlyBooleannofalseWhen you want to match like ===.
verboseWhenMismatches
Type: Boolean
Obligatory: no
Default: false
verboseWhenMismatchesBooleannofalseWhen set to true, instead of false the output will be a string with a message explaining what didn’t match. It’s for cases when it’s important to report what didn’t match.
useWildcards
Type: Boolean
Obligatory: no
Default: false
useWildcardsBooleannofalseIf off by default, but you can enable wildcards within object value strings.

The function returns a boolean:

A positive answer is always boolean true.

A negative answer is either:

  • a boolean false (on default setting, if opts.verboseWhenMismatches is false) OR
  • a string, explaining what didn’t match (if opts.verboseWhenMismatches is true)

API — defaults

You can import defaults:

It's a plain object:

The main function calculates the options to be used by merging the options you passed with these defaults.

API — version

You can import version:

opts.verboseWhenMismatches

Sometimes you just want a yes/no answer is something a subset or equal to something. But sometimes, the whole point of comparison is to inform the user exactly what is mismatching. In the latter cases, set opts.verboseWhenMismatches to true. When there is no match, instead of Boolean false the main function will return a string with an explanatory message.

If you use this setting, you have to anticipate Boolean true OR something else (Boolean false or string) coming out from this library.

Differences from _.isMatch

Partial comparisons will match empty array and empty object source values against any array or object value, respectively.

Lodash documentationopens in a new tab

_.isMatchopens in a new tab positively matches empty arrays to everything. This is bad when you are comparing parsed HTML/CSS trees. This library doesn’t do this. An empty array will not be reported as equal to a non-empty array.

// in this library:
var res = compare(["a", "b", "c"], []);
// now, res === false

Changelog

Open Changelog
↑ back to top
prev next