Misc #16408: Ruby docs list incorrect method signatures for PTY::getpty/PTY::spawn

• Status: Open
• Assignee: -

[yarmiganosca (Chris Hoffman)]

Ruby documentation says the method signature for PTY::getpty/PTY::spawn is

 *   PTY.spawn(command_line)  { |r, w, pid| ... }
 *   PTY.spawn(command_line)  => [r, w, pid]
 *   PTY.spawn(command, arguments, ...)  { |r, w, pid| ... }
 *   PTY.spawn(command, arguments, ...)  => [r, w, pid]

However, running the following command with any Ruby since at least 2.1.9 (and based on git history, I believe since 2.0.0) will demonstrate that these method signatures are incorrect:

ruby -rpty -e 'r, w, pid = PTY.spawn({"GREETING" => "hello"}, "echo $GREETING world"); puts r.gets(11); r.close; w.close'

(it will output hello world)

Further testing confirms that, aside from the block, PTY::spawn has the same method signature as Kernel#exec, Kernel#system, Kernel#spawn, and Process::spawn. This makes sense given that their C implementations all call the C method rb_execarg_new to handle the complex argument possibilities they all have to deal with.

I have a branch with tests that verify this: https://github.com/yarmiganosca/ruby/tree/fix-PTY-getpty-and-spawn-docs-and-tests

Travis isn't running CI on this branch, but I'm assuming that's account related and not an issue with my code, especially since the UI just informs me that I'm not allowed to.

I'm happy to also change the docs for PTY::spawn in this branch, but I wasn't sure which docs to emulate. The docs for this "family" of methods are inconsistent in how they explain the complicated options available to users:

• Kernel#spawn explains in full the argument possibilities.
• Kernel#exec and Kernel#system both link to the docs for Kernel#spawn.
• Process::spawn explains in full (I think it might be a copy-paste job from the Kernel#spawn docs).
• The docs for IO::popen (another method that uses the "execargs signature" with some modifications) list, but don't explain all the argument possibilities. They also don't do all that great a job at explaining where the other arguments from IO::popen's signature fit alongside the "execargs signature".

So it seems that there isn't consensus on the best way to explain this complex method signature (and modifications of it) to readers of the docs. Like I said, I'm happy to fix the PTY::spawn docs in this branch, but I was hoping for some guidance on which of the above documentation approaches to emulate.

[nobu (Nobuyoshi Nakada)]

Thank you for the report and tests.
As for the option tests, PTY.spawn can fail after PTY.open, so could you separate ensure or use the block form of PTY.open?
And as it doesn't seem necessary to be PTY, doesn't IO.pipe suffice?

[yarmiganosca (Chris Hoffman)]

Turns out IO.pipe would result in "bar\n" instead of "bar\r\n" (PTY.open results in strings that end in "\r\n"). Given the rest of the file's test cases all expect strings that end in "\r\n", I thought that sticking to convention would be less confusing for future readers.