language/operators#postcircumfix_<> is misleading.

[0rir]

docs.raku.org/language/operators#postcircumfix_<>

should be

docs.raku.org/language/operators#postfix_<>

And the first sentence there has an unhelpful comma, which could be eliminated with something like:

When applied to a container, the decont operator will return the
value it contains; when applied to a value it returns the value.

I use "decont" because it's in the glossary. In the text above "container" could link to https://docs.raku.org/language/containers. The rest has to do with my best understanding of 'value' as a thing specific to Raku.

[grizzlysmit]

On 13/7/22 02:31, rir wrote:

docs.raku.org/language/operators#postcircumfix_<>

should be

docs.raku.org/language/operators#postfix_<>

And the first sentence there has an unhelpful comma, which could be eliminated with something like:

|When applied to a container, the decont operator will return the
value it contains; when applied to a value it returns the value.|

|that is less clear not more clear|

||

I use "decont" because it's in the glossary. In the text above "container" could link to https://docs.raku.org/language/containers. The rest has to do with my best understanding of 'value' as a thing specific to Raku.

— Reply to this email directly, view it on GitHub https://github.com/Raku/doc/issues/4096, or unsubscribe https://github.com/notifications/unsubscribe-auth/ACE6J5QGVDLJ5VBG74RUNRTVTWMVZANCNFSM53LUQAWA. You are receiving this because you are subscribed to this thread.Message ID: @.***>

--

.~. There are many things that I love.... /V\ but God Comes way above all else❣❣❣❣ /( )\ Francis (Grizzly) Smit ^^-^^ http://www.smit.id.au/

[raiph]

postcircumfix:<> should be postfix:<>

I'm not sure what you mean.

Is your suggestion a pedagogical facilitation ("to make life easier for everyone")?

I am concerned about the underlying reality as in, eg, this SO by jnthn:

The logic to handle ... the zen slice ... is located in the array indexing operator, which is implemented as the multiple-dispatch subroutine postcircumfix:<[ ]>

I get that you're talking about the associative array zen slice, not the positional array zen slice, but I'm presuming the same principle applies. Is my presumption wrong?

[0rir]

@raiph, I am referencing the less used decontainerization operator not the word quoting associative indexing operator; that is $a<> not %a< >.

At a quick try, the decont operator allows whitespace and can only be applied to scalar containers and values.

[0rir]

that is less clear not more clear

@grizzlysmit, neither mine nor the original are so clear. Thanks for showing me how my post misses its mark.

Here is the current doc:

Decontainerization operator, which extracts the value from a container and makes it independent of the container type.

This is a fair description but its simplicity is too seductive. 'Extracts' and 'independent' are too loose in their meaning. To some degree, they mean the same thing; and they are used differently elsewhere in the documentation. So they only carry their lay meaning. The trap is that it conveys too little detail and allows the unknowing to believe they got the whole story. We are addressing a matter that is supports dwimery and pervades the language.

People can write good code with or without a good model of containerization issues, but their domain expands with the knowledge. It behooves the community to get people over this hump.

Core in my suggestion is a link to language/containers. This would allow a brief description to be easily supported by an explanation for those who find their understanding lacking for their purpose. This is a place for accuracy by definition with clarity through explanation handy.

'Extracts' and 'independent' have no specific meaning as used here. And both may be read to suggest $a<>.WHERE != $a.WHERE.

And lastly, there are other ways to decont variables and other docs dealing with other aspects of containers for which I could PR links.

[2colours]

I get that you're talking about the associative array zen slice, not the positional array zen slice, but I'm presuming the same principle applies. Is my presumption wrong?

I think the problem is that even after several months of playing around with both containers and indexing, I still don't know if "zen slicing" and "decont operator" are the same thing or not.

my $a = 13;
$a[]:p; # (0 => 13)
$a[]:d; #Unexpected adverb 'd' passed to zen slice on '$a'.
$a<>:d; #Unexpected adverb 'd' passed to {} slice on '$a'.
$a[].VAR.WHAT; # (Int)
$a<>.VAR.WHAT; # (Int)

Conclusion? There is no conclusion.

According to the docs:

Zen slicing does not reify or cache (not even Seqs) and merely returns the invocant. It is usually used to interpolate entire arrays / hashes into strings or to decont.

So this hints that "zen slicing" is a means to achieve decontainerization, and as you progress, you might realize it's the only way to do that. It really can be either [] or <>, regardless the data.

The problem is that decontainerization is tightly coupled with the subscription feature. I agree with @0rir that it should be seen as a thing on its own, and preferably even separated from indexing, on the technical end of things. The whole concept "decontainerization" seems underdeveloped.

[0rir]

@2colours, my point was only that <> is incompletely documented as having no contents and so a postfix op being documented separately from the < > postcircumfix operator. A simple and clear issue. A small issue. I would like to keep it that way, so when someone with the skill, interest and time addresses this issue it may be easily resolved.

The only point you make that I find on-topic for this issue is the implication that the decont operator is not a separate op or is not functionally different. It is different.

Heading off topic:

I still don't know if "zen slicing" and "decont operator" are the same thing or not

