Z-IO-2.0.0.0: Simple and high performance IO toolkit for Haskell
Copyright(c) Dong Han 2017-2020
LicenseBSD
Maintainerwinterland1989@gmail.com
Stabilityexperimental
Portabilitynon-portable
Safe HaskellSafe-Inferred
LanguageHaskell2010

Z.IO.FileSystem.FilePath

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

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.

PathBasename
/my/path.txtpath.txt
/my/path.txt/path.txt
/my/path.txt////path.txt
file_namefile_name
....
..
/""
C:pathtest.txttest.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.

StylePathRoot
UNIX/test//
UNIXtest.txt""
UNIXC:\test.txt""
UNIX\folder\""
WINDOWS/test.txt/
WINDOWS\test.txt\
WINDOWSC:\test.txtC:\
WINDOWS\\server\folder\data\\server\folder\
WINDOWS\\.\folder\data\\.\
WINDOWS\\?\folder\data\\?\
WINDOWSC:test.txtC:
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.

StylePathResult
UNIX/test/True
UNIXtest.txtFalse
UNIXC:\test.txtFalse
UNIX\folder\False
WINDOWS/test.txtTrue
WINDOWS\test.txtTrue
WINDOWSC:\test.txtTrue
WINDOWS\\server\folder\dataTrue
WINDOWS\\.\folder\dataTrue
WINDOWS\\?\folder\dataTrue
WINDOWSC:test.txtFalse
WINDOWS..\hello\world.txtFalse

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.

StylePathResult
UNIX/test/False
UNIXtest.txtTrue
UNIXC:\test.txtTrue
UNIX\folder\True
WINDOWS/test.txtFalse
WINDOWS\test.txtFalse
WINDOWSC:\test.txtFalse
WINDOWS\\server\folder\dataFalse
WINDOWS\\.\folder\dataFalse
WINDOWS\\?\folder\dataFalse
WINDOWSC:test.txtTrue
WINDOWS..\hello\world.txtTrue

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

Joins two paths together.

StylePath APath BResult
UNIXhello/there../worldhello/world
UNIX/first/second/first/second
UNIXhello...
UNIXhello/there..hello
UNIXhellotherehello/there
WINDOWSthis\C:\..\..\is\a\test\is\a\test
WINDOWSC:\this\pathC:\is\a\test\C:\this\path\C:\is\a\test
WINDOWSC:\this\pathC:\..\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.
InputOutput
/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.

StyleBaseOtherResult
UNIX/test/abc/../foo/bar/test/foo/har/test/abc/../foo
UNIX/test/foo/har/test/abc/../foo/bar/test/foo
UNIX/test/abc.txttest/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
WINDOWSC:/abc/test.txtC:/C:/
WINDOWSC:/abc/test.txtC:/def/test.txtC:/
WINDOWSC:/test/abc.txtD:/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.

BasePathResult
/hello/there../../../../..//
/hello//../theretest//thing/there/test/thing
hello/there/test/test
hello/theretest/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.

StyleBasePathResult
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/twotwo
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
WINDOWSC:/path/sameD:/path/same""

Extensions

splitExtension Source #

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.

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

dropExtension Source #

Arguments

:: CBytes

file path

-> IO CBytes 

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

PathResult
/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 Source #

Arguments

:: CBytes

file path

-> IO CBytes 

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

PathResult
/my/path.txt.txt
/my/path""
/my/.path.path
/my/path..
/my/path.abc.txt.tests.tests

hasExtension Source #

Arguments

:: CBytes

file path

-> IO Bool 

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

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
JSON PathStyle Source # 
Instance details

Defined in Z.IO.FileSystem.FilePath

Print PathStyle Source # 
Instance details

Defined in Z.IO.FileSystem.FilePath

Methods

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

Generic PathStyle Source # 
Instance details

Defined in Z.IO.FileSystem.FilePath

Associated Types

type Rep PathStyle :: Type -> Type #

Show PathStyle Source # 
Instance details

Defined in Z.IO.FileSystem.FilePath

Eq PathStyle Source # 
Instance details

Defined in Z.IO.FileSystem.FilePath

Ord PathStyle Source # 
Instance details

Defined in Z.IO.FileSystem.FilePath

type Rep PathStyle Source # 
Instance details

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 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 default character that separates directories.

pathSeparators :: IO [Word8] Source #

Get characters that separates directories.

isPathSeparator :: Word8 -> IO Bool Source #

Test if a character is a path separator.

isExtensionSeparator :: Word8 -> Bool Source #

Test if a character is a file extension separator.

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 .

isSearchPathSeparator :: Word8 -> IO Bool Source #

Test if a character is a file separator.

Search path

getSearchPath :: IO [CBytes] Source #

Get a list of paths in the $PATH variable.