avro-0.4.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 => FromAvro a where Source #

Methods

fromAvro :: Value Type -> Result a Source #

Instances
FromAvro Bool Source # 
Instance details

Defined in Data.Avro.FromAvro

FromAvro Double Source # 
Instance details

Defined in Data.Avro.FromAvro

FromAvro Float Source # 
Instance details

Defined in Data.Avro.FromAvro

FromAvro Int Source # 
Instance details

Defined in Data.Avro.FromAvro

FromAvro Int32 Source # 
Instance details

Defined in Data.Avro.FromAvro

FromAvro Int64 Source # 
Instance details

Defined in Data.Avro.FromAvro

FromAvro ByteString Source # 
Instance details

Defined in Data.Avro.FromAvro

FromAvro ByteString Source # 
Instance details

Defined in Data.Avro.FromAvro

FromAvro Text Source # 
Instance details

Defined in Data.Avro.FromAvro

FromAvro Text Source # 
Instance details

Defined in Data.Avro.FromAvro

FromAvro a => FromAvro [a] Source # 
Instance details

Defined in Data.Avro.FromAvro

Methods

fromAvro :: Value Type -> Result [a] Source #

FromAvro a => FromAvro (Maybe a) Source # 
Instance details

Defined in Data.Avro.FromAvro

(Unbox a, FromAvro a) => FromAvro (Vector a) Source # 
Instance details

Defined in Data.Avro.FromAvro

FromAvro a => FromAvro (Vector a) Source # 
Instance details

Defined in Data.Avro.FromAvro

(FromAvro a, FromAvro b) => FromAvro (Either a b) Source # 
Instance details

Defined in Data.Avro.FromAvro

Methods

fromAvro :: Value Type -> Result (Either a b) Source #

FromAvro a => FromAvro (HashMap Text a) Source # 
Instance details

Defined in Data.Avro.FromAvro

FromAvro a => FromAvro (Map Text a) Source # 
Instance details

Defined in Data.Avro.FromAvro

(FromAvro a, FromAvro b, FromAvro c) => FromAvro (Either3 a b c) Source # 
Instance details

Defined in Data.Avro.EitherN

Methods

fromAvro :: Value Type -> Result (Either3 a b c) Source #

(FromAvro a, FromAvro b, FromAvro c, FromAvro d) => FromAvro (Either4 a b c d) Source # 
Instance details

Defined in Data.Avro.EitherN

Methods

fromAvro :: Value Type -> Result (Either4 a b c d) Source #

(FromAvro a, FromAvro b, FromAvro c, FromAvro d, FromAvro e) => FromAvro (Either5 a b c d e) Source # 
Instance details

Defined in Data.Avro.EitherN

Methods

fromAvro :: Value Type -> Result (Either5 a b c d e) Source #

class HasAvroSchema a => ToAvro a where Source #

Methods

toAvro :: a -> Value Type Source #

Instances
ToAvro Bool Source # 
Instance details

Defined in Data.Avro.ToAvro

Methods

toAvro :: Bool -> Value Type Source #

ToAvro Double Source # 
Instance details

Defined in Data.Avro.ToAvro

ToAvro Float Source # 
Instance details

Defined in Data.Avro.ToAvro

Methods

toAvro :: Float -> Value Type Source #

ToAvro Int Source # 
Instance details

Defined in Data.Avro.ToAvro

Methods

toAvro :: Int -> Value Type Source #

ToAvro Int32 Source # 
Instance details

Defined in Data.Avro.ToAvro

Methods

toAvro :: Int32 -> Value Type Source #

ToAvro Int64 Source # 
Instance details

Defined in Data.Avro.ToAvro

Methods

toAvro :: Int64 -> Value Type Source #

ToAvro () Source # 
Instance details

Defined in Data.Avro.ToAvro

Methods

toAvro :: () -> Value Type Source #

ToAvro ByteString Source # 
Instance details

Defined in Data.Avro.ToAvro

ToAvro ByteString Source # 
Instance details

Defined in Data.Avro.ToAvro

ToAvro Text Source # 
Instance details

Defined in Data.Avro.ToAvro

Methods

toAvro :: Text -> Value Type Source #

ToAvro Text Source # 
Instance details

