-- 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.2.3 -- | 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")
--
module RawFilePath.Process -- | A literal POSIX file path type RawFilePath = ByteString -- | The process configuration that is needed for creating new processes. -- Use proc 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 Handle. 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 Handle. 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 terminateProcess -- and then waitForProcess. 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 -- | Create a new process with the given configuration, and wait for it to -- finish. callProcess :: ProcessConf stdin stdout stderr -> IO ExitCode -- | 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. readProcessWithExitCode :: ProcessConf stdin stdout stderr -> IO (ExitCode, ByteString, ByteString) -- | This is the module for the RawFilePath version of functions in -- the directory package. module RawFilePath.Directory -- | A literal POSIX file path type RawFilePath = ByteString -- | Test whether the given path points to an existing filesystem object. -- If the user lacks necessary permissions to search the parent -- directories, this function may return false even if the file does -- actually exist. doesPathExist :: RawFilePath -> IO Bool -- | Return True if the argument file exists and is not a directory, -- and False otherwise. doesFileExist :: RawFilePath -> IO Bool -- | Return True if the argument file exists and is either a -- directory or a symbolic link to a directory, and False -- otherwise. doesDirectoryExist :: RawFilePath -> IO Bool -- | Returns the current user's home directory. More specifically, the -- value of the HOME environment variable. -- -- The directory returned is expected to be writable by the current user, -- but note that it isn't generally considered good practice to store -- application-specific data here; use getXdgDirectory or -- getAppUserDataDirectory instead. -- -- The operation may fail with: -- -- getHomeDirectory :: IO (Maybe RawFilePath) -- | Return the current directory for temporary files. It first returns the -- value of the TMPDIR environment variable or "/tmp" if the -- variable isn't defined. getTemporaryDirectory :: IO ByteString -- | Get a list of files in the specified directory, excluding "." and ".." -- -- 
--   ghci> listDirectory "/"
--   ["home","sys","var","opt","lib64","sbin","usr","srv","dev","lost+found","bin","tmp","run","root","boot","proc","etc","lib"]
--
listDirectory :: RawFilePath -> IO [RawFilePath] -- | Get a list of files in the specified directory, including "." and ".." -- -- 
--   ghci> getDirectoryFiles "/"
--   ["home","sys","var","opt","..","lib64","sbin","usr","srv","dev","lost+found","mnt","bin","tmp","run","root","boot",".","proc","etc","lib"]
--
getDirectoryFiles :: RawFilePath -> IO [RawFilePath] -- | Recursively get all files in all subdirectories of the specified -- directory. -- -- 
--   *System.RawFilePath> getDirectoryFilesRecursive "src"
--   ["src/System/RawFilePath.hs"]
--
getDirectoryFilesRecursive :: RawFilePath -> IO [RawFilePath] -- | Create a new directory. -- -- 
--   ghci> createDirectory "/tmp/mydir"
--   ghci> getDirectoryFiles "/tmp/mydir"
--   [".",".."]
--   ghci> createDirectory "/tmp/mydir/anotherdir"
--   ghci> getDirectoryFiles "/tmp/mydir"
--   [".","..","anotherdir"]
--
createDirectory :: RawFilePath -> IO () -- | Create a new directory if it does not already exist. If the first -- argument is True the function will also create all parent -- directories when they are missing. createDirectoryIfMissing :: Bool -> RawFilePath -> IO () -- | Remove a file. This function internally calls unlink. If the -- file does not exist, an exception is thrown. removeFile :: RawFilePath -> IO () -- | A function that "tries" to remove a file. If the file does not exist, -- nothing happens. tryRemoveFile :: RawFilePath -> IO () -- | Remove a directory. The target directory needs to be empty; Otherwise -- an exception will be thrown. removeDirectory :: RawFilePath -> IO () -- | Remove an existing directory dir together with its contents and -- subdirectories. Within this directory, symbolic links are removed -- without affecting their targets. removeDirectoryRecursive :: RawFilePath -> IO () -- | Welcome to RawFilePath, a small part of the Haskell -- community's effort to purge String for the Greater Good. -- -- With this package, you can interact with the Unix system without the -- file path encoding issue or the String ↔ ByteString -- conversion overhead. -- --

Rationale

-- -- Traditional String is notorious: -- -- -- -- String has another problematic nature to serve as a file path -- data type: Encoding blindness. All functions that return -- FilePath would actually take a series of bytes returned by a -- syscall and somehow magically "decode" it into a String which -- is surprising because no encoding information was given. Of course -- there is no magic and it's an abject fail. FilePath just -- wouldn't work. -- --

Usage

-- -- This is the top-level module that re-exports the sub-modules. -- Therefore, you can -- -- 
--   import RawFilePath
--
-- -- to import all functions. module RawFilePath -- | A literal POSIX file path type RawFilePath = ByteString -- | A drop-in replacement of Data.ByteString from the -- bytestring package that provides file I/O functions with -- RawFilePath instead of FilePath. module Data.ByteString.RawFilePath -- | A literal POSIX file path type RawFilePath = ByteString -- | Read an entire file at the RawFilePath strictly into a -- ByteString. readFile :: RawFilePath -> IO ByteString -- | Write a ByteString to a file at the RawFilePath. writeFile :: RawFilePath -> ByteString -> IO () -- | Append a ByteString to a file at the RawFilePath. 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