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

Safe Haskell | None
Language | Haskell2010

Darcs.Util.Path

Contents

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

Synopsis

- data FileName
- fp2fn :: FilePath -> FileName
- fn2fp :: FileName -> FilePath
- fn2ps :: FileName -> ByteString
- ps2fn :: ByteString -> FileName
- niceps2fn :: ByteString -> FileName
- fn2niceps :: FileName -> ByteString
- breakOnDir :: FileName -> Maybe (FileName, FileName)
- normPath :: FileName -> FileName
- ownName :: FileName -> FileName
- superName :: FileName -> FileName
- movedirfilename :: FileName -> FileName -> FileName -> FileName
- encodeWhite :: FilePath -> String
- decodeWhite :: String -> FilePath
- isParentOrEqOf :: FileName -> FileName -> Bool
- data AbsolutePath
- makeAbsolute :: AbsolutePath -> FilePath -> AbsolutePath
- ioAbsolute :: FilePath -> IO AbsolutePath
- rootDirectory :: 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 :: FilePath -> Maybe SubPath
- isSubPathOf :: SubPath -> SubPath -> Bool
- floatSubPath :: SubPath -> AnchoredPath
- sp2fn :: SubPath -> FileName
- class FilePathOrURL a where
- class FilePathOrURL a => FilePathLike a where
- getCurrentDirectory :: IO AbsolutePath
- setCurrentDirectory :: FilePathLike p => p -> IO ()
- getUniquePathName :: Bool -> (FilePath -> String) -> (Int -> FilePath) -> IO FilePath
- doesPathExist :: FilePath -> IO Bool
- isMaliciousPath :: String -> Bool
- isMaliciousSubPath :: String -> Bool
- filterFilePaths :: [FilePath] -> AnchoredPath -> t -> Bool
- filterPaths :: [AnchoredPath] -> AnchoredPath -> t -> Bool
- newtype Name = Name ByteString
- newtype AnchoredPath = AnchoredPath [Name]
- anchoredRoot :: AnchoredPath
- appendPath :: AnchoredPath -> Name -> AnchoredPath
- anchorPath :: FilePath -> AnchoredPath -> FilePath
- isPrefix :: AnchoredPath -> AnchoredPath -> Bool
- parent :: AnchoredPath -> AnchoredPath
- parents :: AnchoredPath -> [AnchoredPath]
- catPaths :: AnchoredPath -> AnchoredPath -> AnchoredPath
- flatten :: AnchoredPath -> ByteString
- makeName :: String -> Name
- appendToName :: AnchoredPath -> String -> AnchoredPath
- floatBS :: ByteString -> AnchoredPath
- floatPath :: FilePath -> AnchoredPath
- replacePrefixPath :: AnchoredPath -> AnchoredPath -> AnchoredPath -> AnchoredPath

# Documentation

data FileName #

FileName is an abstract type intended to facilitate the input and output of unicode filenames.

Instances

Eq FileName # |
Methods (==) :: FileName -> FileName -> Bool # (/=) :: FileName -> FileName -> Bool #
Ord FileName # |
Methods compare :: FileName -> FileName -> Ordering # (<) :: FileName -> FileName -> Bool # (<=) :: FileName -> FileName -> Bool # (>) :: FileName -> FileName -> Bool # (>=) :: FileName -> FileName -> Bool # max :: FileName -> FileName -> FileName # min :: FileName -> FileName -> FileName #
Show FileName # |
Methods showsPrec :: Int -> FileName -> ShowS # show :: FileName -> String # showList :: [FileName] -> ShowS #
Binary FileName # |
Methods put :: FileName -> Put # get :: Get FileName # putList :: [FileName] -> Put #
FilePathLike FileName # |
Methods toFilePath :: FileName -> FilePath #
FilePathOrURL FileName # |
Methods toPath :: FileName -> String #
MonadState (Set FileName, [PatchMod FileName]) FileModMonad # |
Methods get :: FileModMonad (Set FileName, [PatchMod FileName]) # put :: (Set FileName, [PatchMod FileName]) -> FileModMonad () # state :: ((Set FileName, [PatchMod FileName]) -> (a, (Set FileName, [PatchMod FileName]))) -> FileModMonad a #

