My keeper on "contains"

Hi All,

I have 190 of these.  191 in the hopper for unicodes.
This is one of my better one.  It is also unique in
that it takes apart the IEEE-eese on the
documentation and explain what in the world is
going on.  Do you notice the ":" is sometimes a delimiter
and sometimes not.  Eee Gads!

Enjoy!

-T


perl 6: method:

Also: "starts-with" and "ends-with"

A method is a routine that you feed: .foo

    $ p6 'say "abc".contains( "a" );'
    True

    $ p6 'say "abc".contains( "z" );'
    False

    $ p6 'my $x="\na\nb\nc\n"; for $x.lines -> $i {print "<$i>\n"};'
    <>
    <a>
    <b>
    <c>


Case insensitive contains:
     $ p6 'if "2018 Jul 7".fc.contains( "jul".fc ) {say "Yes";}'
     Yes

     $ p6 'if "2018 xJul 7".fc.contains( "jul".fc ) {say "Yes";}'
     Yes

     p6 'if "2018 xul 7".fc.contains( "jul".fc ) {say "Yes";}'
     <nothing>

     $ p6 'my $x="strong>2018.2.0; Coming Soon</strong>"; say so 
$x.fc.contains("strong" & not "coming soon");'
     False



multi method contains(Str:D: Cool:D $needle, Int(Cool:D) $pos --> Bool)

"multi method"
     This means there are multiple ways to address this, as in

          multi method contains(Str:D: Cool:D $needle --> Bool)
          multi method contains(Str:D: Str:D $needle --> Bool)
          multi method contains(Str:D: Cool:D $needle, Int(Cool:D) $pos 
--> Bool)
          multi method contains(Str:D: Str:D $needle, Int:D $pos --> Bool)

"Str"
     means it want to be fed data as a string.  Str.foo

":D"
     means it wants actual data in the string and not a Nil.
     The jargon for this requirement is that is is constrained
     to an actual value

     If it wanted a Nil, it would say ":U" or constrained to
     a Nil

":"
     is the delimiter that tells you it is finished defining
     what is wants to be fed

"Cool:D $needle"
     means it wants a type Cool (string or number) for the
     substring ($needle) it is looking for in the Haystack (Str)

"Int(Cool:D)"
     Means it will change a type Cool into a type Int (integer)
     and the ":D" means it want some actual data and not a Nil.

"$pos"
     Is short of Position.  It is the starting index in the
     haystack (Str) to start looking for the substring
     (needle).  Index starts at zero by way of string
     convention in Perl 6

     $pos is an optional parameter.  Instead of $pos?
     for optional, they stated it with several "multi method"
     that do not include $pos.

"-->Bool"
     means it return True or False
0
perl6
12/9/2019 1:45:22 AM
perl.perl6.users 1389 articles. 0 followers. Follow

9 Replies
79 Views

Similar Articles

[PageSpeed] 4

Today's revised revision of yesterday's new revisions
with amendments!

:-)


perl 6: method:
12/10/2019


perl 6: method:
12/10/2019


Also: "starts-with" and "ends-with"

A method is a routine that you feed: .foo

    $ p6 'say "abc".contains( "a" );'
    True

    $ p6 'say "abc".contains( "z" );'
    False

    $ p6 'my $x="\na\nb\nc\n"; for $x.lines -> $i {print "<$i>\n"};'
    <>
    <a>
    <b>
    <c>


Case insensitive contains:
     if "2018 Jul 7".fc.contains( "jul".fc ) {say "Yes";}
     Yes

     if "2018 xJul 7".fc.contains( "jul".fc ) {say "Yes";}
     Yes

     if "2018 xul 7".fc.contains( "jul".fc ) {say "Yes";}
     <nothing>

     Warning: in the following, use "none" not "not" to negate if 
"coming soon"
              is found.  "not" will always return False.

     my $x="strong>2018.2.0; Coming Soon</strong>"; say so 
$x.fc.contains("strong" & none "coming soon");
     False



multi method contains(Str:D: Cool:D $needle, Int(Cool:D) $pos --> Bool)

