Filters each line, item, key or element in a source container or expression, removing the lines, items, keys or elements that do or don't match a pattern.
# Metadata
Platforms: desktop, server, mobile OS: mac, windows, linux, ios, android Introduced: 1.0 Security:
# Syntax
filter [{lines | items | keys | elements} of] filterSource {with| without | [not] matching} [wildcard] [pattern] wildcardPattern [into targetContainer]
# Params
- filterSource : An expression that evaluates to a string, array, or a container. - wildcardPattern : An expression used to match certain lines, items, keys or elements. See description. - regexPattern : An regular expression used to match certain lines, items, keys or elements. See [Microsoft's RegEx Quick Reference](https://docs.microsoft.com/en-us/dotnet/standard/base-types/regular-expression-language-quick-reference) guide for more info on regex usage. - targetContainer : An expression that evaluates to a container. - whereExpression : An expression that evaluates to a boolean.
# Examples
local tVar put the propertyNames into tVar filter tVar with "[az]*" -- tVar contains all property names beginning with a or z
-- Filtering a string literal causes the filtered string to be placed in the it variable filter items of "apple,banana,cherry" with regex pattern "b.*" -- it contains "banana"
local tSource, tBackscriptObjects put the backscripts into tSource filter lines of tSource without regex pattern "^stack.*" into tBackscriptObjects -- tBackscriptObjects contains a list of non-stack backscripts
create field "Numbers" put "123,234,345,456,567,678,789" into field "Numbers" filter items of field "Numbers" matching "*[!35-9]" -- field contains "234"
local tArray put true into tArray["foo"] put false into tArray["bar"] filter keys of tArray with "f*" put the keys of tArray is "foo"
local tArray put true into tArray["foo"] put false into tArray["bar"] filter elements of tArray without "f*" put the keys of tArray is "foo"
create field "Numbers" put "123,234,345,456,567,678,789" into field "Numbers" filter items of field "Numbers" where each >= 300 and each <= 500 -- field contains "345,456,567"
command FilterIt pValue filter lines of pValue where checkLine(each) end FilterIt function checkLine pLine return item 1 of pLine > item 2 of pLine end checkLine
# Description
Use the filter command to pick specific lines, items, keys or elements in a container or expression.
The `filter...with` form and the `filter...matching` form retain the lines, items, keys or elements that contain a match for the specified wildcardPattern or regexPattern.
The `filter...without` form and the `filter...not matching` form discard the lines, items, keys or elements that do not contain a match for the specified wildcardPattern or regexPattern.
If you don't specify lines, items, keys or elements then lines are filtered by default.
>**Note:** If neither `wildcard pattern` or `regex pattern` forms are explicitly specified then the wildcard pattern form is assumed.
If the `regex pattern` form is specified, the regexPattern should be formatted as a regular expression. There are [many websites](https://www.google.com/search?regex) that provide examples and tutorials of RegEx expressions.
If the 'wildcard pattern' form is to be used, the wildcardPattern should consists of a string of characters to match, which may be combined with any number of the following special characters:
- `*` : Matches zero or more of any character. The filterPattern `A*C` matches "AC", "ABC", or "ADZXC". - `?` : Matches exactly one character. The filterPattern `A?C` matches "ABC", but not "AC" or "ADZXC". - `[chars]` : Matches any one of the characters inside the brackets. The filterPattern `A[BC]D` matches "ABD" or "ACD", but not "AD" or "ABCD". - `[!chars]` : Matches any character which is not one of the characters inside the brackets. - `[char-char]` : Matches any character whose unicode codepoint is between the first character and the second character, such as `[a-y]` any character between "a" and "y" but not "z"
You can match instances of special chars as follows:
- `?` with `[?]` - `*` with `[*]` - `[` with `[[]` - `-` with `-` - `!` with `!`
For example, the wildcardPattern `[[]A]*` will match any string beginning with `[A]`. Broken down, there is `[[]` which equates to an open square bracket `[` followed by `A]*` as the closing square bracket is not a special character.
The three bracketed forms can be combined to create more complex character classes, for example the pattern [!abcA-C] matches any character which is not a, b or c (upper or lower case)
If no targetContainer is specified, and you filter a container, the container contents will be replaced by the filtered result.
When using the where form of the filter command the each keyword may be used in the whereExpression for the value to be filtered.
# Tags
# See
- **keyword:** it, each - **property:** caseSensitive - **command:** replace, sort - **function:** matchChunk, matchText, replaceText - **glossary:** container, expression, regular expression