fp2fn :: FilePath -> FileName #

fn2fp :: FileName -> FilePath #

fn2ps :: FileName -> ByteString #

ps2fn :: ByteString -> FileName #

niceps2fn :: ByteString -> FileName #

fn2niceps :: FileName -> ByteString #

breakOnDir :: FileName -> Maybe (FileName, FileName) #

normPath :: FileName -> FileName #

convert a path string into a sequence of directories strings "/", "." and ".." are generally interpreted as expected. Behaviour with too many '..' is to leave them.

Examples: Splitting: "aabbcc" -> ["aa","bb","cc"] Ignoring "." and extra "/": "aa.bb" -> ["aa","bb"] "aa//bb" -> ["aa","bb"] "aabb/" -> ["aa","bb"] Handling "..": "aa..bb/cc" -> ["bb","cc"] "aabb....cc" -> ["cc"] "aa..bb..cc" -> ["cc"] "../cc" -> ["..","cc"]

ownName :: FileName -> FileName #

superName :: FileName -> FileName #

movedirfilename :: FileName -> FileName -> FileName -> FileName #

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 -> FilePath #

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

    decodeWhite "hello\32\there"  == "hello there"
    decodeWhite "hello\92\there"  == "hello\there"
    decodeWhite "hello\there"   == error "malformed filename"

isParentOrEqOf :: FileName -> FileName -> Bool #

# AbsolutePath

data AbsolutePath #

Instances

Eq AbsolutePath # |
Methods (==) :: AbsolutePath -> AbsolutePath -> Bool # (/=) :: AbsolutePath -> AbsolutePath -> Bool #
Ord AbsolutePath # |
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 #
Show AbsolutePath # |
Methods showsPrec :: Int -> AbsolutePath -> ShowS # show :: AbsolutePath -> String # showList :: [AbsolutePath] -> ShowS #
FilePathLike AbsolutePath # |
Methods toFilePath :: AbsolutePath -> FilePath #
FilePathOrURL AbsolutePath # |
Methods toPath :: AbsolutePath -> String #

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.

rootDirectory :: AbsolutePath #

The root directory as an absolute path.

# 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

Eq AbsolutePathOrStd # |
Methods (==) :: AbsolutePathOrStd -> AbsolutePathOrStd -> Bool # (/=) :: AbsolutePathOrStd -> AbsolutePathOrStd -> Bool #
Ord AbsolutePathOrStd # |
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 #
Show AbsolutePathOrStd # |
Methods showsPrec :: Int -> AbsolutePathOrStd -> ShowS # show :: AbsolutePathOrStd -> String # showList :: [AbsolutePathOrStd] -> ShowS #

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

Eq AbsoluteOrRemotePath # |
Methods (==) :: AbsoluteOrRemotePath -> AbsoluteOrRemotePath -> Bool # (/=) :: AbsoluteOrRemotePath -> AbsoluteOrRemotePath -> Bool #
Ord AbsoluteOrRemotePath # |
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 #
Show AbsoluteOrRemotePath # |
Methods showsPrec :: Int -> AbsoluteOrRemotePath -> ShowS # show :: AbsoluteOrRemotePath -> String # showList :: [AbsoluteOrRemotePath] -> ShowS #
FilePathOrURL AbsoluteOrRemotePath # |
Methods toPath :: AbsoluteOrRemotePath -> String #

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

Eq SubPath # |
Methods (==) :: SubPath -> SubPath -> Bool # (/=) :: SubPath -> SubPath -> Bool #
Ord SubPath # |
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 #
Show SubPath # |
Methods showsPrec :: Int -> SubPath -> ShowS # show :: SubPath -> String # showList :: [SubPath] -> ShowS #
FilePathLike SubPath # |
Methods toFilePath :: SubPath -> FilePath #
FilePathOrURL SubPath # |
Methods toPath :: SubPath -> String #

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

