prelate-0.6.0.0: A Prelude
Safe HaskellSafe-Inferred
LanguageHaskell2010

Prelate.Prelude

Description

A Polysemy Prelude with some basic libraries

Synopsis

Documentation

module Incipit

type (@@) a b = Tagged b a Source #

Alias for Tagged.

class ToJSON 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:

  1. 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.
  2. 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.)

Instances

Instances details
ToJSON Key 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON DotNetTime 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON Value 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON Number 
Instance details

Defined in Data.Aeson.Types.ToJSON

Methods

toJSON :: Number -> Value #

toEncoding :: Number -> Encoding #

toJSONList :: [Number] -> Value #

toEncodingList :: [Number] -> Encoding #

ToJSON Version 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON Void 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON CTime 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON Int16 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON Int32 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON Int64 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON Int8 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON Word16 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON Word32 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON Word64 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON Word8 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON Datetime 
Instance details

Defined in Chronos

ToJSON Day 
Instance details

Defined in Chronos

ToJSON Offset 
Instance details

Defined in Chronos

ToJSON Time 
Instance details

Defined in Chronos

ToJSON Timespan 
Instance details

Defined in Chronos

ToJSON IntSet 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON Ordering 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON Days 
Instance details

Defined in Polysemy.Time.Data.TimeUnit

ToJSON Hours 
Instance details

Defined in Polysemy.Time.Data.TimeUnit

ToJSON MicroSeconds 
Instance details

Defined in Polysemy.Time.Data.TimeUnit

ToJSON MilliSeconds 
Instance details

Defined in Polysemy.Time.Data.TimeUnit

ToJSON Minutes 
Instance details

Defined in Polysemy.Time.Data.TimeUnit

ToJSON Months 
Instance details

Defined in Polysemy.Time.Data.TimeUnit

ToJSON NanoSeconds 
Instance details

Defined in Polysemy.Time.Data.TimeUnit

ToJSON Seconds 
Instance details

Defined in Polysemy.Time.Data.TimeUnit

ToJSON Weeks 
Instance details

Defined in Polysemy.Time.Data.TimeUnit

ToJSON Years 
Instance details

Defined in Polysemy.Time.Data.TimeUnit

ToJSON Scientific 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON Text 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON Text 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON ShortText

Since: aeson-2.0.2.0

Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON CalendarDiffDays 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON Day 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON Month 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON Quarter 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON QuarterOfYear 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON DayOfWeek 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON DiffTime 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON NominalDiffTime 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON SystemTime

Encoded as number

Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON UTCTime 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON CalendarDiffTime 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON LocalTime 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON TimeOfDay 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON ZonedTime 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON UUID 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON Integer 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON Natural 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON () 
Instance details

Defined in Data.Aeson.Types.ToJSON

Methods

toJSON :: () -> Value #

toEncoding :: () -> Encoding #

toJSONList :: [()] -> Value #

toEncodingList :: [()] -> Encoding #

ToJSON Bool 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON Char 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON Double 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON Float 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON Int 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON Word 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON v => ToJSON (KeyMap v) 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON a => ToJSON (Identity a) 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON a => ToJSON (First a) 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON a => ToJSON (Last a) 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON a => ToJSON (First a) 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON a => ToJSON (Last a) 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON a => ToJSON (Max a) 
Instance details

Defined in Data.Aeson.Types.ToJSON

Methods

toJSON :: Max a -> Value #

toEncoding :: Max a -> Encoding #

toJSONList :: [Max a] -> Value #

toEncodingList :: [Max a] -> Encoding #

ToJSON a => ToJSON (Min a) 
Instance details

Defined in Data.Aeson.Types.ToJSON

Methods

toJSON :: Min a -> Value #

toEncoding :: Min a -> Encoding #

toJSONList :: [Min a] -> Value #

toEncodingList :: [Min a] -> Encoding #

ToJSON a => ToJSON (WrappedMonoid a) 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON a => ToJSON (Dual a) 
Instance details

Defined in Data.Aeson.Types.ToJSON

(ToJSON a, Integral a) => ToJSON (Ratio a) 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON a => ToJSON (IntMap a) 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON a => ToJSON (Seq a) 
Instance details

Defined in Data.Aeson.Types.ToJSON

Methods

toJSON :: Seq a -> Value #

toEncoding :: Seq a -> Encoding #

toJSONList :: [Seq a] -> Value #

toEncodingList :: [Seq a] -> Encoding #

ToJSON a => ToJSON (Set a) 
Instance details

Defined in Data.Aeson.Types.ToJSON

Methods

toJSON :: Set a -> Value #

toEncoding :: Set a -> Encoding #

toJSONList :: [Set a] -> Value #

toEncodingList :: [Set a] -> Encoding #

ToJSON v => ToJSON (Tree v) 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON1 f => ToJSON (Fix f)

Since: aeson-1.5.3.0

Instance details

Defined in Data.Aeson.Types.ToJSON

Methods

toJSON :: Fix f -> Value #

toEncoding :: Fix f -> Encoding #

toJSONList :: [Fix f] -> Value #

toEncodingList :: [Fix f] -> Encoding #

(ToJSON1 f, Functor f) => ToJSON (Mu f)

Since: aeson-1.5.3.0

Instance details

Defined in Data.Aeson.Types.ToJSON

Methods

toJSON :: Mu f -> Value #

toEncoding :: Mu f -> Encoding #

toJSONList :: [Mu f] -> Value #

toEncodingList :: [Mu f] -> Encoding #

(ToJSON1 f, Functor f) => ToJSON (Nu f)

Since: aeson-1.5.3.0

Instance details

Defined in Data.Aeson.Types.ToJSON

Methods

toJSON :: Nu f -> Value #

toEncoding :: Nu f -> Encoding #

toJSONList :: [Nu f] -> Value #

toEncodingList :: [Nu f] -> Encoding #

ToJSON a => ToJSON (DNonEmpty a)

Since: aeson-1.5.3.0

Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON a => ToJSON (DList a) 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON a => ToJSON (Array a) 
Instance details

Defined in Data.Aeson.Types.ToJSON

(Prim a, ToJSON a) => ToJSON (PrimArray a) 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON a => ToJSON (SmallArray a) 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON a => ToJSON (Maybe a)

Since: aeson-1.5.3.0

Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON a => ToJSON (HashSet a) 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON a => ToJSON (Vector a) 
Instance details

Defined in Data.Aeson.Types.ToJSON

(Prim a, ToJSON a) => ToJSON (Vector a) 
Instance details

Defined in Data.Aeson.Types.ToJSON

(Storable a, ToJSON a) => ToJSON (Vector a) 
Instance details

Defined in Data.Aeson.Types.ToJSON

(Vector Vector a, ToJSON a) => ToJSON (Vector a) 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON a => ToJSON (NonEmpty a) 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON a => ToJSON (Maybe a) 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON a => ToJSON (a)

Since: aeson-2.0.2.0

Instance details

Defined in Data.Aeson.Types.ToJSON

Methods

toJSON :: (a) -> Value #

toEncoding :: (a) -> Encoding #

toJSONList :: [(a)] -> Value #

toEncodingList :: [(a)] -> Encoding #

ToJSON a => ToJSON [a] 
Instance details

Defined in Data.Aeson.Types.ToJSON

Methods

toJSON :: [a] -> Value #

toEncoding :: [a] -> Encoding #

toJSONList :: [[a]] -> Value #

toEncodingList :: [[a]] -> Encoding #

(ToJSON a, ToJSON b) => ToJSON (Either a b) 
Instance details

Defined in Data.Aeson.Types.ToJSON

Methods

toJSON :: Either a b -> Value #

toEncoding :: Either a b -> Encoding #

toJSONList :: [Either a b] -> Value #

toEncodingList :: [Either a b] -> Encoding #

HasResolution a => ToJSON (Fixed a) 
Instance details

Defined in Data.Aeson.Types.ToJSON

ToJSON (Proxy a) 
Instance details

Defined in Data.Aeson.Types.ToJSON

(ToJSON v, ToJSONKey k) => ToJSON (Map k v) 
Instance details

Defined in Data.Aeson.Types.ToJSON

Methods

toJSON :: Map k v -> Value #

toEncoding :: Map k v -> Encoding #

toJSONList :: [Map k v] -> Value #

toEncodingList :: [Map k v] -> Encoding #

(ToJSON a, ToJSON b) => ToJSON (Either a b)

Since: aeson-1.5.3.0

Instance details

Defined in Data.Aeson.Types.ToJSON

Methods

toJSON :: Either a b -> Value #

toEncoding :: Either a b -> Encoding #

toJSONList :: [Either a b] -> Value #

toEncodingList :: [Either a b] -> Encoding #

(ToJSON a, ToJSON b) => ToJSON (These a b)

Since: aeson-1.5.3.0

Instance details

Defined in Data.Aeson.Types.ToJSON

Methods

toJSON :: These a b -> Value #

toEncoding :: These a b -> Encoding #

toJSONList :: [These a b] -> Value #

toEncodingList :: [These a b] -> Encoding #

