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


-- | Type-safe replacement for System.FilePath etc
--   
--   This module provides type-safe access to filepath manipulations.
--   
--   It is designed to be imported instead of <a>System.FilePath</a> and
--   <a>System.Directory</a> and is intended to provide versions of
--   functions from those modules which have equivalent functionality but
--   are more typesafe.
--   
--   The heart of this module is the <tt>Path ar fd</tt> abstract type
--   which represents file and directory paths. The idea is that there are
--   two phantom type parameters - the first should be <a>Abs</a> or
--   <a>Rel</a>, and the second <a>File</a> or <a>Dir</a>. A number of type
--   synonyms are provided for common types:
--   
--   <pre>
--   type AbsFile    = Path Abs File
--   type RelFile    = Path Rel File
--   type AbsDir     = Path Abs Dir
--   type RelDir     = Path Rel Dir
--   type RelPath fd = Path Rel fd
--   type DirPath ar = Path ar Dir
--   </pre>
--   
--   The type of the <a>combine</a> (aka <a>&lt;/&gt;</a>) function gives
--   the idea:
--   
--   <pre>
--   (&lt;/&gt;) :: DirPath ar -&gt; RelPath fd -&gt; Path ar fd
--   </pre>
--   
--   Together this enables us to give more meaningful types to a lot of the
--   functions, and (hopefully) catch a bunch more errors at compile time.
--   
--   The basic API (and properties satisfied) are heavily influenced by
--   Neil Mitchell's <a>System.FilePath</a> module.
--   
--   WARNING -- THE API IS NOT YET STABLE -- WARNING
@package pathtype
@version 0.0.1


-- | This module provides type-safe access to filepath manipulations.
--   
--   It is designed to be imported instead of <tt>System.FilePath</tt> and
--   <tt>System.Directory</tt>. (It is intended to provide versions of
--   functions from those modules which have equivalent functionality but
--   are more typesafe).
--   
--   The heart of this module is the <tt>Path ar fd</tt> abstract type
--   which represents file and directory paths. The idea is that there are
--   two phantom type parameters - the first should be <a>Abs</a> or
--   <a>Rel</a>, and the second <a>File</a> or <a>Dir</a>. A number of type
--   synonyms are provided for common types:
--   
--   <pre>
--   type AbsFile    = Path Abs File
--   type RelFile    = Path Rel File
--   type AbsDir     = Path Abs Dir
--   type RelDir     = Path Rel Dir
--   type RelPath fd = Path Rel fd
--   type DirPath ar = Path ar Dir
--   </pre>
--   
--   The type of the <a>combine</a> (aka <a>&lt;/&gt;</a>) function gives
--   the idea:
--   
--   <pre>
--   (&lt;/&gt;) :: DirPath ar -&gt; RelPath fd -&gt; Path ar fd
--   </pre>
--   
--   Together this enables us to give more meaningful types to a lot of the
--   functions, and (hopefully) catch a bunch more errors at compile time.
--   
--   The basic API (and properties satisfied) are heavily influenced by
--   Neil Mitchell's <tt>System.FilePath</tt> module.
--   
--   WARNING --- THE API IS NOT YET STABLE --- WARNING
--   
--   Ben Moseley - (c) Jan 2009
module System.Path

-- | This is the main filepath abstract datatype
data Path ar fd
data Abs
data Rel
data File
data Dir
type AbsFile = Path Abs File
type RelFile = Path Rel File
type AbsDir = Path Abs Dir
type RelDir = Path Rel Dir
type AbsPath fd = Path Abs fd
type RelPath fd = Path Rel fd
type FilePath ar = Path ar File
type DirPath ar = Path ar Dir

-- | Convert the <a>Path</a> into a plain <a>String</a>. This is simply an
--   alias for <a>show</a>.
getPathString :: (AbsRelClass ar) => Path ar fd -> String
rootDir :: AbsDir
currentDir :: RelDir

-- | Convert a <a>String</a> into a <a>Path</a> whose type is determined by
--   its context.
mkPath :: String -> Path ar fd
mkRelFile :: String -> RelFile
mkRelDir :: String -> RelDir
mkAbsFile :: String -> AbsFile
mkAbsDir :: String -> AbsDir
mkRelPath :: String -> RelPath fd
mkAbsPath :: String -> AbsPath fd
mkFile :: String -> FilePath ar
mkDir :: String -> DirPath ar

-- | Examines the supplied string and constructs an absolute or relative
--   path as appropriate.
mkPathAbsOrRel :: String -> Either (AbsPath fd) (RelPath fd)

-- | Searches for a file or directory with the supplied path string and
--   returns a <a>File</a> or <a>Dir</a> path as appropriate. If neither
--   exists at the supplied path, <a>Nothing</a> is returned.
mkPathFileOrDir :: (AbsRelClass ar) => String -> IO (Maybe (Either (FilePath ar) (DirPath ar)))

