Implement suggestions from #2

- Just one effect for child processes, rather than separate Stdout,
  Stdin, Stderr. I named it CHILD_PROCESS because I plan to add `exec`
  and `execFile` in addition to `spawn`, and because the effect
  represents not only spawning child processes, but also interacting
  with them.
- Change the child process record into an opaque newtype (without an
  exported constructor). This prevents people from trying to update its
  fields, which would probably not be a good idea.
- Change types for some child process attributes to be a bit safer. For
  example, reading the "connected" state of a child process now requires
  Eff, as does "killing" one (ie, sending a signal).
- Use StrMap for the `env` option
- Make the `env` option nullable so that you can inherit the parent
  environment if you want to.

Author: hdgarrood

bower.json

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

src/Node/ChildProcess.purs

@@ -1,62 +1,112 @@
 module Node.ChildProcess
   ( Handle()
-  , Spawn()
-  , Stdin()
-  , Stdout()
-  , Stderr()
   , ChildProcess()
-  , SpawnOptions()
+  , CHILD_PROCESS()
+  , stderr
+  , stdout
+  , stdin
+  , pid
+  , connected
+  , kill
+  , send
+  , disconnect
   , ChildProcessError()
   , onExit
   , onClose
   , onDisconnect
   , onMessage
   , onError
   , spawn
+  , SpawnOptions()
   , defaultSpawnOptions
   ) where
 
 import Prelude
 
 import Control.Monad.Eff (Eff())
 
-import Data.Function (Fn0(), Fn1(), Fn2())
+import Data.StrMap (StrMap())
+import Data.Function (Fn2(), runFn2)
+import Data.Nullable (Nullable(), toNullable)
 import Data.Maybe (Maybe(..))
 import Data.Foreign (Foreign())
 
+import Node.Buffer (Buffer())
 import Node.Stream (Readable(), Writable())
 import Node.ChildProcess.Signal (Signal(..))
 
+-- | A handle for inter-process communication (IPC).
 foreign import data Handle :: *