"multi method"
     This means there are multiple ways to address this, as in

          multi method contains(Str:D: Cool:D $needle --> Bool)
          multi method contains(Str:D: Str:D $needle --> Bool)
          multi method contains(Str:D: Cool:D $needle, Int(Cool:D) $pos 
--> Bool)
          multi method contains(Str:D: Str:D $needle, Int:D $pos --> Bool)

"Str"
     is the string data (Haystack) that will be operated on by the 
method (contains)

":D"
     means it wants actual data in the string and not a Nil.
     The jargon for this requirement is that is is constrained
     to an actual value

     If it wanted a Nil, it would say ":U" or constrained to
     a Nil

":"
     is the delimiter that tells you it is finished defining
     what is wants to be fed

"Cool:D $needle"
     means it wants a type Cool (string or number) for the
     substring ($needle) it is looking for in the Haystack (Str)

"Int(Cool:D)"
     Means it will change a type Cool into a type Int (integer)
     and the ":D" means it want some actual data and not a Nil.

"$pos"
     Is short of Position.  It is the starting index in the
     haystack (Str) to start looking for the substring
     (needle).  Index starts at zero by way of string
     convention in Perl 6

     $pos is an optional parameter.  Instead of $pos?
     for optional, they stated it with several "multi method"
     that do not include $pos.

"-->Bool"
     means it return True or False
0
perl6
12/10/2019 11:12:33 AM
On 2019-12-10 03:12, ToddAndMargo via perl6-users wrote:
> Today's revised revision of yesterday's new revisions
> with amendments!
>=20
> :-)
>

At it again;

perl 6: method:
12/10/2019 #2


Also see: "starts-with" and "ends-with"


References:
     https://docs.raku.org/routine/contains
     https://docs.raku.org/routine/starts-with
     https://docs.raku.org/routine/ends-with
     https://docs.raku.org/routine/lines
     https://docs.raku.org/routine/fc
     https://docs.raku.org/routine/so
     https://docs.raku.org/syntax/Q


A method is a routine that you feed: Str.foo.

Think of "contains" as looking for a Needle in a Haystack.
You feed contains data and what you are lookig for.  In
return is tells you True or False

    say "abc".contains( "a" );
    True

    say "abc".contains( "z" );
    False

    my $x=3D"\na\nb\nc\n"; for $x.lines -> $i {print "<$i>\n"};
    <>
    <a>
    <b>
    <c>


Case insensitive contains:
     Note: "fc" converts you to lower case.  It also converts weird=20
charters to
           something on your keyboard

                say "XY=C3=9FZ".fc;
                xyssz

     if "2018 Jul 7".fc.contains( "jul".fc ) {say "Yes";}
     Yes

     if "2018 xJul 7".fc.contains( "jul".fc ) {say "Yes";}
     Yes

     if "2018 xul 7".fc.contains( "jul".fc ) {say "Yes";}
     <nothing>


Excluding something from the search:

     Warning: in the following, use "none" not "not" to negate if=20
"coming soon"
              is found.  "not" will always return False.

     say so Q[<strong>2018.2.0; Coming=20
Soon</strong>].fc.contains("strong" & none "coming soon");
     False




multi method contains(Str:D: Cool:D $needle, Int(Cool:D) $pos --> Bool)

"multi method"
     This means there are multiple ways to address this, as in

          multi method contains(Str:D: Cool:D $needle --> Bool)
          multi method contains(Str:D: Str:D $needle --> Bool)
          multi method contains(Str:D: Cool:D $needle, Int(Cool:D) $pos=20
--> Bool)
          multi method contains(Str:D: Str:D $needle, Int:D $pos --> Bool=
)

"Str"
     is the string data (Haystack) that will be operated on by the=20
method (contains)

":D"
     means it wants actual data in the string and not a Nil.
     The jargon for this requirement is that is is constrained
     to an actual value

     If it wanted a Nil, it would say ":U" or constrained to
     a Nil

":"
     is the delimiter that tells you it is finished defining
     what is wants to be fed

"Cool:D $needle"
     means it wants a type Cool (string or number) for the
     substring ($needle) it is looking for in the Haystack (Str)

"Int(Cool:D)"
     Means it will change a type Cool into a type Int (integer)
     and the ":D" means it want some actual data and not a Nil.

