Cabal-3.2.1.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 # 
Instance details

Defined in Distribution.Utils.Structured

Structured Char # 
Instance details

Defined in Distribution.Utils.Structured

Structured Double # 
Instance details

Defined in Distribution.Utils.Structured

Structured Float # 
Instance details

Defined in Distribution.Utils.Structured

Structured Int # 
Instance details

Defined in Distribution.Utils.Structured

Structured Int8 # 
Instance details

Defined in Distribution.Utils.Structured

Structured Int16 # 
Instance details

Defined in Distribution.Utils.Structured

Structured Int32 # 
Instance details

Defined in Distribution.Utils.Structured

Structured Int64 # 
Instance details

Defined in Distribution.Utils.Structured

Structured Integer # 
Instance details

Defined in Distribution.Utils.Structured

Structured Ordering # 
Instance details

Defined in Distribution.Utils.Structured

Structured Word # 
Instance details

Defined in Distribution.Utils.Structured

Structured Word8 # 
Instance details

Defined in Distribution.Utils.Structured

Structured Word16 # 
Instance details

Defined in Distribution.Utils.Structured

Structured Word32 # 
Instance details

Defined in Distribution.Utils.Structured

Structured Word64 # 
Instance details

Defined in Distribution.Utils.Structured

Structured () # 
Instance details

Defined in Distribution.Utils.Structured

Methods

structure :: Proxy () -> Structure Source #

structureHash' :: Tagged () MD5

Structured ByteString # 
Instance details

Defined in Distribution.Utils.Structured

Structured ByteString # 
Instance details

Defined in Distribution.Utils.Structured

Structured IntSet # 
Instance details

Defined in Distribution.Utils.Structured

Structured Text # 
Instance details

Defined in Distribution.Utils.Structured

Structured Text # 
Instance details

Defined in Distribution.Utils.Structured

Structured LocalTime # 
Instance details

Defined in Distribution.Utils.Structured

Structured TimeOfDay # 
Instance details

Defined in Distribution.Utils.Structured

Structured TimeZone # 
Instance details

Defined in Distribution.Utils.Structured

Structured UniversalTime # 
Instance details

Defined in Distribution.Utils.Structured

Structured UTCTime # 
Instance details

Defined in Distribution.Utils.Structured

Structured NominalDiffTime # 
Instance details

Defined in Distribution.Utils.Structured

Structured DiffTime # 
Instance details

Defined in Distribution.Utils.Structured

Structured Day # 
Instance details

Defined in Distribution.Utils.Structured

Structured ShortText # 
Instance details

Defined in Distribution.Utils.ShortText

Structured PathTemplateVariable # 
Instance details

Defined in Distribution.Simple.InstallDirs.Internal

Structured PathComponent # 
Instance details

Defined in Distribution.Simple.InstallDirs.Internal

Structured Version # 
Instance details

Defined in Distribution.Types.Version

Structured VersionRange # 
Instance details

Defined in Distribution.Types.VersionRange.Internal

Structured RepoType # 
Instance details

Defined in Distribution.Types.SourceRepo

Structured RepoKind # 
Instance details

Defined in Distribution.Types.SourceRepo

Structured SourceRepo # 
Instance details

Defined in Distribution.Types.SourceRepo

Structured PkgconfigVersion # 
Instance details

Defined in Distribution.Types.PkgconfigVersion

Structured PkgconfigVersionRange # 
Instance details

Defined in Distribution.Types.PkgconfigVersionRange

Structured PkgconfigName # 
Instance details

Defined in Distribution.Types.PkgconfigName

Structured PkgconfigDependency # 
Instance details

Defined in Distribution.Types.PkgconfigDependency

Structured PackageName # 
Instance details

Defined in Distribution.Types.PackageName

Structured UnqualComponentName # 
Instance details

Defined in Distribution.Types.UnqualComponentName

Structured PackageVersionConstraint # 
Instance details

Defined in Distribution.Types.PackageVersionConstraint

Structured LibraryVisibility # 
Instance details

Defined in Distribution.Types.LibraryVisibility

Structured LibraryName # 
Instance details

Defined in Distribution.Types.LibraryName

Structured MungedPackageName # 
Instance details

Defined in Distribution.Types.MungedPackageName

Structured ForeignLibType # 
Instance details

Defined in Distribution.Types.ForeignLibType

Structured ForeignLibOption # 
Instance details

Defined in Distribution.Types.ForeignLibOption

Structured FlagAssignment # 
Instance details

Defined in Distribution.Types.Flag

