expression documentation needs more information

[brucejo75]

Moved from https://github.com/caddyserver/caddy/issues/4641

---

Going through my monthly hair tear out trying to program my Caddyfile discovered how expressions need to be formatted.

Examples here are either misleading or incomplete. None of these examples put the expression within a string.

When looking through the forums everyone encloses their expressions within a string.

Without enclosing in a string my expression did not work.

bad: @myNamedMatcher expression {my_placeholder} == "0"
good: @myNamedMatcher expression `{my_placeholder} == "0"`

Request: please update the documentation with examples that enclose the expressions within strings and explain when/why enclosing strings are needed.

Thanks!

[mholt]

Not many people use the expression matcher (that we know of) -- and it's still experimental. Sorry if the documentation is not quite accurate.

@francislavoie I haven't looked recently, but I assume we are thinking the entire expr will be in a single token. We could either do a join() on the remaining args assuming that the whole line is an expression, or continue to require the entire expression in a single token (but then our docs are wrong). What do you think we should do? I'm leaning toward the join() solution since it avoids having to wrap an expression that might use quotes in strings.

[brucejo75]

My opinion: just document it as-is. It works great when you know that. Work on the bigger fish.

[brucejo75]

PS: expression matcher is excellent!

[francislavoie]

Actually we do a join @mholt but the issue is that since " has a meaning in the Caddyfile as a string delimiter (the Caddyfile parser looks at each token before dispensing them), the expression as parsed by Caddy becomes {my_placeholder} == 0 i.e. the number 0 instead of the string "0". And I think comparing as the wrong type fails. (As an aside it would be possible to cast the number to a string and not use any ")

But yeah we can improve the docs for sure.

[mholt]

@francislavoie Ah, thanks for reminding me 🤦‍♂️ Yeah... I mean, the docs do talk about tokens and parsing, but maybe we could clarify strings a bit around the expression matcher.

[mholt]

Ok we got this improved in caddyserver/caddy#4643. Thanks Francis!

[brucejo75]

Wow! OK