"$pos"
     Is short of Position.  It is the starting index in the
     haystack (Str) to start looking for the substring
     (needle).  Index starts at zero by way of string
     convention in Perl 6

     $pos is an optional parameter.  Instead of $pos?
     for optional, they stated it with several "multi method"
     that do not include $pos.

"-->Bool"
     means it return True or False

     Notes: $pos in NOT pointing at Bool
            --> means the return value
            it is not a pointer
0
perl6
12/10/2019 8:35:18 PM
On 2019-12-10 12:35, ToddAndMargo via perl6-users wrote:

> Excluding something from the search:
>=20
>  =C2=A0=C2=A0=C2=A0 Warning: in the following, use "none" not "not" to =
negate if=20
> "coming soon"
>  =C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=
 is found.=C2=A0 "not" will always return False.
>=20
>  =C2=A0=C2=A0=C2=A0 say so Q[<strong>2018.2.0; Coming=20
> Soon</strong>].fc.contains("strong" & none "coming soon");
>  =C2=A0=C2=A0=C2=A0 False

I just added:

Excluding something from the search:

     Warning: in the following, use "none" not "not" to negate if=20
"coming soon"
              is found.  "not" will always return False.

     say so Q[<strong>2018.2.0; Coming=20
Soon</strong>].fc.contains("strong" & none "coming soon");
     False

     say so Q[<strong>2018.2.0; Coming=20
Soon</strong>].fc.contains("strong" & none "coming later");
     True
0
perl6
12/10/2019 8:56:54 PM
--Apple-Mail=_601C0362-CB84-47E1-A5FA-1A8FC12CA139
Content-Transfer-Encoding: quoted-printable
Content-Type: text/plain;
	charset=us-ascii

On Dec 10, 2019, at 15:35, ToddAndMargo via perl6-users =
<perl6-users@perl.org> wrote:

> A method is a routine that you feed: Str.foo.

It seems that you're saying the difference between a method and other =
kinds of routines is that methods are "fed" something?

The only thing I can think of that routines are fed are parameters.  So =
it seems that you're saying methods must have parameters, and =
conversely, routines without parameters must not be methods.

But that method invocation doesn't have parameters.  By your definition, =
foo is not a method.

I know what routines and methods are, and I know what feeding is in the =
transitive sense, and what you just wrote doesn't seem to describe a =
method call (or its difference from other function calls).

You seem to be describing technical things with metaphor.  Precision is =
important.  Without it you run a significant risk of being misunderstood =
unless the reader shares your particular frame of reference.

> Think of "contains" as looking for a Needle in a Haystack.
> You feed contains data and what you are lookig for.  In
> return is tells you True or False
>=20
>   say "abc".contains( "a" );
>   True

So you want "feed" to mean both passing parameters and supplying an =
invocant?

You could just have said so.  Something like "A method is a routine =
called on an object."  I can see why you'd want to use metaphor to spice =
that up.  It's silly, if not tedious, if not completely pointless to =
restate common OO knowledge everywhere you intend to use OO.

> Case insensitive contains:
>    Note: "fc" converts you to lower case.  It also converts weird =
charters to
>          something on your keyboard

I can't use this as documentation.  "something on [my] keyboard" is too =
imprecise (what language is my keyboard?).  I'll need to consult the =
technical documentation to understand "fc" well enough to actually use =
it.  Even worse, I suspect "fc" is some kind of mnemonic, and I'd =
probably have understood it better if the expanded term was mentioned.

It seems like using and documenting "fc" adds extraneous details and =
distracts from what this article intends to discuss.  Splitting it into =
two articles with better focus in each would probably be an improvement.

> "Str"
>    is the string data (Haystack) that will be operated on by the =
method (contains)

"data" is wasted everywhere you've used it.  You should consider =
removing it.

""is the string that will be searched by the 'contains' method" is =
better without "data" and possibly without "(Haystack)".

Your personal note is probably fine since you know what you meant when =
you wrote it.  As documentation for a general audience, I'd say it's =
badly written and needs significant edits.  You should totally =
self-publish it anyway.  Probably in a public repository so that =
interested people will help you improve it.

--=20
Rocco Caputo <rcaputo@pobox.com>=

--Apple-Mail=_601C0362-CB84-47E1-A5FA-1A8FC12CA139
Content-Transfer-Encoding: quoted-printable
Content-Type: text/html;
	charset=us-ascii

