scodec

Type Members

1. sealed abstract class Attempt[+A] extends Product with Serializable

   

   Right biased Either[Err, A].

   Right biased Either[Err, A].

   An Attempt is either an Attempt.Successful or an Attempt.Failure. Attempts can be created by calling Attempt.successful or Attempt.failure, as well as converting from an Option via fromOption.

2. trait Codec[A] extends GenCodec[A, A]

   

   Supports encoding a value of type A to a BitVector and decoding a BitVector to a value of A.

   Supports encoding a value of type A to a BitVector and decoding a BitVector to a value of A.

   Not every value of A can be encoded to a bit vector and similarly, not every bit vector can be decoded to a value of type A. Hence, both encode and decode return either an error or the result. Furthermore, decode returns the remaining bits in the bit vector that it did not use in decoding.

   There are various ways to create instances of Codec. The trait can be implemented directly or one of the constructor methods in the companion can be used (e.g., apply). Most of the methods on Codec create return a new codec that has been transformed in some way. For example, the xmap method converts a Codec[A] to a Codec[B] given two functions, A => B and B => A.

   One of the simplest transformation methods is def withContext(context: String): Codec[A], which pushes the specified context string in to any errors (i.e., Errs) returned from encode or decode.

   See the methods on this trait for additional transformation types.

   See the codecs package object for pre-defined codecs for many common data types and combinators for building larger codecs out of smaller ones.

   Tuple Codecs

   The ~ operator supports combining a Codec[A] and a Codec[B] in to a Codec[(A, B)].

   For example:

   val codec: Codec[Int ~ Int ~ Int] = uint8 ~ uint8 ~ uint8

   Codecs generated with ~ result in left nested tuples. These left nested tuples can be pulled back apart by pattern matching with ~. For example:

   Codec.decode(uint8 ~ uint8 ~ uint8, bytes) map { case a ~ b ~ c => a + b + c }

   Alternatively, a function of N arguments can be lifted to a function of left-nested tuples. For example:

   val add3 = (_: Int) + (_: Int) + (_: Int)
   Codec.decode(uint8 ~ uint8 ~ uint8, bytes) map add3

   Similarly, a left nested tuple can be created with the ~ operator. This is useful when creating the tuple structure to pass to encode. For example:

   (uint8 ~ uint8 ~ uint8).encode(1 ~ 2 ~ 3)

   Tuple based codecs are of limited use compared to HList based codecs, which is discussed later.

   Note: this design is heavily based on Scala's parser combinator library and the syntax it provides.

   flatZip

   Sometimes when combining codecs, a latter codec depends on a formerly decoded value. The flatZip method is important in these types of situations -- it represents a dependency between the left hand side and right hand side. Its signature is def flatZip[B](f: A => Codec[B]): Codec[(A, B)]. This is similar to flatMap except the return type is Codec[(A, B)] instead of Decoder[B].

   Consider a binary format of an 8-bit unsigned integer indicating the number of bytes following it. To implement this with flatZip, we could write:

   val x: Codec[(Int, ByteVector)] = uint8 flatZip { numBytes => bytes(numBytes) }
   val y: Codec[ByteVector] = x.xmap[ByteVector]({ case (_, bv) => bv }, bv => (bv.size, bv))

   In this example, x is a Codec[(Int, ByteVector)] but we do not need the size directly in the model because it is redundant with the size stored in the ByteVector. Hence, we remove the Int by xmap-ping over x. The notion of removing redundant data from models comes up frequently. Note: there is a combinator that expresses this pattern more succinctly -- variableSizeBytes(uint8, bytes).

   HList Codecs

   HLists are similar to tuples in that they represent the product of an arbitrary number of types. That is, the size of an HList is known at compile time and the type of each element is also known at compile time. For more information on HLists in general, see Shapeless.

   Codec makes heavy use of HLists. The primary operation is extending a Codec[L] for some L <: HList to a Codec[A :: L]. For example:

   val uint8: Codec[Int] = ...
   val string: Codec[String] = ...
   val codec: Codec[Int :: Int :: String] = uint8 :: uint8 :: string

   The :: method is sort of like cons-ing on to the HList but it is doing so *inside* the Codec type. The resulting codec encodes values by passing each component of the HList to the corresponding codec and concatenating all of the results.

   There are various methods on this trait that only work on Codec[L] for some L <: HList. Besides the aforementioned :: method, there are others like :::, flatPrepend, flatConcat, etc. One particularly useful method is dropUnits, which removes any Unit values from the HList.

   Given a Codec[X0 :: X1 :: ... Xn :: HNil] and a case class with types X0 to Xn in the same order, the HList codec can be turned in to a case class codec via the as method. For example:

   case class Point(x: Int, y: Int, z: Int)
   val threeInts: Codec[Int :: Int :: Int :: HNil] = uint8 :: uint8 :: uint8
   val point: Codec[Point] = threeInts.as[Point]

   flatPrepend

   The HList analog to flatZip is flatPrepend. It has the signature:

   def flatPrepend[L <: HList](f: A => Codec[L]): Codec[A :: L]

   It forms a codec of A consed on to L when called on a Codec[A] and passed a function A => Codec[L]. Note that the specified function must return an HList based codec. Implementing our example from earlier using flatPrepend:

   val x: Codec[Int :: ByteVector :: HNil] = uint8 flatPrepend { numBytes => bytes(numBytes).hlist }

   In this example, bytes(numBytes) returns a Codec[ByteVector] so we called .hlist on it to lift it in to a Codec[ByteVector :: HNil].

   There are similar methods for flat appending and flat concating.

   Coproduct Codecs

   Given some ordered list of types, potentially with duplicates, a value of the HList of those types has a value for *every* type in the list. In other words, an HList represents having an X0 AND X1 AND ... AND XN. A Coproduct for the same list of types represents having a value for *one* of those types. In other words, a Coproduct represents having an X0 OR X1 OR ... OR XN. This is somewhat imprecise because a coproduct can tell us exactly which Xi we have, even in the presence of duplicate types.

   A coproduct can also be thought of as an Either that has an unlimited number of choices instead of just 2 choices.

   Shapeless represents coproducts in a similar way as HLists. A coproduct type is built using the :+: operator with a sentinal value of CNil. For example, an Int or Long or String is represented as the coproduct type:

   Int :+: Long :+: String :+: CNil

   For more information on coproducts in general, see Shapeless.

   Like HList based codecs, scodec supports Coproduct based codecs by coopting syntax from Shapeless. Specifically, the :+: operator is used:

   val builder = uint8 :+: int64 :+: utf8

   Unlike HList based codecs, the result of :+: is not a codec but rather a codecs.CoproductCodecBuilder. Having a list of types and a codec for each is not sufficient to build a coproduct codec. We also need to describe how each entry in the coproduct is differentiated from the other entries. There are a number of ways to do this and each way changes the binary format significantly. See the docs on CoproductCodecBuilder for details.

   Derived Codecs

   Codecs for case classes and sealed class hierarchies can often be automatically derived.

   Consider this example:

   import scodec.codecs.implicits._
   case class Point(x: Int, y: Int, z: Int)
   Codec[Point].encode(Point(1, 2, 3))

   In this example, no explicit codec was defined for Point yet Codec[Point] successfully created one. It did this by "reflecting" over the structure of Point and looking up a codec for each component type (note: no runtime reflection is performed - rather, this is implemented using macro-based compile time reflection). In this case, there are three components, each of type Int, so the compiler first looked for an implicit Codec[Int]. It then combined each Codec[Int] using an HList based codec and finally converted the HList codec to a Codec[Point]. It found the implicit Codec[Int] instances due to the import of scodec.codecs.implicits._. Furthermore, if there was an error encoding or decoding a field, the field name (i.e., x, y, or z) is included as context on the Err returned.

   This works similarly for sealed class hierarchies -- each subtype is internally represented as a member of a coproduct. There must be the following implicits in scope however:

   • Discriminated[A, D] for some discriminator type D, which provides the Codec[D] to use for encoding/decoding the discriminator
   • Discriminator[A, X, D] for each subtype X of A, which provides the discriminator value for type X
   • Codec[X] for each subtype X of A

   Full examples are available in the test directory of this project.

   Implicit Codecs

   If authoring combinators that require implicit codec arguments, use shapeless.Lazy[Codec[A]] instead of Codec[A]. This prevents the occurrence of diverging implicit expansion errors.

   Miscellaneous

   Note: DecodingContext allows multiple decoders/codecs to be sequenced one after the other, with the remainder from each decode operation fed in to the input of the next.