(ToJSON a, ToJSON b) => ToJSON (Pair a b)

Since: aeson-1.5.3.0

Instance details

Defined in Data.Aeson.Types.ToJSON

Methods

toJSON :: Pair a b -> Value #

toEncoding :: Pair a b -> Encoding #

toJSONList :: [Pair a b] -> Value #

toEncodingList :: [Pair a b] -> Encoding #

(ToJSON a, ToJSON b) => ToJSON (These a b)

Since: aeson-1.5.1.0

Instance details

Defined in Data.Aeson.Types.ToJSON

Methods

toJSON :: These a b -> Value #

toEncoding :: These a b -> Encoding #

toJSONList :: [These a b] -> Value #

toEncodingList :: [These a b] -> Encoding #

(ToJSON v, ToJSONKey k) => ToJSON (HashMap k v) 
Instance details

Defined in Data.Aeson.Types.ToJSON

(ToJSON a, ToJSON b) => ToJSON (a, b) 
Instance details

Defined in Data.Aeson.Types.ToJSON

Methods

toJSON :: (a, b) -> Value #

toEncoding :: (a, b) -> Encoding #

toJSONList :: [(a, b)] -> Value #

toEncodingList :: [(a, b)] -> Encoding #

ToJSON a => ToJSON (Const a b) 
Instance details

Defined in Data.Aeson.Types.ToJSON

Methods

toJSON :: Const a b -> Value #

toEncoding :: Const a b -> Encoding #

toJSONList :: [Const a b] -> Value #

toEncodingList :: [Const a b] -> Encoding #

ToJSON b => ToJSON (Tagged a b) 
Instance details

Defined in Data.Aeson.Types.ToJSON

Methods

toJSON :: Tagged a b -> Value #

toEncoding :: Tagged a b -> Encoding #

toJSONList :: [Tagged a b] -> Value #

toEncodingList :: [Tagged a b] -> Encoding #

(ToJSON1 f, ToJSON1 g, ToJSON a) => ToJSON (These1 f g a)

Since: aeson-1.5.1.0

Instance details

Defined in Data.Aeson.Types.ToJSON

Methods

toJSON :: These1 f g a -> Value #

toEncoding :: These1 f g a -> Encoding #

toJSONList :: [These1 f g a] -> Value #

toEncodingList :: [These1 f g a] -> Encoding #

(ToJSON a, ToJSON b, ToJSON c) => ToJSON (a, b, c) 
Instance details

Defined in Data.Aeson.Types.ToJSON

Methods

toJSON :: (a, b, c) -> Value #

toEncoding :: (a, b, c) -> Encoding #

toJSONList :: [(a, b, c)] -> Value #

toEncodingList :: [(a, b, c)] -> Encoding #

(ToJSON1 f, ToJSON1 g, ToJSON a) => ToJSON (Product f g a) 
Instance details

Defined in Data.Aeson.Types.ToJSON

Methods

toJSON :: Product f g a -> Value #

toEncoding :: Product f g a -> Encoding #

toJSONList :: [Product f g a] -> Value #

toEncodingList :: [Product f g a] -> Encoding #

(ToJSON1 f, ToJSON1 g, ToJSON a) => ToJSON (Sum f g a) 
Instance details

Defined in Data.Aeson.Types.ToJSON

Methods

toJSON :: Sum f g a -> Value #

toEncoding :: Sum f g a -> Encoding #

toJSONList :: [Sum f g a] -> Value #

toEncodingList :: [Sum f g a] -> Encoding #

(ToJSON a, ToJSON b, ToJSON c, ToJSON d) => ToJSON (a, b, c, d) 
Instance details

Defined in Data.Aeson.Types.ToJSON

Methods

toJSON :: (a, b, c, d) -> Value #

toEncoding :: (a, b, c, d) -> Encoding #

toJSONList :: [(a, b, c, d)] -> Value #

toEncodingList :: [(a, b, c, d)] -> Encoding #

(ToJSON1 f, ToJSON1 g, ToJSON a) => ToJSON (Compose f g a) 
Instance details

Defined in Data.Aeson.Types.ToJSON

Methods

toJSON :: Compose f g a -> Value #

toEncoding :: Compose f g a -> Encoding #

toJSONList :: [Compose f g a] -> Value #

toEncodingList :: [Compose f g a] -> Encoding #

(ToJSON a, ToJSON b, ToJSON c, ToJSON d, ToJSON e) => ToJSON (a, b, c, d, e) 
Instance details

Defined in Data.Aeson.Types.ToJSON

Methods

toJSON :: (a, b, c, d, e) -> Value #

toEncoding :: (a, b, c, d, e) -> Encoding #

toJSONList :: [(a, b, c, d, e)] -> Value #

toEncodingList :: [(a, b, c, d, e)] -> Encoding #

(ToJSON a, ToJSON b, ToJSON c, ToJSON d, ToJSON e, ToJSON f) => ToJSON (a, b, c, d, e, f) 
Instance details

Defined in Data.Aeson.Types.ToJSON

Methods

toJSON :: (a, b, c, d, e, f) -> Value #

toEncoding :: (a, b, c, d, e, f) -> Encoding #

toJSONList :: [(a, b, c, d, e, f)] -> Value #

toEncodingList :: [(a, b, c, d, e, f)] -> Encoding #

(ToJSON a, ToJSON b, ToJSON c, ToJSON d, ToJSON e, ToJSON f, ToJSON g) => ToJSON (a, b, c, d, e, f, g) 
Instance details

Defined in Data.Aeson.Types.ToJSON

Methods

toJSON :: (a, b, c, d, e, f, g) -> Value #

toEncoding :: (a, b, c, d, e, f, g) -> Encoding #

toJSONList :: [(a, b, c, d, e, f, g)] -> Value #

toEncodingList :: [(a, b, c, d, e, f, g)] -> Encoding #

(ToJSON a, ToJSON b, ToJSON c, ToJSON d, ToJSON e, ToJSON f, ToJSON g, ToJSON h) => ToJSON (a, b, c, d, e, f, g, h) 
Instance details

Defined in Data.Aeson.Types.ToJSON

Methods

toJSON :: (a, b, c, d, e, f, g, h) -> Value #

toEncoding :: (a, b, c, d, e, f, g, h) -> Encoding #

toJSONList :: [(a, b, c, d, e, f, g, h)] -> Value #

toEncodingList :: [(a, b, c, d, e, f, g, h)] -> Encoding #

(ToJSON a, ToJSON b, ToJSON c, ToJSON d, ToJSON e, ToJSON f, ToJSON g, ToJSON h, ToJSON i) => ToJSON (a, b, c, d, e, f, g, h, i) 
Instance details

Defined in Data.Aeson.Types.ToJSON

Methods

toJSON :: (a, b, c, d, e, f, g, h, i) -> Value #

toEncoding :: (a, b, c, d, e, f, g, h, i) -> Encoding #

toJSONList :: [(a, b, c, d, e, f, g, h, i)] -> Value #

toEncodingList :: [(a, b, c, d, e, f, g, h, i)] -> Encoding #

(ToJSON a, ToJSON b, ToJSON c, ToJSON d, ToJSON e, ToJSON f, ToJSON g, ToJSON h, ToJSON i, ToJSON j) => ToJSON (a, b, c, d, e, f, g, h, i, j) 
Instance details

Defined in Data.Aeson.Types.ToJSON

Methods

toJSON :: (a, b, c, d, e, f, g, h, i, j) -> Value #

toEncoding :: (a, b, c, d, e, f, g, h, i, j) -> Encoding #

toJSONList :: [(a, b, c, d, e, f, g, h, i, j)] -> Value #

toEncodingList :: [(a, b, c, d, e, f, g, h, i, j)] -> Encoding #

(ToJSON a, ToJSON b, ToJSON c, ToJSON d, ToJSON e, ToJSON f, ToJSON g, ToJSON h, ToJSON i, ToJSON j, ToJSON k) => ToJSON (a, b, c, d, e, f, g, h, i, j, k) 
Instance details

Defined in Data.Aeson.Types.ToJSON

Methods

toJSON :: (a, b, c, d, e, f, g, h, i, j, k) -> Value #

toEncoding :: (a, b, c, d, e, f, g, h, i, j, k) -> Encoding #

toJSONList :: [(a, b, c, d, e, f, g, h, i, j, k)] -> Value #

toEncodingList :: [(a, b, c, d, e, f, g, h, i, j, k)] -> Encoding #

(ToJSON a, ToJSON b, ToJSON c, ToJSON d, ToJSON e, ToJSON f, ToJSON g, ToJSON h, ToJSON i, ToJSON j, ToJSON k, ToJSON l) => ToJSON (a, b, c, d, e, f, g, h, i, j, k, l) 
Instance details

Defined in Data.Aeson.Types.ToJSON

Methods

toJSON :: (a, b, c, d, e, f, g, h, i, j, k, l) -> Value #

toEncoding :: (a, b, c, d, e, f, g, h, i, j, k, l) -> Encoding #

toJSONList :: [(a, b, c, d, e, f, g, h, i, j, k, l)] -> Value #

toEncodingList :: [(a, b, c, d, e, f, g, h, i, j, k, l)] -> Encoding #

