Path.Posix

This library provides a well-typed representation of paths in a filesystem directory tree.

Note: This module is for working with Posix style paths. Importing Path is usually better.

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.

Types

data Path b t

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:

1. File format: file.txt, foo/bar.txt, /foo/bar.txt
2. Directory format: foo/, /foo/bar/

All directories end in a trailing separator. There are no duplicate path separators //, no .., no ./, no ~/, etc.

Instances

(Typeable b, Typeable t) => Lift (Path b t :: Type)

Defined in Path.Internal.Posix

Methods

lift :: Quote m => Path b t -> m Exp

liftTyped :: forall (m :: Type -> Type). Quote m => Path b t -> Code m (Path b t)

FromJSON (Path Abs Dir)

Defined in Path.Posix

Methods

parseJSON :: Value -> Parser (Path Abs Dir)

parseJSONList :: Value -> Parser [Path Abs Dir]

omittedField :: Maybe (Path Abs Dir)

FromJSON (Path Abs File)

Defined in Path.Posix

Methods

parseJSON :: Value -> Parser (Path Abs File)

parseJSONList :: Value -> Parser [Path Abs File]

omittedField :: Maybe (Path Abs File)

FromJSON (Path Rel Dir)

Defined in Path.Posix

Methods

parseJSON :: Value -> Parser (Path Rel Dir)

parseJSONList :: Value -> Parser [Path Rel Dir]

omittedField :: Maybe (Path Rel Dir)

FromJSON (Path Rel File)

Defined in Path.Posix

Methods

parseJSON :: Value -> Parser (Path Rel File)

parseJSONList :: Value -> Parser [Path Rel File]

omittedField :: Maybe (Path Rel File)

FromJSONKey (Path Abs Dir)

Defined in Path.Posix

Methods

fromJSONKey :: FromJSONKeyFunction (Path Abs Dir)

fromJSONKeyList :: FromJSONKeyFunction [Path Abs Dir]

FromJSONKey (Path Abs File)

Defined in Path.Posix

Methods

fromJSONKey :: FromJSONKeyFunction (Path Abs File)

fromJSONKeyList :: FromJSONKeyFunction [Path Abs File]

FromJSONKey (Path Rel Dir)

Defined in Path.Posix

Methods

fromJSONKey :: FromJSONKeyFunction (Path Rel Dir)

fromJSONKeyList :: FromJSONKeyFunction [Path Rel Dir]

FromJSONKey (Path Rel File)

Defined in Path.Posix

Methods

fromJSONKey :: FromJSONKeyFunction (Path Rel File)

fromJSONKeyList :: FromJSONKeyFunction [Path Rel File]

ToJSON (Path b t)

Defined in Path.Internal.Posix

Methods

toJSON :: Path b t -> Value

toEncoding :: Path b t -> Encoding

toJSONList :: [Path b t] -> Value

toEncodingList :: [Path b t] -> Encoding

omitField :: Path b t -> Bool

ToJSONKey (Path b t)

Defined in Path.Internal.Posix

Methods

toJSONKey :: ToJSONKeyFunction (Path b t)

toJSONKeyList :: ToJSONKeyFunction [Path b t]

(Data b, Data t) => Data (Path b t)

Defined in Path.Internal.Posix

Methods

gfoldl :: (forall d b0. Data d => c (d -> b0) -> d -> c b0) -> (forall g. g -> c g) -> Path b t -> c (Path b t)