Defined in Data.Avro.ToAvro

Methods

toAvro :: Text -> Value Type Source #

ToAvro a => ToAvro [a] Source # 
Instance details

Defined in Data.Avro.ToAvro

Methods

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

ToAvro a => ToAvro (Maybe a) Source # 
Instance details

Defined in Data.Avro.ToAvro

Methods

toAvro :: Maybe a -> Value Type Source #

(Unbox a, ToAvro a) => ToAvro (Vector a) Source # 
Instance details

Defined in Data.Avro.ToAvro

Methods

toAvro :: Vector a -> Value Type Source #

ToAvro a => ToAvro (Vector a) Source # 
Instance details

Defined in Data.Avro.ToAvro

Methods

toAvro :: Vector a -> Value Type Source #

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

Defined in Data.Avro.ToAvro

Methods

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

ToAvro a => ToAvro (HashMap Text a) Source # 
Instance details

Defined in Data.Avro.ToAvro

ToAvro a => ToAvro (HashMap Text a) Source # 
Instance details

Defined in Data.Avro.ToAvro

ToAvro a => ToAvro (HashMap String a) Source # 
Instance details

Defined in Data.Avro.ToAvro

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

Defined in Data.Avro.ToAvro

Methods

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

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

Defined in Data.Avro.ToAvro

Methods

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

ToAvro a => ToAvro (Map String a) Source # 
Instance details

Defined in Data.Avro.ToAvro

Methods

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

(ToAvro a, ToAvro b, ToAvro c) => ToAvro (Either3 a b c) Source # 
Instance details

Defined in Data.Avro.EitherN

Methods

toAvro :: Either3 a b c -> Value Type Source #

(ToAvro a, ToAvro b, ToAvro c, ToAvro d) => ToAvro (Either4 a b c d) Source # 
Instance details

Defined in Data.Avro.EitherN

Methods

toAvro :: Either4 a b c d -> Value Type Source #

(ToAvro a, ToAvro b, ToAvro c, ToAvro d, ToAvro e) => ToAvro (Either5 a b c d e) Source # 
Instance details

Defined in Data.Avro.EitherN

Methods

toAvro :: Either5 a b c d e -> Value Type Source #

class HasAvroSchema a where Source #

Methods

schema :: Tagged a Type Source #

Instances
HasAvroSchema Bool Source # 
Instance details

Defined in Data.Avro.HasAvroSchema

HasAvroSchema Double Source # 
Instance details

Defined in Data.Avro.HasAvroSchema

HasAvroSchema Float Source # 
Instance details

Defined in Data.Avro.HasAvroSchema

HasAvroSchema Int Source # 
Instance details

Defined in Data.Avro.HasAvroSchema

HasAvroSchema Int8 Source # 
Instance details

Defined in Data.Avro.HasAvroSchema

HasAvroSchema Int16 Source # 
Instance details

Defined in Data.Avro.HasAvroSchema

HasAvroSchema Int32 Source # 
Instance details

Defined in Data.Avro.HasAvroSchema

HasAvroSchema Int64 Source # 
Instance details

Defined in Data.Avro.HasAvroSchema

HasAvroSchema Word8 Source # 
Instance details

Defined in Data.Avro.HasAvroSchema

HasAvroSchema Word16 Source # 
Instance details

Defined in Data.Avro.HasAvroSchema

HasAvroSchema Word32 Source # 
Instance details

Defined in Data.Avro.HasAvroSchema

HasAvroSchema Word64 Source # 
Instance details

Defined in Data.Avro.HasAvroSchema

HasAvroSchema () Source # 
Instance details

Defined in Data.Avro.HasAvroSchema

Methods

schema :: Tagged () Type Source #

HasAvroSchema ByteString Source # 
Instance details

Defined in Data.Avro.HasAvroSchema

HasAvroSchema ByteString Source # 
Instance details

Defined in Data.Avro.HasAvroSchema

HasAvroSchema Text Source # 
Instance details

Defined in Data.Avro.HasAvroSchema

HasAvroSchema Text Source # 
Instance details

Defined in Data.Avro.HasAvroSchema

HasAvroSchema a => HasAvroSchema [a] Source # 
Instance details

Defined in Data.Avro.HasAvroSchema

Methods