-- | Join an (absolute or relative) directory path with a relative (file or
--   directory) path to form a new path.
(</>) :: DirPath ar -> RelPath fd -> Path ar fd

-- | We only allow files (and not directories) to have extensions added by
--   this function. This is because it's the vastly common case and an
--   attempt to add one to a directory will - more often than not -
--   represent an error. We don't however want to prevent the corresponding
--   operation on directories, and so we provide a function that is more
--   flexible: <a>addFileOrDirExtension</a>.
(<.>) :: FilePath ar -> String -> FilePath ar

-- | Add an extension, even if there is already one there. E.g.
--   <tt>addExtension "foo.txt" "bat" -&gt; "foo.txt.bat"</tt>.
--   
--   <pre>
--   &gt; addExtension (mkFile "file.txt") "bib" == (mkFile "file.txt.bib")
--   &gt; addExtension (mkFile "file.") ".bib" == (mkFile "file..bib")
--   &gt; addExtension (mkFile "file") ".bib" == (mkFile "file.bib")
--   &gt; takeFileName (addExtension (mkFile "") "ext") == mkFile ".ext"
--    Windows: addExtension "\\\\share" ".txt" == "\\\\share\\.txt"
--   </pre>
addExtension :: FilePath ar -> String -> FilePath ar

-- | Join an (absolute or relative) directory path with a relative (file or
--   directory) path to form a new path.
combine :: DirPath ar -> RelPath fd -> Path ar fd

-- | Remove last extension, and the "." preceding it.
--   
--   <pre>
--   &gt; dropExtension x == fst (splitExtension x)
--   </pre>
dropExtension :: FilePath ar -> FilePath ar

-- | Drop all extensions
--   
--   <pre>
--   &gt; not $ hasExtension (dropExtensions x)
--   </pre>
dropExtensions :: FilePath ar -> FilePath ar
dropFileName :: Path ar fd -> DirPath ar

-- | Set the extension of a file, overwriting one if already present.
--   
--   <pre>
--   &gt; replaceExtension (mkFile "file.txt") ".bob" == (mkFile "file.bob")
--   &gt; replaceExtension (mkFile "file.txt") "bob" == (mkFile "file.bob")
--   &gt; replaceExtension (mkFile "file") ".bob" == (mkFile "file.bob")
--   &gt; replaceExtension (mkFile "file.txt") "" == (mkFile "file")
--   &gt; replaceExtension (mkFile "file.fred.bob") "txt" == (mkFile "file.fred.txt")
--   </pre>
replaceExtension :: FilePath ar -> String -> FilePath ar
replaceBaseName :: Path ar fd -> String -> Path ar fd
replaceDirectory :: Path ar1 fd -> DirPath ar2 -> Path ar2 fd
replaceFileName :: Path ar fd -> String -> Path ar fd

-- | Split on the extension. <a>addExtension</a> is the inverse.
--   
--   <pre>
--   &gt; uncurry (&lt;.&gt;) (splitExtension x) == x
--   &gt; uncurry addExtension (splitExtension x) == x
--   &gt; splitExtension (mkFile "file.txt") == (mkFile "file",".txt")
--   &gt; splitExtension (mkFile "file") == (mkFile "file","")
--   &gt; splitExtension (mkFile "file/file.txt") == (mkFile "file/file",".txt")
--   &gt; splitExtension (mkFile "file.txt/boris") == (mkFile "file.txt/boris","")
--   &gt; splitExtension (mkFile "file.txt/boris.ext") == (mkFile "file.txt/boris",".ext")
--   &gt; splitExtension (mkFile "file/path.txt.bob.fred") == (mkFile "file/path.txt.bob",".fred")
--   </pre>
splitExtension :: FilePath ar -> (FilePath ar, String)

-- | Split on all extensions
--   
--   <pre>
--   &gt; splitExtensions (mkFile "file.tar.gz") == (mkFile "file",".tar.gz")
--   </pre>
splitExtensions :: FilePath ar -> (FilePath ar, String)
splitFileName :: Path ar fd -> (DirPath ar, RelPath fd)
takeBaseName :: Path ar fd -> RelPath fd
takeDirectory :: Path ar fd -> DirPath ar

-- | Get the extension of a file, returns <tt>""</tt> for no extension,
--   <tt>.ext</tt> otherwise.
--   
--   <pre>
--   &gt; takeExtension x == snd (splitExtension x)
--   &gt; takeExtension (addExtension x "ext") == ".ext"
--   &gt; takeExtension (replaceExtension x "ext") == ".ext"
--   </pre>
takeExtension :: FilePath ar -> String

-- | Get all extensions
--   
--   <pre>
--   &gt; takeExtensions (mkFile "file.tar.gz") == ".tar.gz"
--   </pre>
takeExtensions :: FilePath ar -> String
takeFileName :: Path ar fd -> RelPath fd
equalFilePath :: String -> String -> Bool

-- | Constructs a <a>Path</a> from a list of components.
joinPath :: [String] -> Path ar fd

