Copyright	(c) Dong Han 2017-2020
License	BSD
Maintainer	winterland1989@gmail.com
Stability	experimental
Portability	non-portable
Safe Haskell	None
Language	Haskell2010

Z.IO.FileSystem.FilePath

Contents

Paths
Extensions
Path Style
Search path

Description

This module provides file path manipulations using cwalk, both unix and window style path is accepted. Default style is choosen during compile time, but can be changed during runtime.

Synopsis

splitBaseName :: CBytes -> IO (CBytes, CBytes)
changeBaseName :: CBytes -> CBytes -> IO CBytes
splitRoot :: CBytes -> IO (CBytes, CBytes)
changeRoot :: CBytes -> CBytes -> IO CBytes
splitSegments :: CBytes -> IO (CBytes, [CBytes])
isAbsolute :: CBytes -> IO Bool
isRelative :: CBytes -> IO Bool
join :: CBytes -> CBytes -> IO CBytes
concat :: [CBytes] -> IO CBytes
normalize :: CBytes -> IO CBytes
intersection :: CBytes -> CBytes -> IO CBytes
absolute :: CBytes -> CBytes -> IO CBytes
relative :: HasCallStack => CBytes -> CBytes -> IO CBytes
splitExtension :: CBytes -> IO (CBytes, CBytes)
changeExtension :: CBytes -> CBytes -> IO CBytes
data PathStyle
- = WindowsStyle
- | UnixStyle
pathStyle :: CBytes -> IO PathStyle
getPathStyle :: IO PathStyle
setPathStyle :: PathStyle -> IO ()
pathSeparator :: IO [Word8]
searchPathSeparator :: IO Word8
extensionSeparator :: Word8
getSearchPath :: IO [CBytes]

Paths

splitBaseName Source #

Arguments

:: CBytes
-> IO (CBytes, CBytes)	return (dir, basename)

Get the basename of a file path.

The basename is the last segment of a path. For instance, logs is the basename of the path /var/logs.

Path	Basename
/my/path.txt	path.txt
/my/path.txt/	path.txt
/my/path.txt////	path.txt
file_name	file_name
..	..
.	.
/	""
C:pathtest.txt	test.txt

changeBaseName Source #

Arguments

:: CBytes
-> CBytes	new base name
-> IO CBytes

Changes the basename of a file path.

> changeBaseName  "foo/bar.txt" "qux.png"
"foo/qux.png"

splitRoot Source #

Arguments

:: CBytes
-> IO (CBytes, CBytes)	return (root, rest path)

Determines the root of a path.

This function determines the root of a path by finding it’s length. The root comes before the first segment of the path. For example, C:\ is the root of C:\folder\file.txt. It always starts at the submitted path. If the path has no root, empty will be returned.

Style	Path	Root
UNIX	/test/	/
UNIX	test.txt	""
UNIX	C:\test.txt	""
UNIX	\folder\	""
WINDOWS	/test.txt	/
WINDOWS	\test.txt	\
WINDOWS	C:\test.txt	C:\
WINDOWS	\\server\folder\data	\\server\folder\
WINDOWS	\\.\folder\data	\\.\
WINDOWS	\\?\folder\data	\\?\
WINDOWS	C:test.txt	C:
WINDOWS	..\hello\world.txt	""

changeRoot Source #

Arguments

:: CBytes
-> CBytes	new base name
-> IO CBytes

Changes the root of a file path.

> changeBaseName "C:\\test.txt" "D:\\"    -- windows style
"D:\test.txt"

splitSegments Source #

Arguments

:: CBytes
-> IO (CBytes, [CBytes])	return (root, segments)

Split file path into (root, segments, basename) tuple.

Root may be empty, segments are separated by pathSeparator and never be empty if any.

isAbsolute :: CBytes -> IO Bool Source #

Determine whether the path is absolute or not.

This function checks whether the path is an absolute (fully qualified) path or not. A path is considered to be absolute if the root ends with a separator.

Style	Path	Result
UNIX	/test/	True
UNIX	test.txt	False
UNIX	C:\test.txt	False
UNIX	\folder\	False
WINDOWS	/test.txt	True
WINDOWS	\test.txt	True
WINDOWS	C:\test.txt	True
WINDOWS	\\server\folder\data	True
WINDOWS	\\.\folder\data	True
WINDOWS	\\?\folder\data	True
WINDOWS	C:test.txt	False
WINDOWS	..\hello\world.txt	False

isRelative :: CBytes -> IO Bool Source #

Determine whether the path is relative or not.

This function checks whether the path is a relative path or not. A path is considered to be relative if the root does not end with a separator.

