Skip to content

Commit 343ebe0

Browse files
PavelLinearBPavelLinearB
authored
Merge pull request #621 from linear-b/fine/add-readfile-filter
Add readFile Function to Filter
2 parents c90a332 + f2411ff commit 343ebe0

File tree

1 file changed

+101
-25
lines changed

1 file changed

+101
-25
lines changed

‎docs/filter-functions.md

Lines changed: 101 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ The following functions are supported in addition to the built-in functions prov
2020

2121
| Function | Input | Args | Output |
2222
| -------------------------------------------------------------------------------------------------------------- | ---------------------- | ------------------------------- | ---------------------- |
23-
| [`capture`](#capture)<br />Find and return the first occurrence of a regex in the input string | String | `regex` | String |
23+
| [`capture`](#capture)<br />Find and return the first occurrence of a regex in the input string | String | `regex` | String |
2424
| [`difference`](#difference)<br />Given two lists, keep only items that are in the 1st list but not in the 2nd. | [Objects] | `list` | [Objects] |
2525
| [`every`](#every)<br />Checks whether all element in the list are `true` | [Bool] | - | Bool |
2626
| [`filter`](#filter)<br />Reduce list of items into a list of same items that match the specified term | [String]<br />[Object] | `regex`, `term`, `list`, `attr` | [String]<br />[Object] |
@@ -32,32 +32,33 @@ The following functions are supported in addition to the built-in functions prov
3232
| [`reject`](#reject)<br />Inverse of [`filter`](#filter), the result list contains non-matching items | [String]<br />[Object] | `regex`, `term`, `list`, `attr` | [String]<br />[Object] |
3333
| [`some`](#some)<br />Checks whether at least one element in the list is `true` | [Bool] | - | Bool |
3434

35+
3536
</div>
3637

3738
### High level functions
3839

3940
<div class="big-summary" markdown=1>
4041

41-
| Function | Input | Args | Output |
42-
| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ---------------------------- | ----------------------- |
43-
| [`allDocs`](#alldocs)<br />Checks the list includes only documents | [`files`](./context-variables.md#files) | - | Bool |
44-
| [`allImages`](#allimages)<br />Checks the list includes only images | [`files`](./context-variables.md#files) | - | Bool |
45-
| [`allTests`](#alltests)<br />Checks the list includes only tests | [`files`](./context-variables.md#files) | - | Bool |
46-
| [`codeExperts`](#codeexperts)<br />Get list of contributors based on expert reviewer model results | [`repo`](./context-variables.md#repo) | `gt`, `lt` | [String] |
47-
| [`decode`](#decode)<br />Decode Base64 encoded string into an object | String (Base64 encoded) | - | Object |
48-
| [`encode`](#encode)<br />Encode data into Base64 encoded string | Object | - | String (Base64 encoded) |
49-
| [`estimatedReviewTime`](#estimatedreviewtime)<br />Estimated review time in minutes | [`branch`](./context-variables.md#branch) | - | Integer |
50-
| [`extensions`](#extensions)<br />Lists all the unique file extensions | [String] | - | [String] |
51-
| [`extractJitFindings`](#extractjitfindings) :fontawesome-brands-github: <br />Get an object with a summary of the findings found by the Jit scan | [`pr`](./context-variables.md#pr) | - | Object |
52-
| [`extractSonarFindings`](#extractsonarfindings) :fontawesome-brands-github: <br />Get an object with a summary of the findings found by the SonarCloud scan | [`pr`](./context-variables.md#pr) | - | Object |
53-
| [`explainRankByGitBlame`](#explainrankbygitblame)<br />Short markdown text explaining rankByGitBlame results | [`repo`](./context-variables.md#repo) | `gt`, `lt` | [String] |
54-
| [`isFirstCommit`](#isfirstcommit)<br />Checks if its the author first commit in the repo | [`repo.contributors`](./context-variables.md#repo) | String | Bool |
55-
| [`isFormattingChange`](#isformattingchange)<br />Checks that only formatting changed | [[`FileDiff` ](./context-variables.md#filediff-structure)] | - | Bool |
56-
| [`mapToEnum`](#maptoenum)<br />return the enum value matches to the input key | String | Enum object | Object |
57-
| [`matchDiffLines`](#matchdifflines)<br />Match every line in diff | [[`FileDiff` ](./context-variables.md#filediff-structure)] | `regex`, `ignoreWhiteSpaces` | [Bool] |
58-
| [`rankByGitActivity`](#rankbygitactivity)<br />Get list of contributors based on `git-commit` activity | [`repo`](./context-variables.md#repo) | `gt`, `lt` | [String] |
59-
| [`rankByGitBlame`](#rankbygitblame)<br />Get list of contributors based on `git-blame` results | [`repo`](./context-variables.md#repo) | `gt`, `lt` | [String] |
60-
42+
| Function | Input | Args | Output |
43+
| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | -------------------------------------------------- | ----------------------- |
44+
| [`allDocs`](#alldocs)<br />Checks the list includes only documents | [`files`](./context-variables.md#files) | - | Bool |
45+
| [`allImages`](#allimages)<br />Checks the list includes only images | [`files`](./context-variables.md#files) | - | Bool |
46+
| [`allTests`](#alltests)<br />Checks the list includes only tests | [`files`](./context-variables.md#files) | - | Bool |
47+
| [`codeExperts`](#codeexperts)<br />Get list of contributors based on expert reviewer model results | [`repo`](./context-variables.md#repo) | `gt`, `lt` | [String] |
48+
| [`decode`](#decode)<br />Decode Base64 encoded string into an object | String (Base64 encoded) | - | Object |
49+
| [`encode`](#encode)<br />Encode data into Base64 encoded string | Object | - | String (Base64 encoded) |
50+
| [`estimatedReviewTime`](#estimatedreviewtime)<br />Estimated review time in minutes | [`branch`](./context-variables.md#branch) | - | Integer |
51+
| [`extensions`](#extensions)<br />Lists all the unique file extensions | [String] | - | [String] |
52+
| [`extractJitFindings`](#extractjitfindings) :fontawesome-brands-github: <br />Get an object with a summary of the findings found by the Jit scan | [`pr`](./context-variables.md#pr) | - | Object |
53+
| [`extractSonarFindings`](#extractsonarfindings) :fontawesome-brands-github: <br />Get an object with a summary of the findings found by the SonarCloud scan | [`pr`](./context-variables.md#pr) | - | Object |
54+
| [`explainRankByGitBlame`](#explainrankbygitblame)<br />Short markdown text explaining rankByGitBlame results | [`repo`](./context-variables.md#repo) | `gt`, `lt` | [String] |
55+
| [`isFirstCommit`](#isfirstcommit)<br />Checks if its the author first commit in the repo | [`repo.contributors`](./context-variables.md#repo) | String | Bool |
56+
| [`isFormattingChange`](#isformattingchange)<br />Checks that only formatting changed | [[`FileDiff` ](./context-variables.md#filediff-structure)] | - | Bool |
57+
| [`mapToEnum`](#maptoenum)<br />return the enum value matches to the input key | String | Enum object | Object |
58+
| [`matchDiffLines`](#matchdifflines)<br />Match every line in diff | [[`FileDiff` ](./context-variables.md#filediff-structure)] | `regex`, `ignoreWhiteSpaces` | [Bool] |
59+
| [`rankByGitActivity`](#rankbygitactivity)<br />Get list of contributors based on `git-commit` activity | [`repo`](./context-variables.md#repo) | `gt`, `lt` | [String] |
60+
| [`rankByGitBlame`](#rankbygitblame)<br />Get list of contributors based on `git-blame` results | [`repo`](./context-variables.md#repo) | `gt`, `lt` | [String] |
61+
| [`readFile`](#readfile)<br />Reads the contents of a file from the current branch or "cm" folder | String - The file path | String (optional) - the file type. `txt` or `json` | String |
6162
</div>
6263

6364
### Named arguments
@@ -234,13 +235,15 @@ Return `true` for each element in the list that match the search term.
234235

235236
</div>
236237

237-
For example, to check if all code changes are in the `tests` directory:
238+
Examples:
239+
240+
Check if all code changes are in the `tests` directory:
238241

239242
```yaml+jinja
240243
{{ files | match(regex=r/tests\//) | every }}
241244
```
242245

243-
For example, to check if there are code changes with specific function call:
246+
Check if there are code changes with specific function call:
244247

245248
```yaml+jinja
246249
{{ source.diff.files | match(attr='diff', term='myFunction') | some }}
@@ -280,13 +283,15 @@ Creates a shallow copy of a portion of a given list, filtered down to just the e
280283

281284
</div>
282285

283-
For example, check if all changes, but JavaScript files are in tests directory:
286+
Examples:
287+
288+
Check if all changes, but JavaScript files are in tests directory:
284289

285290
```yaml+jinja
286291
{{ files | reject(regex=r/\.js$/) | match(regex=r/tests\//') | every }}
287292
```
288293

289-
For example, check if all changes except for `config.json` files are formatting:
294+
Check if all changes except for `config.json` files are formatting:
290295

291296
```yaml+jinja
292297
{{ source.diff.files | reject(attr='new_file', regex=r/config\.json$/) | isFormattingChange }}
@@ -911,3 +916,74 @@ Check if the branch author is a rookie
911916
```yaml+jinja
912917
is_rookie: {{ repo | rankByGitBlame(lt=15) | match(term=branch.author) | some }}
913918
```
919+
920+
#### `readFile`
921+
922+
Reads the contents of a file from the current branch or the `cm` repo and returns it as a string.
923+
924+
<div class="filter-details" markdown=1>
925+
926+
| Argument | Usage | Type | Description |
927+
| -------- | ------ | ------ | ------------------------------------------------------------------- |
928+
| - | Input | String | The relative file path in the current repo. Prepend `../cm/` to get files from the `cm` repo |
929+
| `output` | Input | String | The content type. Optional, `txt` by default. Allowed options are `txt` or `json`. When using `json`, the output will be returned as a stringified Object |
930+
| - | Output | String | The contents of the file as a String. In case of `json` output, the result will be `JSON.stringified` |
931+
</div>
932+
933+
Examples:
934+
935+
Add a comment with a file's content:
936+
937+
```yaml+jinja
938+
automations:
939+
add_readme_comment:
940+
if:
941+
- true
942+
run:
943+
- action: add-comment@v1
944+
args:
945+
comment: |
946+
{{ README_CONTENT }}
947+
948+
README_CONTENT: {{ "./README.md" | readFile() }}
949+
```
950+
951+
Read JSON configuration file from the `cm` repo and use some of the properties in a comment:
952+
```
953+
automations:
954+
describe_teams:
955+
if:
956+
- {{ true }}
957+
run:
958+
- action: add-comment@v1
959+
args:
960+
comment: |
961+
We have {{ TEAMS | length }} teams with {{ TEAMS.front.members | length + TEAMS.back.members | length }} members in total:
962+
FrontEnd: include {{ TEAMS.front.members | length }} members
963+
BackEnd: include {{ TEAMS.back.members | length }} members
964+
965+
966+
TEAMS: {{ "../cm/TEAMS.json" | readFile(output="json") }}
967+
```
968+
969+
Configuration file example:
970+
``` JSON
971+
{
972+
"front": {
973+
"name": "Frontend",
974+
"description": "Frontend team",
975+
"members": [
976+
"John",
977+
"Jane"
978+
]
979+
},
980+
"back": {
981+
"name": "Backend",
982+
"description": "Backend team",
983+
"members": [
984+
"Alice",
985+
"Bob"
986+
]
987+
}
988+
}
989+
```

0 commit comments

Comments
 (0)