-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Failure-tolerant file and directory editing
--   
--   Failure-tolerant file and directory editing.
@package plan-b
@version 0.2.1


-- | Types and type classes. You usually don't need to import this module
--   because <a>System.PlanB</a> already exports everything you need.
module System.PlanB.Type

-- | We use this as a kind with two promoted constructors. The constructors
--   are used as phantom types to index <a>PbConfig</a>.
data Subject
New :: Subject
Existing :: Subject

-- | Custom behavior for cases when something already exists.
data AlreadyExistsBehavior

-- | First delete that object, then do your thing
AebOverride :: AlreadyExistsBehavior

-- | Continue to work with that object instead
AebUse :: AlreadyExistsBehavior

-- | The configuration allows to control behavior of the library in
--   details. It's a <a>Monoid</a> and so various configuration settings
--   can be combined using <a>mappend</a> while <a>mempty</a> represents
--   default behavior.
--   
--   When combining conflicting configuration settings, the value on the
--   left side of <a>mappend</a> wins:
--   
--   <pre>
--   overrideIfExists &lt;&gt; useIfExists -- will override
--   </pre>
data PbConfig :: Subject -> *

-- | The type class is for the data types that include information
--   specifying how to create temporary files and directories and whether
--   to delete them automatically or not.
class HasTemp c

-- | Specify name of temporary directory to use. The default is the system
--   temporary directory. If the directory does not exist, it will be
--   created, but won't be deleted.
tempDir :: HasTemp c => Path Abs Dir -> c

-- | Specify the template string to use to name temporary directory, see
--   <a>openTempFile</a>, default is <tt>"plan-b"</tt>.
nameTemplate :: HasTemp c => String -> c

-- | <a>preserveCorpse</a> preserves temporary files and directories when
--   exception is thrown (normally they are removed).
preserveCorpse :: HasTemp c => c

-- | By default files are moved by copying. Moving by renaming, although
--   not always possible, often more efficient. This option enables it.
moveByRenaming :: HasTemp c => c
getTempDir :: HasTemp c => c -> Maybe (Path Abs Dir)
getNameTemplate :: HasTemp c => c -> Maybe String
getPreserveCorpse :: HasTemp c => c -> Bool
getMoveByRenaming :: HasTemp c => c -> Bool

-- | The type class includes data types that contain information about what
--   to do when some object already exists. There are two scenarios
--   currently supported: override it or use it.
class CanHandleExisting c

-- | The option allows to avoid throwing exception if upon completion of
--   specified action file with given name already exists in the file
--   system.
overrideIfExists :: CanHandleExisting c => c