gunfold :: (forall b0 r. Data b0 => c (b0 -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c (Path b t)

toConstr :: Path b t -> Constr

dataTypeOf :: Path b t -> DataType

dataCast1 :: Typeable t0 => (forall d. Data d => c (t0 d)) -> Maybe (c (Path b t))

dataCast2 :: Typeable t0 => (forall d e. (Data d, Data e) => c (t0 d e)) -> Maybe (c (Path b t))

gmapT :: (forall b0. Data b0 => b0 -> b0) -> Path b t -> Path b t

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Path b t -> r

gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Path b t -> r

gmapQ :: (forall d. Data d => d -> u) -> Path b t -> [u]

gmapQi :: Int -> (forall d. Data d => d -> u) -> Path b t -> u

gmapM :: Monad m => (forall d. Data d => d -> m d) -> Path b t -> m (Path b t)

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Path b t -> m (Path b t)

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Path b t -> m (Path b t)

Generic (Path b t)

Defined in Path.Internal.Posix

Associated Types

type Rep (Path b t) :: Type -> Type

Methods

from :: Path b t -> Rep (Path b t) x

to :: Rep (Path b t) x -> Path b t

Show (Path b t)

Same as 'show . Path.toFilePath'.

The following property holds:

x == y ≡ show x == show y

Defined in Path.Internal.Posix

Methods

showsPrec :: Int -> Path b t -> ShowS

show :: Path b t -> String

showList :: [Path b t] -> ShowS

NFData (Path b t)

Defined in Path.Internal.Posix

Methods

rnf :: Path b t -> ()

Eq (Path b t)

String equality.

The following property holds:

show x == show y ≡ x == y

Defined in Path.Internal.Posix

Methods

(==) :: Path b t -> Path b t -> Bool

(/=) :: Path b t -> Path b t -> Bool

Ord (Path b t)

String ordering.

The following property holds:

show x `compare` show y ≡ x `compare` y

Defined in Path.Internal.Posix

Methods

compare :: Path b t -> Path b t -> Ordering

(<) :: Path b t -> Path b t -> Bool

(<=) :: Path b t -> Path b t -> Bool

(>) :: Path b t -> Path b t -> Bool

(>=) :: Path b t -> Path b t -> Bool

max :: Path b t -> Path b t -> Path b t

min :: Path b t -> Path b t -> Path b t

Hashable (Path b t)

Defined in Path.Internal.Posix

Methods

hashWithSalt :: Int -> Path b t -> Int

hash :: Path b t -> Int

type Rep (Path b t)

Defined in Path.Internal.Posix

type Rep (Path b t) = D1 ('MetaData "Path" "Path.Internal.Posix" "path-0.9.6-6uAxXgOOp6mHwNWdZSA9MV" 'True) (C1 ('MetaCons "Path" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 FilePath)))

data Abs

An absolute path.

Instances

Data Abs

Defined in Path.Posix

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Abs -> c Abs

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c Abs

toConstr :: Abs -> Constr

dataTypeOf :: Abs -> DataType

dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c Abs)

dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c Abs)

gmapT :: (forall b. Data b => b -> b) -> Abs -> Abs

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Abs -> r

gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Abs -> r

gmapQ :: (forall d. Data d => d -> u) -> Abs -> [u]

gmapQi :: Int -> (forall d. Data d => d -> u) -> Abs -> u

gmapM :: Monad m => (forall d. Data d => d -> m d) -> Abs -> m Abs

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Abs -> m Abs

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Abs -> m Abs

FromJSON (Path Abs Dir)

Defined in Path.Posix

Methods

parseJSON :: Value -> Parser (Path Abs Dir)

parseJSONList :: Value -> Parser [Path Abs Dir]

omittedField :: Maybe (Path Abs Dir)

FromJSON (Path Abs File)

Defined in Path.Posix

Methods

parseJSON :: Value -> Parser (Path Abs File)

parseJSONList :: Value -> Parser [Path Abs File]

omittedField :: Maybe (Path Abs File)

FromJSONKey (Path Abs Dir)

Defined in Path.Posix

Methods

fromJSONKey :: FromJSONKeyFunction (Path Abs Dir)

fromJSONKeyList :: FromJSONKeyFunction [Path Abs Dir]

FromJSONKey (Path Abs File)

Defined in Path.Posix

Methods

fromJSONKey :: FromJSONKeyFunction (Path Abs File)

fromJSONKeyList :: FromJSONKeyFunction [Path Abs File]

data Rel

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

Instances

Data Rel

Defined in Path.Posix

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Rel -> c Rel

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c Rel

toConstr :: Rel -> Constr

dataTypeOf :: Rel -> DataType

dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c Rel)

dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c Rel)

