filter - Extract a subset of files from another element¶
Filter another element by producing an output that is a subset of the parent element’s output. Subsets are defined by the parent element’s split rules.
A filter element must have exactly one build dependency, where said dependency is the ‘parent’ element which we would like to filter. Runtime dependencies may also be specified, which can be useful to propagate forward from this filter element onto its reverse dependencies. See Dependencies to see how we specify dependencies.
When workspaces are opened, closed or reset on a filter element, or this element is tracked, the filter element will transparently pass on the command to its parent element (the sole build-dependency).
Consider a simple import element,
import.bst which imports the local files
‘foo’, ‘bar’ and ‘baz’ (each stored in
files/, relative to the project’s root):
kind: import # Specify sources to import sources: - kind: local path: files # Specify public domain data, visible to other elements public: bst: split-rules: foo: - /foo bar: - /bar
We can make an element’s metadata visible to all reverse dependencies by making use
public: field. See the public data documentation
for more information.
In this example,
import.bst will serve as the ‘parent’ of the filter element, thus
its output will be filtered. It is important to understand that the artifact of the
above element will contain the files: ‘foo’, ‘bar’ and ‘baz’.
Now, to produce an element whose artifact contains the file ‘foo’, and exlusively ‘foo’,
we can define the following filter,
kind: filter # Declare the sole build-dependency of the filter element depends: - filename: import.bst type: build # Declare a list of domains to include in the filter's artifact config: include: - foo
It should be noted that an ‘empty’
include: list would, by default, include all
split-rules specified in the parent element, which, in this example, would be the
files ‘foo’ and ‘bar’ (the file ‘baz’ was not covered by any split rules).
Equally, we can use the
exclude: statement to create the same artifact (which
only contains the file ‘foo’) by declaring the following element,
kind: filter # Declare the sole build-dependency of the filter element depends: - filename: import.bst type: build # Declare a list of domains to exclude in the filter's artifact config: exclude: - bar
In addition to the
exclude: fields, there exists an
(Boolean) field, which defaults to
False. This will determine whether to include files
which are not present in the ‘split-rules’. For example, if we wanted to filter out all files
which are not included as split rules we can define the following element,
kind: filter # Declare the sole build-dependency of the filter element depends: - filename: import.bst type: build # Filter out all files which are not declared as split rules config: exclude: - foo - bar include-orphans: True
The artifact of
filter-misc.bst will only contain the file ‘baz’.
Below is more information regarding the the default configurations and possible options of the filter element:
# Filter element configuration config: # A list of domains to include in each artifact, as # they were defined as public data in the parent # element's 'split-rules'. # # If a domain is specified that does not exist, the # filter element will fail to build. # # The default empty list indicates that all domains # of the parent's artifact should be included. # include:  # A list of domains to exclude from each artifact, as # they were defined in the parent element's 'split-rules'. # # In the case that a file is spoken for by a domain # in the 'include' list and another in the 'exclude' # list, then the file will be excluded. exclude:  # Whether to include orphan files which are not # included by any of the 'split-rules' present in # the parent element. # include-orphans: False