forgejo/modules/util
wxiaoguang 5b89670a31
Use a general Eval function for expressions in templates. (#23927)
One of the proposals in #23328

This PR introduces a simple expression calculator
(templates/eval/eval.go), it can do basic expression calculations.

Many untested template helper functions like `Mul` `Add` can be replaced
by this new approach.

Then these `Add` / `Mul` / `percentage` / `Subtract` / `DiffStatsWidth`
could all use this `Eval`.

And it provides enhancements for Golang templates, and improves
readability.

Some examples:

----

* Before: `{{Add (Mul $glyph.Row 12) 12}}`
* After: `{{Eval $glyph.Row "*" 12 "+" 12}}`

----

* Before: `{{if lt (Add $i 1) (len $.Topics)}}`
* After: `{{if Eval $i "+" 1 "<" (len $.Topics)}}`

## FAQ

### Why not use an existing expression package?

We need a highly customized expression engine:

* do the calculation on the fly, without pre-compiling
* deal with int/int64/float64 types, to make the result could be used in
Golang template.
* make the syntax could be used in the Golang template directly
* do not introduce too much complex or strange syntax, we just need a
simple calculator.
* it needs to strictly follow Golang template's behavior, for example,
Golang template treats all non-zero values as truth, but many 3rd
packages don't do so.

### What's the benefit?

* Developers don't need to add more `Add`/`Mul`/`Sub`-like functions,
they were getting more and more.
Now, only one `Eval` is enough for all cases.
* The new code reads better than old `{{Add (Mul $glyph.Row 12) 12}}`,
the old one isn't familiar to most procedural programming developers
(eg, the Golang expression syntax).
* The `Eval` is fully covered by tests, many old `Add`/`Mul`-like
functions were never tested.

### The performance?

It doesn't use `reflect`, it doesn't need to parse or compile when used
in Golang template, the performance is as fast as native Go template.

### Is it too complex? Could it be unstable?

The expression calculator program is a common homework for computer
science students, and it's widely used as a teaching and practicing
purpose for developers. The algorithm is pretty well-known.

The behavior can be clearly defined, it is stable.
2023-04-07 21:25:49 +08:00
..
filebuffer Implement FSFE REUSE for golang files (#21840) 2022-11-27 18:20:29 +00:00
error.go Use ErrInvalidArgument in packages (#22268) 2022-12-31 12:49:37 +01:00
file_unix.go Implement FSFE REUSE for golang files (#21840) 2022-11-27 18:20:29 +00:00
file_unix_test.go Implement FSFE REUSE for golang files (#21840) 2022-11-27 18:20:29 +00:00
file_windows.go Implement FSFE REUSE for golang files (#21840) 2022-11-27 18:20:29 +00:00
io.go Improve checkIfPRContentChanged (#22611) 2023-01-28 15:54:40 +00:00
keypair.go Add Chef package registry (#22554) 2023-02-06 09:49:21 +08:00
keypair_test.go Use minio/sha256-simd for accelerated SHA256 (#23052) 2023-02-22 14:21:46 -05:00
legacy.go Implement FSFE REUSE for golang files (#21840) 2022-11-27 18:20:29 +00:00
legacy_test.go Implement FSFE REUSE for golang files (#21840) 2022-11-27 18:20:29 +00:00
pack.go Add support for incoming emails (#22056) 2023-01-14 23:57:10 +08:00
pack_test.go Add support for incoming emails (#22056) 2023-01-14 23:57:10 +08:00
paginate.go Implement FSFE REUSE for golang files (#21840) 2022-11-27 18:20:29 +00:00
paginate_test.go Implement FSFE REUSE for golang files (#21840) 2022-11-27 18:20:29 +00:00
path.go Introduce path Clean/Join helper functions (#23495) 2023-03-21 16:02:49 -04:00
path_test.go Introduce path Clean/Join helper functions (#23495) 2023-03-21 16:02:49 -04:00
remove.go Implement FSFE REUSE for golang files (#21840) 2022-11-27 18:20:29 +00:00
sanitize.go Implement FSFE REUSE for golang files (#21840) 2022-11-27 18:20:29 +00:00
sanitize_test.go Implement FSFE REUSE for golang files (#21840) 2022-11-27 18:20:29 +00:00
sec_to_time.go Implement FSFE REUSE for golang files (#21840) 2022-11-27 18:20:29 +00:00
sec_to_time_test.go Implement FSFE REUSE for golang files (#21840) 2022-11-27 18:20:29 +00:00
shellquote.go Implement FSFE REUSE for golang files (#21840) 2022-11-27 18:20:29 +00:00
shellquote_test.go Implement FSFE REUSE for golang files (#21840) 2022-11-27 18:20:29 +00:00
slice.go Improve utils of slices (#22379) 2023-01-11 13:31:16 +08:00
slice_test.go Improve utils of slices (#22379) 2023-01-11 13:31:16 +08:00
string.go Implement FSFE REUSE for golang files (#21840) 2022-11-27 18:20:29 +00:00
string_test.go Implement FSFE REUSE for golang files (#21840) 2022-11-27 18:20:29 +00:00
timer.go Implement FSFE REUSE for golang files (#21840) 2022-11-27 18:20:29 +00:00
truncate.go Introduce GiteaLocaleNumber custom element to handle number localization on pages. (#23861) 2023-04-03 12:58:09 -04:00
truncate_test.go Introduce GiteaLocaleNumber custom element to handle number localization on pages. (#23861) 2023-04-03 12:58:09 -04:00
url.go Implement FSFE REUSE for golang files (#21840) 2022-11-27 18:20:29 +00:00
util.go Use a general Eval function for expressions in templates. (#23927) 2023-04-07 21:25:49 +08:00
util_test.go Introduce GiteaLocaleNumber custom element to handle number localization on pages. (#23861) 2023-04-03 12:58:09 -04:00