Z.IO.FileSystem.FilePath

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.

Paths

splitBaseName

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

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

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

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

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

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

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

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

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

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

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

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

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

Arguments

:: CBytes

file path

-> 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	(/my/path, .txt)
/my/path	(/my/path, "")
/my/.ext	(/my/, .ext)
/my/path.	(/my/path, .)
/my/path.abc.txt.tests	(/my/path.abc.txt, .tests)

changeExtension

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"

dropExtension

Arguments

:: CBytes

file path

-> IO CBytes

Remove the last extension and its correspondence "." of a file path.

Path	Result
/my/path.txt	/my/path
/my/path	/my/path ------- ------------ /my/
/my/.ext
/my/path.	/my/path
/my/path.abc.txt.tests	/my/path.abc.txt

takeExtension

Arguments

:: CBytes

file path

-> IO CBytes

Get the extension of a file from a file path, returns "" for no extension, .ext otherwise.

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

hasExtension

Arguments

:: CBytes

file path

-> IO Bool

Test if a file from a file path has an extension.

Path Style

data PathStyle

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

JSON PathStyle

Defined in Z.IO.FileSystem.FilePath

Methods

fromValue :: Value -> Converter PathStyle

toValue :: PathStyle -> Value

encodeJSON :: PathStyle -> Builder ()

Print PathStyle

Defined in Z.IO.FileSystem.FilePath

Methods

toUTF8BuilderP :: Int -> PathStyle -> Builder ()

Generic PathStyle

Defined in Z.IO.FileSystem.FilePath

Associated Types

type Rep PathStyle :: Type -> Type

Methods

from :: PathStyle -> Rep PathStyle x

to :: Rep PathStyle x -> PathStyle

Show PathStyle

Defined in Z.IO.FileSystem.FilePath

Methods

showsPrec :: Int -> PathStyle -> ShowS

show :: PathStyle -> String

showList :: [PathStyle] -> ShowS

Eq PathStyle

Defined in Z.IO.FileSystem.FilePath

Methods

(==) :: PathStyle -> PathStyle -> Bool

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

Ord PathStyle

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

type Rep PathStyle

Defined in Z.IO.FileSystem.FilePath

type Rep PathStyle = D1 ('MetaData "PathStyle" "Z.IO.FileSystem.FilePath" "Z-IO-2.0.0.0-51Vcxm8cL7LL2DAVynurM3" 'False) (C1 ('MetaCons "WindowsStyle" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "UnixStyle" 'PrefixI 'False) (U1 :: Type -> Type))

pathStyle :: CBytes -> IO PathStyle

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

Gets the path style currently using.

setPathStyle :: PathStyle -> IO ()

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

Get the default character that separates directories.

pathSeparators :: IO [Word8]

Get characters that separates directories.

isPathSeparator :: Word8 -> IO Bool

Test if a character is a path separator.

isExtensionSeparator :: Word8 -> Bool

Test if a character is a file extension separator.

searchPathSeparator :: IO Word8

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

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

extensionSeparator :: Word8

File extension character

ExtSeparator is ASCII .

isSearchPathSeparator :: Word8 -> IO Bool

Test if a character is a file separator.

Search path

getSearchPath :: IO [CBytes]

Get a list of paths in the $PATH variable.