Documentation change for IPC::Open*.pm

2005-08-22 Thread Ben Tilly
I've always been confused by this because I don't know if I'm supposed
to think about reading and writing from the point of view of the
parent process, or the child.  So I either have to do an experiment or
look up some old code where I used the API to figure it out.

The attached patches clarify this by choosing filehandle names which
are less prone to ambiguity.

Cheers,
Ben


Open2.diff
Description: Binary data


Open3.diff
Description: Binary data


Re: Documentation change for IPC::Open*.pm

2005-08-22 Thread Rafael Garcia-Suarez
Ben Tilly wrote:
 
 The attached patches clarify this by choosing filehandle names which
 are less prone to ambiguity.

They're empty.


Re: Documentation change for IPC::Open*.pm

2005-08-22 Thread Rafael Garcia-Suarez
Ben Tilly wrote:
 On 8/22/05, Rafael Garcia-Suarez [EMAIL PROTECTED] wrote:
  Ben Tilly wrote:
  
   The attached patches clarify this by choosing filehandle names which
   are less prone to ambiguity.
  
  They're empty.
  
 Huh, try again.

Confusing.

From Open2.diff :

-$pid = open2(\*RDRFH, \*WTRFH, 'some cmd and args');
+$pid = open2(\*CHLD_IN, \*CHLD_OUT, 'some cmd and args');

I read CHLD_IN as child's input, so surely that should be the other way
around ?

Moreover, Open3.diff has :

