darcs-2.18.2: a distributed, interactive, smart revision control system

Safe Haskell | None
Language | Haskell2010

Darcs.Util.Path

Contents

- AbsolutePath
- AbsolutePathOrStd
- AbsoluteOrRemotePath
- SubPath
- Miscellaneous
- Tree filtering.
- AnchoredPaths: relative paths within a Tree. All paths are
- Unsafe AnchoredPath functions.

Synopsis

- encodeWhite :: FilePath -> String
- decodeWhite :: String -> Either String FilePath
- encodeWhiteName :: Name -> ByteString
- decodeWhiteName :: ByteString -> Either String Name
- data AbsolutePath
- makeAbsolute :: AbsolutePath -> FilePath -> AbsolutePath
- ioAbsolute :: FilePath -> IO AbsolutePath
- data AbsolutePathOrStd
- makeAbsoluteOrStd :: AbsolutePath -> String -> AbsolutePathOrStd
- ioAbsoluteOrStd :: String -> IO AbsolutePathOrStd
- useAbsoluteOrStd :: (AbsolutePath -> a) -> a -> AbsolutePathOrStd -> a
- stdOut :: AbsolutePathOrStd
- data AbsoluteOrRemotePath
- ioAbsoluteOrRemote :: String -> IO AbsoluteOrRemotePath
- isRemote :: AbsoluteOrRemotePath -> Bool
- data SubPath
- makeSubPathOf :: AbsolutePath -> AbsolutePath -> Maybe SubPath
- simpleSubPath :: HasCallStack => FilePath -> Maybe SubPath
- floatSubPath :: SubPath -> Either String AnchoredPath
- makeRelativeTo :: HasCallStack => AbsolutePath -> AbsolutePath -> IO (Maybe SubPath)
- class FilePathOrURL a where
  - toPath :: a -> String
- class FilePathOrURL a => FilePathLike a where
  - toFilePath :: a -> FilePath
- getCurrentDirectory :: IO AbsolutePath
- setCurrentDirectory :: (HasCallStack, FilePathLike p) => p -> IO ()
- getUniquePathName :: Bool -> (FilePath -> String) -> (Int -> FilePath) -> IO FilePath
- filterPaths :: [AnchoredPath] -> AnchoredPath -> t -> Bool
- data Name
- name2fp :: Name -> FilePath
- makeName :: String -> Either String Name
- rawMakeName :: ByteString -> Either String Name
- eqAnycase :: Name -> Name -> Bool
- newtype AnchoredPath = AnchoredPath [Name]
- anchoredRoot :: AnchoredPath
- appendPath :: AnchoredPath -> Name -> AnchoredPath
- anchorPath :: FilePath -> AnchoredPath -> FilePath
- isPrefix :: AnchoredPath -> AnchoredPath -> Bool
- movedirfilename :: AnchoredPath -> AnchoredPath -> AnchoredPath -> AnchoredPath
- parent :: AnchoredPath -> Maybe AnchoredPath
- parents :: AnchoredPath -> [AnchoredPath]
- replaceParent :: AnchoredPath -> AnchoredPath -> Maybe AnchoredPath
- catPaths :: AnchoredPath -> AnchoredPath -> AnchoredPath
- flatten :: AnchoredPath -> ByteString
- inDarcsdir :: AnchoredPath -> Bool
- displayPath :: AnchoredPath -> FilePath
- realPath :: AnchoredPath -> FilePath
- isRoot :: AnchoredPath -> Bool
- darcsdirName :: Name
- floatPath :: FilePath -> Either String AnchoredPath
- unsafeFloatPath :: HasCallStack => FilePath -> AnchoredPath

# Documentation

encodeWhite :: FilePath -> String #

`encodeWhite` translates whitespace in filenames to a darcs-specific format (numerical representation according to `ord` surrounded by backslashes). Note that backslashes are also escaped since they are used in the encoding.

    encodeWhite "hello there" == "hello\32\there"
    encodeWhite "hello\there" == "hello\92\there"

decodeWhite :: String -> Either String FilePath #

`decodeWhite` interprets the Darcs-specific "encoded" filenames produced by `encodeWhite`

    decodeWhite "hello\32\there"  == Right "hello there"
    decodeWhite "hello\92\there"  == Right "hello\there"
    decodeWhite "hello\there"   == Left "malformed filename"

