Hackage :: [Package]

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

[ bsd3, library, system ] [ Propose Tags ] [ Report a vulnerability ]

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:

For more powerful string manipulation of OsPath, you can use the os-string package (OsPath is a type synonym for OsString).

An introduction into the new API can be found in this blog post. Code examples for the new API can be found here.

[Skip to Readme]

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

Versions [RSS] 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.100.0, 1.4.100.1, 1.4.100.2, 1.4.100.3, 1.4.100.4, 1.4.101.0, 1.4.102.0, 1.4.200.0, 1.4.200.1, 1.4.300.1, 1.4.300.2, 1.4.301.0, 1.5.0.0, 1.5.2.0, 1.5.3.0, 1.5.4.0 (info)
Change log changelog.md
Dependencies base (>=4.12.0.0 && <4.22), bytestring (>=0.11.3.0), deepseq, exceptions, os-string (>=2.0.1), template-haskell [details]
Tested with ghc ==8.6.5 || ==8.8.4 || ==8.10.7 || ==9.0.2 || ==9.2.8 || ==9.4.8 || ==9.6.3 || ==9.8.1
License BSD-3-Clause
Copyright Neil Mitchell 2005-2020, Julian Ospald 2021-2022
Author Neil Mitchell <ndmitchell@gmail.com>
Maintainer Julian Ospald <hasufell@posteo.de>
Category System
Home page https://github.com/haskell/filepath/blob/master/README.md
Bug tracker https://github.com/haskell/filepath/issues
Source repo head: git clone https://github.com/haskell/filepath
Uploaded by maerwald at 2024-11-17T13:06:16Z
Distributions Arch:1.4.2.2, Fedora:1.4.2.2
Reverse Dependencies 1775 direct, 13162 indirect [details]
Downloads 67116 total (724 in the last 30 days)
Rating 2.25 (votes: 2) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2024-11-17 [all 1 reports]

Readme for filepath-1.5.4.0

[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:

  • System.FilePath.Posix / System.OsPath.Posix manipulates POSIX/Linux style FilePath values (with / as the path separator).
  • System.FilePath.Windows / System.OsPath.Windows manipulates Windows style FilePath values (with either \ or / as the path separator, and deals with drives).
  • System.FilePath / System.OsPath for dealing with current platform-specific filepaths

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: