Cabal-3.2.0.0: A framework for packaging Haskell software
Copyright(c) 2019 Oleg Grenrus
Safe HaskellNone
LanguageHaskell2010

Distribution.Utils.Structured

Description

Structurally tag binary serialisaton stream. Useful when most Binary instances are Generic derived.

Say you have a data type

data Record = Record
  { _recordFields  :: HM.HashMap Text (Integer, ByteString)
  , _recordEnabled :: Bool
  }
  deriving (Eq, Show, Generic)

instance Binary Record
instance Structured Record

then you can serialise and deserialise Record values with a structure tag by simply

structuredEncode record :: ByteString
structuredDecode lbs :: IO Record

If structure of Record changes in between, deserialisation will fail early.

Technically, Structured is not related to Binary, and may be useful in other uses.

Synopsis

Encoding and decoding

These functions operate like binary's counterparts, but the serialised version has a structure hash in front.

structuredEncode :: forall a. (Binary a, Structured a) => a -> ByteString Source #

Structured encode. Encode a value to using binary serialisation to a lazy ByteString. Encoding starts with 16 byte large structure hash.

structuredEncodeFile :: (Binary a, Structured a) => FilePath -> a -> IO () Source #

Lazily serialise a value to a file

structuredDecode :: forall a. (Binary a, Structured a) => ByteString -> a Source #

Structured decode. Decode a value from a lazy ByteString, reconstructing the original structure. Throws pure exception on invalid inputs.

structuredDecodeFileOrFail :: (Binary a, Structured a) => FilePath -> IO (Either String a) Source #

Lazily reconstruct a value previously written to a file.

Structured class

class Typeable a => Structured a where Source #

Class of types with a known Structure.

For regular data types Structured can be derived generically.

data Record = Record { a :: Int, b :: Bool, c :: [Char] } deriving (Generic)
instance Structured Record

Since: Cabal-3.2.0.0

Minimal complete definition

Nothing

Methods

structure :: Proxy a -> Structure Source #

default structure :: (Generic a, GStructured (Rep a)) => Proxy a -> Structure Source #

Instances

Instances details
Structured Bool Source # 
Instance details

Defined in Distribution.Utils.Structured

Structured Char Source # 
Instance details

Defined in Distribution.Utils.Structured

Structured Double Source # 
Instance details

Defined in Distribution.Utils.Structured

Structured Float Source # 
Instance details

Defined in Distribution.Utils.Structured

Structured Int Source # 
Instance details

Defined in Distribution.Utils.Structured

Structured Int8 Source # 
Instance details

Defined in Distribution.Utils.Structured

Structured Int16 Source # 
Instance details

Defined in Distribution.Utils.Structured

Structured Int32 Source # 
Instance details

Defined in Distribution.Utils.Structured

Structured Int64 Source # 
Instance details

Defined in Distribution.Utils.Structured

Structured Integer Source # 
Instance details

Defined in Distribution.Utils.Structured

Structured Ordering Source # 
Instance details

Defined in Distribution.Utils.Structured

Structured Word Source # 
Instance details

Defined in Distribution.Utils.Structured

Structured Word8 Source # 
Instance details

Defined in Distribution.Utils.Structured

Structured Word16 Source # 
Instance details

Defined in Distribution.Utils.Structured

Structured Word32 Source # 
Instance details

Defined in Distribution.Utils.Structured

Structured Word64 Source # 
Instance details

Defined in Distribution.Utils.Structured

Structured () Source # 
Instance details

Defined in Distribution.Utils.Structured

Methods

structure :: Proxy () -> Structure Source #

structureHash' :: Tagged () MD5

Structured ByteString Source # 
Instance details

Defined in Distribution.Utils.Structured

Structured ByteString Source # 
Instance details

Defined in Distribution.Utils.Structured

Structured IntSet Source # 
Instance details

Defined in Distribution.Utils.Structured

Structured Text Source # 
Instance details

Defined in Distribution.Utils.Structured

Structured Text Source # 
Instance details

Defined in Distribution.Utils.Structured

Structured LocalTime Source # 
Instance details

Defined in Distribution.Utils.Structured

Structured TimeOfDay Source # 
Instance details

Defined in Distribution.Utils.Structured

Structured TimeZone Source # 
Instance details

Defined in Distribution.Utils.Structured

Structured UniversalTime Source # 
Instance details

Defined in Distribution.Utils.Structured

Structured UTCTime Source # 
Instance details

Defined in Distribution.Utils.Structured

Structured NominalDiffTime Source # 
Instance details

Defined in Distribution.Utils.Structured

