@hackage / xcodec

Classes for working with generically typed codecs.

Changelog

xcodec change log:

Major release 1.0

Version 1.1.0.0 (07-08-2026)

This version revamps the class interface for BinaryTranscoder. Functions now are named with octets in mind rather than bytes so that functions specific to the BinaryTranscoder are easy to spot. Namely, the following functions got renamed:

Old New
lengthBytes totalOctets
lengthBytes totalOctets
serializeValue unpackSerial
packBytes packOctets
unpackBytes unpackOctets
pushByte pushOctetTop
pushByteEnd pushOctetEnd
takeBytes takeOctetsTop
takeBytesEnd takeOctetsEnd
dropBytes dropOctetsTop
dropBytesEnd dropOctetsEnd
splitAtByte splitOffset
spanBytes spanOctetsTop
spanBytesEnd spanOctetsEnd
replicateByte replicateOctet
singleton fromOctet

The unpackValue function was replaced with the unpackValueCPU, unpackValueBE, and unpackValueLE functions, so endianness of the unpacked value can be specified.

Also the packValue function got the same change. The functions packValueBE and packValueLE replace it.

The function swapOrder is introduced so that the internal order of the transcoder can be flipped without unpacking the value.

Unit tests for xcodec can now be found as part of ipfshs.

Version 1.0.0.0 (05-21-2026)

Introducing this package to hackage.org! This module provides instances of BinaryTranscoder, a type-class for generically working on binary data formats, and StreamTranscoder a type-class interface for designing encoders and decoders on top of BinaryTranscoder.

Module Data.XCodec.BinaryTranscoder

This module provides the type-class for the BinaryTranscoder. It also provides default instances for ByteString, LazyByteString, and ShortByteString from the GHC standard library. The minimal definition for a BinaryTranscoder is currently with the following methods (where bxc is the type-parameter deriving BinaryTranscoder):

-- | Gives back the length in bytes of the Transcoder data.
lengthBytes :: bxc -> Int
-- | Unpacks transcoder data as BitSet, ie, an infinite bitarray.
unpackValue :: bxc -> BitSet
-- | Places the contents of the transcoder into a ByteString Builder.
serializeValue :: bxc -> Builder
-- | Packs Word8 values into transcoder data `bxc`.
packBytes :: [Word8] -> bxc
-- | Unpacks transcoder data into a list of bytes.
unpackBytes :: bxc -> [Word8]
-- | Prepends a byte value to the top of the transcoder data.
pushByte :: bxc -> Word8 -> bxc
-- | Appends the byte value to the end of the transcoder data.
pushByteEnd :: bxc -> Word8 -> bxc
-- | Takes a subsection of bytes from the beginning of the transcoder data.
takeBytes :: Int -> bxc -> bxc
-- | Removes bytes from the beginning of transcoder data.
dropBytes :: Int -> bxc -> bxc
-- | Removes bytes from the end of transcoder data.
takeBytesEnd :: Int -> bxc -> bxc
-- | Removes bytes from the end of transcoder data.
dropBytesEnd :: Int -> bxc -> bxc
-- | Parititions the binary data at the nth byte.
splitAtByte :: Int -> bxc -> (bxc, bxc)
-- | Repeats a byte value in binary data.
replicateByte :: Int -> Word8 -> bxc
-- | Splits byte values based on the first false result from the predicate.
spanBytes :: (Word8 -> Bool) -> bxc -> (bxc, bxc)
-- | Splits the list while the element predicate holds staring from the left
-- side.
spanBytesEnd :: (Word8 -> Bool) -> bxc -> (bxc, bxc)
Module Data.XCodec.StreamTranscoder

This module exports the type-class and methods for StreamTranscoder. It provides no default instances, and is a way for the programmer to implement generic decoders and decoders on streams of data from deriving from the BinaryTranscoder class of types. It defines the follwing method signatures:

-- | Generic Encoder signature
type Encoder xtype ytype = xtype -> ytype

-- | Generic Decoder signature
type Decoder xtype ytype = ytype -> Maybe xtype

-- | StreamTranscoder give a way to make a generic codec methods.
class (BinaryTranscoder xtype) => StreamTranscoder codec xtype ytype where
  streamEncoder :: codec -> Encoder xtype ytype
  streamDecoder :: codec -> Decoder xtype ytype