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