ModuleCabal-syntax-3.18.1.0Haskell2010

Distribution.Utils.Path

Contents

Symbolic path endpoints
Abstract directory locations
Symbolic paths
Symbolic path API
General filepath API
Working directory handling
Module names

Synopsis

data FileOrDir
data AllowAbsolute
data CWD
data Pkg
data Dist
data Source
data Include
data Lib
data Framework
data Build
data Artifacts
data PkgDB
data DataDir
data Mix
data Tix
data Tmp
data Response
data PkgConf
type RelativePath
type SymbolicPath
newtype AbsolutePath
newtype SymbolicPathX
class FileLike
class PathLike
value getSymbolicPath
value getAbsolutePath
value sameDirectory
value makeRelativePathEx
value makeSymbolicPath
value unsafeMakeSymbolicPath
value coerceSymbolicPath
value unsafeCoerceSymbolicPath
value relativeSymbolicPath
value symbolicPathRelative_maybe
value interpretSymbolicPath
value interpretSymbolicPathAbsolute
value takeDirectorySymbolicPath
value dropExtensionsSymbolicPath
value replaceExtensionSymbolicPath
value normaliseSymbolicPath
value relativePathMaybe
value interpretSymbolicPathCWD
value absoluteWorkingDir
value tryMakeRelative
value moduleNameSymbolicPath

PackageCabal-syntax-3.18.1.0
Exports45
LanguageHaskell2010
LicenceBSD-3-Clause
SourcePath.hs

Symbolic path endpoints

datadata FileOrDir

Source#

A type-level symbolic name, to an abstract file or directory (e.g. the Cabal package directory).

Constructors

File
A file (with no further information).
Dir Type
The abstract name of a directory or category of directories, e.g. the package directory or a source directory.

datadata AllowAbsolute

Source#

Is this symbolic path allowed to be absolute, or must it be relative?

Constructors

AllowAbsolute
The path may be absolute, or it may be relative.
OnlyRelative
The path must be relative.

Abstract directory locations

datadata CWD

Source#

Abstract directory: current working directory.

See Note [Symbolic paths] in Distribution.Utils.Path.

datadata Pkg

Source#

Abstract directory: package directory (e.g. a directory containing the .cabal file).

See Note [Symbolic paths] in Distribution.Utils.Path.

Instances2Newtype