schema :: Tagged [a] Type Source #

HasAvroSchema a => HasAvroSchema (Maybe a) Source # 
Instance details

Defined in Data.Avro.HasAvroSchema

Methods

schema :: Tagged (Maybe a) Type Source #

HasAvroSchema a => HasAvroSchema (Set a) Source # 
Instance details

Defined in Data.Avro.HasAvroSchema

Methods

schema :: Tagged (Set a) Type Source #

HasAvroSchema a => HasAvroSchema (Vector a) Source # 
Instance details

Defined in Data.Avro.HasAvroSchema

HasAvroSchema a => HasAvroSchema (Vector a) Source # 
Instance details

Defined in Data.Avro.HasAvroSchema

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

Defined in Data.Avro.HasAvroSchema

Methods

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

HasAvroSchema a => HasAvroSchema (HashMap Text a) Source # 
Instance details

Defined in Data.Avro.HasAvroSchema

HasAvroSchema a => HasAvroSchema (HashMap Text a) Source # 
Instance details

Defined in Data.Avro.HasAvroSchema

HasAvroSchema a => HasAvroSchema (HashMap String a) Source # 
Instance details

Defined in Data.Avro.HasAvroSchema

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

Defined in Data.Avro.HasAvroSchema

Methods

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

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

Defined in Data.Avro.HasAvroSchema

Methods

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

HasAvroSchema a => HasAvroSchema (Map String a) Source # 
Instance details

Defined in Data.Avro.HasAvroSchema

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

Defined in Data.Avro.HasAvroSchema

Methods

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

(HasAvroSchema a, HasAvroSchema b, HasAvroSchema c) => HasAvroSchema (Either3 a b c) Source # 
Instance details

Defined in Data.Avro.EitherN

Methods

schema :: Tagged (Either3 a b c) Type Source #

(HasAvroSchema a, HasAvroSchema b, HasAvroSchema c, HasAvroSchema d) => HasAvroSchema (Either4 a b c d) Source # 
Instance details

Defined in Data.Avro.EitherN

Methods

schema :: Tagged (Either4 a b c d) Type Source #

(HasAvroSchema a, HasAvroSchema b, HasAvroSchema c, HasAvroSchema d, HasAvroSchema e) => HasAvroSchema (Either5 a b c d e) Source # 
Instance details

Defined in Data.Avro.EitherN

Methods

schema :: Tagged (Either5 a b c d e) Type Source #

type Schema = Type Source #

An Avro schema is either * A "JSON object in the form `{"type":"typeName" ...` * A "JSON string, naming a defined type" (basic type wo free variablesnames) * A "JSON array, representing a union"

N.B. It is possible to create a Haskell value (of Schema type) that is not a valid Avro schema by violating one of the above or one of the conditions called out in validateSchema.

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 # 
Instance details

Defined in Data.Avro.Schema

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 # 
Instance details

Defined in Data.Avro.Schema

Methods

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

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

MonadFail Result Source # 
Instance details

Defined in Data.Avro.Schema

Methods

fail :: String -> Result a #

Applicative Result Source # 
Instance details

Defined in Data.Avro.Schema

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 # 
Instance details

Defined in Data.Avro.Schema

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 # 
Instance details

Defined in Data.Avro.Schema

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 # 
Instance details

Defined in Data.Avro.Schema

Methods

empty :: Result a #

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

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

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

MonadPlus Result Source # 
Instance details

Defined in Data.Avro.Schema

Methods

mzero :: Result a #

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

MonadError String Result Source # 
Instance details

Defined in Data.Avro.Schema

Methods

throwError :: String -> Result a #

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

Eq a => Eq (Result a) Source # 
Instance details

Defined in Data.Avro.Schema

Methods

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

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

Ord a => Ord (Result a) Source # 
Instance details

Defined in Data.Avro.Schema

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 # 
Instance details

Defined in Data.Avro.Schema

Methods

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

show :: Result a -> String #

showList :: [Result a] -> ShowS #

Semigroup (Result a) Source # 
Instance details

Defined in Data.Avro.Schema

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 # 
Instance details

Defined in Data.Avro.Schema

Methods

mempty :: Result a #

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

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

badValue :: Show t => t -> String -> Result a Source #

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