Data.Aeson.Lens

lens-aeson-1.2.3: Law-abiding lenses for aeson

Copyright | (c) Edward Kmett 2013-2019 (c) Paul Wilson 2012
License | BSD3
Maintainer | Edward Kmett <ekmett@gmail.com>
Stability | experimental
Portability | non-portable
Safe Haskell | Trustworthy
Language | Haskell2010

Data.Aeson.Lens

Contents

- Numbers
- Objects and Arrays
- Decoding
- Pattern Synonyms
- Orphan instances

Description

This module also exports orphan ``Ixed` `Value`` and ``Plated` `Value`` instances.

Synopsis

- class AsNumber t where
  - _Number :: Prism' t Scientific
  - _Double :: Prism' t Double
  - _Integer :: Prism' t Integer
- _Integral :: (AsNumber t, Integral a) => Prism' t a
- nonNull :: Prism' Value Value
- class AsNumber t => AsValue t where
  - _Value :: Prism' t Value
  - _String :: Prism' t Text
  - _Bool :: Prism' t Bool
  - _Null :: Prism' t ()
  - _Object :: Prism' t (KeyMap Value)
  - _Array :: Prism' t (Vector Value)
- key :: AsValue t => Key -> Traversal' t Value
- atKey :: AsValue t => Key -> Traversal' t (Maybe Value)
- members :: AsValue t => IndexedTraversal' Key t Value
- nth :: AsValue t => Int -> Traversal' t Value
- values :: AsValue t => IndexedTraversal' Int t Value
- class IsKey t where
  - _Key :: Iso' t Key
- class AsJSON t where
  - _JSON :: (FromJSON a, ToJSON b) => Prism t t a b
- _JSON' :: (AsJSON t, FromJSON a, ToJSON a) => Prism' t a
- pattern JSON :: (FromJSON a, ToJSON a, AsJSON t) => a -> t
- pattern Value_ :: (FromJSON a, ToJSON a) => a -> Value
- pattern Number_ :: AsNumber t => Scientific -> t
- pattern Double :: AsNumber t => Double -> t
- pattern Integer :: AsNumber t => Integer -> t
- pattern Integral :: (AsNumber t, Integral a) => a -> t
- pattern Bool_ :: AsValue t => Bool -> t
- pattern String_ :: AsValue t => Text -> t
- pattern Null_ :: AsValue t => t
- pattern Key_ :: IsKey t => Key -> t

# Numbers

class AsNumber t where #

Minimal complete definition

Nothing

Methods

_Number :: Prism' t Scientific #

    >>> "[1, \"x\"]" ^? nth 0 . _Number
    Just 1.0

    >>> "[1, \"x\"]" ^? nth 1 . _Number
    Nothing

default _Number :: AsValue t => Prism' t Scientific #

_Double :: Prism' t Double #

Prism into an `Double` over a `Value` or `Scientific`

    >>> "[10.2]" ^? nth 0 . _Double
    Just 10.2

_Integer :: Prism' t Integer #

Prism into an `Integer` over a `Value` or `Scientific`

    >>> "[10]" ^? nth 0 . _Integer
    Just 10

    >>> "[10.5]" ^? nth 0 . _Integer
    Just 10

    >>> "42" ^? _Integer
    Just 42

#### Instances

Instances details

AsNumber Value # |
Instance details Defined in Data.Aeson.Lens Methods _Number :: Prism' Value Scientific # _Double :: Prism' Value Double # _Integer :: Prism' Value Integer #
AsNumber ByteString # |
Instance details Defined in Data.Aeson.Lens Methods _Number :: Prism' ByteString Scientific # _Double :: Prism' ByteString Double # _Integer :: Prism' ByteString Integer #
AsNumber ByteString # |
Instance details Defined in Data.Aeson.Lens Methods _Number :: Prism' ByteString Scientific # _Double :: Prism' ByteString Double # _Integer :: Prism' ByteString Integer #
AsNumber Scientific # |
Instance details Defined in Data.Aeson.Lens Methods _Number :: Prism' Scientific Scientific # _Double :: Prism' Scientific Double # _Integer :: Prism' Scientific Integer #
AsNumber Text # |
Instance details Defined in Data.Aeson.Lens Methods _Number :: Prism' Text Scientific # _Double :: Prism' Text Double # _Integer :: Prism' Text Integer #
AsNumber Text # |
Instance details Defined in Data.Aeson.Lens Methods _Number :: Prism' Text Scientific # _Double :: Prism' Text Double # _Integer :: Prism' Text Integer #
AsNumber String # |
Instance details Defined in Data.Aeson.Lens Methods _Number :: Prism' String Scientific # _Double :: Prism' String Double # _Integer :: Prism' String Integer #

