-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Use RawFilePath instead of FilePath -- -- Please see README.md @package rawfilepath @version 1.0.1 -- | 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 -- | The interact function takes a function of type ByteString -> -- ByteString as its argument. The entire input from the standard -- input device is passed to this function as its argument, and the -- resulting string is output on the standard output device. interact :: (ByteString -> ByteString) -> IO () -- | getContents. Read stdin strictly. Equivalent to hGetContents stdin The -- Handle is closed after the contents have been read. getContents :: IO ByteString -- | Read a handle's entire contents strictly into a ByteString. -- -- This function reads chunks at a time, increasing the chunk size on -- each read. The final string is then reallocated to the appropriate -- size. For files > half of available memory, this may lead to memory -- exhaustion. Consider using readFile in this case. -- -- The Handle is closed once the contents have been read, or if an -- exception is thrown. hGetContents :: Handle -> IO ByteString -- | Like hGet, except that a shorter ByteString may be -- returned if there are not enough bytes immediately available to -- satisfy the whole request. hGetSome only blocks if there is no -- data available, and EOF has not yet been reached. hGetSome :: Handle -> Int -> IO ByteString -- | hGetNonBlocking is similar to hGet, except that it will never -- block waiting for data to become available, instead it returns only -- whatever data is available. If there is no data available to be read, -- hGetNonBlocking returns empty. -- -- Note: on Windows and with Haskell implementation other than GHC, this -- function does not work correctly; it behaves identically to -- hGet. hGetNonBlocking :: Handle -> Int -> IO ByteString -- | Read a ByteString directly from the specified Handle. -- This is far more efficient than reading the characters into a -- String and then using pack. First argument is the Handle -- to read from, and the second is the number of bytes to read. It -- returns the bytes read, up to n, or empty if EOF has been -- reached. -- -- hGet is implemented in terms of hGetBuf. -- -- If the handle is a pipe or socket, and the writing end is closed, -- hGet will behave as if EOF was reached. hGet :: Handle -> Int -> IO ByteString -- | Write a ByteString to stdout, appending a newline byte putStrLn :: ByteString -> IO () -- | Write a ByteString to stdout putStr :: ByteString -> IO () -- | Write a ByteString to a handle, appending a newline byte hPutStrLn :: Handle -> ByteString -> IO () -- | A synonym for hPut, for compatibility hPutStr :: Handle -> ByteString -> IO () -- | Similar to hPut except that it will never block. Instead it -- returns any tail that did not get written. This tail may be -- empty in the case that the whole string was written, or the -- whole original string if nothing was written. Partial writes are also -- possible. -- -- Note: on Windows and with Haskell implementation other than GHC, this -- function does not work correctly; it behaves identically to -- hPut. hPutNonBlocking :: Handle -> ByteString -> IO ByteString -- | Outputs a ByteString to the specified Handle. hPut :: Handle -> ByteString -> IO () -- | Read a line from a handle hGetLine :: Handle -> IO ByteString -- | Read a line from stdin. getLine :: IO ByteString -- | O(n) Make a copy of the ByteString with its own storage. -- This is mainly useful to allow the rest of the data pointed to by the -- ByteString to be garbage collected, for example if a large -- string has been read in, and only a small part of it is needed in the -- rest of the program. copy :: ByteString -> ByteString -- | O(n). Construct a new ByteString from a -- CStringLen. The resulting ByteString is an immutable -- copy of the original CStringLen. The ByteString is a -- normal Haskell value and will be managed on the Haskell heap. packCStringLen :: CStringLen -> IO ByteString -- | O(n). Construct a new ByteString from a -- CString. The resulting ByteString is an immutable -- copy of the original CString, and is managed on the Haskell -- heap. The original CString must be null terminated. packCString :: CString -> IO ByteString -- | O(n) construction Use a ByteString with a function -- requiring a CStringLen. As for useAsCString this -- function makes a copy of the original ByteString. It must not -- be stored or used after the subcomputation finishes. useAsCStringLen :: ByteString -> (CStringLen -> IO a) -> IO a -- | O(n) construction Use a ByteString with a function -- requiring a null-terminated CString. The CString is -- a copy and will be freed automatically; it must not be stored or used -- after the subcomputation finishes. useAsCString :: ByteString -> (CString -> IO a) -> IO a -- | O(n) Sort a ByteString efficiently, using counting sort. sort :: ByteString -> ByteString -- | O(n) Return all final segments of the given ByteString, -- longest first. tails :: ByteString -> [ByteString] -- | O(n) Return all initial segments of the given -- ByteString, shortest first. inits :: ByteString -> [ByteString] -- | O(n) unzip transforms a list of pairs of bytes into a -- pair of ByteStrings. Note that this performs two pack -- operations. unzip :: [(Word8, Word8)] -> (ByteString, ByteString) -- | zipWith generalises zip by zipping with the function -- given as the first argument, instead of a tupling function. For -- example, zipWith (+) is applied to two ByteStrings to -- produce the list of corresponding sums. zipWith :: (Word8 -> Word8 -> a) -> ByteString -> ByteString -> [a] -- | O(n) zip takes two ByteStrings and returns a list of -- corresponding pairs of bytes. If one input ByteString is short, excess -- elements of the longer ByteString are discarded. This is equivalent to -- a pair of unpack operations. zip :: ByteString -> ByteString -> [(Word8, Word8)] -- | Find the indexes of all (possibly overlapping) occurences of a -- substring in a string. findSubstrings :: ByteString -> ByteString -> [Int] -- | Get the first index of a substring in another string, or -- Nothing if the string is not found. findSubstring p s -- is equivalent to listToMaybe (findSubstrings p s). findSubstring :: ByteString -> ByteString -> Maybe Int -- | Break a string on a substring, returning a pair of the part of the -- string prior to the match, and the rest of the string. -- -- The following relationships hold: -- -- 
--   break (== c) l == breakSubstring (singleton c) l
--
-- -- and: -- -- 
--   findSubstring s l ==
--      if null s then Just 0
--                else case breakSubstring s l of
--                         (x,y) | null y    -> Nothing
--                               | otherwise -> Just (length x)
--
-- -- For example, to tokenise a string, dropping delimiters: -- -- 
--   tokenise x y = h : if null t then [] else tokenise x (drop (length x) t)
--       where (h,t) = breakSubstring x y
--
-- -- To skip to the first occurence of a string: -- -- 
--   snd (breakSubstring x y)
--
-- -- To take the parts of a string before a delimiter: -- -- 
--   fst (breakSubstring x y)
--
-- -- Note that calling `breakSubstring x` does some preprocessing work, so -- you should avoid unnecessarily duplicating breakSubstring calls with -- the same pattern. breakSubstring :: ByteString -> ByteString -> (ByteString, ByteString) -- | Check whether one string is a substring of another. isInfixOf p -- s is equivalent to not (null (findSubstrings p s)). isInfixOf :: ByteString -> ByteString -> Bool -- | O(n) The stripSuffix function takes two ByteStrings and -- returns Just the remainder of the second iff the first is its -- suffix, and otherwise Nothing. stripSuffix :: ByteString -> ByteString -> Maybe ByteString -- | O(n) The isSuffixOf function takes two ByteStrings and -- returns True iff the first is a suffix of the second. -- -- The following holds: -- -- 
--   isSuffixOf x y == reverse x `isPrefixOf` reverse y
--
-- -- However, the real implemenation uses memcmp to compare the end of the -- string only, with no reverse required.. isSuffixOf :: ByteString -> ByteString -> Bool -- | O(n) The stripPrefix function takes two ByteStrings and -- returns Just the remainder of the second iff the first is its -- prefix, and otherwise Nothing. stripPrefix :: ByteString -> ByteString -> Maybe ByteString -- | O(n) The isPrefixOf function takes two ByteStrings and -- returns True if the first is a prefix of the second. isPrefixOf :: ByteString -> ByteString -> Bool -- | O(n) The partition function takes a predicate a -- ByteString and returns the pair of ByteStrings with elements which do -- and do not satisfy the predicate, respectively; i.e., -- -- 
--   partition p bs == (filter p xs, filter (not . p) xs)
--
partition :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString) -- | O(n) The find function takes a predicate and a -- ByteString, and returns the first element in matching the predicate, -- or Nothing if there is no such element. -- -- 
--   find f p = case findIndex f p of Just n -> Just (p ! n) ; _ -> Nothing
--
find :: (Word8 -> Bool) -> ByteString -> Maybe Word8 -- | O(n) filter, applied to a predicate and a ByteString, -- returns a ByteString containing those characters that satisfy the -- predicate. filter :: (Word8 -> Bool) -> ByteString -> ByteString -- | O(n) notElem is the inverse of elem notElem :: Word8 -> ByteString -> Bool -- | O(n) elem is the ByteString membership predicate. elem :: Word8 -> ByteString -> Bool -- | The findIndices function extends findIndex, by returning -- the indices of all elements satisfying the predicate, in ascending -- order. findIndices :: (Word8 -> Bool) -> ByteString -> [Int] -- | The findIndex function takes a predicate and a -- ByteString and returns the index of the first element in the -- ByteString satisfying the predicate. findIndex :: (Word8 -> Bool) -> ByteString -> Maybe Int -- | count returns the number of times its argument appears in the -- ByteString -- -- 
--   count = length . elemIndices
--
-- -- But more efficiently than using length on the intermediate list. count :: Word8 -> ByteString -> Int -- | O(n) The elemIndices function extends elemIndex, -- by returning the indices of all elements equal to the query element, -- in ascending order. This implementation uses memchr(3). elemIndices :: Word8 -> ByteString -> [Int] -- | O(n) The elemIndexEnd function returns the last index of -- the element in the given ByteString which is equal to the query -- element, or Nothing if there is no such element. The following -- holds: -- -- 
--   elemIndexEnd c xs ==
--   (-) (length xs - 1) `fmap` elemIndex c (reverse xs)
--
elemIndexEnd :: Word8 -> ByteString -> Maybe Int -- | O(n) The elemIndex function returns the index of the -- first element in the given ByteString which is equal to the -- query element, or Nothing if there is no such element. This -- implementation uses memchr(3). elemIndex :: Word8 -> ByteString -> Maybe Int -- | O(1) ByteString index (subscript) operator, starting -- from 0. index :: ByteString -> Int -> Word8 -- | O(n) The intercalate function takes a ByteString -- and a list of ByteStrings and concatenates the list after -- interspersing the first argument between each element of the list. intercalate :: ByteString -> [ByteString] -> ByteString -- | The groupBy function is the non-overloaded version of -- group. groupBy :: (Word8 -> Word8 -> Bool) -> ByteString -> [ByteString] -- | The group function takes a ByteString and returns a list of -- ByteStrings such that the concatenation of the result is equal to the -- argument. Moreover, each sublist in the result contains only equal -- elements. For example, -- -- 
--   group "Mississippi" = ["M","i","ss","i","ss","i","pp","i"]
--
-- -- It is a special case of groupBy, which allows the programmer to -- supply their own equality test. It is about 40% faster than groupBy -- (==) group :: ByteString -> [ByteString] -- | O(n) Break a ByteString into pieces separated by the -- byte argument, consuming the delimiter. I.e. -- -- 
--   split '\n' "a\nb\nd\ne" == ["a","b","d","e"]
--   split 'a'  "aXaXaXa"    == ["","X","X","X",""]
--   split 'x'  "x"          == ["",""]
--
-- -- and -- -- 
--   intercalate [c] . split c == id
--   split == splitWith . (==)
--
-- -- As for all splitting functions in this library, this function does not -- copy the substrings, it just constructs new ByteStrings that -- are slices of the original. split :: Word8 -> ByteString -> [ByteString] -- | O(n) Splits a ByteString into components delimited by -- separators, where the predicate returns True for a separator element. -- The resulting components do not contain the separators. Two adjacent -- separators result in an empty component in the output. eg. -- -- 
--   splitWith (=='a') "aabbaca" == ["","","bb","c",""]
--   splitWith (=='a') []        == []
--
splitWith :: (Word8 -> Bool) -> ByteString -> [ByteString] -- | spanEnd behaves like span but from the end of the -- ByteString. We have -- -- 
--   spanEnd (not.isSpace) "x y z" == ("x y ","z")
--
-- -- and -- -- 
--   spanEnd (not . isSpace) ps
--      ==
--   let (x,y) = span (not.isSpace) (reverse ps) in (reverse y, reverse x)
--
spanEnd :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString) -- | span p xs breaks the ByteString into two segments. It -- is equivalent to (takeWhile p xs, dropWhile p -- xs) span :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString) -- | breakEnd behaves like break but from the end of the -- ByteString -- -- breakEnd p == spanEnd (not.p) breakEnd :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString) -- | breakByte breaks its ByteString argument at the first occurence -- of the specified byte. It is more efficient than break as it is -- implemented with memchr(3). I.e. -- -- 
--   break (=='c') "abcd" == breakByte 'c' "abcd"
--
breakByte :: Word8 -> ByteString -> (ByteString, ByteString) -- | break p is equivalent to span (not . -- p). -- -- Under GHC, a rewrite rule will transform break (==) into a call to the -- specialised breakByte: -- -- 
--   break ((==) x) = breakByte x
--   break (==x) = breakByte x
--
break :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString) -- | dropWhile p xs returns the suffix remaining after -- takeWhile p xs. dropWhile :: (Word8 -> Bool) -> ByteString -> ByteString -- | takeWhile, applied to a predicate p and a ByteString -- xs, returns the longest prefix (possibly empty) of -- xs of elements that satisfy p. takeWhile :: (Word8 -> Bool) -> ByteString -> ByteString -- | O(1) splitAt n xs is equivalent to -- (take n xs, drop n xs). splitAt :: Int -> ByteString -> (ByteString, ByteString) -- | O(1) drop n xs returns the suffix of -- xs after the first n elements, or [] if -- n > length xs. drop :: Int -> ByteString -> ByteString -- | O(1) take n, applied to a ByteString -- xs, returns the prefix of xs of length n, -- or xs itself if n > length xs. take :: Int -> ByteString -> ByteString -- | O(n) Like unfoldr, unfoldrN builds a ByteString -- from a seed value. However, the length of the result is limited by the -- first argument to unfoldrN. This function is more efficient -- than unfoldr when the maximum length of the result is known. -- -- The following equation relates unfoldrN and unfoldr: -- -- 
--   fst (unfoldrN n f s) == take n (unfoldr f s)
--
unfoldrN :: Int -> (a -> Maybe (Word8, a)) -> a -> (ByteString, Maybe a) -- | O(n), where n is the length of the result. The -- unfoldr function is analogous to the List 'unfoldr'. -- unfoldr builds a ByteString from a seed value. The function -- takes the element and returns Nothing if it is done producing -- the ByteString or returns Just (a,b), in which case, -- a is the next byte in the string, and b is the seed -- value for further production. -- -- Examples: -- -- 
--      unfoldr (\x -> if x <= 5 then Just (x, x + 1) else Nothing) 0
--   == pack [0, 1, 2, 3, 4, 5]
--
unfoldr :: (a -> Maybe (Word8, a)) -> a -> ByteString -- | O(n) replicate n x is a ByteString of length -- n with x the value of every element. The following -- holds: -- -- 
--   replicate w c = unfoldr w (\u -> Just (u,u)) c
--
-- -- This implemenation uses memset(3) replicate :: Int -> Word8 -> ByteString -- | scanr1 is a variant of scanr that has no starting value -- argument. scanr1 :: (Word8 -> Word8 -> Word8) -> ByteString -> ByteString -- | scanr is the right-to-left dual of scanl. scanr :: (Word8 -> Word8 -> Word8) -> Word8 -> ByteString -> ByteString -- | scanl1 is a variant of scanl that has no starting value -- argument. This function will fuse. -- -- 
--   scanl1 f [x1, x2, ...] == [x1, x1 `f` x2, ...]
--
scanl1 :: (Word8 -> Word8 -> Word8) -> ByteString -> ByteString -- | scanl is similar to foldl, but returns a list of -- successive reduced values from the left. This function will fuse. -- -- 
--   scanl f z [x1, x2, ...] == [z, z `f` x1, (z `f` x1) `f` x2, ...]
--
-- -- Note that -- -- 
--   last (scanl f z xs) == foldl f z xs.
--
scanl :: (Word8 -> Word8 -> Word8) -> Word8 -> ByteString -> ByteString -- | The mapAccumR function behaves like a combination of map -- and foldr; it applies a function to each element of a -- ByteString, passing an accumulating parameter from right to left, and -- returning a final value of this accumulator together with the new -- ByteString. mapAccumR :: (acc -> Word8 -> (acc, Word8)) -> acc -> ByteString -> (acc, ByteString) -- | The mapAccumL function behaves like a combination of map -- and foldl; it applies a function to each element of a -- ByteString, passing an accumulating parameter from left to right, and -- returning a final value of this accumulator together with the new -- list. mapAccumL :: (acc -> Word8 -> (acc, Word8)) -> acc -> ByteString -> (acc, ByteString) -- | O(n) minimum returns the minimum value from a -- ByteString This function will fuse. An exception will be thrown -- in the case of an empty ByteString. minimum :: ByteString -> Word8 -- | O(n) maximum returns the maximum value from a -- ByteString This function will fuse. An exception will be thrown -- in the case of an empty ByteString. maximum :: ByteString -> Word8 -- | O(n) Applied to a predicate and a ByteString, all -- determines if all elements of the ByteString satisfy the -- predicate. all :: (Word8 -> Bool) -> ByteString -> Bool -- | O(n) Applied to a predicate and a ByteString, any -- determines if any element of the ByteString satisfies the -- predicate. any :: (Word8 -> Bool) -> ByteString -> Bool -- | Map a function over a ByteString and concatenate the results concatMap :: (Word8 -> ByteString) -> ByteString -> ByteString -- | O(n) Concatenate a list of ByteStrings. concat :: [ByteString] -> ByteString -- | foldr1' is a variant of foldr1, but is strict in the -- accumulator. foldr1' :: (Word8 -> Word8 -> Word8) -> ByteString -> Word8 -- | foldr1 is a variant of foldr that has no starting value -- argument, and thus must be applied to non-empty ByteStrings An -- exception will be thrown in the case of an empty ByteString. foldr1 :: (Word8 -> Word8 -> Word8) -> ByteString -> Word8 -- | foldl1' is like foldl1, but strict in the accumulator. -- An exception will be thrown in the case of an empty ByteString. foldl1' :: (Word8 -> Word8 -> Word8) -> ByteString -> Word8 -- | foldl1 is a variant of foldl that has no starting value -- argument, and thus must be applied to non-empty ByteStrings. -- An exception will be thrown in the case of an empty ByteString. foldl1 :: (Word8 -> Word8 -> Word8) -> ByteString -> Word8 -- | foldr' is like foldr, but strict in the accumulator. foldr' :: (Word8 -> a -> a) -> a -> ByteString -> a -- | foldr, applied to a binary operator, a starting value -- (typically the right-identity of the operator), and a ByteString, -- reduces the ByteString using the binary operator, from right to left. foldr :: (Word8 -> a -> a) -> a -> ByteString -> a -- | foldl' is like foldl, but strict in the accumulator. foldl' :: (a -> Word8 -> a) -> a -> ByteString -> a -- | foldl, applied to a binary operator, a starting value -- (typically the left-identity of the operator), and a ByteString, -- reduces the ByteString using the binary operator, from left to right. foldl :: (a -> Word8 -> a) -> a -> ByteString -> a -- | The transpose function transposes the rows and columns of its -- ByteString argument. transpose :: [ByteString] -> [ByteString] -- | O(n) The intersperse function takes a Word8 and a -- ByteString and `intersperses' that byte between the elements of -- the ByteString. It is analogous to the intersperse function on -- Lists. intersperse :: Word8 -> ByteString -> ByteString -- | O(n) reverse xs efficiently returns the -- elements of xs in reverse order. reverse :: ByteString -> ByteString -- | O(n) map f xs is the ByteString obtained by -- applying f to each element of xs. map :: (Word8 -> Word8) -> ByteString -> ByteString -- | O(n) Append two ByteStrings append :: ByteString -> ByteString -> ByteString -- | O(1) Extract the init and last of a ByteString, -- returning Nothing if it is empty. unsnoc :: ByteString -> Maybe (ByteString, Word8) -- | O(1) Return all the elements of a ByteString except the -- last one. An exception will be thrown in the case of an empty -- ByteString. init :: ByteString -> ByteString -- | O(1) Extract the last element of a ByteString, which must be -- finite and non-empty. An exception will be thrown in the case of an -- empty ByteString. last :: ByteString -> Word8 -- | O(1) Extract the head and tail of a ByteString, returning -- Nothing if it is empty. uncons :: ByteString -> Maybe (Word8, ByteString) -- | O(1) Extract the elements after the head of a ByteString, which -- must be non-empty. An exception will be thrown in the case of an empty -- ByteString. tail :: ByteString -> ByteString -- | O(1) Extract the first element of a ByteString, which must be -- non-empty. An exception will be thrown in the case of an empty -- ByteString. head :: ByteString -> Word8 -- | O(n) Append a byte to the end of a ByteString snoc :: ByteString -> Word8 -> ByteString infixl 5 `snoc` -- | O(n) cons is analogous to (:) for lists, but of -- different complexity, as it requires making a copy. cons :: Word8 -> ByteString -> ByteString infixr 5 `cons` -- | O(1) length returns the length of a ByteString as an -- Int. length :: ByteString -> Int -- | O(1) Test whether a ByteString is empty. null :: ByteString -> Bool -- | O(n) Converts a ByteString to a [Word8]. unpack :: ByteString -> [Word8] -- | O(n) Convert a [Word8] into a -- ByteString. -- -- For applications with large numbers of string literals, pack -- can be a bottleneck. In such cases, consider using -- unsafePackAddress (GHC only). pack :: [Word8] -> ByteString -- | O(1) Convert a Word8 into a ByteString singleton :: Word8 -> ByteString -- | O(1) The empty ByteString empty :: ByteString -- | A space-efficient representation of a Word8 vector, supporting -- many efficient operations. -- -- A ByteString contains 8-bit bytes, or by using the operations -- from Data.ByteString.Char8 it can be interpreted as containing -- 8-bit characters. data ByteString -- | 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 -- | 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.Process, a small part of the Haskell -- community's effort to replace 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. -- --

Fast and Brief Example

-- -- If you have experience with Unix pipes, this example should be pretty -- straightforward. In fact it is so simple that you don't need any type -- theory or PL knowledge. It demonstrates how you can create a child -- process and interact with it. -- -- 
--   {-# language OverloadedStrings #-}
--   
--   import RawFilePath.Process
--   import System.IO
--   import qualified Data.ByteString as B
--   
--   
--   main :: IO ()
--   main = do
--     p <- startProcess $ proc "sed" ["-e", "s/\\>/!/g"]
--       `setStdin` CreatePipe
--       `setStdout` CreatePipe
--     B.hPut (processStdin p) "Lorem ipsum dolor sit amet"
--     hClose (processStdin p)
--     result <- B.hGetContents (processStdout p)
--     print result
--     -- "Lorem! ipsum! dolor! sit! amet!"
--
-- -- That's it! You can totally skip the verbose explanation below. -- --

Verbose Explanation of the Example

-- -- We launch sed as a child process. As we know, it is a regular -- expression search and replacement tool. In the example, sed -- is a simple Unix pipe utility: Take some text from stdin and -- output the processed text to stdout. -- -- In sed regex, \> means "the end of the word." So, -- "s/\\>/!/g" means "substitute all ends of the words with -- an exclamation mark." Then, we feed some text to its stdin, -- close stdin (to send EOF to sed EOF), and read what -- it said to stdout. -- -- The interesting part is proc. It is a simple function that -- takes a command and its arguments and returns a ProcessConf -- which defines the properties of the child process you want to create. -- You can use functions like setStdin or setStdout to -- change those properties. -- -- The advantage of this interface is type safety. Take stdout -- for example. There are four options: Inherit, -- UseHandle, CreatePipe, and NoStream. If you -- want to read stdout of the child process, you must set it to -- CreatePipe. With the process package, this is done -- by giving a proper argument to createProcess. The trouble is, -- regardless of the argument, createProcess returns -- Maybe Handle as stdout. You may or may not get -- a Handle. -- -- This is not what we want with Haskell. We want to ensure that (1) we -- use CreatePipe and certainly get the stdout -- Handle without the fear of Nothing, and (2) if we don't -- use CreatePipe but still request the stdout -- Handle, it is an error, detected at compile time. -- -- So that's what RawFilePath.Process does. In the above -- example, we use functions like setStdout. Later, you use the -- processStdout family of functions to get the process's standard -- stream handles. This requires that the process was created with -- CreatePipe appropriately set for that stream. -- -- It sounds all complicated, but all you really need to do is as simple -- as: -- -- 
--   startProcess $ proc "..." [...] `setStdout` CreatePipe
--
-- -- ... If you want to create a new pipe for the child process's -- stdin. Then you can later use processStdout to get the -- Handle. If you don't put the `setStdout` CreatePipe -- part or set it to something other than CreatePipe, it will be -- a compile-time error to use processStdout on this process -- object. -- -- In short, it makes the correct code easy and the wrong code -- impossible. This approach was inspired by the typed-process -- package. Then why not just typed-process? -- rawfilepath offers -- --
    --
  1. RawFilePath!
    2. --
  2. A lot less dependency (only three packages)
    3. --
  3. A lot more portability (doesn't require any language -- extension).
    4. --
-- -- Enjoy. 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 -- | 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) -- | 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: -- -- -- -- FilePath is a type synonym of String. This is a bigger -- problem than what String already has, because it's not just a -- performance issue anymore; it's a correctness issue as there is no -- encoding information. -- -- A syscall would give you (or expect from you) a series of bytes, but -- String is a series of characters. But how do you know the -- system's encoding? NTFS is UTF-16, and FAT32 uses the OEM character -- set. On Linux, there is no filesystem-level encoding. Would Haskell -- somehow magically figure out the system's encoding information and -- encode/decode accordingly? Well, there is no magic. FilePath -- has completely no guarantee of correct behavior at all, especially -- when there are non-ASCII letters. -- -- With this library, you use RawFilePath which is a sequence of -- bytes (instead of characters). You have the full control of decoding -- from (or encoding to) these bytes. This lets you do the job properly. -- --

Usage

-- -- This is the top-level module that re-exports the sub-modules. -- Therefore, you can -- -- 
--   import RawFilePath
--
-- -- to import all functions. For documentation, see: -- -- -- -- For process-related functions, see RawFilePath.Process for a -- brief introduction and an example code. module RawFilePath -- | 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 either a -- directory or a symbolic link to a directory, and False -- otherwise. doesDirectoryExist :: RawFilePath -> IO Bool -- | Return True if the argument file exists and is not a directory, -- and False otherwise. doesFileExist :: 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 () -- | 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 -- | Use the supplied Handle. data UseHandle UseHandle :: Handle -> UseHandle -- | 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 -- | 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 -- | Create a new pipe for the stream. You get a new Handle. data CreatePipe CreatePipe :: CreatePipe -- | The process type. The three type variables denote how its standard -- streams were initialized. data Process stdin stdout stderr -- | 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 -- | 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` -- | 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 -- | 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) -- | Stop a sub-process. For now it simply calls terminateProcess -- and then waitForProcess. stopProcess :: Process stdin stdout stderr -> IO ExitCode -- | Wait (block) for a sub-process to exit and obtain its exit code. waitForProcess :: Process stdin stdout stderr -> IO ExitCode -- | Terminate a sub-process by sending SIGTERM to it. terminateProcess :: Process stdin stdout stderr -> IO () -- | 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) -- | A literal POSIX file path type RawFilePath = ByteString