Cabal-3.12.1.0: A framework for packaging Haskell software

Copyright | Duncan Coutts 2009
Maintainer | cabal-devel@haskell.org
Portability | portable
Safe Haskell | None
Language | Haskell2010

Distribution.Simple.Program.Run

Description

This module provides a data type for program invocations and functions to run them.

Synopsis

- data ProgramInvocation = ProgramInvocation {
  - progInvokePath :: FilePath
  - progInvokeArgs :: [String]
  - progInvokeEnv :: [(String, Maybe String)]
  - progInvokeCwd :: Maybe FilePath
  - progInvokeInput :: Maybe IOData
  - progInvokeInputEncoding :: IOEncoding
  - progInvokeOutputEncoding :: IOEncoding
  }
- data IOEncoding
  - = IOEncodingText
  - | IOEncodingUTF8
- emptyProgramInvocation :: ProgramInvocation
- simpleProgramInvocation :: FilePath -> [String] -> ProgramInvocation
- programInvocation :: ConfiguredProgram -> [String] -> ProgramInvocation
- multiStageProgramInvocation :: ProgramInvocation -> (ProgramInvocation, ProgramInvocation, ProgramInvocation) -> [String] -> [ProgramInvocation]
- runProgramInvocation :: Verbosity -> ProgramInvocation -> IO ()
- getProgramInvocationOutput :: Verbosity -> ProgramInvocation -> IO String
- getProgramInvocationLBS :: Verbosity -> ProgramInvocation -> IO ByteString
- getProgramInvocationOutputAndErrors :: Verbosity -> ProgramInvocation -> IO (String, String, ExitCode)
- getProgramInvocationLBSAndErrors :: Verbosity -> ProgramInvocation -> IO (ByteString, String, ExitCode)
- getEffectiveEnvironment :: [(String, Maybe String)] -> IO (Maybe [(String, String)])

# Documentation

data ProgramInvocation Source #

Represents a specific invocation of a specific program.

This is used as an intermediate type between deciding how to call a program and actually doing it. This provides the opportunity to the caller to adjust how the program will be called. These invocations can either be run directly or turned into shell or batch scripts.

Constructors

ProgramInvocation |

Fields

- progInvokePath :: FilePath
- progInvokeArgs :: [String]
- progInvokeEnv :: [(String, Maybe String)]
- progInvokeCwd :: Maybe FilePath
- progInvokeInput :: Maybe IOData
- progInvokeInputEncoding :: IOEncoding

  TODO: remove this, make user decide when constructing `progInvokeInput`.

- progInvokeOutputEncoding :: IOEncoding

data IOEncoding Source #

Constructors

IOEncodingText |
IOEncodingUTF8 |

emptyProgramInvocation :: ProgramInvocation Source #

simpleProgramInvocation :: FilePath -> [String] -> ProgramInvocation Source #

programInvocation :: ConfiguredProgram -> [String] -> ProgramInvocation Source #

multiStageProgramInvocation :: ProgramInvocation -> (ProgramInvocation, ProgramInvocation, ProgramInvocation) -> [String] -> [ProgramInvocation] Source #

Like the unix xargs program. Useful for when we've got very long command lines that might overflow an OS limit on command line length and so you need to invoke a command multiple times to get all the args in.

It takes four template invocations corresponding to the simple, initial, middle and last invocations. If the number of args given is small enough that we can get away with just a single invocation then the simple one is used:

    $ simple args

If the number of args given means that we need to use multiple invocations then the templates for the initial, middle and last invocations are used:

    $ initial args_0
    $ middle  args_1
    $ middle  args_2
      ...
    $ final   args_n

runProgramInvocation :: Verbosity -> ProgramInvocation -> IO () Source #

getProgramInvocationOutput :: Verbosity -> ProgramInvocation -> IO String Source #

getProgramInvocationLBS :: Verbosity -> ProgramInvocation -> IO ByteString Source #

getProgramInvocationOutputAndErrors :: Verbosity -> ProgramInvocation -> IO (String, String, ExitCode) Source #

getProgramInvocationLBSAndErrors :: Verbosity -> ProgramInvocation -> IO (ByteString, String, ExitCode) Source #

getEffectiveEnvironment :: [(String, Maybe String)] -> IO (Maybe [(String, String)]) Source #

Return the current environment extended with the given overrides. If an entry is specified twice in `overrides`, the second entry takes precedence.