Re: boo-boo in run docs?

[email protected] (Peter Pentchev) Thu, 6 Nov 2025 11:57:30 +0200
Newsgroups	perl.perl6.users
Message-ID	<[email protected]>
On Wed, Nov 05, 2025 at 03:51:55PM -0800, ToddAndMargo via perl6-users wrote:
> On 11/5/25 11:09 AM, Will Coleda wrote:
> > https://docs.raku.org/type/Proc#method_exitcode <https://docs.raku.org/
> > type/Proc#method_exitcode>
> 
> Hi Will,
> 
> Perfect!
> 
> Now it need to be added to
>      https://docs.raku.org/routine/run#(Independent_routines)_sub_run
> 
> so someone reading the page that does not
> already know what he is doing can find it.

It doesn't need to be; the documentation of `run` already points to
the documentation of `Proc`, as you point out.

> Unless I am missing it, there is a who slew of things
> not declared in "Proc" either.  They do give below a simple
> list of some of them: command, mulitimethod, pid,
> exitcode, signal.   But now all of them.

> 
> If you look at
>     https://docs.raku.org/type/Proc/Async
> There is a ton of them missing.

The documentation of `Proc` declares everything that `Proc` does.
The documentation of `Proc::Async` declares everything that `Proc::Async` does.
Those are two different things.

> So Proc seriously need to declare its OOP definition
> (object). Everything.  Not just a sample of them.

It does. However, there seems to be a bit of confusion here: you seem to
expect everything to be passed to the `new` method, while it doesn't really
make sense to do that :)

In very broad (and, of course, incorrect in the details) strokes,
the object-oriented paradigm says that a class may define a couple of
different kinds of things:
- class methods that are usually used to create objects (variables) of that class;
  that includes the constructor, but see below
- class-level properties, but we will not dwell on these for now
- object-level properties: things that you may think of as fields, members,
  variables that are "stored" "in" a single object (a variable of that type);
  sometimes you can modify them directly, sometimes you can only get their values
- object methods that you can call a single object (a variable of that type) that
  may return more information or may do some things specific to what this class is
  supposed to mean

The `new` method is (usually) special; it is used by other things to create
an object of that type. When doing that, some parameters may be passed - those are
usually things that determine "how that object should behave", what it should "do".
For a process, the parameters say e.g. which command to run, which directory to
use for running it, what to do with the new process's standard output and error
streams, etc. - all things that you need to know *when you start a program*.

The `exitcode` method is something different: it has absolutely no meaning when
`run` tries to create the `Proc` object, since `run` simply *doesn't know* what
the program's exit code will be at that point :) The exit code of the program will
be revealed later - that's why it is a method that may return an integer value or
it may say "eh, the program is still running, there is no exit code information yet".

That's why `exitcode` is not defined in the constructor - it doesn't make sense to
put it there, you don't know what it is when you start the program, that's why
you're starting the program in the first place :) And that's why `exitcode` is,
indeed, documented in the `Proc` documentation as a method that you can call to
see what code the program actually exited with.

Hope that helps.

G'luck,
Peter

-- 
Peter Pentchev  [email protected] [email protected] [email protected]
PGP key:        https://www.ringlet.net/roam/roam.key.asc
Key fingerprint 2EE7 A7A5 17FC 124C F115  C354 651E EFB0 2527 DF13
signature.asc (application/pgp-signature, 833 B)