| Copyright | (c) 2023 Composewell Technologies |
|---|---|
| License | BSD3 |
| Maintainer | streamly@composewell.com |
| Portability | GHC |
| Safe Haskell | Safe-Inferred |
| Language | Haskell2010 |
Streamly.Internal.FileSystem.Path
Description
Well typed and flexible file systems paths, preserving the OS and filesystem encoding.
You can choose the level of type safety you want. Path is the basic path
type which can represent a file, directory, absolute or relative path with
no restrictions. Depending on how much type safety you want you can choose
appropriate type wrappers to wrap Path. File Path mandates the path to
be a file whereas Abs (File Path) mandates it to be an absolute path
representing a file.
You can upgrade or downgrade the safety. Whenever a less restrictive path type is converted to a more restrctive path type the conversion involves checks and it may fail. However, a more restrictive path type can be freely converted to a less restrictive one.
See the streamly-filepath package for interworking with the OsPath type.
The Path type can be converted to and from OsPath type at zero cost
since the underlying representation of both is the same.
Synopsis
- newtype Path = Path (Array Word8)
- data File a
- data Dir a
- data Abs a
- data Rel a
- class IsPath a where
- fromPathUnsafe :: Path -> a
- fromPath :: MonadThrow m => Path -> m a
- toPath :: a -> Path
- adaptPath :: (MonadThrow m, IsPath a, IsPath b) => a -> m b
- fromChunk :: MonadThrow m => Array Word8 -> m Path
- fromChunkUnsafe :: Array Word8 -> Path
- fromString :: MonadThrow m => [Char] -> m Path
- fromChars :: MonadThrow m => Stream Identity Char -> m Path
- path :: QuasiQuoter
- abs :: QuasiQuoter
- rel :: QuasiQuoter
- dir :: QuasiQuoter
- file :: QuasiQuoter
- absdir :: QuasiQuoter
- reldir :: QuasiQuoter
- absfile :: QuasiQuoter
- relfile :: QuasiQuoter
- mkPath :: String -> Q Exp
- mkAbs :: String -> Q Exp
- mkRel :: String -> Q Exp
- mkDir :: String -> Q Exp
- mkFile :: String -> Q Exp
- mkAbsDir :: String -> Q Exp
- mkRelDir :: String -> Q Exp
- mkAbsFile :: String -> Q Exp
- mkRelFile :: String -> Q Exp
- toChunk :: Path -> Array Word8
- toString :: Path -> [Char]
- toChars :: Monad m => Path -> Stream m Char
- primarySeparator :: Char
- isSeparator :: Char -> Bool
- extendPath :: Path -> Path -> Path
- extendDir :: (IsPath (a (Dir Path)), IsPath b, IsPath (a b)) => a (Dir Path) -> Rel b -> a b
Path Types
A type representing file system paths for directories or files.
A type representing a file path.
A type representing a directory path.
A type representing absolute paths.
A type representing relative paths.
Conversions
Methods
fromPathUnsafe :: Path -> a Source #
Like fromPath but does not check the properties of Path. Provides
performance and simplicity when we know that the properties of the path
are already verified, for example, when we get the path from the file
system or the OS APIs.
fromPath :: MonadThrow m => Path -> m a Source #
Convert a raw Path to other forms of well-typed paths. It may fail
if the path does not satisfy the properties of the target type.
Path components may have limits. Total path length may have a limit.
Convert a well-typed path to a raw Path. Never fails.
adaptPath :: (MonadThrow m, IsPath a, IsPath b) => a -> m b Source #
Convert a path type to another path type. This operation may fail with a
PathException when converting a less restrictive path type to a more
restrictive one.
Construction
fromChunk :: MonadThrow m => Array Word8 -> m Path Source #
On Posix it may fail if the byte array contains null characters. On
Windows the array passed must be a multiple of 2 bytes as the underlying
representation uses Word16.
Throws InvalidPath.
fromChunkUnsafe :: Array Word8 -> Path Source #
Unsafe: On Posix, a path cannot contain null characters. On Windows, the
array passed must be a multiple of 2 bytes as the underlying representation
uses Word16.
fromString :: MonadThrow m => [Char] -> m Path Source #
Encode a Unicode string to Path using strict UTF-8 encoding on Posix.
On Posix it may fail if the stream contains null characters.
TBD: Use UTF16LE on Windows.
fromChars :: MonadThrow m => Stream Identity Char -> m Path Source #
Encode a Unicode char stream to Path using strict UTF-8 encoding on
Posix. On Posix it may fail if the stream contains null characters.
TBD: Use UTF16LE on Windows.
Statically Verified Literals
path :: QuasiQuoter Source #
Generates a Path type from an interpolated string literal.
Unimplemented
abs :: QuasiQuoter Source #
Generates an Abs Path type from an interpolated string literal.
Unimplemented
rel :: QuasiQuoter Source #
Generates an Rel Path type from an interpolated string literal.
Unimplemented
dir :: QuasiQuoter Source #
Generates an Dir Path type from an interpolated string literal.
Unimplemented
file :: QuasiQuoter Source #
Generates an File Path type from an interpolated string literal.
Unimplemented
absdir :: QuasiQuoter Source #
Generates an Abs (Dir Path) type from an interpolated string literal.
Unimplemented
reldir :: QuasiQuoter Source #
Generates an Rel (Dir Path) type from an interpolated string literal.
Unimplemented
absfile :: QuasiQuoter Source #
Generates an Abs (File Path) type from an interpolated string literal.
Unimplemented
relfile :: QuasiQuoter Source #
Generates an Rel (File Path) type from an interpolated string literal.
Unimplemented
Statically Verified Strings
Elimination
toString :: Path -> [Char] Source #
Decode the path to a Unicode string using strict UTF-8 decoding on Posix. TBD: Use UTF16LE on Windows.
toChars :: Monad m => Path -> Stream m Char Source #
Decode the path to a stream of Unicode chars using strict UTF-8 decoding on Posix. TBD: Use UTF16LE on Windows.
Operations
primarySeparator :: Char Source #
Primary path separator character, / on Posix and \ on Windows.
Windows supports / too as a separator. Please use isSeparator for
testing if a char is a separator char.
isSeparator :: Char -> Bool Source #
On Posix only / is a path separator but in windows it could be either
/ or \.
extendPath :: Path -> Path -> Path Source #
Like extendDir but for the less restrictive Path type which will always
create a syntactically valid Path type but it may not be semantically valid
because we may append an absolute path or we may append to a file path.
The onus lies on the user to ensure that the first path is not a file and
the second path is not absolute.