gmapT :: (forall b. Data b => b -> b) -> Rel -> Rel

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Rel -> r

gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Rel -> r

gmapQ :: (forall d. Data d => d -> u) -> Rel -> [u]

gmapQi :: Int -> (forall d. Data d => d -> u) -> Rel -> u

gmapM :: Monad m => (forall d. Data d => d -> m d) -> Rel -> m Rel

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Rel -> m Rel

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Rel -> m Rel

FromJSON (Path Rel Dir)

Defined in Path.Posix

Methods

parseJSON :: Value -> Parser (Path Rel Dir)

parseJSONList :: Value -> Parser [Path Rel Dir]

omittedField :: Maybe (Path Rel Dir)

FromJSON (Path Rel File)

Defined in Path.Posix

Methods

parseJSON :: Value -> Parser (Path Rel File)

parseJSONList :: Value -> Parser [Path Rel File]

omittedField :: Maybe (Path Rel File)

FromJSONKey (Path Rel Dir)

Defined in Path.Posix

Methods

fromJSONKey :: FromJSONKeyFunction (Path Rel Dir)

fromJSONKeyList :: FromJSONKeyFunction [Path Rel Dir]

FromJSONKey (Path Rel File)

Defined in Path.Posix

Methods

fromJSONKey :: FromJSONKeyFunction (Path Rel File)

fromJSONKeyList :: FromJSONKeyFunction [Path Rel File]

data File

A file path.

Instances

Data File

Defined in Path.Posix

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> File -> c File

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c File

toConstr :: File -> Constr

dataTypeOf :: File -> DataType

dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c File)

dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c File)

gmapT :: (forall b. Data b => b -> b) -> File -> File

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> File -> r

gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> File -> r

gmapQ :: (forall d. Data d => d -> u) -> File -> [u]

gmapQi :: Int -> (forall d. Data d => d -> u) -> File -> u

gmapM :: Monad m => (forall d. Data d => d -> m d) -> File -> m File

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> File -> m File

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> File -> m File

FromJSON (SomeBase File)

Defined in Path.Posix

Methods

parseJSON :: Value -> Parser (SomeBase File)

parseJSONList :: Value -> Parser [SomeBase File]

omittedField :: Maybe (SomeBase File)

FromJSON (Path Abs File)

Defined in Path.Posix

Methods

parseJSON :: Value -> Parser (Path Abs File)

parseJSONList :: Value -> Parser [Path Abs File]

omittedField :: Maybe (Path Abs File)

FromJSON (Path Rel File)

Defined in Path.Posix

Methods

parseJSON :: Value -> Parser (Path Rel File)

parseJSONList :: Value -> Parser [Path Rel File]

omittedField :: Maybe (Path Rel File)

FromJSONKey (Path Abs File)

Defined in Path.Posix

Methods

fromJSONKey :: FromJSONKeyFunction (Path Abs File)

fromJSONKeyList :: FromJSONKeyFunction [Path Abs File]

FromJSONKey (Path Rel File)

Defined in Path.Posix

Methods

fromJSONKey :: FromJSONKeyFunction (Path Rel File)

fromJSONKeyList :: FromJSONKeyFunction [Path Rel File]

data Dir

A directory path.

Instances

Data Dir

Defined in Path.Posix

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Dir -> c Dir

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c Dir

toConstr :: Dir -> Constr

dataTypeOf :: Dir -> DataType

dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c Dir)

dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c Dir)

gmapT :: (forall b. Data b => b -> b) -> Dir -> Dir

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Dir -> r

gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Dir -> r

gmapQ :: (forall d. Data d => d -> u) -> Dir -> [u]

gmapQi :: Int -> (forall d. Data d => d -> u) -> Dir -> u

gmapM :: Monad m => (forall d. Data d => d -> m d) -> Dir -> m Dir

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Dir -> m Dir

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Dir -> m Dir

