Make SpawnOptions a bit safer

- Add a sum type for the `stdio` option
- Use Maybe instead of `undefined`.

Author: hdgarrood

bower.json

@@ -8,7 +8,9 @@
     "purescript-node-streams": "~0.2.0",
     "purescript-foreign": "~0.7.2",
     "purescript-maps": "~0.5.3",
-    "purescript-nullable": "~0.2.1"
+    "purescript-nullable": "~0.2.1",
+    "purescript-unsafe-coerce": "~0.1.0",
+    "purescript-node-fs": "~0.9.2"
   },
   "devDependencies": {
     "purescript-console": "~0.1.1"

docs/Node/ChildProcess.md

@@ -89,7 +89,7 @@ process won't necessarily kill it.
 #### `SpawnOptions`
 
 ``` purescript
-type SpawnOptions = { cwd :: String, stdio :: Array String, env :: Nullable (StrMap String), detached :: Boolean, uid :: Int, gid :: Int }
+type SpawnOptions = { cwd :: Maybe String, stdio :: Array (Maybe StdIOBehaviour), env :: Maybe (StrMap String), detached :: Boolean, uid :: Maybe Int, gid :: Maybe Int }
 ```
 
 #### `onExit`
@@ -140,4 +140,25 @@ defaultSpawnOptions :: SpawnOptions
 type ChildProcessError = { code :: String, errno :: String, syscall :: String }
 ```
 
+An error which occurred inside a child process.
+
+#### `StdIOBehaviour`
+
+``` purescript
+data StdIOBehaviour
+```
+
+Behaviour for standard IO streams (eg, standard input, standard output) of
+a child process.
+
+* `Pipe`: creates a pipe between the child and parent process, which can
+  then be accessed as a `Stream` via the `stdin`, `stdout`, or `stderr`
+  functions.
+* `Ignore`: ignore this stream. This will cause Node to open /dev/null and
+  connect it to the stream.
+* `ShareStream`: Connect the supplied stream to the corresponding file
+   descriptor in the child.
+* `ShareFD`: Connect the supplied file descriptor (which should be open
+  in the parent) to the corresponding file descriptor in the child.
+
 

src/Node/ChildProcess.js

@@ -3,7 +3,7 @@
 // module Node.ChildProcess
 /* eslint-env node*/
 
-exports.spawn = function spawn(command) {
+exports.spawnImpl = function spawnImpl(command) {
   return function(args) {
     return function(opts) {
       return function() {
@@ -70,4 +70,5 @@ exports.onError = function onError(cp){
   };
 };
 
+exports["undefined"] = undefined;
 exports.process = process;

src/Node/ChildProcess.purs

@@ -18,6 +18,7 @@ module Node.ChildProcess
   , onError
   , spawn
   , SpawnOptions()
+  , StdIOBehaviour()
   , defaultSpawnOptions
   ) where
 
@@ -28,11 +29,13 @@ import Control.Monad.Eff (Eff())
 import Data.StrMap (StrMap())
 import Data.Function (Fn2(), runFn2)
 import Data.Nullable (Nullable(), toNullable)
-import Data.Maybe (Maybe(..))
+import Data.Maybe (Maybe(..), fromMaybe)
 import Data.Foreign (Foreign())
+import Unsafe.Coerce (unsafeCoerce)
 
+import Node.FS as FS
 import Node.Buffer (Buffer())
-import Node.Stream (Readable(), Writable())
+import Node.Stream (Readable(), Writable(), Stream())
 import Node.ChildProcess.Signal (Signal(..))
 
 -- | A handle for inter-process communication (IPC).
@@ -95,53 +98,121 @@ kill :: forall eff. Signal -> ChildProcess -> Eff (cp :: CHILD_PROCESS | eff) Bo
 kill sig (ChildProcess cp) = pure (cp.kill sig)
 
 type SpawnOptions =
-  { cwd       :: String
-  , stdio     :: Array String
-  , env       :: Nullable (StrMap String)
+  { cwd       :: Maybe String
+  , stdio     :: Array (Maybe StdIOBehaviour)
+  , env       :: Maybe (StrMap String)
   , detached  :: Boolean
-  , uid       :: Int
-  , gid       :: Int
+  , uid       :: Maybe Int
+  , gid       :: Maybe Int
   }
 
 onExit :: forall eff. ChildProcess -> (Maybe Int -> Maybe Signal -> Eff eff Unit) -> Eff eff Unit
 onExit = mkOnExit Nothing Just Signal
 
+foreign import mkOnExit :: forall a eff.
+          Maybe a -> (a -> Maybe a) -> (String -> Signal) ->
+          ChildProcess -> (Maybe Int -> Maybe Signal -> Eff eff Unit) -> Eff eff Unit
+
 onClose :: forall eff. ChildProcess -> (Maybe Int -> Maybe Signal -> Eff eff Unit) -> Eff eff Unit
 onClose = mkOnClose Nothing Just Signal
 
+foreign import mkOnClose :: forall a eff.
+          Maybe a -> (a -> Maybe a) -> (String -> Signal) ->
+          ChildProcess -> (Maybe Int -> Maybe Signal -> Eff eff Unit) -> Eff eff Unit
+
 onMessage :: forall eff.  ChildProcess -> (Foreign -> Maybe Handle -> Eff eff Unit) -> Eff eff Unit
 onMessage = mkOnMessage Nothing Just
 
+foreign import mkOnMessage :: forall a eff.
+          Maybe a -> (a -> Maybe a) ->
+          ChildProcess -> (Foreign -> Maybe Handle -> Eff eff Unit) -> Eff eff Unit
+
 foreign import onDisconnect :: forall eff. ChildProcess -> Eff eff Unit -> Eff eff Unit
 foreign import onError :: forall eff. ChildProcess -> (ChildProcessError -> Eff eff Unit) -> Eff eff Unit
 
-foreign import spawn :: forall eff. String -> Array String -> SpawnOptions -> Eff (cp :: CHILD_PROCESS | eff) ChildProcess
+spawn :: forall eff. String -> Array String -> SpawnOptions -> Eff (cp :: CHILD_PROCESS | eff) ChildProcess
+spawn cmd args opts = spawnImpl cmd args (convertOpts opts)
+  where
+  convertOpts opts =
+    { cwd: fromMaybe undefined opts.cwd
+    , stdio: toActualStdIOOptions opts.stdio
+    , env: toNullable opts.env
+    , detached: opts.detached
+    , uid: fromMaybe undefined opts.uid
+    , gid: fromMaybe undefined opts.gid
+    }
+
+foreign import spawnImpl :: forall opts eff. String -> Array String -> { | opts } -> Eff (cp :: CHILD_PROCESS | eff) ChildProcess
+
+-- There's gotta be a better way.
+foreign import undefined :: forall a. a
 
 defaultSpawnOptions :: SpawnOptions
 defaultSpawnOptions =
-  { cwd: undefined
-  , stdio: ["pipe", "pipe", "pipe"]
-  , env: toNullable Nothing
+  { cwd: Nothing
+  , stdio: pipe
+  , env: Nothing
   , detached: false
-  , uid: undefined
-  , gid: undefined
+  , uid: Nothing
+  , gid: Nothing
   }
 
-type ChildProcessError = 
+-- | An error which occurred inside a child process.
+type ChildProcessError =
   { code :: String
   , errno :: String
   , syscall :: String
   }
 
-foreign import mkOnExit :: forall a eff.
-          Maybe a -> (a -> Maybe a) -> (String -> Signal) ->
-          ChildProcess -> (Maybe Int -> Maybe Signal -> Eff eff Unit) -> Eff eff Unit
-foreign import mkOnMessage :: forall a eff. 
-          Maybe a -> (a -> Maybe a) -> 
-          ChildProcess -> (Foreign -> Maybe Handle -> Eff eff Unit) -> Eff eff Unit
-foreign import mkOnClose :: forall a eff.
-          Maybe a -> (a -> Maybe a) -> (String -> Signal) ->
-          ChildProcess -> (Maybe Int -> Maybe Signal -> Eff eff Unit) -> Eff eff Unit
-
--- There's gotta be a better way.
-foreign import undefined :: forall a. a
+-- | Behaviour for standard IO streams (eg, standard input, standard output) of
+-- | a child process.
+-- |
+-- | * `Pipe`: creates a pipe between the child and parent process, which can
+-- |   then be accessed as a `Stream` via the `stdin`, `stdout`, or `stderr`
+-- |   functions.
+-- | * `Ignore`: ignore this stream. This will cause Node to open /dev/null and
+-- |   connect it to the stream.
+-- | * `ShareStream`: Connect the supplied stream to the corresponding file
+-- |    descriptor in the child.
+-- | * `ShareFD`: Connect the supplied file descriptor (which should be open
+-- |   in the parent) to the corresponding file descriptor in the child.
+data StdIOBehaviour
+  = Pipe
+  | Ignore
+  | ShareStream (forall r eff a. Stream r eff a)
+  | ShareFD FS.FileDescriptor
+
+-- | Create pipes for each of the three standard IO streams.
+pipe :: Array (Maybe StdIOBehaviour)
+pipe = map Just [Pipe, Pipe, Pipe]
+
+-- | Share stdin with stdin, stdout with stdout, and stderr with stderr.
+inherit :: Array (Maybe StdIOBehaviour)
+inherit = map Just
+  [ ShareStream process.stdin
+  , ShareStream process.stdout
+  , ShareStream process.stderr
+  ]
+
+foreign import process :: forall props. { | props }
+
+-- | Ignore all streams.
+ignore :: Array (Maybe StdIOBehaviour)
+ignore = map Just [Ignore, Ignore, Ignore]
+
+foreign import data ActualStdIOBehaviour :: *
+
+toActualStdIOBehaviour :: StdIOBehaviour -> ActualStdIOBehaviour
+toActualStdIOBehaviour b = case b of
+  Pipe               -> c "pipe"
+  Ignore             -> c "ignore"
+  ShareFD x          -> c x
+  ShareStream stream -> c stream
+  where
+  c :: forall a. a -> ActualStdIOBehaviour
+  c = unsafeCoerce
+
+type ActualStdIOOptions = Array (Nullable ActualStdIOBehaviour)
+
+toActualStdIOOptions :: Array (Maybe StdIOBehaviour) -> ActualStdIOOptions
+toActualStdIOOptions = map (toNullable <<< map toActualStdIOBehaviour)