3

In various web pages, I see references to jq functions with a slash and a number following them. For example:

walk/1

I found the above notation used on a stackoverflow page.

I could not find in the jq Manual page a definition as to what this notation means. I'm guessing it might indicate that the walk function that takes 1 argument. If so, I wonder why a more meaningful notation isn't used such as is used with signatures in C++, Java, and other languages:

<function>(type1, type2, ..., typeN)

Can anyone confirm what the notation <function>/<number> means? Are other variants used?

Community
  • 1
  • 1
Steve Amerige
  • 1,309
  • 1
  • 12
  • 28

1 Answers1

3

The notation name/arity gives the name and arity of the function. "arity" is the number of arguments (i.e., parameters), so for example explode/0 means you'd just write explode without any arguments, and map/1 means you'd write something like map(f).

The fact that 0-arity functions are invoked by name, without any parentheses, makes the notation especially handy. The fact that a function name can have multiple definitions at any one time (each definition having a distinct arity) makes it easy to distinguish between them.

This notation is not used in jq programs, but it is used in the output of the (new) built-in filter, builtins/0.

By contrast, in some other programming languages, it (or some close variant, e.g. module:name/arity in Erlang) is also part of the language.

Why?

There are various difficulties which typically arise when attempting to graft a notation that's suitable for languages in which method-dispatch is based on types onto ones in which dispatch is based solely on arity.

The first, as already noted, has to do with 0-arity functions. This is especially problematic for jq as 0-arity functions are invoked in jq without parentheses.

The second is that, in general, jq functions do not require their arguments to be any one jq type. Having to write something like nth(string+number) rather than just nth/1 would be tedious at best.

This is why the manual strenuously avoids using "name(type)"-style notation. Thus we see, for example, startswith(str), rather than startswith(string). That is, the parameter names in the documentation are clearly just names, though of course they often give strong type hints.

If you're wondering why the 'name/arity' convention isn't documented in the manual, it's probably largely because the documentation was mostly written before jq supported multi-arity functions.

In summary -- any notational scheme can be made to work, but name/arity is (1) concise; (2) precise in the jq context; (3) easy-to-learn; and (4) widely in use for arity-oriented languages, at least on this planet.

peak
  • 105,803
  • 17
  • 152
  • 177
  • 1
    As _arity_ is not used in jq programs, why is this notation used in jq discussions? More meaningful notations are possible that would help formalize the manual. For example, in the manual, one sees `startswith(str)`. Since the allowed types in jq are precisely defined as one of `null|boolean|number|string|array|object`, then I would think `startswith(string)` would be better than `startswith/1` or what is in the manual now. `element` could be used to mean "any type". One could explicitly specify alternates as in `string|array`. `(void)` or _omitted_ could specify 0 arguments. Thanks! – Steve Amerige Jan 22 '17 at 15:50
  • @SteveAmerige That's a different question than what the notation means. If you want to know *why* it is used, that's best taken up with the author of `jq`. – chepner Jan 22 '17 at 17:01
  • @chepner Agreed. I voted up and accepted the answer. I will try to find out why as well. But, you're right, I got the answer to the question that I asked. Happy days! – Steve Amerige Jan 22 '17 at 17:06
  • There is a now (one year later) a hint in the manual listed under "builtins". Since the main gurus of jq all use this shorthand in their examples and discussions, this is a major barrier to entry for lowly noobs such like myself. Feeling like Alice at the tea party. – charles ross Feb 26 '18 at 14:54
  • @CharlesRoss - So perhaps you can explain why a raven is like a writing desk? Scones? – peak Feb 26 '18 at 15:23
  • nevar! you made me lookitup. – charles ross Feb 26 '18 at 18:53