filter ';' LIST ';' REGEX

Summary

The filter macro filters a list to include only those entries that match a specified regular expression pattern. Entries that don’t match are removed from the result.

Syntax

${filter;<list>;<regex>}

Parameters

• list - A comma or semicolon-separated list of values
• regex - A Java regular expression pattern to match against

Behavior

• Splits the input list into individual entries
• Compiles the regex pattern
• Tests each entry against the pattern using full match semantics
• Keeps only entries that match the pattern
• Returns the filtered list as a comma-separated string
• Empty result if no entries match

Examples

Filter for JAR files:

${filter;foo.jar,bar.txt,baz.jar;.*\.jar}
# Returns: "foo.jar,baz.jar"

Filter package names:

${filter;com.example.api,com.example.impl,org.other;com\.example\..*}
# Returns: "com.example.api,com.example.impl"

Filter versions:

${filter;1.0.0,2.0.0-SNAPSHOT,2.1.0;.*SNAPSHOT.*}
# Returns: "2.0.0-SNAPSHOT"

Filter by prefix:

${filter;test-bundle,main-bundle,test-util;test-.*}
# Returns: "test-bundle,test-util"

Use Cases

• Selecting specific files from a list
• Filtering packages or classes by naming patterns
• Extracting specific versions from a list
• Building selective classpaths
• Conditional inclusion based on naming conventions
• Cleaning up lists to match specific criteria

Notes

• Uses Java regular expression syntax
• The pattern must match the entire entry (full match, not substring)
• Case-sensitive by default (use (?i) for case-insensitive matching)
• See also: ${filterout} (or ${reject}) for inverse filtering
• See also: ${select} which is an alias for ${filter}

See test cases in MacroTestsForDocsExamples.java