-
Notifications
You must be signed in to change notification settings - Fork 21
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Document API / Usage #24
Comments
Thank you for asking this question, indeed this is long needed. Basic usagefz = require("fuzzaldrin-plus") FilteringFiltering is the process if finding valid entries among a list of candidate and sorting them by score, given a query.
Filtering Array of strings
fz.filter(candidates, query) Example: candidates = [
'Find And Replace: Select All',
'Settings View: Uninstall Packages',
'Settings View: View Installed Themes',
'Application: Install Update',
'Install'
]
results = fz.filter(candidates, 'install') Filtering Array of objects
fz.filter(candidates, query, {key:"mykey"})
//filter & sort list of objects by obj.mykey ScoringFiltering is provided to provide some out-of-box usefulness, but most of this library is about finding the proper score between a candidate and a query. (Score of 0 meaning entry should be filtered out) Outside of debugging, generating a score is mostly useful to generate your own filtering algorithm.
If you have such a need you can use scoring with the folowing guideline:
Basic scoring
score = fz.filter(candidate_string, query) There's no variant that take an object and ask wich key because at this point you can probably do it better. It is not recommanded to display result of scoring to user. Even if the ordering try to be intuitive, the score by itself is very hard to interpret since it mix together a lot of quality signals, is non linear and sometime jumpy. Loop scoring (prepQuery)The basic idea is to precompute some quantity upfront about the query so we do less work on a candidate by candidate basis. prepared = fz.prepQuery(query)
for(...){
score = fz.filter(candidate_string, query, prepared)
} Note: there's the recent addition of a cache on the fz object that store last query and coresponding prepared query. MatchingTo communicate why the algorithm think a result is good or bad, it's often good to highligth matched characters. fz.match(candidate_string, query) Note See also the demo on how to wrap that ouput with html tag AdvancedAll of the method (filter, score, match, prepQuery) take an option hash. I may return to document those when I have more time, but most user don't need them. |
Thanks! This was very helpful. I'm working on a set of TypeScript typings for your library, does the following look correct to you? // Type definitions for fuzzaldrin-plus
// Project: https://github.com/jeancroy/fuzzaldrin-plus/
// Definitions by: Jason Killian <https://github.com/jkillian>
// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
export as namespace fuzzaldrin;
export interface IQueryOptions {
pathSeparator?: string;
optCharRegEx?: RegExp;
}
export interface IScoringOptions extends IQueryOptions {
allowErrors?: boolean;
isPath?: boolean;
useExtensionBonus?: boolean;
}
export interface IFilterOptions extends IScoringOptions {
key?: string;
maxResults?: number;
}
export type PreparedQuery = { __internalAPIBrand: string; };
export function filter<T>(data: T[], query: string, options?: IFilterOptions): T[];
export function score(str: string, query: string, preparedQuery?: PreparedQuery, options?: IScoringOptions): number;
export function match(str: string, query: string, preparedQuery?: PreparedQuery, options?: IScoringOptions): number[];
export function prepQuery(query: string, options?: IQueryOptions): PreparedQuery; Note that the |
Curently prepQuery looks more like this Others signature seems OK. |
My thinking was that those are private fields that are only meant for use by your library and not by an external user. The way I wrote things above basically only lets users pass a Does that seem like the right decision? |
Yes, thank you that look good. I have some plan to add some options I guess when that settle out we'll see how to extend the option hash definition. |
Great! See PR here if you're interested |
Thanks for that, I'll try to keep more stability in the interface for the future. The reason I've demoted prepared query from it's own argument is that the internal cache was giving just as good performance than explicitly setting a prepared query. So no caring about prepared query allow simpler usage. |
Yes, that is one thing that should be taken care with every new changes. |
I'm open to maintaining a nugget package. And/or outputting typescript as a distribution format on each build. ( I may actually be due to cut a real release soon ) I'm also not that invested in the current coffescript form. |
Awesome, moving to ES6 will definitely bring more cohesion with other projects as most of them are evolving in that direction to get more out of box functionality and performance. Maintain a separate
|
Hi @jeancroy, are you ok with the approach? I already have some work in my local repository for this. |
Yes I think this is the right path forward. I've added you as collaborator as I guess we'll needs to setups some things. If you need me to create branches or something, please tell. |
Hi Jean, May I know your Email ID? I will add you as owner for nuget package. Thanks On Thu, Oct 20, 2016 at 7:08 PM, Jean Christophe Roy <
|
hi I'm registered with nugget as jeancroy, with email [email protected] Jean Christophe Roy On Tue, Oct 25, 2016 at 2:44 PM, Manish Dahamiwal [email protected]
|
My apologies if I missed it while scanning over your README, but I didn't notice any sections that document usage of this library or its API. I'm aware the API is similar to https://github.com/atom/fuzzaldrin, but it would be great to have it listed here as well.
The text was updated successfully, but these errors were encountered: