avro-0.3.2.0: Avro serialization support for Haskell

Safe HaskellNone
LanguageHaskell2010

Data.Avro

Description

Avro encoding and decoding routines.

This library provides a high level interface for encoding (and decoding) Haskell values in Apache's Avro serialization format. The goal is to match Aeson's API whenever reasonable, meaning user experience with one effectively translate to the other.

Avro RPC is not currently supported.

  • *Library Structure**

The library structure includes: * This module, Avro, providing a high-level interface via classes of FromAvro and ToAvro for decoding and encoding values. * Type define the types of Avro data, providing a common (intermediate) representation for any data that is encoded or decoded by Data.Avro. * Encode and Decode: More efficient conversion capable of avoiding the intermediate representation. Also, the implementation of the en/decoding of the intermediate representation. * Deconflict: translate decoded data from an encoder schema to the (potentially different) decoder's schema. * Schema: Defines the type for Avro schema's and its JSON encoding/decoding.

Example decoding:

Let's say you have an ADT and related schema:

{--}
import qualified Data.Avro.Types as Ty
import Data.Avro.Schema
import Data.Avro
import           Data.List.NonEmpty (NonEmpty(..))

data MyEnum = A | B | C | D deriving (Eq,Ord,Show,Enum,Generic)
data MyStruct = MyStruct (Either MyEnum String) Int

meSchema :: Schema
meSchema = Schema $ mkEnum MyEnum [] Nothing Nothing [A,B,C,D]

msSchema  :: Schema
msSchema =
  Struct MyStruct Nothing [] Nothing Nothing
      [ fld "enumOrString" eOrS (Just $ String "The Default")
      , fld "int" Int (Just (Ty.Int 1))
      ]
     where
     fld nm ty def = Field nm [] Nothing Nothing ty def
     eOrS = mkUnion (meSchema :| [String])

instance ToAvro MyEnum where
    toAvro = toAvroEnum
instance ToAvro MyStruct where
    toAvro (MyStruct ab i) =
     record [ "enumOrString" .= ab
            , "int"          .= i
            ]

main = do
  let val = MyStruct (Right Hello) 1
  print (fromAvro (toAvro val) == Success val)

Synopsis

Documentation

class HasAvroSchema a => ToAvro a where Source #

Minimal complete definition

toAvro

Methods

toAvro :: a -> Value Type Source #

Instances

ToAvro Bool Source # 

Methods

toAvro :: Bool -> Value Type Source #

ToAvro Double Source # 
ToAvro Float Source # 

Methods

toAvro :: Float -> Value Type Source #

ToAvro Int Source # 

Methods

toAvro :: Int -> Value Type Source #

ToAvro Int32 Source # 

Methods

toAvro :: Int32 -> Value Type Source #

ToAvro Int64 Source # 

Methods

toAvro :: Int64 -> Value Type Source #

ToAvro () Source # 

Methods

toAvro :: () -> Value Type Source #

ToAvro ByteString Source # 
ToAvro ByteString Source # 
ToAvro Text Source # 

Methods

toAvro :: Text -> Value Type Source #

ToAvro Text Source # 

Methods

toAvro :: Text -> Value Type Source #

ToAvro a => ToAvro [a] Source # 

Methods

toAvro :: [a] -> Value Type Source #

ToAvro a => ToAvro (Maybe a) Source # 

Methods

toAvro :: Maybe a -> Value Type Source #

(ToAvro a, ToAvro b) => ToAvro (Either a b) Source # 

Methods

toAvro :: Either a b -> Value Type Source #

ToAvro a => ToAvro (HashMap String a) Source # 
ToAvro a => ToAvro (HashMap Text a) Source # 
ToAvro a => ToAvro (HashMap Text a) Source # 
ToAvro a => ToAvro (Map String a) Source # 

Methods

toAvro :: Map String a -> Value Type Source #

ToAvro a => ToAvro (Map Text a) Source # 

Methods

toAvro :: Map Text a -> Value Type Source #

