ModuleCabal-syntax-3.16.0.0Haskell2010

Distribution.Utils.Path

22 types
2 classes
20 values

PackageCabal-syntax-3.16.0.0
Exports44
LanguageHaskell2010
LicenceBSD-3-Clause
SourcePath.hs

Symbolic path endpoints

2 declarations

datadata FileOrDir

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

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

Abstract directory: current working directory.

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

datadata Pkg

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.16.0.0 · Distribution.PackageDescription.FieldGrammar
Newtype (SymbolicPath Pkg ('Dir DataDir)) CompatDataDirDefined in Cabal-syntax-3.16.0.0 · Distribution.PackageDescription.FieldGrammar

datadata Dist

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

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

datadata Source

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

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

datadata Include

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

Abstract directory: search directory for extra libraries.

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

datadata Framework

Abstract directory: MacOS framework directory.

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

datadata Build

Abstract directory: build directory.

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

datadata Artifacts

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

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

datadata PkgDB

Abstract directory: package database directory.

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

datadata DataDir

Abstract directory: data files directory.

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

Instances1Newtype

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

datadata Mix

Abstract directory: directory for HPC .mix files.

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

datadata Tix

Abstract directory: directory for HPC .tix files.

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

datadata Tmp

Abstract directory: a temporary directory.

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

datadata Response

Abstract directory: directory for response files.

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

datadata PkgConf

Abstract directory: directory for pkg-config files.

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

Symbolic paths

6 declarations

typetype RelativePath = SymbolicPathX 'OnlyRelative

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

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.16.0.0 · Distribution.Utils.Path

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

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.16.0.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.16.0.0 · Distribution.Utils.Path
Newtype (SymbolicPath Pkg ('Dir DataDir)) CompatDataDirDefined in Cabal-syntax-3.16.0.0 · Distribution.PackageDescription.FieldGrammar
Newtype (RelativePath from to) (RelativePathNT from to)Defined in Cabal-syntax-3.16.0.0 · Distribution.FieldGrammar.Newtypes
Newtype (SymbolicPath from to) (SymbolicPathNT from to)Defined in Cabal-syntax-3.16.0.0 · Distribution.FieldGrammar.Newtypes
Eq (SymbolicPathX allowAbsolute from to)Defined in Cabal-syntax-3.16.0.0 · Distribution.Utils.Path
(Typeable from, Typeable allowAbsolute, Typeable to) => Data (SymbolicPathX allowAbsolute from to)Defined in Cabal-syntax-3.16.0.0 · Distribution.Utils.Path
Ord (SymbolicPathX allowAbsolute from to)Defined in Cabal-syntax-3.16.0.0 · Distribution.Utils.Path
Read (SymbolicPathX allowAbsolute from to)Defined in Cabal-syntax-3.16.0.0 · Distribution.Utils.Path
Show (SymbolicPathX allowAbsolute from to)Defined in Cabal-syntax-3.16.0.0 · Distribution.Utils.Path
Generic (SymbolicPathX allowAbsolute from to)Defined in Cabal-syntax-3.16.0.0 · Distribution.Utils.Path
NFData (SymbolicPathX allowAbsolute from to)Defined in Cabal-syntax-3.16.0.0 · Distribution.Utils.Path
Binary (SymbolicPathX allowAbsolute from to)Defined in Cabal-syntax-3.16.0.0 · Distribution.Utils.Path
Parsec (SymbolicPathX 'AllowAbsolute from to)Defined in Cabal-syntax-3.16.0.0 · Distribution.Utils.Path
Parsec (SymbolicPathX 'OnlyRelative from to)Defined in Cabal-syntax-3.16.0.0 · Distribution.Utils.Path
Pretty (SymbolicPathX allowAbsolute from to)Defined in Cabal-syntax-3.16.0.0 · Distribution.Utils.Path
(Typeable allowAbsolute, Typeable from, Typeable to) => Structured (SymbolicPathX allowAbsolute from to)Defined in Cabal-syntax-3.16.0.0 · Distribution.Utils.Path
p ~ 'File => FileLike (SymbolicPathX allowAbsolute dir p)Defined in Cabal-syntax-3.16.0.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.16.0.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.16.0.0-c954" 'True) (C1 ('MetaCons "SymbolicPath" 'PrefixI 'False) (S1 ('MetaSel 'Nothing 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 FilePath)))Defined in Cabal-syntax-3.16.0.0 · Distribution.Utils.Path

classclass FileLike p where

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.16.0.0 · Distribution.Utils.Path
p ~ 'File => FileLike (SymbolicPathX allowAbsolute dir p)Defined in Cabal-syntax-3.16.0.0 · Distribution.Utils.Path

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

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

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)

A symbolic path from a directory to itself.

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

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

valuemakeSymbolicPath :: FilePath -> SymbolicPath from to

Make a SymbolicPath, which may be relative or absolute.

valueunsafeMakeSymbolicPath :: FilePath -> SymbolicPathX allowAbs from to

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

Change what a symbolic path is pointing to.

valueunsafeCoerceSymbolicPath

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

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

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

valuesymbolicPathRelative_maybe

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

Is this symbolic path a relative symbolic path?

valueinterpretSymbolicPath

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

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

Like System.FilePath.takeDirectory, for symbolic paths.

valuedropExtensionsSymbolicPath

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

Like System.FilePath.dropExtensions, for symbolic paths.

valuereplaceExtensionSymbolicPath

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

Like System.FilePath.replaceExtension, for symbolic paths.

valuenormaliseSymbolicPath

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

Like System.FilePath.normalise, for symbolic paths.

Working directory handling

valueinterpretSymbolicPathCWD :: SymbolicPathX allowAbsolute from to -> FilePath

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.

valueabsoluteWorkingDir :: Maybe (SymbolicPath CWD to) -> IO (AbsolutePath to)

Absolute path to the current working directory.

valuetryMakeRelative

:: Maybe (SymbolicPath CWD ('Dir dir))
-> SymbolicPath dir to
-> IO (SymbolicPath dir to)

Try to make a symbolic path relative.

This function does nothing if the path is already relative.

NB: this function may fail to make the path relative.

Module names

valuemoduleNameSymbolicPath

:: ModuleName
-> SymbolicPathX allowAbsolute Source 'File

Retrieve the relative symbolic path to a Haskell module.