@@ -171,8 +171,8 @@ name .= value = (name, toJSON value)
171{-# INLINE (.=) #-}
171{-# INLINE (.=) #-}
173-- | Construct an optional 'Pair' from a key and a Maybe value. If
173-- | Construct an optional 'Pair' from a key and a Maybe value. If
174−-- the value is Nothing, then it is omitted altogether from the
174+-- the value is Nothing, the Pair's value is set to Missing, which
175−-- resulting Object.
175+-- 'object' will remove from the resulting 'Object'.
176(.=?) :: ToJSON a => Text -> Maybe a -> Pair
176(.=?) :: ToJSON a => Text -> Maybe a -> Pair
177name .=? Nothing = (name, Missing)
177name .=? Nothing = (name, Missing)
178name .=? Just value = (name, toJSON value)
178name .=? Just value = (name, toJSON value)
@@ -214,9 +214,10 @@ obj .:? key = case M.lookup key obj of
214 Just v -> parseJSON v
214 Just v -> parseJSON v
215{-# INLINE (.:?) #-}
215{-# INLINE (.:?) #-}
217−-- | Traverse a object heirarchy.
217+-- | Traverse a object heirarchy. This is useful for traversing a
218−-- This is useful for traversing a JSON object to get to an
219−-- appropriate place before parsing.
218+-- JSON object to get to an appropriate place before parsing. If a
219+-- key is not found or it encounters a non-'Object' node, then it
220+-- returns 'Missing'.
220(./) :: Value -> Text -> Value
221(./) :: Value -> Text -> Value
221(Object obj) ./ key = case M.lookup key obj of
222(Object obj) ./ key = case M.lookup key obj of
222 Nothing -> Missing
223 Nothing -> Missing
@@ -224,8 +225,9 @@ obj .:? key = case M.lookup key obj of
224_ ./ _ = Missing
225_ ./ _ = Missing
225{-# INLINE (./) #-}
226{-# INLINE (./) #-}
227−-- | Create a 'Value' from a list of name\/value 'Pair's. If duplicate
228+-- | Create a 'Value' from a list of name\/value 'Pair's. If
228−-- keys arise, earlier keys and their associated values win.
229+-- duplicate keys arise, earlier keys and their associated values win.
230+-- Missing values will be excluded from the resulting 'Object'.
229object :: [Pair] -> Value
231object :: [Pair] -> Value
230object = Object . M.fromList . filter (notmissing . snd)
232object = Object . M.fromList . filter (notmissing . snd)
231 where notmissing Missing = False
233 where notmissing Missing = False