Re: boo-boo in run docs?

On 11/8/25 11:04 AM, Peter Pentchev wrote:
> On Sat, Nov 08, 2025 at 08:49:16PM +0200, Peter Pentchev wrote:
>> On Sat, Nov 08, 2025 at 04:15:22AM -0800, ToddAndMargo via perl6-users wrote:
>>> On 11/8/25 2:09 AM, Peter Pentchev wrote:
>>>> 4. All the parameters to `run` are documented in `run`.
>>>
>>> The Docs for Proc:
>>
>> I assume you are quoting https://docs.raku.org/type/Proc
>>
>>> method new(Proc:U:
>>>          :$in = '-',
>>>          :$out = '-',
>>>          :$err = '-',
>>>          Bool :$bin = False,
>>>          Bool :$chomp = True,
>>>          Bool :$merge = False,
>>>          Str:D :$enc = 'UTF-8',
>>>          Str:D :$nl = "\n",
>>>      --> Proc:D)
>>
>> The structure of the page that leads to the part you quoted is:
>>
>> # class Proc
>>
>> ## Methods
>>
>> ### routine new
>>
>> <what you quoted>
>>
>> This is not "the Docs for Proc". Immediately above that part,
>> it says "routine new", and this is all in a section called "Methods".
>>
>> What does that mean?
>>
>> It means that this is the documentation for `Proc.new`, the constructor.
>> The constructor is only one of the methods.
>>
>> The rest of the page documents the rest of the methods, or at least
>> those that are supposed to be accessed by other code, like e.g. exitcode.
> 
> Let me try to describe this in a different way, with a different example.
> 
> Take the Version class. Very broadly speaking, a class is a kind of type.
> The variables of that type are called objects of that class.
> The class defines the so-called "methods" that are like functions that
> you can call that know that they are supposed to handle this specific
> variable (the object). [of course, this is subtly wrong in many details,
> but it is kinda right in general]
> 
> So let's take the Version class, the one described at
> 
>    https://docs.raku.org/type/Version
> 
> In the Methods section, it lists several methods that you can call on
> either the type or its objects. The first method is called "new", and
> that is just one of the methods of the Version class.
> 
> The "new" method is described as having a single parameter, a string.
> This means that in your code, you can do stuff like:
> 
>      my $ver = Version("7.42.616");
> 
> Now you have the $ver variable which is of the Version type; it is
> an object of the Version class. This means that you can call any other
> methods listed in the documentation, like e.g. the parts method that
> will return the dot-separated parts of the version string:
> 
>      say $ver.parts.elems;
>      (output: 3)
>      say $ver.parts[0]
>      (output: 7)
> 
> The parts method is something that you can call once you have an object of
> the Version class. The parts of the version are not something that
> you pass to the constructor; it is something that the object knows how to
> "make" from what you "gave" it in the constructor.
> 
> Similarly, Proc is a class, a type. When you call the "new" method -
> which is, shall we say once again, only one of the methods you can call -
> then you tell it what command you want to run. When you call the "new"
> method, you don't tell it what the exit code of the program is, because
> *you don't know it at that point* :)
> 
> When you call Version.new, you only pass the version string itself,
> you do not pass the "parts" list.
> 
> When `run` calls Proc.new, it only passes the command itself and a couple of
> other things, it does not pass the exit code.
> 
> Once you have a Version object, you can call its .parts method to get
> the list of parts.
> 
> Once you have a Proc object, you can call its .exitcode method to get
> the process's exit code.
> 
> You do not pass .parts to Version.new.
> 
> You do not pass .exitcode to Proc.new.
> 
> Does that help?
> 
> G'luck,
> Peter
> 


Hi Peter,

It does help.  Thank you.

My Keeper starts out with:
      Run allows Raku to call and external program outside
      the “shell”. Results are given back in OOP format
      using the Proc class.

This is one of the examples explaining things:

Example showing values returned in Proc:

my Proc $p = run "ls", "-al", "RunTest.raku", :out, :err;

(my \Proc_4827370660800 = Proc.new(
     in => IO::Pipe,
out => IO::Pipe.new(proc => Proc_4827370660800,
path => IO::Path,
chomp => Bool::True,
nl-in => "\n",
nl-out => "\n",
encoding => "utf8"),
err => IO::Pipe.new(proc => Proc_4827370660800,
path => IO::Path,
chomp => Bool::True,
nl-in => "\n",
nl-out => "\n",
encoding => "utf8"),
os-error => Str,
exitcode => Nil,
signal => Any,
pid => 42139,
command => ("ls", "-al", "RunTest.raku")))

[1] > say $p.exitcode
0

[1] > say $p.out
IO::Pipe<(Path)>(opened)

[1] > say $p.out.slurp(:close)
-rwxrwxrwx. 1 todd root 932 Nov  2 22:43 RunTest.raku

[1] > say $p.err
IO::Pipe<(Path)>(opened)

[1] > say $p.err.slurp(:close)


In my Keeper, I explain what EVERY item inside Proc.
And right out he door, not squirreled away by what
is created by a method and what is not.

For example:

:$err
    $p.err is a file handle, usually to STDERR. Use $P.err.Slurp(:close)
    to read it.

    These are "colon-pairs" (like a hash).  Use these arguments to
    redirect to different file handles.

    Syntax to change these values is
        :out($alt-handle)  # handle opened elsewhere

        :out("eraseme.txt".IO.open(:w))  # handle opened in line

    Default = “-” which is capture the STDERR

If you are feeling particularly masochistic, I will
eMail it to you.

-T