RawFilePath.Process

Welcome to RawFilePath.Process, a small part of the Haskell community's effort to purge String for the Greater Good.

With this module, you can create (and interact with) sub-processes without the encoding problem of String. The command and its arguments, all ByteStrings, never get converted from/to String internally on its way to the actual syscall. It also avoids the time/space waste of String.

The interface, unlike the original process package, uses types to prevent unnecessary runtime errors when obtaining Handles. This is inspired by the typed-process package which is awesome, although this module is much simpler; it doesn't introduce any new requirement of language extension or library package (for the sake of portability).

Handle (accessible with processStdin, processStdout, and processStderr) is what you can use to interact with the sub-process. For example, use hGetContents from Data.ByteString to read from a Handle as a ByteString.

Example

{-# language OverloadedStrings #-}

import RawFilePath.Process
import qualified Data.ByteString as B

main :: IO ()
main = do
    p <- startProcess $ proc "echo" ["hello"]
        `setStdout` CreatePipe
    result <- B.hGetContents (processStdout p)
    _ <- waitForProcess p

    print (result == "hello\n")

Documentation

type RawFilePath = ByteString

A literal POSIX file path

Configuring process

Configuration of how a new sub-process will be launched.

data ProcessConf stdin stdout stderr

The process configuration that is needed for creating new processes. Use proc to make one.

proc

Arguments

:: RawFilePath

Command to run

-> [ByteString]

Arguments to the command

-> ProcessConf Inherit Inherit Inherit

Create a process configuration with the default settings.

Configuring process standard streams

class StreamType c

The class of types that determine the standard stream of a sub-process. You can decide how to initialize the standard streams (stdin, stdout, and stderr) of a sub-process with the instances of this class.

Instances

StreamType UseHandle

Methods

mbFd :: FD -> UseHandle -> IO FD

willCreateHandle :: UseHandle -> Bool

StreamType NoStream

Methods

mbFd :: FD -> NoStream -> IO FD

willCreateHandle :: NoStream -> Bool

StreamType Inherit

Methods

mbFd :: FD -> Inherit -> IO FD

willCreateHandle :: Inherit -> Bool

StreamType CreatePipe

Methods

mbFd :: FD -> CreatePipe -> IO FD

willCreateHandle :: CreatePipe -> Bool

data CreatePipe

Create a new pipe for the stream. You get a new Handle.

Constructors

CreatePipe

Instances

Show CreatePipe

Methods

showsPrec :: Int -> CreatePipe -> ShowS

show :: CreatePipe -> String

showList :: [CreatePipe] -> ShowS

StreamType CreatePipe

Methods

mbFd :: FD -> CreatePipe -> IO FD

willCreateHandle :: CreatePipe -> Bool

data Inherit

Inherit the parent (current) process handle. The child will share the stream. For example, if the child writes anything to stdout, it will all go to the parent's stdout.

Constructors

Inherit

Instances

Show Inherit

Methods

showsPrec :: Int -> Inherit -> ShowS

show :: Inherit -> String

showList :: [Inherit] -> ShowS

StreamType Inherit

Methods

mbFd :: FD -> Inherit -> IO FD

willCreateHandle :: Inherit -> Bool

data NoStream

No stream handle will be passed. Use when you don't want to communicate with a stream. For example, to run something silently.

Constructors

NoStream

Instances

Show NoStream

Methods

showsPrec :: Int -> NoStream -> ShowS

show :: NoStream -> String

showList :: [NoStream] -> ShowS

StreamType NoStream

Methods

mbFd :: FD -> NoStream -> IO FD

willCreateHandle :: NoStream -> Bool

data UseHandle

Use the supplied Handle.

Constructors

UseHandle Handle

Instances

Show UseHandle

Methods

showsPrec :: Int -> UseHandle -> ShowS

show :: UseHandle -> String

showList :: [UseHandle] -> ShowS

StreamType UseHandle

Methods

mbFd :: FD -> UseHandle -> IO FD

willCreateHandle :: UseHandle -> Bool

setStdin :: StreamType newStdin => ProcessConf oldStdin stdout stderr -> newStdin -> ProcessConf newStdin stdout stderr infixl 4

Control how the standard input of the process will be initialized.

setStdout :: StreamType newStdout => ProcessConf stdin oldStdout stderr -> newStdout -> ProcessConf stdin newStdout stderr infixl 4

Control how the standard output of the process will be initialized.

setStderr :: StreamType newStderr => ProcessConf stdin stdout oldStderr -> newStderr -> ProcessConf stdin stdout newStderr infixl 4

Control how the standard error of the process will be initialized.

Running process

data Process stdin stdout stderr

The process type. The three type variables denote how its standard streams were initialized.

startProcess :: (StreamType stdin, StreamType stdout, StreamType stderr) => ProcessConf stdin stdout stderr -> IO (Process stdin stdout stderr)

Start a new sub-process with the given configuration.

Obtaining process streams

As the type signature suggests, these functions only work on processes whose stream in configured to CreatePipe. This is the type-safe way of obtaining Handles instead of returning Maybe Handles like the process package does.

processStdin :: Process CreatePipe stdout stderr -> Handle

Take a process and return its standard input handle.

processStdout :: Process stdin CreatePipe stderr -> Handle

Take a process and return its standard output handle.

processStderr :: Process stdin stdout CreatePipe -> Handle

Take a process and return its standard error handle.

Process completion

stopProcess :: Process stdin stdout stderr -> IO ExitCode

Stop a sub-process. For now it simply calls terminateProcess and then waitForProcess.

terminateProcess :: Process stdin stdout stderr -> IO ()

Terminate a sub-process by sending SIGTERM to it.

waitForProcess :: Process stdin stdout stderr -> IO ExitCode

Wait (block) for a sub-process to exit and obtain its exit code.

Utility functions

These are utility functions; they can be implemented with the primary functions above. They are provided for convenience.

callProcess :: ProcessConf stdin stdout stderr -> IO ExitCode

Create a new process with the given configuration, and wait for it to finish.

readProcessWithExitCode :: ProcessConf stdin stdout stderr -> IO (ExitCode, ByteString, ByteString)

Fork an external process, read its standard output and standard error strictly, blocking until the process terminates, and return them with the process exit code.