Docs: Helm template function and "must" versions of functions

[thernstig]

https://helm.sh/docs/chart_template_guide/function_list/ has many must versions of functions, such as mustRegexMatch vs. regexMatch. The docs reads:

regexMatch panics if there is a problem and mustRegexMatch returns an error to the template engine if there is a problem.

As many of the function has these must equivalents it might be a good idea to explain somewhere in the docs what the above means, potentially with an example. I do not find it clear what difference I will see as a user if these functions fail. I "assume" I should rather use the must versions, but I am not sure.

[mattfarina]

@thernstig That's a good idea. I've moved the issue to the repository that holds the docs. It has less traffic and will hopefully be more likely to get attention.

[thernstig]

@mattfarina Thanks. Is there any chance you would know if must is preferred?

[bacongobbler]

Depends on the situation, really. Some cases would prefer an error when the regular expression does not match with the given pattern. Other times it's okay for no matches to be returned. Both will return an error if the regular expression fails to compile.

It's really up to you and your use case. There is no preference for one over the other.

For example... In many cases users will chain its output to default. That way if the function fails, they can use a default value. For example:

{{ default (now | date "01/01/2021") (toDate "01/01/2021" .Values.currentDate) }}

This is used as a common pattern to allow the user to override certain values, but default to a sane value when the user does not provide one.

[thernstig]

I see. I would have guessed that in the above case, if a user inserts an incorrect .Values.currentDate it would have been nicest to use the mustToDate still. The reason being, otherwise the Helm is installed with an unexpected value for the user.

But I agree it is situational still, and many might not agree with me there.

edit: Something along the lines what you explained above, with some improvements, would have been great as a general text for explanation of must vs non-must.

[johnlinvc]

One issue we got is when using mustRegexMatch as an assertion, it'll generate extra true (from the return value) in the rendered result. We need to add extra steps to get rid of the return value. For example

{{- $val := "val" -}}
{{- mustRegexMatch "a" $val -}}
{{- print $val -}} # outputs trueval 

A hack to fix this is discard the result with

{{- $val := "val" -}}
{{- mustRegexMatch "a" $val | toString | trunc 0 -}}
{{- print $val -}} # outputs val 

Does anyone have a better way to discard the result without using if ?

[bstrdsmkr]

Since this is still open with a question and I found it trying to understand the must variants, I think a common convention has evolved to assign the value to "_" and just forget it ever happened :smile:

{{- $_ := regexMatch "(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])?" $key }}

[thernstig]

@bacongobbler can the label "question" be removed? It is in the docs repo and it is a valid thing to document, as it is not clear what the difference are between the two (as visible by the replies in this thread). People might mistake it for a question when in it is rather a docs issue.

edit: To be clear this is not about regexMatch vs mustRegexMatch only. It is about all must variants and most functions have such an equivalent.

[ferm10n]

I found this while also trying to understand the difference.

I assumed one of them would throw some error, but they seem to behave the same. Both # {{ mustRegexMatch "^[0-9]+$" "abc" }} and # {{ regexMatch "^[0-9]+$" "abc" }} render to # false. At least while using helm install --dry-run --debug anyway.

So is this actually a bug too?

[jghiloni]

@ferm10n Those are both valid regexes, so there's no failure there. Try something like {{ mustRegexMatch "^[0-9$" "abc" }} and test. That's an actual error case.