Style	Path	Result
UNIX	/test/	False
UNIX	test.txt	True
UNIX	C:\test.txt	True
UNIX	\folder\	True
WINDOWS	/test.txt	False
WINDOWS	\test.txt	False
WINDOWS	C:\test.txt	False
WINDOWS	\\server\folder\data	False
WINDOWS	\\.\folder\data	False
WINDOWS	\\?\folder\data	False
WINDOWS	C:test.txt	True
WINDOWS	..\hello\world.txt	True

join :: CBytes -> CBytes -> IO CBytes Source #

Joins two paths together.

Style	Path A	Path B	Result
UNIX	hello/there	../world	hello/world
UNIX	/first	/second	/first/second
UNIX	hello	..	.
UNIX	hello/there	..	hello
UNIX	hello	there	hello/there
WINDOWS	this\	C:\..\..\is\a\test\	is\a\test
WINDOWS	C:\this\path	C:\is\a\test\	C:\this\path\C:\is\a\test
WINDOWS	C:\this\path	C:\..\is\a\test\	C:\this\path\is\a\test
WINDOWS	\\s1\unc\path	\\s2\unc\pa	\\s1\unc\pa\s2\unc\path

concat :: [CBytes] -> IO CBytes Source #

Joins multiple paths together.

This function generates a new path by joining multiple paths together. It will remove double separators, and unlike absolute, it permits the use of multiple relative paths to combine.

normalize :: CBytes -> IO CBytes Source #

Creates a normalized version of the path. The following will be true for the normalized path:

"../" will be resolved.
"./" will be removed.
double separators will be fixed with a single separator.
separator suffixes will be removed.

Input	Output
/var	/var
/var/logs/test/../../	/var
/var/logs/test/../../../../../../	/
rel/../../	..
/var////logs//test/	/var/logs/test
/var/././././	/var
/var/./logs/.//test/..//..//////	/var

intersection Source #

Arguments

:: CBytes	The base path which will be compared with the other path.
-> CBytes	The other path which will compared with the base path.
-> IO CBytes

Finds common portions in two paths.

Style	Base	Other	Result
UNIX	/test/abc/../foo/bar	/test/foo/har	/test/abc/../foo
UNIX	/test/foo/har	/test/abc/../foo/bar	/test/foo
UNIX	/test/abc.txt	test/abc.txt	""
UNIX	/	""	""
UNIX	/this///is/a//test	/this//is/a///file	/this///is/a
UNIX	/this/is/a/test	/this/is/a/	/this/is/a
UNIX	/this/is/a/test	/this/is/a	/this/is/a
UNIX	/this/is/a/test	/this/is/a/string	/this/is/a
WINDOWS	C:/abc/test.txt	C:/	C:/
WINDOWS	C:/abc/test.txt	C:/def/test.txt	C:/
WINDOWS	C:/test/abc.txt	D:/test/abc.txt	""

absolute Source #

Arguments

:: CBytes	The absolute base path on which the relative path will be applied.
-> CBytes	The relative path which will be applied on the base path.
-> IO CBytes

Generates an absolute path based on a base.

This function generates an absolute path based on a base path and another path. It is guaranteed to return an absolute path. If the second submitted path is absolute, it will override the base path.

Base	Path	Result
/hello/there	../../../../../	/
/hello//../there	test//thing	/there/test/thing
hello/there	/test	/test
hello/there	test	/hello/there/test
/hello/there	/test	/test
/hello/there	..	/hello

relative Source #

Arguments

:: HasCallStack
=> CBytes	The base path from which the relative path will start.
-> CBytes	The target path where the relative path will point to.
-> IO CBytes

Generates a relative path based on a base.

This function generates a relative path based on a base path and another path. It determines how to get to the submitted path, starting from the base directory.

Note the two arguments must be both absolute or both relative, otherwise an InvalidArgument will be thrown.

Style	Base	Path	Result
UNIX	/../../	/../../	.
UNIX	/path/same	/path/not_same/ho/..	../not_same
UNIX	/path/not_same/ho/..	/path/same	../same
UNIX	/path/same	/path/same/ho/..	.
UNIX	/path/same/ho/..	/path/same	.
UNIX	/path/same	/path/same	.
UNIX	/path/long/one	/path/long/one/two	two
UNIX	/path/long/one/two	/path/long/one	..
UNIX	./this/is/path_one	./this/is/path_two	../path_two
UNIX	/this/is/path_one	/this/is/path_two	../path_two
WINDOWS	C:/path/same	D:/path/same	""

Extensions

splitExtension Source #

Arguments

:: CBytes
-> IO (CBytes, CBytes)	return (file, ext)