-$pid = open3(\*WTRFH, \*RDRFH, \*ERRFH,
+$pid = open3(\*CHLD_IN, \*CHLD_OUT, \*CHLD_ERR,
'some cmd and args', 'optarg', ...);

I hereby suppose that Open2.diff is backwards.


Re: Documentation change for IPC::Open*.pm

2005-08-22 Thread Ben Tilly
On 8/22/05, Rafael Garcia-Suarez [EMAIL PROTECTED] wrote:
 Ben Tilly wrote:
  On 8/22/05, Rafael Garcia-Suarez [EMAIL PROTECTED] wrote:
[...]
  Huh, try again.
 
 Confusing.
 
 From Open2.diff :
 
 -$pid = open2(\*RDRFH, \*WTRFH, 'some cmd and args');
 +$pid = open2(\*CHLD_IN, \*CHLD_OUT, 'some cmd and args');
 
 I read CHLD_IN as child's input, so surely that should be the other way
 around ?
 
 Moreover, Open3.diff has :
 
 -$pid = open3(\*WTRFH, \*RDRFH, \*ERRFH,
 +$pid = open3(\*CHLD_IN, \*CHLD_OUT, \*CHLD_ERR,
 'some cmd and args', 'optarg', ...);
 
 I hereby suppose that Open2.diff is backwards.
 
Gah.  I didn't mean to demonstrate how the variable names in the API
cause me confusion, but I guess I just did. :-(

Yes, Open2.diff is backwards.

Ben


Re: Documentation change for IPC::Open*.pm

2005-08-22 Thread Ben Tilly
On 8/22/05, Rafael Garcia-Suarez [EMAIL PROTECTED] wrote:
 Ben Tilly wrote:
 
  The attached patches clarify this by choosing filehandle names which
  are less prone to ambiguity.
 
 They're empty.
 
Huh, try again.

Ben
--- Open2.pm.orig	2005-08-13 10:56:53.022922352 -0700
+++ Open2.pm	2005-08-13 14:33:31.386870672 -0700
@@ -18,31 +18,31 @@
 
 use IPC::Open2;
 
-$pid = open2(\*RDRFH, \*WTRFH, 'some cmd and args');
+$pid = open2(\*CHLD_IN, \*CHLD_OUT, 'some cmd and args');
   # or without using the shell
-$pid = open2(\*RDRFH, \*WTRFH, 'some', 'cmd', 'and', 'args');
+$pid = open2(\*CHLD_IN, \*CHLD_OUT, 'some', 'cmd', 'and', 'args');
 
 # or with handle autovivification
-my($rdrfh, $wtrfh);
-$pid = open2($rdrfh, $wtrfh, 'some cmd and args');
+my($chld_in, $chld_out);
+$pid = open2($chld_in, $chld_out, 'some cmd and args');
   # or without using the shell
-$pid = open2($rdrfh, $wtrfh, 'some', 'cmd', 'and', 'args');
+$pid = open2($chld_in, $chld_out, 'some', 'cmd', 'and', 'args');
 
 =head1 DESCRIPTION
 
-The open2() function runs the given $cmd and connects $rdrfh for
-reading and $wtrfh for writing.  It's what you think should work 
+The open2() function runs the given $cmd and connects $chld_in for
+reading and $chld_out for writing.  It's what you think should work 
 when you try
 
 $pid = open(HANDLE, |cmd args|);
 
 The write filehandle will have autoflush turned on.
 
-If $rdrfh is a string (that is, a bareword filehandle rather than a glob
+If $chld_in is a string (that is, a bareword filehandle rather than a glob
 or a reference) and it begins with C  , then the child will send output
-directly to that file handle.  If $wtrfh is a string that begins with
-C  , then $wtrfh will be closed in the parent, and the child will read
-from it directly.  In both cases, there will be a dup(2) instead of a
+directly to that file handle.  If $chld_out is a string that begins with
+C  , then $chld_out will be closed in the parent, and the child will
+read from it directly.  In both cases, there will be a dup(2) instead of a
 pipe(2) made.
 
 If either reader or writer is the null string, this will be replaced
--- Open3.pm.orig	2005-08-13 10:56:56.625374696 -0700
+++ Open3.pm	2005-08-13 14:31:10.583276072 -0700
@@ -19,7 +19,7 @@
 
 =head1 SYNOPSIS
 
-$pid = open3(\*WTRFH, \*RDRFH, \*ERRFH,
+$pid = open3(\*CHLD_IN, \*CHLD_OUT, \*CHLD_ERR,
 		'some cmd and args', 'optarg', ...);
 
 my($wtr, $rdr, $err);
@@ -29,15 +29,17 @@
 =head1 DESCRIPTION
 
 Extremely similar to open2(), open3() spawns the given $cmd and
-connects RDRFH for reading, WTRFH for writing, and ERRFH for errors.  If
-ERRFH is false, or the same file descriptor as RDRFH, then STDOUT and 
-STDERR of the child are on the same filehandle.  The WTRFH will have
-autoflush turned on.
-
-If WTRFH begins with C  , then WTRFH will be closed in the parent, and
-the child will read from it directly.  If RDRFH or ERRFH begins with
-C  , then the child will send output directly to that filehandle.
-In both cases, there will be a dup(2) instead of a pipe(2) made.
+connects CHLD_OUT for reading from the child, CHLD_IN for writing to
+the child, and CHLD_ERR for errors.  If CHLD_ERR is false, or the
+same file descriptor as CHLD_OUT, then STDOUT and STDERR of the child
+are on the same filehandle.  The CHLD_IN will have autoflush turned
+on.
+
+If CHLD_IN begins with C  , then CHLD_IN will be closed in the
+parent, and the child will read from it directly.  If CHLD_OUT or
+CHLD_ERR begins with C  , then the child will send output
+directly to that filehandle.  In both cases, there will be a dup(2)
+instead of a pipe(2) made.
 
 If either reader or writer is the null string, this will be replaced
 by an autogenerated filehandle.  If so, you must pass a valid lvalue


Re: Documentation change for IPC::Open*.pm

2005-08-22 Thread Rafael Garcia-Suarez
Ben Tilly wrote:
 On 8/22/05, Rafael Garcia-Suarez [EMAIL PROTECTED] wrote:
  Ben Tilly wrote:
   On 8/22/05, Rafael Garcia-Suarez [EMAIL PROTECTED] wrote:
 [...]
   Huh, try again.
  
  Confusing.
  
  From Open2.diff :
  
  -$pid = open2(\*RDRFH, \*WTRFH, 'some cmd and args');
  +$pid = open2(\*CHLD_IN, \*CHLD_OUT, 'some cmd and args');
  
  I read CHLD_IN as child's input, so surely that should be the other way
  around ?
  
  Moreover, Open3.diff has :
  
  -$pid = open3(\*WTRFH, \*RDRFH, \*ERRFH,
  +$pid = open3(\*CHLD_IN, \*CHLD_OUT, \*CHLD_ERR,
  'some cmd and args', 'optarg', ...);
  
  I hereby suppose that Open2.diff is backwards.
  
 Gah.  I didn't mean to demonstrate how the variable names in the API
 cause me confusion, but I guess I just did. :-(
 
 Yes, Open2.diff is backwards.

OK :) thus, applied backwards as change #25320 :)