canonical-filepath-1.0.0.1: Abstract data type for canonical file paths.

Portabilityportable
Stabilitystable
Maintainernominolo@googlemail.com

System.FilePath.Canonical

Contents

Description

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).

Synopsis

Abstract Type

data CanonicalFilePath Source

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.

Creation

canonical :: FilePath -> IO CanonicalFilePathSource

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

Unsafe/Internal Operations

unsafeCanonicaliseSource

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.