Structured DiffTime Source # 
Instance details

Defined in Distribution.Utils.Structured

Structured Day Source # 
Instance details

Defined in Distribution.Utils.Structured

Structured ShortText Source # 
Instance details

Defined in Distribution.Utils.ShortText

Structured PathTemplateVariable Source # 
Instance details

Defined in Distribution.Simple.InstallDirs.Internal

Structured PathComponent Source # 
Instance details

Defined in Distribution.Simple.InstallDirs.Internal

Structured Version Source # 
Instance details

Defined in Distribution.Types.Version

Structured VersionRange Source # 
Instance details

Defined in Distribution.Types.VersionRange.Internal

Structured RepoType Source # 
Instance details

Defined in Distribution.Types.SourceRepo

Structured RepoKind Source # 
Instance details

Defined in Distribution.Types.SourceRepo

Structured SourceRepo Source # 
Instance details

Defined in Distribution.Types.SourceRepo

Structured PkgconfigVersion Source # 
Instance details

Defined in Distribution.Types.PkgconfigVersion

Structured PkgconfigVersionRange Source # 
Instance details

Defined in Distribution.Types.PkgconfigVersionRange

Structured PkgconfigName Source # 
Instance details

Defined in Distribution.Types.PkgconfigName

Structured PkgconfigDependency Source # 
Instance details

Defined in Distribution.Types.PkgconfigDependency

Structured PackageName Source # 
Instance details

Defined in Distribution.Types.PackageName

Structured UnqualComponentName Source # 
Instance details

Defined in Distribution.Types.UnqualComponentName

Structured PackageVersionConstraint Source # 
Instance details

Defined in Distribution.Types.PackageVersionConstraint

Structured LibraryVisibility Source # 
Instance details

Defined in Distribution.Types.LibraryVisibility

Structured LibraryName Source # 
Instance details

Defined in Distribution.Types.LibraryName

Structured MungedPackageName Source # 
Instance details

Defined in Distribution.Types.MungedPackageName

Structured ForeignLibType Source # 
Instance details

Defined in Distribution.Types.ForeignLibType

Structured ForeignLibOption Source # 
Instance details

Defined in Distribution.Types.ForeignLibOption

Structured FlagAssignment Source # 
Instance details

Defined in Distribution.Types.Flag

Structured FlagName Source # 
Instance details

Defined in Distribution.Types.Flag

Structured Flag Source # 
Instance details

Defined in Distribution.Types.Flag

Structured ExecutableScope Source # 
Instance details

Defined in Distribution.Types.ExecutableScope

Structured ComponentName Source # 
Instance details

Defined in Distribution.Types.ComponentName

Structured ComponentId Source # 
Instance details

Defined in Distribution.Types.ComponentId

Structured GivenComponent Source # 
Instance details

Defined in Distribution.Types.GivenComponent

Structured BuildType Source # 
Instance details

Defined in Distribution.Types.BuildType

Structured AbiHash Source # 
Instance details

Defined in Distribution.Types.AbiHash

Structured Platform Source # 
Instance details

Defined in Distribution.System

Structured Arch Source # 
Instance details

Defined in Distribution.System

Structured OS Source # 
Instance details

Defined in Distribution.System

Structured LicenseRef Source # 
Instance details

Defined in Distribution.SPDX.LicenseReference

Structured LicenseId Source # 
Instance details

Defined in Distribution.SPDX.LicenseId

Structured LicenseExceptionId Source # 
Instance details

Defined in Distribution.SPDX.LicenseExceptionId

Structured SimpleLicenseExpression Source # 
Instance details

Defined in Distribution.SPDX.LicenseExpression

Structured LicenseExpression Source # 
Instance details

Defined in Distribution.SPDX.LicenseExpression

Structured License Source # 
Instance details

Defined in Distribution.SPDX.License

Structured ModuleName Source # 
Instance details

Defined in Distribution.ModuleName

Structured ModuleRenaming Source # 
Instance details

Defined in Distribution.Types.ModuleRenaming

Structured IncludeRenaming Source # 
Instance details

Defined in Distribution.Types.IncludeRenaming

Structured Mixin Source # 
Instance details

Defined in Distribution.Types.Mixin

Structured ModuleReexport Source # 
Instance details

Defined in Distribution.Types.ModuleReexport

Structured VerbosityFlag Source # 
Instance details

Defined in Distribution.Verbosity.Internal

Structured VerbosityLevel Source # 
Instance details

Defined in Distribution.Verbosity.Internal

Structured Verbosity Source # 
Instance details

Defined in Distribution.Verbosity

