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

-- | Support for well-typed paths
--   
--   Support for well-typed paths.
@package path
@version 0.6.1

-- | Internal types and functions.
module Path.Internal

-- | Path of some base and type.
--   
--   The type variables are:
--   
--   
--   
- b — base, the base location of the path; absolute or
--   relative.
--   
- t — type, whether file or directory.
--   
--   
--   Internally is a string. The string can be of two formats only:
--   
--   
--   
- File format: file.txt, foo/bar.txt,
--   /foo/bar.txt
--   
- Directory format: foo/, /foo/bar/
--   
--   
--   All directories end in a trailing separator. There are no duplicate
--   path separators //, no .., no ./, no
--   ~/, etc.
newtype Path b t
Path :: FilePath -> Path b t

-- | Helper function: check if the filepath has any parent directories in
--   it. This handles the logic of checking for different path separators
--   on Windows.
hasParentDir :: FilePath -> Bool

-- | Normalized file path representation for the relative path root
relRootFP :: FilePath

-- | Convert to a FilePath type.
--   
--   All directories have a trailing slash, so if you want no trailing
--   slash, you can use dropTrailingPathSeparator from the filepath
--   package.
toFilePath :: Path b t -> FilePath
instance GHC.Classes.Eq (Path.Internal.Path b t)
instance GHC.Classes.Ord (Path.Internal.Path b t)
instance GHC.Show.Show (Path.Internal.Path b t)
instance Control.DeepSeq.NFData (Path.Internal.Path b t)
instance Data.Aeson.Types.ToJSON.ToJSON (Path.Internal.Path b t)
instance Data.Hashable.Class.Hashable (Path.Internal.Path b t)

-- | This library provides a well-typed representation of paths in a
--   filesystem directory tree. A path is represented by a number of path
--   components separated by a path separator which is a / on
--   POSIX systems and can be a / or \ on Windows.
--   
--   The root of the tree is represented by a / on POSIX and a
--   drive letter followed by a / or \ on Windows (e.g.
--   C:\). Paths can be absolute or relative. An absolute path
--   always starts from the root of the tree (e.g. /x/y) whereas a
--   relative path never starts with the root (e.g. x/y). Just
--   like we represent the notion of an absolute root by "/", the
--   same way we represent the notion of a relative root by ".".
--   The relative root denotes the directory which contains the first
--   component of a relative path.
module Path

-- | Path of some base and type.
--   
--   The type variables are:
--   
--   
--   
- b — base, the base location of the path; absolute or
--   relative.
--   
- t — type, whether file or directory.
--   
--   
--   Internally is a string. The string can be of two formats only:
--   
--   
--   
- File format: file.txt, foo/bar.txt,
--   /foo/bar.txt
--   
- Directory format: foo/, /foo/bar/
--   
--   
--   All directories end in a trailing separator. There are no duplicate
--   path separators //, no .., no ./, no
--   ~/, etc.
data Path b t

-- | An absolute path.
data Abs

-- | A relative path; one without a root. Note that a .. path
--   component to represent the parent directory is not allowed by this
--   library.
data Rel

-- | A file path.
data File

-- | A directory path.
data Dir

-- | Exceptions that can occur during path operations.
data PathException
InvalidAbsDir :: FilePath -> PathException
InvalidRelDir :: FilePath -> PathException
InvalidAbsFile :: FilePath -> PathException
InvalidRelFile :: FilePath -> PathException
NotAProperPrefix :: FilePath -> FilePath -> PathException

-- | Construct a Path Abs Dir using QuasiQuotes.
--   
--   
--   [absdir|/|]
--   
--   [absdir|/home/chris|]
--   
--   
--   Remember: due to the nature of absolute paths a path like
--   [absdir|/home/chris|] may compile on your platform, but it
--   may not compile on another platform (Windows).
absdir :: QuasiQuoter

-- | Construct a Path Rel Dir using QuasiQuotes.
--   
--   
--   [absdir|/home|]</>[reldir|chris|]
--   
reldir :: QuasiQuoter

-- | Construct a Path Abs File using QuasiQuotes.
--   
--   
--   [absfile|/home/chris/foo.txt|]
--   
--   
--   Remember: due to the nature of absolute paths a path like
--   [absdir|/home/chris/foo.txt|] may compile on your platform,
--   but it may not compile on another platform (Windows).
absfile :: QuasiQuoter

-- | Construct a Path Rel File using QuasiQuotes.
--   
--   
--   [absdir|/home/chris|]</>[relfile|foo.txt|]
--   
relfile :: QuasiQuoter

