README.markdown
# Fuzzlogia
[](https://travis-ci.org/builtinnya/fuzzlogia)
[](https://coveralls.io/r/builtinnya/fuzzlogia?branch=master)
[](https://codeclimate.com/github/builtinnya/fuzzlogia)
[](https://david-dm.org/builtinnya/fuzzlogia)
[](https://david-dm.org/builtinnya/fuzzlogia#info=devDependencies)
Fuzzlogia is a simple **Japanese-kanji-reading-aware fuzzy search** library written in JavaScript.
> Fuzzlogia is still in the early development stage. The API is unstable.
Some examples:
```javascript
var fl = require('fuzzlogia');
// => [ 'fuzzy' ]
fl.search('fzzuy', [ 'fuzzy', 'matching' ]);
// => [ '最高裁判所' ]
fl.search('さいこうさいばんしょ', [ '最高裁判所' ]);
// => [ '漢字は難しい' ]
fl.search('かんじ', [ '漢字は難しい' ]);
// => [ '銀河ヒッチハイクガイド' ]
fl.search('ぎんが', [ '電気羊', '銀河ヒッチハイクガイド' ]);
```
## Features
- **Pure** (no dependencies)
- Fuzzy search with **ranking** (based on # of matched letters, distance, and item length)
- **Japanese Kanji's on/kun/nanori reading aware** (using [KANJIDIC][])
[KANJIDIC]: http://www.csse.monash.edu.au/~jwb/kanjidic.html
## Installation
Using [npm](https://www.npmjs.com/):
```shell
npm install --save fuzzlogia
```
### In browser
You can use [Browserify](http://browserify.org/) or [Webpack](http://webpack.github.io/) or whatever you want.
## API
### `search(query, bucket, extractor, options)`
---
**query** (*type*: `String`)
A query string.
---
**bucket** (*type*: `Array`)
An array of items to search for.
---
**extractor** (*type*: `String|Function`, *default*: `identity`)
A function to extract the string to be compared with `query` from each item.
If `extractor` is a string, it will be used as a property name.
Examples:
```javascript
// => [ { name: 'John' }]
fl.search('John', [ { name: 'John' } ], 'name');
// => [ { firstName: 'John', lastName: 'Mullins'} ]
fl.search('John', [ { firstName: 'John', lastName: 'Mullins'} ], function(item) {
return item.firstName + ' ' + item.lastName;
});
```
---
**options** (*type*: `Object`, *default*: see below)
Options to control the behavior. The following options are supported:
- **threshold** (*type*: `Number`, *default*: 0)
If the number of characters in `query` **not** contained in an item string exceeds `threshold`,
the item will not appear in the result.
Examples:
```javascript
// => []
fl.search('gist', [ 'git' ], null, { threshold: 0 })
// => [ 'git' ]
fl.search('gist', [ 'git' ], null, { threshold: 1 })
```
## Dictionaries
Fuzzlogia uses the following dictionaries:
- **[KANJIDIC][]**
[KANJIDIC][] file contains comprehensive information about 6,355 Japanese kanji specified in the JIS X 0208-1990, including Japanese on/kun/nanori readings ([documentation][KANJIDIC DOC]).
The file is the property of the [Electronic Dictionary Research and Development Group][EDRDG], and are used in conformance with the Group's [licence][EDRDGL].
[KANJIDIC]: http://www.csse.monash.edu.au/~jwb/kanjidic.html
[KANJIDIC DOC]: http://www.edrdg.org/kanjidic/kanjidic_doc.html
[EDRDG]: http://www.edrdg.org/
[EDRDGL]: http://www.edrdg.org/edrdg/licence.html
## Tools
Fuzzlogia contains the following tools:
- **[kanjidic.js](tools/kanjidic.js)**
Extracts and compiles KANJIDIC into easy-to-use format for Fuzzlogia. See the file for usage.
[onkundic.js](src/onkundic.js) is automatically generated by this tool.
## TODOs
- Demo page
- Performance analysis and tuning
- Hiragana/katakana/romaji agnostic fuzzy search
## Contributing to Fuzzlogia
Pull requests are welcomed.
Please add the relevant tests and ensure that it passes all the tests by executing
`npm test` before submitting a pull request.
## License
Copyright © 2015 Naoto Yokoyama
Distributed under the MIT license. See the [LICENSE](./LICENSE) file for full details.