Structured FlagName # 
Instance details

Defined in Distribution.Types.Flag

Structured Flag # 
Instance details

Defined in Distribution.Types.Flag

Structured ExecutableScope # 
Instance details

Defined in Distribution.Types.ExecutableScope

Structured ComponentName # 
Instance details

Defined in Distribution.Types.ComponentName

Structured ComponentId # 
Instance details

Defined in Distribution.Types.ComponentId

Structured GivenComponent # 
Instance details

Defined in Distribution.Types.GivenComponent

Structured BuildType # 
Instance details

Defined in Distribution.Types.BuildType

Structured AbiHash # 
Instance details

Defined in Distribution.Types.AbiHash

Structured Platform # 
Instance details

Defined in Distribution.System

Structured Arch # 
Instance details

Defined in Distribution.System

Structured OS # 
Instance details

Defined in Distribution.System

Structured LicenseRef # 
Instance details

Defined in Distribution.SPDX.LicenseReference

Structured LicenseId # 
Instance details

Defined in Distribution.SPDX.LicenseId

Structured LicenseExceptionId # 
Instance details

Defined in Distribution.SPDX.LicenseExceptionId

Structured SimpleLicenseExpression # 
Instance details

Defined in Distribution.SPDX.LicenseExpression

Structured LicenseExpression # 
Instance details

Defined in Distribution.SPDX.LicenseExpression

Structured License # 
Instance details

Defined in Distribution.SPDX.License

Structured ModuleName # 
Instance details

Defined in Distribution.ModuleName

Structured ModuleRenaming # 
Instance details

Defined in Distribution.Types.ModuleRenaming

Structured IncludeRenaming # 
Instance details

Defined in Distribution.Types.IncludeRenaming

Structured Mixin # 
Instance details

Defined in Distribution.Types.Mixin

Structured ModuleReexport # 
Instance details

Defined in Distribution.Types.ModuleReexport

Structured VerbosityFlag # 
Instance details

Defined in Distribution.Verbosity.Internal

Structured VerbosityLevel # 
Instance details

Defined in Distribution.Verbosity.Internal

Structured Verbosity # 
Instance details

Defined in Distribution.Verbosity

Structured TestType # 
Instance details

Defined in Distribution.Types.TestType

Structured TestSuiteInterface # 
Instance details

Defined in Distribution.Types.TestSuiteInterface

Structured PackageIdentifier # 
Instance details

Defined in Distribution.Types.PackageId

Structured DefUnitId # 
Instance details

Defined in Distribution.Types.UnitId

Structured UnitId # 
Instance details

Defined in Distribution.Types.UnitId

Structured Module # 
Instance details

Defined in Distribution.Types.Module

Structured OpenModule # 
Instance details

Defined in Distribution.Backpack

Structured OpenUnitId # 
Instance details

Defined in Distribution.Backpack

Structured ExposedModule # 
Instance details

Defined in Distribution.Types.ExposedModule

Structured MungedPackageId # 
Instance details

Defined in Distribution.Types.MungedPackageId

Structured LegacyExeDependency # 
Instance details

Defined in Distribution.Types.LegacyExeDependency

Structured ExeDependency # 
Instance details

Defined in Distribution.Types.ExeDependency

Structured Dependency # 
Instance details

Defined in Distribution.Types.Dependency

Structured SetupBuildInfo # 
Instance details

Defined in Distribution.Types.SetupBuildInfo

Structured BenchmarkType # 
Instance details

Defined in Distribution.Types.BenchmarkType

Structured BenchmarkInterface # 
Instance details

Defined in Distribution.Types.BenchmarkInterface

Structured AbiDependency # 
Instance details

Defined in Distribution.Types.AbiDependency

Structured License # 
Instance details

Defined in Distribution.License

Structured InstalledPackageInfo # 
Instance details

Defined in Distribution.Types.InstalledPackageInfo

Structured KnownExtension # 
Instance details

Defined in Language.Haskell.Extension

Structured Extension # 
Instance details

Defined in Language.Haskell.Extension

Structured Language # 
Instance details

Defined in Language.Haskell.Extension

Structured AbiTag # 
Instance details

Defined in Distribution.Compiler

Structured CompilerId # 
Instance details

Defined in Distribution.Compiler

Structured CompilerFlavor # 
Instance details

Defined in Distribution.Compiler

Structured ConfVar # 
Instance details

Defined in Distribution.Types.ConfVar

Structured BuildInfo # 
Instance details

Defined in Distribution.Types.BuildInfo