-- | Append two paths.
--   
--   The following cases are valid and the equalities hold:
--   
--   
--   $(mkAbsDir x) </> $(mkRelDir y) = $(mkAbsDir (x ++ "/" ++ y))
--   
--   
--   
--   $(mkAbsDir x) </> $(mkRelFile y) = $(mkAbsFile (x ++ "/" ++ y))
--   
--   
--   
--   $(mkRelDir x) </> $(mkRelDir y) = $(mkRelDir (x ++ "/" ++ y))
--   
--   
--   
--   $(mkRelDir x) </> $(mkRelFile y) = $(mkRelFile (x ++ "/" ++ y))
--   
--   
--   The following are proven not possible to express:
--   
--   
--   $(mkAbsFile …) </> x
--   
--   
--   
--   $(mkRelFile …) </> x
--   
--   
--   
--   x </> $(mkAbsFile …)
--   
--   
--   
--   x </> $(mkAbsDir …)
--   
(</>) :: Path b Dir -> Path Rel t -> Path b t
infixr 5 </>

-- | If the directory in the first argument is a proper prefix of the path
--   in the second argument strip it from the second argument, generating a
--   path relative to the directory. Throws NotAProperPrefix if the
--   directory is not a proper prefix of the path.
--   
--   The following properties hold:
--   
--   
--   stripProperPrefix x (x </> y) = y
--   
--   
--   Cases which are proven not possible:
--   
--   
--   stripProperPrefix (a :: Path Abs …) (b :: Path Rel …)
--   
--   
--   
--   stripProperPrefix (a :: Path Rel …) (b :: Path Abs …)
--   
--   
--   In other words the bases must match.
stripProperPrefix :: MonadThrow m => Path b Dir -> Path b t -> m (Path Rel t)

-- | Determines if the path in the first parameter is a proper prefix of
--   the path in the second parameter.
--   
--   The following properties hold:
--   
--   
--   not (x `isProperPrefixOf` x)
--   
--   
--   
--   x `isProperPrefixOf` (x </> y)
--   
isProperPrefixOf :: Path b Dir -> Path b t -> Bool

-- | Take the parent path component from a path.
--   
--   The following properties hold:
--   
--   
--   parent (x </> y) == x
--   parent "/x" == "/"
--   parent "x" == "."
--   
--   
--   On the root (absolute or relative), getting the parent is idempotent:
--   
--   
--   parent "/" = "/"
--   parent "." = "."
--   
parent :: Path b t -> Path b Dir

-- | Extract the file part of a path.
--   
--   The following properties hold:
--   
--   
--   filename (p </> a) == filename a
--   
filename :: Path b File -> Path Rel File

-- | Extract the last directory name of a path.
--   
--   The following properties hold:
--   
--   
--   dirname $(mkRelDir ".") == $(mkRelDir ".")
--   
--   
--   
--   dirname (p </> a) == dirname a
--   
dirname :: Path b Dir -> Path Rel Dir

-- | Get extension from given file path.
fileExtension :: Path b File -> String

-- | Add extension to given file path. Throws if the resulting filename
--   does not parse.
--   
--   
--   >>> addFileExtension "txt $(mkRelFile "foo")
--   "foo.txt"
--   
--   >>> addFileExtension "symbols" $(mkRelFile "Data.List")
--   "Data.List.symbols"
--   
--   >>> addFileExtension ".symbols" $(mkRelFile "Data.List")
--   "Data.List.symbols"
--   
--   >>> addFileExtension "symbols" $(mkRelFile "Data.List.")
--   "Data.List..symbols"
--   
--   >>> addFileExtension ".symbols" $(mkRelFile "Data.List.")
--   "Data.List..symbols"
--   
--   >>> addFileExtension "evil/" $(mkRelFile "Data.List")
--   *** Exception: InvalidRelFile "Data.List.evil/"
--   
addFileExtension :: MonadThrow m => String -> Path b File -> m (Path b File)

-- | A synonym for addFileExtension in the form of an operator. See
--   more examples there.
--   
--   
--   >>> $(mkRelFile "Data.List") <.> "symbols"
--   "Data.List.symbols"
--   
--   >>> $(mkRelFile "Data.List") <.> "evil/"
--   *** Exception: InvalidRelFile "Data.List.evil/"
--   
(<.>) :: MonadThrow m => Path b File -> String -> m (Path b File)
infixr 7 <.>