encodeWhiteName :: Name -> ByteString #

decodeWhiteName :: ByteString -> Either String Name #

# AbsolutePath

data AbsolutePath #

#### Instances

Instances details

Show AbsolutePath # |
Instance details Defined in Darcs.Util.Path Methods showsPrec :: Int -> AbsolutePath -> ShowS # show :: AbsolutePath -> String # showList :: [AbsolutePath] -> ShowS #
FilePathLike AbsolutePath # |
Instance details Defined in Darcs.Util.Path Methods toFilePath :: AbsolutePath -> FilePath #
FilePathOrURL AbsolutePath # |
Instance details Defined in Darcs.Util.Path Methods toPath :: AbsolutePath -> String #
Eq AbsolutePath # |
Instance details Defined in Darcs.Util.Path Methods (==) :: AbsolutePath -> AbsolutePath -> Bool # (/=) :: AbsolutePath -> AbsolutePath -> Bool #
Ord AbsolutePath # |
Instance details Defined in Darcs.Util.Path Methods compare :: AbsolutePath -> AbsolutePath -> Ordering # (<) :: AbsolutePath -> AbsolutePath -> Bool # (<=) :: AbsolutePath -> AbsolutePath -> Bool # (>) :: AbsolutePath -> AbsolutePath -> Bool # (>=) :: AbsolutePath -> AbsolutePath -> Bool # max :: AbsolutePath -> AbsolutePath -> AbsolutePath # min :: AbsolutePath -> AbsolutePath -> AbsolutePath #

makeAbsolute :: AbsolutePath -> FilePath -> AbsolutePath #

Take an absolute path and a string representing a (possibly relative) path and combine them into an absolute path. If the second argument is already absolute, then the first argument gets ignored. This function also takes care that the result is converted to Posix convention and normalized. Also, parent directories ("..") at the front of the string argument get canceled out against trailing directory parts of the absolute path argument.

Regarding the last point, someone more familiar with how these functions are used should verify that this is indeed necessary or at least useful.

ioAbsolute :: FilePath -> IO AbsolutePath #

Interpret a possibly relative path wrt the current working directory. This also canonicalizes the path, resolving symbolic links etc.

# AbsolutePathOrStd

data AbsolutePathOrStd #

This is for situations where a string (e.g. a command line argument) may take the value "-" to mean stdin or stdout (which one depends on context) instead of a normal file path.

#### Instances

Instances details

Show AbsolutePathOrStd # |
Instance details Defined in Darcs.Util.Path Methods showsPrec :: Int -> AbsolutePathOrStd -> ShowS # show :: AbsolutePathOrStd -> String # showList :: [AbsolutePathOrStd] -> ShowS #
Eq AbsolutePathOrStd # |
Instance details Defined in Darcs.Util.Path Methods (==) :: AbsolutePathOrStd -> AbsolutePathOrStd -> Bool # (/=) :: AbsolutePathOrStd -> AbsolutePathOrStd -> Bool #
Ord AbsolutePathOrStd # |

Instance details

Defined in Darcs.Util.Path

Methods

compare :: AbsolutePathOrStd -> AbsolutePathOrStd -> Ordering #

(<) :: AbsolutePathOrStd -> AbsolutePathOrStd -> Bool #

(<=) :: AbsolutePathOrStd -> AbsolutePathOrStd -> Bool #

(>) :: AbsolutePathOrStd -> AbsolutePathOrStd -> Bool #

(>=) :: AbsolutePathOrStd -> AbsolutePathOrStd -> Bool #

max :: AbsolutePathOrStd -> AbsolutePathOrStd -> AbsolutePathOrStd #

min :: AbsolutePathOrStd -> AbsolutePathOrStd -> AbsolutePathOrStd #

makeAbsoluteOrStd :: AbsolutePath -> String -> AbsolutePathOrStd #

ioAbsoluteOrStd :: String -> IO AbsolutePathOrStd #

useAbsoluteOrStd :: (AbsolutePath -> a) -> a -> AbsolutePathOrStd -> a #

Execute either the first or the second argument action, depending on whether the given path is an `AbsolutePath` or stdin/stdout.

stdOut :: AbsolutePathOrStd #

