filepath: Library for manipulating FilePaths in a cross platform way.

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

This package provides functionality for manipulating FilePath values, and is shipped with GHC. It provides two variants for filepaths:

  1. legacy filepaths: type FilePath = String

  2. operating system abstracted filepaths (OsPath): internally unpinned ShortByteString (platform-dependent encoding)

It is recommended to use OsPath when possible, because it is more correct.

For each variant there are three main modules:

System.OsString is like System.OsPath, but more general purpose. Refer to the documentation of those modules for more information.


[Skip to Readme]

Properties

Versions 1.0, 1.1.0.0, 1.1.0.1, 1.1.0.2, 1.1.0.3, 1.1.0.4, 1.2.0.0, 1.2.0.1, 1.3.0.0, 1.3.0.1, 1.3.0.2, 1.4.0.0, 1.4.1.0, 1.4.1.1, 1.4.1.2, 1.4.2, 1.4.2.1, 1.4.2.2, 1.4.99.3, 1.4.100.0, 1.4.100.1, 1.4.100.2, 1.4.100.3, 1.4.100.4, 1.4.101.0, 1.4.200.0, 1.4.200.1, 1.4.300.1, 1.4.300.2, 1.5.0.0, 1.5.2.0, 1.5.3.0
Change log changelog.md
Dependencies base (>=4.9 && <4.18), bytestring (>=0.11.3.0), deepseq, exceptions, template-haskell [details]
License BSD-3-Clause
Copyright Neil Mitchell 2005-2020, Julain Ospald 2021-2022
Author Neil Mitchell <ndmitchell@gmail.com>
Maintainer Julian Ospald <hasufell@posteo.de>
Category System
Home page https://gitlab.haskell.org/haskell/filepath/-/blob/master/README.md
Bug tracker https://gitlab.haskell.org/haskell/filepath/-/issues
Source repo head: git clone https://gitlab.haskell.org/haskell/filepath
Uploaded by maerwald at 2022-07-01T23:22:36Z

Modules

[Index] [Quick Jump]

Flags

Manual Flags

NameDescriptionDefault
cpphs

Use cpphs (fixes haddock source links)

Disabled

Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


Readme for filepath-1.4.99.3

[back to package description]

FilePath Hackage version

The filepath package provides functionality for manipulating FilePath values, and is shipped with GHC. It provides two variants for filepaths:

  1. legacy filepaths: type FilePath = String
  2. operating system abstracted filepaths (OsPath): internally unpinned ShortByteString (platform-dependent encoding)

It is recommended to use OsPath when possible, because it is more correct.

For each variant there are three main modules:

All three modules provide the same API, and the same documentation (calling out differences in the different variants).

System.OsString is like System.OsPath, but more general purpose. Refer to the documentation of those modules for more information.

What is a FilePath?

In Haskell, the legacy definition (used in base and Prelude) is type FilePath = String, where a Haskell String is a list of Unicode code points.

The new definition is (simplified) newtype OsPath = AFP ShortByteString, where ShortByteString is an unpinned byte array and follows syscall conventions, preserving the encoding.

On unix, filenames don't have a predefined encoding as per the POSIX specification and are passed as char[] to syscalls.

On windows (at least the API used by Win32) filepaths are UTF-16LE strings.

You are encouraged to use OsPath whenever possible, because it is more correct.

Also note that this is a low-level library and it makes no attempt at providing a more type safe variant for filepaths (e.g. by distinguishing between absolute and relative paths) and ensures no invariants (such as filepath validity).

For such libraries, check out the following: