| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
Data.ByteString.IsoBaseFileFormat.Boxes.Box
Contents
Description
Definition of the most basic element in an ISOBMFF file: a box. See Chapter 4 in the standard document. A box is a container with a type, a size, possible some data and some nested boxes. The standard defines - among other characteristics - what boxes exist, what data they contain and how they are nested into each other. This library tries to capture some of these characteristics using modern Haskell type system features to provide compile checks for (partial) standard compliance.
- class BoxRules t where
- type RestrictedTo t :: Maybe [k]
- type IsTopLevelBox t :: Bool
- type RequiredNestedBoxes t :: [k]
- type GetCardinality t (c :: k) :: Cardinality
- data Cardinality
- class BoxRules t => IsBoxType t where
- class IsBoxContent a where
- data Extend a b = Extend a b
- box :: forall t c. (IsBoxType t, IsBoxContent c) => c -> Box t
- emptyBox :: forall t. IsBoxType t => Box t
- data Box b where
- Box :: (IsBoxType t, IsBoxContent c) => BoxType -> c -> Box t
- data BoxSize
- data BoxSizeExtension = BoxSizeExtension BoxSize
- data BoxType
- newtype FourCc = FourCc (Char, Char, Char, Char)
- data BoxTypeExtension = BoxTypeExtension BoxType
- boxes :: forall ts t. (IsBoxType t, ValidBoxes t ts) => Boxes t ts -> Box t
- data Boxes cont boxTypes where
- type Container parent = Boxes parent '[]
- (^-) :: (IsBoxType t, IsBoxType u) => Box t -> Box u -> Boxes t '[u]
- newtype UnverifiedBoxes t ts = UnverifiedBoxes (Boxes t ts)
- type ValidBoxes t ts = (AllAllowedIn t ts ~ True, HasAllRequiredBoxes t (RequiredNestedBoxes t) ts ~ True, CheckTopLevelOk t ~ True)
- type family AllAllowedIn (container :: k) (boxes :: [k]) :: Bool where ...
- type family CheckAllowedIn (c :: k) (t :: k) (a :: Maybe [k]) :: Bool where ...
- type NotAllowedMsg c t = (((((Text "Boxes of type: " :<>: ShowType c) :<>: Text " may not contain boxes of type ") :<>: ShowType t) :$$: ((Text "Valid containers for " :<>: ShowType t) :<>: Text " boxes are: ")) :$$: ShowType (RestrictedTo t)) :$$: (ShowType t :<>: If (IsTopLevelBox c) (Text " boxes may appear top-level in a file.") (Text " boxes must be nested."))
- type family HasAllRequiredBoxes (c :: k) (req :: [k]) (nested :: [k]) :: Bool where ...
- type IsSubSet base sub = Intersection base sub == sub
- type MissingRequired c r nested = ((((Text "Boxes of type: " :<>: ShowType c) :<>: Text " require these nested boxes: ") :<>: ShowType (RequiredNestedBoxes c)) :$$: (Text "but only these box types were nested: " :<>: ShowType nested)) :$$: (Text "e.g. this type is missing: " :<>: ShowType r)
- type family CheckTopLevelOk (t :: k) :: Bool where ...
- type NotTopLevenError c = ((Text "Boxes of type " :<>: ShowType c) :<>: Text " MUST be nested inside boxes of these types: ") :$$: ShowType (RestrictedTo c)
- type FullBox t = Extend FullBoxHeader t
- fullBox :: (IsBoxType t, IsBoxContent c) => BoxVersion -> BoxFlags 24 -> c -> Box t
- data FullBoxHeader = FullBoxHeader BoxVersion (BoxFlags 24)
- newtype BoxVersion = BoxVersion Word8
- newtype BoxFlags bits = BoxFlags Integer
- boxFlagBitMask :: KnownNat bits => BoxFlags bits -> Integer
- cropBits :: KnownNat bits => BoxFlags bits -> BoxFlags bits
Basic Types and classes
A class that describes (on the type level) how a box can be nested into
other boxes (see Boxes).
Associated Types
type RestrictedTo t :: Maybe [k] Source #
List of boxes that this box can be nested into.
type IsTopLevelBox t :: Bool Source #
If the box is also allowed 'top-level' i.e. in the file directly, not nested in an other box.
type RequiredNestedBoxes t :: [k] Source #
Describes which nested boxes MUST be present in a box using boxes.
type GetCardinality t (c :: k) :: Cardinality Source #
Describes how many times a box should be present in a container (-box).
data Cardinality Source #
Describes how many times a box should be present in a container.
Constructors
| AtMostOnce | |
| ExactlyOnce | |
| OnceOrMore |
class BoxRules t => IsBoxType t where Source #
Convert type level box types to values
Minimal complete definition
class IsBoxContent a where Source #
Types that go into a box. A box content is a piece of data that can be
reused in different instances of IsBox. It has no BoxType and hence
defines no box.
Minimal complete definition
Instances
| IsBoxContent () Source # | An empty box content can by represented by |
| IsBoxContent FullBoxHeader Source # | |
| IsBoxContent BoxTypeExtension Source # | |
| IsBoxContent FourCc Source # | |
| IsBoxContent BoxType Source # | |
| IsBoxContent BoxSizeExtension Source # | |
| IsBoxContent BoxSize Source # | |
| IsBoxContent FileType Source # | |
| IsBoxContent MediaData Source # | |
| IsBoxContent ProgressiveDownloadInformation Source # | |
| IsBoxContent Skip Source # | |
| KnownNat bits => IsBoxContent (BoxFlags Nat bits) Source # | Get the number of bytes required to store a number of bits. |
| IsBoxContent (Box t t1) Source # | |
| (IsBoxContent p, IsBoxContent c) => IsBoxContent (Extend p c) Source # | |
| IsBoxContent (UnverifiedBoxes x t bs) Source # | |
| (IsBoxType x t, ValidBoxes x t bs) => IsBoxContent (Boxes x t bs) Source # | To be nested into a box, |
Box content composed of box contents a and b.
Constructors
| Extend a b |
Instances
| (IsBoxContent p, IsBoxContent c) => IsBoxContent (Extend p c) Source # | |
Boxes
emptyBox :: forall t. IsBoxType t => Box t Source #
An empty box. This is for boxes without fields. All these boxes contain
is their obligatory BoxHeader possibly nested boxes.
A type that wraps the contents of a box and the box type.
Constructors
| Box :: (IsBoxType t, IsBoxContent c) => BoxType -> c -> Box t |
Instances
| IsBoxContent (Box t t1) Source # | |
Box Size and Type
The size of the box. If the size is limited to a (fixed) value, it can be
provided as a Word64 which will be represented as either a 32bit compact
size or as 64 bit largesize. If UnlimitedSize is used, the box extends to
the end of the file.
Constructors
| UnlimitedSize | |
| BoxSize Word64 |
data BoxSizeExtension Source #
The BoxSize can be > 2^32 in which case an BoxSizeExtension must be
added after the type field.
Constructors
| BoxSizeExtension BoxSize |
Instances
A box has a type, this is the value level representation for the box type.
A type containin a printable four letter character code.
data BoxTypeExtension Source #
When using custom types extra data must be written after the extra size information. Since the box type and the optional custom box type are not guaranteed to be consequtive, this type handles the second part seperately.
Constructors
| BoxTypeExtension BoxType |
Instances
Type-safe box composition
boxes :: forall ts t. (IsBoxType t, ValidBoxes t ts) => Boxes t ts -> Box t Source #
A box that may contain nested boxes. The nested boxes are type checked to be valid in the container box. This results in a container-box with only valid and all required child boxes. This is checked by the type system.
data Boxes cont boxTypes where Source #
A container-box with child boxes.
Constructors
| Parent :: IsBoxType t => Box t -> Boxes t '[] | |
| (:-) :: IsBoxType t => Boxes c ts -> Box t -> Boxes c (t ': ts) infixl 2 |
Instances
| (IsBoxType x t, ValidBoxes x t bs) => IsBoxContent (Boxes x t bs) Source # | To be nested into a box, |
type Container parent = Boxes parent '[] Source #
A container box that contains only the parent, and no children (yet).
(^-) :: (IsBoxType t, IsBoxType u) => Box t -> Box u -> Boxes t '[u] infixl 2 Source #
An operator for Parent parent :- firstChild
newtype UnverifiedBoxes t ts Source #
An internal wrapper type around Boxes for the IsBoxContent instance.
Since the IsBoxContent instance recursivly deconstructs a Boxes the
constraints for the validity ValidBoxes cannot be asserted. To circumvent
this the IsBoxContent instance for Boxes delegates to the instance of
UnverifiedBoxes, which has no ValidBoxes constraint in the instance head.
Constructors
| UnverifiedBoxes (Boxes t ts) |
Instances
| IsBoxContent (UnverifiedBoxes x t bs) Source # | |
Type level consistency checks
type ValidBoxes t ts = (AllAllowedIn t ts ~ True, HasAllRequiredBoxes t (RequiredNestedBoxes t) ts ~ True, CheckTopLevelOk t ~ True) Source #
A type-level check that uses BoxRules to check that the contained boxes
are standard conform.
type family AllAllowedIn (container :: k) (boxes :: [k]) :: Bool where ... Source #
A type function to check that all nested boxes are allowed in the container.
Equations
| AllAllowedIn c '[] = True | |
| AllAllowedIn c (t ': ts) = If (CheckAllowedIn c t (RestrictedTo t)) (AllAllowedIn c ts) (TypeError (NotAllowedMsg c t)) |
type family CheckAllowedIn (c :: k) (t :: k) (a :: Maybe [k]) :: Bool where ... Source #
Equations
| CheckAllowedIn c t Nothing = True | |
| CheckAllowedIn c t (Just rs) = Find c rs |
type NotAllowedMsg c t = (((((Text "Boxes of type: " :<>: ShowType c) :<>: Text " may not contain boxes of type ") :<>: ShowType t) :$$: ((Text "Valid containers for " :<>: ShowType t) :<>: Text " boxes are: ")) :$$: ShowType (RestrictedTo t)) :$$: (ShowType t :<>: If (IsTopLevelBox c) (Text " boxes may appear top-level in a file.") (Text " boxes must be nested.")) Source #
The custom (type-) error message for AllAllowedIn.
type family HasAllRequiredBoxes (c :: k) (req :: [k]) (nested :: [k]) :: Bool where ... Source #
Check that all required boxes have been nested.
Equations
| HasAllRequiredBoxes c '[] nested = True | |
| HasAllRequiredBoxes c (r ': restReq) nested = If (Find r nested) (HasAllRequiredBoxes c restReq nested) (TypeError (MissingRequired c r nested)) |
type IsSubSet base sub = Intersection base sub == sub Source #
type MissingRequired c r nested = ((((Text "Boxes of type: " :<>: ShowType c) :<>: Text " require these nested boxes: ") :<>: ShowType (RequiredNestedBoxes c)) :$$: (Text "but only these box types were nested: " :<>: ShowType nested)) :$$: (Text "e.g. this type is missing: " :<>: ShowType r) Source #
The custom (type-) error message for HasAllRequiredBoxes.
type family CheckTopLevelOk (t :: k) :: Bool where ... Source #
Check that the box may appear top-level.
Equations
| CheckTopLevelOk t = IsTopLevelBox t || TypeError (NotTopLevenError t) |
type NotTopLevenError c = ((Text "Boxes of type " :<>: ShowType c) :<>: Text " MUST be nested inside boxes of these types: ") :$$: ShowType (RestrictedTo c) Source #
The custom (type-) error message indicating that a box may not appear top-level.
Full Boxes
fullBox :: (IsBoxType t, IsBoxContent c) => BoxVersion -> BoxFlags 24 -> c -> Box t Source #
data FullBoxHeader Source #
The additional header with version and branding information
Constructors
| FullBoxHeader BoxVersion (BoxFlags 24) |
Instances
newtype BoxVersion Source #
The box version (in a FullBox) is a single byte
Constructors
| BoxVersion Word8 |
newtype BoxFlags bits Source #
In addition to a BoxVersion there can be 24 bits for custom flags etc in
a FullBox.