-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Type-safe data versioning.
--   
--   This package provides various tools to deal with data versioning in a
--   type-safe way.
@package versioning
@version 0.2.0.0

module Versioning.Internal.Base

-- | An uninhabited type. We define our own type instead of using
--   <a>Data.Void</a> because we need additional instances. Moreover this
--   type is internal. Users are supposed to use <tt>NA</tt> to express
--   absence.
data Bare
instance GHC.Classes.Eq Versioning.Internal.Base.Bare
instance GHC.Generics.Generic Versioning.Internal.Base.Bare
instance GHC.Show.Show Versioning.Internal.Base.Bare
instance Data.Aeson.Types.FromJSON.FromJSON Versioning.Internal.Base.Bare
instance Data.Aeson.Types.ToJSON.ToJSON Versioning.Internal.Base.Bare


-- | This module provides some tools to encode multiple versions of a data
--   model in a single data-type parametrized by version number. The
--   addition or removal of a field can be expressed through the
--   <a>Since</a> and <a>Until</a> type families.
--   
--   Example:
--   
--   <pre>
--   data Rec v = Rec
--       { foo :: Int               -- this field exists in all versions
--       , bar :: Since V2 v Bool   -- this field has been introduced in V2
--       , baz :: Until V2 v Double -- this field has been removed in V3
--       }
--   </pre>
--   
--   Besides reducing the number of data declarations, this approach also
--   has other advantages:
--   
--   <ul>
--   <li>It makes migrations declarative and self-documenting.</li>
--   <li>It allows for less verbose version-upcasting functions, since the
--   fields that have a non-parametric type do not need to be copied.</li>
--   <li>It is a foundation on which other useful abstractions can be
--   built.</li>
--   </ul>
--   
--   Please note that some classes may require a separate standalone
--   deriving clause for each version of a data-type or some kind of
--   inductive deriving mechanism.
module Versioning.Base

-- | The version of a data model
newtype V
V :: Nat -> V

-- | Get the type-level natural of a version

-- | Get the version number of a versioned value
versionNumber :: forall a v. KnownNat (GetV v) => a v -> Natural

-- | This allows us to express that a field is only present since a given
--   version. The first parameter is the version in which the field has
--   been introduced, the second parameter is the actual version of the
--   data-type.

-- | This allows us to express that a field is only present until a given
--   version. The first parameter is the last version in which the field is
--   present, the second parameter is the actual version of the data-type.

-- | A type indicating absence. The <a>Maybe</a> is a hack needed to let
--   aeson parse a record successfully even if a field of type <a>NA</a> is
--   missing.
--   
--   Ideally we would like to define it as
--   
--   <pre>
--   data NA = NA
--   </pre>
--   
--   but this would not work with <tt>FromJSON</tt> instances that are
--   derived with Generic.
type NA = Maybe Bare

-- | A placeholder for an absent value.
na :: NA
type V1 =  'V 1
type V2 =  'V 2
type V3 =  'V 3
type V4 =  'V 4
type V5 =  'V 5
type V6 =  'V 6
type V7 =  'V 7
type V8 =  'V 8
type V9 =  'V 9
type V10 =  'V 10
type V11 =  'V 11
type V12 =  'V 12
type V13 =  'V 13
type V14 =  'V 14
type V15 =  'V 15
type V16 =  'V 16
type V17 =  'V 17
type V18 =  'V 18
type V19 =  'V 19
type V20 =  'V 20

module Versioning.Internal.Folding

-- | Decrement version until the target version is reached

-- | Increment version until the target version is reached

module Versioning.Upgrade

-- | Adapt from a version to another
class Adapt (v :: V) (w :: V) (a :: V -> Type)
adapt :: Adapt v w a => a v -> a w

-- | Upgrade from a lower to a higher version by calling <a>adapt</a> on
--   all the intermediary steps. You do not need to define any instance.
--   They are derived automatically if all the intermediary <a>Adapt</a>
--   instances are defined.
class Upgrade (v :: V) (w :: V) (a :: V -> Type)
upgrade' :: Upgrade v w a => a v -> a w

-- | Upgrade from a lower to a higher version by calling <a>adapt</a> on
--   all the intermediary steps.
upgrade :: Upgrade v w a => a v -> a w
instance Versioning.Upgrade.Upgrade v v a
instance (Versioning.Upgrade.Adapt v (Versioning.Internal.Folding.Incr v w) a, Versioning.Upgrade.Upgrade (Versioning.Internal.Folding.Incr v w) w a) => Versioning.Upgrade.Upgrade v w a


-- | Encoding-agnosting deserialization utilities.
module Versioning.Internal.Decoding

-- | The result type of the action that has been applied to the decoded
--   object with <a>withAnyVersion</a> or <a>withAnyVersionM</a>.

-- | The pure function to apply to the decoded object with
--   <a>withAnyVersion</a>
type Apply a c = forall v. c (a v) => a v -> Applied c a

-- | The action to apply to the decoded object with <a>withAnyVersionM</a>
type ApplyM m a c = forall v. c (a v) => a v -> m (Applied c a)

-- | Handy constraint synonym to be used with <a>decodeAnyVersion</a>
type DecodableTo dec v a = DecodeAnyVersion v v a dec
class DecodeAnyVersion (v :: V) (w :: V) (a :: V -> Type) dec

-- | The function that will perform the actual decoding
newtype Decoder dec enc t a
Decoder :: (forall v. dec (a v) => enc -> t (a v)) -> Decoder dec enc t a
class WithAnyVersion (v :: V) (a :: V -> Type) c dec