<html><head><meta http-equiv=3D"Content-Type" content=3D"text/html =
charset=3Dus-ascii"></head><body style=3D"word-wrap: break-word; =
-webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" =
class=3D"">On Dec 10, 2019, at 15:35, ToddAndMargo via perl6-users =
&lt;<a href=3D"mailto:perl6-users@perl.org" =
class=3D"">perl6-users@perl.org</a>&gt; wrote:<br class=3D""><div><br =
class=3D""><blockquote type=3D"cite" class=3D""><div class=3D""><div =
class=3D"">A method is a routine that you feed: Str.foo.<br =
class=3D""></div></div></blockquote><div><br class=3D""></div><div>It =
seems that you're saying the difference between a method and other kinds =
of routines is that methods are "fed" something?</div><div><br =
class=3D""></div><div>The only thing I can think of that routines are =
fed are parameters. &nbsp;So it seems that you're saying methods must =
have parameters, and conversely, routines without parameters must not be =
methods.</div><div><br class=3D""></div><div>But that method invocation =
doesn't have parameters. &nbsp;By your definition, foo is not a =
method.</div><div><br class=3D""></div><div>I know what routines and =
methods are, and I know what feeding is in the transitive sense, and =
what you just wrote doesn't seem to describe a method call (or its =
difference from other function calls).</div><div><br =
class=3D""></div><div>You seem to be describing technical things with =
metaphor. &nbsp;Precision is important. &nbsp;Without it you run a =
significant risk of being misunderstood unless the reader shares your =
particular frame of reference.</div><div><br class=3D""></div><blockquote =
type=3D"cite" class=3D""><div class=3D""><div class=3D"">Think of =
"contains" as looking for a Needle in a Haystack.</div><div class=3D"">You=
 feed contains data and what you are lookig for. &nbsp;In<br =
class=3D"">return is tells you True or False<br class=3D""><br class=3D"">=
 &nbsp;&nbsp;say "abc".contains( "a" );<br class=3D""> =
&nbsp;&nbsp;True</div></div></blockquote><div><br class=3D""></div><div>So=
 you want "feed" to mean both passing parameters and supplying an =
invocant?</div><div><br class=3D""></div><div>You could just have said =
so. &nbsp;Something like "A method is a routine called on an object." =
&nbsp;I can see why you'd want to use metaphor to spice that up. =
&nbsp;It's silly, if not tedious, if not completely pointless to restate =
common OO knowledge everywhere you intend to use OO.</div><div><br =
class=3D""></div><blockquote type=3D"cite" class=3D""><div class=3D""><div=
 class=3D"">Case insensitive contains:<br class=3D""> =
&nbsp;&nbsp;&nbsp;Note: "fc" converts you to lower case. &nbsp;It also =
converts weird charters to<br class=3D""> =
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;something on your =
keyboard<br class=3D""></div></div></blockquote><div><br =
class=3D""></div><div>I can't use this as documentation. =
&nbsp;"something on [my] keyboard" is too imprecise (what language is my =
keyboard?). &nbsp;I'll need to consult the technical documentation to =
understand "fc" well enough to actually use it. &nbsp;Even worse, I =
suspect "fc" is some kind of mnemonic, and I'd probably have understood =
it better if the expanded term was mentioned.</div><div><br =
class=3D""></div><div>It seems like using and documenting "fc" adds =
extraneous details and distracts from what this article intends to =
discuss. &nbsp;Splitting it into two articles with better focus in each =
would probably be an improvement.</div><div><br =
class=3D""></div><blockquote type=3D"cite" class=3D""><div class=3D""><div=
 class=3D"">"Str"<br class=3D""> &nbsp;&nbsp;&nbsp;is the string data =