Structured TestType Source # 
Instance details

Defined in Distribution.Types.TestType

Structured TestSuiteInterface Source # 
Instance details

Defined in Distribution.Types.TestSuiteInterface

Structured PackageIdentifier Source # 
Instance details

Defined in Distribution.Types.PackageId

Structured DefUnitId Source # 
Instance details

Defined in Distribution.Types.UnitId

Structured UnitId Source # 
Instance details

Defined in Distribution.Types.UnitId

Structured Module Source # 
Instance details

Defined in Distribution.Types.Module

Structured OpenModule Source # 
Instance details

Defined in Distribution.Backpack

Structured OpenUnitId Source # 
Instance details

Defined in Distribution.Backpack

Structured ExposedModule Source # 
Instance details

Defined in Distribution.Types.ExposedModule

Structured MungedPackageId Source # 
Instance details

Defined in Distribution.Types.MungedPackageId

Structured LegacyExeDependency Source # 
Instance details

Defined in Distribution.Types.LegacyExeDependency

Structured ExeDependency Source # 
Instance details

Defined in Distribution.Types.ExeDependency

Structured Dependency Source # 
Instance details

Defined in Distribution.Types.Dependency

Structured SetupBuildInfo Source # 
Instance details

Defined in Distribution.Types.SetupBuildInfo

Structured BenchmarkType Source # 
Instance details

Defined in Distribution.Types.BenchmarkType

Structured BenchmarkInterface Source # 
Instance details

Defined in Distribution.Types.BenchmarkInterface

Structured AbiDependency Source # 
Instance details

Defined in Distribution.Types.AbiDependency

Structured License Source # 
Instance details

Defined in Distribution.License

Structured InstalledPackageInfo Source # 
Instance details

Defined in Distribution.Types.InstalledPackageInfo

Structured KnownExtension Source # 
Instance details

Defined in Language.Haskell.Extension

Structured Extension Source # 
Instance details

Defined in Language.Haskell.Extension

Structured Language Source # 
Instance details

Defined in Language.Haskell.Extension

Structured AbiTag Source # 
Instance details

Defined in Distribution.Compiler

Structured CompilerId Source # 
Instance details

Defined in Distribution.Compiler

Structured CompilerFlavor Source # 
Instance details

Defined in Distribution.Compiler

Structured ConfVar Source # 
Instance details

Defined in Distribution.Types.ConfVar

Structured BuildInfo Source # 
Instance details

Defined in Distribution.Types.BuildInfo

Structured TestSuite Source # 
Instance details

Defined in Distribution.Types.TestSuite

Structured Library Source # 
Instance details

Defined in Distribution.Types.Library

Structured LibVersionInfo Source # 
Instance details

Defined in Distribution.Types.ForeignLib

Structured ForeignLib Source # 
Instance details

Defined in Distribution.Types.ForeignLib

Structured Executable Source # 
Instance details

Defined in Distribution.Types.Executable

Structured Benchmark Source # 
Instance details

Defined in Distribution.Types.Benchmark

Structured ComponentRequestedSpec Source # 
Instance details

Defined in Distribution.Types.ComponentRequestedSpec

Structured PackageDescription Source # 
Instance details

Defined in Distribution.Types.PackageDescription

Structured GenericPackageDescription Source # 
Instance details

Defined in Distribution.Types.GenericPackageDescription

Structured PathTemplate Source # 
Instance details

Defined in Distribution.Simple.InstallDirs

Structured ProgramSearchPathEntry Source # 
Instance details

Defined in Distribution.Simple.Program.Find

Structured ProgramLocation Source # 
Instance details

Defined in Distribution.Simple.Program.Types

Structured ConfiguredProgram Source # 
Instance details

Defined in Distribution.Simple.Program.Types

Structured ProfDetailLevel Source # 
Instance details

Defined in Distribution.Simple.Compiler

Structured DebugInfoLevel Source # 
Instance details

Defined in Distribution.Simple.Compiler

Structured OptimisationLevel Source # 
Instance details

Defined in Distribution.Simple.Compiler

Structured PackageDB Source # 
Instance details

Defined in Distribution.Simple.Compiler

Structured Compiler Source # 
Instance details

Defined in Distribution.Simple.Compiler

Structured ProgramDb Source # 
Instance details

Defined in Distribution.Simple.Program.Db

Structured TestShowDetails Source # 
Instance details

Defined in Distribution.Simple.Setup

Structured HaddockTarget Source # 
Instance details

Defined in Distribution.Simple.Setup

Structured ConfigFlags Source # 
Instance details

Defined in Distribution.Simple.Setup

