Module

Data.Fuzzy

The Fuzzy module provides functions and metrics for discerning how well a given value matches a string.

#Segments 

type Segments = Array (Either String String)

Type representing segments of matched and unmatched substrings. For example, when matching the pattern "foo bar" against the value "food barn", the resulting Segments would be:

[ Right "foo", Left "d ", Right "bar", Left "n" ]

#Distance 

data Distance

Data representing the distance of a value from the pattern string. There are six magnitudes of distance, ranging from severe on the left, to almost trivial on the right. The smaller the distance, the better the match, with Distance 0 0 0 0 0 0 representing a perfect match.

Distance is an instance of Ord, allowing you to sort based on best distance.

Each position's penalty is incremented for the following conditions:

  • 0: Failed matches. This is the most severe penalty, which is added each time the match function cannot match any of the following in order: The exact pattern in its entirety, entire words within the pattern, individual chars in unmatched words
  • 1: Between matches in a word. This is the next most severe penalty, added for each irrelevant char inbetween matched chars in each word. E.g., when matching the pattern "foo bar" against the value "flooded beamer", this penalty would be set to 4
  • 2: Matched word prefix. This penalty is added whenever the first char for a word in a pattern is not also the first char for the word its matched in. E.g., when matching the pattern "foo bar" against the value "an unfollowed tubular", this penalty would be set to 4
  • 3: Chars till first match. This penalty is added for every char up to the first match. E.g., when matching the pattern "foo bar" against the value "an unfollowed tubular", this penalty would be set to 5
  • 4: Matched word suffix. This penalty is the same as the prefix penalty but for suffixes. E.g., when matching the pattern "foo bar" against the value "fooled barn hens", this penalty would be set to 4
  • 5: Chars after last match. This penalty is added for every char after the last match. E.g., when matching the pattern "foo bar" against the value "fooled barn hens", this penalty would be set to 6

Constructors

Instances

#FuzzyStr 

newtype FuzzyStr

Data representing the result of matching a string value against a string pattern

Fields:

  • original: the original string value provided to matchStr
  • segments: Segments value, which will contain original split into substrings of matched and unmatched chars (see Segments definition)
  • distance: Distance score from pattern to original (see Distance definition)
  • ratio: Rational representing percentage of matched chars. If all chars in pattern are present, value will be a perfect 1 % 1. If no chars are matched, value will be 0 % 1. A few other scenarios for the pattern "foo bar":
    • "goo bar": 5 % 6
    • "go bar": 2 % 3
    • "bar": 1 % 2
    • "car": 1 % 3
    • "curry": 1 % 6 This allows you to filter out results that are below a desired threshold

Constructors

Instances

#Fuzzy 

newtype Fuzzy a

Data representing the result of matching any polymorphic value to a string pattern

Fields:

  • original: the original polymorphic value provided to match
  • segments: Object of keys to Segments values, Segments values each consisting of the original string values for each key, split into substrings of matched and unmatched chars (see Segments or match definitions for more info)
  • distance: the best Distance score found for any provided key values (see Distance and match defintions for more info)
  • ratio: the best ratio found for any provided key values (see FuzzyStr definition)

Constructors

Instances

#matchStr 

matchStr :: Boolean -> String -> String -> FuzzyStr

Function to match a string value against a string pattern

Arguments:

  • ignoreCase: flag for whether or not uppercase and lowercase values should be considered the same or not
  • pattern: string of chars you wish to match for in str
  • str: string to search through for the chars in pattern

Returns:

FuzzyStr data type with properties useful for highlighting matches, sorting a list of values, filtering out poor matches, etc.

Examples:

> matchStr true "foo bar" "fiz baz foo bar buz"
FuzzyStr
  { original: "fiz baz foo bar buz"
  , segmemnts: [ Left "fiz baz ", Right "foo bar", Left " buz" ]
  , distance: Distance 0 0 0 8 0 4
  , ratio: 1 % 1
  }

See `test/Main.purs` for more examples

#match 

match :: forall a. Boolean -> (a -> Object String) -> String -> a -> Fuzzy a

Funtion to match any polymorhic value against a string pattern

Arguments:

  • ignoreCase: flag for whether or not uppercase and lowercase values should be considered the same or not
  • extract: function from your polymorphic val to Object String so match can search through each string for the desired pattern
  • pattern: string of chars you wish to match for in any of the strings extract pulls from the provided val
  • val: polymorphic value that match will pull out strings from via the provided extract function and then search through for the chars in pattern

Returns:

Fuzzy data type with properties useful for highlighting matches, sorting a list of values, filtering out poor matches, etc.

Examples:

> toMapStr { name, value } = fromFoldable [ Tuple "name" name, Tuple "value" value ]
> match true toMapStr "foo bar" { name: "Foo Bar Baz", value: "foobar" }
Fuzzy
  { original: { name: "Foo Bar Baz", value: "foobar" }
  , segments: fromFoldable [ Tuple "name" [ Right "Foo Bar", Left " Baz" ]
                           , Tuple "value" [ Right "foobar" ] ]
  , distance: Distance 0 0 0 0 0 4
  , ratio: 1 % 1
  }

See `test/Main.purs` for more examples

Modules