-- | Decode by trying all the versions decrementally and upgrade the
--   decoded object to the newest version.
decodeAnyVersion :: forall v a dec enc t. (Alt t, Applicative t, DecodableTo dec v a) => Decoder dec enc t a -> enc -> t (a v)

-- | Pure version of <a>withAnyVersionM</a>.
withAnyVersion :: forall v c a dec enc t. (WithAnyVersion v a c dec, c (a v), Alt t, Applicative t, Traversable t) => Decoder dec enc t a -> Apply a c -> enc -> t (Applied c a)

-- | Decode by trying all the versions decrementally and apply an action to
--   the decoded object at its original version.
withAnyVersionM :: forall v c a dec enc m t. (WithAnyVersion v a c dec, Alt t, Applicative t, Traversable t, Applicative m, c (a v)) => Decoder dec enc t a -> ApplyM m a c -> enc -> m (t (Applied c a))
instance (dec (a Versioning.Base.V1), c (a Versioning.Base.V1)) => Versioning.Internal.Decoding.WithAnyVersion Versioning.Base.V1 a c dec
instance (Versioning.Internal.Decoding.WithAnyVersion (Versioning.Internal.Folding.Decr v Versioning.Base.V1) a c dec, dec (a v), dec (a (Versioning.Internal.Folding.Decr v Versioning.Base.V1)), c (a v), c (a (Versioning.Internal.Folding.Decr v Versioning.Base.V1))) => Versioning.Internal.Decoding.WithAnyVersion v a c dec
instance (dec (a Versioning.Base.V1), Versioning.Upgrade.Upgrade Versioning.Base.V1 w a) => Versioning.Internal.Decoding.DecodeAnyVersion Versioning.Base.V1 w a dec
instance (Versioning.Internal.Decoding.DecodeAnyVersion (Versioning.Internal.Folding.Decr v Versioning.Base.V1) w a dec, dec (a v), dec (a (Versioning.Internal.Folding.Decr v Versioning.Base.V1)), Versioning.Upgrade.Upgrade v w a) => Versioning.Internal.Decoding.DecodeAnyVersion v w a dec


-- | JSON-specific deserialization utilities.
module Versioning.JSON

-- | The result type of the action that has been applied to the decoded
--   object with <a>withAnyVersion</a> or <a>withAnyVersionM</a>.

-- | Handy constraint synonym to be used with <a>fromJsonAnyVersion</a>
type JsonDecodableTo v a = DecodableTo FromJSON v a

-- | Decode a JSON string by trying all the versions decrementally and
--   upgrade the decoded object to the newest version.
fromJsonAnyVersion :: forall v a. JsonDecodableTo v a => ByteString -> Maybe (a v)

-- | Like <a>fromJsonAnyVersion</a> but it reads from a strict
--   <tt>ByteString</tt>
fromJsonAnyVersionStrict :: forall v a. JsonDecodableTo v a => ByteString -> Maybe (a v)

-- | Like <a>fromJsonAnyVersion</a> but returns a message when decoding
--   fails
fromJsonAnyVersionEither :: forall v a. JsonDecodableTo v a => ByteString -> Either String (a v)

-- | Like <a>fromJsonAnyVersionStrict</a> but returns a message when
--   decoding fails
fromJsonAnyVersionEitherStrict :: forall v a. JsonDecodableTo v a => ByteString -> Either String (a v)

-- | Decode a JSON string by trying all the versions decrementally and
--   apply a pure function to the decoded object at its original version.
withJsonAnyVersion :: forall c a v. (WithAnyVersion v a c FromJSON, c (a v)) => Apply a c -> ByteString -> Maybe (Applied c a)

-- | Like <a>withJsonAnyVersion</a> but it reads from a strict
--   <tt>ByteString</tt>
withJsonAnyVersionStrict :: forall c a v. (WithAnyVersion v a c FromJSON, c (a v)) => Apply a c -> ByteString -> Maybe (Applied c a)

-- | Like <a>withJsonAnyVersion</a> but returns a message when decoding
--   fails
withJsonAnyVersionEither :: forall c a v. (WithAnyVersion v a c FromJSON, c (a v)) => Apply a c -> ByteString -> Either String (Applied c a)

-- | Like <a>withJsonAnyVersionStrict</a> but returns a message when
--   decoding fails
withJsonAnyVersionEitherStrict :: forall c a v. (WithAnyVersion v a c FromJSON, c (a v)) => Apply a c -> ByteString -> Either String (Applied c a)

-- | Decode a JSON string by trying all the versions decrementally and
--   apply an action to the decoded object at its original version.
withJsonAnyVersionM :: forall c a v m. (WithAnyVersion v a c FromJSON, Applicative m, c (a v)) => ApplyM m a c -> ByteString -> m (Maybe (Applied c a))

-- | Like <a>withJsonAnyVersionM</a> but it reads from a strict
--   <tt>ByteString</tt>
withJsonAnyVersionStrictM :: forall c a v m. (WithAnyVersion v a c FromJSON, Applicative m, c (a v)) => ApplyM m a c -> ByteString -> m (Maybe (Applied c a))

-- | Like <a>withJsonAnyVersionM</a> but returns a message when decoding
--   fails
withJsonAnyVersionEitherM :: forall c a v m. (WithAnyVersion v a c FromJSON, Applicative m, c (a v)) => ApplyM m a c -> ByteString -> m (Either String (Applied c a))

-- | Like <a>withJsonAnyVersionStrictM</a> but returns a message when
--   decoding fails
withJsonAnyVersionEitherStrictM :: forall c a v m. (WithAnyVersion v a c FromJSON, Applicative m, c (a v)) => ApplyM m a c -> ByteString -> m (Either String (Applied c a))