Re: Could this be any more obscure?

[Elizabeth Mattijsen]

> On 3 Oct 2018, at 02:48, ToddAndMargo  wrote:
> 
> On 10/2/18 2:24 AM, Elizabeth Mattijsen wrote:
>> Also, a hopefully less steep introduction:
>> 
>>   https://opensource.com/article/18/9/signatures-perl-6
>> 
> 
> Will do!  Thank you!
> 
> Do you have an index to other stuff you have written?

https://opensource.com/users/lizmat contains an index of the stuff I’ve written 
for opensource.com.

Re: Landing page for Documentation

[JJ Merelo]

Hi

El mié., 3 oct. 2018 a las 7:14, Richard Hainsworth ()
escribió:

> I have just started a review of the documentation for perl6.
>
> When I hit `https://docs.perl6.org/language.html`
>  I get a list of
> sections that is the same as the alphabetical list of pod files in
> `github.com/perl6/doc/tree/master/doc/Language`
>  without
> 00-POD6-CONTROL.
>
> One of my biggest issues about the Language page is its unstructured
> listing.
>
> I looked at 00-POD6-CONTROL and found that the categories were much more
> useful than a straight enumeration of files.
>
> Then I looked at the makefile in the repository, which appears to
> generate documentation based on 00-POD6-CONTROL.
>
> I clicked around on the perl6.org site to see whether I could find a
> landing page for the documentation that is structured as in
> 00-POD6-CONTROL, but couldn't.
>
> So, the question is: why is 00-POD6-CONTROL not used for the Language
> web page? That is why does docs.perl6.org/language.html not reflect the
> structure in 00-POD6-CONTROL?
>

Simply because there has been no time to do it yet. The tooling part of the
Perl 6 docs is complicated and needs an overhaul, and there were already
some pains to implement that particular part; that second part will have to
wait.

>
>
> I do - vaguely - remember a discussion about documentation categories.
> Was it resolved in favour of a straight enumeration of files?
>

No, it wasn't, but in the same way that so many things in the documentation
repo (and, for that matter, others) lays in waiting someone has the time to
do it.

>
> If so, would someone please explain why the most visible public-facing
> description of perl6 is better as an unstructured clutter, rather than a
> structured list with some clue about how each file fits into a whole?
>

No, it's not. But someone's got to do it.

>
>
> I actually disagree a bit with the ordering in 00-POD6-CONTROL, in that
> I would put the 'General Reference' section first. But any order is
> better than no order.
>

I tend to agree with that.

Cheers

JJ

Re: Could this be any more obscure?

[David Green]

On 2018-09-30 9:31 pm, ToddAndMargo wrote:
>By the way, schools have books.  Why is it do you suppose that that 
schools also have teacher?


Well, why is it, do you suppose, that hiring a tutor costs so much more 
than buying a book?


Certainly, some people learn better aurally than visually.  There are 
quite a few recorded P6 presentations around, but I don't know if 
there's a collected list anywhere, or one that links to recent talks 
(anything not too out-of-date).



>[RH] are mixing socialist political terms with what I am stating.  [...]
>I have been very clear what I am after, so I won't repeat it yet again.

The word "common" comes from Latin, and "typical" from Greek, but in 
this context they are synonyms. There's nothing political about it.  But 
it does show how easy it is for something that is clear to one person to 
be misunderstood by another. Repeating something the same way doesn't 
make it clearer (that's one of the reasons we have teachers instead of 
only books, because they can reword things and take different approaches).


