LibTextFilter is a powerful text filtering library with an extensive syntax that allows users to filter for exactly the terms they want.
Compared to ZO_StringSearch it is a lot more flexible and easier to use.
It recognizes a number of operators that can be used to build elaborate filtering terms:
- ' ' (space), '&': combine two words with AND; precedence: 2
- '+', "/": combine two words with OR; precedence: 3
- '-', '^': combine two words with AND, but negate the second one; precedence: 3
- '!': negate the next expression; precedence: 4
- '~', '*': soft match item link (only item id instead of all fields); precedence: 5
- '(', ')': control the order in which operators are evaluated
- '"': filter for an exact term, handling operators in between two double quotes as part of a term
Usually the search terms are split along operators, so filtering for "termA+termB" is the same as using "termA +termB".
There is one exception however: A dash (-) inside a word does not get interpreted like other operators, so you can safely search for "some-item-name" without the need for quotes.
The filter algorithm is also very forgiving and tries to make the best out of invalid input.
In case a searchTerm should apply to multiple different sources, it is recommended to concatenate them into a single haystack with newline (\n).
That way all sources are searched at once and it won't accidentally find strings beyond the boundary of one source.
The filter is case sensitive, so you have to take care of putting everything into lower case yourself, if that's what you need.
Links can be put into lower case without worry as they will still be matched correctly.
Example
Lua Code:
local LTF = LibTextFilter
function list:FilterScrollList()
local scrollData = ZO_ScrollList_GetDataList(self.list)
ZO_ClearNumericallyIndexedTable(scrollData)
local searchTerm = searchBox:GetText():lower()
for i = 1, #masterList do
local data = masterList[i]
if(searchTerm == "" or LTF:Filter(data.name:lower(), searchTerm)) then
table.insert(scrollData, ZO_ScrollList_CreateDataEntry(DATA_TYPE, data))
end
end
end
API Reference
EvaluationResult
EvaluationResult is an enumeration of the possible return states of an evaluation.
lib.RESULT_OK: The evaluation worked without a problem.
lib.RESULT_INVALID_ARGUMENT_COUNT: There has been an operator with too little arguments.
lib.RESULT_INVALID_VALUE_COUNT: There where left over tokens that could not be matched.
lib.RESULT_INVALID_INPUT: The needle was either empty or did contain only operators. This result is only returned by Filter().
Filter
Code:
boolean isMatch, EvaluationResult result = lib:Filter(string haystack, string needle)
This is the main function of the library which combines everything into a simple and easy to use call.
The function fetches the parsedTokens for a needle from an internal cache, or generates them if they have not been cached yet.
Afterwards it calls Evaluate and returns the result. Unlike Evaluate it also recognizes if the input is empty and returns RESULT_INVALID_INPUT.
Tokenize
Code:
table tokens = lib:Tokenize(string needle)
Converts the input string into an array of tokens that will be passed to Parse().
Parse
Code:
table parsedTokens = lib:Parse(table tokens)
Brings the tokenized input into its reversed polish notation which can be cached and will be passed to Evaluate().
Evaluate
Code:
boolean isMatch, EvaluationResult result = lib:Evaluate(string haystack, table parsedTokens)
Applies the search term to the haystack and returns true if the expression is a match.
It also returns the evaluation result, which can be used to show the user some feedback in case the search term cannot be evaluated.
GetCachedTokens
Code:
table parsedTokens = lib:GetCachedTokens(string needle)
Returns the parsedTokens for a needle from the cache if they are already stored, or nil otherwise.
SetCachedTokens
Code:
lib:SetCachedTokens(string needle, table parsedTokens)
Stores the parsedTokens for a needle in the cache.
ClearCachedTokens
Code:
lib:ClearCachedTokens()
Clears all cached parsedTokens.