bond-haskell-0.1.3.0: Runtime support for BOND serialization

Safe HaskellNone
LanguageHaskell2010

Data.Bond

Contents

Description

Bond is an extensible framework for working with schematized data. It is suitable for scenarios ranging from service communications to Big Data storage and processing.

Bond defines a rich type system and schema versioning rules which allow forward and backward compatibility.

Core bond library is published on GitHub at https://github.com/Microsoft/bond/.

Synopsis

Example

Let's use following schema.bond IDL file:

namespace my.test

struct my_struct {
  10: int32 m_int;
  20: string m_str = "some string";
}

Code generation requires hbc program from bond-haskell-compiler package:

hbc schema.bond

This creates file My.Test.My_struct.hs. Note that case conversions are performed to create syntactically correct Haskell code.

-- create structure and set m_int to 5:
let struct = defaultValue { m_int = 5 }
-- serialize struct with FastBinary protocol
let Right binstream = bondWrite FastBinaryProto struct
-- parse binstream using runtime schema
let Right rtstruct = bondReadWithSchema FastBinaryProto (getSchema (Proxy :: Proxy My_struct)) binstream

class BondProto t where Source

Typeclass for Bond serialization protocols.

Minimal complete definition

bondRead, bondWrite, bondReadWithSchema, bondWriteWithSchema, protoSig

Methods

bondRead :: BondStruct a => t -> ByteString -> Either String a Source

Deserialize structure from stream.

bondWrite :: BondStruct a => t -> a -> Either String ByteString Source

Serialize structure to stream.

bondReadWithSchema :: t -> StructSchema -> ByteString -> Either String Struct Source

Deserialize structure from stream using provided schema.

bondWriteWithSchema :: t -> StructSchema -> Struct -> Either String ByteString Source

Serialize structure to stream using provided schema.

bondMarshal :: BondStruct a => t -> a -> Either String ByteString Source

Serialize structure to stream and add protocol header. See bondUnmarshal for deserialization.

bondMarshalWithSchema :: t -> StructSchema -> Struct -> Either String ByteString Source

Serialize structure to stream using provided schema and add protocol header. See bondUnmarshalWithSchema for deserialization.

protoSig :: t -> ByteString Source

Get protocol header.

Instances

class BondProto t => BondTaggedProto t where Source

Typeclass for tagged Bond serialization protocols. Such protocols support schemaless operations.

Minimal complete definition

bondReadTagged, bondWriteTagged

Methods

bondReadTagged :: t -> ByteString -> Either String Struct Source

Deserialize structure from stream without schema.

bondWriteTagged :: t -> Struct -> Either String ByteString Source

Serialize structure to stream without schema.

bondMarshalTagged :: t -> Struct -> Either String ByteString Source

Serialize structure to stream without schema and add protocol header. See bondUnmarshalTagged for deserialization.

Instances

Supported protocols

data CompactBinaryV1Proto Source

A binary, tagged protocol using variable integer encoding and compact field header.

Constructors

CompactBinaryV1Proto 

Instances

data CompactBinaryProto Source

A binary, tagged protocol using variable integer encoding and compact field header. Version 2 of Compact Binary adds length prefix for structs. This enables deserialization of bonded<T> and skipping of unknown struct fields in constant time.

Constructors

CompactBinaryProto 

Instances

data FastBinaryProto Source

A binary, tagged protocol similar to CompactBinaryProto but optimized for deserialization speed rather than payload compactness.

Constructors

FastBinaryProto 

Instances

data SimpleBinaryV1Proto Source

A binary, untagged protocol which is a good choice for storage scenarios as it offers potential for big saving on payload size. Because Simple is an untagged protocol, it requires that the payload schema is available during deserialization.

Constructors

SimpleBinaryV1Proto 

Instances

data SimpleBinaryProto Source

A binary, untagged protocol which is a good choice for storage scenarios as it offers potential for big saving on payload size. Because Simple is an untagged protocol, it requires that the payload schema is available during deserialization. Version 2 of Simple Protocol uses variable integer encoding for string and container lengths, resulting in more compact payload.

Constructors

SimpleBinaryProto 

Instances

data JsonProto Source

The output is a standard JSON and is a very good choice for interoperating with other systems or generating human readable payload. Because payload doesn't include field ordinals, it is treated as untagged protocol.

Constructors

JsonProto 

Instances

bonded<T>

data Bonded a Source

bonded<T> value

Constructors

BondedStream ByteString

Marshalled stream

BondedObject a

Deserialized value

Instances

(BondStruct a, Eq a) => Eq (Bonded a) Source 
Show a => Show (Bonded a) Source 
Generic (Bonded a) Source 
NFData a => NFData (Bonded a) Source 
BondStruct a => BondType (Bonded a) Source 
Default a => Default (Bonded a) 
type Rep (Bonded a) Source 

getValue :: BondStruct a => Bonded a -> Either String a Source

