-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Type driven generic aeson instance customisation -- -- This package provides a newtype wrapper with FromJSON/ToJSON instances -- customisable via a phantom type parameter. The instances can be -- rendered to the original type using DerivingVia. @package deriving-aeson @version 0.2 -- | Type-directed aeson instance CustomJSONisation module Deriving.Aeson -- | A newtype wrapper which gives FromJSON/ToJSON instances with modified -- options. newtype CustomJSON t a CustomJSON :: a -> CustomJSON t a [unCustomJSON] :: CustomJSON t a -> a -- | Function applied to field labels. Handy for removing common record -- prefixes for example. data FieldLabelModifier t -- | Function applied to constructor tags which could be handy for -- lower-casing them for example. data ConstructorTagModifier t -- | Record fields with a Nothing value will be omitted from the resulting -- object. data OmitNothingFields -- | Encode types with a single constructor as sums, so that -- allNullaryToStringTag and sumEncoding apply. data TagSingleConstructors -- | the encoding will always follow the sumEncoding. data NoAllNullaryToStringTag data SumTaggedObject t c data SumUntaggedValue data SumObjectWithSingleField data SumTwoElemArray -- | Strip prefix t. If it doesn't have the prefix, keep it as-is. data StripPrefix t -- | CamelCase to kebab-case data CamelToKebab -- | CamelCase to snake_case data CamelToSnake -- | Reify Options from a type-level list class AesonOptions xs aesonOptions :: AesonOptions xs => Options -- | Reify a function which modifies names class StringModifier t getStringModifier :: StringModifier t => String -> String -- | A type that can be converted from JSON, with the possibility of -- failure. -- -- In many cases, you can get the compiler to generate parsing code for -- you (see below). To begin, let's cover writing an instance by hand. -- -- There are various reasons a conversion could fail. For example, an -- Object could be missing a required key, an Array could -- be of the wrong size, or a value could be of an incompatible type. -- -- The basic ways to signal a failed conversion are as follows: -- --

fail yields a custom error message: it is the recommended -- way of reporting a failure;
empty (or mzero) is uninformative: use it when the -- error is meant to be caught by some (<|>);
typeMismatch can be used to report a failure when the -- encountered value is not of the expected JSON type; unexpected -- is an appropriate alternative when more than one type may be expected, -- or to keep the expected type implicit.

-- -- prependFailure (or modifyFailure) add more information -- to a parser's error messages. -- -- An example type and instance using typeMismatch and -- prependFailure: -- --

--   -- Allow ourselves to write Text literals.
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   data Coord = Coord { x :: Double, y :: Double }
--   
--   instance FromJSON Coord where
--       parseJSON (Object v) = Coord
--           <$> v .: "x"
--           <*> v .: "y"
--   
--       -- We do not expect a non-Object value here.
--       -- We could use empty to fail, but typeMismatch
--       -- gives a much more informative error message.
--       parseJSON invalid    =
--           prependFailure "parsing Coord failed, "
--               (typeMismatch "Object" invalid)
--

-- -- For this common case of only being concerned with a single type of -- JSON value, the functions withObject, withScientific, -- etc. are provided. Their use is to be preferred when possible, since -- they are more terse. Using withObject, we can rewrite the above -- instance (assuming the same language extension and data type) as: -- --

--   instance FromJSON Coord where
--       parseJSON = withObject "Coord" $ \v -> Coord
--           <$> v .: "x"
--           <*> v .: "y"
--

-- -- Instead of manually writing your FromJSON instance, there are -- two options to do it automatically: -- --

Data.Aeson.TH provides Template Haskell functions which -- will derive an instance at compile time. The generated instance is -- optimized for your type so it will probably be more efficient than the -- following option.
The compiler can provide a default generic implementation for -- parseJSON.

-- -- To use the second, simply add a deriving Generic -- clause to your datatype and declare a FromJSON instance for -- your datatype without giving a definition for parseJSON. -- -- For example, the previous example can be simplified to just: -- --