ToAvro a => ToAvro (Map Text a) Source # 

Methods

toAvro :: Map Text a -> Value Type Source #

class HasAvroSchema a where Source #

Minimal complete definition

schema

Methods

schema :: Tagged a Type Source #

Instances

HasAvroSchema Bool Source # 
HasAvroSchema Double Source # 
HasAvroSchema Float Source # 
HasAvroSchema Int Source # 
HasAvroSchema Int8 Source # 
HasAvroSchema Int16 Source # 
HasAvroSchema Int32 Source # 
HasAvroSchema Int64 Source # 
HasAvroSchema Word8 Source # 
HasAvroSchema Word16 Source # 
HasAvroSchema Word32 Source # 
HasAvroSchema Word64 Source # 
HasAvroSchema () Source # 

Methods

schema :: Tagged * () Type Source #

HasAvroSchema ByteString Source # 
HasAvroSchema ByteString Source # 
HasAvroSchema Text Source # 
HasAvroSchema Text Source # 
HasAvroSchema a => HasAvroSchema [a] Source # 

Methods

schema :: Tagged * [a] Type Source #

HasAvroSchema a => HasAvroSchema (Maybe a) Source # 

Methods

schema :: Tagged * (Maybe a) Type Source #

HasAvroSchema a => HasAvroSchema (Set a) Source # 

Methods

schema :: Tagged * (Set a) Type Source #

HasAvroSchema a => HasAvroSchema (Vector a) Source # 

Methods

schema :: Tagged * (Vector a) Type Source #

HasAvroSchema a => HasAvroSchema (Vector a) Source # 

Methods

schema :: Tagged * (Vector a) Type Source #

(HasAvroSchema a, HasAvroSchema b) => HasAvroSchema (Either a b) Source # 

Methods

schema :: Tagged * (Either a b) Type Source #

HasAvroSchema a => HasAvroSchema (HashMap String a) Source # 
HasAvroSchema a => HasAvroSchema (HashMap Text a) Source # 
HasAvroSchema a => HasAvroSchema (HashMap Text a) Source # 
HasAvroSchema a => HasAvroSchema (Map String a) Source # 
HasAvroSchema a => HasAvroSchema (Map Text a) Source # 

Methods

schema :: Tagged * (Map Text a) Type Source #

HasAvroSchema a => HasAvroSchema (Map Text a) Source # 

Methods

schema :: Tagged * (Map Text a) Type Source #

(HasAvroSchema a, Ix i) => HasAvroSchema (Array i a) Source # 

Methods

schema :: Tagged * (Array i a) Type Source #

type Avro a = (FromAvro a, ToAvro a) Source #

(.=) :: ToAvro a => Text -> a -> (Text, Value Type) Source #

data Result a Source #

Constructors

Success a 
Error String 

Instances

Monad Result Source # 

Methods

(>>=) :: Result a -> (a -> Result b) -> Result b #

(>>) :: Result a -> Result b -> Result b #

return :: a -> Result a #

fail :: String -> Result a #

Functor Result Source # 

Methods

fmap :: (a -> b) -> Result a -> Result b #

(<$) :: a -> Result b -> Result a #

MonadFail Result Source # 

Methods

fail :: String -> Result a #

Applicative Result Source # 

Methods

pure :: a -> Result a #

(<*>) :: Result (a -> b) -> Result a -> Result b #

liftA2 :: (a -> b -> c) -> Result a -> Result b -> Result c #

(*>) :: Result a -> Result b -> Result b #

(<*) :: Result a -> Result b -> Result a #

Foldable Result Source # 

Methods

fold :: Monoid m => Result m -> m #

foldMap :: Monoid m => (a -> m) -> Result a -> m #

foldr :: (a -> b -> b) -> b -> Result a -> b #

foldr' :: (a -> b -> b) -> b -> Result a -> b #

foldl :: (b -> a -> b) -> b -> Result a -> b #

foldl' :: (b -> a -> b) -> b -> Result a -> b #