Structured ComponentLocalBuildInfo Source # 
Instance details

Defined in Distribution.Types.ComponentLocalBuildInfo

Structured LocalBuildInfo Source # 
Instance details

Defined in Distribution.Types.LocalBuildInfo

Structured ModuleShape Source # 
Instance details

Defined in Distribution.Backpack.ModuleShape

Structured ModTime Source # 
Instance details

Defined in Distribution.Compat.Time

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

Defined in Distribution.Utils.Structured

Methods

structure :: Proxy [a] -> Structure Source #

structureHash' :: Tagged [a] MD5

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

Defined in Distribution.Utils.Structured

Methods

structure :: Proxy (Maybe a) -> Structure Source #

structureHash' :: Tagged (Maybe a) MD5

Structured a => Structured (Ratio a) Source # 
Instance details

Defined in Distribution.Utils.Structured

Methods

structure :: Proxy (Ratio a) -> Structure Source #

structureHash' :: Tagged (Ratio a) MD5

Structured a => Structured (NonEmpty a) Source # 
Instance details

Defined in Distribution.Utils.Structured

Structured v => Structured (IntMap v) Source # 
Instance details

Defined in Distribution.Utils.Structured

Structured v => Structured (Seq v) Source # 
Instance details

Defined in Distribution.Utils.Structured

Methods

structure :: Proxy (Seq v) -> Structure Source #

structureHash' :: Tagged (Seq v) MD5

Structured k => Structured (Set k) Source # 
Instance details

Defined in Distribution.Utils.Structured

Methods

structure :: Proxy (Set k) -> Structure Source #

structureHash' :: Tagged (Set k) MD5

