Table of Contents
filter
Table of Contents
Prototype: filter(filter, list, is_regex, invert, max_return)
Return type: slist
Description: Transforms a list or data container into a list subset thereof.
This is a generic filtering function that returns a list of up to max_return
elements in list
that match the filtering rules specified in filter
,
is_regex
and invert
.
This function can accept many types of data parameters.
Arguments:
- filter : Anchored regular expression or static string to find, in the range
.*
- list : The name of the list variable or data container to check, in the range
[a-zA-Z0-9_$(){}\[\].:]+
- is_regex_ : Boolean
Treat filter
as a regular expression or as a static string.
invert
: Boolean
Invert filter.
max_return
: Maximum number of elements to return in the range0,999999999
Example:
body common control
{
bundlesequence => { "test" };
}
bundle agent test
{
vars:
"test" slist => {
1,2,3,
"one", "two", "three",
"long string",
"one", "two", "three",
};
"test2" data => parsejson('[1,2,3, "ab", "c"]');
"test_filtergrep" slist => filter("[0-9]", test, "true", "false", 999);
"test_exact1" slist => filter("one", test, "false", "false", 999);
"test_exact2" slist => filter(".", test, "false", "false", 999);
"test_invert" slist => filter("[0-9]", test, "true", "true", 999);
"test_max2" slist => filter(".*", test, "true", "false", 2);
"test_max0" slist => filter(".*", test, "true", "false", 0);
"test_grep" slist => grep("[0-9]", test);
"test2_filtergrep" slist => filter("[0-9]", test2, "true", "false", 999);
"test2_exact1" slist => filter("one", test2, "false", "false", 999);
"test2_exact2" slist => filter(".", test2, "false", "false", 999);
"test2_invert" slist => filter("[0-9]", test2, "true", "true", 999);
"test2_max2" slist => filter(".*", test2, "true", "false", 2);
"test2_max0" slist => filter(".*", test2, "true", "false", 0);
"test2_grep" slist => grep("[0-9]", test2);
"todo" slist => { "test", "test2", "test_filtergrep", "test_exact1",
"test_exact2", "test_invert", "test_max2",
"test_max0", "test_grep", "test2_filtergrep",
"test2_exact1", "test2_exact2",
"test2_invert", "test2_max2", "test2_max0",
"test2_grep"};
"$(todo)_str" string => format("%S", $(todo));
"tests" slist => { "test", "test2" };
reports:
"The $(tests) list is $($(tests)_str)";
"The grepped list (only single digits from $(tests)) is $($(tests)_grep_str)";
"The filter-grepped list (only single digits from $(tests)) is $($(tests)_grep_str)";
"The filter-exact list, looking for only 'one' in $(tests), is $($(tests)_exact1_str)";
"This list should be empty, the '.' is not literally in the list $(tests): $($(tests)_exact2_str)";
"The filter-invert list, looking for non-digits in $(tests), is $($(tests)_invert_str)";
"The filter-bound list, matching at most 2 items from the whole list $(tests), is $($(tests)_max2_str)";
"This list should be empty because 0 elements of $(tests) were requested: $($(tests)_max0_str)";
}
Output:
R: The test list is { "1", "2", "3", "one", "two", "three", "long string", "one", "two", "three" }
R: The test2 list is [1,2,3,"ab","c"]
R: The grepped list (only single digits from test) is { "1", "2", "3" }
R: The grepped list (only single digits from test2) is { "1", "2", "3" }
R: The filter-grepped list (only single digits from test) is { "1", "2", "3" }
R: The filter-grepped list (only single digits from test2) is { "1", "2", "3" }
R: The filter-exact list, looking for only 'one' in test, is { "one", "one" }
R: The filter-exact list, looking for only 'one' in test2, is { --empty-list-- }
R: This list should be empty, the '.' is not literally in the list test: { --empty-list-- }
R: This list should be empty, the '.' is not literally in the list test2: { --empty-list-- }
R: The filter-invert list, looking for non-digits in test, is { "one", "two", "three", "long string", "one", "two", "three" }
R: The filter-invert list, looking for non-digits in test2, is { "ab", "c" }
R: The filter-bound list, matching at most 2 items from the whole list test, is { "1", "2" }
R: The filter-bound list, matching at most 2 items from the whole list test2, is { "1", "2" }
R: This list should be empty because 0 elements of test were requested: { --empty-list-- }
R: This list should be empty because 0 elements of test2 were requested: { --empty-list-- }
History: The collecting function behavior was added in 3.9.
See also: About collecting functions, grep()
, every()
, some()
, and none()
.