Safe Haskell | None |
---|---|
Language | Haskell2010 |
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
- data ParentBox b where
- ParentBox :: (IsBoxType t, IsBoxContent c) => BoxType -> c -> ParentBox t
- parentBox :: forall t c. (IsBoxType t, IsBoxContent c) => c -> ParentBox t
- emptyParentBox :: forall t. IsBoxType t => ParentBox t
- boxes :: (IsBoxType t, IsBoxContent (Boxes t ts)) => ParentBox t -> Boxes t ts -> Box t
- (^-) :: (IsBoxType t, IsBoxContent (Boxes t ts)) => ParentBox t -> Boxes t ts -> Box t
- data Boxes cont boxTypes where
- 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
).
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.
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.
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
.
Extend a b |
(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.
Box :: (IsBoxType t, IsBoxContent c) => BoxType -> c -> Box t |
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.
data BoxSizeExtension Source #
The BoxSize
can be > 2^32 in which case an BoxSizeExtension
must be
added after the type field.
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.
Type-safe box composition
data ParentBox b where Source #
A ParentBox
is a Box
but without it's children. It has no
IsBoxContent
instance, and it must be converted to a real Box
using
boxes
. This is to prevent creation of boxes with invalid children.
ParentBox :: (IsBoxType t, IsBoxContent c) => BoxType -> c -> ParentBox t |
emptyParentBox :: forall t. IsBoxType t => ParentBox t Source #
An empty parent box. This is for boxes without fields. All these boxes
contain is their obligatory BoxHeader
possibly nested boxes.
boxes :: (IsBoxType t, IsBoxContent (Boxes t ts)) => ParentBox t -> 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. It
accept a ParentBox
and the nested Boxes
and returns a Box
, if the type
checker is convinced that the parent box and the nested boxes are valid.
(^-) :: (IsBoxType t, IsBoxContent (Boxes t ts)) => ParentBox t -> Boxes t ts -> Box t infixr 1 Source #
An operator for starting a Boxes
from the parent box.
Example: > xxx :: Box "moov" > xxx = movieBox > ^- Nested (movieHeaderBox (MovieHeader ...)) > :- (trackBox > ^- Nested (trackHeaderBox (TrackHeader ...)) > :- trackReferenceBox (TrackReference ...) > :- trackGroupingIndication (TrackGroupingInd ...))
data Boxes cont boxTypes where Source #
A heterogenous collection of child boxes for a parent box wiht type cont
.
Nested :: IsBoxType t => Box t -> Boxes c '[t] | |
(:-) :: IsBoxType t => Boxes c ts -> Box t -> Boxes c (t ': ts) infixl 2 |
(IsBoxType x t, ValidBoxes x t bs) => IsBoxContent (Boxes x t bs) Source # | To be nested into a box, |
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.
UnverifiedBoxes (Boxes t ts) |
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.
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 #
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.
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.
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
newtype BoxFlags bits Source #
In addition to a BoxVersion
there can be 24 bits for custom flags etc in
a FullBox
.