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


-- | Use RawFilePath instead of FilePath
--   
--   Please see README.md
@package rawfilepath
@version 0.1.1


-- | Higher-level API for the <a>RawFilePath</a>-variants of functions in
--   the <tt>unix</tt> module.
module System.RawFilePath

-- | A literal POSIX file path
type RawFilePath = ByteString

-- | Creates a new process to run the specified command with the given
--   arguments, and waits for it to finish. Throws an exception if the
--   process returns a nonzero exit code.
--   
--   <pre>
--   *System.RawFilePath&gt; callProcess "ls" ["-a", "src"]
--   .  ..  System
--   </pre>
callProcess :: RawFilePath -> [ByteString] -> IO ()

-- | Same as <a>callProcess</a> except the child process will share the
--   parent's stdout and stderr, meaning it won't print anything.
callProcessSilent :: RawFilePath -> [ByteString] -> IO ExitCode

-- | Runs a command, reads its standard output strictly, blocking until the
--   process terminates, and returns the output as <a>ByteString</a>.
--   
--   <pre>
--   *System.RawFilePath&gt; readProcess "date" ["+%s"]
--   "1469999314\n"
--   </pre>
readProcess :: RawFilePath -> [ByteString] -> IO ByteString

-- | A 'safer' approach to <a>readProcess</a>. Depending on the exit status
--   of the process, this function will return output either from stderr or
--   stdout.
--   
--   <pre>
--   *System.RawFilePath&gt; readProcessEither "date" ["%s"]
--   Left "date: invalid date \226\128\152%s\226\128\153\n"
--   *System.RawFilePath&gt; readProcessEither "date" ["+%s"]
--   Right "1469999817\n"
--   </pre>
readProcessEither :: RawFilePath -> [ByteString] -> IO (Either ByteString ByteString)

-- | Get a list of files in the specified directory, excluding "." and ".."
--   
--   <pre>
--   *System.RawFilePath&gt; listDirectory "src"
--   ["..","System","."]
--   </pre>
listDirectory :: RawFilePath -> IO [RawFilePath]

-- | Get a list of files in the specified directory, including "." and ".."
--   
--   <pre>
--   *System.RawFilePath&gt; getDirectoryFiles "src"
--   ["..","System","."]
--   </pre>
getDirectoryFiles :: RawFilePath -> IO [RawFilePath]

-- | Recursively get all files in all subdirectories of the specified
--   directory.
--   
--   <pre>
--   *System.RawFilePath&gt; getDirectoryFilesRecursive "src"
--   ["src/System/RawFilePath.hs"]
--   </pre>
getDirectoryFilesRecursive :: RawFilePath -> IO [RawFilePath]

-- | Copy a file from the source path to the destination path.
copyFile :: RawFilePath -> RawFilePath -> IO ()

-- | Returns the current user's home directory.
getHomeDirectory :: IO RawFilePath

-- | Returns <a>True</a> if the argument file exists and is not a
--   directory.
doesFileExist :: RawFilePath -> IO Bool

-- | Returns <a>True</a> if the argument file exists and is a directory.
doesDirectoryExist :: RawFilePath -> IO Bool

-- | Change the working directory to the given path.
setCurrentDirectory :: RawFilePath -> IO ()

-- | A function that "tries" to remove a file. If the file does not exist,
--   nothing happens.
tryRemoveFile :: RawFilePath -> IO ()


-- | Welcome to <tt>System.Process.RawFilePath</tt>, a small part of the
--   Haskell community's effort to purge <a>String</a> for the Greater
--   Good.
--   
--   With this module, you can create (and interact with) sub-processes
--   without the encoding problem of <a>String</a>. The command and its
--   arguments, all <a>ByteString</a>s, never get converted from/to
--   <a>String</a> internally on its way to the actual syscall. It also
--   avoids the time/space waste of <a>String</a>.
--   
--   The interface, unlike the original <tt>process</tt> package, uses
--   types to prevent unnecessary runtime errors when obtaining
--   <a>Handle</a>s. This is inspired by the <tt>typed-process</tt> 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).
--   
--   <a>Handle</a> (accessible with <a>processStdin</a>,
--   <a>processStdout</a>, and <a>processStderr</a>) is what you can use to
--   interact with the sub-process. For example, use <a>hGetContents</a>
--   from <a>Data.ByteString</a> to read from a <a>Handle</a> as a
--   <a>ByteString</a>.
--   
--   <h2>Example</h2>
--   
--   <pre>
--   {-# language OverloadedStrings #-}
--   
--   import System.Process.RawFilePath
--   import qualified Data.ByteString as B
--   
--   main :: IO ()
--   main = do
--       p &lt;- <a>startProcess</a> $ <a>proc</a> "echo" ["hello"]
--           `setStdout` <a>CreatePipe</a>
--       result &lt;- B.hGetContents (<a>processStdout</a> p)
--       _ &lt;- <a>waitForProcess</a> p
--   
--       print (result == "hello\n")
--   </pre>
module System.Process.RawFilePath

-- | The process configuration that is needed for creating new processes.
--   Use <a>proc</a> to make one.
data ProcessConf stdin stdout stderr

-- | Create a process configuration with the default settings.
proc :: RawFilePath -> [ByteString] -> ProcessConf Inherit Inherit Inherit

-- | 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.
class StreamType c where mbFd = undefined willCreateHandle = undefined

-- | Create a new pipe for the stream. You get a new <a>Handle</a>.
data CreatePipe
CreatePipe :: CreatePipe

-- | 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.
data Inherit
Inherit :: Inherit

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

-- | Use the supplied <a>Handle</a>.
data UseHandle
UseHandle :: Handle -> UseHandle

-- | Control how the standard input of the process will be initialized.
setStdin :: (StreamType newStdin) => ProcessConf oldStdin stdout stderr -> newStdin -> ProcessConf newStdin stdout stderr
infixl 4 `setStdin`

-- | Control how the standard output of the process will be initialized.
setStdout :: (StreamType newStdout) => ProcessConf stdin oldStdout stderr -> newStdout -> ProcessConf stdin newStdout stderr
infixl 4 `setStdout`

-- | Control how the standard error of the process will be initialized.
setStderr :: (StreamType newStderr) => ProcessConf stdin stdout oldStderr -> newStderr -> ProcessConf stdin stdout newStderr
infixl 4 `setStderr`

-- | The process type. The three type variables denote how its standard
--   streams were initialized.
data Process stdin stdout stderr

-- | Start a new sub-process with the given configuration.
startProcess :: (StreamType stdin, StreamType stdout, StreamType stderr) => ProcessConf stdin stdout stderr -> IO (Process stdin stdout stderr)

-- | Take a process and return its standard input handle.
processStdin :: Process CreatePipe stdout stderr -> Handle

-- | Take a process and return its standard output handle.
processStdout :: Process stdin CreatePipe stderr -> Handle

-- | Take a process and return its standard error handle.
processStderr :: Process stdin stdout CreatePipe -> Handle

-- | Stop a sub-process. For now it simply calls <a>terminateProcess</a>
--   and then <a>waitForProcess</a>.
stopProcess :: Process stdin stdout stderr -> IO ExitCode

-- | Terminate a sub-process by sending SIGTERM to it.
terminateProcess :: Process stdin stdout stderr -> IO ()

-- | Wait (block) for a sub-process to exit and obtain its exit code.
waitForProcess :: Process stdin stdout stderr -> IO ExitCode


-- | A drop-in replacement of <tt>Data.ByteString</tt> from the
--   <tt>bytestring</tt> package that provides file I/O functions with
--   <a>RawFilePath</a> instead of <a>FilePath</a>.
module Data.ByteString.RawFilePath

-- | A literal POSIX file path
type RawFilePath = ByteString

-- | Read an entire file at the <a>RawFilePath</a> strictly into a
--   <a>ByteString</a>.
readFile :: RawFilePath -> IO ByteString

-- | Write a <a>ByteString</a> to a file at the <a>RawFilePath</a>.
writeFile :: RawFilePath -> ByteString -> IO ()

-- | Append a <a>ByteString</a> to a file at the <a>RawFilePath</a>.
appendFile :: RawFilePath -> ByteString -> IO ()

-- | Acquire a file handle and perform an I/O action. The file will be
--   closed on exit or when this I/O action throws an exception.
withFile :: RawFilePath -> IOMode -> (Handle -> IO r) -> IO r