A short Haskell FileStore Tutorial

Haskell package filestore

provides an interface for a versioning file store. It uses git, Darcs and Mercurial as a backend. Here's a short walk-through to get you started.

Documentation

In Data.FileStore.Types you find the most important functions such as initialise. save. retrieve, delete, etc. Data.FileStore.Generic has some utility function like modify, create, etc. For more details see the package description on hackage.

Walk-through

First activate the language extension and import the package:

{-# LANGUAGE TemplateHaskell #-}
import Data.FileStore  

To initialise a filestore first create a FileStore
instance (here I choose the git backend, but you could just as well use mercurialFileStore or darcsFileStore)

let f = gitFileStore "mystore"  
initialize f  

then create an author and then a new file "some_file.txt"

let a = Author "Max" "max@example.com"  
create f "some_file.txt" a "describe the revision" "some content"  

Let's view the resources in the filestore:

i <- index f  
print i  

This will just print a list of filenames, in this case
that's ["some_file.txt"].

To get the revision ID of a file you can use latest

latest f "some_file.txt"  

As an example of how to use the searchRevisions utility function I show you another way to retrieve the newest revision ID. The following will print a list of Revision objects.

  rs <- searchRevisions f False "some_file.txt" ""
  print rs

and we can use that to extract the first revID:

let i = head $ map (\(Revision i t a d cs) -> i) rs  

Next, let's create a new revision of the file by modifying it:

m <- modify f "some_file.txt" i a "description of change" "new content!"  

Let's print the revisions again:

rs <- searchRevisions f False "some_file.txt" ""  
print rs  

To retrieve the content of a file just call content:

content <- (retrieve f "some_file.txt" Nothing) :: IO String  
print content  

The generic utility function smartRetrieve does the same but allows to also retrieve by revision ID (to get the latest revision use Nothing):

  -- read content of file
  content <- (smartRetrieve f False "some_file.txt" Nothing) :: IO String
  print content

Querying

Let's first add some more files (author a and filestore f were defined above):

create f "second-file.txt" a "2nd file" "222222222"  
create f "third-file.txt" a "3rd file" "3333333"  

Now we have three files as index f shows:

["second-file.txt","some_file.txt","third-file.txt"]

Let's define and apply a query:

q = SearchQuery ["2"] False False True  

The result is

[SearchMatch {matchResourceName = "second-file.txt", matchLineNumber = 1, matchLine = "222222222"}]

The signature of the SearchQuery function is

And that's it.

The source code is available on github.