Split the extension of a file path.

This function extracts the extension portion of a file path.

Path	Result
/my/path.txt	.txt
/my/path	""
/my/.path	.path
/my/path.	.
/my/path.abc.txt.tests	.tests

changeExtension Source #

Arguments

:: CBytes	The path which will be used to make the change.
-> CBytes	The extension which will be placed within the new path.
-> IO CBytes

Changes the extension of a file path.

This function changes the extension of a file name. The function will append an extension if the basename does not have an extension, or use the extension as a basename if the path does not have a basename.

Note:

This function does not normalize the resulting path. You can use normalize to do so.
If the new_extension parameter starts with a dot, the first dot will be ignored when the new extension is appended.

> changeExtension  "foo/bar.txt" "png"
"foo/bar.png"

Path Style

data PathStyle Source #

Constructors

WindowsStyle	Use backslashes as a separator and volume for the root.
UnixStyle	Use slashes as a separator and a slash for the root.

Instances

Instances details

Eq PathStyle Source #
Instance details Defined in Z.IO.FileSystem.FilePath Methods (==) :: PathStyle -> PathStyle -> Bool # (/=) :: PathStyle -> PathStyle -> Bool #
Ord PathStyle Source #
Instance details Defined in Z.IO.FileSystem.FilePath Methods compare :: PathStyle -> PathStyle -> Ordering # (<) :: PathStyle -> PathStyle -> Bool # (<=) :: PathStyle -> PathStyle -> Bool # (>) :: PathStyle -> PathStyle -> Bool # (>=) :: PathStyle -> PathStyle -> Bool # max :: PathStyle -> PathStyle -> PathStyle # min :: PathStyle -> PathStyle -> PathStyle #
Show PathStyle Source #
Instance details Defined in Z.IO.FileSystem.FilePath Methods showsPrec :: Int -> PathStyle -> ShowS # show :: PathStyle -> String # showList :: [PathStyle] -> ShowS #
Generic PathStyle Source #
Instance details Defined in Z.IO.FileSystem.FilePath Associated Types type Rep PathStyle :: Type -> Type # Methods from :: PathStyle -> Rep PathStyle x # to :: Rep PathStyle x -> PathStyle #
ToValue PathStyle Source #
Instance details Defined in Z.IO.FileSystem.FilePath Methods toValue :: PathStyle -> Value #
EncodeJSON PathStyle Source #
Instance details Defined in Z.IO.FileSystem.FilePath Methods encodeJSON :: PathStyle -> Builder () #
FromValue PathStyle Source #
Instance details Defined in Z.IO.FileSystem.FilePath Methods fromValue :: Value -> Converter PathStyle #
ShowT PathStyle Source #
Instance details Defined in Z.IO.FileSystem.FilePath Methods toUTF8BuilderP :: Int -> PathStyle -> Builder () #
type Rep PathStyle Source #
Instance details Defined in Z.IO.FileSystem.FilePath type Rep PathStyle = D1 ('MetaData "PathStyle" "Z.IO.FileSystem.FilePath" "Z-IO-0.2.0.0-9WozHvkV8CCkBNKN4MqC3" 'False) (C1 ('MetaCons "WindowsStyle" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "UnixStyle" 'PrefixI 'False) (U1 :: Type -> Type))

pathStyle :: CBytes -> IO PathStyle Source #

Guesses the path style.

This function guesses the path style based on a submitted path-string. The guessing will look at the root and the type of slashes contained in the path and return the style which is more likely used in the path. The algorithm checks the following:

If the root is longer than 1 character -> WINDOWS
If the first separator is a backslash -> WINDOWS
If the first separator is a slash -> UNIX
If the last segment starts with a dot -> UNIX
If the last segment contains a dot -> WINDOWS
If nothing was found to determine the style -> UNIX

getPathStyle :: IO PathStyle Source #

Gets the path style currently using.

setPathStyle :: PathStyle -> IO () Source #

Configures which path style is used afterwards.

This function configures which path style is used. call to this function is only required if a non-native behaviour is required. The style defaults to WindowsStyle on windows builds and to UnixStyle otherwise.

pathSeparator :: IO [Word8] Source #

Get the character that separates directories.

searchPathSeparator :: IO Word8 Source #

The character that is used to separate the entries in the $PATH environment variable.

Windows: searchPathSeparator is ASCII ;
Unix: searchPathSeparator is ASCII :

extensionSeparator :: Word8 Source #

File extension character

ExtSeparator is ASCII .

Search path

getSearchPath :: IO [CBytes] Source #

Get a list of paths in the $PATH variable.