(ToJSON a, ToJSON b, ToJSON c, ToJSON d, ToJSON e, ToJSON f, ToJSON g, ToJSON h, ToJSON i, ToJSON j, ToJSON k, ToJSON l, ToJSON m) => ToJSON (a, b, c, d, e, f, g, h, i, j, k, l, m) 
Instance details

Defined in Data.Aeson.Types.ToJSON

Methods

toJSON :: (a, b, c, d, e, f, g, h, i, j, k, l, m) -> Value #

toEncoding :: (a, b, c, d, e, f, g, h, i, j, k, l, m) -> Encoding #

toJSONList :: [(a, b, c, d, e, f, g, h, i, j, k, l, m)] -> Value #

toEncodingList :: [(a, b, c, d, e, f, g, h, i, j, k, l, m)] -> Encoding #

(ToJSON a, ToJSON b, ToJSON c, ToJSON d, ToJSON e, ToJSON f, ToJSON g, ToJSON h, ToJSON i, ToJSON j, ToJSON k, ToJSON l, ToJSON m, ToJSON n) => ToJSON (a, b, c, d, e, f, g, h, i, j, k, l, m, n) 
Instance details

Defined in Data.Aeson.Types.ToJSON

Methods

toJSON :: (a, b, c, d, e, f, g, h, i, j, k, l, m, n) -> Value #

toEncoding :: (a, b, c, d, e, f, g, h, i, j, k, l, m, n) -> Encoding #

toJSONList :: [(a, b, c, d, e, f, g, h, i, j, k, l, m, n)] -> Value #

toEncodingList :: [(a, b, c, d, e, f, g, h, i, j, k, l, m, n)] -> Encoding #

(ToJSON a, ToJSON b, ToJSON c, ToJSON d, ToJSON e, ToJSON f, ToJSON g, ToJSON h, ToJSON i, ToJSON j, ToJSON k, ToJSON l, ToJSON m, ToJSON n, ToJSON o) => ToJSON (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o) 
Instance details

Defined in Data.Aeson.Types.ToJSON

Methods

toJSON :: (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o) -> Value #

toEncoding :: (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o) -> Encoding #

toJSONList :: [(a, b, c, d, e, f, g, h, i, j, k, l, m, n, o)] -> Value #

toEncodingList :: [(a, b, c, d, e, f, g, h, i, j, k, l, m, n, o)] -> Encoding #

class FromJSON 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.

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

Instances

Instances details
FromJSON Key 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON DotNetTime 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON Value 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON Version 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON Void 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON CTime 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON Int16 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON Int32 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON Int64 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON Int8 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON Word16 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON Word32 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON Word64 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON Word8 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON Datetime 
Instance details

Defined in Chronos

FromJSON Day 
Instance details

Defined in Chronos

FromJSON Offset 
Instance details

Defined in Chronos

FromJSON Time 
Instance details

Defined in Chronos

FromJSON Timespan 
Instance details

Defined in Chronos

FromJSON IntSet 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON Ordering 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON Days 
Instance details

Defined in Polysemy.Time.Data.TimeUnit

FromJSON Hours 
Instance details

Defined in Polysemy.Time.Data.TimeUnit

FromJSON MicroSeconds 
Instance details

Defined in Polysemy.Time.Data.TimeUnit

FromJSON MilliSeconds 
Instance details

Defined in Polysemy.Time.Data.TimeUnit

FromJSON Minutes 
Instance details

Defined in Polysemy.Time.Data.TimeUnit

FromJSON Months 
Instance details

Defined in Polysemy.Time.Data.TimeUnit

FromJSON NanoSeconds 
Instance details

Defined in Polysemy.Time.Data.TimeUnit

FromJSON Seconds 
Instance details

Defined in Polysemy.Time.Data.TimeUnit

FromJSON Weeks 
Instance details

Defined in Polysemy.Time.Data.TimeUnit

FromJSON Years 
Instance details

Defined in Polysemy.Time.Data.TimeUnit

FromJSON Scientific 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON Text 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON Text 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON ShortText

Since: aeson-2.0.2.0

Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON CalendarDiffDays 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON Day 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON Month 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON Quarter 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON QuarterOfYear 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON DayOfWeek 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON DiffTime

This instance includes a bounds check to prevent maliciously large inputs to fill up the memory of the target system. You can newtype Scientific and provide your own instance using withScientific if you want to allow larger inputs.

Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON NominalDiffTime

This instance includes a bounds check to prevent maliciously large inputs to fill up the memory of the target system. You can newtype Scientific and provide your own instance using withScientific if you want to allow larger inputs.

Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON SystemTime 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON UTCTime 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON CalendarDiffTime 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON LocalTime 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON TimeOfDay 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON ZonedTime

Supported string formats:

YYYY-MM-DD HH:MM Z YYYY-MM-DD HH:MM:SS Z YYYY-MM-DD HH:MM:SS.SSS Z

The first space may instead be a T, and the second space is optional. The Z represents UTC. The Z may be replaced with a time zone offset of the form +0000 or -08:00, where the first two digits are hours, the : is optional and the second two digits (also optional) are minutes.

Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON UUID 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON Integer

This instance includes a bounds check to prevent maliciously large inputs to fill up the memory of the target system. You can newtype Scientific and provide your own instance using withScientific if you want to allow larger inputs.

Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON Natural 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON () 
Instance details

Defined in Data.Aeson.Types.FromJSON

Methods

parseJSON :: Value -> Parser () #

parseJSONList :: Value -> Parser [()] #

FromJSON Bool 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON Char 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON Double 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON Float 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON Int 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON Word 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON v => FromJSON (KeyMap v)

Since: aeson-2.0.1.0

Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON a => FromJSON (Identity a) 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON a => FromJSON (First a) 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON a => FromJSON (Last a) 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON a => FromJSON (First a) 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON a => FromJSON (Last a) 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON a => FromJSON (Max a) 
Instance details

Defined in Data.Aeson.Types.FromJSON

Methods

parseJSON :: Value -> Parser (Max a) #

parseJSONList :: Value -> Parser [Max a] #

FromJSON a => FromJSON (Min a) 
Instance details

Defined in Data.Aeson.Types.FromJSON

Methods

parseJSON :: Value -> Parser (Min a) #

parseJSONList :: Value -> Parser [Min a] #

FromJSON a => FromJSON (WrappedMonoid a) 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON a => FromJSON (Dual a) 
Instance details

Defined in Data.Aeson.Types.FromJSON

(FromJSON a, Integral a) => FromJSON (Ratio a) 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON a => FromJSON (IntMap a) 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON a => FromJSON (Seq a) 
Instance details

Defined in Data.Aeson.Types.FromJSON

Methods

parseJSON :: Value -> Parser (Seq a) #

parseJSONList :: Value -> Parser [Seq a] #

(Ord a, FromJSON a) => FromJSON (Set a) 
Instance details

Defined in Data.Aeson.Types.FromJSON

Methods

parseJSON :: Value -> Parser (Set a) #

parseJSONList :: Value -> Parser [Set a] #

FromJSON v => FromJSON (Tree v) 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON1 f => FromJSON (Fix f)

Since: aeson-1.5.3.0

Instance details

Defined in Data.Aeson.Types.FromJSON

Methods

parseJSON :: Value -> Parser (Fix f) #

parseJSONList :: Value -> Parser [Fix f] #

(FromJSON1 f, Functor f) => FromJSON (Mu f)

Since: aeson-1.5.3.0

Instance details

Defined in Data.Aeson.Types.FromJSON

Methods

parseJSON :: Value -> Parser (Mu f) #

parseJSONList :: Value -> Parser [Mu f] #

(FromJSON1 f, Functor f) => FromJSON (Nu f)

Since: aeson-1.5.3.0

Instance details

Defined in Data.Aeson.Types.FromJSON

Methods

parseJSON :: Value -> Parser (Nu f) #

parseJSONList :: Value -> Parser [Nu f] #

FromJSON a => FromJSON (DNonEmpty a)

Since: aeson-1.5.3.0

Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON a => FromJSON (DList a) 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON a => FromJSON (Array a) 
Instance details

Defined in Data.Aeson.Types.FromJSON

(Prim a, FromJSON a) => FromJSON (PrimArray a) 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON a => FromJSON (SmallArray a) 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON a => FromJSON (Maybe a)

Since: aeson-1.5.3.0

Instance details

Defined in Data.Aeson.Types.FromJSON

(Eq a, Hashable a, FromJSON a) => FromJSON (HashSet a) 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON a => FromJSON (Vector a) 
Instance details

Defined in Data.Aeson.Types.FromJSON

(Prim a, FromJSON a) => FromJSON (Vector a) 
Instance details

Defined in Data.Aeson.Types.FromJSON

(Storable a, FromJSON a) => FromJSON (Vector a) 
Instance details

Defined in Data.Aeson.Types.FromJSON

(Vector Vector a, FromJSON a) => FromJSON (Vector a) 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON a => FromJSON (NonEmpty a) 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON a => FromJSON (Maybe a) 
Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON a => FromJSON (a)

Since: aeson-2.0.2.0

Instance details

Defined in Data.Aeson.Types.FromJSON

Methods

parseJSON :: Value -> Parser (a) #

parseJSONList :: Value -> Parser [(a)] #

FromJSON a => FromJSON [a] 
Instance details

Defined in Data.Aeson.Types.FromJSON

Methods

parseJSON :: Value -> Parser [a] #

parseJSONList :: Value -> Parser [[a]] #

(FromJSON a, FromJSON b) => FromJSON (Either a b) 
Instance details

Defined in Data.Aeson.Types.FromJSON

Methods

parseJSON :: Value -> Parser (Either a b) #

parseJSONList :: Value -> Parser [Either a b] #

HasResolution a => FromJSON (Fixed a)

This instance includes a bounds check to prevent maliciously large inputs to fill up the memory of the target system. You can newtype Scientific and provide your own instance using withScientific if you want to allow larger inputs.

Instance details

Defined in Data.Aeson.Types.FromJSON

FromJSON (Proxy a) 
Instance details

Defined in Data.Aeson.Types.FromJSON

(FromJSONKey k, Ord k, FromJSON v) => FromJSON (Map k v) 
Instance details

Defined in Data.Aeson.Types.FromJSON

Methods

parseJSON :: Value -> Parser (Map k v) #

parseJSONList :: Value -> Parser [Map k v] #

(FromJSON a, FromJSON b) => FromJSON (Either a b)

Since: aeson-1.5.3.0

Instance details

Defined in Data.Aeson.Types.FromJSON

Methods

parseJSON :: Value -> Parser (Either a b) #

parseJSONList :: Value -> Parser [Either a b] #

(FromJSON a, FromJSON b) => FromJSON (These a b)

Since: aeson-1.5.3.0

Instance details

Defined in Data.Aeson.Types.FromJSON

Methods

parseJSON :: Value -> Parser (These a b) #

parseJSONList :: Value -> Parser [These a b] #

(FromJSON a, FromJSON b) => FromJSON (Pair a b)

Since: aeson-1.5.3.0

Instance details

Defined in Data.Aeson.Types.FromJSON

Methods

parseJSON :: Value -> Parser (Pair a b) #

parseJSONList :: Value -> Parser [Pair a b] #

(FromJSON a, FromJSON b) => FromJSON (These a b)

Since: aeson-1.5.1.0

Instance details

Defined in Data.Aeson.Types.FromJSON

Methods

parseJSON :: Value -> Parser (These a b) #

parseJSONList :: Value -> Parser [These a b] #

(FromJSON v, FromJSONKey k, Eq k, Hashable k) => FromJSON (HashMap k v) 
Instance details

Defined in Data.Aeson.Types.FromJSON

(FromJSON a, FromJSON b) => FromJSON (a, b) 
Instance details

Defined in Data.Aeson.Types.FromJSON

Methods

parseJSON :: Value -> Parser (a, b) #

parseJSONList :: Value -> Parser [(a, b)] #

FromJSON a => FromJSON (Const a b) 
Instance details

Defined in Data.Aeson.Types.FromJSON

Methods

parseJSON :: Value -> Parser (Const a b) #

parseJSONList :: Value -> Parser [Const a b] #

FromJSON b => FromJSON (Tagged a b) 
Instance details

Defined in Data.Aeson.Types.FromJSON

Methods

parseJSON :: Value -> Parser (Tagged a b) #

parseJSONList :: Value -> Parser [Tagged a b] #

(FromJSON1 f, FromJSON1 g, FromJSON a) => FromJSON (These1 f g a)

Since: aeson-1.5.1.0

Instance details

Defined in Data.Aeson.Types.FromJSON

Methods

parseJSON :: Value -> Parser (These1 f g a) #

parseJSONList :: Value -> Parser [These1 f g a] #

(FromJSON a, FromJSON b, FromJSON c) => FromJSON (a, b, c) 
Instance details

Defined in Data.Aeson.Types.FromJSON

Methods

parseJSON :: Value -> Parser (a, b, c) #

parseJSONList :: Value -> Parser [(a, b, c)] #

(FromJSON1 f, FromJSON1 g, FromJSON a) => FromJSON (Product f g a) 
Instance details

Defined in Data.Aeson.Types.FromJSON

Methods

parseJSON :: Value -> Parser (Product f g a) #

parseJSONList :: Value -> Parser [Product f g a] #

(FromJSON1 f, FromJSON1 g, FromJSON a) => FromJSON (Sum f g a) 
Instance details

Defined in Data.Aeson.Types.FromJSON

Methods

parseJSON :: Value -> Parser (Sum f g a) #

parseJSONList :: Value -> Parser [Sum f g a] #

(FromJSON a, FromJSON b, FromJSON c, FromJSON d) => FromJSON (a, b, c, d) 
Instance details

Defined in Data.Aeson.Types.FromJSON

Methods

parseJSON :: Value -> Parser (a, b, c, d) #

parseJSONList :: Value -> Parser [(a, b, c, d)] #

(FromJSON1 f, FromJSON1 g, FromJSON a) => FromJSON (Compose f g a) 
Instance details

Defined in Data.Aeson.Types.FromJSON

Methods

parseJSON :: Value -> Parser (Compose f g a) #

parseJSONList :: Value -> Parser [Compose f g a] #

(FromJSON a, FromJSON b, FromJSON c, FromJSON d, FromJSON e) => FromJSON (a, b, c, d, e) 
Instance details

Defined in Data.Aeson.Types.FromJSON

Methods

parseJSON :: Value -> Parser (a, b, c, d, e) #

parseJSONList :: Value -> Parser [(a, b, c, d, e)] #

(FromJSON a, FromJSON b, FromJSON c, FromJSON d, FromJSON e, FromJSON f) => FromJSON (a, b, c, d, e, f) 
Instance details

Defined in Data.Aeson.Types.FromJSON

Methods

parseJSON :: Value -> Parser (a, b, c, d, e, f) #

parseJSONList :: Value -> Parser [(a, b, c, d, e, f)] #

(FromJSON a, FromJSON b, FromJSON c, FromJSON d, FromJSON e, FromJSON f, FromJSON g) => FromJSON (a, b, c, d, e, f, g) 
Instance details

Defined in Data.Aeson.Types.FromJSON

Methods

parseJSON :: Value -> Parser (a, b, c, d, e, f, g) #

parseJSONList :: Value -> Parser [(a, b, c, d, e, f, g)] #

(FromJSON a, FromJSON b, FromJSON c, FromJSON d, FromJSON e, FromJSON f, FromJSON g, FromJSON h) => FromJSON (a, b, c, d, e, f, g, h) 
Instance details

Defined in Data.Aeson.Types.FromJSON

Methods

parseJSON :: Value -> Parser (a, b, c, d, e, f, g, h) #

parseJSONList :: Value -> Parser [(a, b, c, d, e, f, g, h)] #

(FromJSON a, FromJSON b, FromJSON c, FromJSON d, FromJSON e, FromJSON f, FromJSON g, FromJSON h, FromJSON i) => FromJSON (a, b, c, d, e, f, g, h, i) 
Instance details

Defined in Data.Aeson.Types.FromJSON

Methods

parseJSON :: Value -> Parser (a, b, c, d, e, f, g, h, i) #

parseJSONList :: Value -> Parser [(a, b, c, d, e, f, g, h, i)] #

(FromJSON a, FromJSON b, FromJSON c, FromJSON d, FromJSON e, FromJSON f, FromJSON g, FromJSON h, FromJSON i, FromJSON j) => FromJSON (a, b, c, d, e, f, g, h, i, j) 
Instance details

Defined in Data.Aeson.Types.FromJSON

Methods

parseJSON :: Value -> Parser (a, b, c, d, e, f, g, h, i, j) #

parseJSONList :: Value -> Parser [(a, b, c, d, e, f, g, h, i, j)] #

(FromJSON a, FromJSON b, FromJSON c, FromJSON d, FromJSON e, FromJSON f, FromJSON g, FromJSON h, FromJSON i, FromJSON j, FromJSON k) => FromJSON (a, b, c, d, e, f, g, h, i, j, k) 
Instance details

Defined in Data.Aeson.Types.FromJSON

Methods

parseJSON :: Value -> Parser (a, b, c, d, e, f, g, h, i, j, k) #

parseJSONList :: Value -> Parser [(a, b, c, d, e, f, g, h, i, j, k)] #

(FromJSON a, FromJSON b, FromJSON c, FromJSON d, FromJSON e, FromJSON f, FromJSON g, FromJSON h, FromJSON i, FromJSON j, FromJSON k, FromJSON l) => FromJSON (a, b, c, d, e, f, g, h, i, j, k, l) 
Instance details

Defined in Data.Aeson.Types.FromJSON

Methods

parseJSON :: Value -> Parser (a, b, c, d, e, f, g, h, i, j, k, l) #

parseJSONList :: Value -> Parser [(a, b, c, d, e, f, g, h, i, j, k, l)] #

