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


-- | BSON documents are JSON-like objects with a standard binary encoding
--   
--   A BSON Document is an untyped (dynamically type-checked) record. I.e.
--   it is a list of name-value pairs, where a Value is a single sum type
--   with constructors for basic types (Bool, Int, Float, String, and
--   Time), compound types (List, and (embedded) Document), and special
--   types (Binary, Javascript, ObjectId, RegEx, and a few others).
--   
--   A BSON Document is serialized to a standard binary encoding defined at
--   <a>http://bsonspec.org</a>. This implements version 1 of that spec.
@package bson
@version 0.1


-- | UTF-8 String
module Data.UString

-- | UTF-8 String
type UString = CompactString
u :: String -> UString
instance Typeable UTF8
instance Typeable1 CompactString
instance Read CompactString


-- | A BSON document is a JSON-like object with a standard binary encoding
--   defined at bsonspec.org. This implements version 1.0 of that spec.
--   
--   Use the GHC language extension <i>OverloadedStrings</i> to
--   automatically convert String literals to UString (UTF8)
module Data.Bson

-- | UTF-8 String
type UString = CompactString

-- | A BSON document is a list of <a>Field</a>s
type Document = [Field]

-- | Value of field in document, or fail (Nothing) if field not found
look :: Monad m => Label -> Document -> m Value

-- | Lookup value of field in document and cast to expected type. Fail
--   (Nothing) if field not found or value not of expected type.
lookup :: (Val v, Monad m) => Label -> Document -> m v

-- | Value of field in document. Error if missing.
valueAt :: Label -> Document -> Value

-- | Typed value of field in document. Error if missing or wrong type.
at :: Val v => Label -> Document -> v

-- | Only include fields of document in label list
include :: [Label] -> Document -> Document

-- | Exclude fields from document in label list
exclude :: [Label] -> Document -> Document

-- | Merge documents with preference given to first one when both have the
--   same label. I.e. for every (k := v) in first argument, if k exists in
--   second argument then replace its value with v, otherwise add (k := v)
--   to second argument.
merge :: Document -> Document -> Document

-- | A BSON field is a named value, where the name (label) is a string and
--   the value is a BSON <a>Value</a>
data Field
(:=) :: Label -> Value -> Field
label :: Field -> Label
value :: Field -> Value

-- | Field with given label and typed value
(=:) :: Val v => Label -> v -> Field

-- | If Just value then return one field document, otherwise return empty
--   document
(=?) :: Val a => Label -> Maybe a -> Document

-- | The name of a BSON field
type Label = UString

-- | A BSON value is one of the following types of values
data Value
Float :: Double -> Value
String :: UString -> Value
Doc :: Document -> Value
Array :: [Value] -> Value
Bin :: Binary -> Value
Fun :: Function -> Value
Uuid :: UUID -> Value
Md5 :: MD5 -> Value
UserDef :: UserDefined -> Value
ObjId :: ObjectId -> Value
Bool :: Bool -> Value
UTC :: UTCTime -> Value
Null :: Value
RegEx :: Regex -> Value
JavaScr :: Javascript -> Value
Sym :: Symbol -> Value
Int32 :: Int32 -> Value
Int64 :: Int64 -> Value
Stamp :: MongoStamp -> Value
MinMax :: MinMaxKey -> Value

-- | Haskell types of this class correspond to BSON value types
class (Typeable a, Show a, Eq a) => Val a
val :: Val a => a -> Value
cast' :: Val a => Value -> Maybe a

-- | Apply generic function to typed value
fval :: (forall a. Val a => a -> b) -> Value -> b

-- | Convert Value to expected type, or fail (Nothing) if not of that type
cast :: (Val a, Monad m) => Value -> m a

-- | Convert Value to expected type. Error if not that type.
typed :: Val a => Value -> a

-- | Type of typed value
typeOfVal :: Value -> TypeRep
newtype Binary
Binary :: ByteString -> Binary
newtype Function
Function :: ByteString -> Function
newtype UUID
UUID :: ByteString -> UUID
newtype MD5
MD5 :: ByteString -> MD5
newtype UserDefined
UserDefined :: ByteString -> UserDefined
data Regex
Regex :: UString -> UString -> Regex