There isn't any easy answer to coming up with documentation that works 
for everyone.  (You can't please all of the people all of the time.) 
Perl(5)doc is just a book, after all; but "be more like Perl 5" won't 
work, because Perl 6 is *different* from Perl 5.  Putting beginner and 
advanced docs together might end up with a mish-mash that makes nobody 
happy.  It seems likely to me that you're looking for example-based 
documentation that is organised very differently from docs.perl6.  What 
about Moritz's *Perl 6 Fundamentals*, "A Primer with Examples, Projects, 
and Case Studies"?


https://www.apress.com/gp/book/9781484228982

Is this something that better fits the way you think?


-David

Re: bitwise paper?

[David Green]

On 2018-10-02 9:57 pm, ToddAndMargo wrote:
Does anyone know of a paper out in web land showing how to do bitwise 
operations?

Trying to AND 0010  with 0001 
$ p6 'my $v = 32 & 16; say $v;' 

If you search docs.perl6.org for "bitwise" you will find "+&":

https://docs.perl6.org/language/operators#infix_+&;

And sure enough, 'say 32 +& 16' will return '0'.

The other bitwise operators work likewise: almost the same as Perl 5, 
but with a "+" in front (to indicate that they are numeric operators, as 
opposed to plain "&", "|", etc., which are now junctions... and yes, 
there is https://docs.perl6.org/type/Junction for those who dare!).



-David


P.S. Actually, the search returns:
https://docs.perl6.org/language/operators#index-entry-Numeric_bitwise_AND_operator
...instead of the correct fragment: "#infix_+&" -- is that generated 
automatically?

Re: Could this be any more obscure?

[David Green]

On 2018-09-30 9:31 pm, ToddAndMargo wrote:
>By the way, schools have books.  Why is it do you suppose that that 
schools also have teacher?


Well, why is it, do you suppose, that hiring a tutor costs so much more 
than buying a book?


Certainly, some people learn better aurally than visually.  There are 
quite a few recorded P6 presentations around, but I don't know if 
there's a collected list anywhere, or one that links to recent talks 
(anything not too out-of-date).



>[RH] are mixing socialist political terms with what I am stating.  [...]
>I have been very clear what I am after, so I won't repeat it yet again.

The word "common" comes from Latin, and "typical" from Greek, but in 
this context they are synonyms. There's nothing political about it.  But 
it does show how easy it is for something that is clear to one person to 
be misunderstood by another. Repeating something the same way doesn't 
make it clearer (that's one of the reasons we have teachers instead of 
only books, because they can reword things and take different approaches).


There isn't any easy answer to coming up with documentation that works 
for everyone.  (You can't please all of the people all of the time.) 
Perl(5)doc is just a book, after all; but "be more like Perl 5" won't 
work, because Perl 6 is *different* from Perl 5.  Putting beginner and 
advanced docs together might end up with a mish-mash that makes nobody 
happy.  It seems likely to me that you're looking for example-based 
documentation that is organised very differently from docs.perl6.  What 
about Moritz's *Perl 6 Fundamentals*, "A Primer with Examples, Projects, 
and Case Studies"?


https://www.apress.com/gp/book/9781484228982

Is this something that better fits the way you think?


-David

Landing page for Documentation

[Richard Hainsworth]

I have just started a review of the documentation for perl6.

When I hit `https://docs.perl6.org/language.html` I get a list of 
sections that is the same as the alphabetical list of pod files in 
`github.com/perl6/doc/tree/master/doc/Language` without 00-POD6-CONTROL.


One of my biggest issues about the Language page is its unstructured 
listing.


I looked at 00-POD6-CONTROL and found that the categories were much more 
useful than a straight enumeration of files.


Then I looked at the makefile in the repository, which appears to 
generate documentation based on 00-POD6-CONTROL.


I clicked around on the perl6.org site to see whether I could find a 
landing page for the documentation that is structured as in 
00-POD6-CONTROL, but couldn't.


So, the question is: why is 00-POD6-CONTROL not used for the Language 
web page? That is why does docs.perl6.org/language.html not reflect the 
structure in 00-POD6-CONTROL?



I do - vaguely - remember a discussion about documentation categories. 
Was it resolved in favour of a straight enumeration of files?


If so, would someone please explain why the most visible public-facing 
description of perl6 is better as an unstructured clutter, rather than a 
structured list with some clue about how each file fits into a whole?


If the problem is that different people have different ideas about 
structure, then why not make it possible to have multiple structures, 
switchable with a button in html. It seems from 00-POD6-CONTROL that the 
ordering can be easily changed. This would indicate that multiple 
CONTROL files could be created using the same programs to generate them.


I actually disagree a bit with the ordering in 00-POD6-CONTROL, in that 
I would put the 'General Reference' section first. But any order is 
better than no order.


Regards,

Richard

aka finanalyst

Re: bitwise paper?

[Trey Harris]

On Tue, Oct 2, 2018 at 23:57 ToddAndMargo  wrote:

> Hi All,
>
> Does anyone know of a paper out in web land showing how to
> do bitwise operations?  DuckDuckGo give me tons of hits
> for Perl 5.
>
> Trying to AND 0010  with 0001 
>
> $ p6 'my $v = 32 & 16; say $v;'
> all(32, 16)
>
> should give me  .


"Should give you"? Why do you say that?

Go to docs.perl6.org. Type "bitwise" into the search box. You will see a
popup, "Numeric bitwise AND operator". Click it to be taken to
https://docs.perl6.org/language/operators#index-entry-Numeric_bitwise_AND_operator,
which will tell you the bitwise AND operator in Perl 6 is +&.

Run the same command with +& and you will get the answer 0.

If, on the other hand, you go to docs.perl6.org, and type "&" into the
search box, you will see under "Infix" (since you used the operator between
two things, it is Infix, as the docs say if you type "infix" into the
search box and click the first entry under "Reference"; I have no idea how
you'd divine that such a thing is called an infix operator aside from
common programming parlance, but if you have an idea how that might be
expressed it can easily be added to the index) that the first entry is "&".

Click on this "&" and you are taken to https://docs.perl6.org/routine/&;
which rather clearly says it returns an all Junction.

So I wonder why were you under the impression that the above "should give
[you]  "?

Trey

Re: No. It is lucid! Re: Could this be any more obscure?

[Richard Hainsworth]

This could only too easily become a flame war, so I am replying once and 
will not answer again unless it is about substance.


The Perl6 community is warm, generous, and intellectually inspiring. 
Those virtues should be defended against unseemly and intemperate 
language. Calling a documentation writer a 'jerk' is wrong.


On 03/10/18 07:40, ToddAndMargo wrote:

On 9/30/18 9:11 PM, Richard Hainsworth wrote:

But I thought you just implied you wanted pro stuff, not beginner stuff. 


I have no idea how you got that out of what I said.  I want the
beginners stuff included with the pro stuff.
Yes the best of all worlds, and it must be short. Demand the impossible 
and complain when it does not happen. There are a number of people 
trying very hard to balance the contradictions of writing documentation. 
We need to support them and offer constructive suggestions. Clearly my 
post was wrong because you did not *think* about what I said, only 
reacted negatively to my British sense of humour.



So what is wanted is 'common user' stuff (see below).


You are mixing socialist political terms with what I
am stating.  By "common user" I mean a typical user.
The term was meant to differentiate typical users from
experts.
Where did 'socialist' come from? You said 'common user' and I was trying 
to elicit from you what it meant. But as it happens I do not think that 
'socialist' is a negative word, and for many people it means an emphasis 
on society and community (as in this very valuable Perl6 community) 
rather than on solitary individuals.


Actually, I do not understand what you are saying at all, eg., 'I 
have know how to use ...' is not clear.


Again, I have no idea how you got that out of what I said.
I quoted your words from your post. They are in quotes. Your use of 
English grammar is not standard, and consequently it is ambiguous.

When I use a function all the time, I know who to use the
you know 'who to use' or 'how to use'? It would be useful for you to 
read what you have written for mistakes before clicking on the 'send' 
button. That way, other people can understand you better.

function. The problem was that I could not reverse engineer
the documentation.
  In other words, I figured out how to
use the function from other sources than the documentation.
Had I used the documentation, I never would have figured it out.
That is the issue.
This use of 'reverse engineer' is obscure. But if you mean that you had 
to read around a bit in order to understand, I suggest that this is 
quite a normal intellectual activity. That is why repeatedly it has been 
suggested that you read a book.



But I am confused about what *you* want from the reference 
documentation.


I think maybe there is a translation issue between your native
language and mine.  I have been very clear what I am
after, so I won't repeat it yet again.
My native language is English. I was born to English parents, went to 
school in Leeds, went to University in London, studied computer science 
and economics in Birmingham, spent 20 years editing and translating into 
English from Russian in Moscow. I speak and write Russian, and I am 
learning Cantonese.


I do get it: you are following the example of the current crop of 
political leaders in the US. When someone demonstrates - as I did in the 
previous post, and in this one - that your English grammar and spelling 
are slovenly, you throw back the criticism as if I am guilty of the 
same, and charge that my native language is not English.


So no it is not a translation issue. What you want is not clear because 
(a) you do not write clearly, (b) you ask for different things at 
different times, (c) you assume that the world is predominantly the same 
as you, when it is not.




    3) when calling other term to explain things, it should
   pick the easiest term available. It should not pick
   any nasty, advanced terms.  (Unless the writer enjoys
   confusing the reader and bragging about how smart
   he is.  And he is a jerk.)
This does not seem to be correct English. 


You are again missing the point.  It is wonderful if the writer
wants to share an interesting, complex way of doing things.
But only AFTER he explains it in is simple terms.  You don't
share a calculus equation with someone until after you
teach them the fundamentals of arithmetic.
I did not miss the point. You deleted the part of my response where I 
agreed that there should be simple examples. You also deleted the part 
where I pointed out that calling someone a 'jerk' is not polite. It is 
possible to get carried away by beauty and elegance and forget the need 
to start with simple things. That might make the explanation cryptic; it 
does not make them a jerk.




We come again to this category: 'the common user'. This person 
(possibly there are more) is not a 'beginner' nor a 'pro'. What is to 
be expected of a 'common user' of perl6? Can we assume that a 'common 
user' has read an introduction to perl

bitwise paper?

[ToddAndMargo]

Hi All,

Does anyone know of a paper out in web land showing how to
do bitwise operations?  DuckDuckGo give me tons of hits
for Perl 5.

Trying to AND 0010  with 0001 

$ p6 'my $v = 32 & 16; say $v;'
all(32, 16)

should give me  .


I have a nice paper on Perl 5.  I don't think they the same?

$ perl -E 'my $v = 32 & 16; say $v;'
0

$ perl -E 'my $v = 32 | 16; say $v;'
48



Many thanks,
-T

Re: What are the official names?

[ToddAndMargo]

On 10/2/18 7:38 PM, Timo Paulssen wrote:

I just saw that this was already kind of answered in the other thread,
sorry about that!



It is appreciated anyway!   Being smacked from two sides
works even better!

:-)

Any idea what the official name of the crypto line is?

Re: need doc help with []

[ToddAndMargo]

On 10/2/18 7:32 PM, Timo Paulssen wrote:

Hi Todd,

On 03/10/2018 02:14, ToddAndMargo wrote:

sub postcircumfix:<[ ]>(@container, **@index,
     :$k, :$v, :$kv, :$p, :$exists, :$delete)

1  Why the <[]>?  I have always used [] with out the <>.
    Why would I want to use one over the other?

2)  Where does it state that the <> is optional?



postcircumfix:<[ ]> is the "real name" of the [ ] postfix operator. In
this case the < > are just how it's quoted, i.e. this is how you
communicate to perl6 where the name starts and ends. It is also in other
operator's names, like infix:<+> for the + operator, or postfix:<++> for
the ++ postfix operator. If your operator itself contains a < or a >,
you can instead use ['blah'] for the quoting, like infix:['<'] for the <
operator. As you can see, it's more or less different ways to write what
is essentially a string. Just like you have "foo" and 'foo' but also
q, q«foo», and anything else you want to come up with.



6)  Where is the --> return described?



The "-->" part of the signature is optional. If there isn't one, it
defaults to Mu, which is the type that everything conforms to, i.e. the
sub or method that either has "--> Mu" explicitly, or has it by leaving
it out, may return absolutely whatever it wants.

After all, the "-->" part is a constraint, and it gets validated at
compile time every time a sub or method returns.



Yours in confusion,
-T



Hope that helps a little
   - Timo




Thank you!  :-)

Re: What are the official names?

[Timo Paulssen]

I just saw that this was already kind of answered in the other thread,
sorry about that!

Re: What are the official names?

[Timo Paulssen]

On 03/10/2018 01:50, ToddAndMargo wrote:
> On 10/2/18 4:47 PM, David Green wrote:
>> On 2018-10-02 4:06 pm, ToddAndMargo wrote:
>>> What is the official Perl syntaxland name of the [] subroutine?
>> If you search for "[]" at https://docs.perl6.org, it will turn up the
>> routine "postcircumfix [ ]", which links to
>> 
>>
>> https://docs.perl6.org/language/subscripts
>> 
>>
>>
>>
>> -David
>>
>
> Thank you!
>
> One down, one to go!
>
> :-)


The same page you already found by searching for [ ] in the search bar
also gives you the explanation of the other [ ], i.e. the one used in my
@a = [1, 2, 3].

It is perhaps less visible than desirable, as it doesn't come with an
example, but the category it's in, namely "circumfix" can clue you in
that it means the one in [1, 2, 3]. circumfix means "goes around", like
prefix means "goes before" or infix means "in between". postcircumfix is
kind of a combination of postfix and circumfix where there is one thing
that the routine goes after, and another thing that the routine goes
around. That's how you get @a[1]; the [ ] from the view of @a is a
postfix and from the view of 1 is a circumfix. Hence, postcircumfix.

Hope that helps
  - Timo

Re: need doc help with []

[Timo Paulssen]

Hi Todd,

On 03/10/2018 02:14, ToddAndMargo wrote:
> sub postcircumfix:<[ ]>(@container, **@index,
>     :$k, :$v, :$kv, :$p, :$exists, :$delete)
>
> 1  Why the <[]>?  I have always used [] with out the <>.
>    Why would I want to use one over the other?
>
> 2)  Where does it state that the <> is optional?


postcircumfix:<[ ]> is the "real name" of the [ ] postfix operator. In
this case the < > are just how it's quoted, i.e. this is how you
communicate to perl6 where the name starts and ends. It is also in other
operator's names, like infix:<+> for the + operator, or postfix:<++> for
the ++ postfix operator. If your operator itself contains a < or a >,
you can instead use ['blah'] for the quoting, like infix:['<'] for the <
operator. As you can see, it's more or less different ways to write what
is essentially a string. Just like you have "foo" and 'foo' but also
q, q«foo», and anything else you want to come up with.


> 6)  Where is the --> return described?


The "-->" part of the signature is optional. If there isn't one, it
defaults to Mu, which is the type that everything conforms to, i.e. the
sub or method that either has "--> Mu" explicitly, or has it by leaving
it out, may return absolutely whatever it wants.

After all, the "-->" part is a constraint, and it gets validated at
compile time every time a sub or method returns.


> Yours in confusion,
> -T


Hope that helps a little
  - Timo

Re: join questions

[ToddAndMargo]

On 10/1/18 4:35 PM, Larry Wall wrote:

On Sun, Sep 30, 2018 at 04:02:15AM -0700, ToddAndMargo wrote:
: Hi All,
:
: https://docs.perl6.org/routine/join#(List)_routine_join
:
: method join(List:D: $separator --> Str:D)
:
: $ p6 'say (1, ).join("|");'
: 1|a b c
:
:
: It states in the manual that this will happen.
:
: Questions:
:
:1) why?

Because an invocant is only one thing.  In this case, it's a List of
exactly two things: a 1 and a sublist of .  And you since passed
.join only two things to stringify and join, it stringified the 1 and
then it stringified the , and then it joined those two things,
just as you asked it to.

A deeper "why" is that Perl 6 doesn't autoflatten sublists unless you
explicitly ask it to, so you'd need to put | to "slip" the sublist
into the outer list, or use flat().

:2) where in the method definition does it state
:   this will happen?

It's not in the method definition, and it doesn't belong in the method
definition.  It's in the definition of how Perl 6 works at a fundamental
level.  We're not going to document every list argument in Perl 6 to
say that it *doesn't* work like in Perl 5.

:3) why does this work?
:  $ p6 'join( "|", <1 2 3>).say;'
:  1|2|3

Because functions can take multiple arguments, and so the signature of
the join function is allowed (and required) to use a comma to separate
those arguments.  This is not the same comma that creates the general
list above.  Functions often cheat with their commas, especially functions
that were borrowed from Perl 5, which cheats on most of its commas and
doesn't really understand nested lists at all without explicit references.

The deeper and/or shallower reason is that a Perl 5 programmer will
expect the join function to work that way, and even expect the slurpy
argument to autoflatten, which it does for old time's sake, and because
it seems to be a useful DWIM for this particular string-based function.
The functions that flatten their slurpy (like join) are explicitly marked
with * on that argument in the signature.  So it's still true that we
flatten only explicitly in Perl 6, but that explicit mark is in the
that pesky signature you gotta get your brain around someday.

In short, the method form is optimized for people who understand nested
lists and want them to to stay nested by default, while the function
form is optimized for, er, the typical Perl 5 programmer who expects
random list flattening in various places.

Larry



Thank you!  I understand now.

:-)

Re: need doc help with []

[ToddAndMargo]

On 10/2/18 6:29 PM, Trey Harris wrote:

It's nice, certainly, but I think you miss my point.


Oh no, I completely caught it.  I am noticing that with
regex's.  They just have started to peal off.

I only posted that link in case its would assist
English as a second language speakers.  It was
a "non sequitur", meaning I changed the subject.

A regex that tickles me

[ToddAndMargo]

Hi All,

This regex just tickles me.  I am converting a date
(2018-09-15) I harvest from a web page into a
revision number (2018.09.15).  The particular web site
only dates for their releases, so, no problem, I am using
Perl 6


#!/usr/bin/env perl6

my Str $x = "2018-09-15";
$x ~~ s/ (<:N>**4) "-" (<:N>**2) "-" (<:N>**2) /$0.$1.$2/;
say $x;

2018.09.15

I am starting to just peal off regex's.  They are also starting
to become fun.  (Uh oh, did I just admit to brain damage?)

:-)

-T

Re: need doc help with []

[Peter Scott]

On 10/2/2018 6:29 PM, Trey Harris wrote:
So it is for the [] postcircumfix. For those of us who have been 
following Perl 6 development for 18 years, the fact that it—and almost 
every other low-level particle—can be described at all in such a way 
is a remarkable triumph of the language.


Amen to that.  I am in awe of the beauty and the genius every time I see 
one of those definitions.

Re: need doc help with []

[Trey Harris]

On Tue, Oct 2, 2018 at 21:10 ToddAndMargo  wrote:

> If you have a free moment, speaking to "have", the diagram here
> is a work of art:
>
> https://www.freethesaurus.com/have
>
> I know there a lot of English as a second language speaker on this
> group.  The above thesaurus uses diagrams and is wonderfully
> well done.


It's nice, certainly, but I think you miss my point.

None of the words in that diagram can be used as a substitute for "$x" in
"I $x already seen that movie". There is no word in English that can be
placed there instead. "Have" in English, like [] in Perl, has some
extremely low-level purposes that are very difficult to describe in the way
we can describe most words.

Asking for a thesaurus-like explanation of those purposes is not merely
unreasonable; it's literally impossible. That doesn't mean those
definitions _should not be_ in the document; they MUST be in the document,
if it is to have any claim to being an exhaustive reference. Yet there is
no way to set forth the definition without using some abstruse terminology
that, if you look up _its_ definitions, will get you no closer to
understanding $x above.

These low-level definitions WILL confuse anyone who is merely seeking
meaning at a "common knowledge" level. Omitting them is impossible. Making
them understandable to the common-knowledge-level user of the document is
also impossible.

So including these very arcane definitions—even at the risk of confusion to
those who will look at a definition expecting to be able to understand 100%
of it on first reading—is necessary; confusing those common-knowledge
seekers is a necessary evil. The lexicographers must assume that those
learning English will learn these purposes of "have" elsewhere; otherwise
they would need to embed an entire grammar of English under the definition
of "have".

So it is for the [] postcircumfix. For those of us who have been following
Perl 6 development for 18 years, the fact that it—and almost every other
low-level particle—can be described at all in such a way is a remarkable
triumph of the language. But that cannot coexist with your desire to look
at the perl6 doc for [] and understand all of it as a non-expert Perl 6
programmer.

Trey

Re: need doc help with []

[ToddAndMargo]

On 10/2/18 5:14 PM, ToddAndMargo wrote:

