But I think Loops' point is that nowhere in the documentation of join makes the above explicit.
Nice attempt at mind reading. Unfortunately, based on private messages that Loops and I exchanged, I believe you are wrong. But beyond guessing at one person's intent, I also disagree with your implied expectation.
Show me anywhere in the Perl documentation where it makes it clear that a specific argument to a specific function is not magical like the first arguments to map/grep. Rather, the Perl documentation covers how expressions yield values and values are passed as arguments to functions. I really don't think it behooves the Perl documentation to repeatedly call out that "this particular argument to this particular function is ordinary and not magical like this other, rare case".
Now we have to document that kill( signal(), @pids ) doesn't magically call signal() over and over to get a different signal for each PID? That chown( uid(), gid(), @files ) doesn't call uid() and gid() over and over again? That pack "I5", foo() doesn't magically call foo() 5 times?
Does return need to document that sub foo { return bar() } $foo = foo(); print $foo, $foo; doesn't call bar() twice, potentially passing two different values to print? That split( sep(), $str ) doesn't get a fresh regex to match at each step?
Given that johngg's code demonstrates that the behaviour of join in this regard has actually changed recently, it's not unreasonable to expect this behaviour to now be documented and ensured by the test suite.
Yes, I believe it is unreasonable to bloat the documentation with such an explanation. To document that, you'd actually have to add to the join documentation, a summary of what a tied scalar even is and, really, some demonstration code. You'd end up with the explanation of this one optimization quirk constituting over 80% of the documentation of join(), obscuring the crux of what join() does to many readers. Or, if you add a much shorter explanation of this quirk, then you'll just have made the documentation potentially very confusing to many readers.
The join documentation actually provides us with an example of specifically declaring what one argument isn't: 'Beware that unlike "split", "join" doesn't take a pattern as its first argument'. I think a much better version of that would not use the word "beware" as I don't see how this constitutes any type of trap. Unlike split(), join() doesn't take a regex pattern as its first argument because join() isn't matching (parts of) strings and so taking a regex pattern would simply make no sense. If you thought join() took a regex pattern, then you really didn't think about it very clearly. "Of course" belongs in that sentence more than "beware".
At least that sentence is very short and so doesn't directly distract much. Though I think the documentation would be better without it (at least as worded). The word "pattern" is quite out of context in that short documentation. That sentence might be clear if one had just finished reading split before reading join. Otherwise, one could easily not be clear that "pattern" means "regex" and be worried about why this matters. It would be better if that sentence made it clear that you don't need to understand the split documentation to understand what join does, because that means understanding 14 times as much documentation!
Adding tied variables and optimization quirks would be a much worse mistake.
- tye
In reply to Re^5: Undocumented join() feature, now defunct? (docs)
by tye
in thread Undocumented join() feature, now defunct?
by johngg
| For: | Use: | ||
| & | & | ||
| < | < | ||
| > | > | ||
| [ | [ | ||
| ] | ] |