System.FilePath.Canonical

Abstract data type for canonical file paths.

Due to the context sensitive way in which file paths are specified on today's computer systems it is useful to have the notion of a canonical FilePath.

The basic feature is that two canonical file paths cfp1 and cfp2 refer to the same file if and only if cfp1 == cfp2. This property can be achieved using canonicalizePath. However, if given an arbitrary FilePath we don't know whether it is canonical so having a separate type is useful. Secondly, canonicalizePath might fail if the target path does not exist on the system.

This module therefore provides an abstract type that represents paths that have been canonicalised. The intended use straightforward, just use canonical to create a CanonicalFilePath.

example = do 
  cfp1 <- canonical "./foo"
  curr <- getCurrentDirectory
  cfp2 <- canonical (curr </> "foo")
  print (cfp1 == cfp2)  -- should print "True"

To extract a canonical FilePath use canonicalFilePath (don't use show).

Abstract Type

data CanonicalFilePath

A canonical FilePath.

Construct values of this type using the canonical function.

Note that it is not always possible to guarantee a truly canonical path due to various file system features. For more information see the documentation of realpath in your favourite man page.

Instances

Eq CanonicalFilePath

Ord CanonicalFilePath

Show CanonicalFilePath

NFData CanonicalFilePath

Creation

canonical :: FilePath -> IO CanonicalFilePath

Construct a canonical file path from the given path.

Unlike canonicalizePath this operation works even if the file or its containing directory does not exist, but it may fail due to other reasons (e.g., permission errors).

Deconstruction

originalFilePath :: CanonicalFilePath -> FilePath

The original input to canonical.

canonicalFilePath :: CanonicalFilePath -> FilePath

The canonical path.

Unsafe/Internal Operations

unsafeCanonicalise

Arguments

:: FilePath

Original file path

-> FilePath

Canonical file path.

-> CanonicalFilePath

Unsafely constructs a CanonicalFilePath.

It is unsafe in the sense that it is up to the caller to guarantee that the second argument is indeed a canonical file path.

This function is intended mainly to aid in writing custom serialisation instances.