3)  What is a **@?  *@ is a slurp all remaining.   A
     super duper slurp?


Found this one. It is a special kind of slurpy.  Grape
flavor.  What?  Not funny?

https://docs.perl6.org/syntax/%20**@

(Signature) parameter **@

Slurpy parameters declared with two stars do not flatten
any Iterable arguments within the list, but keep the
arguments more or less as-is:

-T

Re: need doc help with []

[ToddAndMargo]

On 10/2/18 6:09 PM, Curt Tilmes wrote:



On Tue, Oct 2, 2018 at 9:04 PM ToddAndMargo > wrote:


Not to put the cart before the horse, having not read those
references yet, but did the crypto line forget the --> return?


https://docs.perl6.org/type/Signature#Constraining_return_types




It is not sinking in.  Every line uses -->

 sub greeting1(Str $name  --> Str) { say "Hello, $name" } # Valid
 sub greeting2(Str $name, --> Str) { say "Hello, $name" } # Valid

 sub favorite-number1(--> 42) {} # OUTPUT: 42
 sub favorite-number2(--> 42) { return } # OUTPUT: 42

Why do the above all use "-->" and

 sub postcircumfix:<[ ]>(@container, **@index, :$k, :$v, :$kv, :$p, 
:$exists, :$delete)


does not?

Yours in confusion,
-T

Re: need doc help with []

[ToddAndMargo]

On 10/2/18 6:02 PM, Trey Harris wrote:
What Curt said, but also, this is a bit like trying to understand 
English's word "have" with a dictionary. No one who speaks English 
natively looks up "have" in the dictionary. Anyone who does so will find 
definitions like, "Used in forming the perfect aspect and the past 
perfect aspect." Well, that's not very good at all, how could any common 
speaker be expected to understand that? Could any fluent English speaker 
reverse engineer that definition? Obviously, considering common cases 
like "I *have* already seen that movie", how you _should_ write that 
definition is... well...


The [] postcircmfix is so low-level to how Perl (both 5 and 6) work that 
squinting at its solitary definition to try to divine meaning is not 
particularly useful. Eventually you will know Perl 6 well enough that 
this document might be of interest to you when you're trying to 
implement your own indexing or postcircumfix operator. But it's not 
useful for learning what [] _does_ in practice, because it's so basic to 
the language that one can only really learn it through seeing it used, 
or in a tutorial where it comes up as a topic.


I am noticing that with regex's.  They are starting to just peal off.

If you have a free moment, speaking to "have", the diagram here
is a work of art:

https://www.freethesaurus.com/have

I know there a lot of English as a second language speaker on this 
group.  The above thesaurus uses diagrams and is wonderfully

well done.

Re: need doc help with []

[Curt Tilmes]

On Tue, Oct 2, 2018 at 9:04 PM ToddAndMargo  wrote:

> Not to put the cart before the horse, having not read those
> references yet, but did the crypto line forget the --> return?
>

https://docs.perl6.org/type/Signature#Constraining_return_types

Re: need doc help with []

[ToddAndMargo]

On Tue, Oct 2, 2018 at 8:14 PM ToddAndMargo > wrote:


Hi All,

I use postcircumfix [] all the time.  But I don't
understand the documentation.

https://docs.perl6.org/routine/[%20]#language_documentation_Operators 


would someone please explain what the crypto line means:

sub postcircumfix:<[ ]>(@container, **@index,
  :$k, :$v, :$kv, :$p, :$exists, :$delete)

1  Why the <[]>?  I have always used [] with out the <>.
 Why would I want to use one over the other?

2)  Where does it state that the <> is optional?

3)  What is a **@?  *@ is a slurp all remaining.   A
  super duper slurp?

4)  What is :$k, :$v, :$kv, :$p, :$exists, :$delete
  and where are they defined?

5)  Why does :$k, :$v, :$kv, :$p, :$exists, :$delete
  have colons in front of them?

6)  Where is the --> return described?

Yours in confusion,
-T



On 10/2/18 5:20 PM, Curt Tilmes wrote:
Remember within the few days people sent you links to read more about 
signatures?  Go read them, then re-ask any remaining questions.


I can cut/paste bits from them them under each of your questions, but it 
would really be better for you to just read the existing docs and try to 
understand signatures more holistically.

https://opensource.com/article/18/9/signatures-perl-6
https://docs.perl6.org/type/Signature
https://perl6advent.wordpress.com/2013/12/21/day-21-signatures/

and some videos:
https://vimeo.com/42051800
https://www.youtube.com/watch?v=obYlOurt-44




Not to put the cart before the horse, having not read those
references yet, but did the crypto line forget the --> return?

Re: need doc help with []

[Trey Harris]

What Curt said, but also, this is a bit like trying to understand English's
word "have" with a dictionary. No one who speaks English natively looks up
"have" in the dictionary. Anyone who does so will find definitions like,
"Used in forming the perfect aspect and the past perfect aspect." Well,
that's not very good at all, how could any common speaker be expected to
understand that? Could any fluent English speaker reverse engineer that
definition? Obviously, considering common cases like "I *have* already seen
that movie", how you _should_ write that definition is... well...

The [] postcircmfix is so low-level to how Perl (both 5 and 6) work that
squinting at its solitary definition to try to divine meaning is not
particularly useful. Eventually you will know Perl 6 well enough that this
document might be of interest to you when you're trying to implement your
own indexing or postcircumfix operator. But it's not useful for learning
what [] _does_ in practice, because it's so basic to the language that one
can only really learn it through seeing it used, or in a tutorial where it
comes up as a topic.
On Tue, Oct 2, 2018 at 20:21 Curt Tilmes  wrote:

> Remember within the few days people sent you links to read more about
> signatures?  Go read them, then re-ask any remaining questions.
>
> I can cut/paste bits from them them under each of your questions, but it
> would really be better for you to just read the existing docs and try to
> understand signatures more holistically.
>
> https://opensource.com/article/18/9/signatures-perl-6
> https://docs.perl6.org/type/Signature
> https://perl6advent.wordpress.com/2013/12/21/day-21-signatures/
>
> and some videos:
> https://vimeo.com/42051800
> https://www.youtube.com/watch?v=obYlOurt-44
>
>
> On Tue, Oct 2, 2018 at 8:14 PM ToddAndMargo  wrote:
>
>> Hi All,
>>
>> I use postcircumfix [] all the time.  But I don't
>> understand the documentation.
>>
>> https://docs.perl6.org/routine/[%20]#language_documentation_Operators
>> 
>>
>> would someone please explain what the crypto line means:
>>
>> sub postcircumfix:<[ ]>(@container, **@index,
>>  :$k, :$v, :$kv, :$p, :$exists, :$delete)
>>
>> 1  Why the <[]>?  I have always used [] with out the <>.
>> Why would I want to use one over the other?
>>
>> 2)  Where does it state that the <> is optional?
>>
>> 3)  What is a **@?  *@ is a slurp all remaining.   A
>>  super duper slurp?
>>
>> 4)  What is :$k, :$v, :$kv, :$p, :$exists, :$delete
>>  and where are they defined?
>>
>> 5)  Why does :$k, :$v, :$kv, :$p, :$exists, :$delete
>>  have colons in front of them?
>>
>> 6)  Where is the --> return described?
>>
>> Yours in confusion,
>> -T
>>
>

Re: need doc help with []

[ToddAndMargo]

On 10/2/18 5:20 PM, Curt Tilmes wrote:
Remember within the few days people sent you links to read more about 
signatures?  Go read them, then re-ask any remaining questions.


Hi Curt,

Will do.  I have them both up in tabs.  I am awaiting
a customer to do a go to assist, so I was answering
my mail.

Maybe later today, I will get to do some actual coding.
Perl 6 is just fun to code in. 1001 ways to do everything.
Larry is freakin' genius!

:-)

-T

--
~
When we ask for advice, we are usually looking for an accomplice.
   --  Charles Varlet de La Grange
~

Re: Could this be any more obscure?

[Peter Scott]

On 10/2/2018 5:45 PM, ToddAndMargo wrote:

On 10/2/18 5:31 PM, Curt Tilmes wrote:


On Tue, Oct 2, 2018 at 8:28 PM ToddAndMargo > wrote:


    Question: in Perl syntaxland, is "postfix" short
    for "postcircumfix"?


