Replies: 1 comment 6 replies
-
Yeah I agree - I've struggled to describe how it all works succinctly and clearly (and in fact I struggled to work out jq in the beginning till one day it 'clicked'). That said, from your description, I think it would help if I had some sort of terminology page with examples and diagrams. Open to suggestions / content to make it easier to learn... |
Beta Was this translation helpful? Give feedback.
6 replies
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
-
As someone who's spent the past two weeks trying to decipher the fundamental pattern of behaviour behind
yq
(andjq
, to a lesser degree) -- having grokked it now almost to my satisfaction -- I must confess I think a form of documentation appendix that functions as reference for certain things current manual rather informally (through examples) covers, would be a great addition.For instance, one may deduce that
+
inyq
functions much like injq
(which specifies it more formally), although nothing really explicitly refers tojq
documentation so it isn't clear that the former functions as the latter unless one is aware of the relationship between the two tools.Assuming one is not aware of the relationship, or assuming one hasn't understood what exactly
jq
calls a filter vs. an operator vs. one vs. multiple result -- and withyq
keeping silent on these things as well -- one can't expect people's intuition to make up for this much lack of specification, in my opinion.For example, I have deduced that
select
expects multiple inputs, if I define something called "multiple results" and "multiple inputs" where an input is a [YAML/JSON] node and "multiple" means "a collection of [inputs]" but specifically not a [YAML/JSON] sequence/array (herejq
seems to either be stepping on own toes referring to arrays liberally, implying both a multitude of results/inputs and a JSON array). This is very confusing to someone about to strap either tool on their belt. I certainly have spent hours before I understood this crucial difference.[ "foo", "bar" ] | select(. == "foo")
, for instance, does not produce two results where'bar'
is filtered from the array being piped in toselect
! This much may be obvious to someone who now understandsyq
just as I do, but to a beginner it's almost completely counter-intuitive, and they don't understand (yet) the distinction between ayq
processing sequence and an array specified in the document. In the former example, one single value that is the array is indeed piped toselect
but the latter actually selects based on the whole array, meaning the selection is done akin to "do I allow the entire array through as one single output element in the result, based on the predicate. == 'foo'
?"). That will do the wrong thing. Obviously, the right thing to do is to "splat" the array before passing it on toselect
, with "splat" being another alien termyq
seems to borrow from Ruby or Go of which I am expert at neither, and drop straight into the manual without giving it much further thought of definition. In case of the example, the right thing to do is[ "foo", "bar" ] | .[] | select(. == "foo")
.Also, one of the most important constructs in the query language used in
yq
, the pipe operator (is it a "filter"? a "function"?)|
, is again not explained very well, in particular with regards to its precedence (other than mentioning it's "very low") and, as importantly, its associativity, a term that would for an operator define whether it "binds left" or "right". The example with Sally and Bob inyq
documentation is very interesting but I still don't understand it.To sum this argument of mine up -- it would greatly help, IMO, if
yq
manual went more or at least in addition to what is there today, in direction of more formally defining the elements of its potent query language. It (the latter) deserves as much, given how it's a context-free language in its own right and is thus as complex as JavaScript. It conversely does not do it justice to leave it defined through examples and very loose terms that are being used interchangeable like "operator", "function", "array", "map", etc.Without a formal definition, I feel like I am stumbling in near-dark, forced to re-read Mike's awesome incantations that only he, the true master of
yq
, can design.Another example is the
tag
function (operator? filter?) where it's allowed to write. tag = $value
but not. tag
, former apparently being its own form of assignment operatortag =
of arity 2 (a binary operator like arithmetical+
) and latter being a different operator calledtag
which has arity of 1 (an unary operator) and syntactically expects a value on the left. The documentation seems to gloss over this or at least imply it's a given or should be apparent.I am also bringing this up because I think noone else should spend two weeks going through the same I did. Because I think in general syntactically-aware utilities like
yq
are a god-send vs. error-prone text-wrangling, so I'd like to make most use ofyq
and the like.Beta Was this translation helpful? Give feedback.
All reactions