Type representing filenames/pathnames.

This type doesn't add any guarantees over OsString.

Encodes a FilePath to an OsPath. This is a pure version of filepath's encodeUtf that returns the EncodingException in the event of an error.

Since: 0.1

Total conversion from FilePath to OsPath, replacing encode failures with the closest visual match.

Since: 0.1

encode that throws EncodingException.

Since: 0.1

encodeThrowM with MonadFail.

Since: 0.1

Unsafely converts a FilePath to OsPath falling back to error.

WARNING: Partial

Since: 0.1

QuasiQuote an OsPath. This accepts Unicode characters and encodes as UTF-8 on unix and UTF-16LE on windows. Runs isValid on the input. If used as a pattern, requires turning on the ViewPatterns extension.

Like osp, except it runs paths through a "replace function" first. On unix, replaces \ with /. On windows, does the opposite.

This is convenient for writing paths in a platform-agnostic way i.e. we are expecting a path

  "path/to/foo" -- unix
  "path\to\foo" -- windows

The normal way to handle this would be to use the combine function (</>) i.e.

  [osp|path|] </> [osp|to|] </> [osp|foo|]

This can be quite cumbersome for long paths, so we provide this alternative, allowing:

  [ospPathSep|path/to/foo]

Which will automatically convert slashes.

encode that also checks isValid i.e. encode only succeeds if the FilePath can be encoded and passes expected invariants.

Since: 0.1

Total conversion from FilePath to OsPath, replacing encode failures with the closest visual match. If the result is not valid, makes it valid.

Since: 0.1

encodeValid that throws EncodingException.

Since: 0.1

encodeValid with MonadFail.

Since: 0.1

Unsafely converts a FilePath to OsPath falling back to error.

WARNING: Partial

Since: 0.1

Decodes an OsPath to a FilePath. This is a pure version of filepath's decodeUtf.

Since: 0.1

Total conversion from OsPath to FilePath, replacing decode failures with the closest visual match.

Since: 0.1

Total conversion from OsPath to String. If decoding fails, displays the exception.

Since: 0.1

Total conversion from OsPath to String. If decoding fails, falls back to its Show instance.

Since: 0.1

decode that throws EncodingException.

Since: 0.1

decode with MonadFail.

Since: 0.1

Unsafely converts an OsPath to a FilePath falling back to error.

WARNING: Partial

Since: 0.1

Convert an OsPath to OsString. This is currently the identity function.

Since: 0.1

Convert an OsString to OsPath. Currently this merely checks isValid.

Since: 0.1

fromOsString that throws the EncodingException.

Since: 0.1

fromOsString for MonadFail.

Since: 0.1

Unsafely checks an OsString for validity, dying with error on failure.

Since: 0.1

Converts from OsString to OsPath without checking any invariants. Used for when we know an operator cannot have

Since: 0.1

Combine two paths with a path separator. If the second path starts with a path separator or a drive letter, then it returns the second. The intention is that readFile (dir </> file) will access the same file as setCurrentDirectory dir; readFile file.

Posix:   "/directory" </> "file.ext" == "/directory/file.ext"
Windows: "/directory" </> "file.ext" == "/directory\\file.ext"
         "directory" </> "/file.ext" == "/file.ext"
Valid x => (takeDirectory x </> takeFileName x) `equalFilePath` x

Combined:

Posix:   "/" </> "test" == "/test"
Posix:   "home" </> "bob" == "home/bob"
Posix:   "x:" </> "foo" == "x:/foo"
Windows: "C:\\foo" </> "bar" == "C:\\foo\\bar"
Windows: "home" </> "bob" == "home\\bob"

Not combined:

Posix:   "home" </> "/bob" == "/bob"
Windows: "home" </> "C:\\bob" == "C:\\bob"

Not combined (tricky):

On Windows, if a filepath starts with a single slash, it is relative to the root of the current drive. In [1], this is (confusingly) referred to as an absolute path. The current behavior of </> is to never combine these forms.

Windows: "home" </> "/bob" == "/bob"
Windows: "home" </> "\\bob" == "\\bob"
Windows: "C:\\home" </> "\\bob" == "\\bob"

On Windows, from [1]: "If a file name begins with only a disk designator but not the backslash after the colon, it is interpreted as a relative path to the current directory on the drive with the specified letter." The current behavior of </> is to never combine these forms.

Windows: "D:\\foo" </> "C:bar" == "C:bar"
Windows: "C:\\foo" </> "C:bar" == "C:bar"

Add an extension, even if there is already one there, equivalent to addExtension.

"/directory/path" <.> "ext" == "/directory/path.ext"
"/directory/path" <.> ".ext" == "/directory/path.ext"

Remove the current extension and add another, equivalent to replaceExtension.

"/directory/path.txt" -<.> "ext" == "/directory/path.ext"
"/directory/path.txt" -<.> ".ext" == "/directory/path.ext"
"foo.o" -<.> "c" == "foo.c"

Unsafely combines an OsPath and a FilePath via (/) with unsafeEncode.

WARNING: Partial

Since: 0.1

Unsafely combines a FilePath and an OsPath via (/) with unsafeEncode.

WARNING: Partial

Since: 0.1

Legacy alias for FilePaths' / operator. Exists because the / exported here is (</>) :: OsPath -> OsPath -> OsPath.

Since: 0.1

Retrieves the path's "tilde state".

Since: 0.1

Represents the "tilde state" for a given path.

Sum type representing a possible empty OsPath.

Since: 0.1

Exception for a path containing a tilde.