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


-- | High-level, byte-based file and directory path manipulations
--   
--   High-level, byte-based file and directory path manipulations
@package system-filepath
@version 0.4.6


-- | High‐level, byte‐based file and directory path manipulations. You
--   probably want to import <a>Filesystem.Path.CurrentOS</a> instead,
--   since it handles detecting which rules to use in the current
--   compilation.
module Filesystem.Path
data FilePath

-- | A file path with no root, directory, or filename
empty :: FilePath

-- | <pre>
--   null p = (p == <a>empty</a>)
--   </pre>
null :: FilePath -> Bool

-- | Retrieves the <a>FilePath</a>’s root.
root :: FilePath -> FilePath

-- | Retrieves the <a>FilePath</a>’s directory. If the path is already a
--   directory, it is returned unchanged.
directory :: FilePath -> FilePath

-- | Retrieves the <a>FilePath</a>’s parent directory.
parent :: FilePath -> FilePath

-- | Retrieve a <a>FilePath</a>’s filename component.
--   
--   <pre>
--   filename "foo/bar.txt" == "bar.txt"
--   </pre>
filename :: FilePath -> FilePath

-- | Retrieve a <a>FilePath</a>’s directory name. This is only the <i>file
--   name</i> of the directory, not its full path.
--   
--   <pre>
--   dirname "foo/bar/baz.txt" == "bar"
--   dirname "/" == ""
--   </pre>
--   
--   Since: 0.4.1
dirname :: FilePath -> FilePath

-- | Retrieve a <a>FilePath</a>’s basename component.
--   
--   <pre>
--   basename "foo/bar.txt" == "bar"
--   </pre>
basename :: FilePath -> FilePath

-- | Test whether a path is absolute.
absolute :: FilePath -> Bool

-- | Test whether a path is relative.
relative :: FilePath -> Bool

-- | Appends two <a>FilePath</a>s. If the second path is absolute, it is
--   returned unchanged.
append :: FilePath -> FilePath -> FilePath

-- | An alias for <a>append</a>.
(</>) :: FilePath -> FilePath -> FilePath

-- | A fold over <a>append</a>.
concat :: [FilePath] -> FilePath

-- | Find the greatest common prefix between a list of <a>FilePath</a>s.
commonPrefix :: [FilePath] -> FilePath
stripPrefix :: FilePath -> FilePath -> Maybe FilePath

-- | Remove <tt>"."</tt> and <tt>".."</tt> directories from a path.
--   
--   Note that if any of the elements are symbolic links, <a>collapse</a>
--   may change which file the path resolves to.
--   
--   Since: 0.2
collapse :: FilePath -> FilePath

-- | Get a <a>FilePath</a>’s last extension, or <a>Nothing</a> if it has no
--   extensions.
extension :: FilePath -> Maybe Text

-- | Get a <a>FilePath</a>’s full extension list.
extensions :: FilePath -> [Text]

-- | Get whether a <a>FilePath</a>’s last extension is the predicate.
hasExtension :: FilePath -> Text -> Bool

-- | Append an extension to the end of a <a>FilePath</a>.
addExtension :: FilePath -> Text -> FilePath

-- | An alias for <a>addExtension</a>.
(<.>) :: FilePath -> Text -> FilePath

-- | Remove a <a>FilePath</a>’s last extension.
dropExtension :: FilePath -> FilePath

-- | Replace a <a>FilePath</a>’s last extension.
replaceExtension :: FilePath -> Text -> FilePath

-- | Append many extensions to the end of a <a>FilePath</a>.
addExtensions :: FilePath -> [Text] -> FilePath

-- | Remove all extensions from a <a>FilePath</a>.
dropExtensions :: FilePath -> FilePath

-- | Remove all extensions from a <a>FilePath</a>, and replace them with a
--   new list.
replaceExtensions :: FilePath -> [Text] -> FilePath

-- | <pre>
--   splitExtension p = (<a>dropExtension</a> p, <a>extension</a> p)
--   </pre>
splitExtension :: FilePath -> (FilePath, Maybe Text)

-- | <pre>
--   splitExtensions p = (<a>dropExtensions</a> p, <a>extensions</a> p)
--   </pre>
splitExtensions :: FilePath -> (FilePath, [Text])
instance Monoid FilePath


module Filesystem.Path.Rules
data Rules platformFormat

-- | Linux, BSD, and other UNIX or UNIX-like operating systems.
posix :: Rules ByteString

-- | Linux, BSD, and other UNIX or UNIX-like operating systems.
--   
--   This is a variant of <a>posix</a> for use with GHC 7.2, which tries to
--   decode file paths in its IO computations.
--   
--   Since: 0.3.3 / 0.4.2
posix_ghc702 :: Rules ByteString

-- | Linux, BSD, and other UNIX or UNIX-like operating systems.
--   
--   This is a variant of <a>posix</a> for use with GHC 7.4 or later, which
--   tries to decode file paths in its IO computations.
--   
--   Since: 0.3.7 / 0.4.6
posix_ghc704 :: Rules ByteString

-- | Windows and DOS
windows :: Rules Text

-- | Darwin and Mac OS X.
--   
--   This is almost identical to <a>posix</a>, but with a native path type
--   of <a>Text</a> rather than <a>ByteString</a>.
--   
--   Since: 0.3.4 / 0.4.3
darwin :: Rules Text

-- | Darwin and Mac OS X.
--   
--   This is a variant of <a>darwin</a> for use with GHC 7.2 or later,
--   which tries to decode file paths in its IO computations.
--   
--   Since: 0.3.4 / 0.4.3
darwin_ghc702 :: Rules Text

