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

-- | Use Template Haskell to embed file contents directly.
--   
--   Use Template Haskell to read a file or all the files in a directory,
--   and turn them into (path, bytestring) pairs embedded in your Haskell
--   code.
@package file-embed
@version 0.0.16.0

-- | This module uses template Haskell. Following is a simplified
--   explanation of usage for those unfamiliar with calling Template
--   Haskell functions.
--   
--   The function embedFile in this modules embeds a file into the
--   executable that you can use it at runtime. A file is represented as a
--   ByteString. However, as you can see below, the type signature
--   indicates a value of type Q Exp will be returned. In order to
--   convert this into a ByteString, you must use Template Haskell
--   syntax, e.g.:
--   
--   
--   $(embedFile "myfile.txt")
--   
--   
--   This expression will have type ByteString. Be certain to
--   enable the TemplateHaskell language extension, usually by adding the
--   following to the top of your module:
--   
--   
--   {-# LANGUAGE TemplateHaskell #-}
--   
module Data.FileEmbed

-- | Embed a single file in your source code.
--   
--   
--   import qualified Data.ByteString
--   
--   myFile :: Data.ByteString.ByteString
--   myFile = $(embedFile "dirName/fileName")
--   
embedFile :: FilePath -> Q Exp

-- | Embed a single file in your source code. Unlike embedFile, path
--   is given relative to project root. @since 0.0.16.0
embedFileRelative :: FilePath -> Q Exp

-- | Maybe embed a single file in your source code depending on whether or
--   not file exists.
--   
--   Warning: When a build is compiled with the file missing, a recompile
--   when the file exists might not trigger an embed of the file. You might
--   try to fix this by doing a clean build.
--   
--   
--   import qualified Data.ByteString
--   
--   maybeMyFile :: Maybe Data.ByteString.ByteString
--   maybeMyFile = $(embedFileIfExists "dirName/fileName")
--   
embedFileIfExists :: FilePath -> Q Exp

-- | Embed a single existing file in your source code out of list a list of
--   paths supplied.
--   
--   
--   import qualified Data.ByteString
--   
--   myFile :: Data.ByteString.ByteString
--   myFile = $(embedOneFileOf [ "dirName/fileName", "src/dirName/fileName" ])
--   
embedOneFileOf :: [FilePath] -> Q Exp

-- | Embed a directory recursively in your source code.
--   
--   
--   import qualified Data.ByteString
--   
--   myDir :: [(FilePath, Data.ByteString.ByteString)]
--   myDir = $(embedDir "dirName")
--   
embedDir :: FilePath -> Q Exp

-- | Embed a directory listing recursively in your source code.
--   
--   
--   myFiles :: [FilePath]
--   myFiles = $(embedDirListing "dirName")
--   
embedDirListing :: FilePath -> Q Exp

-- | Get a directory tree in the IO monad.
--   
--   This is the workhorse of embedDir
getDir :: FilePath -> IO [(FilePath, ByteString)]

-- | Embed a single file in your source code.
--   
--   
--   import Data.String
--   
--   myFile :: IsString a => a
--   myFile = $(embedStringFile "dirName/fileName")
--   
--   
--   Since 0.0.9
embedStringFile :: FilePath -> Q Exp

-- | Embed a single existing string file in your source code out of list a
--   list of paths supplied.
--   
--   Since 0.0.9
embedOneStringFileOf :: [FilePath] -> Q Exp

-- | Allocate the given number of bytes in the generate executable. That
--   space can be filled up with the inject and injectFile
--   functions.
dummySpace :: Int -> Q Exp

-- | Like dummySpace, but takes a postfix for the magic string. In
--   order for this to work, the same postfix must be used by inject
--   / injectFile. This allows an executable to have multiple
--   ByteStrings injected into it, without encountering
--   collisions.
--   
--   Since 0.0.8
dummySpaceWith :: ByteString -> Int -> Q Exp

-- | Inject some raw data inside a ByteString containing empty,
--   dummy space (allocated with dummySpace). Typically, the
--   original ByteString is an executable read from the
--   filesystem.
inject :: ByteString -> ByteString -> Maybe ByteString

-- | Same as inject, but instead of performing the injecting in
--   memory, read the contents from the filesystem and write back to a
--   different file on the filesystem.
injectFile :: ByteString -> FilePath -> FilePath -> IO ()

-- | Like inject, but takes a postfix for the magic string.
--   
--   Since 0.0.8
injectWith :: ByteString -> ByteString -> ByteString -> Maybe ByteString

-- | Like injectFile, but takes a postfix for the magic string.
--   
--   Since 0.0.8
injectFileWith :: ByteString -> ByteString -> FilePath -> FilePath -> IO ()

-- | Take a relative file path and attach it to the root of the current
--   project.
--   
--   The idea here is that, when building with Stack, the build will always
--   be executed with a current working directory of the root of the
--   project (where your .cabal file is located). However, if you load up
--   multiple projects with stack ghci, the working directory may
--   be something else entirely.
--   
--   This function looks at the source location of the Haskell file calling
--   it, finds the first parent directory with a .cabal file, and uses that
--   as the root directory for fixing the relative path.
--   
--   
--   $(makeRelativeToProject "data/foo.txt" >>= embedFile)
--   
makeRelativeToProject :: FilePath -> Q FilePath

-- | Take a predicate to infer the project root and a relative file path,
--   the given file path is then attached to the inferred project root
--   
--   This function looks at the source location of the Haskell file calling
--   it, finds the first parent directory with a file matching the given
--   predicate, and uses that as the root directory for fixing the relative
--   path.
--   
--   
--   $(makeRelativeToLocationPredicate ((==) ".cabal" . takeExtension) "data/foo.txt" >>= embedFile)
--   
makeRelativeToLocationPredicate :: (FilePath -> Bool) -> FilePath -> Q FilePath
stringToBs :: String -> ByteString
bsToExp :: ByteString -> Q Exp
strToExp :: String -> Q Exp
