@@ -44,6 +44,7 @@ module Data.Aeson.Types.Internal
4444 , parse
4545 , parseEither
4646 , parseMaybe
47+ , parseFail
4748 , modifyFailure
4849 , prependFailure
4950 , parserThrowError
@@ -342,6 +343,11 @@ instance Monoid (Parser a) where
342343 mappend = (<>)
343344 {-# INLINE mappend #-}
344345
346+-- | Raise a parsing failure with some custom message.
347+parseFail :: String -> Parser a
348+parseFail = fail
349+{-# INLINE parseFail #-}
350+
345351apP :: Parser (a -> b) -> Parser a -> Parser b
346352apP d e = do
347353 b <- d
@@ -581,41 +587,53 @@ data Options = Options
581587 -- the constructor tag. If 'False' the encoding will always
582588 -- follow the `sumEncoding`.
583589 , omitNothingFields :: Bool
584− -- ^ If 'True' record fields with a 'Nothing' value will be
585− -- omitted from the resulting object. If 'False' the resulting
590+ -- ^ If 'True', record fields with a 'Nothing' value will be
591+ -- omitted from the resulting object. If 'False', the resulting
586592 -- object will include those fields mapping to @null@.
587593 --
594+ -- Note that this /does not/ affect parsing: 'Maybe' fields are
595+ -- optional regardless of the value of 'omitNothingFields', subject
596+ -- to the note below.
597+ --
588598 -- === Note
589599 --
590600 -- Setting 'omitNothingFields' to 'True' only affects fields which are of
591− -- type 'Maybe' /uniformly/ in the 'ToJSON' or 'FromJSON' instance. In
592− -- particular, if the type of a field is declared as a type variable, it
601+ -- type 'Maybe' /uniformly/ in the 'ToJSON' instance.
602+ -- In particular, if the type of a field is declared as a type variable, it
593603 -- will not be omitted from the JSON object, unless the field is
594604 -- specialized upfront in the instance.
595605 --
606+ -- The same holds for 'Maybe' fields being optional in the 'FromJSON' instance.
607+ --
596608 -- ==== __Example__
597609 --
598610 -- The generic instance for the following type @Fruit@ depends on whether
599611 -- the instance head is @Fruit a@ or @Fruit (Maybe a)@.
600612 --
601613 -- @
602− -- data Fruit a =
614+ -- data Fruit a = Fruit
603615 -- { apples :: a -- A field whose type is a type variable.
604616 -- , oranges :: 'Maybe' Int
605− -- }
606− --
607− -- options :: 'Options'
608− -- options = 'defaultOptions' { 'omitNothingFields' = 'True' }
617+ -- } deriving 'Generic'
609618 --
610619 -- -- apples required, oranges optional
611620 -- -- Even if 'Data.Aeson.fromJSON' is then specialized to (Fruit ('Maybe' a)).
612− -- instance 'Data.Aeson.FromJSON' a => 'Data.Aeson.FromJSON' (Fruit a) where
613− -- 'Data.Aeson.fromJSON' = 'Data.Aeson.genericFromJSON' options
621+ -- instance 'Data.Aeson.FromJSON' a => 'Data.Aeson.FromJSON' (Fruit a)
614622 --
615623 -- -- apples optional, oranges optional
616624 -- -- In this instance, the field apples is uniformly of type ('Maybe' a).
617− -- instance 'Data.Aeson.FromJSON' a => 'Data.Aeson.FromJSON' (Fruit ('Maybe' a)) where
618− -- 'Data.Aeson.fromJSON' = 'Data.Aeson.genericFromJSON' options
625+ -- instance 'Data.Aeson.FromJSON' a => 'Data.Aeson.FromJSON' (Fruit ('Maybe' a))
626+ --
627+ -- options :: 'Options'
628+ -- options = 'defaultOptions' { 'omitNothingFields' = 'True' }
629+ --
630+ -- -- apples always present in the output, oranges is omitted if 'Nothing'
631+ -- instance 'Data.Aeson.ToJSON' a => 'Data.Aeson.ToJSON' (Fruit a) where
632+ -- 'Data.Aeson.toJSON' = 'Data.Aeson.genericToJSON' options
633+ --
634+ -- -- both apples and oranges are omitted if 'Nothing'
635+ -- instance 'Data.Aeson.ToJSON' a => 'Data.Aeson.ToJSON' (Fruit ('Maybe' a)) where
636+ -- 'Data.Aeson.toJSON' = 'Data.Aeson.genericToJSON' options
619637 -- @
620638 , sumEncoding :: SumEncoding
621639 -- ^ Specifies how to encode constructors of a sum datatype.