diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -1,5 +1,15 @@ # fuzzyset-haskell [![Build Status](https://img.shields.io/travis/laserpants/fuzzyset-haskell/master.svg?style=flat)](https://travis-ci.org/laserpants/fuzzyset-haskell) [![License](https://img.shields.io/badge/license-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause) [![Language](https://img.shields.io/badge/language-Haskell-yellow.svg)](https://www.haskell.org/) [![Hackage](https://img.shields.io/hackage/v/fuzzyset.svg)](http://hackage.haskell.org/package/fuzzyset) +## Table of Contents + +* [About](#about) +* [Install](#install) +* [How to use](#how-to-use) +* [API](#api) +* [Examples](#examples) + +## About + A fuzzy string set data structure for approximate string matching. This implementation is based on the Python and JavaScript libraries with the same name: * [JavaScript version](https://github.com/Glench/fuzzyset.js) @@ -35,11 +45,133 @@ [(0.7692307692307693,"Shaggy Rogers"),(0.5,"Fred Jones")] ``` +See [here](https://github.com/laserpants/fuzzyset-haskell/blob/master/README.md#examples) for more examples. + +## API + +### Initializing + +#### `mkSet :: Size -> Size -> Bool -> FuzzySet` + +* `Size` The lower bound of gram sizes to use (inclusive) +* `Size` The upper bound of gram sizes to use (inclusive) +* `Bool` Whether to use Levenshtein distance to determine the score +* `FuzzySet` An empty fuzzy string set + +Initialize a FuzzySet. + +#### `defaultSet :: FuzzySet` + +A FuzzySet with the following field values: + +``` +{ gramSizeLower = 2 +, gramSizeUpper = 3 +, useLevenshtein = True +, exactSet = ε +, matchDict = ε +, items = ε } +``` + +#### `fromList :: [Text] -> FuzzySet` + +Create a fuzzy string set with entries from the given list. + +``` +fromList = addMany defaultSet +``` + +### Adding + +#### `add :: FuzzySet -> Text -> FuzzySet` + +* `FuzzySet` Fuzzy string set to add the entry to +* `Text` The new entry +* `FuzzySet` The updated set + +Add an entry to the set, or do nothing if a key identical to the provided value already exists in the set. + +#### `addToSet :: FuzzySet -> Text -> (FuzzySet, Bool)` + +* `FuzzySet` Fuzzy string set to add the entry to +* `Text` The new entry +* `(FuzzySet, Bool)` The updated set and a boolean, which will be `True` if, and only if, the value was not already in the set. + +Add an entry to the set and return a pair with the new set, and a boolean to indicate if a new entry was inserted, or not. + +#### `addMany :: FuzzySet -> [Text] -> FuzzySet` + +* `FuzzySet` Fuzzy string set to add the entries to +* `[Text]` A list of new entries +* `FuzzySet` A new fuzzy string set + +Add a list of entries to the set, in one go. + +``` +addMany = foldr (flip add) +``` + +### Retrieving + +#### `get :: FuzzySet -> Text -> [(Double, Text)]` + +* `FuzzySet` The fuzzy string set to compare the string against +* `Text` The lookup query +* `[(Double, Text)]` A list of results (score and matched value pairs) + +Try to match the given string against the entries in the set, using a minimum score of 0.33. Return a list of results ordered by similarity score, with the closest match first. + +#### `getWithMinScore :: Double -> FuzzySet -> Text -> [(Double, Text)]` + +* `Double` A minimum score +* `FuzzySet` The fuzzy string set to compare the string against +* `Text` The lookup query +* `[(Double, Text)]` A list of results (score and matched value pairs) + +Try to match the given string against the entries in the set, and return a list of all results with a score greater than or equal to the specified minimum score (i.e., the first argument). The results are ordered by similarity score, with the closest match first. + +#### `getOne :: FuzzySet -> Text -> Maybe Text` + +* `FuzzySet` The fuzzy string set to compare the string against +* `Text` The lookup query +* `Maybe Text` Return `Just` the result, if a match was found, otherwise `Nothing` + +Try to match the given string against the entries in the set, and return the closest match, if one is found. + +### Inspecting + There are also a few functions to inspect the set. -### More examples +#### `size :: FuzzySet -> Int` +Return the number of entries in the set. + ``` +>>> size (defaultSet `add` "map" `add` "cap") +2 +``` + +#### `isEmpty :: FuzzySet -> Bool` + +Return a boolean to indicate whether the set is empty. + +``` +>>> isEmpty (fromList []) +True +``` + +#### `values :: FuzzySet -> [Text]` + +Return the elements of the set. + +``` +>>> values (fromList ["bass", "craze", "space", "lace", "daze", "haze", "ace", "maze"]) +["space","daze","bass","maze","ace","craze","lace","haze"] +``` + +## Examples + +``` {-# LANGUAGE OverloadedStrings #-} module Main where @@ -72,7 +204,7 @@ (0.35714285714285715,"Maryland") ``` -Using the definition of `statesSet` from previous example: +Using the same definition of `statesSet` from previous example: ``` >>> get statesSet "Why-oh-me-ing" diff --git a/fuzzyset.cabal b/fuzzyset.cabal --- a/fuzzyset.cabal +++ b/fuzzyset.cabal @@ -1,5 +1,5 @@ name: fuzzyset -version: 0.1.0.4 +version: 0.1.0.5 synopsis: Fuzzy set for approximate string matching description: This library is based on the Python and JavaScript libraries with the same name. homepage: https://github.com/laserpants/fuzzyset-haskell @@ -23,7 +23,7 @@ build-depends: base >= 4.7 && < 5 , base-unicode-symbols ==0.2.2.4 , data-default ==0.7.1.1 - , lens ==4.15.4 + , lens >=4.15.4 , text >=1.2.2.2 , text-metrics ==0.3.0 , unordered-containers ==0.2.8.0 @@ -38,7 +38,7 @@ , base-unicode-symbols ==0.2.2.4 , hspec >=2.4.4 , fuzzyset - , lens ==4.15.4 + , lens >=4.15.4 , text >=1.2.2.2 , ieee754 ==0.8.0 , unordered-containers ==0.2.8.0 diff --git a/src/Data/FuzzySet.hs b/src/Data/FuzzySet.hs --- a/src/Data/FuzzySet.hs +++ b/src/Data/FuzzySet.hs @@ -183,7 +183,7 @@ → Text -- ^ The lookup query → Maybe Text - -- ^ 'Just' the result, if one was found, otherwise 'Nothing' + -- ^ 'Just' the result, if a match was found, otherwise 'Nothing' getOne set val = case get set val of [] → Nothing