Polysemy.Process

Introduction

This library provides an abstraction of a system process in the effect Process, whose constructors represent the three standard file descriptors.

An intermediate effect, SystemProcess, is more concretely tied to the functionality of the System.Process library. See Polysemy.Process.SystemProcess for its constructors.

The utility effect ProcessOutput takes care of decoding the process output, getting called by the Process interpreters whenever a chunk was read, while accumulating chunks until they were decoded successfully. See Polysemy.Process.ProcessOutput for its constructors.

The effect Pty abstracts pseudo terminals. See Polysemy.Process.Pty for its constructors.

Effects

Process

data Process i o e :: Effect where

Abstraction of a process with stdinstdoutstderr.

This effect is intended to be used in a scoped manner:

import Polysemy.Resume
import Polysemy.Conc
import Polysemy.Process
import qualified System.Process.Typed as System

prog :: Member (Scoped resource (Process Text Text e !! err)) r => Sem r Text
prog =
 resumeAs "failed" do
   withProcess do
     send "input"
     recv

main :: IO ()
main = do
  out <- runConc $ interpretProcessNative (System.proc "cat" []) prog
  putStrLn out

Constructors

Recv :: Process i o e m o

RecvError :: Process i o e m e

Send :: i -> Process i o e m ()

Instances

type DefiningModule Process

Defined in Polysemy.Process.Effect.Process

type DefiningModule Process = "Polysemy.Process.Effect.Process"

recv :: forall i o e r. Member (Process i o e) r => Sem r o

Obtain a chunk of stdout.

recvError :: forall i o e r. Member (Process i o e) r => Sem r e

Obtain a chunk of stderr.

send :: forall i o e r. Member (Process i o e) r => i -> Sem r ()

Send data to stdin.

withProcess :: forall resource i o e r. Member (Scoped resource (Process i o e)) r => InterpreterFor (Process i o e) r

Create a scoped resource for Process.

ProcessOutput

data ProcessOutput a :: Effect

This effect is used by the effect Process to accumulate and decode chunks of ByteStrings, for example using a parser. The interpreter may be stateful or stateless, since the constructor Chunk is expected to be called with both the accumulated unprocessed output as well as the new chunk.

Instances

type DefiningModule ProcessOutput

Defined in Polysemy.Process.Effect.ProcessOutput

type DefiningModule ProcessOutput = "Polysemy.Process.Effect.ProcessOutput"

SystemProcess

data SystemProcess :: Effect

Low-level interface for a process, operating on raw chunks of bytes. Interface is modeled after System.Process.

Instances

type DefiningModule SystemProcess

Defined in Polysemy.Process.Effect.SystemProcess

type DefiningModule SystemProcess = "Polysemy.Process.Effect.SystemProcess"

withSystemProcess :: forall resource err r. Member (Scoped resource (SystemProcess !! err)) r => InterpreterFor (SystemProcess !! err) r

Create a scoped resource for SystemProcess.

Pty

data Pty :: Effect

A pseudo terminal, to be scoped with withPty.

Instances

type DefiningModule Pty

Defined in Polysemy.Process.Effect.Pty

type DefiningModule Pty = "Polysemy.Process.Effect.Pty"

withPty :: forall resource r. Member (Scoped resource Pty) r => InterpreterFor Pty r

Bracket an action with the creation and destruction of a pseudo terminal.

Interpreters

Process

interpretProcessByteStringNative

Arguments

:: Members [Resource, Race, Async, Embed IO] r

=> Bool

Whether to discard output chunks if the queue is full.

-> Int

Maximum number of chunks allowed to be queued for each of the three standard pipes.

-> ProcessConfig () () ()

Basic config. The pipes will be changed to Handle by the interpreter.

-> InterpreterFor (Scoped () (Process ByteString ByteString ByteString) !! ProcessError) r

Interpret Process as a native SystemProcess, producing unaccumulated chunks of ByteString.

interpretProcessByteStringLinesNative

Arguments

:: Members [Resource, Race, Async, Embed IO] r

=> Bool

Whether to discard output chunks if the queue is full.

-> Int

Maximum number of chunks allowed to be queued for each of the three standard pipes.

-> ProcessConfig () () ()

Basic config. The pipes will be changed to Handle by the interpreter.

-> InterpreterFor (Scoped () (Process ByteString ByteString ByteString) !! ProcessError) r

Interpret Process as a native SystemProcess, producing lines of ByteString.

interpretProcessTextNative

Arguments

:: Members [Resource, Race, Async, Embed IO] r

=> Bool

Whether to discard output chunks if the queue is full.

-> Int

Maximum number of chunks allowed to be queued for each of the three standard pipes.

-> ProcessConfig () () ()

Basic config. The pipes will be changed to Handle by the interpreter.

-> InterpreterFor (Scoped () (Process ByteString Text Text) !! ProcessError) r

Interpret Process as a native SystemProcess, producing unaccumulated chunks of Text.

interpretProcessTextLinesNative

Arguments

:: Members [Resource, Race, Async, Embed IO] r

=> Bool

Whether to discard output chunks if the queue is full.

-> Int

Maximum number of chunks allowed to be queued for each of the three standard pipes.

-> ProcessConfig () () ()

Basic config. The pipes will be changed to Handle by the interpreter.

-> InterpreterFor (Scoped () (Process ByteString Text Text) !! ProcessError) r

Interpret Process as a native SystemProcess, producing lines of Text.

interpretProcess

Arguments

:: forall resource err o e r. Member (Scoped resource (SystemProcess !! err)) r

=> Members [ProcessOutput o, ProcessOutput e, Resource, Race, Async, Embed IO] r

=> Bool

Whether to discard output chunks if the queue is full or block.

-> Int

Maximum number of chunks allowed to be queued for each of the three standard pipes.

-> InterpreterFor (Scoped () (Process ByteString o e) !! ProcessError) r

Interpret Process with a system process resource whose file descriptors are connected to three TBMQueues, deferring decoding of stdout and stderr to the interpreters of two ProcessOutput effects.

interpretProcessByteString

Arguments

:: forall resource err r. Members [Scoped resource (SystemProcess !! err), Resource, Race, Async, Embed IO] r

=> Bool

Whether to discard output chunks if the queue is full.

-> Int

Maximum number of chunks allowed to be queued for each of the three standard pipes.

-> InterpreterFor (Scoped () (Process ByteString ByteString ByteString) !! ProcessError) r

Interpret Process with a system process resource whose file descriptors are connected to three TBMQueues, producing ByteStrings.

interpretProcessByteStringLines

Arguments

:: forall resource err r. Members [Scoped resource (SystemProcess !! err), Resource, Race, Async, Embed IO] r

=> Bool

Whether to discard output chunks if the queue is full.

-> Int

Maximum number of chunks allowed to be queued for each of the three standard pipes.

-> InterpreterFor (Scoped () (Process ByteString ByteString ByteString) !! ProcessError) r

Interpret Process with a system process resource whose file descriptors are connected to three TBMQueues, producing chunks of lines of ByteStrings.

interpretProcessText

Arguments

:: forall resource err r. Members [Scoped resource (SystemProcess !! err), Resource, Race, Async, Embed IO] r

=> Bool

Whether to discard output chunks if the queue is full.

-> Int

Maximum number of chunks allowed to be queued for each of the three standard pipes.

-> InterpreterFor (Scoped () (Process ByteString Text Text) !! ProcessError) r

Interpret Process with a system process resource whose file descriptors are connected to three TBMQueues, producing Texts.

interpretProcessTextLines

Arguments

:: forall resource err r. Members [Scoped resource (SystemProcess !! err), Resource, Race, Async, Embed IO] r

=> Bool

Whether to discard output chunks if the queue is full.

-> Int

Maximum number of chunks allowed to be queued for each of the three standard pipes.

-> InterpreterFor (Scoped () (Process ByteString Text Text) !! ProcessError) r

Interpret Process with a system process resource whose file descriptors are connected to three TBMQueues, producing chunks of lines of Texts.

ProcessOutput

interpretProcessOutputId :: InterpreterFor (ProcessOutput ByteString) r

Interpret ProcessOutput by immediately emitting raw ByteStrings without accumulation.

interpretProcessOutputLines :: InterpreterFor (ProcessOutput ByteString) r

Interpret ProcessOutput by emitting individual ByteString lines of output.

interpretProcessOutputText :: InterpreterFor (ProcessOutput Text) r

Interpret ProcessOutput by immediately emitting Text without accumulation.

interpretProcessOutputTextLines :: InterpreterFor (ProcessOutput Text) r

Interpret ProcessOutput by emitting individual Text lines of output.

SystemProcess

interpretSystemProcessWithProcess :: forall r. Member (Embed IO) r => Process Handle Handle Handle -> InterpreterFor (SystemProcess !! SystemProcessError) r

Interpret SystemProcess with a concrete Process with connected pipes.

interpretSystemProcessNativeSingle :: forall r. Members [Resource, Embed IO] r => ProcessConfig () () () -> InterpreterFor (SystemProcess !! SystemProcessError) r

Interpret SystemProcess as a single global Process that's started immediately.

interpretSystemProcessNative :: forall r. Members [Resource, Embed IO] r => ProcessConfig () () () -> InterpreterFor (Scoped PipesProcess (SystemProcess !! SystemProcessError)) r

Interpret SystemProcess as a scoped Process that's started wherever withSystemProcess is called and terminated when the wrapped action finishes.

interpretSystemProcessWithProcessOpaque :: forall i o e r. Member (Embed IO) r => Process i o e -> InterpreterFor (SystemProcess !! SystemProcessError) r

Interpret SystemProcess with a concrete Process with connected pipes.

interpretSystemProcessNativeOpaqueSingle :: forall i o e r. Members [Resource, Embed IO] r => ProcessConfig i o e -> InterpreterFor (SystemProcess !! SystemProcessError) r

Interpret SystemProcess as a single global Process that's started immediately.

interpretSystemProcessNativeOpaque :: forall i o e r. Members [Resource, Embed IO] r => ProcessConfig i o e -> InterpreterFor (Scoped (Process i o e) (SystemProcess !! SystemProcessError)) r

Interpret SystemProcess as a scoped Process that's started wherever withSystemProcess is called and terminated when the wrapped action finishes.

Pty

interpretPty :: Members [Resource, Embed IO] r => InterpreterFor (Scoped PtyResources Pty !! PtyError) r

Interpret Pty as a Pty.

Tools

resolveExecutable

Arguments

:: Member (Embed IO) r

=> Path Rel File

Executable name, for $PATH lookup and error messages

-> Maybe (Path Abs File)

Explicit override to be checked for adequate permissions

-> Sem r (Either Text (Path Abs File))

Find a file in $PATH, verifying that it is executable by this process.