Commits

Bryan O'Sullivan committed 03feb16

Get rid of the (.:/) combinator.

Comments (0)

Files changed (3)

     , (.:)
     , (.:?)
     , (.!=)
-    , (.:/)
     , object
     -- * Parsing
     , json

Data/Aeson/Types.hs

     , (.:)
     , (.:?)
     , (.!=)
-    , (.:/)
     , object
     ) where
 

Data/Aeson/Types/Class.hs

     , (.:)
     , (.:?)
     , (.!=)
-    , (.:/)
     , (.=)
     , typeMismatch
     ) where
 
 -- | Helper for use in combination with '.:?' to provide default
 -- values for optional JSON object fields.
+--
+-- This combinator is most useful if the key and value can be absent
+-- from an object without affecting its validity and we know a default
+-- value to assign in that case.  If the key and value are mandatory,
+-- use '(.:)' instead.
 -- 
 -- Example usage:
 --
 -- @ v1 <- o '.:?' \"opt_field_with_dfl\" .!= \"default_val\"
 -- v2 <- o '.:'  \"mandatory_field\"
 -- v3 <- o '.:?' \"opt_field2\"
---
--- \-- alternative version of v1 using the '.:/' operator
--- v1' <- o '.:/' (\"opt_field_with_dfl\", \"default_val\")
 -- @
 (.!=) :: Parser (Maybe a) -> a -> Parser a
 pmval .!= val = fromMaybe val <$> pmval
 {-# INLINE (.!=) #-}
 
--- | Retrieve the value associated with the given key of an 'Object'.
--- The result is a default value if the key is not present, or 'empty' 
--- if the value cannot be converted to the desired type.
---
--- This accessor is most useful if the key and value can be absent 
--- from an object without affecting its validity and we know a 
--- default value to assign in that case.  If the key and value 
--- are mandatory, use '(.:)' instead.
---
--- See also '.!=' for an alternative way to represent optional fields
--- with defaulting.
-(.:/) :: (FromJSON a) => Object -> (Text, a) -> Parser a
-obj .:/ (key, val) = case H.lookup key obj of
-                       Nothing -> pure val
-                       Just v  -> parseJSON v
-{-# INLINE (.:/) #-}
-
 -- | Fail parsing due to a type mismatch, with a descriptive message.
 typeMismatch :: String -- ^ The name of the type you are trying to parse.
              -> Value  -- ^ The actual value encountered.