# AbsoluteOrRemotePath

data AbsoluteOrRemotePath #

#### Instances

Instances details

Show AbsoluteOrRemotePath # |
Instance details Defined in Darcs.Util.Path Methods showsPrec :: Int -> AbsoluteOrRemotePath -> ShowS # show :: AbsoluteOrRemotePath -> String # showList :: [AbsoluteOrRemotePath] -> ShowS #
FilePathOrURL AbsoluteOrRemotePath # |
Instance details Defined in Darcs.Util.Path Methods toPath :: AbsoluteOrRemotePath -> String #
Eq AbsoluteOrRemotePath # |
Instance details Defined in Darcs.Util.Path Methods (==) :: AbsoluteOrRemotePath -> AbsoluteOrRemotePath -> Bool # (/=) :: AbsoluteOrRemotePath -> AbsoluteOrRemotePath -> Bool #
Ord AbsoluteOrRemotePath # |

Instance details

Defined in Darcs.Util.Path

Methods

compare :: AbsoluteOrRemotePath -> AbsoluteOrRemotePath -> Ordering #

(<) :: AbsoluteOrRemotePath -> AbsoluteOrRemotePath -> Bool #

(<=) :: AbsoluteOrRemotePath -> AbsoluteOrRemotePath -> Bool #

(>) :: AbsoluteOrRemotePath -> AbsoluteOrRemotePath -> Bool #

(>=) :: AbsoluteOrRemotePath -> AbsoluteOrRemotePath -> Bool #

max :: AbsoluteOrRemotePath -> AbsoluteOrRemotePath -> AbsoluteOrRemotePath #

min :: AbsoluteOrRemotePath -> AbsoluteOrRemotePath -> AbsoluteOrRemotePath #

ioAbsoluteOrRemote :: String -> IO AbsoluteOrRemotePath #

isRemote :: AbsoluteOrRemotePath -> Bool #

# SubPath

data SubPath #

Paths which are relative to the local darcs repository and normalized. Note: These are understood not to have the dot in front.

#### Instances

Instances details

Show SubPath # |
Instance details Defined in Darcs.Util.Path Methods showsPrec :: Int -> SubPath -> ShowS # show :: SubPath -> String # showList :: [SubPath] -> ShowS #
FilePathLike SubPath # |
Instance details Defined in Darcs.Util.Path Methods toFilePath :: SubPath -> FilePath #
FilePathOrURL SubPath # |
Instance details Defined in Darcs.Util.Path Methods toPath :: SubPath -> String #
Eq SubPath # |
Instance details Defined in Darcs.Util.Path Methods (==) :: SubPath -> SubPath -> Bool # (/=) :: SubPath -> SubPath -> Bool #
Ord SubPath # |
Instance details Defined in Darcs.Util.Path Methods compare :: SubPath -> SubPath -> Ordering # (<) :: SubPath -> SubPath -> Bool # (<=) :: SubPath -> SubPath -> Bool # (>) :: SubPath -> SubPath -> Bool # (>=) :: SubPath -> SubPath -> Bool # max :: SubPath -> SubPath -> SubPath # min :: SubPath -> SubPath -> SubPath #

makeSubPathOf :: AbsolutePath -> AbsolutePath -> Maybe SubPath #

Make the second path relative to the first, if possible. Note that this returns an empty `SubPath` if the inputs are equal.

simpleSubPath :: HasCallStack => FilePath -> Maybe SubPath #

floatSubPath :: SubPath -> Either String AnchoredPath #

Transform a SubPath into an AnchoredPath.

makeRelativeTo :: HasCallStack => AbsolutePath -> AbsolutePath -> IO (Maybe SubPath) #

The first argument must be the absolute path of a `directory`, the second is an arbitrary absolute `path`. Find the longest prefix of `path` that points to the same `directory`; if there is none, return `Nothing`, else return `Just` the remainder.

# Miscellaneous

class FilePathOrURL a where #

Methods

toPath :: a -> String #

#### Instances

Instances details

FilePathOrURL FilePath # |
Instance details Defined in Darcs.Util.Path Methods toPath :: FilePath -> String #
FilePathOrURL AbsoluteOrRemotePath # |
Instance details Defined in Darcs.Util.Path Methods toPath :: AbsoluteOrRemotePath -> String #
FilePathOrURL AbsolutePath # |
Instance details Defined in Darcs.Util.Path Methods toPath :: AbsolutePath -> String #
FilePathOrURL SubPath # |
Instance details Defined in Darcs.Util.Path Methods toPath :: SubPath -> String #