Structured TestSuite # 
Instance details

Defined in Distribution.Types.TestSuite

Structured Library # 
Instance details

Defined in Distribution.Types.Library

Structured LibVersionInfo # 
Instance details

Defined in Distribution.Types.ForeignLib

Structured ForeignLib # 
Instance details

Defined in Distribution.Types.ForeignLib

Structured Executable # 
Instance details

Defined in Distribution.Types.Executable

Structured Benchmark # 
Instance details

Defined in Distribution.Types.Benchmark

Structured ComponentRequestedSpec # 
Instance details

Defined in Distribution.Types.ComponentRequestedSpec

Structured PackageDescription # 
Instance details

Defined in Distribution.Types.PackageDescription

Structured GenericPackageDescription # 
Instance details

Defined in Distribution.Types.GenericPackageDescription

Structured PathTemplate # 
Instance details

Defined in Distribution.Simple.InstallDirs

Structured ProgramSearchPathEntry # 
Instance details

Defined in Distribution.Simple.Program.Find

Structured ProgramLocation # 
Instance details

Defined in Distribution.Simple.Program.Types

Structured ConfiguredProgram # 
Instance details

Defined in Distribution.Simple.Program.Types

Structured ProfDetailLevel # 
Instance details

Defined in Distribution.Simple.Compiler

Structured DebugInfoLevel # 
Instance details

Defined in Distribution.Simple.Compiler

Structured OptimisationLevel # 
Instance details

Defined in Distribution.Simple.Compiler

Structured PackageDB # 
Instance details

Defined in Distribution.Simple.Compiler

Structured Compiler # 
Instance details

Defined in Distribution.Simple.Compiler

Structured ProgramDb # 
Instance details

Defined in Distribution.Simple.Program.Db

Structured TestShowDetails # 
Instance details

Defined in Distribution.Simple.Setup

Structured HaddockTarget # 
Instance details

Defined in Distribution.Simple.Setup

Structured ConfigFlags # 
Instance details

Defined in Distribution.Simple.Setup

Structured ComponentLocalBuildInfo # 
Instance details

Defined in Distribution.Types.ComponentLocalBuildInfo

Structured LocalBuildInfo # 
Instance details

Defined in Distribution.Types.LocalBuildInfo

Structured ModuleShape # 
Instance details

Defined in Distribution.Backpack.ModuleShape

Structured ModTime # 
Instance details

Defined in Distribution.Compat.Time

Structured a => Structured [a] # 
Instance details

Defined in Distribution.Utils.Structured

Methods

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

structureHash' :: Tagged [a] MD5

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

Defined in Distribution.Utils.Structured

Methods

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

structureHash' :: Tagged (Maybe a) MD5

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

Defined in Distribution.Utils.Structured

Methods

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

structureHash' :: Tagged (Ratio a) MD5

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

Defined in Distribution.Utils.Structured

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

Defined in Distribution.Utils.Structured

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

Defined in Distribution.Utils.Structured

Methods

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

structureHash' :: Tagged (Seq v) MD5

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

Defined in Distribution.Utils.Structured

Methods

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

structureHash' :: Tagged (Set k) MD5

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

Defined in Distribution.Compat.Semigroup

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

Defined in Distribution.Compat.Semigroup

Methods

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

structureHash' :: Tagged (Last' a) MD5

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

Defined in Distribution.Types.Condition

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

Defined in Distribution.Simple.Flag

Methods

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

structureHash' :: Tagged (Flag a) MD5

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

Defined in Distribution.Compat.Graph

Methods

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

structureHash' :: Tagged (Graph a) MD5

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

Defined in Distribution.Compiler

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

Defined in Distribution.Simple.InstallDirs

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

Defined in Distribution.Utils.NubList

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

Defined in Distribution.Simple.PackageIndex

(Structured a, Structured b) => Structured (Either a b) # 
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) # 
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) # 
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) # 
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) # 
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) # 
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) # 
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) # 
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) # 
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) # 
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) # 
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 # 
Instance details

Defined in Distribution.Utils.Structured

Ord Structure # 
Instance details

Defined in Distribution.Utils.Structured

Show Structure # 
Instance details

Defined in Distribution.Utils.Structured

Generic Structure # 
Instance details

Defined in Distribution.Utils.Structured

Associated Types

type Rep Structure :: Type -> Type Source #

type Rep Structure # 
Instance details

Defined in Distribution.Utils.Structured

type Rep Structure = D1 ('MetaData "Structure" "Distribution.Utils.Structured" "Cabal-3.2.1.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