_Integral :: (AsNumber t, Integral a) => Prism' t a #

Access Integer `Value`s as Integrals.

    >>> "[10]" ^? nth 0 . _Integral
    Just 10

    >>> "[10.5]" ^? nth 0 . _Integral
    Just 10

nonNull :: Prism' Value Value #

Prism into non-`Null` values

    >>> "{\"a\": \"xyz\", \"b\": null}" ^? key "a" . nonNull
    Just (String "xyz")

    >>> "{\"a\": {}, \"b\": null}" ^? key "a" . nonNull
    Just (Object (fromList []))

    >>> "{\"a\": \"xyz\", \"b\": null}" ^? key "b" . nonNull
    Nothing

# Objects and Arrays

class AsNumber t => AsValue t where #

Minimal complete definition

_Value

Methods

_Value :: Prism' t Value #

    >>> preview _Value "[1,2,3]" == Just (Array (Vector.fromList [Number 1.0,Number 2.0,Number 3.0]))
    True

_String :: Prism' t Text #

    >>> "{\"a\": \"xyz\", \"b\": true}" ^? key "a" . _String
    Just "xyz"

    >>> "{\"a\": \"xyz\", \"b\": true}" ^? key "b" . _String
    Nothing

    >>> _Object._Wrapped # [("key" :: Key, _String # "value")] :: String
    "{\"key\":\"value\"}"

_Bool :: Prism' t Bool #

    >>> "{\"a\": \"xyz\", \"b\": true}" ^? key "b" . _Bool
    Just True

    >>> "{\"a\": \"xyz\", \"b\": true}" ^? key "a" . _Bool
    Nothing

    >>> _Bool # True :: String
    "true"

    >>> _Bool # False :: String
    "false"

_Null :: Prism' t () #

    >>> "{\"a\": \"xyz\", \"b\": null}" ^? key "b" . _Null
    Just ()

    >>> "{\"a\": \"xyz\", \"b\": null}" ^? key "a" . _Null
    Nothing

    >>> _Null # () :: String
    "null"

_Object :: Prism' t (KeyMap Value) #

    >>> "{\"a\": {}, \"b\": null}" ^? key "a" . _Object
    Just (fromList [])

    >>> "{\"a\": {}, \"b\": null}" ^? key "b" . _Object
    Nothing

    >>> _Object._Wrapped # [("key" :: Key, _String # "value")] :: String
    "{\"key\":\"value\"}"

_Array :: Prism' t (Vector Value) #

    >>> preview _Array "[1,2,3]" == Just (Vector.fromList [Number 1.0,Number 2.0,Number 3.0])
    True

#### Instances

Instances details

AsValue Value # |
Instance details Defined in Data.Aeson.Lens Methods _Value :: Prism' Value Value # _String :: Prism' Value Text # _Bool :: Prism' Value Bool # _Null :: Prism' Value () # _Object :: Prism' Value (KeyMap Value) # _Array :: Prism' Value (Vector Value) #
AsValue ByteString # |
Instance details Defined in Data.Aeson.Lens Methods _Value :: Prism' ByteString Value # _String :: Prism' ByteString Text # _Bool :: Prism' ByteString Bool # _Null :: Prism' ByteString () # _Object :: Prism' ByteString (KeyMap Value) # _Array :: Prism' ByteString (Vector Value) #
AsValue ByteString # |
Instance details Defined in Data.Aeson.Lens Methods _Value :: Prism' ByteString Value # _String :: Prism' ByteString Text # _Bool :: Prism' ByteString Bool # _Null :: Prism' ByteString () # _Object :: Prism' ByteString (KeyMap Value) # _Array :: Prism' ByteString (Vector Value) #
AsValue Text # |
Instance details Defined in Data.Aeson.Lens Methods _Value :: Prism' Text Value # _String :: Prism' Text Text # _Bool :: Prism' Text Bool # _Null :: Prism' Text () # _Object :: Prism' Text (KeyMap Value) # _Array :: Prism' Text (Vector Value) #
AsValue Text # |
Instance details Defined in Data.Aeson.Lens Methods _Value :: Prism' Text Value # _String :: Prism' Text Text # _Bool :: Prism' Text Bool # _Null :: Prism' Text () # _Object :: Prism' Text (KeyMap Value) # _Array :: Prism' Text (Vector Value) #
AsValue String # |
Instance details Defined in Data.Aeson.Lens Methods _Value :: Prism' String Value # _String :: Prism' String Text # _Bool :: Prism' String Bool # _Null :: Prism' String () # _Object :: Prism' String (KeyMap Value) # _Array :: Prism' String (Vector Value) #

key :: AsValue t => Key -> Traversal' t Value #

Like `ix`, but for `Object` with `Key` indices. This often has better inference than `ix` when used with OverloadedStrings.

    >>> "{\"a\": 100, \"b\": 200}" ^? key "a"
    Just (Number 100.0)

    >>> "[1,2,3]" ^? key "a"
    Nothing

atKey :: AsValue t => Key -> Traversal' t (Maybe Value) #

Like `key`, but uses `at` instead of `ix`. This is handy when adding and removing object keys:

    >>> "{\"a\": 100, \"b\": 200}" & atKey "a" .~ Nothing
    "{\"b\":200}"

    >>> "{\"a\": 100, \"b\": 200}" & atKey "c" ?~ String "300"
    "{\"a\":100,\"b\":200,\"c\":\"300\"}"

members :: AsValue t => IndexedTraversal' Key t Value #

An indexed Traversal into Object properties

    >>> Data.List.sort ("{\"a\": 4, \"b\": 7}" ^@.. members . _Number)
    [("a",4.0),("b",7.0)]

    >>> "{\"a\": 4}" & members . _Number *~ 10
    "{\"a\":40}"

nth :: AsValue t => Int -> Traversal' t Value #

Like `ix`, but for Arrays with Int indexes

    >>> "[1,2,3]" ^? nth 1
    Just (Number 2.0)

    >>> "{\"a\": 100, \"b\": 200}" ^? nth 1
    Nothing

    >>> "[1,2,3]" & nth 1 .~ Number 20
    "[1,20,3]"

values :: AsValue t => IndexedTraversal' Int t Value #

An indexed Traversal into Array elements

    >>> "[1,2,3]" ^.. values
    [Number 1.0,Number 2.0,Number 3.0]

    >>> "[1,2,3]" & values . _Number *~ 10
    "[10,20,30]"

class IsKey t where #

Methods

_Key :: Iso' t Key #

`_Key` is an `Iso` from something to a `Key`. This is primarily intended for situations where one wishes to use object keys that are not string literals and therefore must be converted:

    >>> let k = "a" :: Text
    >>> "{\"a\": 100, \"b\": 200}" ^? key (k ^. _Key)
    Just (Number 100.0)

Note that applying `_Key` directly to a string literal (e.g., `"a" ^. `_Key``) will likely not typecheck when `OverloadedStrings` is enabled.

#### Instances

Instances details

IsKey Key # |
Instance details Defined in Data.Aeson.Lens Methods _Key :: Iso' Key Key #
IsKey ByteString # | This instance assumes that you are dealing with UTF-8–encoded `ByteString`s, as this is the encoding that RFC 8259 requires JSON values to use. As such, this is not a full `Iso`, since non–UTF-8–encoded `ByteString`s will not roundtrip:
    >>> let str = view _Key ("\255" :: Strict.ByteString)
    >>> str
    "\65533"
    >>> view (from _Key) str :: Strict.ByteString
    "\239\191\189"
