Re: boo-boo in run docs?
[email protected] (Richard Hainsworth) Sat, 8 Nov 2025 19:59:39 +0000
| Newsgroups | perl.perl6.users |
|---|---|
| Message-ID | <[email protected]> |
--------------5LJYar0GE0H00tJnKLMd4lT0
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 8bit
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)
On 03/11/2025 08:03, ToddAndMargo via perl6-users wrote:
> Hi All,
>
> I do believe I came across a boo-boo in the docs for "run":
>
> https://docs.raku.org/routine/run
>
> sub run(
> *@args ($, *@),
> :$in = '-',
> :$out = '-',
> :$err = '-',
> Bool :$bin = False,
> Bool :$chomp = True,
> Bool :$merge = False,
> Str:D :$enc = 'UTF-8',
> Str:D :$nl = "\n",
> :$cwd = $*CWD,
> Hash() :$env = %*ENV,
> :$arg0,
> :$win-verbatim-args = False
> --> Proc:D)
>
>
> The above stated that it return a variable of type "Proc".
>
> Type Proc states:
>
> 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)
>
> Hmmmmmmm. They forgot:
> $proc.exitcode
>
> Maybe I am blind?
>
> -T
>
>
--------------5LJYar0GE0H00tJnKLMd4lT0
Content-Type: text/html; charset=UTF-8
Content-Transfer-Encoding: 8bit
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
</head>
<body>
<p>Hi Todd,</p>
<p>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.<br>
</p>
<p>I'm responding to the original post although I have read all the
responses by others. <br>
</p>
<p>First, lets look at the document in the url you posted. It
clearly states: <br>
</p>
<div class="raku page-title has-text-centered"> run </div>
<p> Combined from primary sources listed below'</p>
<p>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).</p>
<p>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.<br>
</p>
<p>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).</p>
<p>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.</p>
<p>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.</p>
<p>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. <br>
</p>
<p>Now that $proc has a Proc object, the method 'exitcode' can be
run on $proc.</p>
<p>So, 'exitcode' has nothing to do with the method 'run', and so
should not be included in the documentation for 'run'.</p>
<p>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. <br>
</p>
<p>They are not a part of or associated with 'run'.<br>
</p>
<p>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.</p>
<p>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.<br>
</p>
<p>Regards,</p>
<p>Richard (finanalyst)<br>
</p>
<div class="moz-cite-prefix">On 03/11/2025 08:03, ToddAndMargo via
perl6-users wrote:<br>
</div>
<blockquote type="cite"
cite="mid:[email protected]">Hi All,
<br>
<br>
I do believe I came across a boo-boo in the docs for "run":
<br>
<br>
<a class="moz-txt-link-freetext" href="https://docs.raku.org/routine/run">https://docs.raku.org/routine/run</a>
<br>
<br>
sub run(
<br>
*@args ($, *@),
<br>
:$in = '-',
<br>
:$out = '-',
<br>
:$err = '-',
<br>
Bool :$bin = False,
<br>
Bool :$chomp = True,
<br>
Bool :$merge = False,
<br>
Str:D :$enc = 'UTF-8',
<br>
Str:D :$nl = "\n",
<br>
:$cwd = $*CWD,
<br>
Hash() :$env = %*ENV,
<br>
:$arg0,
<br>
:$win-verbatim-args = False
<br>
--> Proc:D)
<br>
<br>
<br>
The above stated that it return a variable of type "Proc".
<br>
<br>
Type Proc states:
<br>
<br>
method new(Proc:U:
<br>
:$in = '-',
<br>
:$out = '-',
<br>
:$err = '-',
<br>
Bool :$bin = False,
<br>
Bool :$chomp = True,
<br>
Bool :$merge = False,
<br>
Str:D :$enc = 'UTF-8',
<br>
Str:D :$nl = "\n",
<br>
--> Proc:D)
<br>
<br>
Hmmmmmmm. They forgot:
<br>
$proc.exitcode
<br>
<br>
Maybe I am blind?
<br>
<br>
-T
<br>
<br>
<br>
</blockquote>
</body>
</html>
--------------5LJYar0GE0H00tJnKLMd4lT0--