Document behavior of %(), @(), $()

[AlexDaniel]

See rakudo/rakudo#1946 for a detailed description.

Currently we say:

Brackets are used to declare blocks. However, empty brackets will declare a hash.

That is why, in general, the %() form of declaring hashes is preferred.

Except that %() is not an empty hash :)

EDIT: hash, of course

[JJ]

The problem I see here is that there seems to be no safe way to declare an empty hash. I'll revise that issue for clarification, but it looks hard...

[JJ]

OK, I see. The safe way is using {}

[AlexDaniel]

I think %() should be documented as a separate trap right next to it. Yes, maybe it will be deprecated, but we should document what we have now.

[JJ]

Maybe not a trap, but a document with all that, maybe as part of language/variables.

[jdv]

Kind of a side issue - can we not call {} chars brackets - at least curly brackets or, better yet, braces
or curly braces. When I read bracket I think of [] chars.

[AlexDaniel]

@jdv yes, please see #2114.

[raiph]

Please note my latest StackOverflow attempt at formulating the precise {} hash vs block DWIM rule.

I'm going on a trip for a week, but if everyone is happy with it I will be happy to integrate it into the doc a couple weeks from now.

Imo the right way forward for the docs is to show respect for Larry's DWIM. This is consistent with jnthn's perspective and the majority of existing community usage and, I think, preferences, though I acknowledge some strong opinions against it. (I return to this aspect at the end of this comment.)

Perhaps the WAT side of this DWIM belongs on the traps page but I'm unsure. Please read the latest version of my Reddit discussion of this DWIM/WAT that complements my SO answer.

Imo the right way forward for the docs contributor style guide is to recommend use of the DWIM in all cases except where documenting the %(...) alternative and the hash routines. The current guide text contains multiple factual errors and points in the wrong direction imo:

Prefer the %() form of declaring hashes

Imo this should be "Prefer the {} form of declaring hashes".

my %hash := { this => "is", a => "hash" }; # Correct, but BAD
my %hash := %( this => "is", a => "hash" ); # GOOD

Imo this is inappropriately "disrespectful" to Larry's DWIM. (I get that the "disrespect" isn't emotive but just trying to be clear.)

Using the second form is more idiomatic

Idiom is natural to a native speaker. I'd argue that's much more {} than %().

and avoids confusion with blocks.

As we know, it unfortunately introduces confusion with %() which won't go away for a few years.

See also my discussion of strange consistency with hash subscripts and ugliness in pair literals in my reddit comment linked above.

This does not apply to empty hashes, which should be declared using {}:

Switching guidance to be use of the DWIM will eliminate this exception.

I understand that samcv and alex and others got burned over this dwim. I think that was down to poor doc. Perhaps my poor original SO answer didn't help. (Hopefully it's not so bad now.) I understand that what I'm saying almost certainly won't resonate for them. Getting burned a few times before the right mental model clicks leaves a lasting impression, especially if the right mental model still hasn't clicked.

But I'm hopeful that Larry's view (which is that the DWIM made sense), and the majority newbie view (which is that the DWIM is fine if no one tells them about it but rather just exposes them to it), and the view of some old hands (jnthn finds the DWIM simple and natural, as do many others including me), and the evident widespread use of this DWIM, and the prospect that improved doc and community understanding will be in place, are persuasive that disrespecting Larry's DWIM isn't the way to go but rather embracing it, at least for now, until we perhaps revisit this in another few years once %() has completed a deprecation cycle.

[JJ]

Sorry, what is WAT?

[JJ]

El sáb., 23 jun. 2018 a las 11:00, raiph (<notifications@github.com>) escribió:

Please note my latest attempt at formulating the {} hash vs block DWIM rule <https://stackoverflow.com/a/44102980/1077672>. I'm going on a trip for a week, but if everyone is happy with it I will be happy to integrate it into the doc a couple weeks from now.

if you want, we can assign it to you. I mostly agree with everything you say.

[rafaelschipiura]

@JJ A WAT is what you get for every DWIM. http://knowyourmeme.com/memes/wat

[rafaelschipiura]

#2632 related