Instance details Defined in Data.Aeson.Lens Methods _Key :: Iso' ByteString Key #
IsKey ByteString # | This instance assumes that you are dealing with UTF-8–encoded `ByteString`s, as this is the encoding that RFC 8259 requires JSON values to use. As such, this is not a full `Iso`, since non–UTF-8–encoded `ByteString`s will not roundtrip:
    >>> let str = view _Key ("\255" :: Lazy.ByteString)
    >>> str
    "\65533"
    >>> view (from _Key) str :: Lazy.ByteString
    "\239\191\189"
Instance details Defined in Data.Aeson.Lens Methods _Key :: Iso' ByteString Key #
IsKey Text # |
Instance details Defined in Data.Aeson.Lens Methods _Key :: Iso' Text Key #
IsKey Text # |
Instance details Defined in Data.Aeson.Lens Methods _Key :: Iso' Text Key #
IsKey ShortText # |
Instance details Defined in Data.Aeson.Lens Methods _Key :: Iso' ShortText Key #
IsKey String # |
Instance details Defined in Data.Aeson.Lens Methods _Key :: Iso' String Key #

# Decoding

class AsJSON t where #

Methods

_JSON :: (FromJSON a, ToJSON b) => Prism t t a b #

`_JSON` is a `Prism` from something containing JSON to something encoded in that structure

#### Instances

Instances details

AsJSON Value # |
Instance details Defined in Data.Aeson.Lens Methods _JSON :: (FromJSON a, ToJSON b) => Prism Value Value a b #
AsJSON ByteString # |
Instance details Defined in Data.Aeson.Lens Methods _JSON :: (FromJSON a, ToJSON b) => Prism ByteString ByteString a b #
AsJSON ByteString # |
Instance details Defined in Data.Aeson.Lens Methods _JSON :: (FromJSON a, ToJSON b) => Prism ByteString ByteString a b #
AsJSON Text # |
Instance details Defined in Data.Aeson.Lens Methods _JSON :: (FromJSON a, ToJSON b) => Prism Text Text a b #
AsJSON Text # |
Instance details Defined in Data.Aeson.Lens Methods _JSON :: (FromJSON a, ToJSON b) => Prism Text Text a b #
AsJSON String # |
Instance details Defined in Data.Aeson.Lens Methods _JSON :: (FromJSON a, ToJSON b) => Prism String String a b #

_JSON' :: (AsJSON t, FromJSON a, ToJSON a) => Prism' t a #

# Pattern Synonyms

pattern JSON :: (FromJSON a, ToJSON a, AsJSON t) => a -> t #

pattern Value_ :: (FromJSON a, ToJSON a) => a -> Value #

pattern Number_ :: AsNumber t => Scientific -> t #

pattern Double :: AsNumber t => Double -> t #

pattern Integer :: AsNumber t => Integer -> t #

pattern Integral :: (AsNumber t, Integral a) => a -> t #

pattern Bool_ :: AsValue t => Bool -> t #

pattern String_ :: AsValue t => Text -> t #

pattern Null_ :: AsValue t => t #

pattern Key_ :: IsKey t => Key -> t #

# Orphan instances

Ixed Value # |
Instance details Methods ix :: Index Value -> Traversal' Value (IxValue Value) #
Plated Value # |
Instance details Methods plate :: Traversal' Value Value #
At (KeyMap v) # |
Instance details Methods at :: Index (KeyMap v) -> Lens' (KeyMap v) (Maybe (IxValue (KeyMap v))) #
Ixed (KeyMap v) # |
Instance details Methods ix :: Index (KeyMap v) -> Traversal' (KeyMap v) (IxValue (KeyMap v)) #
Wrapped (KeyMap v) # |
Instance details Associated Types
type Unwrapped (KeyMap v) |
Instance details Defined in Data.Aeson.Lens type Unwrapped (KeyMap v) = [(Key, v)]
Methods _Wrapped' :: Iso' (KeyMap v) (Unwrapped (KeyMap v)) #
t ~ KeyMap v' => Rewrapped (KeyMap v) t # | Use ``iso` `toList` `fromList``. Unwrapping returns some permutation of the list.
Instance details
Each (KeyMap a) (KeyMap b) a b # |
Instance details Methods each :: Traversal (KeyMap a) (KeyMap b) a b #