gdritter repos tansu / 082f34d
And a README, too! Getty Ritter 9 years ago
1 changed file(s) with 70 addition(s) and 0 deletion(s). Collapse all Expand all
+70
-0
README.md less more
1 # Tansu
2
3 **WARNING: DO NOT USE THIS CODE.** It's seriously like almost totally
4 untested, very much not finished, and I reserve the right to modify it
5 in part or in total at any time.
6
7 The Tansu library is a minimal API for storing and recalling data in
8 key-value storage backends. The Tansu library does not intend to be useful
9 for working with pre-existing data, as it makes assumptions about the
10 formatting of keys and values.
11
12 ## Example
13
14 ~~~.haskell
15 {-# LANGUAGE DeriveGeneric, DeriveAnyClass #-}
16
17 module Main where
18
19 import Data.Serialize (Serialize)
20 import GHC.Generics (Generic)
21
22 import Database.Tansu ((=:), get, run)
23 import Database.Tansu.Backend.Filesystem (withFilesystemDb)
24
25 data Person = Person { name :: String, age :: Int }
26 deriving (Eq, Show, Generic, Serialize)
27
28 main :: IO ()
29 main = withFilesystemDb "sample.db" $ \ db -> do
30 run db $ do
31 "alex" =: Person "alex" 33
32 "blake" =: Person "blake" 22
33
34 Right age <- run db (age `fmap` get "blake")
35 putStrLn $ "Blake's age is " ++ show age
36 ~~~
37
38 ## Use
39
40 The Tansu API is very small and simple. All keys and values must implement
41 the `Serialize` typeclass from the
42 [`cereal`](https://hackage.haskell.org/package/cereal)
43 library. No type information is saved in the key-value store, so care must
44 be taken to ensure that the correct deserializer is being used when a value
45 is extracted from the backing store.
46
47 A value of type `TansuDb` represents a given key-value mapping. The only
48 way to interact with a `TansuDb` is by running a `Tansu` command, which
49 represents a (possibly empty) sequence of stores and loads applied
50 successively to the key-value mapping. Values can be set using the `set`
51 command (or its operator synonym `=:`) and retrieved using the `get`
52 command.
53
54 A value of type `TansuDb` should be supplied by a _backend_, which can
55 correspond to any storage medium capable of storing a key-value store.
56 The `tansu` library only defines two trivial storage backends—one that
57 offers a trivial in-memory key-value mapping without any persistence at
58 all, and another that naïvely stores the key-value mapping as files in a
59 local directory. However, `tansu` is designed in such a way that storage
60 backends can be simply implemented separately from the core `tansu`
61 library, and backends can be easily swapped out as desired.
62
63 ## About the Name
64
65 A _tansu_ is a kind of
66 [mobile Japanese wooden cabinet](https://en.wikipedia.org/wiki/Tansu),
67 and the initial plan for the _tansu_ library was for it to be a convenient
68 API wrapper over the [Kyoto Cabinet](http://fallabs.com/kyotocabinet/)
69 library, but it has since become a generic wrapper over various
70 key-value mapping backends. It is still a kind of storage system.