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.

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 range 0,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-- }

See also: grep(), every(), some(), and none().