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 Source #

Minimal complete definition

Nothing

Methods

_Number :: Prism' t Scientific Source #

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

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

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

_Double :: Prism' t Double Source #

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

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

_Integer :: Prism' t Integer Source #

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 Source # |
Instance details Defined in Data.Aeson.Lens Methods _Number :: Prism' Value Scientific Source # _Double :: Prism' Value Double Source # _Integer :: Prism' Value Integer Source #
AsNumber ByteString Source # |
Instance details Defined in Data.Aeson.Lens Methods _Number :: Prism' ByteString Scientific Source # _Double :: Prism' ByteString Double Source # _Integer :: Prism' ByteString Integer Source #
AsNumber ByteString Source # |
Instance details Defined in Data.Aeson.Lens Methods _Number :: Prism' ByteString Scientific Source # _Double :: Prism' ByteString Double Source # _Integer :: Prism' ByteString Integer Source #
AsNumber Scientific Source # |
Instance details Defined in Data.Aeson.Lens Methods _Number :: Prism' Scientific Scientific Source # _Double :: Prism' Scientific Double Source # _Integer :: Prism' Scientific Integer Source #
AsNumber Text Source # |
Instance details Defined in Data.Aeson.Lens Methods _Number :: Prism' Text Scientific Source # _Double :: Prism' Text Double Source # _Integer :: Prism' Text Integer Source #
AsNumber Text Source # |
Instance details Defined in Data.Aeson.Lens Methods _Number :: Prism' Text Scientific Source # _Double :: Prism' Text Double Source # _Integer :: Prism' Text Integer Source #
AsNumber String Source # |
Instance details Defined in Data.Aeson.Lens Methods _Number :: Prism' String Scientific Source # _Double :: Prism' String Double Source # _Integer :: Prism' String Integer Source #

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

Access Integer `Value`s as Integrals.

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

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

nonNull :: Prism' Value Value Source #

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 Source #

Minimal complete definition

_Value

Methods

_Value :: Prism' t Value Source #

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

_String :: Prism' t Text Source #

    >>> "{\"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 Source #

    >>> "{\"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 () Source #

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

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

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

_Object :: Prism' t (KeyMap Value) Source #

    >>> "{\"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) Source #

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

#### Instances

Instances details

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

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

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) Source #

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 Source #

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 Source #

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 Source #

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 Source #

Methods

_Key :: Iso' t Key Source #

`_Key` is an `ReifiedIso` 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 Source # |
Instance details Defined in Data.Aeson.Lens Methods _Key :: Iso' Key Key Source #

IsKey ByteString Source #

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 `ReifiedIso`, 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 Source #

IsKey ByteString Source #

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 `ReifiedIso`, 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 Source #
IsKey Text Source # |
Instance details Defined in Data.Aeson.Lens Methods _Key :: Iso' Text Key Source #
IsKey Text Source # |
Instance details Defined in Data.Aeson.Lens Methods _Key :: Iso' Text Key Source #
IsKey ShortText Source # |
Instance details Defined in Data.Aeson.Lens Methods _Key :: Iso' ShortText Key Source #
IsKey String Source # |
Instance details Defined in Data.Aeson.Lens Methods _Key :: Iso' String Key Source #

# Decoding

class AsJSON t where Source #

Methods

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

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

#### Instances

Instances details

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

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

# Pattern Synonyms

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

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

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

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

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

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

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

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

pattern Null_ :: AsValue t => t Source #

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

# Orphan instances

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