(Haystack) that will be operated on by the method (contains)<br =
class=3D""></div></div></blockquote><div><br class=3D""></div><div>"data" =
is wasted everywhere you've used it. &nbsp;You should consider removing =
it.</div><div><br class=3D""></div><div>""is the string that will be =
searched by the 'contains' method" is better without "data" and possibly =
without "(Haystack)".</div><div><br class=3D""></div><div>Your personal =
note is probably fine since you know what you meant when you wrote it. =
&nbsp;As documentation for a general audience, I'd say it's badly =
written and needs significant edits. &nbsp;You should totally =
self-publish it anyway. &nbsp;Probably in a public repository so that =
interested people will help you improve it.</div><div><br =
class=3D""></div></div><div class=3D""><div class=3D""><span =
class=3D"Apple-style-span" style=3D"border-collapse: separate; =
font-family: Monaco; font-variant-ligatures: normal; =
font-variant-east-asian: normal; font-variant-position: normal; =
line-height: normal; border-spacing: 0px;"><div style=3D"word-wrap: =
break-word; -webkit-nbsp-mode: space; -webkit-line-break: =
after-white-space;" class=3D""><div class=3D"">--&nbsp;</div><div =
class=3D"">Rocco Caputo &lt;<a href=3D"mailto:rcaputo@pobox.com" =
class=3D"">rcaputo@pobox.com</a>&gt;</div></div></span></div></div></body>=
</html>=

--Apple-Mail=_601C0362-CB84-47E1-A5FA-1A8FC12CA139--
0
rcaputo
12/10/2019 10:40:34 PM
--0000000000001818a50599618223
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

You've made a very interesting point on how difficult it is to write proper
documentation. I hope that Todd will reflect on that.



Le mar. 10 d=C3=A9c. 2019 =C3=A0 23:45, Rocco Caputo <rcaputo@pobox.com> a =
=C3=A9crit :

> On Dec 10, 2019, at 15:35, ToddAndMargo via perl6-users <
> perl6-users@perl.org> wrote:
>
> A method is a routine that you feed: Str.foo.
>
>
> It seems that you're saying the difference between a method and other
> kinds of routines is that methods are "fed" something?
>
> The only thing I can think of that routines are fed are parameters.  So i=
t
> seems that you're saying methods must have parameters, and conversely,
> routines without parameters must not be methods.
>
> But that method invocation doesn't have parameters.  By your definition,
> foo is not a method.
>
> I know what routines and methods are, and I know what feeding is in the
> transitive sense, and what you just wrote doesn't seem to describe a meth=
od
> call (or its difference from other function calls).
>
> You seem to be describing technical things with metaphor.  Precision is
> important.  Without it you run a significant risk of being misunderstood
> unless the reader shares your particular frame of reference.
>
> Think of "contains" as looking for a Needle in a Haystack.
> You feed contains data and what you are lookig for.  In
> return is tells you True or False
>
>   say "abc".contains( "a" );
>   True
>
>
> So you want "feed" to mean both passing parameters and supplying an
> invocant?
>
> You could just have said so.  Something like "A method is a routine calle=
d
> on an object."  I can see why you'd want to use metaphor to spice that up=
..
> It's silly, if not tedious, if not completely pointless to restate common
> OO knowledge everywhere you intend to use OO.
>
> Case insensitive contains:
>    Note: "fc" converts you to lower case.  It also converts weird charter=
s
> to
>          something on your keyboard
>
>
> I can't use this as documentation.  "something on [my] keyboard" is too
> imprecise (what language is my keyboard?).  I'll need to consult the
> technical documentation to understand "fc" well enough to actually use it=
..
> Even worse, I suspect "fc" is some kind of mnemonic, and I'd probably hav=
e
> understood it better if the expanded term was mentioned.
>
> It seems like using and documenting "fc" adds extraneous details and
> distracts from what this article intends to discuss.  Splitting it into t=
wo
> articles with better focus in each would probably be an improvement.
>
> "Str"
>    is the string data (Haystack) that will be operated on by the method
> (contains)
>
>
> "data" is wasted everywhere you've used it.  You should consider removing
> it.
>
> ""is the string that will be searched by the 'contains' method" is better
> without "data" and possibly without "(Haystack)".
>
> Your personal note is probably fine since you know what you meant when yo=
u
> wrote it.  As documentation for a general audience, I'd say it's badly
> written and needs significant edits.  You should totally self-publish it
> anyway.  Probably in a public repository so that interested people will
> help you improve it.
>
> --
> Rocco Caputo <rcaputo@pobox.com>
>