Nope.  Each are different types of oeprator.  Here is the list:
https://docs.perl6.org/language/operators#Operator_classification



Hi Curt,

Maybe I am blind, but I can only find

postcircumfix [ ]
https://docs.perl6.org/language/operators#postcircumfix_[_]

in that list.


It's second in the list:



Searching within web page for the term you want usually finds it if it's 
there.  Ctrl-F postfix.

Re: Could this be any more obscure?

[ToddAndMargo]

On 10/2/18 5:51 PM, Curt Tilmes wrote:



On Tue, Oct 2, 2018 at 8:46 PM ToddAndMargo > wrote:


On 10/2/18 5:31 PM, Curt Tilmes wrote:
 >
 > On Tue, Oct 2, 2018 at 8:28 PM ToddAndMargo
mailto:toddandma...@zoho.com>
 > >> wrote:
 >
 >     Question: in Perl syntaxland, is "postfix" short
 >     for "postcircumfix"?
 >
 >
 > Nope.  Each are different types of oeprator.  Here is the list:
 > https://docs.perl6.org/language/operators#Operator_classification
 >

Hi Curt,

Maybe I am blind, but I can only find

postcircumfix [ ]
https://docs.perl6.org/language/operators#postcircumfix_[_]

Here's the list cut/pasted from directly at the link I posted:

Operators can occur in several positions relative to a term:

+term   prefix
term1 + term2   infix
term++  postfix
(term)  circumfix
term1[term2]postcircumfix

 From that, you can see that postfix things go behind a single term 
while postcircumfix things go behind 1 term, and around another term.


One example on that page of a postcircumfix operator is the [] you 
linked to.





Hi Curt,

Thank you!

Larry removed the rest of the fuzz from my thinking.

-T

Re: Could this be any more obscure?

[ToddAndMargo]

On 10/2/18 5:51 PM, Larry Wall wrote:

On Tue, Oct 02, 2018 at 05:28:01PM -0700, ToddAndMargo wrote:
: On 10/2/18 11:23 AM, Ralph Mellor wrote:
: >So, to recap: a postfix `[]` acts on whatever is on its left,
: >pulling out elements from the thing on its left, treated as
: >a list like thing, with the elements selected according to
: >the index(es) inside the brackets.
: >
:
:
: Perfect!  Thank you!
:
: I am going to quote you in my write up.
:
: Question: in Perl syntaxland, is "postfix" short
: for "postcircumfix"?

Kinda the other way around.  A postcircumfix is just a special kind of
postfix that happens to enclose an extra argument, with the result that,
while your typical postfix has only one argument (like the $a of $a++),
your typical postcircumfix has two (like the @a and 42 of @a[42]).

The second syntactic argument is often interpreted as a slice or an
function argument list later on, but syntactically it's just a single
expression inside the bracketing chars.  So in @a[42,43], there are
still only two arguments, @a array and the 42,43 list expression.

Larry



Hi Larry,

Beautiful explanation!  You even tied their relationship
together, rather than leaving me thinking there were
two separate unrelated functions.   Thank you!

I am going to quote you too in my private write up.

-T

Re: Could this be any more obscure?

[Curt Tilmes]

On Tue, Oct 2, 2018 at 8:46 PM ToddAndMargo  wrote:

> On 10/2/18 5:31 PM, Curt Tilmes wrote:
> >
> > On Tue, Oct 2, 2018 at 8:28 PM ToddAndMargo  > > wrote:
> >
> > Question: in Perl syntaxland, is "postfix" short
> > for "postcircumfix"?
> >
> >
> > Nope.  Each are different types of oeprator.  Here is the list:
> > https://docs.perl6.org/language/operators#Operator_classification
> >
>
> Hi Curt,
>
> Maybe I am blind, but I can only find
>
> postcircumfix [ ]
> https://docs.perl6.org/language/operators#postcircumfix_[_]


Here's the list cut/pasted from directly at the link I posted:

Operators can occur in several positions relative to a term:
+term prefix
term1 + term2 infix
term++ postfix
(term) circumfix
term1[term2] postcircumfix

>From that, you can see that postfix things go behind a single term while
postcircumfix things go behind 1 term, and around another term.

One example on that page of a postcircumfix operator is the [] you linked
to.

Re: Could this be any more obscure?

[Larry Wall]

On Tue, Oct 02, 2018 at 05:28:01PM -0700, ToddAndMargo wrote:
: On 10/2/18 11:23 AM, Ralph Mellor wrote:
: >So, to recap: a postfix `[]` acts on whatever is on its left,
: >pulling out elements from the thing on its left, treated as
: >a list like thing, with the elements selected according to
: >the index(es) inside the brackets.
: >
: 
: 
: Perfect!  Thank you!
: 
: I am going to quote you in my write up.
: 
: Question: in Perl syntaxland, is "postfix" short
: for "postcircumfix"?

Kinda the other way around.  A postcircumfix is just a special kind of
postfix that happens to enclose an extra argument, with the result that,
while your typical postfix has only one argument (like the $a of $a++),
your typical postcircumfix has two (like the @a and 42 of @a[42]).

The second syntactic argument is often interpreted as a slice or an
function argument list later on, but syntactically it's just a single
expression inside the bracketing chars.  So in @a[42,43], there are
still only two arguments, @a array and the 42,43 list expression.

Larry

Re: Could this be any more obscure?

[ToddAndMargo]

On 10/2/18 2:24 AM, Elizabeth Mattijsen wrote:

Also, a hopefully less steep introduction:


   https://opensource.com/article/18/9/signatures-perl-6



Will do!  Thank you!

Do you have an index to other stuff you have written?

Re: Could this be any more obscure?

[ToddAndMargo]

On 10/2/18 2:01 AM, Simon Proctor wrote:

https://docs.perl6.org/type/Signature

Todd can I ask that you read this page of the docs for two reasons. 
Firstly understanding Signatures will go a long way to helping you to 
understand the rest of the docs, and secondly so you can give use your 
take on it pointing out any areas you think could be more clear.


I personally think that grasping the signature system is fundamental in 
moving from Perl 5 to Perl 6 and in reading the Perl6 docs.


Simon


In progress.   Thank you!

Re: Could this be any more obscure?

[ToddAndMargo]

On 10/2/18 5:31 PM, Curt Tilmes wrote:


On Tue, Oct 2, 2018 at 8:28 PM ToddAndMargo > wrote:


Question: in Perl syntaxland, is "postfix" short
for "postcircumfix"?


Nope.  Each are different types of oeprator.  Here is the list:
https://docs.perl6.org/language/operators#Operator_classification



Hi Curt,

Maybe I am blind, but I can only find

postcircumfix [ ]
https://docs.perl6.org/language/operators#postcircumfix_[_]

in that list.

:'(

-T

Re: Could this be any more obscure?

[Curt Tilmes]

On Tue, Oct 2, 2018 at 8:28 PM ToddAndMargo  wrote:

> Question: in Perl syntaxland, is "postfix" short
> for "postcircumfix"?
>

Nope.  Each are different types of oeprator.  Here is the list:
https://docs.perl6.org/language/operators#Operator_classification

Re: Could this be any more obscure?

[ToddAndMargo]

On 10/2/18 11:23 AM, Ralph Mellor wrote:

So, to recap: a postfix `[]` acts on whatever is on its left,
pulling out elements from the thing on its left, treated as
a list like thing, with the elements selected according to
the index(es) inside the brackets.




Perfect!  Thank you!

I am going to quote you in my write up.

Question: in Perl syntaxland, is "postfix" short
for "postcircumfix"?


-T

Re: need doc help with []

[Curt Tilmes]

Remember within the few days people sent you links to read more about
signatures?  Go read them, then re-ask any remaining questions.

I can cut/paste bits from them them under each of your questions, but it
would really be better for you to just read the existing docs and try to
understand signatures more holistically.

https://opensource.com/article/18/9/signatures-perl-6
https://docs.perl6.org/type/Signature
https://perl6advent.wordpress.com/2013/12/21/day-21-signatures/

and some videos:
https://vimeo.com/42051800
https://www.youtube.com/watch?v=obYlOurt-44


