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


-- | Interface for versioning file stores.
--   
--   The filestore library provides an abstract interface for a versioning
--   file store, and modules that instantiate this interface. Currently
--   Git, Darcs, and Mercurial modules are provided, and other VCSs or
--   databases could be added.
@package filestore
@version 0.6.5.1


-- | Type definitions for <a>Data.FileStore</a>.
module Data.FileStore.Types
type RevisionId = String
data Resource
FSFile :: FilePath -> Resource
FSDirectory :: FilePath -> Resource
data Author
Author :: String -> String -> Author
[authorName] :: Author -> String
[authorEmail] :: Author -> String
data Change
Added :: FilePath -> Change
Deleted :: FilePath -> Change
Modified :: FilePath -> Change
type Description = String
data Revision
Revision :: RevisionId -> UTCTime -> Author -> Description -> [Change] -> Revision
[revId] :: Revision -> RevisionId
[revDateTime] :: Revision -> UTCTime
[revAuthor] :: Revision -> Author
[revDescription] :: Revision -> Description
[revChanges] :: Revision -> [Change]
class Contents a
fromByteString :: Contents a => ByteString -> a
toByteString :: Contents a => a -> ByteString
data TimeRange
TimeRange :: Maybe UTCTime -> Maybe UTCTime -> TimeRange

-- | <tt>Nothing</tt> means no lower bound
[timeFrom] :: TimeRange -> Maybe UTCTime

-- | <tt>Nothing</tt> means no upper bound
[timeTo] :: TimeRange -> Maybe UTCTime
data MergeInfo
MergeInfo :: Revision -> Bool -> String -> MergeInfo

-- | The revision w/ which changes were merged
[mergeRevision] :: MergeInfo -> Revision

-- | <tt>True</tt> if there were merge conflicts
[mergeConflicts] :: MergeInfo -> Bool

-- | The merged text, w/ conflict markers
[mergeText] :: MergeInfo -> String
data FileStoreError

-- | Tried to initialize a repo that exists
RepositoryExists :: FileStoreError

-- | Tried to create a resource that exists
ResourceExists :: FileStoreError

-- | Requested resource was not found
NotFound :: FileStoreError

-- | The specified resource name is illegal
IllegalResourceName :: FileStoreError

-- | The resource was not modified, because the contents were unchanged
Unchanged :: FileStoreError
UnsupportedOperation :: FileStoreError

-- | The darcs version used does not support --max-count
NoMaxCount :: FileStoreError
UnknownError :: String -> FileStoreError
data SearchMatch
SearchMatch :: FilePath -> Integer -> String -> SearchMatch
[matchResourceName] :: SearchMatch -> FilePath
[matchLineNumber] :: SearchMatch -> Integer
[matchLine] :: SearchMatch -> String
data SearchQuery
SearchQuery :: [String] -> Bool -> Bool -> Bool -> SearchQuery

-- | Patterns to match
[queryPatterns] :: SearchQuery -> [String]

-- | Match patterns only with whole words?
[queryWholeWords] :: SearchQuery -> Bool

-- | Return matches only from files in which all patterns match?
[queryMatchAll] :: SearchQuery -> Bool

-- | Make matches case-insensitive?
[queryIgnoreCase] :: SearchQuery -> Bool
defaultSearchQuery :: SearchQuery
data UTCTime

-- | A versioning filestore, which can be implemented using the file
--   system, a database, or revision-control software.
data FileStore
FileStore :: IO () -> (forall a. Contents a => FilePath -> Author -> Description -> a -> IO ()) -> (forall a. Contents a => FilePath -> Maybe RevisionId -> IO a) -> (FilePath -> Author -> Description -> IO ()) -> (FilePath -> FilePath -> Author -> Description -> IO ()) -> ([FilePath] -> TimeRange -> Maybe Int -> IO [Revision]) -> (FilePath -> IO RevisionId) -> (RevisionId -> IO Revision) -> IO [FilePath] -> (FilePath -> IO [Resource]) -> (RevisionId -> RevisionId -> Bool) -> (SearchQuery -> IO [SearchMatch]) -> FileStore