--0000000000001818a50599618223
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div dir=3D"ltr"><div>You&#39;ve made a very interesting point on how diffi=
cult it is to write proper documentation. I hope that Todd will reflect on =
that.</div><div><br></div><div><br></div></div><br><div class=3D"gmail_quot=
e"><div dir=3D"ltr" class=3D"gmail_attr">Le=C2=A0mar. 10 d=C3=A9c. 2019 =C3=
=A0=C2=A023:45, Rocco Caputo &lt;<a href=3D"mailto:rcaputo@pobox.com">rcapu=
to@pobox.com</a>&gt; a =C3=A9crit=C2=A0:<br></div><blockquote class=3D"gmai=
l_quote" style=3D"margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,20=
4,204);padding-left:1ex"><div style=3D"overflow-wrap: break-word;">On Dec 1=
0, 2019, at 15:35, ToddAndMargo via perl6-users &lt;<a href=3D"mailto:perl6=
-users@perl.org" target=3D"_blank">perl6-users@perl.org</a>&gt; wrote:<br><=
div><br><blockquote type=3D"cite"><div><div>A method is a routine that you =
feed: Str.foo.<br></div></div></blockquote><div><br></div><div>It seems tha=
t you&#39;re saying the difference between a method and other kinds of rout=
ines is that methods are &quot;fed&quot; something?</div><div><br></div><di=
v>The only thing I can think of that routines are fed are parameters.=C2=A0=
 So it seems that you&#39;re saying methods must have parameters, and conve=
rsely, routines without parameters must not be methods.</div><div><br></div=
><div>But that method invocation doesn&#39;t have parameters.=C2=A0 By your=
 definition, foo is not a method.</div><div><br></div><div>I know what rout=
ines and methods are, and I know what feeding is in the transitive sense, a=
nd what you just wrote doesn&#39;t seem to describe a method call (or its d=
ifference from other function calls).</div><div><br></div><div>You seem to =
be describing technical things with metaphor.=C2=A0 Precision is important.=
=C2=A0 Without it you run a significant risk of being misunderstood unless =
the reader shares your particular frame of reference.</div><div><br></div><=
blockquote type=3D"cite"><div><div>Think of &quot;contains&quot; as looking=
 for a Needle in a Haystack.</div><div>You feed contains data and what you =
are lookig for.=C2=A0 In<br>return is tells you True or False<br><br> =C2=
=A0=C2=A0say &quot;abc&quot;.contains( &quot;a&quot; );<br> =C2=A0=C2=A0Tru=
e</div></div></blockquote><div><br></div><div>So you want &quot;feed&quot; =
to mean both passing parameters and supplying an invocant?</div><div><br></=
div><div>You could just have said so.=C2=A0 Something like &quot;A method i=
s a routine called on an object.&quot; =C2=A0I can see why you&#39;d want t=
o use metaphor to spice that up.=C2=A0 It&#39;s silly, if not tedious, if n=
ot completely pointless to restate common OO knowledge everywhere you inten=
d to use OO.</div><div><br></div><blockquote type=3D"cite"><div><div>Case i=
nsensitive contains:<br> =C2=A0=C2=A0=C2=A0Note: &quot;fc&quot; converts yo=
u to lower case.=C2=A0 It also converts weird charters to<br> =C2=A0=C2=A0=
=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0=C2=A0something on your keyboard<br></d=
iv></div></blockquote><div><br></div><div>I can&#39;t use this as documenta=
tion. =C2=A0&quot;something on [my] keyboard&quot; is too imprecise (what l=
anguage is my keyboard?).=C2=A0 I&#39;ll need to consult the technical docu=
mentation to understand &quot;fc&quot; well enough to actually use it.=C2=
=A0 Even worse, I suspect &quot;fc&quot; is some kind of mnemonic, and I&#3=
9;d probably have understood it better if the expanded term was mentioned.<=
/div><div><br></div><div>It seems like using and documenting &quot;fc&quot;=
 adds extraneous details and distracts from what this article intends to di=
scuss.=C2=A0 Splitting it into two articles with better focus in each would=
 probably be an improvement.</div><div><br></div><blockquote type=3D"cite">=