-- | Replace/add extension to given file path. Throws if the resulting
--   filename does not parse.
setFileExtension :: MonadThrow m => String -> Path b File -> m (Path b File)

-- | A synonym for setFileExtension in the form of an operator.
(-<.>) :: MonadThrow m => Path b File -> String -> m (Path b File)
infixr 7 -<.>

-- | Convert an absolute FilePath to a normalized absolute dir
--   Path.
--   
--   Throws: InvalidAbsDir when the supplied path:
--   
--   
--   
- is not an absolute path
--   
- contains a .. path component representing the parent
--   directory
--   
- is not a valid path (See isValid)
--   
parseAbsDir :: MonadThrow m => FilePath -> m (Path Abs Dir)

-- | Convert a relative FilePath to a normalized relative dir
--   Path.
--   
--   Throws: InvalidRelDir when the supplied path:
--   
--   
--   
- is not a relative path
--   
- is ""
--   
- contains a .. path component representing the parent
--   directory
--   
- is not a valid path (See isValid)
--   
parseRelDir :: MonadThrow m => FilePath -> m (Path Rel Dir)

-- | Convert an absolute FilePath to a normalized absolute file
--   Path.
--   
--   Throws: InvalidAbsFile when the supplied path:
--   
--   
--   
- is not an absolute path
--   
- is a directory path i.e.

- has a trailing path
--   separator
- is . or ends in /.

--   
- contains a .. path component representing the parent
--   directory
--   
- is not a valid path (See isValid)
--   
parseAbsFile :: MonadThrow m => FilePath -> m (Path Abs File)

-- | Convert a relative FilePath to a normalized relative file
--   Path.
--   
--   Throws: InvalidRelFile when the supplied path:
--   
--   
--   
- is not a relative path
--   
- is ""
--   
- is a directory path i.e.

- has a trailing path
--   separator
- is . or ends in /.

--   
- contains a .. path component representing the parent
--   directory
--   
- is not a valid path (See isValid)
--   
parseRelFile :: MonadThrow m => FilePath -> m (Path Rel File)

-- | Convert to a FilePath type.
--   
--   All directories have a trailing slash, so if you want no trailing
--   slash, you can use dropTrailingPathSeparator from the filepath
--   package.
toFilePath :: Path b t -> FilePath

-- | Convert absolute path to directory to FilePath type.
fromAbsDir :: Path Abs Dir -> FilePath

-- | Convert relative path to directory to FilePath type.
fromRelDir :: Path Rel Dir -> FilePath

-- | Convert absolute path to file to FilePath type.
fromAbsFile :: Path Abs File -> FilePath

-- | Convert relative path to file to FilePath type.
fromRelFile :: Path Rel File -> FilePath

-- | Make a Path Abs Dir'.
--   
--   Remember: due to the nature of absolute paths this (e.g.
--   /home/foo) may compile on your platform, but it may not
--   compile on another platform (Windows).
mkAbsDir :: FilePath -> Q Exp

-- | Make a Path Rel Dir.
mkRelDir :: FilePath -> Q Exp

-- | Make a Path Abs File.
--   
--   Remember: due to the nature of absolute paths this (e.g.
--   /home/foo) may compile on your platform, but it may not
--   compile on another platform (Windows).
mkAbsFile :: FilePath -> Q Exp

-- | Make a Path Rel File.
mkRelFile :: FilePath -> Q Exp

-- | Same as PathException.

-- | Deprecated: Please use PathException instead.
type PathParseException = PathException

-- | Same as stripProperPrefix.

-- | Deprecated: Please use stripProperPrefix instead.
stripDir :: MonadThrow m => Path b Dir -> Path b t -> m (Path Rel t)

-- | Same as isProperPrefixOf.

-- | Deprecated: Please use isProperPrefixOf instead.
isParentOf :: Path b Dir -> Path b t -> Bool
instance GHC.Classes.Eq Path.PathException
instance GHC.Show.Show Path.PathException
instance GHC.Exception.Type.Exception Path.PathException
instance Data.Aeson.Types.FromJSON.FromJSON (Path.Internal.Path Path.Abs Path.Dir)
instance Data.Aeson.Types.FromJSON.FromJSON (Path.Internal.Path Path.Rel Path.Dir)
instance Data.Aeson.Types.FromJSON.FromJSON (Path.Internal.Path Path.Abs Path.File)
instance Data.Aeson.Types.FromJSON.FromJSON (Path.Internal.Path Path.Rel Path.File)