class FilePathOrURL a => FilePathLike a where #

Methods

toFilePath :: a -> FilePath #

#### Instances

Instances details

FilePathLike FilePath # |
Instance details Defined in Darcs.Util.Path Methods toFilePath :: FilePath -> FilePath #
FilePathLike AbsolutePath # |
Instance details Defined in Darcs.Util.Path Methods toFilePath :: AbsolutePath -> FilePath #
FilePathLike SubPath # |
Instance details Defined in Darcs.Util.Path Methods toFilePath :: SubPath -> FilePath #

getCurrentDirectory :: IO AbsolutePath #

setCurrentDirectory :: (HasCallStack, FilePathLike p) => p -> IO () #

getUniquePathName :: Bool -> (FilePath -> String) -> (Int -> FilePath) -> IO FilePath #

Iteratively tries find first non-existing path generated by buildName, it feeds to buildName the number starting with -1. When it generates non-existing path and it isn't first, it displays the message created with buildMsg. Usually used for generation of the name like path_number when path already exist (e.g. darcs.net_0).

# Tree filtering.

filterPaths :: [AnchoredPath] -> AnchoredPath -> t -> Bool #

Construct a filter from a list of AnchoredPaths, that will accept any path that is either a parent or a child of any of the listed paths, and discard everything else.

# AnchoredPaths: relative paths within a Tree. All paths are

data Name #

#### Instances

Instances details

Show Name # |
Instance details Defined in Darcs.Util.Path Methods showsPrec :: Int -> Name -> ShowS # show :: Name -> String # showList :: [Name] -> ShowS #
Binary Name # |
Instance details Defined in Darcs.Util.Path Methods put :: Name -> Put # get :: Get Name # putList :: [Name] -> Put #
Eq Name # |
Instance details Defined in Darcs.Util.Path Methods (==) :: Name -> Name -> Bool # (/=) :: Name -> Name -> Bool #
Ord Name # |
Instance details Defined in Darcs.Util.Path Methods compare :: Name -> Name -> Ordering # (<) :: Name -> Name -> Bool # (<=) :: Name -> Name -> Bool # (>) :: Name -> Name -> Bool # (>=) :: Name -> Name -> Bool # max :: Name -> Name -> Name # min :: Name -> Name -> Name #

name2fp :: Name -> FilePath #

makeName :: String -> Either String Name #

Make a `Name` from a `String`. May fail if the input `String` is invalid, that is, "", ".", "..", or contains a `/`.

rawMakeName :: ByteString -> Either String Name #

Make a `Name` from a `ByteString`.

eqAnycase :: Name -> Name -> Bool #

newtype AnchoredPath #

This is a type of "sane" file paths. These are always canonic in the sense that there are no stray slashes, no ".." components and similar. They are usually used to refer to a location within a Tree, but a relative filesystem path works just as well. These are either constructed from individual name components (using "appendPath", "catPaths" and "makeName"), or converted from a FilePath ("unsafeFloatPath" -- but take care when doing that).

Constructors

AnchoredPath [Name] |

#### Instances

Instances details

Show AnchoredPath # |
Instance details Defined in Darcs.Util.Path Methods showsPrec :: Int -> AnchoredPath -> ShowS # show :: AnchoredPath -> String # showList :: [AnchoredPath] -> ShowS #
Binary AnchoredPath # |
Instance details Defined in Darcs.Util.Path Methods put :: AnchoredPath -> Put # get :: Get AnchoredPath # putList :: [AnchoredPath] -> Put #
ObjectId AnchoredPath # |
Instance details Defined in Darcs.Patch.Object Methods formatObjectId :: FileNameFormat -> AnchoredPath -> Doc #
Eq AnchoredPath # |
Instance details Defined in Darcs.Util.Path Methods (==) :: AnchoredPath -> AnchoredPath -> Bool # (/=) :: AnchoredPath -> AnchoredPath -> Bool #
Ord AnchoredPath # |
Instance details Defined in Darcs.Util.Path Methods compare :: AnchoredPath -> AnchoredPath -> Ordering # (<) :: AnchoredPath -> AnchoredPath -> Bool # (<=) :: AnchoredPath -> AnchoredPath -> Bool # (>) :: AnchoredPath -> AnchoredPath -> Bool # (>=) :: AnchoredPath -> AnchoredPath -> Bool # max :: AnchoredPath -> AnchoredPath -> AnchoredPath # min :: AnchoredPath -> AnchoredPath -> AnchoredPath #
MonadThrow m => ApplyMonad Tree (TreeMonad m) # |
Instance details Defined in Darcs.Patch.ApplyMonad Methods readFilePS :: ObjectIdOf Tree -> TreeMonad m ByteString #
MonadThrow m => ApplyMonadTree (TreeMonad m) # |