3. type CodecTransformation = ~>[Codec, Codec]

   

   Universally quantified transformation of a Codec to a Codec.

4. final case class DecodeResult[+A](value: A, remainder: BitVector) extends Product with Serializable

   

   Result of a decoding operation, which consists of the decoded value and the remaining bits that were not consumed by decoding.

5. trait Decoder[+A] extends AnyRef

   

   Supports decoding a value of type A from a BitVector.

6. trait DecoderFunctions extends AnyRef

   

   Provides functions for working with decoders.

7. sealed abstract class DecodingContext[A] extends AnyRef

   

   Provides the ability to sequence decoding operations such that the remainder of an operation is fed in to the input of the next operation.

   Provides the ability to sequence decoding operations such that the remainder of an operation is fed in to the input of the next operation. This is useful when using codecs in for comprehensions for decoding purposes.

   Note: this is a domain specific fail fast state monad.

8. trait Encoder[-A] extends AnyRef

   

   Supports encoding a value of type A to a BitVector.

9. trait EncoderFunctions extends AnyRef

   

   Provides functions for working with encoders.

10. implicit final class EnrichedCoproductDecoder[C <: Coproduct] extends AnyVal

    

    Provides methods specific to decoders of Shapeless coproducts.

11. implicit final class EnrichedCoproductEncoder[C <: Coproduct] extends AnyVal

    

    Provides methods specific to encoders of Shapeless coproducts.

12. implicit final class EnrichedHList[L <: HList] extends AnyVal

    

    Provides additional methods on HLists.

13. trait Err extends AnyRef

    

    Describes an error.

    Describes an error.

    An error has a message and a list of context identifiers that provide insight into where an error occurs in a large structure.

    This type is not sealed so that codecs can return domain specific subtypes and dispatch on those subtypes.

14. trait GenCodec[-A, +B] extends Encoder[A] with Decoder[B]

    

    Generalized codec that allows the type to encode to vary from the type to decode.

15. implicit final class HListCodecEnrichedWithHListSupport[L <: HList] extends AnyVal

    

    Provides common operations on a Codec[HList].

16. final case class SizeBound(lowerBound: Long, upperBound: Option[Long]) extends Product with Serializable

    

    Bounds the size, in bits, of the binary encoding of a codec -- i.e., it provides a lower bound and an upper bound on the size of bit vectors returned as a result of encoding.

    Bounds the size, in bits, of the binary encoding of a codec -- i.e., it provides a lower bound and an upper bound on the size of bit vectors returned as a result of encoding.

    lowerBound

    Minimum number of bits

    upperBound

    Maximum number of bits

17. abstract class Transform[F[_]] extends AnyRef

    

    Typeclass that describes type constructors that support the exmap operation.

18. implicit class TransformSyntax[F[_], A] extends AnyRef

    

    Provides method syntax for working with a type constructor that has a Transform typeclass instance.

19. abstract class Transformer[A, B] extends AnyRef

    

    Witness operation that supports transforming an F[A] to an F[B] for all F which have a Transform instance available.

    Witness operation that supports transforming an F[A] to an F[B] for all F which have a Transform instance available.

    Annotations

    @implicitNotFound( ... )

20. implicit final class Tuple2CodecSupport[A] extends AnyVal

    

21. implicit final class ValueCodecEnrichedWithGenericSupport[A] extends AnyVal

    

    Provides syntax related to generic programming for codecs of any type.

22. implicit final class ValueCodecEnrichedWithHListSupport[A] extends AnyVal

    

    Provides HList related syntax for codecs of any type.