--   {-# LANGUAGE DeriveGeneric #-}
--   
--   import GHC.Generics
--   
--   data Coord = Coord { x :: Double, y :: Double } deriving Generic
--   
--   instance FromJSON Coord
--

-- -- The default implementation will be equivalent to parseJSON = -- genericParseJSON defaultOptions; if you need -- different options, you can customize the generic decoding by defining: -- --

--   customOptions = defaultOptions
--                   { fieldLabelModifier = map toUpper
--                   }
--   
--   instance FromJSON Coord where
--       parseJSON = genericParseJSON customOptions
--

class FromJSON a -- | A type that can be converted to JSON. -- -- Instances in general must specify toJSON and -- should (but don't need to) specify toEncoding. -- -- An example type and instance: -- --

--   -- Allow ourselves to write Text literals.
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   data Coord = Coord { x :: Double, y :: Double }
--   
--   instance ToJSON Coord where
--     toJSON (Coord x y) = object ["x" .= x, "y" .= y]
--   
--     toEncoding (Coord x y) = pairs ("x" .= x <> "y" .= y)
--

-- -- Instead of manually writing your ToJSON instance, there are two -- options to do it automatically: -- --

Data.Aeson.TH provides Template Haskell functions which -- will derive an instance at compile time. The generated instance is -- optimized for your type so it will probably be more efficient than the -- following option.
The compiler can provide a default generic implementation for -- toJSON.

-- -- To use the second, simply add a deriving Generic -- clause to your datatype and declare a ToJSON instance. If you -- require nothing other than defaultOptions, it is sufficient to -- write (and this is the only alternative where the default -- toJSON implementation is sufficient): -- --

--   {-# LANGUAGE DeriveGeneric #-}
--   
--   import GHC.Generics
--   
--   data Coord = Coord { x :: Double, y :: Double } deriving Generic
--   
--   instance ToJSON Coord where
--       toEncoding = genericToEncoding defaultOptions
--

-- -- If on the other hand you wish to customize the generic decoding, you -- have to implement both methods: -- --

--   customOptions = defaultOptions
--                   { fieldLabelModifier = map toUpper
--                   }
--   
--   instance ToJSON Coord where
--       toJSON     = genericToJSON customOptions
--       toEncoding = genericToEncoding customOptions
--

-- -- Previous versions of this library only had the toJSON method. -- Adding toEncoding had two reasons: -- --

toEncoding is more efficient for the common case that the output -- of toJSON is directly serialized to a ByteString. -- Further, expressing either method in terms of the other would be -- non-optimal.
The choice of defaults allows a smooth transition for existing -- users: Existing instances that do not define toEncoding still -- compile and have the correct semantics. This is ensured by making the -- default implementation of toEncoding use toJSON. This -- produces correct results, but since it performs an intermediate -- conversion to a Value, it will be less efficient than directly -- emitting an Encoding. (this also means that specifying nothing -- more than instance ToJSON Coord would be sufficient as a -- generically decoding instance, but there probably exists no good -- reason to not specify toEncoding in new instances.)

class ToJSON a -- | Representable types of kind *. This class is derivable in GHC -- with the DeriveGeneric flag on. -- -- A Generic instance must satisfy the following laws: -- --

--   from . to ≡ id
--   to . from ≡ id
--

class Generic a instance forall k (t :: k) a. (Deriving.Aeson.AesonOptions t, GHC.Generics.Generic a, Data.Aeson.Types.FromJSON.GFromJSON Data.Aeson.Types.Generic.Zero (GHC.Generics.Rep a)) => Data.Aeson.Types.FromJSON.FromJSON (Deriving.Aeson.CustomJSON t a) instance forall k (t :: k) a. (Deriving.Aeson.AesonOptions t, GHC.Generics.Generic a, Data.Aeson.Types.Class.GToJSON Data.Aeson.Types.Generic.Zero (GHC.Generics.Rep a), Data.Aeson.Types.Class.GToEncoding Data.Aeson.Types.Generic.Zero (GHC.Generics.Rep a)) => Data.Aeson.Types.ToJSON.ToJSON (Deriving.Aeson.CustomJSON t a) instance Deriving.Aeson.AesonOptions '[] instance Deriving.Aeson.AesonOptions xs => Deriving.Aeson.AesonOptions (Deriving.Aeson.OmitNothingFields : xs) instance forall k (f :: k) (xs :: [*]). (Deriving.Aeson.StringModifier f, Deriving.Aeson.AesonOptions xs) => Deriving.Aeson.AesonOptions (Deriving.Aeson.FieldLabelModifier f : xs) instance forall k (f :: k) (xs :: [*]). (Deriving.Aeson.StringModifier f, Deriving.Aeson.AesonOptions xs) => Deriving.Aeson.AesonOptions (Deriving.Aeson.ConstructorTagModifier f : xs) instance Deriving.Aeson.AesonOptions xs => Deriving.Aeson.AesonOptions (Deriving.Aeson.TagSingleConstructors : xs) instance Deriving.Aeson.AesonOptions xs => Deriving.Aeson.AesonOptions (Deriving.Aeson.NoAllNullaryToStringTag : xs) instance (GHC.TypeLits.KnownSymbol t, GHC.TypeLits.KnownSymbol c, Deriving.Aeson.AesonOptions xs) => Deriving.Aeson.AesonOptions (Deriving.Aeson.SumTaggedObject t c : xs) instance (GHC.TypeLits.KnownSymbol t, GHC.TypeLits.KnownSymbol c, Deriving.Aeson.AesonOptions xs) => Deriving.Aeson.AesonOptions (Deriving.Aeson.SumUntaggedValue : xs) instance (GHC.TypeLits.KnownSymbol t, GHC.TypeLits.KnownSymbol c, Deriving.Aeson.AesonOptions xs) => Deriving.Aeson.AesonOptions (Deriving.Aeson.SumObjectWithSingleField : xs) instance (GHC.TypeLits.KnownSymbol t, GHC.TypeLits.KnownSymbol c, Deriving.Aeson.AesonOptions xs) => Deriving.Aeson.AesonOptions (Deriving.Aeson.SumTwoElemArray : xs) instance GHC.TypeLits.KnownSymbol k => Deriving.Aeson.StringModifier (Deriving.Aeson.StripPrefix k) instance (Deriving.Aeson.StringModifier a, Deriving.Aeson.StringModifier b) => Deriving.Aeson.StringModifier (a, b) instance Deriving.Aeson.StringModifier Deriving.Aeson.CamelToKebab instance Deriving.Aeson.StringModifier Deriving.Aeson.CamelToSnake module Deriving.Aeson.Stock -- | Field names are prefixed by str; strip them from JSON -- representation type Prefixed str = CustomJSON '[FieldLabelModifier (StripPrefix str)] -- | Strip str prefices and convert from CamelCase to snake_case type PrefixedSnake str = CustomJSON '[FieldLabelModifier (StripPrefix str, CamelToSnake)] -- | Convert from CamelCase to snake_case type Snake = CustomJSON '[FieldLabelModifier CamelToSnake] -- | No customisation type Vanilla = CustomJSON '[] -- | A newtype wrapper which gives FromJSON/ToJSON instances with modified -- options. newtype CustomJSON t a CustomJSON :: a -> CustomJSON t a [unCustomJSON] :: CustomJSON t a -> a -- | A type that can be converted from JSON, with the possibility of -- failure. -- -- In many cases, you can get the compiler to generate parsing code for -- you (see below). To begin, let's cover writing an instance by hand. -- -- There are various reasons a conversion could fail. For example, an -- Object could be missing a required key, an Array could -- be of the wrong size, or a value could be of an incompatible type. -- -- The basic ways to signal a failed conversion are as follows: -- --

fail yields a custom error message: it is the recommended -- way of reporting a failure;
empty (or mzero) is uninformative: use it when the -- error is meant to be caught by some (<|>);
typeMismatch can be used to report a failure when the -- encountered value is not of the expected JSON type; unexpected -- is an appropriate alternative when more than one type may be expected, -- or to keep the expected type implicit.