On Tue, 10 Dec 2019 at 02:40, ToddAndMargo via perl6-users < 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/
