@@ -44,6 +44,7 @@ module Data.Aeson.Types.Internal
45 , parseEither
45 , parseEither
46 , parseMaybe
46 , parseMaybe
47 , modifyFailure
48 , modifyFailure
48 , prependFailure
49 , prependFailure
49 , parserThrowError
50 , parserThrowError
@@ -94,7 +95,6 @@ import Data.HashMap.Strict (HashMap)
94import Data.Hashable (Hashable(..))
95import Data.Hashable (Hashable(..))
95import Data.List (intercalate)
96import Data.List (intercalate)
96import Data.Scientific (Scientific)
97import Data.Scientific (Scientific)
97−import Data.Semigroup (Semigroup((<>)))
98import Data.String (IsString(..))
98import Data.String (IsString(..))
99import Data.Text (Text, pack, unpack)
99import Data.Text (Text, pack, unpack)
100import Data.Time (UTCTime)
100import Data.Time (UTCTime)
@@ -342,6 +342,10 @@ instance Monoid (Parser a) where
342 mappend = (<>)
342 mappend = (<>)
343 {-# INLINE mappend #-}
343 {-# INLINE mappend #-}
345+-- | Raise a parsing failure with some custom message.
346+parseFail :: String -> Parser a
345apP :: Parser (a -> b) -> Parser a -> Parser b
349apP :: Parser (a -> b) -> Parser a -> Parser b
346apP d e = do
350apP d e = do
@@ -581,41 +585,53 @@ data Options = Options
581 -- the constructor tag. If 'False' the encoding will always
585 -- the constructor tag. If 'False' the encoding will always
582 -- follow the `sumEncoding`.
586 -- follow the `sumEncoding`.
583 , omitNothingFields :: Bool
587 , omitNothingFields :: Bool
584− -- ^ If 'True' record fields with a 'Nothing' value will be
588+ -- ^ If 'True', record fields with a 'Nothing' value will be
585− -- omitted from the resulting object. If 'False' the resulting
589+ -- omitted from the resulting object. If 'False', the resulting
586 -- object will include those fields mapping to @null@.
590 -- object will include those fields mapping to @null@.
592+ -- Note that this /does not/ affect parsing: 'Maybe' fields are
593+ -- optional regardless of the value of 'omitNothingFields', subject
594+ -- to the note below.
588 -- === Note
596 -- === Note
590 -- Setting 'omitNothingFields' to 'True' only affects fields which are of
598 -- Setting 'omitNothingFields' to 'True' only affects fields which are of
591− -- type 'Maybe' /uniformly/ in the 'ToJSON' or 'FromJSON' instance. In
599+ -- type 'Maybe' /uniformly/ in the 'ToJSON' instance.
592− -- particular, if the type of a field is declared as a type variable, it
600+ -- In particular, if the type of a field is declared as a type variable, it
593 -- will not be omitted from the JSON object, unless the field is
601 -- will not be omitted from the JSON object, unless the field is
594 -- specialized upfront in the instance.
602 -- specialized upfront in the instance.
604+ -- The same holds for 'Maybe' fields being optional in the 'FromJSON' instance.
596 -- ==== __Example__
606 -- ==== __Example__
598 -- The generic instance for the following type @Fruit@ depends on whether
608 -- The generic instance for the following type @Fruit@ depends on whether
599 -- the instance head is @Fruit a@ or @Fruit (Maybe a)@.
609 -- the instance head is @Fruit a@ or @Fruit (Maybe a)@.
602− -- data Fruit a =
612+ -- data Fruit a = Fruit
603 -- { apples :: a -- A field whose type is a type variable.
613 -- { apples :: a -- A field whose type is a type variable.
604 -- , oranges :: 'Maybe' Int
614 -- , oranges :: 'Maybe' Int
605− -- }
615+ -- } deriving 'Generic'
607− -- options :: 'Options'
608− -- options = 'defaultOptions' { 'omitNothingFields' = 'True' }
610 -- -- apples required, oranges optional
617 -- -- apples required, oranges optional
611 -- -- Even if 'Data.Aeson.fromJSON' is then specialized to (Fruit ('Maybe' a)).
618 -- -- Even if 'Data.Aeson.fromJSON' is then specialized to (Fruit ('Maybe' a)).
612− -- instance 'Data.Aeson.FromJSON' a => 'Data.Aeson.FromJSON' (Fruit a) where
619+ -- instance 'Data.Aeson.FromJSON' a => 'Data.Aeson.FromJSON' (Fruit a)
613− -- 'Data.Aeson.fromJSON' = 'Data.Aeson.genericFromJSON' options
615 -- -- apples optional, oranges optional
621 -- -- apples optional, oranges optional
616 -- -- In this instance, the field apples is uniformly of type ('Maybe' a).
622 -- -- 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
623+ -- instance 'Data.Aeson.FromJSON' a => 'Data.Aeson.FromJSON' (Fruit ('Maybe' a))
618− -- 'Data.Aeson.fromJSON' = 'Data.Aeson.genericFromJSON' options
624+ --
625+ -- options :: 'Options'
626+ -- options = 'defaultOptions' { 'omitNothingFields' = 'True' }
628+ -- -- apples always present in the output, oranges is omitted if 'Nothing'
629+ -- instance 'Data.Aeson.ToJSON' a => 'Data.Aeson.ToJSON' (Fruit a) where
630+ -- 'Data.Aeson.toJSON' = 'Data.Aeson.genericToJSON' options
632+ -- -- both apples and oranges are omitted if 'Nothing'
633+ -- instance 'Data.Aeson.ToJSON' a => 'Data.Aeson.ToJSON' (Fruit ('Maybe' a)) where
634+ -- 'Data.Aeson.toJSON' = 'Data.Aeson.genericToJSON' options
620 , sumEncoding :: SumEncoding
636 , sumEncoding :: SumEncoding
621 -- ^ Specifies how to encode constructors of a sum datatype.
637 -- ^ Specifies how to encode constructors of a sum datatype.