-- | Currently just transforms:
--   
--   <pre>
--   &gt; normalise (mkFile "/tmp/fred/./jim/./file") == mkFile "/tmp/fred/jim/file"
--   </pre>
normalise :: Path ar fd -> Path ar fd
splitDirectories :: Path ar fd -> [String]
splitPath :: Path ar fd -> [String]
makeRelative :: AbsDir -> AbsPath fd -> RelPath fd
isAbsolute :: (AbsRelClass ar) => Path ar fd -> Bool
isAbsoluteString :: String -> Bool

-- | Invariant - this should return True iff arg is of type <tt>Path Rel
--   _</tt>
isRelative :: (AbsRelClass ar) => Path ar fd -> Bool
isRelativeString :: String -> Bool

-- | Does the given filename have an extension?
--   
--   <pre>
--   &gt; null (takeExtension x) == not (hasExtension x)
--   </pre>
hasExtension :: FilePath ar -> Bool

-- | This is largely for <tt>System.FilePath</tt> compatability
addTrailingPathSeparator :: String -> String

-- | This is largely for <tt>System.FilePath</tt> compatability
dropTrailingPathSeparator :: String -> String

-- | File extension character
--   
--   <pre>
--   &gt; extSeparator == '.'
--   </pre>
extSeparator :: Char

-- | This is largely for <tt>System.FilePath</tt> compatability
hasTrailingPathSeparator :: String -> Bool

-- | The character that separates directories. In the case where more than
--   one character is possible, <a>pathSeparator</a> is the 'ideal' one.
--   
--   <pre>
--    Windows: pathSeparator == '\\'
--    Posix:   pathSeparator ==  '/'
--   &gt; isPathSeparator pathSeparator
--   </pre>
pathSeparator :: Char

-- | The list of all possible separators.
--   
--   <pre>
--    Windows: pathSeparators == ['\\', '/']
--    Posix:   pathSeparators == ['/']
--   &gt; pathSeparator `elem` pathSeparators
--   </pre>
pathSeparators :: [Char]

-- | The character that is used to separate the entries in the $PATH
--   environment variable.
--   
--   <pre>
--   Windows: searchPathSeparator == ';'
--   Posix:   searchPathSeparator == ':'
--   </pre>
searchPathSeparator :: Char

-- | Is the character an extension character?
--   
--   <pre>
--   &gt; isExtSeparator a == (a == extSeparator)
--   </pre>
isExtSeparator :: Char -> Bool

-- | Rather than using <tt>(== <a>pathSeparator</a>)</tt>, use this. Test
--   if something is a path separator.
--   
--   <pre>
--   &gt; isPathSeparator a == (a `elem` pathSeparators)
--   </pre>
isPathSeparator :: Char -> Bool

-- | Is the character a file separator?
--   
--   <pre>
--   &gt; isSearchPathSeparator a == (a == searchPathSeparator)
--   </pre>
isSearchPathSeparator :: Char -> Bool

-- | This is a more flexible variant of <a>addExtension</a> /
--   <tt><a>.</a></tt> which can work with files or directories
--   
--   <pre>
--   &gt; addFileOrDirExtension (mkFile "/") "x" == (mkFile "/.x")
--   </pre>
addFileOrDirExtension :: Path ar fd -> String -> Path ar fd
dropFileOrDirExtension :: Path ar fd -> Path ar fd
dropFileOrDirExtensions :: Path ar fd -> Path ar fd
splitFileOrDirExtension :: Path ar fd -> (Path ar fd, String)
splitFileOrDirExtensions :: Path ar fd -> (Path ar fd, String)
takeFileOrDirExtension :: Path ar fd -> String
takeFileOrDirExtensions :: Path ar fd -> String
getDirectoryContents :: (AbsRelClass ar) => DirPath ar -> IO ([AbsDir], [AbsFile])

-- | Retrieve the contents of a directory path (which may be relative) as
--   absolute paths
absDirectoryContents :: (AbsRelClass ar) => DirPath ar -> IO ([AbsDir], [AbsFile])

-- | Returns paths relative <i>to</i> the supplied (abs or relative)
--   directory path. eg (for current working directory of
--   <tt>/somewhere/cwd/</tt>):
--   
--   <pre>
--   show (relDirectoryContents (mkRelDir "subDir1")) == (["subDir1A","subDir1B"],
--                                                        ["file1A","file1B"])
--   </pre>
relDirectoryContents :: (AbsRelClass ar) => DirPath ar -> IO ([RelDir], [RelFile])
instance Eq PathComponent
instance Ord PathComponent
instance Eq (Path ar fd)
instance Ord (Path ar fd)
instance Arbitrary (Path ar Dir)
instance Arbitrary (Path ar File)
instance Arbitrary PathComponent
instance (AbsRelClass ar) => Read (Path ar fd)
instance (AbsRelClass ar) => Show (Path ar fd)
instance FileDirClass Dir
instance FileDirClass File
instance AbsRelClass Rel
instance AbsRelClass Abs
instance Show PathComponent