Filter functions

Filters can change the look and format of the source data, or even generate new data derived from the input values. What's important is that the original data is replaced by the result of transformations, and that's what ends up in rendered templates.

Overview

The following functions are supported in addition to the built-in functions provided by Nunjucks.

Low level functions

High level functions

Named arguments

Some functions supports named arguments, many of these repeat in different functions.

term - a single string, used as substring to match with the matched item.

list - a list of strings, trying to match any of the listed substrings with the matched item.

regex - a single string, used as regular expression to with the matched item. A regular expression can be created just like JavaScript, but needs to be prefixed with r, for example r/^foo.*/g, for more info see Nunjucks.

globs - a key to an element in the .cm that holds a list of strings, used as glob pattern test on the matched item. For more info, see Wikipedia.

attr - a key in the element to use when doing the requested operation.

For example, the following expressions provide an identical result:

- {{ 'something' | includes(regex=r/^some.*/) }}
- {{ 'something' | includes(term='some') }}
- {{ 'something' | includes(list=['some']) }}

Reference

every

Checks whether all element in the list are true. In case the list of elements is empty, it will return false.

For example, check that all changes are in either 'src' or 'dest' directories:

{{ files | match(list=['src', 'dest']) | every }}

filter

Creates a shallow copy of a portion of a given list, filtered down to just the elements that match the given term. You can use either a single term, regex, or a list of terms to match with.

For example, check if all changes to JavaScript files are in tests directory:

{{ files | filter(regex=r/\.js$/) | match(regex=r/tests\/) | every }}

For example, check if all changes to JavaScript files are formatting:

{{ source.diff.files | filter(attr='new_file', regex=r/\.js$/) | isFormattingChange }}

includes

Determines whether a string includes a certain substring. You can use either a single term, regex, or a list of terms to match with.

Check string matches either of the terms:

{{ 'something' | includes(list=['any', 'thing']) }}

map

Creates a new list populated with the values of the selected attribute of every element in the input list.

For example, the source.diff.files context holds a list of FileDiff , each has new_file attribute. You can create a list of all the new file names by mapping to the new_file attribute and then check if there are changes to any handler.js file:

{{ source.diff.files | map(attr='new_file') | match(term='handler.js') | some }}

match

Return true for each element in the list that match the search term.

For example, to check if all code changes are in the tests directory:

{{ files | match(regex=r/tests\//) | every }}

For example, to check if there are code changes with specific function call:

{{ source.diff.files | match(attr='diff', term='myFunction') | some }}

nope

The inverse of every, checks whether all element in the list are false. In case the list of elements is empty, it will return false.

For example, check that no changes in either 'src' or 'dest' directories:

{{ files | match(list=['src', 'dest']) | nope }}

reject

Creates a shallow copy of a portion of a given list, filtered down to just the elements that does not match the given term. You can use either a single term, regex, or a list of terms to match with.

For example, check if all changes, but JavaScript files are in tests directory:

{{ files | reject(regex=r/\.js$/) | match(regex=r/tests\//') | every }}

For example, check if all changes except for config.json files are formatting:

{{ source.diff.files | reject(attr='new_file', regex=r/config\.json$/) | isFormattingChange }}

some

Checks whether any element in the list is true. In case the list of elements is empty it will return false.

{{ files | match(list=['src', 'dest']) | some }}

allDocs

Return true if the input list includes only documents based on file extensions.

Doc files extensions are: md, mkdown, txt, rst.

{{ files | allDocs }}

allImages

Return true if the input list includes only images based on file extensions.

Image file extensions are: svg, png, gif.

{{ files | allImages }}

allTests

Return true if the input list includes only tests based on file's path and name.

Test files must include the substring test or spec in its name or path.

{{ files | allTests }}

estimatedReviewTime

Returns the estimated review time in minutes based on statistical model. For the estimation the model uses additions and deletions statistics grouped by the file types and additional information about the commits and base branch.

{{ branch | estimatedReviewTime }}

extensions

Expects files and provide a list of all unique file extensions.

For example, check that only one file type was changed:

{{ files | extensions | length == 1 }}

explainRankByGitBlame

This filter helps to explain the results of rankByGitBlame, the output is in Markdown format that can be used in a PR comment.

For example:

automations:
  the_right_reviewer:
    if: 
      - true
    run:
      - action: add-reviewers@v1
        args:
          reviewers: {{ repo | rankByGitBlame(gt=50) }}
      - action: add-comment@v1
        args:
          comment: {{ repo | explainRankByGitBlame(gt=50) }}

isFirstCommit

Return true if it's the author first commit in the repo.

if: 
  - {{ repo.contributors | isFirstCommit(branch.author) }}
run: 
  - action: add-comment@v1
    args:
      comment: Welcome {{branch.author}}!

isFormattingChange

Return true if all file diffs are validated as formatting changes.

Support source code languages: JavaScript, TypeScript, JSON, YAML and HTML.

If changes in other formats detected, the filter will return false.

{{ source.diff.files | isFormattingChange }}

matchDiffLines

Checks diff for matching lines.

For example, to check if all the changes are of adding prints and ignore white spaces:

{{ source.diff.files | matchDiffLines(regex=r/^\+.*console\.log/, ignoreWhiteSpaces=true) | every }}

rankByGitActivity

Get list of contributors based on git-commit activity.

The repo context includes all the changed files, for each file it includes each contributor number of lines changed every week over the last 52 weeks, based on git-commit.

These functions compare each contributor changes per week and yield an average percentage of contribution for any given file. For example, in a certain week a file had 500 line changed, 200 by a first user, while 3 other users changed 100 lines each. So the score for the first user in that week will be 40 (200/500 in %). The function then average the score for each user for the selected time period.

Then you can use the thresholds to get the right reviewer.

Check if the branch author is a rookie

active_coders: {{ repo | rankByGitActivity(gt=50, weeks=12) }}

rankByGitBlame

Get list of contributors based on git-blame results

The repo context includes all the changed files, for each file it includes the contributors' percentage of lines in the file, based on git-blame.

This function sums all these percentages per user and yield an average percentage of contribution. Then you can use the thresholds to get the right reviewer.

The output lists the Git provider users, e.g., GitHub users, which are mapped from the Git users included in the git-blame output. When gitStream cannot map the Git user to a Git provider user it will be dropped from the output list, hence the list may contain less than 100% of the lines.

Example of the filter output, note the output are GitHub users in the example:

[
  "PopeyeUser",
  "olive_user",
  "BRUTUS_USER"
]

Get the most significant contributors for the PR files:

contributors: {{ repo | rankByGitBlame(gt=30) }}

Check if the branch author is a rookie

is_rookie: {{ repo | rankByGitBlame(lt=15) | match(term=branch.author) | some }}