Revision d8adc255 src/Ganeti/THH.hs
b/src/Ganeti/THH.hs | ||
---|---|---|
101 | 101 |
| OptionalSerializeNull -- ^ Field is optional, null is serialised |
102 | 102 |
deriving (Show, Eq) |
103 | 103 |
|
104 |
-- | Serialised field data type. |
|
104 |
-- | Serialised field data type describing how to generate code for the field. |
|
105 |
-- Each field has a type, which isn't captured in the type of the data type, |
|
106 |
-- but is saved in the 'Q' monad in 'fieldType'. |
|
107 |
-- |
|
108 |
-- Let @t@ be a type we want to parametrize the field with. There are the |
|
109 |
-- following possible types of fields: |
|
110 |
-- |
|
111 |
-- [Mandatory with no default.] Then @fieldType@ holds @t@, |
|
112 |
-- @fieldDefault = Nothing@ and @fieldIsOptional = NotOptional@. |
|
113 |
-- |
|
114 |
-- [Field with a default value.] Then @fieldType@ holds @t@ and |
|
115 |
-- @fieldDefault = Just exp@ where @exp@ is an expression of type @t@ and |
|
116 |
-- @fieldIsOptional = NotOptional@. |
|
117 |
-- |
|
118 |
-- [Optional, no default value.] Then @fieldType@ holds @Maybe t@, |
|
119 |
-- @fieldDefault = Nothing@ and @fieldIsOptional@ is either |
|
120 |
-- 'OptionalOmitNull' or 'OptionalSerializeNull'. |
|
121 |
-- |
|
122 |
-- Optional fields with a default value are prohibited, as their main |
|
123 |
-- intention is to represent the information that a request didn't contain |
|
124 |
-- the field data. |
|
125 |
-- |
|
126 |
-- /Custom (de)serialization:/ |
|
127 |
-- Field can have custom (de)serialization functions that are stored in |
|
128 |
-- 'fieldRead' and 'fieldShow'. If they aren't provided, the default is to use |
|
129 |
-- 'readJSON' and 'showJSON' for the field's type @t@. If they are provided, |
|
130 |
-- the type of the contained deserializing expression must be |
|
131 |
-- |
|
132 |
-- @ |
|
133 |
-- [(String, JSON.JSValue)] -> JSON.JSValue -> JSON.Result t |
|
134 |
-- @ |
|
135 |
-- |
|
136 |
-- where the first argument carries the whole record in the case the |
|
137 |
-- deserializing function needs to process additional information. |
|
138 |
-- |
|
139 |
-- The type of the contained serializing experssion must be |
|
140 |
-- |
|
141 |
-- @ |
|
142 |
-- t -> (JSON.JSValue, [(String, JSON.JSValue)]) |
|
143 |
-- @ |
|
144 |
-- |
|
145 |
-- where the result can provide extra JSON fields to include in the output |
|
146 |
-- record (or just return @[]@ if they're not needed). |
|
147 |
-- |
|
148 |
-- Note that for optional fields the type appearing in the custom functions |
|
149 |
-- is still @t@. Therefore making a field optional doesn't change the |
|
150 |
-- functions. |
|
105 | 151 |
data Field = Field { fieldName :: String |
106 | 152 |
, fieldType :: Q Type |
153 |
-- ^ the type of the field, @t@ for non-optional fields, |
|
154 |
-- @Maybe t@ for optional ones. |
|
107 | 155 |
, fieldRead :: Maybe (Q Exp) |
156 |
-- ^ an optional custom deserialization function of type |
|
157 |
-- @[(String, JSON.JSValue)] -> JSON.JSValue -> |
|
158 |
-- JSON.Result t@ |
|
108 | 159 |
, fieldShow :: Maybe (Q Exp) |
160 |
-- ^ an optional custom serialization function of type |
|
161 |
-- @t -> (JSON.JSValue, [(String, JSON.JSValue)])@ |
|
109 | 162 |
, fieldExtraKeys :: [String] |
110 | 163 |
, fieldDefault :: Maybe (Q Exp) |
164 |
-- ^ an optional default value of type @t@ |
|
111 | 165 |
, fieldConstr :: Maybe String |
112 | 166 |
, fieldIsOptional :: OptionalType |
167 |
-- ^ determines if a field is optional, and if yes, |
|
168 |
-- how |
|
113 | 169 |
, fieldDoc :: String |
114 | 170 |
} |
115 | 171 |
|
Also available in: Unified diff