doc.go RawHistoryFolder

1// SPDX-License-Identifier: MIT
2
3// Regenerate the case-mapping tables (needs node; see gen/casing_dump.mjs).
4//go:generate sh -c "node gen/casing_dump.mjs | go run gen/casing.go -o casing_tables.go"
5
6// Package expr implements GitHub Actions expressions: the language found
7// between the braces of ${{ }} in workflow files.
8//
9// The behaviour is that of the C# runner (actions/runner, MIT), the
10// implementation that evaluates expressions on github.com: its tokenizer and
11// parser, error messages, coercions, case-insensitive comparison, number
12// formatting, JSON reader and writer, and built-in functions. It was first
13// ported from GitHub's editor library, the npm package @actions/expressions
14// (MIT, actions/languageservices), then checked against the runner on 34 765
15// expressions and against the shared cross-language fixtures; where the two
16// differ, the runner wins. PORTING.md lists every difference with the C#
17// source that decides it.
18//
19// The entry points are [Parse], which turns the text of one expression into a
20// [Node], and [Evaluate], which computes its [Value] against the named
21// contexts and functions of an [EvalContext]:
22//
23//	node, err := expr.Parse("github.ref == 'refs/heads/main'", []string{"github"}, nil)
24//	if err != nil { /* *expr.Error */ }
25//	v, err := expr.Evaluate(ctx, node, expr.EvalContext{Contexts: map[string]expr.Value{"github": github}})
26//	if err != nil { /* *expr.EvalError */ }
27//	if expr.Truthy(v) { /* ... */ }
28//
29// Values are the JSON-like [Null], [Boolean], [Number], [String], [*Array]
30// and [*Dictionary]. Dictionaries keep insertion order and look keys up
31// case-insensitively. [FromJSON] and [ToJSON] convert to and from JSON text
32// exactly as the fromJSON and toJSON functions do.
33//
34// Evaluation is bounded: [Evaluate] honours its context.Context and stops
35// when the strings and filtered arrays it builds exceed
36// [EvalContext.MaxResultBytes] (default [MaxResultBytes]); the parser limits
37// length and nesting ([MaxExpressionLength], [MaxParserDepth]).
38package expr