On Tue, Oct 2, 2018 at 8:14 PM ToddAndMargo  wrote:

> Hi All,
>
> I use postcircumfix [] all the time.  But I don't
> understand the documentation.
>
> https://docs.perl6.org/routine/[%20]#language_documentation_Operators
> 
>
> would someone please explain what the crypto line means:
>
> sub postcircumfix:<[ ]>(@container, **@index,
>  :$k, :$v, :$kv, :$p, :$exists, :$delete)
>
> 1  Why the <[]>?  I have always used [] with out the <>.
> Why would I want to use one over the other?
>
> 2)  Where does it state that the <> is optional?
>
> 3)  What is a **@?  *@ is a slurp all remaining.   A
>  super duper slurp?
>
> 4)  What is :$k, :$v, :$kv, :$p, :$exists, :$delete
>  and where are they defined?
>
> 5)  Why does :$k, :$v, :$kv, :$p, :$exists, :$delete
>  have colons in front of them?
>
> 6)  Where is the --> return described?
>
> Yours in confusion,
> -T
>

Re: Could this be any more obscure?

[Rocco Caputo]

> On Oct 2, 2018, at 04:40, ToddAndMargo  wrote:
> 
> I am thinking of doing an RFE to place at the front
> of the routines documentation that introduces the reader
> on how to read THAT line in the documentation -- what
> the abbreviations and symbols and the like mean.


Referring the reader to the copy that already exists is better than duplicating 
that information.

Redundancy is tedious to read and hard to maintain.

Making the manual more readable for people who won't look things up isn't worth 
that.

-- 
Rocco Caputo 

Re: Could this be any more obscure?

[ToddAndMargo]

On 10/2/18 6:06 AM, Rocco Caputo wrote:
On Oct 2, 2018, at 04:40, ToddAndMargo > wrote:


I am thinking of doing an RFE to place at the front
of the routines documentation that introduces the reader
on how to read THAT line in the documentation -- what
the abbreviations and symbols and the like mean.


Referring the reader to the copy that already exists is better than 
duplicating that information.


So it is already written?  Do you have a link to that?

need doc help with []

[ToddAndMargo]

Hi All,

I use postcircumfix [] all the time.  But I don't
understand the documentation.

https://docs.perl6.org/routine/[%20]#language_documentation_Operators

would someone please explain what the crypto line means:

sub postcircumfix:<[ ]>(@container, **@index,
:$k, :$v, :$kv, :$p, :$exists, :$delete)

1  Why the <[]>?  I have always used [] with out the <>.
   Why would I want to use one over the other?

2)  Where does it state that the <> is optional?

3)  What is a **@?  *@ is a slurp all remaining.   A
super duper slurp?

4)  What is :$k, :$v, :$kv, :$p, :$exists, :$delete
and where are they defined?

5)  Why does :$k, :$v, :$kv, :$p, :$exists, :$delete
have colons in front of them?

6)  Where is the --> return described?

Yours in confusion,
-T

Re: What are the official names?

[ToddAndMargo]

On 10/2/18 4:47 PM, David Green wrote:

On 2018-10-02 4:06 pm, ToddAndMargo wrote:

What is the official Perl syntaxland name of the [] subroutine?
If you search for "[]" at https://docs.perl6.org, it will turn up the 
routine "postcircumfix [ ]", which links to 



https://docs.perl6.org/language/subscripts 





-David



Thank you!

One down, one to go!

:-)

Re: No. It is lucid! Re: Could this be any more obscure?

[ToddAndMargo]

On 9/30/18 9:11 PM, Richard Hainsworth wrote:

But I thought you just implied you wanted pro stuff, not beginner stuff. 


I have no idea how you got that out of what I said.  I want the
beginners stuff included with the pro stuff.


So what is wanted is 'common user' stuff (see below).


You are mixing socialist political terms with what I
am stating.  By "common user" I mean a typical user.
The term was meant to differentiate typical users from
experts.

Actually, I do not understand what you are saying at all, eg., 'I have 
know how to use ...' is not clear.


Again, I have no idea how you got that out of what I said.
When I use a function all the time, I know who to use the
function.  The problem was that I could not reverse engineer
the documentation.  In other words, I figured out how to
use the function from other sources than the documentation.
Had I used the documentation, I never would have figured it out.
That is the issue.



But I am confused about what *you* want from the reference documentation.


I think maybe there is a translation issue between your native
language and mine.  I have been very clear what I am
after, so I won't repeat it yet again.



    3) when calling other term to explain things, it should
   pick the easiest term available. It should not pick
   any nasty, advanced terms.  (Unless the writer enjoys
   confusing the reader and bragging about how smart
   he is.  And he is a jerk.)
This does not seem to be correct English. 


You are again missing the point.  It is wonderful if the writer
wants to share an interesting, complex way of doing things.
But only AFTER he explains it in is simple terms.  You don't
share a calculus equation with someone until after you
teach them the fundamentals of arithmetic.


We come again to this category: 'the common user'. This person (possibly 
there are more) is not a 'beginner' nor a 'pro'. What is to be expected 
of a 'common user' of perl6? Can we assume that a 'common user' has read 
an introduction to perl6?


You are mixing socialist political terms with what
I am saying again.


Perl 5's perldoc did a wonderful job of this.

I never liked perldoc. 'To whom how', as they say in Russian.


I find perldocs from the command line a total pain in the butt.
Fortunately, it is repeated on web beautifully.



I have been posting RFE about this as they come up.
So I am trying to be part of the solution instead
of constantly gripping about the problem.


Indeed this discussion has, at times, been gripping, but I hope you 
don't think I have been griping. ;)


I think that there is a translation and maybe a cultural difference
that has lead you to misconstrue my statements.  That or you are
just trying to pick a fight.  Your "buffoon in the White House"
statement is definitely trying to pick a fight.

Re: No. It is lucid! Re: Could this be any more obscure?

[ToddAndMargo]

On 10/1/18 4:17 PM, Brandon Allbery wrote:
That just sounds like the backing store got restored from backup, losing 
anything added after the backup was taken. Which is not the best way to 
do things (incrementals are nice), but if things had gone wrong enough 
might have been the best they could do.


That does sound very plausible.

What are the official names?

[ToddAndMargo]

Hi All,

What is the official Perl syntaxland name of the following line?

multi method words(Str:D $input: $limit = Inf --> Positional)


What is the official Perl syntaxland name of the [] subroutine?
$ p6 'my @x=[1,2,3,4]; @x[3,2,1,0].say;'
(4 3 2 1)

$ p6 'my @x=[1,2,3,4]; @x[2,3,0,1].say;'
(3 4 1 2)


Many thanks,
-T

Re: Could this be any more obscure?

[Ralph Mellor]

>> On 10/1/18 3:37 PM, Donald Hunter wrote:
>>  > Methods don't accept [], values that are positional do that.
>> Is your distinction that [] is actually a routine in itself
>> and not part of the method?  And I am lumping them together?
On 10/2/18 12:18 AM, Laurent Rosenfeld via perl6-users wrote:
> Yes, [] acts on the result (a positional, e.g. a list) returned by
> function or method, it does not act on the function or method itself.

"acts on the result" is a beautiful way to state it.

Just to be clear, the fact that it acts on the result of a method
or function doesn't mean a method or function or result has to
be involved. Consider:

@array[0]

A variable `@array` may well not be a result of anything.



The thing on the left of a postfix `[...]` may not even do the `Positional`
role.

The postfix `[]` operattor turns into an an `AT-POS` method call if
the thing on the left is a `Positional`. The Positional role defines
an `AT-POS` method. Anything that does the `Positional` role will
work as the left hand side of a postfix `[...]`.

But other types that *don't* do the `Positional` role can still have
an `AT-POS` method and a postfix `[...]` will work with them too.

--

In particular the built in `Any` has an `AT-POS`.

So you can append a `[...]` to any single thing and it'll work:

42[0]

The above results in 42.

42[1]

yields "Index out of range. Is: 1, should be in 0..0"

-

So, to recap: a postfix `[]` acts on whatever is on its left,
pulling out elements from the thing on its left, treated as
a list like thing, with the elements selected according to
the index(es) inside the brackets.

--
raiph

