From f27becc4dfeba24152853cb575fea500d9de6391 Mon Sep 17 00:00:00 2001 From: Julian Ospald Date: Mon, 9 May 2016 17:37:16 +0200 Subject: [PATCH] Cleanup, improve docs --- src/HPath.hs | 9 ++---- src/HPath/IO.hs | 53 +++++++++++++++++++++++++++++++----- src/HPath/IO/Errors.hs | 5 ---- src/HPath/IO/Utils.hs | 2 -- src/System/Posix/FilePath.hs | 12 +++++++- 5 files changed, 60 insertions(+), 21 deletions(-) diff --git a/src/HPath.hs b/src/HPath.hs index f9c4168..0b84119 100644 --- a/src/HPath.hs +++ b/src/HPath.hs @@ -14,7 +14,6 @@ {-# LANGUAGE DeriveDataTypeable #-} {-# LANGUAGE EmptyDataDecls #-} {-# LANGUAGE PatternSynonyms #-} -{-# OPTIONS_HADDOCK ignore-exports #-} module HPath ( @@ -48,10 +47,6 @@ module HPath -- * ByteString operations ,fpToString ,userStringToFP - -- * Queries - ,hasParentDir - ,isFileName - -- * String based functions ) where @@ -211,13 +206,15 @@ parseFn filepath = -------------------------------------------------------------------------------- -- Path Conversion --- | Convert to a ByteString type. +-- | Convert any Path to a ByteString type. toFilePath :: Path b -> ByteString toFilePath (MkPath l) = l +-- | Convert an absolute Path to a ByteString type. fromAbs :: Path Abs -> ByteString fromAbs = toFilePath +-- | Convert a relative Path to a ByteString type. fromRel :: RelC r => Path r -> ByteString fromRel = toFilePath diff --git a/src/HPath/IO.hs b/src/HPath/IO.hs index 1db067e..e806870 100644 --- a/src/HPath/IO.hs +++ b/src/HPath/IO.hs @@ -8,7 +8,7 @@ -- Portability : portable -- -- This module provides high-level IO related file operations like --- copy, delete, move and so on. It only operates on `Path Abs` which +-- copy, delete, move and so on. It only operates on /Path Abs/ which -- guarantees us well-typed paths which are absolute. -- -- Some functions are just path-safe wrappers around @@ -16,7 +16,7 @@ -- and some implement functionality that doesn't have a unix -- counterpart (like `copyDirRecursive`). -- --- Some of these operations are due to their nature not _atomic_, which +-- Some of these operations are due to their nature __not atomic__, which -- means they may do multiple syscalls which form one context. Some -- of them also have to examine the filetypes explicitly before the -- syscalls, so a reasonable decision can be made. That means @@ -24,13 +24,52 @@ -- while the non-atomic operation is still happening. However, where -- possible, as few syscalls as possible are used and the underlying -- exception handling is kept. +-- +-- Note: `BlockDevice`, `CharacterDevice`, `NamedPipe` and `Socket` +-- are not explicitly supported right now. Calling any of these +-- functions on such a file may throw an exception. {-# LANGUAGE PackageImports #-} {-# LANGUAGE OverloadedStrings #-} -{-# OPTIONS_HADDOCK ignore-exports #-} - -module HPath.IO where +module HPath.IO + ( + -- * Types + FileType(..) + -- * File copying + , copyDirRecursive + , copyDirRecursiveOverwrite + , recreateSymlink + , copyFile + , copyFileOverwrite + , easyCopy + , easyCopyOverwrite + -- * File deletion + , deleteFile + , deleteDir + , deleteDirRecursive + , easyDelete + -- * File opening + , openFile + , executeFile + -- * File creation + , createRegularFile + , createDir + -- * File renaming/moving + , renameFile + , moveFile + , moveFileOverwrite + -- * File permissions + , newFilePerms + , newDirPerms + -- * Directory reading + , getDirsFiles + -- * Filetype operations + , getFileType + -- * Others + , canonicalizePath + ) + where import Control.Exception @@ -517,7 +556,7 @@ easyDelete p = do -- |Opens a file appropriately by invoking xdg-open. The file type --- is not checked. +-- is not checked. This forks a process. openFile :: Path Abs -> IO ProcessID openFile p = @@ -525,7 +564,7 @@ openFile p = SPP.forkProcess $ SPP.executeFile "xdg-open" True [fp] Nothing --- |Executes a program with the given arguments. +-- |Executes a program with the given arguments. This forks a process. executeFile :: Path Abs -- ^ program -> [ByteString] -- ^ arguments -> IO ProcessID diff --git a/src/HPath/IO/Errors.hs b/src/HPath/IO/Errors.hs index 6517029..fe1b0d2 100644 --- a/src/HPath/IO/Errors.hs +++ b/src/HPath/IO/Errors.hs @@ -11,7 +11,6 @@ {-# LANGUAGE DeriveDataTypeable #-} {-# LANGUAGE ScopedTypeVariables #-} -{-# OPTIONS_HADDOCK ignore-exports #-} module HPath.IO.Errors where @@ -42,10 +41,6 @@ import GHC.IO.Exception ) import HPath import HPath.IO.Utils -{- import HPath.IO -} - {- ( -} - {- canonicalizePath -} - {- ) -} import System.IO.Error ( catchIOError diff --git a/src/HPath/IO/Utils.hs b/src/HPath/IO/Utils.hs index d49259d..2eab3b5 100644 --- a/src/HPath/IO/Utils.hs +++ b/src/HPath/IO/Utils.hs @@ -9,8 +9,6 @@ -- -- Random and general IO/monad utilities. -{-# OPTIONS_HADDOCK ignore-exports #-} - module HPath.IO.Utils where diff --git a/src/System/Posix/FilePath.hs b/src/System/Posix/FilePath.hs index 61e593b..ec03f10 100644 --- a/src/System/Posix/FilePath.hs +++ b/src/System/Posix/FilePath.hs @@ -18,6 +18,7 @@ module System.Posix.FilePath ( + -- * Separators pathSeparator , isPathSeparator , searchPathSeparator @@ -25,6 +26,7 @@ module System.Posix.FilePath ( , extSeparator , isExtSeparator + -- * File extensions , splitExtension , takeExtension , replaceExtension @@ -36,6 +38,7 @@ module System.Posix.FilePath ( , dropExtensions , takeExtensions + -- * Filenames/Directory names , splitFileName , takeFileName , replaceFileName @@ -44,17 +47,23 @@ module System.Posix.FilePath ( , replaceBaseName , takeDirectory , replaceDirectory + + -- * Path combinators and splitters , combine , () , splitPath , joinPath -, normalise , splitDirectories + -- * Path conversions +, normalise + + -- * Trailing path separator , hasTrailingPathSeparator , addTrailingPathSeparator , dropTrailingPathSeparator + -- * Queries , isRelative , isAbsolute , isValid @@ -63,6 +72,7 @@ module System.Posix.FilePath ( , equalFilePath , hiddenFile + -- * Type conversion , fpToString , userStringToFP