-- | Initialize a new filestore.
[initialize] :: FileStore -> IO ()

-- | Save contents in the filestore.
[save] :: FileStore -> forall a. Contents a => FilePath -> Author -> Description -> a -> IO ()

-- | Retrieve the contents of the named resource.
[retrieve] :: FileStore -> forall a. Contents a => FilePath -> Maybe RevisionId -> IO a

-- | Delete a named resource, providing author and log message.
[delete] :: FileStore -> FilePath -> Author -> Description -> IO ()

-- | Rename a resource, providing author and log message.
[rename] :: FileStore -> FilePath -> FilePath -> Author -> Description -> IO ()

-- | Get history for a list of named resources in a (possibly openended)
--   time range. If the list is empty, history for all resources will be
--   returned. If the TimeRange is 2 Nothings, history for all dates will
--   be returned.
[history] :: FileStore -> [FilePath] -> TimeRange -> Maybe Int -> IO [Revision]

-- | Return the revision ID of the latest change for a resource. Raises
--   <a>NotFound</a> if the resource is not found.
[latest] :: FileStore -> FilePath -> IO RevisionId

-- | Return information about a revision, given the ID. Raises
--   <a>NotFound</a> if there is no such revision.
[revision] :: FileStore -> RevisionId -> IO Revision

-- | Return a list of resources in the filestore.
[index] :: FileStore -> IO [FilePath]

-- | Return a list of resources in a directory of the filestore.
[directory] :: FileStore -> FilePath -> IO [Resource]

-- | <tt>True</tt> if the revision IDs match, in the sense that the can be
--   treated as specifying the same revision.
[idsMatch] :: FileStore -> RevisionId -> RevisionId -> Bool

-- | Search the filestore for patterns.
[search] :: FileStore -> SearchQuery -> IO [SearchMatch]
instance Data.FileStore.Types.Contents Data.ByteString.Lazy.Internal.ByteString
instance Data.FileStore.Types.Contents GHC.Internal.Base.String
instance GHC.Classes.Eq Data.FileStore.Types.Author
instance GHC.Classes.Eq Data.FileStore.Types.Change
instance GHC.Classes.Eq Data.FileStore.Types.FileStoreError
instance GHC.Classes.Eq Data.FileStore.Types.MergeInfo
instance GHC.Classes.Eq Data.FileStore.Types.Resource
instance GHC.Classes.Eq Data.FileStore.Types.Revision
instance GHC.Classes.Eq Data.FileStore.Types.SearchMatch
instance GHC.Classes.Eq Data.FileStore.Types.SearchQuery
instance GHC.Classes.Eq Data.FileStore.Types.TimeRange
instance GHC.Internal.Exception.Type.Exception Data.FileStore.Types.FileStoreError
instance GHC.Classes.Ord Data.FileStore.Types.Resource
instance GHC.Internal.Read.Read Data.FileStore.Types.Author
instance GHC.Internal.Read.Read Data.FileStore.Types.Change
instance GHC.Internal.Read.Read Data.FileStore.Types.FileStoreError
instance GHC.Internal.Read.Read Data.FileStore.Types.MergeInfo
instance GHC.Internal.Read.Read Data.FileStore.Types.Resource
instance GHC.Internal.Read.Read Data.FileStore.Types.Revision
instance GHC.Internal.Read.Read Data.FileStore.Types.SearchMatch
instance GHC.Internal.Read.Read Data.FileStore.Types.SearchQuery
instance GHC.Internal.Read.Read Data.FileStore.Types.TimeRange
instance GHC.Internal.Show.Show Data.FileStore.Types.Author
instance GHC.Internal.Show.Show Data.FileStore.Types.Change
instance GHC.Internal.Show.Show Data.FileStore.Types.FileStoreError
instance GHC.Internal.Show.Show Data.FileStore.Types.MergeInfo
instance GHC.Internal.Show.Show Data.FileStore.Types.Resource
instance GHC.Internal.Show.Show Data.FileStore.Types.Revision
instance GHC.Internal.Show.Show Data.FileStore.Types.SearchMatch
instance GHC.Internal.Show.Show Data.FileStore.Types.SearchQuery
instance GHC.Internal.Show.Show Data.FileStore.Types.TimeRange