Not! <> is applicable to various container types (i.e. @a<>) while '< >' (i.e. @a<1> is @a{'1'} and errors; so they are different ops. That decont-ing happens with indexing is not a problem; it is inherent to the action.

We had have similiar confusions, so I share your frustration regarding the general docs. I felt that I should not need to read the Scalar, Positional, Associative, and/or Callable docs to get the how of this subject. I am headed towards those readings.

In your comment are concrete things implied which would make good issues. Get in contact if you would like help finding them.

[2colours]

<> is applicable to various container types (i.e. @a<>) while '< >' (i.e. @a<1> is @a{'1'} and errors; so they are different ops. That decont-ing happens with indexing is not a problem; it is inherent to the action.

I don't think it's that simple, and I think this is exactly what @raiph was pointing out by quoting Jonathan. It seems that <> without arguments is just a multi candidate of the very same subscription operator. When you add arguments, a different multi candidate is called, and the underlying AT-KEY and AT-POS methods come into play. This is where the failure fires:

'12'.AT-KEY(4) # Type Str does not support associative indexing.

[0rir]

@2colours, I don't understand your point? If it relates to changing the decont op's documentation from postcircumfix to postfix or with the proposed wording change, I would like to understand it here in this issue.

[raiph]

@0rir

@raiph, I am referencing the less used decontainerization operator not the word quoting associative indexing operator; that is $a<> not %a< >.

I think you've misunderstood what's going on.

Are you sure someone created a postfix:« <> » operator? Can you show the code in Rakudo where that is defined?

To be clear, I get that the concept of a postfix decont operator exists. And I get that it looks indistinguishable from a postfix <> in use. But I find it hard to believe it isn't just the solution @Larry came up with, given that his solution worked great.

To wit, Rakoons had discussed the situation regarding a distinct "decont" operation.

Many, many Raku operations include "decontainerization" as part of what they do. For example, $a + $b involves deconting the two variables.

In these scenarios there's no need for a separate explicit decont operator.

But one does sometimes (albeit rarely) want to just decont.

There was talk of creating a method called .decont. But there was already a .self that served that purpose well.

On the other hand, the method name .self utterly obscured its purpose if it were used just to decont, and sometimes .self would be used for other reasons that had nothing to do with decontainerizing. So there needed to be something else for the occasional explicit decont.

Larry wanted something something that served as a postfix operator conceptually and visually. He began using zen slices because they did the job nicely even though they were technically implemented as postcircumfix operators.

Then he settled on using <> as his go to "decont op". Any of the zen slices could reasonably stand in as a "decont" op, so why not just pick one of them as the anointed convention? So he anointed one.

It all worked fine.

And as far as I knew that's where it ended.

But now you are suggesting something changed.

But are you sure?

At a quick try, the decont operator allows whitespace and can only be applied to scalar containers and values.

Any of the zen slices can be applied to any value:

my @foo = 1,2,3;
say @foo<>; # [1 2 3]
say @foo{}; # [1 2 3]
say @foo[]; # [1 2 3]
say 42<>; # 42
say 42{}; # 42
say 42[]; # 42

Unless you can show me Rakudo code that shocks me into submission, I will continue to think you've misunderstood what's going on here, and am hopeful this comment will have been helpful in clearing things up.

[2colours]

The funny thing is that while I think @raiph is perfectly right with the description (what's more, finally filled some gaps in my understanding of what is going on, so thank you for that) - I not only understand the confusion of @0rir but I think the following sentence shouldn't be underestimated at all:

To be clear, I get that the concept of a postfix decont operator exists. And I get that it looks indistinguishable from a postfix <> in use

So, to reiterate: it is a concept but NOT an existing underlying subroutine in Rakudo.

My question is: if it is indeed a concept, shouldn't the documentation respect the concept over the Rakudo implementation of it? The Raku documentation is not the Rakudo behavior documentation, and particularly not a Rakudo developer manual.

We can have two resolutions I can quickly think of:

1. treat "zen slice as decont" authoritative: the documentation needs to be rewritten in a way that doesn't confuse people like @0rir or myself ("decontainerisation can be achieved using zen-slicing", not hinting that there is a dedicated "decont operator" etc.)
2. reflect the conceptual distinction: clarify documentation in the way @0rir originally proposed (only for a different reason: concept instead of implementation), and perhaps provide Rakudo-agnostic tests for it in Roast. To be honest, I don't think this can be done in a non-confusing way if there isn't a tested implementation that does separate the concepts on a code level, so I'm afraid to do something like this right would result in a change on a language level, for relatively small benefit.

[0rir]

@raiph, yes, I definitely missed something, I missed the having the ability to understand the source code. And I missed your point, because I was ignorant and focused on learning from the documentation. My complaint was more at the level of a simple non-completion of the parts of an op's doc; and an postcircumfix op without any content is by definition a postfix op.

As you indicate, conting and deconting make manifest a conceptualization that supports Raku's definition in a fundamental way. It is common for people to understand such a concept by poking the bear with operators, seeing what happens, and mentally mapping that against the concept. Here, with the action happening most often in an implicit manner, it is good to clearly tie the concept to an op by name.

And, your argument that .self would muddle different issues also applies to combining the documentation of <> with any of the other ops you mention.

Finding the decont operator quickly lead to my third little container epiphany. Seeing the action allowed understanding. So I support keeping them separate.

Thanks (includes @2colours ).

[2colours]

I have the impression this issue is hard-blocked by the lack of clarity regarding the relation of concepts vs implementation details and/or the relation of Rakudo and the docs. To decide for or against a separate "decont operator entry" would demand a much more holistic view of Raku-related content.