Re: boo-boo in run docs?

On 11/11/25 5:55 AM, Peter Pentchev wrote:
> On Tue, Nov 11, 2025 at 04:44:42AM -0800, ToddAndMargo via perl6-users wrote:
>> On 11/6/25 3:58 PM, Peter Pentchev wrote:
>>>> exitcode
>>>> should have been included in the examples in run's documentation.
>>>> And exit code should have been included in the definition of
>>>> Proc, not buried at the end of the document,
>>
>>> It is in the definition. It is listed as one of the methods, because
>>> that is what it is. "The end of the document" is the section that
>>> lists all of the methods that you can call.
>>
>> .exitcode in not a method.  The value is an integer.
> 
> No, "$.exitcode" is an internal field that you do not have
> direct access to. The only reason you know about that field right now is
> that you looked at the source code of the class; programs that use
> objects of the Proc class cannot access it directly.
> 
> The "exitcode" method, on the other hand, is what Raku creates
> automatically when the source code says "has $.exitcode". It will
> read the value of the internal "$.exitcode" field and it will return
> that value to you. If you have a variable called $proc and it is
> a Proc object, then you can call that method in two main ways:
> 
>    say $proc.exitcode()  # see, it's a method with no arguments
> 
>    say $proc.exitcode  # Raku allows you to omit the parentheses
> 
> That second way is the standard Raku way to let programs access
> the fields of an object that they are allowed to: the class
> says "has $.field" and Raku automatically generates a method
> called "field" that you can call with or without the parentheses.
> The internal variable that is called $.exitcode is not really
> visible to your program; the only way for you to get that exit code
> is to invoke the method that is called "exitcode"...
> 
> ...and that is described in "Methods" section of the Proc documentation.
>   
>> So what your are saying, correct me if I misinterpret you,
>> is that
>>
>>    .exitcode,
>>    .signal
>>    .pid
>>    @.command
>>
>> Should all go at the end becasue somewhere in the run command,
>> methods are used to populate them?
> 
> Not exactly. The $.exitcode, $.signal, $.pid, and @.command
> INTERNAL variables are not documented on purpose - your program
> does not have any way to access them directly.
> 
> However, the way they are defined in the source code means that
> Raku has automatically generated the "exitcode", "signal", "pid",
> and "command" methods for you to call to get those values...
> 
> ...and those methods are all described in the "Methods" section
> of the https://docs.raku.org/type/Proc page :)
> 
> And they are described in the "Methods" section of the "Proc" page
> because that's where they belong - because they are methods of
> the "Proc" class. A function that returns an object of the type
> "Proc" does not need to document anything you can do with that
> object, just as a function that returns an object of the type "Int"
> does not need to document anything you can do with that object.
> 
> I mean, the Str class has a method called "chars" that you call to
> figure out how many characters there are in a string. Now do you
> think that the documentation of the string class should tell you
> stuff like "oh, and once you call chars, you can then do several
> things with that value, like you can call is-prime to figure out
> whether that is a prime number, or you can call sign to figure out
> whether this is a positive or a negative number, or you can
> call sqrt to get the square root of that number"? No, none of
> that belongs in the Str class, because it has nothing to do
> with strings; however, it is documented in the Int class, the Real
> class, the Numeric class and so on.
> 
> So just as the documentation of Str does not tell you that you can
> do $name.chars.sqrt, so the documentation of run() does not tell you
> that you can do run().exitcode. The documentation of Str says
> that "chars" returns an Int; the documentation of "run" says
> that it returns a Proc.
>   
> G'luck,
> Peter
> 

Hi Peter,

No objection here.

I am also marveling at your technical writing.  You stated
the information very clearly.   I have a hard time with
technical writing and you really impressed me with yours.

-T

Now I will go wash my mouth out with soap!  :-)