FromJSON (SomeBase Dir)

Defined in Path.Posix

Methods

parseJSON :: Value -> Parser (SomeBase Dir)

parseJSONList :: Value -> Parser [SomeBase Dir]

omittedField :: Maybe (SomeBase Dir)

FromJSON (Path Abs Dir)

Defined in Path.Posix

Methods

parseJSON :: Value -> Parser (Path Abs Dir)

parseJSONList :: Value -> Parser [Path Abs Dir]

omittedField :: Maybe (Path Abs Dir)

FromJSON (Path Rel Dir)

Defined in Path.Posix

Methods

parseJSON :: Value -> Parser (Path Rel Dir)

parseJSONList :: Value -> Parser [Path Rel Dir]

omittedField :: Maybe (Path Rel Dir)

FromJSONKey (Path Abs Dir)

Defined in Path.Posix

Methods

fromJSONKey :: FromJSONKeyFunction (Path Abs Dir)

fromJSONKeyList :: FromJSONKeyFunction [Path Abs Dir]

FromJSONKey (Path Rel Dir)

Defined in Path.Posix

Methods

fromJSONKey :: FromJSONKeyFunction (Path Rel Dir)

fromJSONKeyList :: FromJSONKeyFunction [Path Rel Dir]

data SomeBase t

Path of some type. t represents the type, whether file or directory. Pattern match to find whether the path is absolute or relative.

Constructors

Abs (Path Abs t)

Rel (Path Rel t)

Instances

FromJSON (SomeBase Dir)

Defined in Path.Posix

Methods

parseJSON :: Value -> Parser (SomeBase Dir)

parseJSONList :: Value -> Parser [SomeBase Dir]

omittedField :: Maybe (SomeBase Dir)

FromJSON (SomeBase File)

Defined in Path.Posix

Methods

parseJSON :: Value -> Parser (SomeBase File)

parseJSONList :: Value -> Parser [SomeBase File]

omittedField :: Maybe (SomeBase File)

ToJSON (SomeBase t)

Defined in Path.Posix

Methods

toJSON :: SomeBase t -> Value

toEncoding :: SomeBase t -> Encoding

toJSONList :: [SomeBase t] -> Value

toEncodingList :: [SomeBase t] -> Encoding

omitField :: SomeBase t -> Bool

Generic (SomeBase t)

Defined in Path.Posix

Associated Types

type Rep (SomeBase t) :: Type -> Type

Methods

from :: SomeBase t -> Rep (SomeBase t) x

to :: Rep (SomeBase t) x -> SomeBase t

Show (SomeBase t)

Defined in Path.Posix

Methods

showsPrec :: Int -> SomeBase t -> ShowS

show :: SomeBase t -> String

showList :: [SomeBase t] -> ShowS

NFData (SomeBase t)

Defined in Path.Posix

Methods

rnf :: SomeBase t -> ()

Eq (SomeBase t)

Defined in Path.Posix

Methods

(==) :: SomeBase t -> SomeBase t -> Bool

(/=) :: SomeBase t -> SomeBase t -> Bool

Ord (SomeBase t)

Defined in Path.Posix

Methods

compare :: SomeBase t -> SomeBase t -> Ordering

(<) :: SomeBase t -> SomeBase t -> Bool

(<=) :: SomeBase t -> SomeBase t -> Bool

(>) :: SomeBase t -> SomeBase t -> Bool

(>=) :: SomeBase t -> SomeBase t -> Bool

max :: SomeBase t -> SomeBase t -> SomeBase t

min :: SomeBase t -> SomeBase t -> SomeBase t

Hashable (SomeBase t)

Defined in Path.Posix

Methods

hashWithSalt :: Int -> SomeBase t -> Int

hash :: SomeBase t -> Int

type Rep (SomeBase t)

Defined in Path.Posix

type Rep (SomeBase t) = D1 ('MetaData "SomeBase" "Path.Posix" "path-0.9.6-6uAxXgOOp6mHwNWdZSA9MV" 'False) (C1 ('MetaCons "Abs" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Path Abs t))) :+: C1 ('MetaCons "Rel" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Path Rel t))))

