Filesystem.Path.Rules

system-filepath-0.4.13.4: High-level, byte-based file and directory path manipulations (deprecated)

Copyright | 2010 John Millikin
License | MIT
Maintainer | jmillikin@gmail.com
Portability | portable
Safe Haskell | Safe
Language | Haskell98

Filesystem.Path.Rules

Contents

- Type conversions
- Rule‐specific path properties

Description

Synopsis

- data Rules platformFormat
- posix :: Rules ByteString
- posix_ghc702 :: Rules ByteString
- posix_ghc704 :: Rules ByteString
- windows :: Rules Text
- darwin :: Rules Text
- darwin_ghc702 :: Rules Text
- toText :: Rules platformFormat -> FilePath -> Either Text Text
- fromText :: Rules platformFormat -> Text -> FilePath
- encode :: Rules platformFormat -> FilePath -> platformFormat
- decode :: Rules platformFormat -> platformFormat -> FilePath
- encodeString :: Rules platformFormat -> FilePath -> String
- decodeString :: Rules platformFormat -> String -> FilePath
- valid :: Rules platformFormat -> FilePath -> Bool
- splitSearchPath :: Rules platformFormat -> platformFormat -> [FilePath]
- splitSearchPathString :: Rules platformFormat -> String -> [FilePath]

# Documentation

data Rules platformFormat

The type of `platformFormat` for `Rules` is conditionally selected at compilation time. As such it is only intended for direct use with external OS functions and code that expects `platformFormat` to be stable across platforms may fail to subsequently compile on a differing platform.

For example: on Windows or OSX `platformFormat` will be `Text`, and on Linux it will be `ByteString`.

If portability is a concern, restrict usage to functions which do not expose `platformFormat` directly.

Instances

Show (Rules a) |

posix :: Rules ByteString

Linux, BSD, and other UNIX or UNIX-like operating systems.

posix_ghc702 :: Rules ByteString

Linux, BSD, and other UNIX or UNIX-like operating systems.

This is a variant of `posix` for use with GHC 7.2, which tries to decode file paths in its IO computations.

Since: 0.3.3 / 0.4.2

posix_ghc704 :: Rules ByteString

Linux, BSD, and other UNIX or UNIX-like operating systems.

This is a variant of `posix` for use with GHC 7.4 or later, which tries to decode file paths in its IO computations.

Since: 0.3.7 / 0.4.6

windows :: Rules Text

Windows and DOS

darwin :: Rules Text

Darwin and Mac OS X.

This is almost identical to `posix`, but with a native path type of `Text` rather than `ByteString`.

Since: 0.3.4 / 0.4.3

darwin_ghc702 :: Rules Text

Darwin and Mac OS X.

This is a variant of `darwin` for use with GHC 7.2 or later, which tries to decode file paths in its IO computations.

Since: 0.3.4 / 0.4.3

# Type conversions

toText :: Rules platformFormat -> FilePath -> Either Text Text

Attempt to convert a `FilePath` to human‐readable text.

If the path is decoded successfully, the result is a `Right` containing the decoded text. Successfully decoded text can be converted back to the original path using `fromText`.

If the path cannot be decoded, the result is a `Left` containing an approximation of the original path. If displayed to the user, this value should be accompanied by some warning that the path has an invalid encoding. Approximated text cannot be converted back to the original path.

This function ignores the user’s locale, and assumes all file paths are encoded in UTF8. If you need to display file paths with an unusual or obscure encoding, use `encode` and then decode them manually.

Since: 0.2

fromText :: Rules platformFormat -> Text -> FilePath

Convert human‐readable text into a `FilePath`.

This function ignores the user’s locale, and assumes all file paths are encoded in UTF8. If you need to create file paths with an unusual or obscure encoding, encode them manually and then use `decode`.

Since: 0.2

encode :: Rules platformFormat -> FilePath -> platformFormat

Convert a `FilePath` to a platform‐specific format, suitable for use with external OS functions.

Note: The type of `platformTextFormat` can change depending upon the underlying compilation platform. Consider using `toText` or `encodeString` instead. See `Rules` for more information.

Since: 0.3

decode :: Rules platformFormat -> platformFormat -> FilePath

Convert a `FilePath` from a platform‐specific format, suitable for use with external OS functions.

Note: The type of `platformTextFormat` can change depending upon the underlying compilation platform. Consider using `fromText` or `decodeString` instead. See `Rules` for more information.

Since: 0.3

encodeString :: Rules platformFormat -> FilePath -> String

Attempt to convert a `FilePath` to a string suitable for use with functions in `System.IO`. The contents of this string are platform‐dependent, and are not guaranteed to be human‐readable. For converting `FilePath`s to a human‐readable format, use `toText`.

Since: 0.3.1

decodeString :: Rules platformFormat -> String -> FilePath

Attempt to parse a `FilePath` from a string suitable for use with functions in `System.IO`. Do not use this function for parsing human‐readable paths, as the character set decoding is platform‐dependent. For converting human‐readable text to a `FilePath`, use `fromText`.

Since: 0.3.1

# Rule‐specific path properties

valid :: Rules platformFormat -> FilePath -> Bool

Check if a `FilePath` is valid; it must not contain any illegal characters, and must have a root appropriate to the current `Rules`.

splitSearchPath :: Rules platformFormat -> platformFormat -> [FilePath]

Split a search path, such as `$PATH` or `$PYTHONPATH`, into a list of `FilePath`s.

Note: The type of `platformTextFormat` can change depending upon the underlying compilation platform. Consider using `splitSearchPathString` instead. See `Rules` for more information.

splitSearchPathString :: Rules platformFormat -> String -> [FilePath]

splitSearchPathString is like `splitSearchPath`, but takes a string encoded in the format used by `System.IO`.