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


-- | Indexable, serializable  form of Data.Dynamic
--   
--   A variant of Data.Dynamic that can be indexed, stored, transmitted
--   trough communications etc.
@package IDynamic
@version 0.1

module Data.IResource

-- | A general interface for indexable, serializable and input-output
--   objects. <a>readResource</a> and <a>writeResource</a> are implemented
--   by default as read-write to files with its key as filename
--   <a>serialize</a> and <a>deserialize</a> are specified just to allow
--   these defaults. If you define your own persistence, then
--   <tt>serialize</tt> and <tt>deserialize</tt> are not needed. The
--   package Workflow need them anyway.
--   
--   minimal definition: keyResource, serialize, deserialize
--   
--   While serialize and deserialize are agnostic about the way of
--   converison to strings, either binary or textual, treadp and tshowp use
--   the monad defined in the RefSerialize package. Both ways of
--   serialization are alternative. one is defined by default in terms of
--   the other. the RefSerialize monad has been introduced to permit
--   IResource objects to be serialized as part of larger structures that
--   embody them. This is necessary for the Workdlow package.
--   
--   The keyResource string must be a unique since this is used to index it
--   in the hash table. when accessing a resource, the user must provide a
--   partial object for wich the key can be obtained. for example:
--   
--   <pre>
--   data Person= Person{name, surname:: String, account :: Int ....)
--   
--   keyResource Person n s ...= n++s
--   </pre>
--   
--   the data being accesed must have the fields used by keyResource
--   filled. For example
--   
--   <pre>
--   readResource Person {name=<a>John</a>, surname= <a>Adams</a>}
--   </pre>
--   
--   leaving the rest of the fields undefined
--   
--   IResource has defaults definitions for all the methods except
--   keyResource Either one or other serializer must be defiened for
--   default witeResource, readResource and delResource
class IResource a
keyResource :: (IResource a) => a -> String
serialize :: (IResource a) => a -> String
deserialize :: (IResource a) => String -> a
defPath :: (IResource a) => a -> String
readResource :: (IResource a) => a -> IO (Maybe a)
writeResource :: (IResource a) => a -> IO ()
delResource :: (IResource a) => a -> IO ()
type AccessTime = Integer
type ModifTime = Integer

-- | Resources returned by withSTMResources'
data Resources a b

-- | forces a retry
Retry :: Resources a b
Resources :: [a] -> [a] -> b -> Resources a b

-- | resources to be inserted back in the cache
toAdd :: Resources a b -> [a]

-- | resources to be deleted from the cache and from permanent storage
toDelete :: Resources a b -> [a]

-- | result to be returned
toReturn :: Resources a b -> b

-- | <pre>
--   resources= Resources  [] [] ()
--   </pre>
resources :: Resources a ()

module Data.IDynamic

-- | Data.IDynamic is a indexable and serializable version
--   <tt>Data.Dynamic</tt> . IDinamic provices methods for safe casting,
--   serializaton, deserialization, registration output and input
--   
--   the data definition of IDymanic is as such: <tt>data IDynamic= forall
--   a. (Typeable a, IResource a) =&gt; IDynamic a deriving Typeable</tt>
--   
--   The registration trough <tt>registerType</tt> is necessary before
--   deserialization: <tt><a>registerType</a> :: IO Type</tt>
--   
--   example:
--   
--   <pre>
--   module Main where
--   import Data.IResource
--   import Data.IDynamic
--   import Data.Typeable
--   
--   instance IResource Int where     
--          keyResource x=  "I"
--          serialize = show
--          deserialize = read
--          defPath _= "data/ "
--   
--   instance IResource String where
--          keyResource x=  take 5 x
--          serialize = show
--          deserialize = read
--          defPath _= "data/"
--   
--   main= do
--         putStrLn "see the code to know the meaning of he results"
--         registerType :: IO Int           -- register both datatypes (Int, and String)
--         registerType :: IO String
--         let x= 1 :: Int
--   
--   let list= [IDynamic x, IDynamic "hello, how are you"]
--   
--   let assoc= zip (map keyResource list) list
--         print $ lookup (keyResource (5 ::Int)) assoc
--   
--   mapM writeResource list
--         mds &lt;-  readResource $  IDynamic  "hello"
--         case mds of
--               Nothing -&gt; error "must have been Just!"
--               Just ds -&gt; do
--                        putStrLn $ serialize ds
--                        let str= fromIDyn  ds ::   String
--                        putStrLn str
--   
--   let y=  fromIDyn  ds ::   Int   -- casting error
--                        print y
--   </pre>
data IDynamic
IDynamic :: a -> IDynamic
list :: MVar (Map Word (IDynamic -> IO (Maybe IDynamic), String -> IDynamic))

-- | DynamicInterface groups a set of default method calls to handle
--   dynamic objects. It is not necessary to derive instances from it
class DynamicInterface x
toIDyn :: (DynamicInterface x) => x -> IDynamic
registerType :: (DynamicInterface x) => IO x
fromIDyn :: (DynamicInterface x) => IDynamic -> x
unsafeFromIDyn :: (DynamicInterface x) => IDynamic -> x
safeFromIDyn :: (DynamicInterface x) => IDynamic -> Maybe x

-- | Key datatype can be used to read any object trough the Dynamic
--   interface.
--   
--   <pre>
--   data Key =  Key <a>TypeRep</a> String deriving Typeable
--   </pre>
--   
--   Example
--   
--   <pre>
--   mst &lt;- getDResource $ <a>Key</a> type keyofDesiredObject
--              case mst of
--                Nothing -&gt; error $ "not found "++ key
--                Just (idyn) -&gt;  fromIDyn idyn :: DesiredDatatype}
--   </pre>
data Key
Key :: TypeRep -> String -> Key
instance Typeable Key
instance Typeable IDynamic
instance IResource Key
instance (IResource x, Typeable x) => DynamicInterface x
instance Show IDynamic
instance IResource IDynamic