-- | Attempt to convert a <a>FilePath</a> to human‐readable text.
--   
--   If the path is decoded successfully, the result is a <a>Right</a>
--   containing the decoded text. Successfully decoded text can be
--   converted back to the original path using <a>fromText</a>.
--   
--   If the path cannot be decoded, the result is a <a>Left</a> containing
--   an approximation of the original path. If displayed to the user, this
--   value should be accompanied by some warning that the path has an
--   invalid encoding. Approximated text cannot be converted back to the
--   original path.
--   
--   This function ignores the user’s locale, and assumes all file paths
--   are encoded in UTF8. If you need to display file paths with an unusual
--   or obscure encoding, use <a>encode</a> and then decode them manually.
--   
--   Since: 0.2
toText :: Rules platformFormat -> FilePath -> Either Text Text

-- | Convert human‐readable text into a <a>FilePath</a>.
--   
--   This function ignores the user’s locale, and assumes all file paths
--   are encoded in UTF8. If you need to create file paths with an unusual
--   or obscure encoding, encode them manually and then use <a>decode</a>.
--   
--   Since: 0.2
fromText :: Rules platformFormat -> Text -> FilePath

-- | Convert a <a>FilePath</a> to a platform‐specific format, suitable for
--   use with external OS functions.
--   
--   Since: 0.3
encode :: Rules platformFormat -> FilePath -> platformFormat

-- | Convert a <a>FilePath</a> from a platform‐specific format, suitable
--   for use with external OS functions.
--   
--   Since: 0.3
decode :: Rules platformFormat -> platformFormat -> FilePath

-- | Attempt to convert a <a>FilePath</a> to a string suitable for use with
--   functions in <tt>System.IO</tt>. The contents of this string are
--   platform‐dependent, and are not guaranteed to be human‐readable. For
--   converting <a>FilePath</a>s to a human‐readable format, use
--   <a>toText</a>.
--   
--   Since: 0.3.1
encodeString :: Rules platformFormat -> FilePath -> String

-- | Attempt to parse a <a>FilePath</a> from a string suitable for use with
--   functions in <tt>System.IO</tt>. Do not use this function for parsing
--   human‐readable paths, as the character set decoding is
--   platform‐dependent. For converting human‐readable text to a
--   <a>FilePath</a>, use <a>fromText</a>.
--   
--   Since: 0.3.1
decodeString :: Rules platformFormat -> String -> FilePath

-- | Check if a <a>FilePath</a> is valid; it must not contain any illegal
--   characters, and must have a root appropriate to the current
--   <a>Rules</a>.
valid :: Rules platformFormat -> FilePath -> Bool

-- | Split a search path, such as <tt>$PATH</tt> or <tt>$PYTHONPATH</tt>,
--   into a list of <a>FilePath</a>s.
splitSearchPath :: Rules platformFormat -> platformFormat -> [FilePath]


-- | Re‐exports contents of <a>Filesystem.Path.Rules</a>, defaulting to the
--   current OS’s rules when needed.
--   
--   Also enables <a>Show</a> and <a>IsString</a> instances for
--   <a>FilePath</a>.
module Filesystem.Path.CurrentOS
currentOS :: Rules ByteString

-- | Attempt to convert a <a>FilePath</a> to human‐readable text.
--   
--   If the path is decoded successfully, the result is a <a>Right</a>
--   containing the decoded text. Successfully decoded text can be
--   converted back to the original path using <a>fromText</a>.
--   
--   If the path cannot be decoded, the result is a <a>Left</a> containing
--   an approximation of the original path. If displayed to the user, this
--   value should be accompanied by some warning that the path has an
--   invalid encoding. Approximated text cannot be converted back to the
--   original path.
--   
--   This function ignores the user’s locale, and assumes all file paths
--   are encoded in UTF8. If you need to display file paths with an unusual
--   or obscure encoding, use <a>encode</a> and then decode them manually.
--   
--   Since: 0.2
toText :: FilePath -> Either Text Text

-- | Convert human‐readable text into a <a>FilePath</a>.
--   
--   This function ignores the user’s locale, and assumes all file paths
--   are encoded in UTF8. If you need to create file paths with an unusual
--   or obscure encoding, encode them manually and then use <a>decode</a>.
--   
--   Since: 0.2
fromText :: Text -> FilePath

-- | Convert a <a>FilePath</a> to a platform‐specific format, suitable for
--   use with external OS functions.
--   
--   Since: 0.3
encode :: FilePath -> ByteString

-- | Convert a <a>FilePath</a> from a platform‐specific format, suitable
--   for use with external OS functions.
--   
--   Since: 0.3
decode :: ByteString -> FilePath

-- | Attempt to convert a <a>FilePath</a> to a string suitable for use with
--   functions in <tt>System.IO</tt>. The contents of this string are
--   platform‐dependent, and are not guaranteed to be human‐readable. For
--   converting <a>FilePath</a>s to a human‐readable format, use
--   <a>toText</a>.
--   
--   Since: 0.3.1
encodeString :: FilePath -> String

-- | Attempt to parse a <a>FilePath</a> from a string suitable for use with
--   functions in <tt>System.IO</tt>. Do not use this function for parsing
--   human‐readable paths, as the character set decoding is
--   platform‐dependent. For converting human‐readable text to a
--   <a>FilePath</a>, use <a>fromText</a>.
--   
--   Since: 0.3.1
decodeString :: String -> FilePath

-- | Check if a <a>FilePath</a> is valid; it must not contain any illegal
--   characters, and must have a root appropriate to the current
--   <a>Rules</a>.
valid :: FilePath -> Bool

-- | Split a search path, such as <tt>$PATH</tt> or <tt>$PYTHONPATH</tt>,
--   into a list of <a>FilePath</a>s.
splitSearchPath :: ByteString -> [FilePath]
instance Show FilePath
instance IsString FilePath