Exceptions

data PathException

Exceptions that can occur during path operations.

Since: 0.6.0

Constructors

InvalidAbsDir FilePath

InvalidRelDir FilePath

InvalidAbsFile FilePath

InvalidRelFile FilePath

InvalidFile FilePath

InvalidDir FilePath

NotAProperPrefix FilePath FilePath

HasNoExtension FilePath

InvalidExtension String

Instances

Exception PathException

Defined in Path.Posix

Methods

toException :: PathException -> SomeException

fromException :: SomeException -> Maybe PathException

displayException :: PathException -> String

Show PathException

Defined in Path.Posix

Methods

showsPrec :: Int -> PathException -> ShowS

show :: PathException -> String

showList :: [PathException] -> ShowS

Eq PathException

Defined in Path.Posix

Methods

(==) :: PathException -> PathException -> Bool

(/=) :: PathException -> PathException -> Bool

QuasiQuoters

Using the following requires the QuasiQuotes language extension.

For Windows users, the QuasiQuoters are especially beneficial because they prevent Haskell from treating \ as an escape character. This makes Windows paths easier to write.

[absfile|C:\chris\foo.txt|]

absdir :: QuasiQuoter

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

Since: 0.5.13

reldir :: QuasiQuoter

Construct a Path Rel Dir using QuasiQuotes.

[absdir|/home|]</>[reldir|chris|]

Since: 0.5.13

absfile :: 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).

Since: 0.5.13

relfile :: QuasiQuoter

Construct a Path Rel File using QuasiQuotes.

[absdir|/home/chris|]</>[relfile|foo.txt|]

Since: 0.5.13

Operations

(</>) :: Path b Dir -> Path Rel t -> Path b t infixr 5

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

stripProperPrefix :: MonadThrow m => Path b Dir -> Path b t -> m (Path Rel t)

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.

Since: 0.6.0

isProperPrefixOf :: Path b Dir -> Path b t -> Bool

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)

Since: 0.6.0

replaceProperPrefix :: MonadThrow m => Path b Dir -> Path b' Dir -> Path b t -> m (Path b' t)

Change from one directory prefix to another.

Throw NotAProperPrefix if the first argument is not a proper prefix of the path.

>>> replaceProperPrefix $(mkRelDir "foo") $(mkRelDir "bar") $(mkRelFile "foo/file.txt") == $(mkRelFile "bar/file.txt")

parent :: Path b t -> Path b Dir

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 "." = "."

filename :: Path b File -> Path Rel File

Extract the file part of a path.

The following properties hold:

filename (p </> a) == filename a

dirname :: Path b Dir -> Path Rel Dir

Extract the last directory name of a path.

The following properties hold:

dirname $(mkRelDir ".") == $(mkRelDir ".")

dirname (p </> a) == dirname a

addExtension

Arguments

:: MonadThrow m

=> String

Extension to add

-> Path b File

Old file name

-> m (Path b File)

New file name with the desired extension added at the end

Add extension to given file path.

>>> addExtension ".foo"   $(mkRelFile "name"     ) == Just $(mkRelFile "name.foo"    )
>>> addExtension ".foo."  $(mkRelFile "name"     ) == Just $(mkRelFile "name.foo."   )
>>> addExtension ".foo.." $(mkRelFile "name"     ) == Just $(mkRelFile "name.foo.."  )
>>> addExtension ".foo"   $(mkRelFile "name.bar" ) == Just $(mkRelFile "name.bar.foo")
>>> addExtension ".foo"   $(mkRelFile ".name"    ) == Just $(mkRelFile ".name.foo"   )
>>> addExtension ".foo"   $(mkRelFile "name."    ) == Just $(mkRelFile "name..foo"   )
>>> addExtension ".foo"   $(mkRelFile "..."      ) == Just $(mkRelFile "....foo"     )

