On 2019-12-10 01:14, Simon Proctor wrote:
On Tue, 10 Dec 2019 at 02:40, ToddAndMargo via perl6-users
<perl6-us...@perl.org <mailto:perl6-us...@perl.org>> wrote:
On 2019-12-09 07:21, Simon Proctor wrote:
> I think this does highlight something we probably should document
more.
>
> How to read signatures. Because it's a *very* powerful part of the
> language that if you don't understand you're only using it at
half strength.
>
> multi method contains(Str:D: Cool:D $needle, Cool:D $pos --> Bool:D)
>
> If not some documentation magic, it's a core part of the
language. It
> tell you this method is called on a defined Str (Str:D:) it takes 2
> positional arguments which have to be defined Cool types ($needle
and
> $pos) and it returns a Boolean.
>
> That is the code as it will be written in the Str Role.
>
> I *highly* advise learning how signatures work.
Firstly can I say I admire the fact that you are using Raku in
production on a regular basis.
Hi Simon,
Did you see the How To post I made on ".contains"? At
the bottom of the How To, I take apart the signature
and explain each part.
I did. It's pretty good except your understanding of the first part Str:D :
This indicates that this method will be used when it's called on a
defined (D) String instance. The wording you use is a bit weird and it
speak to my beliefe that you don't really get Signatures.
Do you see anywhere in the docs where how to read
signatures is explained? (Don't get any ideas. The
signatures should not be there to start with.)
Apart from here? https://docs.raku.org/type/Signature
I read through this (and some bits on Captures) and was able to get
enough information to give a talk at the Perl Conference in Glasgow in 2018.
Here's the video :
https://www.youtube.com/watch?v=V5rWtKIVmJc&list=PLQTGmZanuBovAKtE0dDs7rdTUvxnOwvEz
Larry was there, it was rather stressful.
An aside on the signatures: what is and what is
not a separator can blow your mind.
Not really. comma seperates arguments, colon can be used if you want to
specify information about the calling instance or class.
Do you think it help me or anyone else understand
how to use ".contains" because I explained the
"Signature"? Seriously?
No, I don't think you NEED the signature to understand contains. I think
that understanding and being able to read signatures CAN help you
understand more about how a subroutine or method works.
To answer the question, look at all the various
teaching manuals out there for Raku. Do you see a
SINGLE ONE, other that the one I posted, that
uses the signatures as a teaching tool?
I have every single book written about Raku (though of course most are
Perl6) and most of them explain Signatures.
Again I'm not saying that they should be used as a teaching tool, but
the documentation has a lot of uses and it's not just teaching.
And notice that I put the signature explanation
at the bottom AFTER I explained how to use the
function (method). This is akin to the good math
teachers that run circles around bad math teachers
in both mechanics and theory by FIRST teaching the
mechanics and them teaching the theory. When
teaching, you should never start with the theory.
The docs do just that.
So when I was first reading the docs I mostly just skipped over the
signatures to get to the rest of the code. I didn't try and understand
them too much "Oh this takes a string, makes sense".
Over time I did start to learn them and that helped me getting better at
programming Perl6.
The "Signatures" in the docs only confuse and often
have mistakes in them. Trying to get them corrected
is a fools errand too.
How do you mean? If there's a mistake in the signature you can fix it in
the docs and put in a pull request to get it updated.
The signatures are how the developers talk to each other.
And judging by the results of their work, it works
marvelously for them. This kind of information is
not appropriate for standard Rakoon that just wants to
write code.
Here is where I have to respectfully disagree with you.
Writing Raku code without using Signatures and Multi Methods is like
owning a Jaguar and only driving in first gear. I mean *technically* you
can get where you want to go but you are forgoing a lot of the power of
the language.
I generally write a couple of Raku scripts a week (more if I've got the
time) and they *all* use Signatures. Most use multi methods too.
You don't need to know how much current affects an LED
diode to read the time on your digital clock. This
is what the signatures are doing.
The Signatures only confuse. They need to be left to
the developers.
This is the problem, until you stop treating signatures as some kind of
weird messaging system only to be used by "the developers" you will be
coding with one hand tied behind you back. You'll also keep asking the
same questions over and over again.
Please take a moment to really try and understand them. It will blow
your mind.
-T
With respect.
--
Simon Proctor
Cognoscite aliquid novum cotidie
http://www.khanate.co.uk/
Hi Simon,
Thank you for such a wonderful, respectful letter. You make
a lot of sound points.
"Str"
means it want to be fed data as a string. Str.foo
was meant to bring the complicated down to a simple, understandable
level. Is not your "This indicates that this method will be used when
it's called on a defined (D) String instance" doing the same thing only
far more words and
far more technical?
Layman's terms, the data from Str (the Haystack) gets
input (fed) to .constains which looks to see if the fragment
you gave contains (the Needle) is inside the Haystack.
If it does, it return a Boolean True, otherwise it return False.
I too usually skip over the signatures and look at the
examples. Typically I will run an example, if it fits
what I am after and play with it. I have caught the examples
crashing at times too.
Maybe I would look at the signatures more, *if* I trusted
them to be accurate. I don't. Yes, I should report them
when I find them wrong, but it requires a lot of arguing
to get them accepted and I just don't have the time.
The culture on the bug reporter is more akin to
LibreOffice's culture and not Fedora's.
As far a separators, both commas and colons are used as separators.
Colons are used for other things too. It
is not always apparent what a colon is being used for.
My main gripe with the documentation is how it is presented.
One does not need to know how to do Matrix Math to
add two numbers. That is jumping too far ahead. The
docs should not expect the user to have advanced level
knowledge of Raku.
Just an aside, my all time worst programming language is
Windows Batch programming. It must have been designed by
the devil himself. But you know what, even the devil put
help /?
to give a simple list of its functions. This goes back
to jumping too far ahead and expecting the user to have
advanced knowledge of the subject.
If I might posit a solution that would make both of us
happy, lets look at how Math is taught. Those teacher
in my college that first taught the mechanics and then
the theory absoulty wiped the floor with those teachers
that first taught the theory and then expect the
student to pick up the mechanics by osmosis.
So, follow that principle,
First teach what the function does and then after stating
what it does and how to use it (the mechanics), then
AFTER that give the theory (the signature).
Using this method, I bet folks start picking up how to use
the signature 1000 times faster. I know I would. As it stands, now the
signature is more of a migraine to me
than a help.
My four favorite "methods" that I use all the time
are "contains", "kv", "words", and "lines". I ADORE
Raku.
My next big Raku project is to convert my Cobian Backup
wrappers from Batch to Raku. I have started with
supporting modules. So far I have my WinPops and my
WinMount completed.
I love modules (I did a YUGE amount of Modula2 in my past)
I really enjoyed your letter, Thank you!
-T