-- | Utility functions for running external processes.
module Data.FileStore.Utils

-- | Run shell command and return error status, standard output, and error
--   output. Assumes UTF-8 locale. Note that this does not actually go
--   through /bin/sh!
runShellCommand :: FilePath -> Maybe [(String, String)] -> String -> [String] -> IO (ExitCode, ByteString, ByteString)

-- | Do a three way merge, using either git merge-file or RCS merge.
--   Assumes that either <tt>git</tt> or <tt>merge</tt> is in the system
--   path. Assumes UTF-8 locale.
mergeContents :: (String, ByteString) -> (String, ByteString) -> (String, ByteString) -> IO (Bool, String)

-- | A number of VCS systems uniquely identify a particular revision or
--   change via a cryptographic hash of some sort. These hashs can be very
--   long, and so systems like Git and Darcs don't require the entire hash
--   - a *unique prefix*. Thus a definition of hash equality is <a>==</a>,
--   certainly, but also simply whether either is a prefix of the other. If
--   both are reasonably long, then the likelihood the shorter one is not a
--   unique prefix of the longer (that is, clashes with another hash) is
--   small. The burden of proof is on the caller to not pass a uselessly
--   short short-hash like '1', however.
hashsMatch :: Eq a => [a] -> [a] -> Bool
escapeRegexSpecialChars :: String -> String

-- | A parser function. This is intended for use on strings which are
--   output by grep programs or programs which mimic the standard grep
--   output - which uses colons as delimiters and has 3 fields: the
--   filename, the line number, and then the matching line itself. Note
--   that this is for use on only strings meeting that format - if it goes
--   "file:match", this will throw a pattern-match exception.
--   
--   <pre>
--   parseMatchLine "foo:10:bar baz quux" ~&gt; 
--   SearchMatch {matchResourceName = "foo", matchLineNumber = 10, matchLine = "bar baz quux"}
--   </pre>
parseMatchLine :: String -> SearchMatch

-- | Our policy is: if the input is clearly a "name &lt;e@mail.com&gt;"
--   input, then we return "(Just Address, Name)" If there is no
--   <a>&lt;</a> in the input, then it clearly can't be of that format, and
--   so we just return "(Nothing, Name)"
--   
--   <pre>
--   splitEmailAuthor "foo bar baz@gmail.com" ~&gt; (Nothing,"foo bar baz@gmail.com")
--   splitEmailAuthor "foo bar &lt;baz@gmail.com&gt;" ~&gt; (Just "baz@gmail.com","foo bar")
--   </pre>
splitEmailAuthor :: String -> (Maybe String, String)

-- | If name doesn't exist in repo or is not a file, throw <a>NotFound</a>
--   exception.
ensureFileExists :: FilePath -> FilePath -> IO ()

-- | Search multiple files with a single regexp. This calls out to grep,
--   and so supports the regular expressions grep does.
regSearchFiles :: FilePath -> [String] -> String -> IO [String]

-- | Search a single file with multiple regexps.
regsSearchFile :: [String] -> FilePath -> [String] -> String -> IO [String]

-- | Check that the filename/location is within the given repo, and not
--   inside any of the (relative) paths in <tt>excludes</tt>. Create the
--   directory if needed. If everything checks out, then perform the
--   specified action.
withSanityCheck :: FilePath -> [FilePath] -> FilePath -> IO b -> IO b