Re: Could this be any more obscure?

[Elizabeth Mattijsen]

Also, a hopefully less steep introduction:

 
  https://opensource.com/article/18/9/signatures-perl-6


> On 2 Oct 2018, at 11:01, Simon Proctor  wrote:
> 
> https://docs.perl6.org/type/Signature
> 
> Todd can I ask that you read this page of the docs for two reasons. Firstly 
> understanding Signatures will go a long way to helping you to understand the 
> rest of the docs, and secondly so you can give use your take on it pointing 
> out any areas you think could be more clear.
> 
> I personally think that grasping the signature system is fundamental in 
> moving from Perl 5 to Perl 6 and in reading the Perl6 docs. 
> 
> Simon
> 
> On Tue, 2 Oct 2018 at 09:41, ToddAndMargo  wrote:
> >> Le dim. 30 sept. 2018 à 11:32, ToddAndMargo  >> > a écrit :
> >> 
> >> On 9/26/18 7:27 PM, Brandon Allbery wrote:
> >>  > And again: this is only because you know perl 5. People are not born
> >>  > knowing perl 5; to someone who doesn't know it, perldoc raises
> >> the same
> >>  > kinds of questions you have been asking, and the answers have to be
> >>  > found in perlsyn or perldata, etc. Which is exactly what you have
> >> been
> >>  > complaining about with respect to perl 6 doing the same kind of
> >> thing.
> >> 
> >> Geez Louise Bradley!  The above is a really bad argument!
> >> 
> >> "perldocs -f xxx" is a bazillion times easier to understand
> >> than Perl 6's manual, regardless if you know Perl 5 or not.
> >> 
> >> And, by the way, I wonder just how may are coming to Perl 6
> >> without ANY Perl 5 experience?
> >> 
> >> In every instance I can look up, perldocs puts Perl 6's
> >> documentation to shame.
> >> 
> >> A simple comparison: which one leaves you knowing how to use
> >> the function and which one leaves you wondering "What the h***???"
> >> 
> >> $ perldoc -f join
> >>   join EXPR,LIST
> >>   Joins the separate strings of LIST into a single
> >> string with
> >>   fields separated by the value of EXPR, and returns
> >> that new
> >>   string. Example:
> >> 
> >>  my $rec = join(':',
> >> $login,$passwd,$uid,$gid,$gcos,$home,$shell);
> >> 
> >>   Beware that unlike "split", "join" doesn't take a pattern
> >>   as its first argument. Compare "split".
> >> 
> >> 
> >> 
> >> https://docs.perl6.org/routine/join#(List)_routine_join
> >> 
> >>   (List) routine join
> >> 
> >>   Defined as:
> >> 
> >>   subjoin($separator, *@list --> Str:D)
> >>   method join(List:D: $separator --> Str:D)
> >> 
> >>   Treats the elements of the list as strings, interleaves
> >>   them with $separator and concatenates everything into a
> >>   single string.
> >> 
> >>   Example:
> >> 
> >>   join ', ', ; # RESULT: «a, b, c»
> >> 
> >>   Note that the method form does not flatten sublists:
> >> 
> >>   say (1, ).join('|'); # OUTPUT: «1|a b c␤»
> >> 
> >> 
> >> Oh and what the &*@% is a "*@list"?  And why does the sub have one
> >> and the method does not?  They are suppose to be identical.
> >> 
> >> -T
> >> 
> 
> On 9/30/18 4:01 AM, Laurent Rosenfeld wrote:
> > Hi Todd,
> > I disagree with you. The P6 documentation can certainly be improved, but 
> > it is quite good and clear already. Remember that it is technical 
> > documentation, not a tutorial.
> > 
> > And the example you chose to give does not support your point: the P6 
> > documentation for join is just at least as clear as the P5 documentation 
> > on the same function.
> > 
> > When I wrote my book on Perl 6, there was no other P6 book around, so I 
> > had to rely heavily on the existing documentation for all kinds of 
> > syntax details, and I found that is was quite useful and even easy (and 
> > it has improved quite a bit since then). You're welcome to help 
> > improving the documentation, but, please, don't say it's bad just 
> > because you don't want to make the effort needed to understand it.
> > 
> > If you don't understand the signatures in the documentation, you've 
> > basically two possible solutions: just skip them, as you can certainly 
> > understand how to use a built-in function without understanding the 
> > signature (but it is still very useful to have the signature definition 
> > in the documentation), or bite the bullet and learn how to read signatures.
> > 
> > Despite your denegation, I think that what you really need is to read a 
> > good tutorial or book on Perl 6. If you had made a real effort to read 
> > such introductory material, you would probably not have needed to ask 
> > about 90% of the questions you asked lately. Do yourself a favor: read 
> > good introductory material (tutorials or books).
> > 
> > HTH,
> > Laurent.
> > 
> > 
> 
> Hi Laurent,
> 
> You already know what to expect. 

Re: Could this be any more obscure?

[Simon Proctor]

https://docs.perl6.org/type/Signature

Todd can I ask that you read this page of the docs for two reasons. Firstly
understanding Signatures will go a long way to helping you to understand
the rest of the docs, and secondly so you can give use your take on it
pointing out any areas you think could be more clear.

I personally think that grasping the signature system is fundamental in
moving from Perl 5 to Perl 6 and in reading the Perl6 docs.

Simon

On Tue, 2 Oct 2018 at 09:41, ToddAndMargo  wrote:

> >> Le dim. 30 sept. 2018 à 11:32, ToddAndMargo  >> > a écrit :
> >>
> >> On 9/26/18 7:27 PM, Brandon Allbery wrote:
> >>  > And again: this is only because you know perl 5. People are not
> born
> >>  > knowing perl 5; to someone who doesn't know it, perldoc raises
> >> the same
> >>  > kinds of questions you have been asking, and the answers have to
> be
> >>  > found in perlsyn or perldata, etc. Which is exactly what you have
> >> been
> >>  > complaining about with respect to perl 6 doing the same kind of
> >> thing.
> >>
> >> Geez Louise Bradley!  The above is a really bad argument!
> >>
> >> "perldocs -f xxx" is a bazillion times easier to understand
> >> than Perl 6's manual, regardless if you know Perl 5 or not.
> >>
> >> And, by the way, I wonder just how may are coming to Perl 6
> >> without ANY Perl 5 experience?
> >>
> >> In every instance I can look up, perldocs puts Perl 6's
> >> documentation to shame.
> >>
> >> A simple comparison: which one leaves you knowing how to use
> >> the function and which one leaves you wondering "What the h***???"
> >>
> >> $ perldoc -f join
> >>   join EXPR,LIST
> >>   Joins the separate strings of LIST into a single
> >> string with
> >>   fields separated by the value of EXPR, and returns
> >> that new
> >>   string. Example:
> >>
> >>  my $rec = join(':',
> >> $login,$passwd,$uid,$gid,$gcos,$home,$shell);
> >>
> >>   Beware that unlike "split", "join" doesn't take a
> pattern
> >>   as its first argument. Compare "split".
> >>
> >>
> >>
> >> https://docs.perl6.org/routine/join#(List)_routine_join
> >>
> >>   (List) routine join
> >>
> >>   Defined as:
> >>
> >>   subjoin($separator, *@list --> Str:D)
> >>   method join(List:D: $separator --> Str:D)
> >>
> >>   Treats the elements of the list as strings, interleaves
> >>   them with $separator and concatenates everything into a
> >>   single string.
> >>
> >>   Example:
> >>
> >>   join ', ', ; # RESULT: «a, b, c»
> >>
> >>   Note that the method form does not flatten sublists:
> >>
> >>   say (1, ).join('|'); # OUTPUT: «1|a b c␤»
> >>
> >>
> >> Oh and what the &*@% is a "*@list"?  And why does the sub have one
> >> and the method does not?  They are suppose to be identical.
> >>
> >> -T
> >>
>
> On 9/30/18 4:01 AM, Laurent Rosenfeld wrote:
> > Hi Todd,
> > I disagree with you. The P6 documentation can certainly be improved, but
> > it is quite good and clear already. Remember that it is technical
> > documentation, not a tutorial.
> >
> > And the example you chose to give does not support your point: the P6
> > documentation for join is just at least as clear as the P5 documentation
> > on the same function.
> >
> > When I wrote my book on Perl 6, there was no other P6 book around, so I
> > had to rely heavily on the existing documentation for all kinds of
> > syntax details, and I found that is was quite useful and even easy (and
> > it has improved quite a bit since then). You're welcome to help
> > improving the documentation, but, please, don't say it's bad just
> > because you don't want to make the effort needed to understand it.
> >
> > If you don't understand the signatures in the documentation, you've
> > basically two possible solutions: just skip them, as you can certainly
> > understand how to use a built-in function without understanding the
> > signature (but it is still very useful to have the signature definition
> > in the documentation), or bite the bullet and learn how to read
> signatures.
> >
> > Despite your denegation, I think that what you really need is to read a
> > good tutorial or book on Perl 6. If you had made a real effort to read
> > such introductory material, you would probably not have needed to ask
> > about 90% of the questions you asked lately. Do yourself a favor: read
> > good introductory material (tutorials or books).
> >
> > HTH,
> > Laurent.
> >
> >
>
> Hi Laurent,
>
> You already know what to expect.  You are an advanced user.
> And I would have to tentatively agree with you. The documentation
> does "seem" to be extraordinarily well written for advanced
> developer level users.  Just the sort of reader that does not
> need t

