| Copyright | (C) CSIRO 2017-2019 |
|---|---|
| License | BSD3 |
| Maintainer | George Wilson <george.wilson@data61.csiro.au> |
| Stability | experimental |
| Portability | non-portable |
| Safe Haskell | None |
| Language | Haskell2010 |
Data.Sv
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
Synopsis
- parseDecode :: Decode' ByteString a -> ParseOptions -> ByteString -> DecodeValidation ByteString [a]
- parseDecodeFromFile :: MonadIO m => Decode' ByteString a -> ParseOptions -> FilePath -> m (DecodeValidation ByteString [a])
- parseDecodeFromDsvCursor :: Decode' ByteString a -> ParseOptions -> DsvCursor -> DecodeValidation ByteString [a]
- parseDecodeNamed :: NameDecode' ByteString a -> ParseOptions -> ByteString -> DecodeValidation ByteString [a]
- parseDecodeNamedFromFile :: MonadIO m => NameDecode' ByteString a -> ParseOptions -> FilePath -> m (DecodeValidation ByteString [a])
- parseDecodeNamedFromDsvCursor :: NameDecode' ByteString a -> ParseOptions -> DsvCursor -> DecodeValidation ByteString [a]
- decode :: Traversable f => Decode' ByteString a -> f (Vector ByteString) -> DecodeValidation ByteString (f 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
- (.:) :: Ord s => s -> Decode' s a -> NameDecode' 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.Parse
- module Data.Sv.Decode.Type
- module Data.Sv.Decode.Error
- 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
- encodeNamed :: NameEncode a -> EncodeOptions -> [a] -> ByteString
- encodeNamedToFile :: NameEncode a -> EncodeOptions -> [a] -> FilePath -> IO ()
- encodeNamedToHandle :: NameEncode a -> EncodeOptions -> [a] -> Handle -> IO ()
- encodeNamedBuilder :: NameEncode a -> EncodeOptions -> [a] -> Builder
- encodeRow :: Encode a -> EncodeOptions -> a -> ByteString
- (=:) :: Builder -> Encode a -> NameEncode a
- module Data.Sv.Encode.Type
- module Data.Sv.Encode.Options
- module Data.Sv.Structure
- class Functor f => Alt (f :: Type -> Type) where
- (<!>) :: f a -> f a -> f a
- some :: Applicative f => f a -> f [a]
- many :: Applicative f => f a -> f [a]
- class Contravariant (f :: Type -> Type) where
- class Contravariant f => Divisible (f :: Type -> Type) where
- divided :: Divisible f => f a -> f b -> f (a, b)
- class Divisible f => Decidable (f :: Type -> Type) where
- chosen :: Decidable f => f b -> f c -> f (Either b c)
- data Validation err a
Decoding
parseDecode :: Decode' ByteString a -> ParseOptions -> ByteString -> DecodeValidation ByteString [a] Source #
Parse a ByteString as an Sv, and then decode it with the given decoder.
parseDecodeFromFile :: MonadIO m => Decode' ByteString a -> ParseOptions -> FilePath -> m (DecodeValidation ByteString [a]) Source #
Load a file, parse it, and decode it.
parseDecodeFromDsvCursor :: Decode' ByteString a -> ParseOptions -> DsvCursor -> DecodeValidation ByteString [a] Source #
Decode from a DsvCursor
parseDecodeNamed :: NameDecode' ByteString a -> ParseOptions -> ByteString -> DecodeValidation ByteString [a] Source #
Parse a ByteString as an Sv, and then decode it with the given colum
based decoder.
parseDecodeNamedFromFile :: MonadIO m => NameDecode' ByteString a -> ParseOptions -> FilePath -> m (DecodeValidation ByteString [a]) Source #
Load a file, parse it, and decode it by column.
parseDecodeNamedFromDsvCursor :: NameDecode' ByteString a -> ParseOptions -> DsvCursor -> DecodeValidation ByteString [a] Source #
Decode from a DsvCursor
decode :: Traversable f => Decode' ByteString a -> f (Vector ByteString) -> DecodeValidation ByteString (f a) #
Decodes a sv into a list of its values using the provided Decode
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 #
(.:) :: Ord s => s -> Decode' s a -> NameDecode' s a infixl 5 #
Infix alias for column
Mnemonic: Dot colon names Decoders, Equal colon names Encoders.
(>>==) :: Decode e s a -> (a -> DecodeValidation e b) -> Decode e s b infixl 1 #
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.Parse
module Data.Sv.Decode.Type
module Data.Sv.Decode.Error
Encoding
encode :: Encode a -> EncodeOptions -> [a] -> ByteString #
Encode the given list using the given Encode, configured by the given
EncodeOptions.
encodeToFile :: Encode a -> EncodeOptions -> [a] -> FilePath -> IO () #
Encode, writing to a file. This way is more efficient than encoding to
a ByteString and then writing to file.
encodeToHandle :: Encode a -> EncodeOptions -> [a] -> Handle -> IO () #
Encode, writing the output to a file handle.
encodeBuilder :: Encode a -> EncodeOptions -> [a] -> Builder #
Encode to a ByteString Builder, which is useful if you are going
to combine the output with other ByteStrings.
encodeNamed :: NameEncode a -> EncodeOptions -> [a] -> ByteString #
Encode the given list with a header using the given NameEncode,
configured by the given EncodeOptions.
encodeNamedToFile :: NameEncode a -> EncodeOptions -> [a] -> FilePath -> IO () #
Encode with a header, writing to a file. This way is more efficient
than encoding to a ByteString and then writing to file.
encodeNamedToHandle :: NameEncode a -> EncodeOptions -> [a] -> Handle -> IO () #
Encode with a header, writing the output to a file handle.
encodeNamedBuilder :: NameEncode a -> EncodeOptions -> [a] -> Builder #
Encode with column names to a ByteString Builder, which is useful
if you are going to combine the output with other ByteStrings.
encodeRow :: Encode a -> EncodeOptions -> a -> ByteString #
Encode one row only
(=:) :: Builder -> Encode a -> NameEncode a #
Synonym for named.
Mnemonic: Dot colon names Decoders, Equal colon names Encoders.
module Data.Sv.Encode.Type
module Data.Sv.Encode.Options
Structure
module Data.Sv.Structure
Re-exports from contravariant, validation, and semigroupoids
class Functor f => Alt (f :: Type -> Type) 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
class Contravariant (f :: Type -> Type) 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 :: Type -> Type) 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 :: Type -> Type) 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
data Validation err a #
An Validation is either a value of the type err or a, similar to Either. However,
the Applicative instance for Validation accumulates errors using a Semigroup on err.
In contrast, the Applicative for Either returns only the first error.
A consequence of this is that Validation has no Bind or Monad instance. This is because
such an instance would violate the law that a Monad's ap must equal the
Applicative's <*>
An example of typical usage can be found here.
Instances
| Bitraversable Validation | |
Defined in Data.Validation Methods bitraverse :: Applicative f => (a -> f c) -> (b -> f d) -> Validation a b -> f (Validation c d) # | |
| Bifoldable Validation | |
Defined in Data.Validation Methods bifold :: Monoid m => Validation m m -> m # bifoldMap :: Monoid m => (a -> m) -> (b -> m) -> Validation a b -> m # bifoldr :: (a -> c -> c) -> (b -> c -> c) -> c -> Validation a b -> c # bifoldl :: (c -> a -> c) -> (c -> b -> c) -> c -> Validation a b -> c # | |
| Bifunctor Validation | |
Defined in Data.Validation Methods bimap :: (a -> b) -> (c -> d) -> Validation a c -> Validation b d # first :: (a -> b) -> Validation a c -> Validation b c # second :: (b -> c) -> Validation a b -> Validation a c # | |
| Swapped Validation | |
Defined in Data.Validation Methods swapped :: Iso (Validation a b) (Validation c d) (Validation b a) (Validation d c) # | |
| Validate Validation | |
Defined in Data.Validation Methods _Validation :: Iso (Validation e a) (Validation g b) (Validation e a) (Validation g b) # _Either :: Iso (Validation e a) (Validation g b) (Either e a) (Either g b) # | |
| Functor (Validation err) | |
Defined in Data.Validation Methods fmap :: (a -> b) -> Validation err a -> Validation err b # (<$) :: a -> Validation err b -> Validation err a # | |
| Semigroup err => Applicative (Validation err) | |
Defined in Data.Validation Methods pure :: a -> Validation err a # (<*>) :: Validation err (a -> b) -> Validation err a -> Validation err b # liftA2 :: (a -> b -> c) -> Validation err a -> Validation err b -> Validation err c # (*>) :: Validation err a -> Validation err b -> Validation err b # (<*) :: Validation err a -> Validation err b -> Validation err a # | |
| Foldable (Validation err) | |
Defined in Data.Validation Methods fold :: Monoid m => Validation err m -> m # foldMap :: Monoid m => (a -> m) -> Validation err a -> m # foldr :: (a -> b -> b) -> b -> Validation err a -> b # foldr' :: (a -> b -> b) -> b -> Validation err a -> b # foldl :: (b -> a -> b) -> b -> Validation err a -> b # foldl' :: (b -> a -> b) -> b -> Validation err a -> b # foldr1 :: (a -> a -> a) -> Validation err a -> a # foldl1 :: (a -> a -> a) -> Validation err a -> a # toList :: Validation err a -> [a] # null :: Validation err a -> Bool # length :: Validation err a -> Int # elem :: Eq a => a -> Validation err a -> Bool # maximum :: Ord a => Validation err a -> a # minimum :: Ord a => Validation err a -> a # sum :: Num a => Validation err a -> a # product :: Num a => Validation err a -> a # | |
| Traversable (Validation err) | |
Defined in Data.Validation Methods traverse :: Applicative f => (a -> f b) -> Validation err a -> f (Validation err b) # sequenceA :: Applicative f => Validation err (f a) -> f (Validation err a) # mapM :: Monad m => (a -> m b) -> Validation err a -> m (Validation err b) # sequence :: Monad m => Validation err (m a) -> m (Validation err a) # | |
| Semigroup err => Apply (Validation err) | |
Defined in Data.Validation Methods (<.>) :: Validation err (a -> b) -> Validation err a -> Validation err b # (.>) :: Validation err a -> Validation err b -> Validation err b # (<.) :: Validation err a -> Validation err b -> Validation err a # liftF2 :: (a -> b -> c) -> Validation err a -> Validation err b -> Validation err c # | |
| Alt (Validation err) | |
Defined in Data.Validation Methods (<!>) :: Validation err a -> Validation err a -> Validation err a # some :: Applicative (Validation err) => Validation err a -> Validation err [a] # many :: Applicative (Validation err) => Validation err a -> Validation err [a] # | |
| (Eq err, Eq a) => Eq (Validation err a) | |
Defined in Data.Validation Methods (==) :: Validation err a -> Validation err a -> Bool # (/=) :: Validation err a -> Validation err a -> Bool # | |
| (Data err, Data a) => Data (Validation err a) | |
Defined in Data.Validation Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Validation err a -> c (Validation err a) # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c (Validation err a) # toConstr :: Validation err a -> Constr # dataTypeOf :: Validation err a -> DataType # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c (Validation err a)) # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c (Validation err a)) # gmapT :: (forall b. Data b => b -> b) -> Validation err a -> Validation err a # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Validation err a -> r # gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Validation err a -> r # gmapQ :: (forall d. Data d => d -> u) -> Validation err a -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> Validation err a -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> Validation err a -> m (Validation err a) # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Validation err a -> m (Validation err a) # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Validation err a -> m (Validation err a) # | |
| (Ord err, Ord a) => Ord (Validation err a) | |
Defined in Data.Validation Methods compare :: Validation err a -> Validation err a -> Ordering # (<) :: Validation err a -> Validation err a -> Bool # (<=) :: Validation err a -> Validation err a -> Bool # (>) :: Validation err a -> Validation err a -> Bool # (>=) :: Validation err a -> Validation err a -> Bool # max :: Validation err a -> Validation err a -> Validation err a # min :: Validation err a -> Validation err a -> Validation err a # | |
| (Show err, Show a) => Show (Validation err a) | |
Defined in Data.Validation Methods showsPrec :: Int -> Validation err a -> ShowS # show :: Validation err a -> String # showList :: [Validation err a] -> ShowS # | |
| Generic (Validation err a) | |
Defined in Data.Validation Associated Types type Rep (Validation err a) :: Type -> Type # Methods from :: Validation err a -> Rep (Validation err a) x # to :: Rep (Validation err a) x -> Validation err a # | |
| Semigroup e => Semigroup (Validation e a) | |
Defined in Data.Validation Methods (<>) :: Validation e a -> Validation e a -> Validation e a # sconcat :: NonEmpty (Validation e a) -> Validation e a # stimes :: Integral b => b -> Validation e a -> Validation e a # | |
| Monoid e => Monoid (Validation e a) | |
Defined in Data.Validation Methods mempty :: Validation e a # mappend :: Validation e a -> Validation e a -> Validation e a # mconcat :: [Validation e a] -> Validation e a # | |
| (NFData e, NFData a) => NFData (Validation e a) | |
Defined in Data.Validation Methods rnf :: Validation e a -> () # | |
| type Rep (Validation err a) | |
Defined in Data.Validation type Rep (Validation err a) = D1 (MetaData "Validation" "Data.Validation" "validation-1-GTk8NhU1jrXDiDIOshT3OV" False) (C1 (MetaCons "Failure" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 err)) :+: C1 (MetaCons "Success" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 a))) | |