foldr1 :: (a -> a -> a) -> Result a -> a #

foldl1 :: (a -> a -> a) -> Result a -> a #

toList :: Result a -> [a] #

null :: Result a -> Bool #

length :: Result a -> Int #

elem :: Eq a => a -> Result a -> Bool #

maximum :: Ord a => Result a -> a #

minimum :: Ord a => Result a -> a #

sum :: Num a => Result a -> a #

product :: Num a => Result a -> a #

Traversable Result Source # 

Methods

traverse :: Applicative f => (a -> f b) -> Result a -> f (Result b) #

sequenceA :: Applicative f => Result (f a) -> f (Result a) #

mapM :: Monad m => (a -> m b) -> Result a -> m (Result b) #

sequence :: Monad m => Result (m a) -> m (Result a) #

Alternative Result Source # 

Methods

empty :: Result a #

(<|>) :: Result a -> Result a -> Result a #

some :: Result a -> Result [a] #

many :: Result a -> Result [a] #

MonadPlus Result Source # 

Methods

mzero :: Result a #

mplus :: Result a -> Result a -> Result a #

MonadError String Result Source # 

Methods

throwError :: String -> Result a #

catchError :: Result a -> (String -> Result a) -> Result a #

Eq a => Eq (Result a) Source # 

Methods

(==) :: Result a -> Result a -> Bool #

(/=) :: Result a -> Result a -> Bool #

Ord a => Ord (Result a) Source # 

Methods

compare :: Result a -> Result a -> Ordering #

(<) :: Result a -> Result a -> Bool #

(<=) :: Result a -> Result a -> Bool #

(>) :: Result a -> Result a -> Bool #

(>=) :: Result a -> Result a -> Bool #

max :: Result a -> Result a -> Result a #

min :: Result a -> Result a -> Result a #

Show a => Show (Result a) Source # 

Methods

showsPrec :: Int -> Result a -> ShowS #

show :: Result a -> String #

showList :: [Result a] -> ShowS #

Semigroup (Result a) Source # 

Methods

(<>) :: Result a -> Result a -> Result a #

sconcat :: NonEmpty (Result a) -> Result a #

stimes :: Integral b => b -> Result a -> Result a #

Monoid (Result a) Source # 

Methods

mempty :: Result a #

mappend :: Result a -> Result a -> Result a #

mconcat :: [Result a] -> Result a #

decode :: forall a. FromAvro a => ByteString -> Result a Source #

Decode a lazy bytestring using a Schema for the return type.

decodeWithSchema :: FromAvro a => Schema -> ByteString -> Result a Source #

Decode a lazy bytestring with a provided schema

decodeContainer :: forall a. FromAvro a => ByteString -> [[a]] Source #

Decode a container and de-conflict the writer schema with a reader schema for a return type. Like in decodeContainerWithSchema exceptions are thrown instead of a Result type to allow this function to be read lazy (to be done in some later version).

decodeContainerWithSchema :: FromAvro a => Schema -> ByteString -> [[a]] Source #

Decode a container and de-conflict the writer schema with a given reader-schema. Exceptions are thrown instead of a Result type to allow this function to be read lazy (to be done in some later version).

decodeContainerBytes :: ByteString -> [[ByteString]] Source #

Like decodeContainer but returns the avro-encoded bytes for each object in the container instead of the Haskell type.

This is particularly useful when slicing up containers into one or more smaller files. By extracting the original bytestring it is possible to avoid re-encoding data.

encode :: ToAvro a => a -> ByteString Source #

Encodes a value to a lazy ByteString

encodeContainer :: forall a. ToAvro a => [[a]] -> IO ByteString Source #

Encode chunks of objects into a container, using 16 random bytes for the synchronization markers.

encodeContainerWithSync :: forall a. ToAvro a => (Word64, Word64, Word64, Word64) -> [[a]] -> ByteString Source #

Encode chunks of objects into a container, using the provided ByteString as the synchronization markers