Safe Haskell | Safe-Inferred |
---|---|
Language | Haskell2010 |
Exposes functions for building JSON decoders that harness the power of the simdjson::ondemand API.
A decoder is really a function from a Value
to some Haskell type in the Decoder
monad.
It looks like Data.Aeson.parseJSON, except the Value
is opaque and can only be used
when it's passed by reference across the C FFI.
decodeEither
provides the quickest way to feed the initial Value
to your decoder.
It does this by obtaining a top-level Value
from the simdjson document
instance. Decoding a document into a scalar from a Value
is not supported
by simdjson. While simdjson can cast a document directly to a scalar, this
library currently exposes no interface for this.
Synopsis
- decodeEither :: (Value -> Decoder a) -> ByteString -> Either HermesException a
- data Decoder a
- data HermesEnv
- atKey :: Text -> (Value -> Decoder a) -> Object -> Decoder a
- atKeyOptional :: Text -> (Value -> Decoder a) -> Object -> Decoder (Maybe a)
- atKeyStrict :: Text -> (Value -> Decoder a) -> Object -> Decoder a
- atPointer :: Text -> (Value -> Decoder a) -> Decoder a
- bool :: Value -> Decoder Bool
- char :: Value -> Decoder Char
- double :: Value -> Decoder Double
- int :: Value -> Decoder Int
- scientific :: Value -> Decoder Scientific
- string :: Value -> Decoder String
- text :: Value -> Decoder Text
- list :: (Value -> Decoder a) -> Value -> Decoder [a]
- nullable :: (Value -> Decoder a) -> Value -> Decoder (Maybe a)
- objectAsKeyValues :: (Text -> Decoder k) -> (Value -> Decoder v) -> Value -> Decoder [(k, v)]
- day :: Value -> Decoder Day
- month :: Value -> Decoder Month
- quarter :: Value -> Decoder Quarter
- timeOfDay :: Value -> Decoder TimeOfDay
- timeZone :: Value -> Decoder (Maybe TimeZone)
- localTime :: Value -> Decoder LocalTime
- utcTime :: Value -> Decoder UTCTime
- zonedTime :: Value -> Decoder ZonedTime
- data HermesException
- data DocumentError = DocumentError {}
- isNull :: Value -> Decoder Bool
- withArray :: (Array -> Decoder a) -> Value -> Decoder a
- withBool :: (Bool -> Decoder a) -> Value -> Decoder a
- withDocumentValue :: (Value -> Decoder a) -> InputBuffer -> Decoder a
- withDouble :: (Double -> Decoder a) -> Value -> Decoder a
- withInt :: (Int -> Decoder a) -> Value -> Decoder a
- withObject :: (Object -> Decoder a) -> Value -> Decoder a
- withString :: (String -> Decoder a) -> Value -> Decoder a
- withText :: (Text -> Decoder a) -> Value -> Decoder a
- withRawByteString :: (ByteString -> Decoder a) -> Value -> Decoder a
- data Array
- data ArrayIter
- data Document
- data InputBuffer
- data Object
- data Parser
- data Value
Decoding from ByteString input
decodeEither :: (Value -> Decoder a) -> ByteString -> Either HermesException a Source #
Decode a strict ByteString
using the simdjson::ondemand bindings.
Decoder monad
A Decoder is some context around the IO needed by the C FFI to allocate local memory.
Users have no access to the underlying IO, since this could allow decoders to launch nukes.
Using decodeEither
discharges the IO and returns us to purity,
since we know decoding a document is referentially transparent.
Contains foreign references to the allocated simdjson::parser and simdjson::document. Also maintains a path string that is updated when an object field or array value is entered and which is displayed in errors.
Object field accessors
Obtain an object using withObject
that can be passed
to these field lookup functions.
atKey :: Text -> (Value -> Decoder a) -> Object -> Decoder a Source #
Find an object field by key, where an exception is thrown if the key is missing.
atKeyOptional :: Text -> (Value -> Decoder a) -> Object -> Decoder (Maybe a) Source #
Find an object field by key, where Nothing is returned if the key is missing.
atKeyStrict :: Text -> (Value -> Decoder a) -> Object -> Decoder a Source #
Uses find_field, which means if you access a field out-of-order this will throw an exception. It also cannot support optional fields.
Decoders
JSON pointer
atPointer :: Text -> (Value -> Decoder a) -> Decoder a Source #
Decode a value at the particular JSON pointer following RFC 6901. Be careful where you use this because it rewinds the document on each successive call.
Values
scientific :: Value -> Decoder Scientific Source #
Parse a Scientific from a Value.
string :: Value -> Decoder String Source #
Parse a JSON string into a Haskell String.
For best performance you should use text
instead.
list :: (Value -> Decoder a) -> Value -> Decoder [a] Source #
Parse a homogenous JSON array into a Haskell list.
nullable :: (Value -> Decoder a) -> Value -> Decoder (Maybe a) Source #
Transforms a parser to return Nothing when the value is null.
:: (Text -> Decoder k) | Parses a Text key in the Decoder monad. JSON keys are always text. |
-> (Value -> Decoder v) | Decoder for the field value. |
-> Value | |
-> Decoder [(k, v)] |
Parse an object into a homogenous list of key-value tuples.
Date and time
Parses date and time types from Data.Time using the same attoparsec parsers as Data.Aeson via https://hackage.haskell.org/package/attoparsec-iso8601.
timeZone :: Value -> Decoder (Maybe TimeZone) Source #
Parse a time zone, and return Nothing
if the offset from UTC is
zero. (This makes some speedups possible.)
localTime :: Value -> Decoder LocalTime Source #
Parse a date and time, of the form YYYY-MM-DD HH:MM[:SS[.SSS]]
.
The space may be replaced with a T
. The number of seconds is optional
and may be followed by a fractional component.
utcTime :: Value -> Decoder UTCTime Source #
Behaves as zonedTime
, but converts any time zone offset into a UTC time.
zonedTime :: Value -> Decoder ZonedTime Source #
Parse a date with time zone info. Acceptable 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.
Error Types
data HermesException Source #
The library can throw exceptions from simdjson in addition to its own exceptions.
SIMDException DocumentError | An exception thrown from the simdjson library. |
InternalException DocumentError | An exception thrown from an internal library function. |
Instances
data DocumentError Source #
Record containing all pertinent information for troubleshooting an exception.
Instances
Value helpers
withArray :: (Array -> Decoder a) -> Value -> Decoder a Source #
Helper to work with an Array parsed from a Value.
withBool :: (Bool -> Decoder a) -> Value -> Decoder a Source #
Helper to work with a Bool parsed from a Value.
withDocumentValue :: (Value -> Decoder a) -> InputBuffer -> Decoder a Source #
Parse the given input into a document iterator, get its Value, which is either a JSON object or an array, and run the given action on that Value.
withDouble :: (Double -> Decoder a) -> Value -> Decoder a Source #
Helper to work with a Double parsed from a Value.
withInt :: (Int -> Decoder a) -> Value -> Decoder a Source #
Helper to work with an Int parsed from a Value.
withObject :: (Object -> Decoder a) -> Value -> Decoder a Source #
Helper to work with an Object parsed from a Value.
withString :: (String -> Decoder a) -> Value -> Decoder a Source #
Helper to work with a String parsed from a Value.
withText :: (Text -> Decoder a) -> Value -> Decoder a Source #
Helper to work with a Text parsed from a Value.
Raw ByteString access
withRawByteString :: (ByteString -> Decoder a) -> Value -> Decoder a Source #
Helper to work with the raw ByteString of the JSON token parsed from the given Value.
simdjson Opaque Types
data InputBuffer Source #
A reference to an opaque simdjson::padded_string.