*From:* William Michels <w...@caa.columbia.edu
<mailto:w...@caa.columbia.edu>>
*Sent:* Sunday, August 30, 2020 2:44:55 PM
*To:* yary <not....@gmail.com <mailto:not....@gmail.com>>
*Cc:* perl6-users <perl6-us...@perl.org <mailto:perl6-us...@perl.org>>;
ToddAndMargo <toddandma...@zoho.com <mailto:toddandma...@zoho.com>>;
Brad Gilbert <b2gi...@gmail.com <mailto:b2gi...@gmail.com>>
*Subject:* Re: lines :$nl-in question
Do you agree with that definition, Yary? Brad? Here it is:
"Invocant"
"Caller, the one who calls or invokes. The invocant of a method would
be the object on which that method is being called, or, in some cases,
the class itself. Invocant is used instead of caller because the
latter refers to the scope."
https://docs.raku.org/language/glossary#Invocant
At first blush, the definition at
https://docs.raku.org/language/glossary#Invocant contradicts the
definition given to us by Brad. English speaker will typically use the
following word pairs to denote 1. an actor and 2. a recipient of some
action. So we have the following:
Payer vs. Payee
Lessor vs. Lessee
Employer vs. Employee
So going with the typical English usage above, the pattern would
continue with "Caller" vs "Callee" and "Invoker" vs
"Invokee/Invocant". Therefore my humble reading of the definition
given by Brad, as well as a post authored by a certain TChrist on
StackExchange [1], suggests to me that "Invocant" is a synonym for
"Callee" (or the possibly-imaginary word "Invokee"). One can look at
the definition of "Invoker" online provided by Oracle with regards to
the Java programming language [2], to further distinguish "Invoker" vs
"Invocant".
HTH, Bill.
W. Michels, Ph.D.
[1] https://english.stackexchange.com/a/59070
[2]
https://docs.oracle.com/javase/8/docs/api/index.html?javax/xml/ws/spi/Invoker.html
On Sun, Aug 30, 2020 at 9:54 AM yary <not....@gmail.com
<mailto:not....@gmail.com>> wrote:
The Raku glossary has a definition
https://docs.raku.org/language/glossary#Invocant
suggestion, link to that where the term appears.
-y
On Sun, Aug 30, 2020 at 9:16 AM William Michels via perl6-users <perl6-us...@perl.org
<mailto:perl6-us...@perl.org>> wrote:
Inline:
On Sun, Aug 30, 2020 at 12:49 AM Brad Gilbert <b2gi...@gmail.com
<mailto:b2gi...@gmail.com>> wrote:
>
> Invocant is in the dictionary though.
>
> In fact it is from Latin.
>
> Origin & history:
> Derived from in- + vocō ("I call").
>
> Verb:
> I invoke
> I call (by name)
>
> In fact that is pretty close to the same meaning as it is used in the Raku
docs.
>
> It is the object that we are calling (aka invoking) a method on.
Maybe we can meet Todd halfway?
>
> On Sat, Aug 29, 2020 at 6:39 PM ToddAndMargo via perl6-users <perl6-us...@perl.org
<mailto:perl6-us...@perl.org>> wrote:
>>
>> On 2020-08-28 23:51, Tobias Boege wrote:
>> > On Fri, 28 Aug 2020, ToddAndMargo via perl6-users wrote:
>> >> https://docs.raku.org/type/IO::Path#method_lines
>> >>
>> >> (IO::Path) method lines
>> >>
>> >> Defined as:
>> >>
>> >> method lines(IO::Path:D: :$chomp = True, :$enc = 'utf8', :$nl-in = ["\x0A",
"\r\n"], |c --> Seq:D)
>> >>
>> >> Opens the invocant and returns its lines.
"Opens the invocant (i.e. the object being called) and returns its lines."
[Add text in parentheses above only once per method, when the word
'invocant' is first used].
Comments?
Best Regards, Bill.
On 2020-08-30 14:08, Stuckwisch, Matthew wrote:
So I guess I got included on this as the resident language professor :-)
(although I probably should subscribe to p6 users at some point) I
didn't see the whole thread in the e-mail I got copied in on, so
apologizes if I repeat much.
I'll spare everyone all the linguistic details, but suffice it to say,
invocant and invoker are functionally equivalent. The former is a
nominalized adjective, and the latter a noun proper. They mean "the one
that invokes (calls)". We can use either, but I'd recommend we be very
consistent. Invocant seems to be the preferred, so let's use it
exclusively. On the other side, we have invoked and invokee, which in
English share a similar distinction (although nominalizing the former
often sounds odd, and adjectifying the latter would probably be read as
missing a genitive 's).
Summed up, we should avoid using invocant to refer to a method that's
being called. Generally, just calling it a "method" is sufficient, but
if need be, I'd go with "the invoked method". We probably can write
documentation to avoid the formalisms altogether, though, by saying
something to the effect of
> Opens the file [represented by the [calling] object] and returns its
lines.
That's fairly simple and clear. In an article about signatures,
however, I think using the term is absolutely appropriate, and warrants
defining it parenthetically inline as "the object that calls/invokes the
associated method". I get that using the word "call" muddies the water
(the formal distinction that tchrist was getting at is that a sub has no
invocant except perhaps a calling context, ie the "caller" — which a
method also has), but we already did that by having methods use CALL-ME
instead of INVOKE-ME :-) *
MSS
Hi Everyone,
I would like add to the wonderful dialog above.
Th start, one of the things I absolutely adore about
Raku is that it is human readable, making it easy to
maintain. You can make it into a "write only" language
if you wish along the lines of Perl 5, but it takes
some sloppy writing.
The docs are not so much human readable. They are
refreshers for those that "already know" what they
doing. I dearly wish this would change. The
framework is good, it just needs some polish so
beginners can use it too -- those that need the
manual because they "do not" know what they are
doing.
1) That being said, I do realize that in a programming
language it is absolutely impossible to get around
esoteric terms, those requiring "insider knowledge".
But that problem is very easy to get around. As
Yary wonderfully states in one sentence:
"suggestion, link to that where the term appears."
Whenever an esoteric term appears, link it to
https://docs.raku.org/language/glossary
This uses the current framework and only required
inserting links. And it succeeds in removing
the need scratch ones head thing "what is that
suppose to mean?"
2) the glossary should not be written like a lawyer
writes an obscure legal document. For example:
https://docs.raku.org/language/glossary#Invocant
Caller, the one who calls or invokes. The invocant
of a method would be the object on which that method
is being called, or, in some cases, the class itself.
Invocant is used instead of caller because the latter
refers to the scope.
Huh? What is that suppose to mean? A better description
would be (borrowing from Brad, the dictionary, and myself):
Invocant: derived from the Latin invocan: invocare
to invoke. It is the object that we are calling
(a.k.a. invoking) a method on. It is the data that
is being fed to the function (method, subroutine, etc.)
from another function. For example:
raku -e 'say sqrt(2);'
1.4142135623730951
raku -e 'say( sqrt(2) );'
1.4142135623730951
In the above, the invocant would be `sqrt(2)` which is
fed to `say`
I am sure others can clean up the above to make it even
better to understand. And examples can be worth millions
of words.
Here is an example of me trying to improve the problem:
RFE: add some links to Operators #3175
https://github.com/Raku/doc/issues/3175
prefix: +foo
'pre' means something like 'before'. What is before
then. It is about operators. So an operator goes
before an argument. '+foo' here could then be +$a.
Other prefix
examples are ?$a, !$a, -$a, .
It covers more operators too. There is NO DOUBT what
there terms mean when I am done. Unfortunately, the
RFE was shot down by JJ as
"I don't really think we should go down to that
level of detail."
I am sorry, but yes you do. The manual needs to be
usable by more than those that already know what they
are doing and DO NOT NEED IT.
And again, it can be accomplished with in the
current framework.
3) The "signature" blocks need to me explained.
They also need to be accurate.
For instance:
https://docs.raku.org/routine/print
multi method print(--> Bool:D)
a) It is inaccurate, as it is missing the data source.
"Seg:D" I do believe, whatever describes "**@args".
b) The invocant need to be described:
i) the data source need to be described
ii) the result need to be described (Bool:d)
iii) any options need to be described.
My big criticism of signatures, besides them being
inaccurate a lot, is that they are too complicated to
pick up at first glance and I usually ignore them
and go straight to the examples. The inaccuracy
causes a lot of confusion.
But this does not have to be. After seeing them broken
down enough times, understand "signatures" will become
down right easy. They are a VERY POWERFUL too. They
should not remain shrouded in inaccuracy and mystery.
And as a side benefit, breaking them down also helps
the technical writer. He will quickly catch his
mistakes in the signature line.
Again, this uses the current framework, It just polishes
it up.
4) The examples should be for the item being described.
No showing off.
For example:
https://docs.raku.org/type/IO::Path#method_lines
say "The file contains ",
'50GB-file'.IO.lines.grep(*.contains: 'Perl').elems,
" lines that mention Perl";
# OUTPUT: «The file contains 72 lines that mention Perl»
This is not appropriate as an example for "lines". Maybe
"grep" or "elems", but not lines. Also it does not show
an example of the signature block as all the options are
missing.
And it does not help that the Signature line is also
wrong. ":$chomp = True" is wrong as IO::Path removes
the line feeds and chomp is ignored.
Here is a wonderful example of a clean up. This
was prompted by my
A booboo and an rfe in contains documentation #2334
https://github.com/Raku/doc/issues/2334
https://docs.raku.org/type/Str#method_contains
Given a Str invocant (known as the haystack) and a
first argument (known as the $needle), it searches
for the $needle in the haystack from the beginning
of the string and returns True if $needle is found.
If the optional parameter $pos is provided, then
contains will search the haystack starting from
$pos characters into the string.
The only thing I would have done different was to
break each parameter down into different lines.
A does this
B does this
C does this
But I can easily live with the above. And they
cleaned up the signature line so it was accurate.
Again, within the current framework.
My 2 cents. Hopefully, William is not shaking his
head too hard over my poor writing. Thank you
all for suffering me.
Raku is just damned fun to write in
:-)
-T