Structured a => Structured (Option' a) Source # 
Instance details

Defined in Distribution.Compat.Semigroup

Structured a => Structured (Last' a) Source # 
Instance details

Defined in Distribution.Compat.Semigroup

Methods

structure :: Proxy (Last' a) -> Structure Source #

structureHash' :: Tagged (Last' a) MD5

Structured c => Structured (Condition c) Source # 
Instance details

Defined in Distribution.Types.Condition

Structured a => Structured (Flag a) Source # 
Instance details

Defined in Distribution.Simple.Flag

Methods

structure :: Proxy (Flag a) -> Structure Source #

structureHash' :: Tagged (Flag a) MD5

Structured a => Structured (Graph a) Source # 
Instance details

Defined in Distribution.Compat.Graph

Methods

structure :: Proxy (Graph a) -> Structure Source #

structureHash' :: Tagged (Graph a) MD5

Structured a => Structured (PerCompilerFlavor a) Source # 
Instance details

Defined in Distribution.Compiler

Structured dir => Structured (InstallDirs dir) Source # 
Instance details

Defined in Distribution.Simple.InstallDirs

Structured a => Structured (NubList a) Source # 
Instance details

Defined in Distribution.Utils.NubList

Structured a => Structured (PackageIndex a) Source # 
Instance details

Defined in Distribution.Simple.PackageIndex

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

Defined in Distribution.Utils.Structured

Methods

structure :: Proxy (Either a b) -> Structure Source #

structureHash' :: Tagged (Either a b) MD5

(Structured a1, Structured a2) => Structured (a1, a2) Source # 
Instance details

Defined in Distribution.Utils.Structured

Methods

structure :: Proxy (a1, a2) -> Structure Source #

structureHash' :: Tagged (a1, a2) MD5

(Structured k, Structured v) => Structured (Map k v) Source # 
Instance details

Defined in Distribution.Utils.Structured

Methods

structure :: Proxy (Map k v) -> Structure Source #

structureHash' :: Tagged (Map k v) MD5

(Structured a1, Structured a2, Structured a3) => Structured (a1, a2, a3) Source # 
Instance details

Defined in Distribution.Utils.Structured

Methods

structure :: Proxy (a1, a2, a3) -> Structure Source #

structureHash' :: Tagged (a1, a2, a3) MD5

(Structured v, Structured c, Structured a) => Structured (CondBranch v c a) Source # 
Instance details

Defined in Distribution.Types.CondTree

Methods

structure :: Proxy (CondBranch v c a) -> Structure Source #

structureHash' :: Tagged (CondBranch v c a) MD5

(Structured v, Structured c, Structured a) => Structured (CondTree v c a) Source # 
Instance details

Defined in Distribution.Types.CondTree

Methods

structure :: Proxy (CondTree v c a) -> Structure Source #

structureHash' :: Tagged (CondTree v c a) MD5

(Structured a1, Structured a2, Structured a3, Structured a4) => Structured (a1, a2, a3, a4) Source # 
Instance details

Defined in Distribution.Utils.Structured

Methods

structure :: Proxy (a1, a2, a3, a4) -> Structure Source #

structureHash' :: Tagged (a1, a2, a3, a4) MD5

(Structured a1, Structured a2, Structured a3, Structured a4, Structured a5) => Structured (a1, a2, a3, a4, a5) Source # 
Instance details

Defined in Distribution.Utils.Structured

Methods

structure :: Proxy (a1, a2, a3, a4, a5) -> Structure Source #

structureHash' :: Tagged (a1, a2, a3, a4, a5) MD5

(Structured a1, Structured a2, Structured a3, Structured a4, Structured a5, Structured a6) => Structured (a1, a2, a3, a4, a5, a6) Source # 
Instance details

Defined in Distribution.Utils.Structured

Methods

structure :: Proxy (a1, a2, a3, a4, a5, a6) -> Structure Source #

structureHash' :: Tagged (a1, a2, a3, a4, a5, a6) MD5

(Structured a1, Structured a2, Structured a3, Structured a4, Structured a5, Structured a6, Structured a7) => Structured (a1, a2, a3, a4, a5, a6, a7) Source # 
Instance details

Defined in Distribution.Utils.Structured

Methods

structure :: Proxy (a1, a2, a3, a4, a5, a6, a7) -> Structure Source #

structureHash' :: Tagged (a1, a2, a3, a4, a5, a6, a7) MD5

structureHash :: forall a. Structured a => Proxy a -> MD5 Source #

Semantically hashStructure . structure.

structureBuilder :: Structure -> Builder Source #

Flatten Structure into something we can calculate hash of.

As Structure can be potentially infinite. For mutually recursive types, we keep track of TypeReps, and put just TypeRep name when it's occurred another time.

genericStructure :: forall a. (Typeable a, Generic a, GStructured (Rep a)) => Proxy a -> Structure Source #

Derive structure genrically.

class GStructured (f :: Type -> Type) Source #

Used to implement genericStructure.

Minimal complete definition

gstructured

Instances

Instances details
(i ~ D, Datatype c, GStructuredSum f) => GStructured (M1 i c f) Source # 
Instance details

Defined in Distribution.Utils.Structured

Methods

gstructured :: TypeRep -> Proxy (M1 i c f) -> TypeVersion -> Structure

nominalStructure :: Typeable a => Proxy a -> Structure Source #

Use Typeable to infer name

containerStructure :: forall f a. (Typeable f, Structured a) => Proxy (f a) -> Structure Source #

Structure type

data Structure Source #

Structure of a datatype.

It can be infinite, as far as TypeReps involved are finite. (e.g. polymorphic recursion might cause troubles).

Constructors

Nominal !TypeRep !TypeVersion TypeName [Structure]

nominal, yet can be parametrised by other structures.

Newtype !TypeRep !TypeVersion TypeName Structure

a newtype wrapper

Structure !TypeRep !TypeVersion TypeName SopStructure

sum-of-products structure

Instances

Instances details
Eq Structure Source # 
Instance details

Defined in Distribution.Utils.Structured

Ord Structure Source # 
Instance details

Defined in Distribution.Utils.Structured

Show Structure Source # 
Instance details

Defined in Distribution.Utils.Structured

Generic Structure Source # 
Instance details

Defined in Distribution.Utils.Structured

Associated Types

type Rep Structure :: Type -> Type Source #

type Rep Structure Source # 
Instance details

Defined in Distribution.Utils.Structured

type Rep Structure = D1 ('MetaData "Structure" "Distribution.Utils.Structured" "Cabal-3.2.0.0" 'False) (C1 ('MetaCons "Nominal" 'PrefixI 'False) ((S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 TypeRep) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 TypeVersion)) :*: (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 TypeName) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [Structure]))) :+: (C1 ('MetaCons "Newtype" 'PrefixI 'False) ((S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 TypeRep) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 TypeVersion)) :*: (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 TypeName) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Structure))) :+: C1 ('MetaCons "Structure" 'PrefixI 'False) ((S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 TypeRep) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 TypeVersion)) :*: (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 TypeName) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 SopStructure)))))

type TypeVersion = Word32 Source #

A sematic version of a data type. Usually 0.

hashStructure :: Structure -> MD5 Source #

A MD5 hash digest of Structure.

typeName :: Functor f => (TypeName -> f TypeName) -> Structure -> f Structure Source #

A van-Laarhoven lens into TypeName of Structure

typeName :: Lens' Structure TypeName