On 11/8/25 11:59 AM, Richard Hainsworth wrote:
Hi Todd,
Long time since I responded to one of your questions. This thread seems
to have a lot in common, both in tone and approach, with other
assertions you have made.
I'm responding to the original post although I have read all the
responses by others.
First, lets look at the document in the url you posted. It clearly states:
run
Combined from primary sources listed below'
Although you have been accessing the docs website for many years now, it
seems that the structure of the website is not as transparent to you as
it should be. There are about 700 'primary' source pages, and some 1500
'secondary' ones. The secondary pages are automatically generated every
time the website is built from the primary ones (about once every 2
hours - I think).
The reason for this is that quite a few methods are defined for many
classes (try searching for 'new'). They are each documented in the
primary sources for those classes, but naturally we want to see a single
page with all the references in one place. Hence the need for secondary
pages.
The documentation on 'run' is literally combined from other primary
sources. You can click on the link to 'independent routines', and in
that document is a link to the primary document on class 'Proc' (not
Pro, which you sometimes write).
Raku is quite different from some other languages in the way it handles
Objects. For example, 'run' as an independent routine, returns an object
of type 'Proc'. In the same way the fragment 'hello world' creates an
object of type Str. Hence 'my $v = "hello world" puts an object of type
Str into the variable $y.
Once the object is created, all the methods associated with that object
can now be used, so `say $v.tc` will output "Hello world". The method
`tc` is defined on Str objects, and $v contains a Str object.
In the same way, `my $proc = run <cat "my-file">` will run the program
cat with input 'my-file', and the object will be stored in $proc.
Now that $proc has a Proc object, the method 'exitcode' can be run on $proc.
So, 'exitcode' has nothing to do with the method 'run', and so should
not be included in the documentation for 'run'.
All the other methods that you noted (in subsequent posts) are
associated with class Proc and can therefore be run on an object of type
Proc.
They are not a part of or associated with 'run'.
This way of thinking about objects is fundamental to Raku and what gives
it a great deal of power. However, Raku is in a sense very modest, you
dont need to know about its power to use it for simple things.
I hope this helps you understand why there isn't a 'boo boo' in the
documentation, and why what others have said is actually answering the
question you asked.
Regards,
Richard (finanalyst)
Hi Richard,
I under stand why it is done that way. I just
do not like how it is done.
"run" return its results in the OOP class "Proc".
I wish the documentation would define what is
put into your Proc variable when "run" exits.
Not divide it up all over the place.
As you said, Raku does wonderful things for you,
so you do not have to know how everything works.
just trust that it does.
$proc.exit code is an example. It contains the
exit code from the program you ran. So
there is no need to rat pack it down somewhere
at the bottom of everything because under
the hood, Raku did it for you.
The doc's should just state what it does up front.
Down the road they can break things down
as to how.
This might seems a bit weird to you becasue
you are one of those experts stand out in your
field, but the docs need to be usable for
both your skill level and beginners like me too.
And, I should not have to find the source code
more readable and explanatory than the documents.
And that should tell you something!
Thank you for the well written letter.
I appreciate it.
-T
