result of `map list [1 2 3]`? (documentation enhancement request)

[alan-isaac]

map list [1 2 3] behaves as desired, producing [[1] [2] [3]]. But, is this guaranteed? I have not been able to deduce it from the documentation. E.g., one might expect to have to use [# -> (list #)] instead of just list. And similarly for multiple lists (more than 2). Of course the existing behavior is much better!

[SethTisue]

https://docs.netlogo.org/7.0.4/dictionary#map says:

reporter may be an anonymous reporter or the name of a reporter

and it's illustrated in an example using map round ...

was there somewhere else specific that you looked, expecting to find this documented...?

[ERSUCC]

I think the relevant place in the docs is here. This section makes it clear under which circumstances you are allowed to use the condensed version.

[alan-isaac]

I cannot get to a guarantee from those docs, and I already am familiar with the "concise syntax". I doubt I am alone. Could you please add an example using list to make it an explicit behavioral promise. (The one I provided above would suffice.)

[alan-isaac]

@SethTisue But they have different arity: round is unary, and list by default is binary. E.g., print list 1 is an error.

[ERSUCC]

Adding another example with list seems like a slippery slope. What about + and -, or word, or any of the other reporters in the language for which this syntax is valid? We shouldn't have to add examples for every single primitive just to prove that the behavior is consistent. I think the confusion here is why the parentheses are not needed, but it's not a core part of the use of the list primitive, it just tells NetLogo how to apply the arguments correctly when it's used in context with other primitives. In the case of this concise syntax, no parentheses are needed because it is already clear that exactly one argument will be provided to the list primitive each time it is invoked. If I'm correct about this confusion, then I agree that it could be made a bit more clear in the docs.

[alan-isaac]

@ERSUCC See my comment to Seth. And in fact, + and - do not work when mapped over a single list, yet list and word do. This of course is entirely understandable and desirable, since they are variadic, but I believe it cannot be deduced from the existing docs because they are binary by default.

[SethTisue]

Ah, it's the arity that concerns you! I hadn't understood that from your original report.

I don't see a need to modify the entry for map (or its cousins), but in the "Concise Syntax" section Isaac linked to, I think it would make sense to add:

The concise syntax only works if the primitive or reporter procedure in question can accept exactly one argument — either because it always accepts exactly one, or because it is variadic.

The word "variadic" has already been defined above.

I have no strong opinion on whether an additional example using a variadic primitive is needed.

Note the "or reporter procedure". I checked that this does in fact work:

to-report square [n]
  report n * n
end

observer> show map square [1 2 3]
observer: [1 4 9]

whether that also merits an additional example, no strong opinion either way.

[alan-isaac]

@SethTisue Yes, I think that also deserves explicit documentation! (I think it has only been true since version 6.0.)