Extract value from Bonded using compile-type schema

putValue :: a -> Bonded a Source

Put struct to the bonded<T> field.

castValue :: BondStruct b => Bonded a -> Either String b Source

Extract value from Bonded using compile-type schema for other type. This may be useful for casting values to child structs. User is responsible for schema compatibility.

marshalValue :: (BondProto t, BondStruct a) => t -> a -> Either String (Bonded b) Source

Marshal struct to the bonded<T> field. There is no checks for schema compatibility, caveat emptor.

data BondedException Source

BondedException is thrown when attempt to deserialize bonded field for comparison fails. To handle such cases in the pure code explicitly decode all bonded fields before comparing structures.

Constructors

BondedException String 

Instances

Runtime-schema operations

Generic applications may need to work with Bond schemas unknown at compile-time. In order to address such scenarios Bond defines a type SchemaDef to represent schemas in stoorage and transfer.

Haskell library uses StructSchema internally for performance reasons and provides conversion functions.

class BondType a => BondStruct a where Source

Bond top-level structure, can be de/serialized on its own.

Minimal complete definition

bondStructGetUntagged, bondStructGetBase, bondStructGetField, bondStructPut, getSchema

Methods

getSchema :: Proxy a -> StructSchema Source

Obtain struct schema.

Instances

class BondEnum a where Source

Bond enumeration class containing utility functions.

Methods

toName :: a -> Maybe Text Source

Convert constant value to name.

fromName :: Text -> Maybe a Source

Convert constant name to value.

Instances

assembleSchema :: StructSchema -> SchemaDef Source

Convert internal schema representation to SchemaDef for storage or transfer.

checkStructSchema :: MonadError String m => StructSchema -> Struct -> m Struct Source

Verify that Struct matches StructSchema and is internally consistent.

defaultStruct :: StructSchema -> Struct Source

Create minimal valid Struct representing given schema

parseSchema :: SchemaDef -> Either String StructSchema Source

Convert SchemaDef to internal schema representation.

data Struct Source

Representation of bond structure used in runtime-schema operations.

Constructors

Struct 

Fields

base :: Maybe Struct
 
fields :: Map Ordinal Value
 

Instances

data Value Source

Representation of bond serializable type used in runtime-schema operations.

Constructors

BOOL Bool 
INT8 Int8 
INT16 Int16 
INT32 Int32 
INT64 Int64 
UINT8 Word8 
UINT16 Word16 
UINT32 Word32 
UINT64 Word64 
FLOAT Float 
DOUBLE Double 
STRING Utf8 
WSTRING Utf16 
STRUCT Struct 
LIST BondDataType [Value] 
SET BondDataType [Value] 
MAP BondDataType BondDataType [(Value, Value)] 
BONDED (Bonded Struct) 

Instances

Marshalling

Since Bond supports multiple serialization protocols, application endpoints either have to agree on a particular protocol, or include protocol metadata in the payload. Marshaling APIs provide the standard way to do the latter, by automatically adding a payload header with the protocol identifier and version.

See bondMarshal, bondMarshalWithSchema and bondMarshalTagged for serialization.

bondUnmarshal :: BondStruct a => ByteString -> Either String a Source

Deserialize structure from stream, finding protocol from stream header.

bondUnmarshalWithSchema :: StructSchema -> ByteString -> Either String Struct Source

Deserialize structure from stream with provided schema, finding protocol from stream header.

bondUnmarshalTagged :: ByteString -> Either String Struct Source

Deserialize structure from stream without schema, finding protocol from stream header.

Misc

class IsString a => EncodedString a where Source

Bond string/wstring transformations from/to String and Text.

Minimal complete definition

fromText, toText

Methods

toString :: a -> String Source

Convert to String

fromText :: Text -> a Source

Make bond string from Text

toText :: a -> Text Source

Convert to Text

Instances

newtype Ordinal Source

Bond structure field ordinal.

Constructors

Ordinal Word16 

Instances

defaultValue :: Default a => a Source

Get default value for specified type.

Reexported from generated code

newtype BondDataType Source

Constructors

BondDataType Int32 

Instances

bT_BOOL :: BondDataType Source

bT_UINT8 :: BondDataType Source

bT_UINT16 :: BondDataType Source

bT_UINT32 :: BondDataType Source

bT_UINT64 :: BondDataType Source

bT_FLOAT :: BondDataType Source

bT_DOUBLE :: BondDataType Source

bT_STRING :: BondDataType Source

bT_STRUCT :: BondDataType Source

bT_LIST :: BondDataType Source

bT_SET :: BondDataType Source

bT_MAP :: BondDataType Source

bT_INT8 :: BondDataType Source

bT_INT16 :: BondDataType Source

bT_INT32 :: BondDataType Source

bT_INT64 :: BondDataType Source

bT_WSTRING :: BondDataType Source

data SchemaDef Source

Instances