Better stdio option handling - fixes #24

[SamVerschueren]

Cherry picked from #36 (Thanks @jamestalmage for the initial work!).

Also fixed some issues regarding #79 as it didn't support stdio to being an Array.

Feel free to provide feedback on anything, not sure about the docs either.

[jamestalmage]

We should link to the relevant Node docs and provide a reminder of the available options: https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio

We should also allow positive integers, undefined, and null.

[SamVerschueren]

Made a little change to the docs, is this better? Or should we do something like

stdin

Same options as stdio. Shorter and more descriptive form for stdio: ['inherit', null, null].

[jamestalmage]

That works. Do we have tests making sure we cover the number and stream scenarios?

[SamVerschueren]

I will have a look tomorrow to cover that. Any ideas how we could test the streams?

[jamestalmage]

Hmmm.

Using streams with child_process does not work how I thought. You can actually only pass native like streams (net / dgram / tty, etc).

I am working on a module to reliably detect those types of streams. (stealing from the code here).

If they pass a userland stream, I think we can still accommodate, but it's more of a PITA.

[jamestalmage]

Just go with this for now. We can discuss providing more user friendly stream handling later

[SamVerschueren]

Added 2 more types of tests

1. Writing content to a file via a file descriptor fs.openSync('file.txt', 'w');
2. Add tests to see if parsing numbers works. This wasn't working as expected so I fixed that

I was looking into the stream thing before I read your comment. From the docs

Share a readable or writable stream that refers to a tty, file, socket, or a pipe with the child process.

So I was expecting I could do something like this

const writeStream = fs.createWriteStream('file.txt');

await execa('foo', {stdout: writeStream});

But as you figured out, that is not possible.

[jamestalmage]

Ah. Good test strategy. File streams are allowed. I opened an issue to handle userland streams better

[jamestalmage]

Wait, I missed your comment. So this is just a descriptor, not a stream. The way child_process handles streams just gets weirder and weirder

[SamVerschueren]

Yes exactly. Either the docs are wrong, or I did it wrong. But the docs link to Stream which states

Incorrect value for stdio stream: WriteStream

But but... Ugh, nevermind.

[jamestalmage]

I like it. Let's merge