-foreign import data Spawn :: !
-foreign import data Stdin :: !
-foreign import data Stdout :: !
-foreign import data Stderr :: !
-
-type ChildProcess =
-  { stderr     :: forall eff. Readable () (stderr :: Stderr | eff) String
-  , stdin      :: forall eff. Writable () (stdin :: Stdin | eff) String
-  , stdout     :: forall eff. Readable  () (stdout :: Stdout | eff) String
-  , pid        :: Number
+
+-- | The effect for creating and interacting with child processes.
+foreign import data CHILD_PROCESS :: !
+
+newtype ChildProcess = ChildProcess ChildProcessRec
+
+runChildProcess :: ChildProcess -> ChildProcessRec
+runChildProcess (ChildProcess r) = r
+
+-- | Note: some of these types are lies, and so it is unsafe to access some of
+-- | these record fields directly.
+type ChildProcessRec =
+  { stderr     :: forall eff. Readable () (cp :: CHILD_PROCESS | eff) Buffer
+  , stdin      :: forall eff. Writable () (cp :: CHILD_PROCESS | eff) Buffer
+  , stdout     :: forall eff. Readable () (cp :: CHILD_PROCESS | eff) Buffer
+  , pid        :: Int
   , connected  :: Boolean
-  , kill       :: forall eff. Fn1 Signal Boolean
-  , send       :: forall eff r. Fn2 { | r} Handle (Eff eff Unit)
-  , disconnect :: forall eff. Fn0 (Eff eff Unit)
+  , kill       :: Signal -> Boolean
+  , send       :: forall r. Fn2 { | r} Handle Boolean
+  , disconnect :: forall eff. Eff eff Unit
   }
 
+-- | The standard error stream of a child process. Note that this is only
+-- | available if the process was spawned with the stderr option set to "pipe".
+stderr :: forall eff. ChildProcess -> Readable () (cp :: CHILD_PROCESS | eff) Buffer
+stderr = _.stderr <<< runChildProcess
+
+-- | The standard output stream of a child process. Note that this is only
+-- | available if the process was spawned with the stdout option set to "pipe".
+stdout :: forall eff. ChildProcess -> Readable () (cp :: CHILD_PROCESS | eff) Buffer
+stdout = _.stdout <<< runChildProcess
+
+-- | The standard input stream of a child process. Note that this is only
+-- | available if the process was spawned with the stdin option set to "pipe".
+stdin :: forall eff. ChildProcess -> Writable () (cp :: CHILD_PROCESS | eff) Buffer
+stdin = _.stdin <<< runChildProcess
+
+-- | The process ID of a child process. Note that if the process has already
+-- | exited, another process may have taken the same ID, so be careful!
+pid :: ChildProcess -> Int
+pid = _.pid <<< runChildProcess
+
+connected :: forall eff. ChildProcess -> Eff (cp :: CHILD_PROCESS | eff) Boolean
+connected = pure <<< _.connected <<< runChildProcess
+
+send :: forall eff props. { | props } -> Handle -> ChildProcess -> Eff (cp :: CHILD_PROCESS | eff) Boolean
+send msg handle (ChildProcess cp) = pure (runFn2 cp.send msg handle)
+
+disconnect :: forall eff. ChildProcess -> Eff (cp :: CHILD_PROCESS | eff) Unit
+disconnect = _.disconnect <<< runChildProcess
+
+-- | Send a signal to a child process. It's an unfortunate historical decision
+-- | that this function is called "kill", as sending a signal to a child
+-- | process won't necessarily kill it.
+kill :: forall eff. Signal -> ChildProcess -> Eff (cp :: CHILD_PROCESS | eff) Boolean
+kill sig (ChildProcess cp) = pure (cp.kill sig)
+
 type SpawnOptions =
   { cwd       :: String
   , stdio     :: Array String
-  , env       :: forall r. { | r}
+  , env       :: Nullable (StrMap String)
   , detached  :: Boolean
-  , uid       :: Number
-  , gid       :: Number
+  , uid       :: Int
+  , gid       :: Int
   }
 
-onExit :: forall eff. ChildProcess -> (Maybe Number -> Maybe Signal -> Eff eff Unit) -> Eff eff Unit
+onExit :: forall eff. ChildProcess -> (Maybe Int -> Maybe Signal -> Eff eff Unit) -> Eff eff Unit
 onExit = mkOnExit Nothing Just Signal
 
-onClose :: forall eff. ChildProcess -> (Maybe Number -> 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
 
 onMessage :: forall eff.  ChildProcess -> (Foreign -> Maybe Handle -> Eff eff Unit) -> Eff eff Unit
@@ -65,13 +115,13 @@ onMessage = mkOnMessage Nothing Just
 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 (spawn :: Spawn | eff) ChildProcess
+foreign import spawn :: forall eff. String -> Array String -> SpawnOptions -> Eff (cp :: CHILD_PROCESS | eff) ChildProcess
 
 defaultSpawnOptions :: SpawnOptions
 defaultSpawnOptions =
   { cwd: undefined
   , stdio: ["pipe", "pipe", "pipe"]
-  , env: process.env
+  , env: toNullable Nothing
   , detached: false
   , uid: undefined
   , gid: undefined
@@ -85,14 +135,13 @@ type ChildProcessError =
 
 foreign import mkOnExit :: forall a eff.
           Maybe a -> (a -> Maybe a) -> (String -> Signal) ->
-          ChildProcess -> (Maybe Number -> Maybe Signal -> Eff eff Unit) -> Eff eff Unit
+          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 Number -> Maybe Signal -> Eff eff Unit) -> Eff eff Unit
+          ChildProcess -> (Maybe Int -> Maybe Signal -> Eff eff Unit) -> Eff eff Unit
 
 -- There's gotta be a better way.
 foreign import undefined :: forall a. a
-foreign import process :: forall r. {env :: { | r}}

src/Node/ChildProcess/Signal.purs

@@ -40,48 +40,48 @@ module Node.ChildProcess.Signal
   , sigxfsz
   ) where
 
-  import Prelude (Show)
+import Prelude (Show)
 
-  newtype Signal = Signal String
+newtype Signal = Signal String
 
-  sigabrt   = Signal "SIGABRT"
-  sigalrm   = Signal "SIGALRM"
-  sigbus    = Signal "SIGBUS"
-  sigchld   = Signal "SIGCHLD"
-  sigcld    = Signal "SIGCLD"
-  sigcont   = Signal "SIGCONT"
-  sigemt    = Signal "SIGEMT"
-  sigfpe    = Signal "SIGFPE"
-  sighup    = Signal "SIGHUP"
-  sigill    = Signal "SIGILL"
-  siginfo   = Signal "SIGINFO"
-  sigint    = Signal "SIGINT"
-  sigio     = Signal "SIGIO"
-  sigiot    = Signal "SIGIOT"
-  sigkill   = Signal "SIGKILL"
-  siglost   = Signal "SIGLOST"
-  sigpipe   = Signal "SIGPIPE"
-  sigpoll   = Signal "SIGPOLL"
-  sigprof   = Signal "SIGPROF"
-  sigpwr    = Signal "SIGPWR"
-  sigquit   = Signal "SIGQUIT"
-  sigsegv   = Signal "SIGSEGV"
-  sigstkflt = Signal "SIGSTKFLT"
-  sigstop   = Signal "SIGSTOP"
-  sigsys    = Signal "SIGSYS"
-  sigterm   = Signal "SIGTERM"
-  sigtrap   = Signal "SIGTRAP"
-  sigtstp   = Signal "SIGTSTP"
-  sigttin   = Signal "SIGTTIN"
-  sigttou   = Signal "SIGTTOU"
-  sigunused = Signal "SIGUNUSED"
-  sigurg    = Signal "SIGURG"
-  sigusr1   = Signal "SIGUSR1"
-  sigusr2   = Signal "SIGUSR2"
-  sigvtalrm = Signal "SIGVTALRM"
-  sigwinch  = Signal "SIGWINCH"
-  sigxcpu   = Signal "SIGXCPU"
-  sigxfsz   = Signal "SIGXFSZ"
+sigabrt   = Signal "SIGABRT"
+sigalrm   = Signal "SIGALRM"
+sigbus    = Signal "SIGBUS"
+sigchld   = Signal "SIGCHLD"
+sigcld    = Signal "SIGCLD"
+sigcont   = Signal "SIGCONT"
+sigemt    = Signal "SIGEMT"
+sigfpe    = Signal "SIGFPE"
+sighup    = Signal "SIGHUP"
+sigill    = Signal "SIGILL"
+siginfo   = Signal "SIGINFO"
+sigint    = Signal "SIGINT"
+sigio     = Signal "SIGIO"
+sigiot    = Signal "SIGIOT"
+sigkill   = Signal "SIGKILL"
+siglost   = Signal "SIGLOST"
+sigpipe   = Signal "SIGPIPE"
+sigpoll   = Signal "SIGPOLL"
+sigprof   = Signal "SIGPROF"
+sigpwr    = Signal "SIGPWR"
+sigquit   = Signal "SIGQUIT"
+sigsegv   = Signal "SIGSEGV"
+sigstkflt = Signal "SIGSTKFLT"
+sigstop   = Signal "SIGSTOP"
+sigsys    = Signal "SIGSYS"
+sigterm   = Signal "SIGTERM"
+sigtrap   = Signal "SIGTRAP"
+sigtstp   = Signal "SIGTSTP"
+sigttin   = Signal "SIGTTIN"
+sigttou   = Signal "SIGTTOU"
+sigunused = Signal "SIGUNUSED"
+sigurg    = Signal "SIGURG"
+sigusr1   = Signal "SIGUSR1"
+sigusr2   = Signal "SIGUSR2"
+sigvtalrm = Signal "SIGVTALRM"
+sigwinch  = Signal "SIGWINCH"
+sigxcpu   = Signal "SIGXCPU"
+sigxfsz   = Signal "SIGXFSZ"
 
-  instance showSignal :: Show Signal where
-    show (Signal sig) = sig
+instance showSignal :: Show Signal where
+  show (Signal sig) = sig

test/Main.purs

@@ -0,0 +1,20 @@
+module Test.Main where
+
+import Prelude
+import Control.Bind
+
+import Control.Monad.Eff.Console
+
+import Node.Encoding (Encoding(UTF8))
+import Node.Buffer as Buffer
+import Node.ChildProcess
+import Node.ChildProcess.Signal
+import Node.Stream (onData)
+
+main = do
+  ls <- spawn "ls" ["-la"] defaultSpawnOptions
+  onClose ls \code sig ->
+      log $ "ls exited with code: " ++ (show code) ++ "\nfrom signal: " ++ (show sig)
+  onData (stdout ls) (Buffer.toString UTF8 >=> log)
+  kill sigterm ls
+  log "Killed."