Throws an InvalidExtension exception if the extension is not valid. A valid extension starts with a . followed by one or more characters not including . followed by zero or more . in trailing position. Moreover, an extension must be a valid filename, notably it cannot include path separators. Particularly, .foo.bar is an invalid extension, instead you have to first set .foo and then .bar individually. Some examples of invalid extensions are:

>>> addExtension "foo"      $(mkRelFile "name")
>>> addExtension "..foo"    $(mkRelFile "name")
>>> addExtension ".foo.bar" $(mkRelFile "name")
>>> addExtension ".foo/bar" $(mkRelFile "name")

Since: 0.7.0

splitExtension :: MonadThrow m => Path b File -> m (Path b File, String)

splitExtension is the inverse of addExtension. It splits the given file path into a valid filename and a valid extension.

>>> splitExtension $(mkRelFile "name.foo"     ) == Just ($(mkRelFile "name"    ), ".foo"  )
>>> splitExtension $(mkRelFile "name.foo."    ) == Just ($(mkRelFile "name"    ), ".foo." )
>>> splitExtension $(mkRelFile "name.foo.."   ) == Just ($(mkRelFile "name"    ), ".foo..")
>>> splitExtension $(mkRelFile "name.bar.foo" ) == Just ($(mkRelFile "name.bar"), ".foo"  )
>>> splitExtension $(mkRelFile ".name.foo"    ) == Just ($(mkRelFile ".name"   ), ".foo"  )
>>> splitExtension $(mkRelFile "name..foo"    ) == Just ($(mkRelFile "name."   ), ".foo"  )
>>> splitExtension $(mkRelFile "....foo"      ) == Just ($(mkRelFile "..."     ), ".foo"  )

Throws HasNoExtension exception if the filename does not have an extension or in other words it cannot be split into a valid filename and a valid extension. The following cases throw an exception, please note that "." and ".." are not valid filenames:

>>> splitExtension $(mkRelFile "name"   )
>>> splitExtension $(mkRelFile "name."  )
>>> splitExtension $(mkRelFile "name.." )
>>> splitExtension $(mkRelFile ".name"  )
>>> splitExtension $(mkRelFile "..name" )
>>> splitExtension $(mkRelFile "...name")

splitExtension and addExtension are inverses of each other, the following laws hold:

uncurry addExtension . swap >=> splitExtension == return
splitExtension >=> uncurry addExtension . swap == return

Since: 0.7.0

fileExtension :: MonadThrow m => Path b File -> m String

Get extension from given file path. Throws HasNoExtension exception if the file does not have an extension. The following laws hold:

flip addExtension file >=> fileExtension == return
fileExtension == (fmap snd) . splitExtension

Since: 0.5.11

replaceExtension

Arguments

:: MonadThrow m

=> String

Extension to set

-> Path b File

Old file name

-> m (Path b File)

New file name with the desired extension

If the file has an extension replace it with the given extension otherwise add the new extension to it. Throws an InvalidExtension exception if the new extension is not a valid extension (see fileExtension for validity rules).

The following law holds:

(fileExtension >=> flip replaceExtension file) file == return file

Since: 0.7.0

splitDrive :: Path Abs t -> (Path Abs Dir, Maybe (Path Rel t))

Split an absolute path into a drive and, perhaps, a path. On POSIX, / is a drive.

takeDrive :: Path Abs t -> Path Abs Dir

Get the drive from an absolute path. On POSIX, / is a drive.

takeDrive x = fst (splitDrive x)

dropDrive :: Path Abs t -> Maybe (Path Rel t)

Drop the drive from an absolute path. May result in Nothing if the path is just a drive.

dropDrive x = snd (splitDrive x)

isDrive :: Path Abs Dir -> Bool

Is an absolute directory path a drive?