-- | Javascript code with possibly empty environment mapping variables to
--   values that the code may reference
data Javascript
Javascript :: Document -> UString -> Javascript
newtype Symbol
Symbol :: UString -> Symbol
newtype MongoStamp
MongoStamp :: Int64 -> MongoStamp
data MinMaxKey
MinKey :: MinMaxKey
MaxKey :: MinMaxKey

-- | A BSON ObjectID is a 12-byte value consisting of a 4-byte timestamp
--   (seconds since epoch), a 3-byte machine id, a 2-byte process id, and a
--   3-byte counter. Note that the timestamp and counter fields must be
--   stored big endian unlike the rest of BSON. This is because they are
--   compared byte-by-byte and we want to ensure a mostly increasing order.
data ObjectId
Oid :: Word32 -> Word64 -> ObjectId

-- | Time when objectId was created
timestamp :: ObjectId -> UTCTime

-- | Create a fresh ObjectId
genObjectId :: IO ObjectId
instance [incoherent] Typeable ObjectId
instance [incoherent] Typeable MinMaxKey
instance [incoherent] Typeable MongoStamp
instance [incoherent] Typeable Symbol
instance [incoherent] Typeable Javascript
instance [incoherent] Typeable Regex
instance [incoherent] Typeable UserDefined
instance [incoherent] Typeable MD5
instance [incoherent] Typeable UUID
instance [incoherent] Typeable Function
instance [incoherent] Typeable Binary
instance [incoherent] Typeable Value
instance [incoherent] Typeable Field
instance [incoherent] Eq ObjectId
instance [incoherent] Ord ObjectId
instance [incoherent] Show MinMaxKey
instance [incoherent] Read MinMaxKey
instance [incoherent] Eq MinMaxKey
instance [incoherent] Show MongoStamp
instance [incoherent] Read MongoStamp
instance [incoherent] Eq MongoStamp
instance [incoherent] Show Symbol
instance [incoherent] Read Symbol
instance [incoherent] Eq Symbol
instance [incoherent] Show Javascript
instance [incoherent] Eq Javascript
instance [incoherent] Show Regex
instance [incoherent] Read Regex
instance [incoherent] Eq Regex
instance [incoherent] Show UserDefined
instance [incoherent] Read UserDefined
instance [incoherent] Eq UserDefined
instance [incoherent] Show MD5
instance [incoherent] Read MD5
instance [incoherent] Eq MD5
instance [incoherent] Show UUID
instance [incoherent] Read UUID
instance [incoherent] Eq UUID
instance [incoherent] Show Function
instance [incoherent] Read Function
instance [incoherent] Eq Function
instance [incoherent] Show Binary
instance [incoherent] Read Binary
instance [incoherent] Eq Binary
instance [incoherent] Eq Value
instance [incoherent] Eq Field
instance [incoherent] Show ObjectId
instance [incoherent] Val MinMaxKey
instance [incoherent] Val MongoStamp
instance [incoherent] Val Integer
instance [incoherent] Val Int
instance [incoherent] Val Int64
instance [incoherent] Val Int32
instance [incoherent] Val Symbol
instance [incoherent] Val Javascript
instance [incoherent] Val Regex
instance [incoherent] Val a => Val (Maybe a)
instance [incoherent] Val (Maybe Value)
instance [incoherent] Val POSIXTime
instance [incoherent] Val UTCTime
instance [incoherent] Val Bool
instance [incoherent] Val ObjectId
instance [incoherent] Val UserDefined
instance [incoherent] Val MD5
instance [incoherent] Val UUID
instance [incoherent] Val Function
instance [incoherent] Val Binary
instance [incoherent] Val a => Val [a]
instance [incoherent] Val [Value]
instance [incoherent] Val Document
instance [incoherent] Val String
instance [incoherent] Val UString
instance [incoherent] Val Float
instance [incoherent] Val Double
instance [incoherent] Show Value
instance [incoherent] Show Field


-- | Standard binary encoding of BSON documents, version 1.0. See
--   bsonspec.org
module Data.Bson.Binary
putDocument :: Document -> Put
getDocument :: Get Document
putDouble :: Double -> Put
getDouble :: Get Double
putInt32 :: Int32 -> Put
getInt32 :: Get Int32
putInt64 :: Int64 -> Put
getInt64 :: Get Int64
putCString :: UString -> Put
getCString :: Get UString