-- | Uses grep to search a file-based repository. Note that this calls out
--   to grep; and so is generic over repos like git or darcs-based repos.
--   (The git FileStore instance doesn't use this because git has builtin
--   grep functionality.) Expected usage is to specialize this function
--   with a particular backend's <tt>index</tt>.
grepSearchRepo :: (FilePath -> IO [String]) -> FilePath -> SearchQuery -> IO [SearchMatch]

-- | we don't actually need the contents, just want to check that the
--   directory exists and we have enough permissions
withVerifyDir :: FilePath -> IO a -> IO a

-- | Encode argument for raw command.
encodeArg :: String -> String


-- | A versioned filestore implemented using mercurial. Normally this
--   module should not be imported: import <a>Data.FileStore</a> instead.
module Data.FileStore.Mercurial

-- | Return a filestore implemented using the mercurial distributed
--   revision control system (<a>http://mercurial.selenic.com/</a>).
mercurialFileStore :: FilePath -> FileStore


-- | A versioned filestore implemented using git. Normally this module
--   should not be imported: import <a>Data.FileStore</a> instead.
--   
--   It is assumed that git &gt;= 1.7.2 is available on the system path.
module Data.FileStore.Git

-- | Return a filestore implemented using the git distributed revision
--   control system (<a>http://git-scm.com/</a>).
gitFileStore :: FilePath -> FileStore


-- | Generic utility functions for working with filestores.
module Data.FileStore.Generic

-- | Modify a named resource in the filestore. Like save, except that a
--   revision ID must be specified. If the resource has been modified since
--   the specified revision, <tt>Left</tt> merge information is returned.
--   Otherwise, <tt>Right</tt> the new contents are saved.
modify :: Contents a => FileStore -> FilePath -> RevisionId -> Author -> Description -> a -> IO (Either MergeInfo ())

-- | Like save, but first verify that the resource name is new. If not,
--   throws a <a>ResourceExists</a> error.
create :: Contents a => FileStore -> FilePath -> Author -> Description -> a -> IO ()
type Diff a = PolyDiff a a
data PolyDiff a b
First :: a -> PolyDiff a b
Second :: b -> PolyDiff a b
Both :: a -> b -> PolyDiff a b

-- | Return a unified diff of two revisions of a named resource. Format of
--   the diff is a list <tt>[(Diff, [String])]</tt>, where <tt>DI</tt> is
--   <tt>F</tt> (in first document only), <tt>S</tt> (in second only), or
--   <tt>B</tt> (in both), and the list is a list of lines (without
--   newlines at the end).
diff :: FileStore -> FilePath -> Maybe RevisionId -> Maybe RevisionId -> IO [Diff [String]]

-- | Return a list of all revisions that are saved with the given
--   description or with a part of this description.
searchRevisions :: FileStore -> Bool -> FilePath -> Description -> IO [Revision]

-- | Try to retrieve a resource from the repository by name and possibly a
--   revision identifier. When retrieving a resource by revision identifier
--   fails this function will try to fetch the latest revision for which
--   the description matches the given string.
smartRetrieve :: Contents a => FileStore -> Bool -> FilePath -> Maybe String -> IO a

-- | Like <a>directory</a>, but returns information about the latest
--   revision.
richDirectory :: FileStore -> FilePath -> IO [(Resource, Either String Revision)]


-- | A versioned filestore implemented using darcs. Normally this module
--   should not be imported: import <a>Data.FileStore</a> instead.
module Data.FileStore.Darcs

-- | Return a filestore implemented using the Darcs distributed revision
--   control system (<a>http://darcs.net/</a>).
darcsFileStore :: FilePath -> FileStore


-- | Abstract interface to a versioned file store, which can be implemented
--   using a revision-control system or database.
--   
--   Based on ideas from Sebastiaan Visser's
--   <a>Network.Orchid.Core.Backend</a>.
module Data.FileStore