mapSomeBase :: (forall b. Path b t -> Path b t') -> SomeBase t -> SomeBase t'

Helper to apply a function to the SomeBase object

>>> mapSomeBase parent (Abs [absfile|/foo/bar/cow.moo|]) == Abs [absdir|"/foo/bar"|]

prjSomeBase :: (forall b. Path b t -> a) -> SomeBase t -> a

Helper to project the contents out of a SomeBase object.

>>> prjSomeBase toFilePath (Abs [absfile|/foo/bar/cow.moo|]) == "/foo/bar/cow.moo"

Parsing

parseAbsDir :: MonadThrow m => FilePath -> m (Path Abs Dir)

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)

parseRelDir :: MonadThrow m => FilePath -> m (Path Rel 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)
• is all path separators

parseAbsFile :: MonadThrow m => FilePath -> m (Path Abs File)

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)

parseRelFile :: MonadThrow m => FilePath -> m (Path Rel 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)

parseSomeDir :: MonadThrow m => FilePath -> m (SomeBase Dir)

Convert an absolute or relative FilePath to a normalized SomeBase representing a directory.

Throws: InvalidDir when the supplied path:

• contains a .. path component representing the parent directory
• is not a valid path (See isValid)

parseSomeFile :: MonadThrow m => FilePath -> m (SomeBase File)

Convert an absolute or relative FilePath to a normalized SomeBase representing a file.

Throws: InvalidFile when the supplied 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)

Conversion

toFilePath :: Path b t -> 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.

fromAbsDir :: Path Abs Dir -> FilePath

Convert absolute path to directory to FilePath type.

fromRelDir :: Path Rel Dir -> FilePath

Convert relative path to directory to FilePath type.

fromAbsFile :: Path Abs File -> FilePath

Convert absolute path to file to FilePath type.

fromRelFile :: Path Rel File -> FilePath

Convert relative path to file to FilePath type.

fromSomeDir :: SomeBase Dir -> FilePath

Convert a valid directory to a FilePath.

fromSomeFile :: SomeBase File -> FilePath

Convert a valid file to a FilePath.

TemplateHaskell constructors

These require the TemplateHaskell language extension.

mkAbsDir :: FilePath -> Q Exp

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

mkRelDir :: FilePath -> Q Exp

Make a Path Rel Dir.

mkAbsFile :: 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).

mkRelFile :: FilePath -> Q Exp

Make a Path Rel File.

Deprecated

type PathParseException = PathException

Deprecated: Please use PathException instead.

Same as PathException.

stripDir :: MonadThrow m => Path b Dir -> Path b t -> m (Path Rel t)

Deprecated: Please use stripProperPrefix instead.

Same as stripProperPrefix.

isParentOf :: Path b Dir -> Path b t -> Bool

Deprecated: Please use isProperPrefixOf instead.

Same as isProperPrefixOf.

addFileExtension

Arguments

:: MonadThrow m

=> String

Extension to add

-> Path b File

Old file name

-> m (Path b File)

New file name with the desired extension added at the end

Deprecated: Please use addExtension instead.

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/"

Since: 0.6.1

(<.>) infixr 7

Arguments

:: MonadThrow m

=> Path b File

Old file name

-> String

Extension to add

-> m (Path b File)

New file name with the desired extension added at the end

Deprecated: Please use addExtension instead.

A synonym for addFileExtension in the form of an infix operator. See more examples there.

>>> $(mkRelFile "Data.List") <.> "symbols"
"Data.List.symbols"
>>> $(mkRelFile "Data.List") <.> "evil/"
*** Exception: InvalidRelFile "Data.List.evil/"

Since: 0.6.1

setFileExtension

Arguments

:: MonadThrow m

=> String

Extension to set

-> Path b File

Old file name

-> m (Path b File)

New file name with the desired extension

Deprecated: Please use replaceExtension instead.

Replace/add extension to given file path. Throws if the resulting filename does not parse.

Since: 0.5.11

(-<.>) infixr 7

Arguments

:: MonadThrow m

=> Path b File

Old file name

-> String

Extension to set

-> m (Path b File)

New file name with the desired extension

Deprecated: Please use replaceExtension instead.

A synonym for setFileExtension in the form of an operator.

Since: 0.6.0