| Copyright | (C) CSIRO 2017-2018 |
|---|---|
| License | BSD3 |
| Maintainer | George Wilson <george.wilson@data61.csiro.au> |
| Stability | experimental |
| Portability | non-portable |
| Safe Haskell | None |
| Language | Haskell2010 |
Data.Sv
Contents
Description
This module exports most of the other modules from the package. It is intended to be imported unqualified, along with some qualified imports for the Data.Sv.Decode and Data.Sv.Encode modules as needed.
import Data.Sv import qualified Data.Sv.Decode as D import qualified Data.Sv.Encode as E
- decode :: Decode' s a -> Sv s -> DecodeValidation s [a]
- parseDecode :: Decode' ByteString a -> ParseOptions ByteString -> ByteString -> DecodeValidation ByteString [a]
- parseDecode' :: SvParser s -> Decode' s a -> ParseOptions s -> s -> DecodeValidation s [a]
- parseDecodeFromFile :: MonadIO m => Decode' ByteString a -> ParseOptions ByteString -> FilePath -> m (DecodeValidation ByteString [a])
- parseDecodeFromFile' :: MonadIO m => SvParser s -> Decode' s a -> ParseOptions s -> FilePath -> m (DecodeValidation s [a])
- decodeMay :: DecodeError e -> (s -> Maybe a) -> Decode e s a
- decodeEither :: (s -> Either (DecodeError e) a) -> Decode e s a
- decodeEither' :: (e -> DecodeError e') -> (s -> Either e a) -> Decode e' s a
- (>>==) :: Decode e s a -> (a -> DecodeValidation e b) -> Decode e s b
- (==<<) :: (a -> DecodeValidation e b) -> Decode e s a -> Decode e s b
- module Data.Sv.Decode.Type
- module Data.Sv.Decode.Error
- module Data.Sv.Parse
- module Data.Sv.Print
- encode :: Encode a -> EncodeOptions -> [a] -> ByteString
- encodeToFile :: Encode a -> EncodeOptions -> [a] -> FilePath -> IO ()
- encodeToHandle :: Encode a -> EncodeOptions -> [a] -> Handle -> IO ()
- encodeBuilder :: Encode a -> EncodeOptions -> [a] -> Builder
- encodeRow :: Encode a -> EncodeOptions -> a -> ByteString
- encodeSv :: Encode a -> EncodeOptions -> Maybe (NonEmpty ByteString) -> [a] -> Sv ByteString
- module Data.Sv.Encode.Type
- module Data.Sv.Encode.Options
- module Data.Sv.Syntax
- class Functor f => Alt (f :: * -> *) where
- class Contravariant (f :: * -> *) where
- class Contravariant f => Divisible (f :: * -> *) where
- divided :: Divisible f => f a -> f b -> f (a, b)
- class Divisible f => Decidable (f :: * -> *) where
- chosen :: Decidable f => f b -> f c -> f (Either b c)
Decoding
decode :: Decode' s a -> Sv s -> DecodeValidation s [a] Source #
Decodes a sv into a list of its values using the provided Decode
parseDecode :: Decode' ByteString a -> ParseOptions ByteString -> ByteString -> DecodeValidation ByteString [a] Source #
Parse a ByteString as an Sv, and then decode it with the given decoder.
This version uses Trifecta to parse the ByteString, which is assumed to
be UTF-8 encoded. If you want a different library, use parseDecode'.
parseDecode' :: SvParser s -> Decode' s a -> ParseOptions s -> s -> DecodeValidation s [a] Source #
Parse text as an Sv, and then decode it with the given decoder.
This version lets you choose which parsing library to use by providing an
SvParser. Common selections are trifecta and attoparsecByteString.
parseDecodeFromFile :: MonadIO m => Decode' ByteString a -> ParseOptions ByteString -> FilePath -> m (DecodeValidation ByteString [a]) Source #
Load a file, parse it, and decode it.
This version uses Trifecta to parse the file, which is assumed to be UTF-8 encoded.
parseDecodeFromFile' :: MonadIO m => SvParser s -> Decode' s a -> ParseOptions s -> FilePath -> m (DecodeValidation s [a]) Source #
Load a file, parse it, and decode it.
This version lets you choose which parsing library to use by providing an
SvParser. Common selections are trifecta and attoparsecByteString.
decodeEither :: (s -> Either (DecodeError e) a) -> Decode e s a Source #
decodeEither' :: (e -> DecodeError e') -> (s -> Either e a) -> Decode e' s a Source #
(>>==) :: Decode e s a -> (a -> DecodeValidation e b) -> Decode e s b infixl 1 Source #
This can be used to build a Decode whose value depends on the
result of another Decode. This is especially useful since Decode is not
a Monad.
If you need something like this but with more power, look at bindDecode
module Data.Sv.Decode.Type
module Data.Sv.Decode.Error
Parsing
module Data.Sv.Parse
Printing
module Data.Sv.Print
Encoding
encode :: Encode a -> EncodeOptions -> [a] -> ByteString Source #
Encode the given list with the given Encode, configured by the given
EncodeOptions.
encodeToFile :: Encode a -> EncodeOptions -> [a] -> FilePath -> IO () Source #
Encode, writing to a file. This is way is more efficient than encoding to
a ByteString and then writing to file.
encodeToHandle :: Encode a -> EncodeOptions -> [a] -> Handle -> IO () Source #
Encode, writing the output to a file handle.
encodeBuilder :: Encode a -> EncodeOptions -> [a] -> Builder Source #
Encode to a ByteString Builder, which is useful if you are going
to combine the output with other ByteStrings.
encodeRow :: Encode a -> EncodeOptions -> a -> ByteString Source #
Encode one row only
encodeSv :: Encode a -> EncodeOptions -> Maybe (NonEmpty ByteString) -> [a] -> Sv ByteString Source #
Build an Sv rather than going straight to ByteString. This allows you
to query the Sv or run sanity checks.
module Data.Sv.Encode.Type
module Data.Sv.Encode.Options
Core data types
module Data.Sv.Syntax
Re-exports from contravariant and semigroupoids
class Functor f => Alt (f :: * -> *) where #
Laws:
<!> is associative: (a <!> b) <!> c = a <!> (b <!> c) <$> left-distributes over <!>: f <$> (a <!> b) = (f <$> a) <!> (f <$> b)
If extended to an Alternative then <!> should equal <|>.
Ideally, an instance of Alt also satisfies the "left distributon" law of
MonadPlus with respect to <.>:
<.> right-distributes over <!>: (a <!> b) <.> c = (a <.> c) <!> (b <.> c)
But Maybe, IO, Either aErrorT e mSTM satisfy the alternative
"left catch" law instead:
pure a <!> b = pure a
However, this variation cannot be stated purely in terms of the dependencies of Alt.
When and if MonadPlus is successfully refactored, this class should also be refactored to remove these instances.
The right distributive law should extend in the cases where the a Bind or Monad is
provided to yield variations of the right distributive law:
(m <!> n) >>- f = (m >>- f) <!> (m >>- f) (m <!> n) >>= f = (m >>= f) <!> (m >>= f)
Minimal complete definition
Methods
(<!>) :: f a -> f a -> f a infixl 3 #
<|> without a required empty
some :: Applicative f => f a -> f [a] #
many :: Applicative f => f a -> f [a] #
Instances
| Alt [] | |
| Alt Maybe | |
| Alt IO | This instance does not actually satisfy the ( |
| Alt Option | |
| Alt NonEmpty | |
| Alt IntMap | |
| Alt Seq | |
| Alt (Either a) | |
| Alt (V1 *) | |
| Alt (U1 *) | |
| MonadPlus m => Alt (WrappedMonad m) | |
| Alt (Proxy *) | |
| Ord k => Alt (Map k) | |
| Alt (Alt f) | |
| Alt f => Alt (Yoneda f) | |
| Alt (ReifiedFold s) | |
| Apply f => Alt (ListT f) | |
| Alternative f => Alt (WrappedApplicative f) | |
| Alt f => Alt (Lift f) | |
| (Bind f, Monad f) => Alt (MaybeT f) | |
| Alt (Validation err) | |
| Alt f => Alt (Rec1 * f) | |
| ArrowPlus a => Alt (WrappedArrow a b) | |
| Alt f => Alt (IdentityT * f) | |
| (Bind f, Monad f, Semigroup e) => Alt (ExceptT e f) | |
| (Bind f, Monad f) => Alt (ErrorT e f) | |
| Alt f => Alt (Backwards * f) | |
| Alt (ReifiedIndexedFold i s) | |
| Alt f => Alt (StateT e f) | |
| Alt f => Alt (StateT e f) | |
| Alt f => Alt (WriterT w f) | |
| Alt f => Alt (WriterT w f) | |
| Alt f => Alt (Static f a) | |
| Alt f => Alt (Reverse * f) | |
| Alt (Decode e s) # | |
| (Alt f, Alt g) => Alt ((:*:) * f g) | |
| (Alt f, Alt g) => Alt (Product * f g) | |
| Alt f => Alt (ReaderT * e f) | |
| Alt f => Alt (M1 * i c f) | |
| (Alt f, Functor g) => Alt (Compose * * f g) | |
| Alt f => Alt (RWST r w s f) | |
| Alt f => Alt (RWST r w s f) | |
class Contravariant (f :: * -> *) where #
The class of contravariant functors.
Whereas in Haskell, one can think of a Functor as containing or producing
values, a contravariant functor is a functor that can be thought of as
consuming values.
As an example, consider the type of predicate functions a -> Bool. One
such predicate might be negative x = x < 0, which
classifies integers as to whether they are negative. However, given this
predicate, we can re-use it in other situations, providing we have a way to
map values to integers. For instance, we can use the negative predicate
on a person's bank balance to work out if they are currently overdrawn:
newtype Predicate a = Predicate { getPredicate :: a -> Bool }
instance Contravariant Predicate where
contramap f (Predicate p) = Predicate (p . f)
| `- First, map the input...
`----- then apply the predicate.
overdrawn :: Predicate Person
overdrawn = contramap personBankBalance negative
Any instance should be subject to the following laws:
contramap id = id contramap f . contramap g = contramap (g . f)
Note, that the second law follows from the free theorem of the type of
contramap and the first law, so you need only check that the former
condition holds.
Minimal complete definition
Instances
class Contravariant f => Divisible (f :: * -> *) where #
A Divisible contravariant functor is the contravariant analogue of Applicative.
Continuing the intuition that Contravariant functors consume input, a Divisible
contravariant functor also has the ability to be composed "beside" another contravariant
functor.
Serializers provide a good example of Divisible contravariant functors. To begin
let's start with the type of serializers for specific types:
newtype Serializer a = Serializer { runSerializer :: a -> ByteString }
This is a contravariant functor:
instance Contravariant Serializer where contramap f s = Serializer (runSerializer s . f)
That is, given a serializer for a (s :: Serializer a), and a way to turn
bs into as (a mapping f :: b -> a), we have a serializer for b:
contramap f s :: Serializer b.
Divisible gives us a way to combine two serializers that focus on different
parts of a structure. If we postulate the existance of two primitive
serializers - string :: Serializer String and int :: Serializer Int, we
would like to be able to combine these into a serializer for pairs of
Strings and Ints. How can we do this? Simply run both serializer and
combine their output!
data StringAndInt = StringAndInt String Int
stringAndInt :: Serializer StringAndInt
stringAndInt = Serializer $ (StringAndInt s i) ->
let sBytes = runSerializer string s
iBytes = runSerializer int i
in sBytes <> iBytes
divide is a generalization by also taking a contramap like function to
split any a into a pair. This conveniently allows you to target fields of
a record, for instance, by extracting the values under two fields and
combining them into a tuple.
To complete the example, here is how to write stringAndInt using a
Divisible instance:
instance Divisible Serializer where
conquer = Serializer (const mempty)
divide toBC bSerializer cSerializer = Serializer $ a ->
case toBC a of
(b, c) ->
let bBytes = runSerializer bSerializer b
cBytes = runSerializer cSerializer c
in bBytes <> cBytes
stringAndInt :: Serializer StringAndInt
stringAndInt =
divide ((StringAndInt s i) -> (s, i)) string int
Methods
divide :: (a -> (b, c)) -> f b -> f c -> f a #
Conquer acts as an identity for combining Divisible functors.
Instances
class Divisible f => Decidable (f :: * -> *) where #
A Decidable contravariant functor is the contravariant analogue of Alternative.
Noting the superclass constraint that f must also be Divisible, a Decidable
functor has the ability to "fan out" input, under the intuition that contravariant
functors consume input.
In the dicussion for Divisible, an example was demonstrated with Serializers,
that turn as into ByteStrings. Divisible allowed us to serialize the product
of multiple values by concatenation. By making our Serializer also Decidable-
we now have the ability to serialize the sum of multiple values - for example
different constructors in an ADT.
Consider serializing arbitrary identifiers that can be either Strings or Ints:
data Identifier = StringId String | IntId Int
We know we have serializers for Strings and Ints, but how do we combine them
into a Serializer for Identifier? Essentially, our Serializer needs to
scrutinise the incoming value and choose how to serialize it:
identifier :: Serializer Identifier
identifier = Serializer $ identifier ->
case identifier of
StringId s -> runSerializer string s
IntId i -> runSerializer int i
It is exactly this notion of choice that Decidable encodes. Hence if we add
an instance of Decidable for Serializer...
instance Decidable Serializer where
lose f = Serializer $ a -> absurd (f a)
choose split l r = Serializer $ a ->
either (runSerializer l) (runSerializer r) (split a)
Then our identifier Serializer is
identifier :: Serializer Identifier identifier = choose toEither string int where toEither (StringId s) = Left s toEither (IntId i) = Right i
Methods
Acts as identity to choose.
Instances