Make the second path relative to the first, if possible

simpleSubPath :: FilePath -> Maybe SubPath #

isSubPathOf :: SubPath -> SubPath -> Bool #

floatSubPath :: SubPath -> AnchoredPath #

Transform a SubPath into an AnchoredPath.

# Miscellaneous

sp2fn :: SubPath -> FileName #

class FilePathOrURL a where #

Minimal complete definition

toPath

Methods

toPath :: a -> String #

Instances

FilePathOrURL AbsoluteOrRemotePath # |
Methods toPath :: AbsoluteOrRemotePath -> String #
FilePathOrURL AbsolutePath # |
Methods toPath :: AbsolutePath -> String #
FilePathOrURL SubPath # |
Methods toPath :: SubPath -> String #
FilePathOrURL FileName # |
Methods toPath :: FileName -> String #
CharLike c => FilePathOrURL [c] # |
Methods toPath :: [c] -> String #

class FilePathOrURL a => FilePathLike a where #

Minimal complete definition

toFilePath

Methods

toFilePath :: a -> FilePath #

Instances

FilePathLike AbsolutePath # |
Methods toFilePath :: AbsolutePath -> FilePath #
FilePathLike SubPath # |
Methods toFilePath :: SubPath -> FilePath #
FilePathLike FileName # |
Methods toFilePath :: FileName -> FilePath #
CharLike c => FilePathLike [c] # |
Methods toFilePath :: [c] -> FilePath #

getCurrentDirectory :: IO AbsolutePath #

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

doesPathExist :: FilePath -> IO Bool #

# Check for malicious paths

isMaliciousPath :: String -> Bool #

What is a malicious path?

A spoofed path is a malicious path.

1. Darcs only creates explicitly relative paths (beginning with `"./"`), so any not explicitly relative path is surely spoofed.
2. Darcs normalizes paths so they never contain `"/../"`, so paths with `"/../"` are surely spoofed.

A path to a darcs repository's meta data can modify "trusted" patches or change safety defaults in that repository, so we check for paths containing `"/_darcs/"` which is the entry to darcs meta data.

To do?

- How about get repositories?
- Would it be worth adding a --semi-safe-paths option for allowing changes to certain preference files (_darcs/prefs/) in sub repositories'?

isMaliciousSubPath :: String -> Bool #

Warning : this is less rigorous than isMaliciousPath but it's to allow for subpath representations that don't start with ./

# Tree filtering.

filterFilePaths :: [FilePath] -> AnchoredPath -> t -> Bool #

Same as `filterPath`, but for ordinary `FilePath`s (as opposed to AnchoredPath).

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

newtype Name #

Constructors

Name ByteString |

Instances

Eq Name # |
Methods (==) :: Name -> Name -> Bool # (/=) :: Name -> Name -> Bool #
Ord Name # |
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 #
Show Name # |
Methods showsPrec :: Int -> Name -> ShowS # show :: Name -> String # showList :: [Name] -> ShowS #

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 ("floatPath" -- but take care when doing that) or .

Constructors

AnchoredPath [Name] |

Instances