-- | The option will copy already existing file into temporary location, so
--   you can edit it instead of creating new file.
useIfExists :: CanHandleExisting c => c
howHandleExisting :: CanHandleExisting c => c -> Maybe AlreadyExistsBehavior
instance GHC.Enum.Bounded System.PlanB.Type.AlreadyExistsBehavior
instance GHC.Enum.Enum System.PlanB.Type.AlreadyExistsBehavior
instance GHC.Classes.Eq System.PlanB.Type.AlreadyExistsBehavior
instance Data.Semigroup.Semigroup (System.PlanB.Type.PbConfig k)
instance GHC.Base.Monoid (System.PlanB.Type.PbConfig k)
instance System.PlanB.Type.HasTemp (System.PlanB.Type.PbConfig k)
instance System.PlanB.Type.CanHandleExisting (System.PlanB.Type.PbConfig 'System.PlanB.Type.New)


-- | Failure-tolerant file and directory editing. All functions here can
--   recover from exceptions thrown while they work. They bring file-system
--   into the state it was in before specific function was called.
--   Temporary files and backups are handled automatically.
module System.PlanB

-- | Create a new file. Name of the file is taken as the second argument.
--   The third argument allows to perform actions (in simplest case just
--   creation of file), result of those actions should be new file with the
--   given file name.
--   
--   This action throws <a>alreadyExistsErrorType</a> by default instead of
--   silently overwriting already existing file, use
--   <a>overrideIfExists</a> and <a>useIfExists</a> to change this
--   behavior.
withNewFile :: (MonadIO m, MonadMask m) => PbConfig New -> Path b File -> (Path Abs File -> m a) -> m a

-- | Edit an existing file. Name of the file is taken as the second
--   argument. The third argument allows to perform actions on temporary
--   copy of the specified file.
--   
--   This action throws <a>doesNotExistErrorType</a> exception if target
--   file does not exist.
withExistingFile :: (MonadIO m, MonadMask m) => PbConfig Existing -> Path b File -> (Path Abs File -> m a) -> m a

-- | Create a new directory. Name of the directory is specified as the
--   second argument. The third argument allows to perform actions in
--   “sandboxed” version of new directory.
--   
--   This action throws <a>alreadyExistsErrorType</a> by default instead of
--   silently overwriting already existing directory, use
--   <a>overrideIfExists</a> and <a>useIfExists</a>to change this behavior.
withNewDir :: (MonadIO m, MonadMask m) => PbConfig New -> Path b Dir -> (Path Abs Dir -> m a) -> m a

-- | Edit an existing directory. Name of the directory is specified as the
--   second argument. The third argument allows to perform actions in
--   “sandboxed” copy of target directory.
--   
--   This action throws <a>doesNotExistErrorType</a> exception if target
--   directory does not exist.
withExistingDir :: (MonadIO m, MonadMask m) => PbConfig Existing -> Path b Dir -> (Path Abs Dir -> m a) -> m a

-- | Create a new container file. This is suitable for processing of all
--   sorts of archive-like objects. The first and second arguments specify
--   how to unpack directory from file and pack it back. The fourth
--   argument names the new file. The fifth argument allows to perform
--   actions knowing name of temporary directory.
--   
--   This action throws <a>alreadyExistsErrorType</a> by default instead of
--   silently overwriting already existing file, use
--   <a>overrideIfExists</a> and <a>useIfExists</a>to change this behavior.
withNewContainer :: (MonadIO m, MonadMask m) => (Path Abs File -> Path Abs Dir -> m ()) -> (Path Abs Dir -> Path b File -> m ()) -> PbConfig New -> Path b File -> (Path Abs Dir -> m a) -> m a

-- | Edit an existing container file. This is suitable for processing of
--   all sorts of archive-like objects. The first and second arguments
--   specify how to unpack directory from file and pack it back
--   (overwriting old version). Fourth argument names container file to
--   edit. The last argument allows to perform actions knowing name of
--   temporary directory.
--   
--   This action throws <a>doesNotExistErrorType</a> exception if target
--   file does not exist.
withExistingContainer :: (MonadIO m, MonadMask m) => (Path b File -> Path Abs Dir -> m ()) -> (Path Abs Dir -> Path b File -> m ()) -> PbConfig Existing -> Path b File -> (Path Abs Dir -> m a) -> m a

-- | Specify name of temporary directory to use. The default is the system
--   temporary directory. If the directory does not exist, it will be
--   created, but won't be deleted.
tempDir :: HasTemp c => Path Abs Dir -> c

-- | Specify the template string to use to name temporary directory, see
--   <a>openTempFile</a>, default is <tt>"plan-b"</tt>.
nameTemplate :: HasTemp c => String -> c

-- | <a>preserveCorpse</a> preserves temporary files and directories when
--   exception is thrown (normally they are removed).
preserveCorpse :: HasTemp c => c

-- | By default files are moved by copying. Moving by renaming, although
--   not always possible, often more efficient. This option enables it.
moveByRenaming :: HasTemp c => c

-- | The option allows to avoid throwing exception if upon completion of
--   specified action file with given name already exists in the file
--   system.
overrideIfExists :: CanHandleExisting c => c

-- | The option will copy already existing file into temporary location, so
--   you can edit it instead of creating new file.
useIfExists :: CanHandleExisting c => c