ghc/docs/libraries/Dynamic.sgml

   1 <sect> <idx/Dynamic/
   2 <label id="sec:Dynamic">
   3 <p>
   4
   5 The <tt/Dynamic/ library provides cheap-and-cheerful dynamic types for
   6 Haskell. A dynamically typed value is one which carries type
   7 information with it at run-time, and is represented here by the
   8 abstract type <tt/Dynamic/. Values can be converted into <tt/Dynamic/
   9 ones, which can then be combined and manipulated by the program using
  10 the operations provided over the abstract, dynamic type. One of
  11 these operations allows you to convert a dynamically-typed value back
  12 into a value with the same (monomorphic) type it had before converting
  13 it into a dynamically-typed value.
  14
  15 The <tt/Dynamic/ library is capable of dealing with monomorphic types
  16 only; no support for polymorphic dynamic values, but hopefully that
  17 can be added at a later stage.
  18
  19 Examples where this library may come in handy (dynamic types, really -
  20 hopefully the library provided here will suffice) are: persistent
  21 programming, interpreters, distributed programming etc.
  22
  23 The following operations are provided over the <tt/Dynamic/ type:
  24
  25 <tscreen> <verb>
  26 data Dynamic -- abstract, instance of: Show --
  27
  28 toDyn       :: Typeable a => a -> Dynamic
  29 fromDyn     :: Typeable a => Dynamic -> a -> a
  30 fromDynamic :: Typeable a => Dynamic -> Maybe a
  31 </verb></tscreen>
  32
  33 <itemize>
  34 <item> <tt/toDyn/ converts a value into a dynamic one, provided
  35 <tt/toDyn/ knows the (concrete) type representation of the value.
  36 The <tt/Typeable/ type class is used to encode this, overloading a
  37 function that returns the type representation of a value. More on this
  38 below.
  39 <item> There's two ways of going from a dynamic value to one with
  40 a concrete type: <tt/fromDyn/, tries to convert the dynamic value into
  41 a value with the same type as its second argument. If this fails, the
  42 default second argument is just returned. <tt/fromDynamic/ returns a
  43 <tt/Maybe/ type instead, <tt/Nothing/ coming back if the conversion
  44 was not possible.
  45 <item>
  46 The <tt/Dynamic/ type has got a <tt/Show/ instance which returns
  47 a pretty printed string of the type of the dynamic value. (Useful when
  48 debugging).
  49 </itemize>
  50
  51 <sect1>  <idx/Representing types/
  52 <label id="sec:Dynamic:TypeRep">
  53 <p>
  54
  55 Haskell types are represented as terms using the <tt/TypeRep/
  56 abstract type:
  57
  58 <tscreen> <verb>
  59 data TypeRep  -- abstract, instance of: Eq, Show
  60 data TyCon    -- abstract, instance of: Eq, Show
  61
  62 mkTyCon  :: String  -> TyCon
  63 mkAppTy  :: TyCon   -> [TypeRep] -> TypeRep
  64 mkFunTy  :: TypeRep -> TypeRep   -> TypeRep
  65 applyTy  :: TypeRep -> TypeRep   -> Maybe TypeRep
  66 </verb></tscreen>
  67
  68 <itemize>
  69 <item> <tt/mkAppTy/ applies a type constructor to a sequence of types,
  70 returning a type.
  71 <item> <tt/mkFunTy/ is a special case of <tt/mkAppTy/, applying
  72 the function type constructor to a pair of types.
  73 <item> <tt/applyTy/ applies a type to a function type. If possible,
  74 the result type is returned.
  75 <item> Type constructors are represented by the abstract type,
  76 <tt/TyCon/.
  77 <item>
  78 Most importantly, <tt/TypeRep/s can be compared for equality.
  79 Type equality is used when converting a <tt/Dynamic/ value into a
  80 value of some specific type, comparing the type representation that
  81 the <tt/Dynamic/ value embeds with equality of the type representation
  82 of the type we're trying to convert the dynamically-typed value into.
  83 <item>
  84 To allow comparisons between <tt/TypeRep/s to be implemented
  85 efficiently, the <em/abstract/ <tt/TyCon/ type is used, with
  86 the constructor function <tt/mkTyCon/ provided:
  87
  88 <tscreen> <verb>
  89 mkTyCon :: String -> TyCon
  90 </verb></tscreen>
  91
  92 An implementation of the <tt/Dynamic/ interface guarantees the
  93 following,
  94
  95 <tscreen> <verb>
  96  mkTyCon "a" == mkTyCon "a"
  97 </verb></tscreen>
  98
  99 A really efficient implementation is possible if we guarantee/demand
 100 that the strings are unique, and for a particular type constructor,
 101 the application <tt/mkTyCon/ to the string that represents the type
 102 constructor is never duplicated. <bf/Q:/ <em>Would this constraint be
 103 unworkable in practice?</em>
 104 <item>
 105 Both <tt/TyCon/ and <tt/TypeRep/ are instances of the <tt/Show/ type
 106 classes. To have tuple types be shown in infix form, the <tt/Show/
 107 instance guarantees that type constructors consisting of <tt/n/-commas,
 108 i.e., (<tt/mkTyCon ",,,,"/), is shown as an <tt/(n+1)/ tuple in infix
 109 form.
 110 </itemize>
 111
 112 <sect1>The <tt/Typeable/ class
 113 <nidx>Typeable class</nidx>
 114 <label id="sec:Dynamic:Typeable">
 115 <p>
 116
 117 To ease the construction of <tt/Dynamic/ values, we
 118 introduce the following type class to help working with <tt/TypeRep/s:
 119
 120 <tscreen><verb>
 121 class Typeable a where
 122   typeOf :: a -> TypeRep
 123 </verb></tscreen>
 124
 125 <itemize>
 126 <item> The <tt/typeOf/ function is overloaded to return the type
 127 representation associated with a type.
 128 <item> <bf/Important:/ The argument to <tt/typeOf/ is only used to
 129 carry type information around so that overloading can be resolved.
 130 <tt/Typeable/ instances should never, ever look at this argument.
 131 <item> The <tt/Dynamic/ library provide <tt/Typeable/ instances
 132 for all Prelude and Hugs/GHC extension library types. They are:
 133
 134 <tscreen><verb>
 135 Prelude types:
 136    Int, Char, Bool, Float, Double, Integer, (IO a),
 137    [a], (Either a b), (Maybe a), (a->b),
 138    (), (,), (,,), (,,,), (,,,,),
 139    Ordering, Complex, Array, Handle
 140 Hugs/GHC types:
 141    Addr, Word8, Word16, Word32, Word64,
 142    Int8,Int16,Int32,Int64,
 143    ForeignObj, MVar, (ST s a), (StablePtr a)
 144 GHC types:
 145    Word, ByteArray, MutableByteArray
 146 </verb></tscreen>
 147
 148 </itemize>
 149
 150 <sect1>  <idx/Utility functions/
 151 <label id="sec:Dynamic:util">
 152 <p>
 153
 154 Operations for applying a dynamic function type to a
 155 dynamically typed argument are commonly useful, and
 156 also provided:
 157
 158 <tscreen> <verb>
 159 dynApply   :: Dynamic -> Dynamic -> Dynamic -- unsafe.
 160 dynApplyMb :: Dynamic -> Dynamic -> Maybe Dynamic
 161 </verb></tscreen>