Instance details

Defined in Darcs.Patch.ApplyMonad

Methods

mDoesDirectoryExist :: AnchoredPath -> TreeMonad m Bool #

mDoesFileExist :: AnchoredPath -> TreeMonad m Bool #

mReadFilePS :: AnchoredPath -> TreeMonad m ByteString #

mCreateDirectory :: AnchoredPath -> TreeMonad m () #

mRemoveDirectory :: AnchoredPath -> TreeMonad m () #

mCreateFile :: AnchoredPath -> TreeMonad m () #

mRemoveFile :: AnchoredPath -> TreeMonad m () #

mRename :: AnchoredPath -> AnchoredPath -> TreeMonad m () #

mModifyFilePS :: AnchoredPath -> (ByteString -> TreeMonad m ByteString) -> TreeMonad m () #

mChangePref :: String -> String -> String -> TreeMonad m () #

anchoredRoot :: AnchoredPath #

appendPath :: AnchoredPath -> Name -> AnchoredPath #

Append an element to the end of a path.

anchorPath :: FilePath -> AnchoredPath -> FilePath #

Take a "root" directory and an anchored path and produce a full `FilePath`. Moreover, you can use `anchorPath ""` to get a relative `FilePath`.

isPrefix :: AnchoredPath -> AnchoredPath -> Bool #

Check whether a path is a prefix of another path.

movedirfilename :: AnchoredPath -> AnchoredPath -> AnchoredPath -> AnchoredPath #

The effect of renaming on paths. The first argument is the old path, the second is the new path, and the third is the possibly affected path we are interested in.

parent :: AnchoredPath -> Maybe AnchoredPath #

Get parent (path) of a given path. foobarbaz -> foo/bar

parents :: AnchoredPath -> [AnchoredPath] #

List all (proper) parents of a given path. foobarbaz -> [.,foo, foo/bar]

replaceParent :: AnchoredPath -> AnchoredPath -> Maybe AnchoredPath #

Replace the second arg's parent with the first arg.

catPaths :: AnchoredPath -> AnchoredPath -> AnchoredPath #

Catenate two paths together. Not very safe, but sometimes useful (e.g. when you are representing paths relative to a different point than a Tree root).

flatten :: AnchoredPath -> ByteString #

inDarcsdir :: AnchoredPath -> Bool #

Is the given path in (or equal to) the _darcs metadata directory?

displayPath :: AnchoredPath -> FilePath #

For displaying paths to the user. It should never be used for on-disk patch storage. This adds the "./" for consistency with how repo paths are displayed by `showPatch` and friends, except for the root path which is displayed as plain ".".

realPath :: AnchoredPath -> FilePath #

Interpret an `AnchoredPath` as relative the current working directory. Intended for IO operations in the file system. Use with care!

isRoot :: AnchoredPath -> Bool #

darcsdirName :: Name #

floatPath :: FilePath -> Either String AnchoredPath #

# Unsafe AnchoredPath functions.

unsafeFloatPath :: HasCallStack => FilePath -> AnchoredPath #

Take a relative FilePath and turn it into an AnchoredPath. This is a partial function. Basically, by using unsafeFloatPath, you are testifying that the argument is a path relative to some common root -- i.e. the root of the associated Tree object. In particular, the input path may not contain any ocurrences of "." or ".." after normalising. You should sanitize any FilePaths before you declare them "good" by converting into AnchoredPath (using this function), especially if the FilePath come from any external source (command line, file, environment, network, etc)