-- 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.5.13


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

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


-- | Support for well-typed paths.
module Path

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

-- | An absolute path.
data Abs

-- | A relative path; one without a root. Note that a <tt>.</tt> as well as
--   any path starting with a <tt>..</tt> is not a valid relative path. In
--   other words, a relative path is always strictly under the directory
--   tree to which it is relative.
data Rel

-- | A file path.
data File

-- | A directory path.
data Dir

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

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

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

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

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

-- | Strip directory from path, making it relative to that directory.
--   Throws <a>Couldn'tStripPrefixDir</a> if directory is not a parent of
--   the path.
--   
--   The following properties hold:
--   
--   <pre>
--   stripDir x (x &lt;/&gt; y) = y
--   </pre>
--   
--   Cases which are proven not possible:
--   
--   <pre>
--   stripDir (a :: Path Abs …) (b :: Path Rel …)
--   </pre>
--   
--   <pre>
--   stripDir (a :: Path Rel …) (b :: Path Abs …)
--   </pre>
--   
--   In other words the bases must match.
stripDir :: MonadThrow m => Path b Dir -> Path b t -> m (Path Rel t)

-- | Is p a parent of the given location? Implemented in terms of
--   <a>stripDir</a>. The bases must match.
--   
--   The following properties hold:
--   
--   <pre>
--   not (x `isParentOf` x)
--   </pre>
--   
--   <pre>
--   x `isParentOf` (x &lt;/&gt; y)
--   </pre>
isParentOf :: Path b Dir -> Path b t -> Bool

-- | Take the absolute parent directory from the absolute path.
--   
--   The following properties hold:
--   
--   <pre>
--   parent (x &lt;/&gt; y) == x
--   </pre>
--   
--   On the root, getting the parent is idempotent:
--   
--   <pre>
--   parent (parent "/") = "/"
--   </pre>
parent :: Path Abs t -> Path Abs Dir

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

-- | Extract the last directory name of a path.
--   
--   The following properties hold:
--   
--   <pre>
--   dirname (p &lt;/&gt; a) == dirname a
--   </pre>
dirname :: Path b Dir -> Path Rel Dir

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

-- | 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)

-- | Convert an absolute <a>FilePath</a> to a normalized absolute dir
--   <a>Path</a>.
--   
--   Throws: <a>PathParseException</a> when the supplied path:
--   
--   <ul>
--   <li>is not an absolute path</li>
--   <li>contains a <tt>..</tt> anywhere in the path</li>
--   <li>is not a valid path (See <a>isValid</a>)</li>
--   </ul>
parseAbsDir :: MonadThrow m => FilePath -> m (Path Abs Dir)

-- | Convert a relative <a>FilePath</a> to a normalized relative dir
--   <a>Path</a>.
--   
--   Throws: <a>PathParseException</a> when the supplied path:
--   
--   <ul>
--   <li>is not a relative path</li>
--   <li>is any of <tt>""</tt>, <tt>.</tt> or <tt>..</tt></li>
--   <li>contains <tt>..</tt> anywhere in the path</li>
--   <li>is not a valid path (See <a>isValid</a>)</li>
--   </ul>
parseRelDir :: MonadThrow m => FilePath -> m (Path Rel Dir)

-- | Convert an absolute <a>FilePath</a> to a normalized absolute file
--   <a>Path</a>.
--   
--   Throws: <a>PathParseException</a> when the supplied path:
--   
--   <ul>
--   <li>is not an absolute path</li>
--   <li>has a trailing path separator</li>
--   <li>contains <tt>..</tt> anywhere in the path</li>
--   <li>ends in <tt>/.</tt></li>
--   <li>is not a valid path (See <a>isValid</a>)</li>
--   </ul>
parseAbsFile :: MonadThrow m => FilePath -> m (Path Abs File)

-- | Convert a relative <a>FilePath</a> to a normalized relative file
--   <a>Path</a>.
--   
--   Throws: <a>PathParseException</a> when the supplied path:
--   
--   <ul>
--   <li>is not a relative path</li>
--   <li>has a trailing path separator</li>
--   <li>is <tt>""</tt>, <tt>.</tt> or <tt>..</tt></li>
--   <li>contains <tt>..</tt> anywhere in the path</li>
--   <li>is not a valid path (See <a>isValid</a>)</li>
--   </ul>
parseRelFile :: MonadThrow m => FilePath -> m (Path Rel File)

-- | Exception when parsing a location.
data PathParseException

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

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

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

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

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

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

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

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

-- | Make a <a>Path</a> <a>Rel</a> <a>File</a>.
mkRelFile :: FilePath -> Q Exp
instance GHC.Show.Show Path.PathParseException
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)
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 GHC.Exception.Exception Path.PathParseException