On Mon, Jun 08, 2020 at 02:39:10PM -0700, ToddAndMargo via perl6-users wrote: > On 2020-06-08 14:12, Peter Pentchev wrote: > > On Mon, Jun 08, 2020 at 01:28:34PM -0700, ToddAndMargo via perl6-users > > wrote: > > > On 2020-06-08 02:45, Richard Hainsworth wrote: > > > > Ok Todd, let me have a go at this issue. > > > > > > > > From what I understand, you see 'multi' and think 'there are more than > > > > one', which leads to the question 'where are they?' > > > > > > > > My understanding of 'multi' is 'there COULD be more than one', which > > > > leads to the question 'are there any?' > > > > > > > > This is actually a very powerful aspect of Raku. > > > > > > > > There are (as has been stated in this thread) four types of which multi > > > > = 'could be more than one' and only = 'only one' . > > > > > > > > If the developer wrote 'only sub' then, no one else could write a sub > > > > with that name. For a developer of a program or a module, that might be > > > > OK, because it's unlikely anyone else would need/want to use that name. > > > > But for a compiler, the probability is reversed. Someone will want to > > > > use it. That is why in many other languages there are 'reserved words' > > > > which you are not allowed to use. > > > > > > > > In Raku, if you develop a new type, for example say a quodion, and you > > > > want to 'add' quodions, then you CAN use + because it can be overloaded. > > > > It is defined as a multi. > > > > > > > > Or in your most overused example 'needle' can be rewritten to take a > > > > quodion, which may yield a spectrum of results because that's what > > > > quodions are for. > > > > > > > > Since needle is defined as a 'multi', if you write a 'needle' method for > > > > quodions, the needle for strings STILL exists, and Raku will correctly > > > > call the method you wrote for quodions if a quodion is implied, but call > > > > the default needle if a string (or any other type) is used. > > > > > > > > Since you have developed the quodion method entirely for your paid > > > > subscribers, the module is NOT available to the public, so you wont tell > > > > anyone about it. So it doesn't have to be in the documentation. > > > > > > > > Is this making any sense to you? > > > > > > > > Richard > > > > > > > > > Hi Richard, > > > > > > You are perfectly clear and beautifully well written. > > > You did make me look up "quodion". > > > > > > :-) > > > > > > And I am feeling guilty because I did already know all > > > this and it looks like you spent a considerable amount of > > > time getting into my head to formulate an answer that > > > was perfect for me. > > > > > > Here is the thing. I have no objecting to the developer > > > calling something a "multi" or an "only" depending on his > > > needs. That is entirely "HIS" call, "NOT" mine. > > > > > > And I hope the above statement ends all the well meaning, > > > helpful folks who are trying the re-explain the concept > > > to me. I got it a LONG time ago. > > > > > > My objection is when there actually exists more than > > > one and they are not experimental or otherwise hidden > > > for some reason and are truly, actually part of the > > > distribution, then they also should be documented. > > > Updates to the documentation should be part of > > > the code check in process, and in all probability, are. > > > > > > So, basically what I am saying is when multiples are > > > there and are open to the public, than it should be > > > documented. In this situation, why would the > > > developer want his hard work hidden? > > > > OK, let me try to give you another example. If I'm too long-winded, > > there will be an abstract at the end :) > > > > Say somebody is writing a library that should serve as the standard > > library for the C language. Now, there is a published, adopted standard > > for the C language that all C compilers and C standard libraries > > follow[1]. > > > > Now, the C language standard says that there may be more than one > > library - one called "libc" as "the C library" providing pretty much all > > of the functions, and another one called "libm" as "the mathematics > > library" providing some additional functions for more-or-less precise > > mathematical operations[2]. The standard says that the C library must > > provide a function called printf() that prints out all kinds of things > > according to a specific format, and that the maths library must provide > > a function called trunc() that pretty much rounds a real number down to > > the nearest integer that is not larger than it (so trunc(3.0) would return > > 3, trunc(4.5) would return 4, and trunc(-3.5) would return -4). > > > > OK... So somebody is writing a "libc" that must provide the printf() > > function, and they suddenly realize that, in order to be able to print > > out real numbers with, say, two digits after the decimal point, one of > > the easiest ways is to have a function that rounds a real number down. > > So they write such a function, let's call it printf_trunc(), and they > > hide it, they make it internal to the "libc" library, so your programs > > can't see it. Right? Everything's fine, there is an internal function > > that nobody can access. > > > > So the next thing they do is turn to the maths library, and they realize > > that they have to write a trunc() function, and the lightbulb comes on: > > they have *already written* a function that rounds a real number down, > > but for various reasons that *only matter to the author of the library*, > > not to the users of the library, that function needs to live in the > > "libc" library, not in the "libm" library. > > > > OK, but they do not want to do the work twice, they do not want to have > > the same code in both libraries, do they? So they want to make the > > trunc() function in the maths library call the printf_trunc() function > > in the standard C library. But... but that means... that means that > > printf_trunc() may no longer be internal - it *must* be exposed, at least > > to the maths library, and the way the C language works[3], this means > > that *any* program that uses the standard C library can now see > > the printf_trunc() function. That means that anybody who takes the time > > to look at the source of the library can figure out that there is such > > a function and, if they feel adventurous, they may actually call it in > > their own program. > > > > But! and this is the important point. THEY DO NOT WANT TO. > > > > The author of a program - not the author of the library! - but the > > author of a program that uses that library, that is you, that is me, > > this author *does not want* to call a function that is not defined in > > the C standard. This author - you and me - can guess that this function > > is probably an internal one used by some of the other libraries > > developed along with the standard C library. But they don't need to > > guess: they KNOW, from reading the documentation, that this function is > > NOT part of the specification of the C language. Moreover, they KNOW, by > > reading the documentation of the "libc" library, that this function is > > NOT listed there. > > > > So, even though you and I can see the printf_trunc() function, we never > > want to call it. > > > > There is a very important reason for that: it is a function that is > > written solely for the needs of the maths library, and if tomorrow the > > next version of the maths library needs this function to operate in > > another way, maybe add another argument, maybe drop an argument because > > something is handled elsewhere, the C library's printf_trunc() function > > *will change*. And if you or I had used it in our programs, our programs > > would break. > > > > Then, if we go to the author of the library and complain about using the > > printf_trunc() function that is not in the specification of the C > > language and that is not listed in the documentation of the "libc" > > library... the author would say, and I quote, "Huh?!" They would say, > > "Wait... *why* are you using this function? How do you know about... no, > > wait, nevermind how you know about it... *why* are you using a function > > that is neither part of the language specification, nor listed in the > > documentation of this implementation of the language?" > > > > So, you see, the hard work of the author of the library is not hidden. > > It is there for us to see in the printf() function from "libc" and in > > the trunc() function from "libm". Every time we use one of these > > well-known and well-documented functions, we make use of the hard work > > of the author. We do not need to call the internal function to do that. > > > > So, to recap: > > - there are two libraries, "libc" and "libm" > > - "libc" has a function that wants to round numbers down > > - "libm" must have a function that wants to round numbers down > > - the common function to be used by both libraries has to be placed in > > "libc", but it needs to be visible so that "libm" can use it > > - somebody curious enough can look into the sources of "libc" and see > > this function > > - but this somebody must realize that this is an internal, undocumented > > function that serves some purpose for the combination of "libc" and > > "libm" and that is *not* supposed to be used by anything outside these > > two libraries > > - so this somebody will shrug it off, say "hey, there's some kind of > > implementation detail, there's some kind of internal function, okay, > > forget about it" > > > > Hope that helps! > > > > G'luck, > > Peter > > > > [1] ...and to everyone who cringed at that statement... sorry! :) > > Let's go with that for now and push the pain away :) > > > > [2] ...and to everyone who cringed at *that* statement... sorry! :) > > > > [3] ...let's go with "the C language" here, not get into details about > > compilers and linkers and foreign functions and stuff > > > > > Hi Peter, > > I don't get what is going on here. You are of course > correct in everything you write here. You are also off > on a tangent. I totally accept everything you eloquently > state and have for a long time now.
I'm not. I'm explaining why there may be internal functions that must not be included in the documentation. The printf_trunc() function is a (somewhat, but not entirely contrived) example of that. > If a developers writes something, it gets accepted into > the project, he want people to use and see his work, then > he deserved to have it added to the documentation, hopefully > as part of the acceptance, code check in process. That is > ALL I am saying. Not always. Sometimes the developer writes something that is really only useful for the ways the compiler or the virtual machine does things internally. Or sometimes the developer writes something that *must* only be used internally, so that the developer or others after him retain the freedom to change it as the thing that uses it changes. In both these cases the developer is not just fine, but actually *wants* this thing to *not* be part of the documentation. > If for the MULTIPLE reason you state above, he or > the project does not want his work to be shown, then > it is a different story. Well... what I'm saying is that what started this whole story, the three different forms of Str.starts-with(), are just that: two of them are internal functions that do not concern you or me, so they *must not* be in the documentation that we read to know what methods we can use. > It is basically all his/the project's call, not mine. Exactly :) So in that case, the documentation is neither incomplete nor wrong. > I am feeling guilty that you went through all the effort > of trying to re-explain why something would be hidden. > You are an excellent writer and spend a lot of time on > this. I truly did get your point a long time ago. > > And I sincerely appreciate your help! Thanks for the kind words :) G'luck, Peter -- Peter Pentchev r...@ringlet.net r...@debian.org p...@storpool.com PGP key: http://people.FreeBSD.org/~roam/roam.key.asc Key fingerprint 2EE7 A7A5 17FC 124C F115 C354 651E EFB0 2527 DF13
signature.asc
Description: PGP signature
