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.

Overview

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).

Example

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

Note

We can make an element’s metadata visible to all reverse dependencies by making use of the 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, filter-foo.bst:

kind: filter

# Declare the sole build-dependency of the filter element
build-depends:
- import.bst

# 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, exclude-bar.bst:

kind: filter

# Declare the sole build-dependency of the filter element
build-depends:
- import.bst

# Declare a list of domains to exclude in the filter's artifact
config:
  exclude:
  - bar

In addition to the include: and exclude: fields, there exists an include-orphans: (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, filter-misc.bst:

kind: filter

# Declare the sole build-dependency of the filter element
build-depends:
- import.bst

# 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:

#  Licensed under the Apache License, Version 2.0 (the "License");
#  you may not use this file except in compliance with the License.
#  You may obtain a copy of the License at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
#  Unless required by applicable law or agreed to in writing, software
#  distributed under the License is distributed on an "AS IS" BASIS,
#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#  See the License for the specific language governing permissions and
#  limitations under the License.

# 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

  # Whether to pass the 'integration-commands' of the
  # parent element through the filter.
  #
  pass-integration: False