(FromJSON a, FromJSON b, FromJSON c, FromJSON d, FromJSON e, FromJSON f, FromJSON g, FromJSON h, FromJSON i, FromJSON j, FromJSON k, FromJSON l, FromJSON m) => FromJSON (a, b, c, d, e, f, g, h, i, j, k, l, m) 
Instance details

Defined in Data.Aeson.Types.FromJSON

Methods

parseJSON :: Value -> Parser (a, b, c, d, e, f, g, h, i, j, k, l, m) #

parseJSONList :: Value -> Parser [(a, b, c, d, e, f, g, h, i, j, k, l, m)] #

(FromJSON a, FromJSON b, FromJSON c, FromJSON d, FromJSON e, FromJSON f, FromJSON g, FromJSON h, FromJSON i, FromJSON j, FromJSON k, FromJSON l, FromJSON m, FromJSON n) => FromJSON (a, b, c, d, e, f, g, h, i, j, k, l, m, n) 
Instance details

Defined in Data.Aeson.Types.FromJSON

Methods

parseJSON :: Value -> Parser (a, b, c, d, e, f, g, h, i, j, k, l, m, n) #

parseJSONList :: Value -> Parser [(a, b, c, d, e, f, g, h, i, j, k, l, m, n)] #

(FromJSON a, FromJSON b, FromJSON c, FromJSON d, FromJSON e, FromJSON f, FromJSON g, FromJSON h, FromJSON i, FromJSON j, FromJSON k, FromJSON l, FromJSON m, FromJSON n, FromJSON o) => FromJSON (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o) 
Instance details

Defined in Data.Aeson.Types.FromJSON

Methods

parseJSON :: Value -> Parser (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o) #

parseJSONList :: Value -> Parser [(a, b, c, d, e, f, g, h, i, j, k, l, m, n, o)] #

(&) :: a -> (a -> b) -> b infixl 1 #

& is a reverse application operator. This provides notational convenience. Its precedence is one higher than that of the forward application operator $, which allows & to be nested in $.

>>> 5 & (+1) & show
"6"

Since: base-4.8.0.0

(<&>) :: Functor f => f a -> (a -> b) -> f b infixl 1 #

Flipped version of <$>.

(<&>) = flip fmap

Examples

Expand

Apply (+1) to a list, a Just and a Right:

>>> Just 2 <&> (+1)
Just 3
>>> [1,2,3] <&> (+1)
[2,3,4]
>>> Right 3 <&> (+1)
Right 4

Since: base-4.11.0.0

_Nothing :: Traversal' (Maybe a) () #

_Nothing targets a () if the Maybe is a Nothing, and doesn't target anything otherwise:

>>> Just 1 ^.. _Nothing
[]
>>> Nothing ^.. _Nothing
[()]

It's not particularly useful (unless you want to use has _Nothing as a replacement for isNothing), and provided mainly for consistency.

Implementation:

_Nothing f Nothing = const Nothing <$> f ()
_Nothing _ j       = pure j