Newtype [RelativePath Pkg 'File] CompatLicenseFileDefined in Cabal-syntax-3.18.1.0 · Distribution.PackageDescription.FieldGrammar
Newtype (SymbolicPath Pkg ('Dir DataDir)) CompatDataDirDefined in Cabal-syntax-3.18.1.0 · Distribution.PackageDescription.FieldGrammar

datadata Dist

Source#

Abstract directory: dist directory (e.g. dist-newstyle).

See Note [Symbolic paths] in Distribution.Utils.Path.

datadata Source

Source#

Abstract directory: source directory (a search directory for source files).

See Note [Symbolic paths] in Distribution.Utils.Path.

datadata Include

Source#

Abstract directory: include directory (a search directory for CPP includes like header files, e.g. with ghc -I).

See Note [Symbolic paths] in Distribution.Utils.Path.

datadata Lib

Source#

Abstract directory: search directory for extra libraries.

See Note [Symbolic paths] in Distribution.Utils.Path.

datadata Framework

Source#

Abstract directory: MacOS framework directory.

See Note [Symbolic paths] in Distribution.Utils.Path.

datadata Build

Source#

Abstract directory: build directory.

See Note [Symbolic paths] in Distribution.Utils.Path.

datadata Artifacts

Source#

Abstract directory: directory for build artifacts, such as documentation or .hie files.

See Note [Symbolic paths] in Distribution.Utils.Path.

datadata PkgDB

Source#

Abstract directory: package database directory.

See Note [Symbolic paths] in Distribution.Utils.Path.

datadata DataDir

Source#

Abstract directory: data files directory.

See Note [Symbolic paths] in Distribution.Utils.Path.

Instances1Newtype

Newtype (SymbolicPath Pkg ('Dir DataDir)) CompatDataDirDefined in Cabal-syntax-3.18.1.0 · Distribution.PackageDescription.FieldGrammar

datadata Mix

Source#

Abstract directory: directory for HPC .mix files.

See Note [Symbolic paths] in Distribution.Utils.Path.

datadata Tix

Source#

Abstract directory: directory for HPC .tix files.

See Note [Symbolic paths] in Distribution.Utils.Path.

datadata Tmp

Source#

Abstract directory: a temporary directory.

See Note [Symbolic paths] in Distribution.Utils.Path.

datadata Response

Source#

Abstract directory: directory for response files.

See Note [Symbolic paths] in Distribution.Utils.Path.

datadata PkgConf

Source#

Abstract directory: directory for pkg-config files.

See Note [Symbolic paths] in Distribution.Utils.Path.

Symbolic paths

typetype RelativePath = SymbolicPathX 'OnlyRelative

Source#

A symbolic relative path, relative to an abstract location specified by the from type parameter.

They are *symbolic*, which means we cannot perform any IO until we interpret them (using e.g. interpretSymbolicPath).

typetype SymbolicPath = SymbolicPathX 'AllowAbsolute

Source#

A symbolic path which is allowed to be absolute.

They are *symbolic*, which means we cannot perform any IO until we interpret them (using e.g. interpretSymbolicPath).

newtypenewtype AbsolutePath (to :: FileOrDir)

Constructors

AbsolutePath (forall from. SymbolicPath from to)

Instances1PathLike

(b1 ~ 'Dir b2, c2 ~ c3, midAbsolute ~ 'OnlyRelative) => PathLike (AbsolutePath b1) (SymbolicPathX midAbsolute b2 c2) (AbsolutePath c3)Defined in Cabal-syntax-3.18.1.0 · Distribution.Utils.Path

newtypenewtype SymbolicPathX (allowAbsolute :: AllowAbsolute) from (to :: FileOrDir)

Source#

A symbolic path, possibly relative to an abstract location specified by the from type parameter.

They are *symbolic*, which means we cannot perform any IO until we interpret them (using e.g. interpretSymbolicPath).

Instances20Newtype, Eq, Data, Ord, Read, Show, …

Newtype [RelativePath Pkg 'File] CompatLicenseFileDefined in Cabal-syntax-3.18.1.0 · Distribution.PackageDescription.FieldGrammar
(b1 ~ 'Dir b2, c2 ~ c3, midAbsolute ~ 'OnlyRelative) => PathLike (AbsolutePath b1) (SymbolicPathX midAbsolute b2 c2) (AbsolutePath c3)Defined in Cabal-syntax-3.18.1.0 · Distribution.Utils.Path
Newtype (SymbolicPath Pkg ('Dir DataDir)) CompatDataDirDefined in Cabal-syntax-3.18.1.0 · Distribution.PackageDescription.FieldGrammar
Newtype (RelativePath from to) (RelativePathNT from to)Defined in Cabal-syntax-3.18.1.0 · Distribution.FieldGrammar.Newtypes
Newtype (SymbolicPath from to) (SymbolicPathNT from to)Defined in Cabal-syntax-3.18.1.0 · Distribution.FieldGrammar.Newtypes
Eq (SymbolicPathX allowAbsolute from to)Defined in Cabal-syntax-3.18.1.0 · Distribution.Utils.Path
(Typeable from, Typeable allowAbsolute, Typeable to) => Data (SymbolicPathX allowAbsolute from to)Defined in Cabal-syntax-3.18.1.0 · Distribution.Utils.Path
Ord (SymbolicPathX allowAbsolute from to)Defined in Cabal-syntax-3.18.1.0 · Distribution.Utils.Path
Read (SymbolicPathX allowAbsolute from to)Defined in Cabal-syntax-3.18.1.0 · Distribution.Utils.Path
Show (SymbolicPathX allowAbsolute from to)Defined in Cabal-syntax-3.18.1.0 · Distribution.Utils.Path
Generic (SymbolicPathX allowAbsolute from to)Defined in Cabal-syntax-3.18.1.0 · Distribution.Utils.Path
NFData (SymbolicPathX allowAbsolute from to)Defined in Cabal-syntax-3.18.1.0 · Distribution.Utils.Path
Binary (SymbolicPathX allowAbsolute from to)Defined in Cabal-syntax-3.18.1.0 · Distribution.Utils.Path
Parsec (SymbolicPathX 'AllowAbsolute from to)Defined in Cabal-syntax-3.18.1.0 · Distribution.Utils.Path
Parsec (SymbolicPathX 'OnlyRelative from to)Defined in Cabal-syntax-3.18.1.0 · Distribution.Utils.Path
Pretty (SymbolicPathX allowAbsolute from to)Defined in Cabal-syntax-3.18.1.0 · Distribution.Utils.Path
(Typeable allowAbsolute, Typeable from, Typeable to) => Structured (SymbolicPathX allowAbsolute from to)Defined in Cabal-syntax-3.18.1.0 · Distribution.Utils.Path
p ~ 'File => FileLike (SymbolicPathX allowAbsolute dir p)Defined in Cabal-syntax-3.18.1.0 · Distribution.Utils.Path
(b1 ~ 'Dir b2, a3 ~ a1, c2 ~ c3, midAbsolute ~ 'OnlyRelative) => PathLike (SymbolicPathX allowAbsolute a1 b1) (SymbolicPathX midAbsolute b2 c2) (SymbolicPathX allowAbsolute a3 c3)Defined in Cabal-syntax-3.18.1.0 · Distribution.Utils.Path
This instance ensures we don't accidentally discard a symbolic path in a System.FilePath.</> operation due to the second path being absolute.
(Recall that a / b = b whenever b is absolute.)
type Rep (SymbolicPathX allowAbsolute from to) = D1 ('MetaData "SymbolicPathX" "Distribution.Utils.Path" "Cabal-syntax-3.18.1.0-046d" 'True) (C1 ('MetaCons "SymbolicPath" 'PrefixI 'False) (S1 ('MetaSel 'Nothing 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 FilePath)))Defined in Cabal-syntax-3.18.1.0 · Distribution.Utils.Path

classclass FileLike p where

Source#

Types that support System.FilePath.<.>.

Methods

(<.>) :: p -> String -> pinfixr 7
Like System.FilePath.<.>, but also supporting symbolic paths.

Instances2FileLike

FileLike FilePathDefined in Cabal-syntax-3.18.1.0 · Distribution.Utils.Path
p ~ 'File => FileLike (SymbolicPathX allowAbsolute dir p)Defined in Cabal-syntax-3.18.1.0 · Distribution.Utils.Path

classclass PathLike p q r | q r -> p, p r -> q, p q -> r where

Source#

Types that support System.FilePath.</>.

Methods

(</>) :: p -> q -> rinfixr 5
Like System.FilePath.</>, but also supporting symbolic paths.

Instances3PathLike

PathLike FilePath FilePath FilePathDefined in Cabal-syntax-3.18.1.0 · Distribution.Utils.Path
(b1 ~ 'Dir b2, c2 ~ c3, midAbsolute ~ 'OnlyRelative) => PathLike (AbsolutePath b1) (SymbolicPathX midAbsolute b2 c2) (AbsolutePath c3)Defined in Cabal-syntax-3.18.1.0 · Distribution.Utils.Path
(b1 ~ 'Dir b2, a3 ~ a1, c2 ~ c3, midAbsolute ~ 'OnlyRelative) => PathLike (SymbolicPathX allowAbsolute a1 b1) (SymbolicPathX midAbsolute b2 c2) (SymbolicPathX allowAbsolute a3 c3)Defined in Cabal-syntax-3.18.1.0 · Distribution.Utils.Path
This instance ensures we don't accidentally discard a symbolic path in a System.FilePath.</> operation due to the second path being absolute.
(Recall that a / b = b whenever b is absolute.)

Symbolic path API

valuegetSymbolicPath :: SymbolicPathX allowAbsolute from to -> FilePath

Source#

Extract the FilePath underlying a SymbolicPath or RelativePath, without interpreting it.

Use this function e.g. to validate the underlying filepath.

When interacting with the file system, you should instead use interpretSymbolicPath or interpretSymbolicPathCWD.

See Note [Symbolic paths] in Distribution.Utils.Path.

valuegetAbsolutePath :: AbsolutePath to -> FilePath

valuesameDirectory :: SymbolicPathX allowAbsolute from ('Dir to)

Source#

A symbolic path from a directory to itself.

valuemakeRelativePathEx :: HasCallStack => FilePath -> RelativePath from to

Source#

Make a RelativePath, ensuring the path is not absolute, but performing no further checks.

valuemakeSymbolicPath :: FilePath -> SymbolicPath from to

Source#

Make a SymbolicPath, which may be relative or absolute.

valueunsafeMakeSymbolicPath :: FilePath -> SymbolicPathX allowAbs from to

Source#

Make a SymbolicPath which may be relative or absolute, without performing any checks.

Avoid using this function in new code.

valuecoerceSymbolicPath

:: SymbolicPathX allowAbsolute from to1
-> SymbolicPathX allowAbsolute from to2

Source#

Change what a symbolic path is pointing to.

valueunsafeCoerceSymbolicPath

:: SymbolicPathX allowAbsolute from1 to1
-> SymbolicPathX allowAbsolute from2 to2

Source#

Change both what a symbolic path is pointing from and pointing to.

Avoid using this in new code.

valuerelativeSymbolicPath :: RelativePath from to -> SymbolicPath from to

Source#

Weakening: convert a relative symbolic path to a symbolic path, "forgetting" that it is relative.

valuesymbolicPathRelative_maybe

:: SymbolicPath from to
-> Maybe (RelativePath from to)

Source#

Is this symbolic path a relative symbolic path?

valueinterpretSymbolicPath

:: Maybe (SymbolicPath CWD ('Dir from))
-> SymbolicPathX allowAbsolute from to
-> FilePath

Source#

Interpret a symbolic path with respect to the given directory.

Use this function before directly interacting with the file system in order to take into account a working directory argument.

NB: when invoking external programs (such as GHC), it is preferable to set the working directory of the process and use interpretSymbolicPathCWD rather than calling this function, as this function will turn relative paths into absolute paths if the working directory is an absolute path. This can degrade error messages, or worse, break the behaviour entirely (because the program might expect certain paths to be relative).

See Note [Symbolic paths] in Distribution.Utils.Path.

valueinterpretSymbolicPathAbsolute

:: AbsolutePath ('Dir Pkg)
-> SymbolicPathX allowAbsolute Pkg to
-> FilePath

General filepath API

valuetakeDirectorySymbolicPath

:: SymbolicPathX allowAbsolute from 'File
-> SymbolicPathX allowAbsolute from ('Dir to')

Source#

Like System.FilePath.takeDirectory, for symbolic paths.

valuedropExtensionsSymbolicPath

:: SymbolicPathX allowAbsolute from 'File
-> SymbolicPathX allowAbsolute from 'File

Source#

Like System.FilePath.dropExtensions, for symbolic paths.

valuereplaceExtensionSymbolicPath

:: SymbolicPathX allowAbsolute from 'File
-> String
-> SymbolicPathX allowAbsolute from 'File

Source#

Like System.FilePath.replaceExtension, for symbolic paths.

valuenormaliseSymbolicPath

:: SymbolicPathX allowAbsolute from to
-> SymbolicPathX allowAbsolute from to

Source#

Like System.FilePath.normalise, for symbolic paths.

valuerelativePathMaybe

:: SymbolicPath from ('Dir dir)
-> SymbolicPath from to
-> Maybe (RelativePath dir to)

Source#

Does the second argument point to a sub-directory of the first one? If so, return the relative portion of the path, relative to the first argument.

Working directory handling

valueinterpretSymbolicPathCWD :: SymbolicPathX allowAbsolute from to -> FilePath

Source#

Interpret a symbolic path, **under the assumption that the working directory is the package directory**.

Use interpretSymbolicPath instead if you need to take into account a working directory argument before directly interacting with the file system.

Use this function instead of interpretSymbolicPath when invoking a child process: set the working directory of the sub-process, and use this function, e.g.:

callGhc :: Maybe (SymbolicPath CWD (Dir Pkg))
        -> SymbolicPath (Dir Pkg) File
        -> IO ()
callGhc mbWorkDir inputFile =
  runProgramInvocation $
    programInvocationCwd mbWorkDir ghcProg [interpretSymbolicPathCWD inputFile]

In this example, programInvocationCwd sets the working directory, so it is appropriate to use interpretSymbolicPathCWD to provide its arguments.

See Note [Symbolic paths] in Distribution.Utils.Path.