Convenience Error structure for the separate parsing/decoding phases. For when things really aren't that complicated.

Convenience Error structure for the separate parsing/decoding phases. For when things really aren't that complicated.

Wrapper for our CursorHistory' to define our index as being an Int.

Provide some of the type parameters that the underlying DecodeResultT requires. This contains the state and error management as we walk around our zipper and decode our JSON input.

Type alias to describe the lens that may be given to a zipper movement function to more directly target something within the Json data structure.

This is an alias to help explain a type from the zipper that is used to move around the Json data structure. 'JCursor h a' represents a "cursor" that is currently located on a thing of type a, having previously been on a thing of type h.

This type will grow as a form of "breadcrumb" trail as the cursor moves through the data structure. It may be used interchangably with 'h :>> a' from the Zipper module.

A shorthand description of our Decoder type that is used directly to convert Json structures to other data types.

Function to define a Decoder for a specific data type.

For example, given the following data type:

data Image = Image
  { _imageW        :: Int
  , _imageH        :: Int
  , _imageTitle    :: Text
  , _imageAnimated :: Bool
  , _imageIDs      :: [Int]
  }

We can use withCursor to write a decoder that will be given a cursor that we can use to build the data types that we need.

imageDecoder :: Monad f => Decoder f Image
imageDecoder = withCursor $ \curs -> Image
  <$> D.fromKey "Width" D.int curs
  <*> D.fromKey "Height" D.int curs
  <*> D.fromKey "Title" D.text curs
  <*> D.fromKey "Animated" D.bool curs
  <*> D.fromKey "IDs" intArray curs

It's up to you to provide a cursor that is at the correct position for a Decoder to operate, but building decoders in this way simplifies creating decoders for larger structures, as the smaller pieces contain fewer assumptions. This encourages greater reuse of decoders and simplifies the debugging process.

Run a 'Decoder f a' using a JCursor to try to convert it into the data type described by the Decoder.

Execute a DecodeResult to determine if the process has been successful, providing a descriptive error and the path history of the cursor movements to assist in debugging any failures.

Run a pure decoder with Identity.

Using the given parsing function, take some input and try to convert it to the Json structure. Then pass it to the given Decoder.

Generalise a Decoder that has been specialised to Identity back to some 'Monad f'.

Using a given LensLike, try to step down into the Json data structure to the location targeted by the lens.

This can be used to move large steps over the data structure, or more precisely to specific keys at deeper levels. On a successful step, the history will be recorded as a single step into the thing described by the Text input.

Attempt to step one level "up" from the current cursor location.

A constrained version of into that will only move a single step down into a Json value. The Text input is so you're able to provide an expectation of what you are stepping down into, this provides a more descriptive error message than simply "down".

For example:

firstElemCursor <- down "array" cursor

From the current cursor location, try to move n steps to the left.

From the current cursor location, try to move 1 step to the left.

From the current cursor location, try to move n steps to the right.

From the current cursor location, try to move 1 step to the right.

From the current cursor position, try to move to the value for the first occurence of that key. This move expects that you've positioned the cursor on an object.

Attempt a Decoder action that might fail and return a Maybe value instead.

Move to the first occurence of this key, as per moveToKey and then attempt to run the given Decoder on that value, returning the result.

...
txtVal <- fromKey "foo" text c
...

A simplified version of fromKey that takes a Text value indicating a key to be moved to and decoded using the given 'Decoder f a'. If you don't need any special cursor movements to reach the list of keys you require, you could use this function to build a trivial Decoder for a record type:

data MyRec = MyRec { fieldA :: Text, fieldB :: Int }

myRecDecoder :: Decoder f MyRec
myRecDecoder = MyRec
  $ atKey "field_a" text
  * atKey "field_b" int

Provide a conversion function and create a Decoder that uses the current cursor and runs the given function. Fails with ConversionFailure and the given Text description.

Try to decode the value at the current focus using the given Decoder.

Decoder for Scientific

Decoder for a bounded integral value.

Decoder for Int

Decoder for Bool

Decoder for Text, as per the Text documentation any unacceptable utf8 characters will be replaced.

Decoder for String

Decoder for a Char value that cannot contain values in the range U+D800 to U+DFFF. This decoder will fail if the Char is outside of this range.

Decoder for a Haskell Char value whose values represent Unicode (or equivalently ISO/IEC 10646) characters.

Decoder for null

Decoder for pulling out the Json Haskell data structure at the current cursor.

Allows for folding over the results of repeated cursor movements.

intList :: Decoder f [String]
intList = withCursor $ curs ->
  foldCursor [] (acc a -> acc <> [a]) moveRight1 string curs

Use the Cons typeclass and move leftwards from the current cursor position, "consing" the values to the s as it moves.

Use the Snoc typeclass and move rightwards from the current cursor position, "snocing" the values to the s as it moves.

Decode a NonEmpty list of a at the given cursor position.

Create a Decoder for a NonEmpty list.

Decode a '[a]' at the current cursor position.

Create a Decoder for a list of a

Named to match it's Encoder counterpart, this function will decode an optional value.

Try to decode an optional value, returning the given default value if Nothing is returned.

Decode either an a or a b, failing if neither Decoder succeeds. The Right decoder is attempted first.