MIT licensed by Colin Woodbury
Maintained by Colin Woodbury
This version can be pinned in stack with:microlens-aeson-2.5.2@sha256:32c27de86a54e63ce917973050cf8338e2782e008f71986c0b98c10aeb88947d,1641

Module documentation for 2.5.2

microlens-aeson

Hackage Stackage Nightly Stackage LTS

microlens-aeson provides Traversals for the Aeson library’s Value type, while obeying the Traversal laws.

microlens-aeson is derived from lens-aeson, but is based upon microlens to reduce the amount of dependencies involved.

Here is the dependency graph for lens-aeson:

lens-aeson dependencies

And that for microlens-aeson:

microlens-aeson dependencies

Usage

microlens-aeson provides Traversals into both lazy and strict variants of all the text types. Here are some examples:

{-# LANGUAGE OverloadedStrings #-}

import Data.Aeson
import Data.Text (Text)
import Lens.Micro.Aeson

--------------------------
-- Manipulating primatives
--------------------------
-- | Optionally getting one value
a :: Maybe Int
a = ("37" :: Text) ^? _Integer  -- Just 37

-- | Setting one value within encoded JSON
b :: Maybe Text
b = "true" & _Bool .~ False  -- "false"

----------------------
-- Manipulating arrays
----------------------
-- | Get all values as an Aeson type.
c :: [Value]
c = "[1, 2, 3]" ^.. values  -- [Number 1.0, Number 2.0, Number 3.0]

-- | Get all values cast to some simpler number type.
d :: [Double]
d = "[1, 2, 3]" ^.. values . _Double  -- [1.0, 2.0, 3.0]

-- | Access a specific index, and set a `Value` directly.
e :: Text
e = "[1,2,3]" & nth 1 .~ Number 20  -- "[1,20,3]"

-----------------------
-- Manipulating objects
-----------------------
-- | Access all values of the key/value pairs.
f :: Text
f = "{\"a\":4,\"b\":7}" & members . _Number %~ (*10)  -- "{\"a\":40,\"b\":70}"

-- | Access via a given key.
g :: Maybe Value
g = ("{\"a\": 100, \"b\": 200}" :: Text) ^? key "a"  -- Just (Number 100.0)

-----------------------------------
-- Aeson `Value`s from encoded JSON
-----------------------------------
h :: Maybe Text
h = "{\"a\":4,\"b\":7}" ^? _Value
-- Just (Object (fromList [("a",Number 4.0),("b",Number 7.0)]))

See the Haddock documentation for a full API specification.

Migration from Data.Aeson.Lens

The functions provided here are Traversals, not Prisms, therefore creation of encoded JSON from Haskell types like:

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

is no longer possible. Otherwise, if your use cases are strictly like those listed in the Usage section above, then you need only to switch the import from Data.Aeson.Lens to Lens.Micro.Aeson.

Changes

microlens-aeson

2.5.2 (2024-03-01)

Changed

  • Support for text-2.1.

2.5.1 (2023-08-16)

Changed

  • Support for aeson-2.2.

2.5.0 (2022-03-19)

This is a breaking update that matches upstream changes to lens-aeson. Luckily the changes are mostly simplifications and improvements that better match the aeson-2 API. Thanks to sjshuck for his contributions to this release.

Changed

  • Simplify class hierarchy to AsNumber t => AsValue t. Change the default signature of _Number accordingly.
  • Move _String, _Bool, and _Null to be methods of class AsValue.
  • Convert HashMap Text-based interfaces to KeyMap Key. This changes the types of _Object and key.
  • Change Index Value to Key.
  • Require base >= 4.9, the same as aeson-2.* does.
  • Drop dependencies on deepseq and unordered-containers.

Removed

  • Primitive and class AsPrimitive.
  • Orphan Ixed instances for HashMap and Vector.

2.4.1 (2022-01-21)

Added

  • text-2.0 support.

2.4.0 (2021-10-21)

Changed

  • aeson-2.0 is now the minimum required version.

2.3.1 (2020-07-19)

Fixed

  • Test suite fixed to succeed deterministically on 32-bit machines.

2.3.0.3

  • Readd 7.10 support. Forgive the spam.

2.3.0.2

  • Bumping bounds, cleaning code.

2.3.0.1

  • Enable compilation with GHC 7.8 (base-4.7). Only when this version of base is used does our type Primitive lose its Hashable instance, due to a lack of DeriveAnyClass. Otherwise, the API is unchanged from microlens-aeson-2.3.0.

2.2.0

  • Various fixes to dependency version bounds

2.1.0

  • Restored original AsJSON and _JSON typing
  • Bumped microlens dep max

2.0.0

  • Complete conversion to microlens
  • All Prism are now Traversal

1.0.0.5

  • Fix tests to work against vector-0.11
  • Documentation fixes
  • No functional changes since 1.0.0.4

1.0.0.3

  • Move lens upper bound to < 5 like the other packages in the family

1

  • Module migrated from lens package to Data.Aeson.Lens

0.1.2

  • Added members and values

0.1.1

  • Broadened dependencies

0.1

  • Repository initialized