Eq AnchoredPath # |
Methods (==) :: AnchoredPath -> AnchoredPath -> Bool # (/=) :: AnchoredPath -> AnchoredPath -> Bool #
Ord AnchoredPath # |
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 #
Show AnchoredPath # |
Methods showsPrec :: Int -> AnchoredPath -> ShowS # show :: AnchoredPath -> String # showList :: [AnchoredPath] -> ShowS #
(Functor m, Monad m) => ApplyMonad Tree (TreeMonad m) # |
Associated Types type ApplyMonadBase (TreeMonad m :: * -> *) :: * -> * # Methods nestedApply :: TreeMonad m x -> Tree (ApplyMonadBase (TreeMonad m)) -> TreeMonad m (x, Tree (ApplyMonadBase (TreeMonad m))) # liftApply :: (Tree (ApplyMonadBase (TreeMonad m)) -> ApplyMonadBase (TreeMonad m) x) -> Tree (ApplyMonadBase (TreeMonad m)) -> TreeMonad m (x, Tree (ApplyMonadBase (TreeMonad m))) # getApplyState :: TreeMonad m (Tree (ApplyMonadBase (TreeMonad m))) #
(Functor m, Monad m) => TreeRW (TreeMonad m) # |
Methods writeFile :: AnchoredPath -> ByteString -> TreeMonad m () # createDirectory :: AnchoredPath -> TreeMonad m () # unlink :: AnchoredPath -> TreeMonad m () # rename :: AnchoredPath -> AnchoredPath -> TreeMonad m () # copy :: AnchoredPath -> AnchoredPath -> TreeMonad m () #
(Functor m, Monad m) => TreeRO (TreeMonad m) # |
Methods currentDirectory :: TreeMonad m AnchoredPath # withDirectory :: AnchoredPath -> TreeMonad m a -> TreeMonad m a # expandTo :: AnchoredPath -> TreeMonad m AnchoredPath readFile :: AnchoredPath -> TreeMonad m ByteString # exists :: AnchoredPath -> TreeMonad m Bool # directoryExists :: AnchoredPath -> TreeMonad m Bool # fileExists :: AnchoredPath -> TreeMonad m Bool #
(Functor m, Monad m) => MonadProgress (TreeMonad m) # |
Methods runProgressActions :: String -> [ProgressAction (TreeMonad m) ()] -> TreeMonad m () #
(Functor m, Monad m) => ApplyMonadTree (TreeMonad m) # |
Methods mDoesDirectoryExist :: FileName -> TreeMonad m Bool # mDoesFileExist :: FileName -> TreeMonad m Bool # mReadFilePS :: FileName -> TreeMonad m ByteString # mReadFilePSs :: FileName -> TreeMonad m [ByteString] # mCreateDirectory :: FileName -> TreeMonad m () # mRemoveDirectory :: FileName -> TreeMonad m () # mCreateFile :: FileName -> TreeMonad m () # mRemoveFile :: FileName -> TreeMonad m () # mRename :: FileName -> FileName -> TreeMonad m () # mModifyFilePS :: FileName -> (ByteString -> TreeMonad m ByteString) -> TreeMonad m () # mModifyFilePSs :: FileName -> ([ByteString] -> TreeMonad m [ByteString]) -> TreeMonad m () # mChangePref :: String -> String -> String -> TreeMonad m () #
type ApplyMonadBase (TreeMonad m) # |
type ApplyMonadBase (TreeMonad m) = 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.

parent :: AnchoredPath -> AnchoredPath #

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

parents :: AnchoredPath -> [AnchoredPath] #

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

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 #

makeName :: String -> Name #

appendToName :: AnchoredPath -> String -> AnchoredPath #

Append a ByteString to the last Name of an AnchoredPath.

# Unsafe AnchoredPath functions.

floatBS :: ByteString -> AnchoredPath #

Unsafe. Only ever use on bytestrings that came from flatten on a pre-existing AnchoredPath.

floatPath :: FilePath -> AnchoredPath #

Take a relative FilePath and turn it into an AnchoredPath. The operation is (relatively) unsafe. Basically, by using floatPath, you are testifying that the argument is a path relative to some common root -- i.e. the root of the associated Tree object. Also, there are certain invariants about AnchoredPath that this function tries hard to preserve, but probably cannot guarantee (i.e. this is a best-effort thing). You should sanitize any FilePaths before you declare them "good" by converting into AnchoredPath (using this function).

replacePrefixPath :: AnchoredPath -> AnchoredPath -> AnchoredPath -> AnchoredPath #

Take a prefix path, the changed prefix path, and a path to change. Assumes the prefix path is a valid prefix. If prefix is wrong return AnchoredPath [].