<div><div>&quot;Str&quot;<br> =C2=A0=C2=A0=C2=A0is the string data (Haystac=
k) that will be operated on by the method (contains)<br></div></div></block=
quote><div><br></div><div>&quot;data&quot; is wasted everywhere you&#39;ve =
used it.=C2=A0 You should consider removing it.</div><div><br></div><div>&q=
uot;&quot;is the string that will be searched by the &#39;contains&#39; met=
hod&quot; is better without &quot;data&quot; and possibly without &quot;(Ha=
ystack)&quot;.</div><div><br></div><div>Your personal note is probably fine=
 since you know what you meant when you wrote it.=C2=A0 As documentation fo=
r a general audience, I&#39;d say it&#39;s badly written and needs signific=
ant edits.=C2=A0 You should totally self-publish it anyway.=C2=A0 Probably =
in a public repository so that interested people will help you improve it.<=
/div><div><br></div></div><div><div><span style=3D"border-collapse:separate=
;font-family:Monaco;font-variant-ligatures:normal;font-variant-east-asian:n=
ormal;line-height:normal;border-spacing:0px"><div style=3D"overflow-wrap: b=
reak-word;"><div>--=C2=A0</div><div>Rocco Caputo &lt;<a href=3D"mailto:rcap=
uto@pobox.com" target=3D"_blank">rcaputo@pobox.com</a>&gt;</div></div></spa=
n></div></div></div></blockquote></div>

--0000000000001818a50599618223--
0
perl6
12/10/2019 11:02:26 PM
I feel that ToddAndMargo are only capable of "magical programming".  I =
call that "magical", because people who program this way, only work with =
remembering from what they put into something, and what came out, =
*without* attempting to build a mental image of *how* the damn thing =
works.

The result is a continuously growing list of incantations that vaguely =
cover what they need from a programming language.

This is fine as long as the programs or the documentation they write, =
does not have to be used by anybody else who is not using the "magical =
programming" approach.

I would argue that *if* you want to become fluent in a programming =
language, you try to build a mental image on *how* that language works.  =
Because, even though it will need refining, it saves you *so much* on =
what you need to remember!


An example: remembering that you need to put in a piece of metal into a =
door and turn it to get in, versus the concept of a "key" that you need =
to gain access.

> On 11 Dec 2019, at 00:02, Laurent Rosenfeld via perl6-users =
<perl6-users@perl.org> wrote:
>=20
> You've made a very interesting point on how difficult it is to write =
proper documentation. I hope that Todd will reflect on that.
>=20
>=20
>=20
> Le mar. 10 d=C3=A9c. 2019 =C3=A0 23:45, Rocco Caputo =
<rcaputo@pobox.com> a =C3=A9crit :
> On Dec 10, 2019, at 15:35, ToddAndMargo via perl6-users =
<perl6-users@perl.org> wrote:
>=20
>> A method is a routine that you feed: Str.foo.
>=20
> It seems that you're saying the difference between a method and other =
kinds of routines is that methods are "fed" something?
>=20
> The only thing I can think of that routines are fed are parameters.  =
So it seems that you're saying methods must have parameters, and =
conversely, routines without parameters must not be methods.
>=20
> But that method invocation doesn't have parameters.  By your =
definition, foo is not a method.
>=20
> I know what routines and methods are, and I know what feeding is in =
the transitive sense, and what you just wrote doesn't seem to describe a =
method call (or its difference from other function calls).
>=20
> You seem to be describing technical things with metaphor.  Precision =
is important.  Without it you run a significant risk of being =
misunderstood unless the reader shares your particular frame of =
reference.
>=20
>> Think of "contains" as looking for a Needle in a Haystack.
>> You feed contains data and what you are lookig for.  In
>> return is tells you True or False
>>=20
>>   say "abc".contains( "a" );
>>   True
>=20
> So you want "feed" to mean both passing parameters and supplying an =
invocant?
>=20
> You could just have said so.  Something like "A method is a routine =
called on an object."  I can see why you'd want to use metaphor to spice =
that up.  It's silly, if not tedious, if not completely pointless to =
restate common OO knowledge everywhere you intend to use OO.
>=20
>> Case insensitive contains:
>>    Note: "fc" converts you to lower case.  It also converts weird =
charters to
>>          something on your keyboard
>=20
> I can't use this as documentation.  "something on [my] keyboard" is =
too imprecise (what language is my keyboard?).  I'll need to consult the =
technical documentation to understand "fc" well enough to actually use =
it.  Even worse, I suspect "fc" is some kind of mnemonic, and I'd =
probably have understood it better if the expanded term was mentioned.
>=20
> It seems like using and documenting "fc" adds extraneous details and =
distracts from what this article intends to discuss.  Splitting it into =
two articles with better focus in each would probably be an improvement.
>=20
>> "Str"
>>    is the string data (Haystack) that will be operated on by the =
method (contains)
>=20
> "data" is wasted everywhere you've used it.  You should consider =
removing it.
>=20
> ""is the string that will be searched by the 'contains' method" is =
better without "data" and possibly without "(Haystack)".
>=20
> Your personal note is probably fine since you know what you meant when =
you wrote it.  As documentation for a general audience, I'd say it's =
badly written and needs significant edits.  You should totally =
self-publish it anyway.  Probably in a public repository so that =
interested people will help you improve it.
>=20
> --=20
> Rocco Caputo <rcaputo@pobox.com>
0
liz
12/10/2019 11:19:25 PM
On 2019-12-10 14:40, Rocco Caputo wrote:
> It seems that you're saying the difference between a method and other=20
> kinds of routines is that methods are "fed" something?

