Documentation
¶
Overview ¶
Package expr evaluates GitHub Actions style `if:` conditions under three-valued logic. A reference that the caller's Facts cannot resolve yields Unknown rather than a guess, so callers can tell "this condition is provably false" from "we don't have enough information to know."
The grammar is the subset of GitHub's expression syntax actually used in job and step conditions: boolean literals, string literals in single quotes, dotted references (including `.*.name` collection references), the operators `==`, `!=`, `&&`, `||`, `!`, parentheses, and the functions contains, startsWith and endsWith. Anything outside that grammar parses as an unknown leaf instead of failing, since a condition this package cannot parse is exactly the kind of condition it should refuse to decide on.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ComparedLiteral ¶
ComparedLiteral is the string literal the first of refs (any of them) is compared against in expression, read off that very comparison node: `ref == 'x'`, `'x' == ref`, `ref != 'x'`, or a contains / startsWith / endsWith call whose first argument is the reference and whose second is the literal. ok is false when no reference of refs is compared to a literal (compared to another reference, or not compared at all).
func ComparedLiterals ¶
ComparedLiterals is every string literal any of refs is compared against in expression, in source order, read off the same comparison shapes as ComparedLiteral. Empty when none is.
func HasStatusCall ¶
HasStatusCall reports whether expression calls a job status function that makes GitHub run the job even when a job it needs was skipped: always(), failure() or cancelled() anywhere, or success() under a negation (a plain success() is the default and changes nothing). Function names are case-insensitive, as GitHub reads them. A status call the grammar could not place (it sits inside a fragment parsed as unknown) counts too: reading a status call where there is none only keeps a predecessor's gate from closing the job, never the reverse.
Types ¶
type Comparison ¶
Comparison is one comparison of a reference to a string literal: Negated when the condition holds with the two different (`!=`, or an odd number of `!` around it), not when it holds with them equal (`==`, a contains / startsWith / endsWith call).
func Comparisons ¶
func Comparisons(expression string, refs []string) []Comparison
Comparisons is every comparison of any of refs to a string literal in expression, in source order, read off the same shapes as ComparedLiteral, with its polarity.
type Facts ¶
Facts resolves a dotted reference such as "github.event_name" or "needs.policy.outputs.run" to its string value. known is false when the reference has no value in the facts the caller has available, which is distinct from the reference resolving to an empty string.
type Value ¶
type Value int
Value is the result of evaluating a condition under three-valued logic.
func Eval ¶
Eval evaluates expression against f and returns its three-valued result. An expression wrapped in "${{ ... }}" has the wrapper stripped first. An empty expression (no "if:" present) evaluates to True, since an absent condition runs unconditionally. Anything the grammar does not cover evaluates to Unknown rather than panicking.
Source Files