_Just :: Traversal (Maybe a) (Maybe a') a a' #

_Just targets the value contained in a Maybe, provided it's a Just.

See documentation for _Left (as these 2 are pretty similar). In particular, it can be used to write these:

  • Unsafely extracting a value from a Just:
   fromJust = (^?! _Just)
   
  • Checking whether a value is a Just:
   isJust = has _Just
   
  • Converting a Maybe to a list (empty or consisting of a single element):
   maybeToList = (^.. _Just)
   
  • Gathering all Justs in a list:
   catMaybes = (^.. each . _Just)
   

_Right :: Traversal (Either a b) (Either a b') b b' #

_Right targets the value contained in an Either, provided it's a Right.

See documentation for _Left.

_Left :: Traversal (Either a b) (Either a' b) a a' #

_Left targets the value contained in an Either, provided it's a Left.

Gathering all Lefts in a structure (like the lefts function, but not necessarily just for lists):

>>> [Left 1, Right 'c', Left 3] ^.. each._Left
[1,3]

Checking whether an Either is a Left (like isLeft):

>>> has _Left (Left 1)
True
>>> has _Left (Right 1)
False

Extracting a value (if you're sure it's a Left):

>>> Left 1 ^?! _Left
1

Mapping over all Lefts:

>>> (each._Left %~ map toUpper) [Left "foo", Right "bar"]
[Left "FOO",Right "bar"]

Implementation:

_Left f (Left a)  = Left <$> f a
_Left _ (Right b) = pure (Right b)

mapAccumLOf :: LensLike (State acc) s t a b -> (acc -> a -> (acc, b)) -> acc -> s -> (acc, t) #

This generalizes mapAccumL to an arbitrary Traversal. (Note that it doesn't work on folds, only traversals.)

mapAccumLmapAccumLOf traverse

_last :: Snoc s s a a => Traversal' s a #

_last gives you access to the last element of the list:

>>> "Hello." ^? _last
'.'

See documentation for _head, as _last and _head are pretty similar.

_init :: Snoc s s a a => Traversal' s s #

_init gives you access to all-but-the-last elements of the list:

>>> "Hello." ^. _init
"Hello"

See documentation for _tail, as _init and _tail are pretty similar.

_tail :: Cons s s a a => Traversal' s s #

_tail gives you access to the tail of a list (or Seq, etc):

>>> [1..5] ^? _tail
Just [2,3,4,5]

You can modify the tail as well:

>>> [4,1,2,3] & _tail %~ reverse
[4,3,2,1]

Since lists are monoids, you can use _tail with plain (^.) (and then it'll return an empty list if you give it an empty list):

>>> [1..5] ^. _tail
[2,3,4,5]
>>> [] ^. _tail
[]

If you want to traverse each element of the tail, use _tail with each:

>>> "I HATE CAPS." & _tail.each %~ toLower
"I hate caps."

This package only lets you use _tail on lists, but if you use microlens-ghc you get instances for ByteString and Seq, and if you use microlens-platform you additionally get instances for Text and Vector.

_head :: Cons s s a a => Traversal' s a #

_head traverses the 1st element of something (usually a list, but can also be a Seq, etc):

>>> [1..5] ^? _head
Just 1

It can be used to modify too, as in this example where the 1st letter of a sentence is capitalised:

>>> "mary had a little lamb." & _head %~ toTitle
"Mary had a little lamb."

The reason it's a traversal and not a lens is that there's nothing to traverse when the list is empty:

>>> [] ^? _head
Nothing

This package only lets you use _head on lists, but if you use microlens-ghc you get instances for ByteString and Seq, and if you use microlens-platform you additionally get instances for Text and Vector.

both :: Traversal (a, a) (b, b) a b #

both traverses both fields of a tuple. Unlike both from lens, it only works for pairs – not for triples or Either.

>>> ("str","ing") ^. both
"string"
>>> ("str","ing") & both %~ reverse
("rts","gni")

filtered :: (a -> Bool) -> Traversal' a a #

filtered is a traversal that filters elements “passing” through it:

>>> (1,2,3,4) ^.. each
[1,2,3,4]
>>> (1,2,3,4) ^.. each . filtered even
[2,4]

It also can be used to modify elements selectively:

>>> (1,2,3,4) & each . filtered even %~ (*100)
(1,200,3,400)

The implementation of filtered is very simple. Consider this traversal, which always “traverses” just the value it's given:

id :: Traversal' a a
id f s = f s

And this traversal, which traverses nothing (in other words, doesn't traverse the value it's given):

ignored :: Traversal' a a
ignored f s = pure s

And now combine them into a traversal that conditionally traverses the value it's given, and you get filtered:

filtered :: (a -> Bool) -> Traversal' a a
filtered p f s = if p s then f s else pure s

By the way, note that filtered can generate illegal traversals – sometimes this can bite you. In particular, an optimisation that should be safe becomes unsafe. (To the best of my knowledge, this optimisation never happens automatically. If you just use filtered to modify/view something, you're safe. If you don't define any traversals that use filtered, you're safe too.)

Let's use evens as an example:

evens = filtered even

If evens was a legal traversal, you'd be able to fuse several applications of evens like this:

over evens f . over evens g = over evens (f . g)

Unfortunately, in case of evens this isn't a correct optimisation:

  • the left-side variant applies g to all even numbers, and then applies f to all even numbers that are left after f (because f might've turned some even numbers into odd ones)
  • the right-side variant applies f and g to all even numbers

Of course, when you are careful and know what you're doing, you won't try to make such an optimisation. However, if you export an illegal traversal created with filtered and someone tries to use it, they might mistakenly assume that it's legal, do the optimisation, and silently get an incorrect result.

If you are using filtered with some another traversal that doesn't overlap with -whatever the predicate checks-, the resulting traversal will be legal. For instance, here the predicate looks at the 1st element of a tuple, but the resulting traversal only gives you access to the 2nd:

pairedWithEvens :: Traversal [(Int, a)] [(Int, b)] a b
pairedWithEvens = each . filtered (even . fst) . _2

Since you can't do anything with the 1st components through this traversal, the following holds for any f and g:

over pairedWithEvens f . over pairedWithEvens g = over pairedWithEvens (f . g)

failing :: Traversal s t a b -> Traversal s t a b -> Traversal s t a b infixl 5 #

failing lets you chain traversals together; if the 1st traversal fails, the 2nd traversal will be used.

>>> ([1,2],[3]) & failing (_1.each) (_2.each) .~ 0
([0,0],[3])
>>> ([],[3]) & failing (_1.each) (_2.each) .~ 0
([],[0])

Note that the resulting traversal won't be valid unless either both traversals don't touch each others' elements, or both traversals return exactly the same results. To see an example of how failing can generate invalid traversals, see this Stackoverflow question.

singular :: HasCallStack => Traversal s t a a -> Lens s t a a #

singular turns a traversal into a lens that behaves like a single-element traversal:

>>> [1,2,3] ^. singular each
1
>>> [1,2,3] & singular each %~ negate
[-1,2,3]

If there is nothing to return, it'll throw an error:

>>> [] ^. singular each
*** Exception: Lens.Micro.singular: empty traversal

However, it won't fail if you are merely setting the value:

>>> [] & singular each %~ negate

forOf :: LensLike f s t a b -> s -> (a -> f b) -> f t #

traverseOf with flipped arguments. Useful if the “loop body” is a lambda or a do block.

traverseOf :: LensLike f s t a b -> (a -> f b) -> s -> f t #

Apply an action to all targets (like mapM or traverse):

>>> traverseOf both readFile ("file1", "file2")
(<contents of file1>, <contents of file2>)
>>> traverseOf _1 id (Just 1, 2)
Just (1, 2)
>>> traverseOf _1 id (Nothing, 2)
Nothing

You can also just apply the lens/traversal directly (but traverseOf might be more readable):

>>> both readFile ("file1", "file2")
(<contents of file1>, <contents of file2>)

If you don't need the result, use traverseOf_.

non :: Eq a => a -> Lens' (Maybe a) a #

non lets you “relabel” a Maybe by equating Nothing to an arbitrary value (which you can choose):

>>> Just 1 ^. non 0
1
>>> Nothing ^. non 0
0

The most useful thing about non is that relabeling also works in other direction. If you try to set the “forbidden” value, it'll be turned to Nothing:

>>> Just 1 & non 0 .~ 0
Nothing

Setting anything else works just fine:

>>> Just 1 & non 0 .~ 5
Just 5

Same happens if you try to modify a value:

>>> Just 1 & non 0 %~ subtract 1
Nothing
>>> Just 1 & non 0 %~ (+ 1)
Just 2

non is often useful when combined with at. For instance, if you have a map of songs and their playcounts, it makes sense not to store songs with 0 plays in the map; non can act as a filter that wouldn't pass such entries.

Decrease playcount of a song to 0, and it'll be gone:

>>> fromList [("Soon",1),("Yesterday",3)] & at "Soon" . non 0 %~ subtract 1
fromList [("Yesterday",3)]

Try to add a song with 0 plays, and it won't be added:

>>> fromList [("Yesterday",3)] & at "Soon" . non 0 .~ 0
fromList [("Yesterday",3)]

But it will be added if you set any other number:

>>> fromList [("Yesterday",3)] & at "Soon" . non 0 .~ 1
fromList [("Soon",1),("Yesterday",3)]

non is also useful when working with nested maps. Here a nested map is created when it's missing:

>>> Map.empty & at "Dez Mona" . non Map.empty . at "Soon" .~ Just 1
fromList [("Dez Mona",fromList [("Soon",1)])]

and here it is deleted when its last entry is deleted (notice that non is used twice here):

>>> fromList [("Dez Mona",fromList [("Soon",1)])] & at "Dez Mona" . non Map.empty . at "Soon" . non 0 %~ subtract 1
fromList []

To understand the last example better, observe the flow of values in it:

  • the map goes into at "Dez Mona"
  • the nested map (wrapped into Just) goes into non Map.empty
  • Just is unwrapped and the nested map goes into at "Soon"
  • Just 1 is unwrapped by non 0

Then the final value – i.e. 1 – is modified by subtract 1 and the result (which is 0) starts flowing backwards:

  • non 0 sees the 0 and produces a Nothing
  • at "Soon" sees Nothing and deletes the corresponding value from the map
  • the resulting empty map is passed to non Map.empty, which sees that it's empty and thus produces Nothing
  • at "Dez Mona" sees Nothing and removes the key from the map

folding :: Foldable f => (s -> f a) -> SimpleFold s a #

folding creates a fold out of any function that returns a Foldable container (for instance, a list):

>>> [1..5] ^.. folding tail
[2,3,4,5]

has :: Getting Any s a -> s -> Bool #

has checks whether a getter (any getter, including lenses, traversals, and folds) returns at least 1 value.

Checking whether a list is non-empty:

>>> has each []
False

You can also use it with e.g. _Left (and other 0-or-1 traversals) as a replacement for isNothing, isJust and other isConstructorName functions:

>>> has _Left (Left 1)
True

forOf_ :: Functor f => Getting (Traversed r f) s a -> s -> (a -> f r) -> f () #

traverseOf_ with flipped arguments. Useful if the “loop body” is a lambda or a do block, or in some other cases – for instance, you can avoid accidentally using for_ on a tuple or Either by switching to forOf_ each. Or you can write custom loops like these:

forOf_ both (a, b) $ \x ->
  ...
forOf_ each [1..10] $ \x ->
  ...
forOf_ (each . _Right) $ \x ->
  ...

traverseOf_ :: Functor f => Getting (Traversed r f) s a -> (a -> f r) -> s -> f () #

Apply an action to all targets and discard the result (like mapM_ or traverse_):

>>> traverseOf_ both putStrLn ("hello", "world")
hello
world

Works with anything that allows getting, including lenses and getters (so, anything except for ASetter). Should be faster than traverseOf when you don't need the result.

(^?!) :: HasCallStack => s -> Getting (Endo a) s a -> a infixl 8 #

(^?!) is an unsafe variant of (^?) – instead of using Nothing to indicate that there were no elements returned, it throws an exception.

(^?) :: s -> Getting (First a) s a -> Maybe a infixl 8 #

s ^? t returns the 1st element t returns, or Nothing if t doesn't return anything. It's trivially implemented by passing the First monoid to the getter.

Safe head:

>>> [] ^? each
Nothing
>>> [1..3] ^? each
Just 1

Converting Either to Maybe:

>>> Left 1 ^? _Right
Nothing
>>> Right 1 ^? _Right
Just 1

A non-operator version of (^?) is called preview, and – like view – it's a bit more general than (^?) (it works in MonadReader). If you need the general version, you can get it from microlens-mtl; otherwise there's preview available in Lens.Micro.Extras.

toListOf :: Getting (Endo [a]) s a -> s -> [a] #

toListOf is a synonym for (^..).

(^..) :: s -> Getting (Endo [a]) s a -> [a] infixl 8 #

s ^.. t returns the list of all values that t gets from s.

A Maybe contains either 0 or 1 values:

>>> Just 3 ^.. _Just
[3]

Gathering all values in a list of tuples:

>>> [(1,2),(3,4)] ^.. each.each
[1,2,3,4]

to :: (s -> a) -> SimpleGetter s a #

to creates a getter from any function:

a ^. to f = f a

It's most useful in chains, because it lets you mix lenses and ordinary functions. Suppose you have a record which comes from some third-party library and doesn't have any lens accessors. You want to do something like this:

value ^. _1 . field . at 2

However, field isn't a getter, and you have to do this instead:

field (value ^. _1) ^. at 2

but now value is in the middle and it's hard to read the resulting code. A variant with to is prettier and more readable:

value ^. _1 . to field . at 2

(^.) :: s -> Getting a s a -> a infixl 8 #

(^.) applies a getter to a value; in other words, it gets a value out of a structure using a getter (which can be a lens, traversal, fold, etc.).

Getting 1st field of a tuple:

(^. _1) :: (a, b) -> a
(^. _1) = fst

When (^.) is used with a traversal, it combines all results using the Monoid instance for the resulting type. For instance, for lists it would be simple concatenation:

>>> ("str","ing") ^. each
"string"

The reason for this is that traversals use Applicative, and the Applicative instance for Const uses monoid concatenation to combine “effects” of Const.

A non-operator version of (^.) is called view, and it's a bit more general than (^.) (it works in MonadReader). If you need the general version, you can get it from microlens-mtl; otherwise there's view available in Lens.Micro.Extras.

transformOf :: ASetter a b a b -> (b -> b) -> a -> b #

Transform every element by recursively applying a given ASetter in a bottom-up manner.

Since: microlens-0.4.11

rewriteOf :: ASetter a b a b -> (b -> Maybe a) -> a -> b #

→ See an example on GitHub.

Rewrite by applying a rule everywhere you can. Ensures that the rule cannot be applied anywhere in the result.

Usually transformOf is more appropriate, but rewriteOf can give better compositionality. Given two single transformations f and g, you can construct \a -> f a <|> g a which performs both rewrites until a fixed point.

Since: microlens-0.4.11

(<<.~) :: LensLike ((,) a) s t a b -> b -> s -> (a, t) infixr 4 #

This is a version of (.~) which modifies the structure and returns it along with the old value:

>>> (1, 2) & _1 <<.~ 0
(1, (0, 2))

Simpler type signatures:

(<<.~) ::             Lens s t a b      -> b -> s -> (a, t)
(<<.~) :: Monoid a => Traversal s t a b -> b -> s -> (a, t)

(<<%~) :: LensLike ((,) a) s t a b -> (a -> b) -> s -> (a, t) infixr 4 #

This is a version of (%~) which modifies the structure and returns it along with the old value:

>>> (1, 2) & _1 <<%~ negate
(1, (-1, 2))

Simpler type signatures:

(<<%~) ::             Lens s t a b      -> (a -> b) -> s -> (a, t)
(<<%~) :: Monoid a => Traversal s t a b -> (a -> b) -> s -> (a, t)

(<%~) :: LensLike ((,) b) s t a b -> (a -> b) -> s -> (b, t) infixr 4 #

This is a version of (%~) which modifies the structure and returns it along with the new value:

>>> (1, 2) & _1 <%~ negate
(-1, (-1, 2))

Simpler type signatures:

(<%~) ::             Lens s t a b      -> (a -> b) -> s -> (b, t)
(<%~) :: Monoid b => Traversal s t a b -> (a -> b) -> s -> (b, t)

Since it does getting in addition to setting, you can't use it with ASetter (but you can use it with lens and traversals).

mapped :: Functor f => ASetter (f a) (f b) a b #

mapped is a setter for everything contained in a functor. You can use it to map over lists, Maybe, or even IO (which is something you can't do with traversed or each).

Here mapped is used to turn a value to all non-Nothing values in a list:

>>> [Just 3,Nothing,Just 5] & mapped.mapped .~ 0
[Just 0,Nothing,Just 0]

Keep in mind that while mapped is a more powerful setter than each, it can't be used as a getter! This won't work (and will fail with a type error):

[(1,2),(3,4),(5,6)] ^.. mapped . both

(?~) :: ASetter s t a (Maybe b) -> b -> s -> t infixr 4 #

(?~) is a version of (.~) that wraps the value into Just before setting.

l ?~ b = l .~ Just b

It can be useful in combination with at:

>>> Map.empty & at 3 ?~ x
fromList [(3,x)]

set :: ASetter s t a b -> b -> s -> t #

set is a synonym for (.~).

Setting the 1st component of a pair:

set _1 :: x -> (a, b) -> (x, b)
set _1 = \x t -> (x, snd t)

Using it to rewrite (<$):

set mapped :: Functor f => a -> f b -> f a
set mapped = (<$)

(.~) :: ASetter s t a b -> b -> s -> t infixr 4 #

(.~) assigns a value to the target. It's the same thing as using (%~) with const:

l .~ x = l %~ const x

See set if you want a non-operator synonym.

Here it is used to change 2 fields of a 3-tuple:

>>> (0,0,0) & _1 .~ 1 & _3 .~ 3
(1,0,3)

(<>~) :: Monoid a => ASetter s t a a -> a -> s -> t infixr 4 #

(<>~) appends a value monoidally to the target.

>>> ("hello", "goodbye") & both <>~ " world!"
("hello world!", "goodbye world!")

Since: microlens-0.4.9

(-~) :: Num a => ASetter s t a a -> a -> s -> t infixr 4 #

Decrement the target(s) of a numerically valued Lens, or Traversal.

>>> (a,b) & _1 -~ c
(a - c,b)
>>> (a,b) & both -~ c
(a - c,b - c)
>>> _1 -~ 2 $ (1,2)
(-1,2)
>>> mapped.mapped -~ 1 $ [[4,5],[6,7]]
[[3,4],[5,6]]
(-~) :: Num a => Lens' s a      -> a -> s -> s
(-~) :: Num a => Traversal' s a -> a -> s -> s

Since: microlens-0.4.10

(+~) :: Num a => ASetter s t a a -> a -> s -> t infixr 4 #

Increment the target(s) of a numerically valued Lens or Traversal.

>>> (a,b) & _1 +~ c
(a + c,b)
>>> (a,b) & both +~ c
(a + c,b + c)
>>> (1,2) & _2 +~ 1
(1,3)
>>> [(a,b),(c,d)] & traverse.both +~ e
[(a + e,b + e),(c + e,d + e)]
(+~) :: Num a => Lens' s a      -> a -> s -> s
(+~) :: Num a => Traversal' s a -> a -> s -> s

Since: microlens-0.4.10

over :: ASetter s t a b -> (a -> b) -> s -> t #

over is a synonym for (%~).

Getting fmap in a roundabout way:

over mapped :: Functor f => (a -> b) -> f a -> f b
over mapped = fmap

Applying a function to both components of a pair:

over both :: (a -> b) -> (a, a) -> (b, b)
over both = \f t -> (f (fst t), f (snd t))

Using over _2 as a replacement for second:

>>> over _2 show (10,20)
(10,"20")

(%~) :: ASetter s t a b -> (a -> b) -> s -> t infixr 4 #

(%~) applies a function to the target; an alternative explanation is that it is an inverse of sets, which turns a setter into an ordinary function. mapped %~ reverse is the same thing as fmap reverse.

See over if you want a non-operator synonym.

Negating the 1st element of a pair:

>>> (1,2) & _1 %~ negate
(-1,2)

Turning all Lefts in a list to upper case:

>>> (mapped._Left.mapped %~ toUpper) [Left "foo", Right "bar"]
[Left "FOO",Right "bar"]

sets :: ((a -> b) -> s -> t) -> ASetter s t a b #

sets creates an ASetter from an ordinary function. (The only thing it does is wrapping and unwrapping Identity.)

folded :: forall (f :: TYPE LiftedRep -> Type) a. Foldable f => SimpleFold (f a) a #

folded is a fold for anything Foldable. In a way, it's an opposite of mapped – the most powerful getter, but can't be used as a setter.

traversed :: forall (f :: Type -> Type) a b. Traversable f => Traversal (f a) (f b) a b #

traversed traverses any Traversable container (list, vector, Map, Maybe, you name it):

>>> Just 1 ^.. traversed
[1]

traversed is the same as traverse, but can be faster thanks to magic rewrite rules.

each :: Each s t a b => Traversal s t a b #

each tries to be a universal Traversal – it behaves like traversed in most situations, but also adds support for e.g. tuples with same-typed values:

>>> (1,2) & each %~ succ
(2,3)
>>> ["x", "y", "z"] ^. each
"xyz"

However, note that each doesn't work on every instance of Traversable. If you have a Traversable which isn't supported by each, you can use traversed instead. Personally, I like using each instead of traversed whenever possible – it's shorter and more descriptive.

You can use each with these things:

each :: Traversal [a] [b] a b

each :: Traversal (Maybe a) (Maybe b) a b
each :: Traversal (Either a a) (Either b b) a b  -- since 0.4.11

each :: Traversal (a,a) (b,b) a b
each :: Traversal (a,a,a) (b,b,b) a b
each :: Traversal (a,a,a,a) (b,b,b,b) a b
each :: Traversal (a,a,a,a,a) (b,b,b,b,b) a b

each :: (RealFloat a, RealFloat b) => Traversal (Complex a) (Complex b) a b

You can also use each with types from array, bytestring, and containers by using microlens-ghc, or additionally with types from vector, text, and unordered-containers by using microlens-platform.

ix :: Ixed m => Index m -> Traversal' m (IxValue m) #

This traversal lets you access (and update) an arbitrary element in a list, array, Map, etc. (If you want to insert or delete elements as well, look at at.)

An example for lists:

>>> [0..5] & ix 3 .~ 10
[0,1,2,10,4,5]

You can use it for getting, too:

>>> [0..5] ^? ix 3
Just 3

Of course, the element may not be present (which means that you can use ix as a safe variant of (!!)):

>>> [0..5] ^? ix 10
Nothing

Another useful instance is the one for functions – it lets you modify their outputs for specific inputs. For instance, here's maximum that returns 0 when the list is empty (instead of throwing an exception):

maximum0 = maximum & ix [] .~ 0

The following instances are provided in this package:

ix :: Int -> Traversal' [a] a

ix :: Int -> Traversal' (NonEmpty a) a

ix :: (Eq e) => e -> Traversal' (e -> a) a

You can also use ix with types from array, bytestring, and containers by using microlens-ghc, or additionally with types from vector, text, and unordered-containers by using microlens-platform.

at :: At m => Index m -> Lens' m (Maybe (IxValue m)) #

This lens lets you read, write, or delete elements in Map-like structures. It returns Nothing when the value isn't found, just like lookup:

Data.Map.lookup k m = m ^. at k

However, it also lets you insert and delete values by setting the value to Just value or Nothing:

Data.Map.insert k a m = m & at k .~ Just a

Data.Map.delete k m = m & at k .~ Nothing

Or you could use (?~) instead of (.~):

Data.Map.insert k a m = m & at k ?~ a

Note that at doesn't work for arrays or lists. You can't delete an arbitrary element from an array (what would be left in its place?), and you can't set an arbitrary element in a list because if the index is out of list's bounds, you'd have to somehow fill the stretch between the last element and the element you just inserted (i.e. [1,2,3] & at 10 .~ 5 is undefined). If you want to modify an already existing value in an array or list, you should use ix instead.

at is often used with non. See the documentation of non for examples.

Note that at isn't strict for Map, even if you're using Data.Map.Strict:

>>> Data.Map.Strict.size (Data.Map.Strict.empty & at 1 .~ Just undefined)
1

The reason for such behavior is that there's actually no “strict Map” type; Data.Map.Strict just provides some strict functions for ordinary Maps.

This package doesn't actually provide any instances for at, but there are instances for Map and IntMap in microlens-ghc and an instance for HashMap in microlens-platform.

_1 :: Field1 s t a b => Lens s t a b #

Gives access to the 1st field of a tuple (up to 5-tuples).

Getting the 1st component:

>>> (1,2,3,4,5) ^. _1
1

Setting the 1st component:

>>> (1,2,3) & _1 .~ 10
(10,2,3)

Note that this lens is lazy, and can set fields even of undefined:

>>> set _1 10 undefined :: (Int, Int)
(10,*** Exception: Prelude.undefined

This is done to avoid violating a lens law stating that you can get back what you put:

>>> view _1 . set _1 10 $ (undefined :: (Int, Int))
10

The implementation (for 2-tuples) is:

_1 f t = (,) <$> f    (fst t)
             <*> pure (snd t)

or, alternatively,

_1 f ~(a,b) = (\a' -> (a',b)) <$> f a

(where ~ means a lazy pattern).

_2, _3, _4, and _5 are also available (see below).

_2 :: Field2 s t a b => Lens s t a b #

_3 :: Field3 s t a b => Lens s t a b #

_4 :: Field4 s t a b => Lens s t a b #

_5 :: Field5 s t a b => Lens s t a b #

strict :: Strict lazy strict => Lens' lazy strict #

strict lets you convert between strict and lazy versions of a datatype:

>>> let someText = "hello" :: Lazy.Text
>>> someText ^. strict
"hello" :: Strict.Text

It can also be useful if you have a function that works on a strict type but your type is lazy:

stripDiacritics :: Strict.Text -> Strict.Text
stripDiacritics = ...
>>> let someText = "Paul Erdős" :: Lazy.Text
>>> someText & strict %~ stripDiacritics
"Paul Erdos" :: Lazy.Text

strict works on ByteString and StateT/WriterT/RWST if you use microlens-ghc, and additionally on Text if you use microlens-platform.

lazy :: Strict lazy strict => Lens' strict lazy #

lazy is like strict but works in opposite direction:

>>> let someText = "hello" :: Strict.Text
>>> someText ^. lazy
"hello" :: Lazy.Text

type ASetter s t a b = (a -> Identity b) -> s -> Identity t #

ASetter s t a b is something that turns a function modifying a value into a function modifying a structure. If you ignore Identity (as Identity a is the same thing as a), the type is:

type ASetter s t a b = (a -> b) -> s -> t

The reason Identity is used here is for ASetter to be composable with other types, such as Lens.

Technically, if you're writing a library, you shouldn't use this type for setters you are exporting from your library; the right type to use is Setter, but it is not provided by this package (because then it'd have to depend on distributive). It's completely alright, however, to export functions which take an ASetter as an argument.

type ASetter' s a = ASetter s s a a #

This is a type alias for monomorphic setters which don't change the type of the container (or of the value inside). It's useful more often than the same type in lens, because we can't provide real setters and so it does the job of both ASetter' and Setter'.

type SimpleGetter s a = forall r. Getting r s a #

A SimpleGetter s a extracts a from s; so, it's the same thing as (s -> a), but you can use it in lens chains because its type looks like this:

type SimpleGetter s a =
  forall r. (a -> Const r a) -> s -> Const r s

Since Const r is a functor, SimpleGetter has the same shape as other lens types and can be composed with them. To get (s -> a) out of a SimpleGetter, choose r ~ a and feed Const :: a -> Const a a to the getter:

-- the actual signature is more permissive:
-- view :: Getting a s a -> s -> a
view :: SimpleGetter s a -> s -> a
view getter = getConst . getter Const

The actual Getter from lens is more general:

type Getter s a =
  forall f. (Contravariant f, Functor f) => (a -> f a) -> s -> f s

I'm not currently aware of any functions that take lens's Getter but won't accept SimpleGetter, but you should try to avoid exporting SimpleGetters anyway to minimise confusion. Alternatively, look at microlens-contra, which provides a fully lens-compatible Getter.

Lens users: you can convert a SimpleGetter to Getter by applying to . view to it.

type Getting r s a = (a -> Const r a) -> s -> Const r s #

Functions that operate on getters and folds – such as (^.), (^..), (^?) – use Getter r s a (with different values of r) to describe what kind of result they need. For instance, (^.) needs the getter to be able to return a single value, and so it accepts a getter of type Getting a s a. (^..) wants the getter to gather values together, so it uses Getting (Endo [a]) s a (it could've used Getting [a] s a instead, but it's faster with Endo). The choice of r depends on what you want to do with elements you're extracting from s.

type SimpleFold s a = forall r. Monoid r => Getting r s a #

A SimpleFold s a extracts several as from s; so, it's pretty much the same thing as (s -> [a]), but you can use it with lens operators.

The actual Fold from lens is more general:

type Fold s a =
  forall f. (Contravariant f, Applicative f) => (a -> f a) -> s -> f s

There are several functions in lens that accept lens's Fold but won't accept SimpleFold; I'm aware of takingWhile, droppingWhile, backwards, foldByOf, foldMapByOf. For this reason, try not to export SimpleFolds if at all possible. microlens-contra provides a fully lens-compatible Fold.

Lens users: you can convert a SimpleFold to Fold by applying folded . toListOf to it.

type Lens s t a b = forall (f :: Type -> Type). Functor f => (a -> f b) -> s -> f t #

Lens s t a b is the lowest common denominator of a setter and a getter, something that has the power of both; it has a Functor constraint, and since both Const and Identity are functors, it can be used whenever a getter or a setter is needed.

  • a is the type of the value inside of structure
  • b is the type of the replaced value
  • s is the type of the whole structure
  • t is the type of the structure after replacing a in it with b

type Lens' s a = Lens s s a a #

This is a type alias for monomorphic lenses which don't change the type of the container (or of the value inside).

type Traversal s t a b = forall (f :: Type -> Type). Applicative f => (a -> f b) -> s -> f t #

Traversal s t a b is a generalisation of Lens which allows many targets (possibly 0). It's achieved by changing the constraint to Applicative instead of Functor – indeed, the point of Applicative is that you can combine effects, which is just what we need to have many targets.

Ultimately, traversals should follow 2 laws:

t pure ≡ pure
fmap (t f) . t g ≡ getCompose . t (Compose . fmap f . g)

The 1st law states that you can't change the shape of the structure or do anything funny with elements (traverse elements which aren't in the structure, create new elements out of thin air, etc.). The 2nd law states that you should be able to fuse 2 identical traversals into one. For a more detailed explanation of the laws, see this blog post (if you prefer rambling blog posts), or The Essence Of The Iterator Pattern (if you prefer papers).

Traversing any value twice is a violation of traversal laws. You can, however, traverse values in any order.

type Traversal' s a = Traversal s s a a #

This is a type alias for monomorphic traversals which don't change the type of the container (or of the values inside).

type LensLike (f :: Type -> Type) s t a b = (a -> f b) -> s -> f t #

LensLike is a type that is often used to make combinators as general as possible. For instance, take (<<%~), which only requires the passed lens to be able to work with the (,) a functor (lenses and traversals can do that). The fully expanded type is as follows:

(<<%~) :: ((a -> (a, b)) -> s -> (a, t)) -> (a -> b) -> s -> (a, t)

With LensLike, the intent to use the (,) a functor can be made a bit clearer:

(<<%~) :: LensLike ((,) a) s t a b -> (a -> b) -> s -> (a, t)

type LensLike' (f :: Type -> Type) s a = LensLike f s s a a #

A type alias for monomorphic LensLikes.

at :: At m => Index m -> Lens' m (Maybe (IxValue m)) #

This lens lets you read, write, or delete elements in Map-like structures. It returns Nothing when the value isn't found, just like lookup:

Data.Map.lookup k m = m ^. at k

However, it also lets you insert and delete values by setting the value to Just value or Nothing:

Data.Map.insert k a m = m & at k .~ Just a

Data.Map.delete k m = m & at k .~ Nothing

Or you could use (?~) instead of (.~):

Data.Map.insert k a m = m & at k ?~ a

Note that at doesn't work for arrays or lists. You can't delete an arbitrary element from an array (what would be left in its place?), and you can't set an arbitrary element in a list because if the index is out of list's bounds, you'd have to somehow fill the stretch between the last element and the element you just inserted (i.e. [1,2,3] & at 10 .~ 5 is undefined). If you want to modify an already existing value in an array or list, you should use ix instead.

at is often used with non. See the documentation of non for examples.

Note that at isn't strict for Map, even if you're using Data.Map.Strict:

>>> Data.Map.Strict.size (Data.Map.Strict.empty & at 1 .~ Just undefined)
1

The reason for such behavior is that there's actually no “strict Map” type; Data.Map.Strict just provides some strict functions for ordinary Maps.

This package doesn't actually provide any instances for at, but there are instances for Map and IntMap in microlens-ghc and an instance for HashMap in microlens-platform.