Fix manual on paths/1 to use boolean filter for its argument #2678
Conversation
| `paths(f)` outputs the paths to any values for which `f` is true. | ||
| That is, `paths(numbers)` outputs the paths to all numeric | ||
| `paths(f)` outputs the paths to any values for which `f` is `true`. | ||
| That is, `paths(type == "number")` outputs the paths to all numeric |
There was a problem hiding this comment.
This got me thinking that i several times wanted to have is_number etc functions, for fq i have these https://github.com/wader/fq/blob/d15a41f9430f869dc6d11ac360f56c29e3a1b45e/pkg/interp/internal.jq#L147C1-L153 because i kept needing it
There was a problem hiding this comment.
def paths(node_filter): . as $dot|paths|select(. as $p|$dot|getpath($p)|node_filter);
f doesn't have to output true -- it just has to not be empty or null.
There was a problem hiding this comment.
I mean, maybe that's a bug...
But separately from that, jq considers any non-null, non-empty [EDIT: and non-false] value to be "trueish".
There was a problem hiding this comment.
Also empty is not really a falsish value, it really stops execution for that expression. e.g. if empty then "yes" else "no" end outputs nothing, not "no". Anyway, this is all intended in my opinion. false and null are the only false values, and empty works as it should, and when you use it inside select() it is effectively the same as false.
There was a problem hiding this comment.
As a user manual, it is enough to mention that the filter works well with boolean filter arguments. No need to mention all its behaviors.
There was a problem hiding this comment.
Yes, speaking of "empty values" is not exactly accurate. It's a bit of a colloquialism in jq speak. In the context of select/1 though, empty really is falseish :)
There was a problem hiding this comment.
@wader I'm not sure that it's a good idea to document all the places where trueish values work, yeah.
|
Thanks! |
The manual of
paths/1explains its usage the argument filter yields a boolean. Nevertheless the following sentence uses non-boolean filternumbersand also the definition ofleaf_pathsfilter was wrong (#1163). The filterleaf_pathswas deprecated 9 years ago and was removed in #2666. There is still remaining confusing manual so I fixed it in this PR. Along with #2666, this PR resolves #2288.