Hi Rocco,

Indeed!

It is my sloppy way of saying what a method is.  I am not using
programming terminology.  My purpose was to stay away from
official jargon and use common terms.

The data, in the case the string to be searched is fed into
the method to be evaluated.

Now the "official" description would be something like

https://docs.raku.org/language/101-basics#array,_method_and_invocant

      The right-hand side calls a method =E2=80=94 a named group
      of behavior =E2=80=94 named get on the filehandle stored in
      $file. The get method reads and returns one line
      from the file, removing the line ending. If you
      print the contents of $file after calling get,
      you will see that the first line is no longer in
      there. words is also a method, called on the
      string returned from get. words decomposes its
      invocant =E2=80=94 the string on which it operates =E2=80=94 into
      a list of words, which here means strings separated
      by whitespace

That would require a keeper file all on its own.  "fed"
got to the point a lot quicker.

Thank you for the tips!
-T
0
perl6
12/11/2019 12:14:32 AM
On 2019-12-10 15:02, Laurent Rosenfeld via perl6-users wrote:
> You've made a very interesting point on how difficult it is to write 
> proper documentation. I hope that Todd will reflect on that.


Hi Laurent,

Oh good lord.  I do no have to do any reflecting
on it at all.  I spend hours and hours and hours
writing directions and procedures for customers
on a weekly basis.  I pull my hair out at times
trying to get things understandable at the skill
level of the user.

So, I have an extreme understanding of what it takes.
It is an art form all on its own and *it ain't easy!*

Do not take my griping about the way the docs are
presented as not appreciating the work that was
involved in getting there.  Oh good lord that was
a lot of work!

One thing I do a lot is screen shots and pictures.
I love the arrow add on in GIMP.  My stuff is
peppered with read arrows.  That seems to work
really well with customers.

When I write for myself, I almost never use a screen shot.
I just to the
     --> click this
       --> click that
Long winded explanations drives me nuts.  But one
has to remember their target audience and write
specifically for them.  That also is also an art form!

The one thing I find about writing documentation is
that it forces me to organize my thoughts and
quite often, I teach myself thing I did not
realize I did not know.

-T
0
perl6
12/11/2019 12:25:38 AM
On 2019-12-10 15:19, Elizabeth Mattijsen wrote:
> I feel that ToddAndMargo are only capable of "magical programming".

Hi Elizabeth,

By any chance were you involved in the writing
of the documentation?  That would explain your
hurt feelings.

I seriously did to intent to hurt anyone's feelings.
I am just trying to get the docs improved so they
are more usable by their intended audience.  This
is part of Kaisen (1).

The original writer did indeed put a lot of
effort into writing them.  I can see where I
may have hurt some feeling, but it truly
was not my intention.  I did not mean to diminish
their labors.

Can we be friends again?

-T

1) Kaisen: constant improvement.  Raku is a STUNNING
example of kaisen.
     https://www.dictionary.com/browse/kaizen
     https://en.wikipedia.org/wiki/Kaizen
0
perl6
12/11/2019 12:34:50 AM
Reply: