-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Process piping library
--   
--   A library with operations for piping data through a pipeline of
--   processes.
@package Pipe
@version 1.0


-- | Operations for piping data through multiple processes.
--   
--   <a>pipe</a> is the most general function, with <a>filePipe</a> and
--   'pipe\'' provided for convenience purposes. For the common case of
--   piping between <a>String</a>s, the <a>pipeString</a> wrapper and the
--   <a>word8ToString</a> and <a>stringToWord8</a> helpers are included.
--   
--   Whenever specifying a path to a process, explicitly specifying the
--   current directory is recommended for portability. That is: use "./foo"
--   instead of "foo", for instance.
--   
--   On Windows, appending ".exe" to process paths is attempted if the
--   invocation fails.
module System.Process.Pipe

-- | Pipes the contents of the first file to the second file through all
--   the programs named.
--   
--   The working directory used is the directory component of the path to
--   the first file.
filePipe :: [(FilePath, [String])] -> FilePath -> FilePath -> IO ()

-- | From a <a>Tap</a>, data up to the requested amount flows into a
--   <a>Ptr</a>. The exact amount of 'Word8'\'s that flowed is returned.
--   The requested amount is guaranteed to be no greater than
--   <a>bufferSize</a>.
class Tap a
flowOut :: (Tap a) => a -> Ptr Word8 -> Int -> IO (a, Int)
exhausted :: (Tap a) => a -> IO Bool

-- | To a <a>Sink</a>, the requested amount of 'Word8'\'s flows from a
--   <a>Ptr</a>. The requested amount is guaranteed to be no greater than
--   <a>bufferSize</a>.
class Sink a
flowIn :: (Sink a) => a -> Ptr Word8 -> Int -> IO a

-- | The size of one chunk of data. A <a>Ptr</a> <a>Word8</a> given to a
--   <a>Tap</a> or <a>Sink</a> is guaranteed to have room for this many
--   'Word8'\'s, but no more.
bufferSize :: Int

-- | Pipes data from the <a>Tap</a> to the <a>Sink</a> through all the
--   commands named, in the given working directory.
--   
--   Be careful! All IO is at the byte level: this means that piping even a
--   String such as "foo" will result in the raw UTF-32 moving: the bytes
--   (in my case; I believe this is implementation-dependent) in question
--   are not the ASCII <tt>[102, 111, 111]</tt> but rather <tt>[102, 0, 0,
--   0, 111, 0, 0, 0, 111, 0, 0, 0]</tt>.
--   
--   Note to Windows users: since <a>hGetBufNonBlocking</a> doesn't work on
--   Windows (it blocks despite its name, see
--   <a>http://hackage.haskell.org/trac/ghc/ticket/806</a>), this pipeline
--   uses a non-constant amount of space. The amount used is linear in the
--   amount of data used at any point in the pipeline. So if you want to
--   pipe 20 gibioctets of data to a program, you better make sure you have
--   at least said amount of memory available. (In fact, ByteStrings are
--   used, and their documentation suggests that you might want twice that,
--   just in case.)
--   
--   In addition, the <a>Tap</a> and <a>Sink</a> classes are meant for the
--   POSIX code: having to move data through the <a>Ptr</a> <a>Word8</a>
--   types, <a>bufferSize</a> bytes at a time, results in extra complexity.
--   
--   If you want to do something about the above, ideally fix the GHC
--   ticket (probably nontrivial) and let me know so that I can activate
--   the better code for Windows as well. Alternatively, feel free to code
--   an implementation of this which works on Windows.
pipe :: (Tap t, Sink s) => FilePath -> [(FilePath, [String])] -> t -> s -> IO (t, s)

-- | A convenience function for when you don't care about the working
--   directory.
--   
--   <pre>
--   pipe' = pipe "."
--   </pre>
pipe' :: (Tap t, Sink s) => [(FilePath, [String])] -> t -> s -> IO (t, s)

-- | A convenience function for the common case of piping from a
--   <a>String</a> to a <a>String</a>. This uses the <a>word8ToString</a>
--   and <a>stringToWord8</a> functions and thus loses information if your
--   <a>Char</a>s are non-ASCII.
pipeString :: [(FilePath, [String])] -> String -> IO String

-- | A helper function which converts a <tt>[<a>Word8</a>]</tt> to a
--   <a>String</a> by mapping <a>chr</a> over the octets.
--   
--   In most cases, when you wish to pipe data to a String, you do not want
--   to interpret the results as the raw byte pattern of <a>Char</a>s, so
--   you use <tt>[<a>Word8</a>]</tt> as the <a>Sink</a> type. This function
--   handles the common case of ASCII data simply—if you're dealing with
--   non-ASCII data you probably need to handle the results in a different
--   way.
word8ToString :: [Word8] -> String

-- | The inverse of <a>word8ToString</a>. Any <a>Char</a>s greater than 255
--   are truncated: once again, be careful with non-ASCII.
stringToWord8 :: String -> [Word8]