Re: Could this be any more obscure?

[ToddAndMargo]

Le dim. 30 sept. 2018 à 11:32, ToddAndMargo > a écrit :


On 9/26/18 7:27 PM, Brandon Allbery wrote:
 > And again: this is only because you know perl 5. People are not born
 > knowing perl 5; to someone who doesn't know it, perldoc raises
the same
 > kinds of questions you have been asking, and the answers have to be
 > found in perlsyn or perldata, etc. Which is exactly what you have
been
 > complaining about with respect to perl 6 doing the same kind of
thing.

Geez Louise Bradley!  The above is a really bad argument!

"perldocs -f xxx" is a bazillion times easier to understand
than Perl 6's manual, regardless if you know Perl 5 or not.

And, by the way, I wonder just how may are coming to Perl 6
without ANY Perl 5 experience?

In every instance I can look up, perldocs puts Perl 6's
documentation to shame.

A simple comparison: which one leaves you knowing how to use
the function and which one leaves you wondering "What the h***???"

$ perldoc -f join
  join EXPR,LIST
  Joins the separate strings of LIST into a single
string with
  fields separated by the value of EXPR, and returns
that new
  string. Example:

 my $rec = join(':',
$login,$passwd,$uid,$gid,$gcos,$home,$shell);

  Beware that unlike "split", "join" doesn't take a pattern
  as its first argument. Compare "split".



https://docs.perl6.org/routine/join#(List)_routine_join

  (List) routine join

  Defined as:

  subjoin($separator, *@list --> Str:D)
  method join(List:D: $separator --> Str:D)

  Treats the elements of the list as strings, interleaves
  them with $separator and concatenates everything into a
  single string.

  Example:

  join ', ', ; # RESULT: «a, b, c»

  Note that the method form does not flatten sublists:

  say (1, ).join('|'); # OUTPUT: «1|a b c␤»


Oh and what the &*@% is a "*@list"?  And why does the sub have one
and the method does not?  They are suppose to be identical.

-T



On 9/30/18 4:01 AM, Laurent Rosenfeld wrote:

Hi Todd,
I disagree with you. The P6 documentation can certainly be improved, but 
it is quite good and clear already. Remember that it is technical 
documentation, not a tutorial.


And the example you chose to give does not support your point: the P6 
documentation for join is just at least as clear as the P5 documentation 
on the same function.


When I wrote my book on Perl 6, there was no other P6 book around, so I 
had to rely heavily on the existing documentation for all kinds of 
syntax details, and I found that is was quite useful and even easy (and 
it has improved quite a bit since then). You're welcome to help 
improving the documentation, but, please, don't say it's bad just 
because you don't want to make the effort needed to understand it.


If you don't understand the signatures in the documentation, you've 
basically two possible solutions: just skip them, as you can certainly 
understand how to use a built-in function without understanding the 
signature (but it is still very useful to have the signature definition 
in the documentation), or bite the bullet and learn how to read signatures.


Despite your denegation, I think that what you really need is to read a 
good tutorial or book on Perl 6. If you had made a real effort to read 
such introductory material, you would probably not have needed to ask 
about 90% of the questions you asked lately. Do yourself a favor: read 
good introductory material (tutorials or books).


HTH,
Laurent.




Hi Laurent,

You already know what to expect.  You are an advanced user.
And I would have to tentatively agree with you. The documentation
does "seem" to be extraordinarily well written for advanced
developer level users.  Just the sort of reader that does not
need to use it as they already know what is going on.

When you know how to use a function but can't reverse
engineer how to do it from the documentation, then you
are in real trouble.

I am thinking of doing an RFE to place at the front
of the routines documentation that introduces the reader
on how to read THAT line in the documentation -- what
the abbreviations and symbols and the like mean.

If I do, I will post it here first for criticism.

Your thoughts?

-T

Re: Could this be any more obscure?

[ToddAndMargo]

On 10/1/18 1:20 AM, Siavash wrote:


You can read the thread here:
https://www.nntp.perl.org/group/perl.perl6.users/2018/09/msg5757.html

On 2018-10-01 04:21:43 +0330, ToddAndMargo wrote:

Hi All,

My "Perl" box got corrupted and in the process of rebuilding
it I lost this thread except for one one message from JJ.
Anyway, I am not deliberately ignoring anyone, I just
lost the thread.

:'(

-T


Thank you!

Something must has appeased the imap gods and the entire thread
came storming back one entry at a time.

But the note I sent says it had be erased did not.  Then a day
later it appeared too.


Hm

Re: Could this be any more obscure?

[ToddAndMargo]

Le mar. 2 oct. 2018 à 08:05, ToddAndMargo > a écrit :


On 10/1/18 3:37 PM, Donald Hunter wrote:
 > toddandma...@zoho.com 
(ToddAndMargo) writes:
 >>
 >> Hi Curt,
 >>
 >> Perfect! Thank you!
 >>
 >> So all methods that respond with --> Positional will accept []
 >>
 >> Awesome!
 >>
 >> -T
 >
 > Not quite.
 >
 > All methods that respond with --> Positional, provide a
Positional that
 > will accept []
 >
 > Methods don't accept [], values that are positional do that.
 >
 > Cheers,
 > Donald.
 >

Hi Donald,

I am confused.  I though we both said the same thing?
Is your distinction that [] is actually a routine in itself
and not part of the method?  And I am lumping them together?

-T



On 10/2/18 12:18 AM, Laurent Rosenfeld via perl6-users wrote:
Yes, [] acts on the result (a positional, e.g. a list) returned by 
function or method, it does not act on the function or method itself.


You have more or less the same in Perl 5, for example:

my $first_item = (split /;/, $string)[0];

Here, the [0] acts on the list returned by split.



"acts on the result" is a beautiful way to state it.

Thank you!

Re: Could this be any more obscure?

[Laurent Rosenfeld via perl6-users]

Yes, [] acts on the result (a positional, e.g. a list) returned by function
or method, it does not act on the function or method itself.

You have more or less the same in Perl 5, for example:

my $first_item = (split /;/, $string)[0];

Here, the [0] acts on the list returned by split.


Le mar. 2 oct. 2018 à 08:05, ToddAndMargo  a écrit :

> On 10/1/18 3:37 PM, Donald Hunter wrote:
> > toddandma...@zoho.com (ToddAndMargo) writes:
> >>
> >> Hi Curt,
> >>
> >> Perfect! Thank you!
> >>
> >> So all methods that respond with --> Positional will accept []
> >>
> >> Awesome!
> >>
> >> -T
> >
> > Not quite.
> >
> > All methods that respond with --> Positional, provide a Positional that
> > will accept []
> >
> > Methods don't accept [], values that are positional do that.
> >
> > Cheers,
> > Donald.
> >
>
> Hi Donald,
>
> I am confused.  I though we both said the same thing?
> Is your distinction that [] is actually a routine in itself
> and not part of the method?  And I am lumping them together?
>
> -T
>