-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Vector and Text utilities -- -- Please see the README on GitHub at -- https://github.com/akashche/vt-utils#readme @package vt-utils @version 1.0.0.0 -- | Date format utilities module VtUtils.Date -- | Formats a date into a Text string using specified formatting string -- -- Arguments: -- --

format :: Text: Format string
date :: UTCTime: Date to format

-- -- Return value: String containing a date in a specified format dateFormat :: Text -> UTCTime -> Text -- | Formats a date into a Text string using ISO8601 formatting string -- -- Format: %Y-%m-%d %H:%M:%S -- -- Output example: 2018-11-25 00:00:01 -- -- Arguments: -- --

date :: UTCtime: Date to format

-- -- Return value: String containing a date in ISO8601 format dateFormatISO8601 :: UTCTime -> Text -- | Parses Text string using ISO8601 format -- -- Raises an error, if input string cannot be parsed as ISO8601 -- date -- -- Expected input example: 2018-11-25 00:00:01 -- -- Arguments: -- --

text :: Text: Text string containing a date in ISO8601 -- format

-- -- Return value: Parsed date dateParseISO8601 :: Text -> UTCTime -- | IO utilities module VtUtils.IO -- | Reads contents of a specified file as a lazy ByteString (with -- streaming) and provides it to the specified callback -- -- Throws an error if specified file cannot be read -- -- Arguments: -- --

path :: Text: path to file
fun :: (Data.ByteString.Lazy.ByteString -> IO a): -- callback to process the file data

-- -- Return value: Result of the callback invocation ioWithFileBytes :: Text -> (ByteString -> IO a) -> IO a -- | Reads contents of a specified file as a lazy Text (with -- streaming) and provides it to the specified callback -- -- File contents are decoded as UTF-8 -- -- Throws an error if specified file cannot be read -- -- Arguments: -- --

path :: Text: path to file
fun :: (Data.Text.Lazy.Text -> IO a): callback to -- process the file data

-- -- Return value: Result of the callback invocation ioWithFileText :: Text -> (Text -> IO a) -> IO a -- | JSON utilities -- -- Example of the data type, that supports JSON encoding and decoding -- with Aeson: -- --

--   data Foo = Foo
--       { foo :: Int
--       , bar :: Text
--       } deriving Generic
--   instance FromJSON Foo
--   instance ToJSON Foo
--

module VtUtils.Json -- | Parses contents of a specified JSON file into a typed data -- -- Data type should be specified with a type annotation: -- -- Example: -- --

--   dt <- jsonDecodeFile "path/to/foo.json" :: IO Foo
--

-- -- Data must be an instance of FromJSON -- -- File contents are decoded as UTF-8 -- -- Throws an error if file cannot be read or data cannot be decoded -- -- Arguments: -- --

path :: Text: Path to JSON file

-- -- Return value: Decoded data jsonDecodeFile :: forall a. FromJSON a => Text -> IO a -- | Parses a JSON Text string into a typed data -- -- Data type should be specified with a type annotation: -- -- Example: -- --

--   let dt = jsonDecodeText text :: Foo
--

-- -- Data must be an instance of FromJSON -- -- Throws an error if data cannot be decoded -- -- Arguments: -- --

text :: Text: JSON Text string to parse

-- -- Return value: Decoded data jsonDecodeText :: forall a. FromJSON a => Text -> a -- | Encodes a data into a JSON Text string -- -- Data must be an instance of ToJSON -- -- Throws an error if data cannot be encoded -- -- Arguments: -- --

data :: ToJSON: some data that supports JSON -- serialization with Aeson

-- -- Return value: JSON Text string jsonEncodeText :: ToJSON a => a -> Text -- | Extract the field value from the specified JSON object -- -- Throws an error, if specified JSON Value is not a JSON -- object, if it does't contain a specified field, if field type is -- different from the one specified in type annotation -- -- Data type should be specified with a type annotation: -- --

--   let obj = object
--           [ "foo" .= (42 :: Int)
--           , "bar" .= ("baz" :: Text)
--           ]
--   let fooval = jsonGet obj "foo" :: Int
--   let barval = jsonGet obj "bar" :: Text
--

-- -- Arguments: -- --

val :: Aeson.Value: JSON value, must be a JSON -- object
field :: Text: Field name

-- -- Return value: Field value jsonGet :: forall a. FromJSON a => Value -> Text -> a -- | HashMap utilities module VtUtils.Map -- | Lookups a key in a HashMap -- -- Throws an error if key not found in a specified HashMap -- -- Arguments: -- --

map :: HashMap Text v: Map with Text keys
key :: Text: Key to lookup

-- -- Return value: Map value that corresponds to the specified key mapGet :: HashMap Text v -> Text -> v -- | Utilities to work with FS paths module VtUtils.Path -- | Checks whether specified path is absolute -- -- Only checks the path string itself, doesn't use FS API. -- -- Arguments: -- --

path :: Text: FS path to check

-- -- Return value: True if path is absolute, False -- otherwise pathIsAbsolute :: Text -> Bool -- | Concatenates two paths -- -- Throws an error, if specified postfix is absolute -- -- Arguments: -- --

prefix :: Text: Path prefix, may be absolute
postfix :: Text: Path postfix, must not be absolute

-- -- Return value: Concatenated path pathConcat :: Text -> Text -> Text -- | Prepends an absolute prefix to the relative path -- -- Does nothing, if path is already absolute -- -- Arguments: -- --

prefix :: Text: Path prefix, must be absolute
postfix :: Text: Path postfix, may be absolute

-- -- Return value: Path with a specified prefix prepended, if path is -- relative, specified path unchanged otherwise pathPrepend :: Text -> Text -> Text -- | Filesystem utilities module VtUtils.FS -- | Copies a directory recursively -- -- Throws an exception if source directory does not exist or if -- destination path already exists -- -- Arguments: -- --

src :: Text: Source directory
dest :: Text: Destination path

fsCopyDirectory :: Text -> Text -> IO () -- | Text utilities module VtUtils.Text -- | Stringifies a specified value -- -- If input is Text, String or ByteString, it -- is returned as a Text string without additional quotes around -- it -- -- Arguments: -- --

val :: a: Value to stringify

-- -- Return value: Text string representation of a specified value textShow :: (Show a, Typeable a) => a -> Text -- | Custom Prelude module VtUtils.Prelude data Bool False :: Bool True :: Bool -- | The Either type represents values with two possibilities: a -- value of type Either a b is either Left -- a or Right b. -- -- The Either type is sometimes used to represent a value which is -- either correct or an error; by convention, the Left constructor -- is used to hold an error value and the Right constructor is -- used to hold a correct value (mnemonic: "right" also means "correct"). -- --

Examples

-- -- The type Either String Int is the type -- of values which can be either a String or an Int. The -- Left constructor can be used only on Strings, and the -- Right constructor can be used only on Ints: -- --

--   >>> let s = Left "foo" :: Either String Int
--   
--   >>> s
--   Left "foo"
--   
--   >>> let n = Right 3 :: Either String Int
--   
--   >>> n
--   Right 3
--   
--   >>> :type s
--   s :: Either String Int
--   
--   >>> :type n
--   n :: Either String Int
--

-- -- The fmap from our Functor instance will ignore -- Left values, but will apply the supplied function to values -- contained in a Right: -- --

--   >>> let s = Left "foo" :: Either String Int
--   
--   >>> let n = Right 3 :: Either String Int
--   
--   >>> fmap (*2) s
--   Left "foo"
--   
--   >>> fmap (*2) n
--   Right 6
--

-- -- The Monad instance for Either allows us to chain -- together multiple actions which may fail, and fail overall if any of -- the individual steps failed. First we'll write a function that can -- either parse an Int from a Char, or fail. -- --

--   >>> import Data.Char ( digitToInt, isDigit )
--   
--   >>> :{
--       let parseEither :: Char -> Either String Int
--           parseEither c
--             | isDigit c = Right (digitToInt c)
--             | otherwise = Left "parse error"
--   
--   >>> :}
--

-- -- The following should work, since both '1' and '2' -- can be parsed as Ints. -- --

--   >>> :{
--       let parseMultiple :: Either String Int
--           parseMultiple = do
--             x <- parseEither '1'
--             y <- parseEither '2'
--             return (x + y)
--   
--   >>> :}
--

-- --

--   >>> parseMultiple
--   Right 3
--

-- -- But the following should fail overall, since the first operation where -- we attempt to parse 'm' as an Int will fail: -- --

--   >>> :{
--       let parseMultiple :: Either String Int
--           parseMultiple = do
--             x <- parseEither 'm'
--             y <- parseEither '2'
--             return (x + y)
--   
--   >>> :}
--

-- --

--   >>> parseMultiple
--   Left "parse error"
--

data Either a b Left :: a -> Either a b Right :: b -> Either a b -- | The Eq class defines equality (==) and inequality -- (/=). All the basic datatypes exported by the Prelude -- are instances of Eq, and Eq may be derived for any -- datatype whose constituents are also instances of Eq. -- -- The Haskell Report defines no laws for Eq. However, == -- is customarily expected to implement an equivalence relationship where -- two values comparing equal are indistinguishable by "public" -- functions, with a "public" function being one not allowing to see -- implementation details. For example, for a type representing -- non-normalised natural numbers modulo 100, a "public" function doesn't -- make the difference between 1 and 201. It is expected to have the -- following properties: -- --

Reflexivity x == x = True
Symmetry x == y = y == x
Transitivity if x == y && y == z = -- True, then x == z = True
Substitutivity if x == y = True and -- f is a "public" function whose return type is an instance of -- Eq, then f x == f y = True
Negation x /= y = not (x == -- y)

-- -- Minimal complete definition: either == or /=. class Eq a -- | A fixed-precision integer type with at least the range [-2^29 .. -- 2^29-1]. The exact range for a given implementation can be -- determined by using minBound and maxBound from the -- Bounded class. data Int -- | A value of type IO a is a computation which, when -- performed, does some I/O before returning a value of type a. -- -- There is really only one way to "perform" an I/O action: bind it to -- Main.main in your program. When your program is run, the I/O -- will be performed. It isn't possible to perform I/O from an arbitrary -- function, unless that function is itself in the IO monad and -- called at some point, directly or indirectly, from Main.main. -- -- IO is a monad, so IO actions can be combined using -- either the do-notation or the >> and >>= -- operations from the Monad class. data IO a -- | The Maybe type encapsulates an optional value. A value of type -- Maybe a either contains a value of type a -- (represented as Just a), or it is empty (represented -- as Nothing). Using Maybe is a good way to deal with -- errors or exceptional cases without resorting to drastic measures such -- as error. -- -- The Maybe type is also a monad. It is a simple kind of error -- monad, where all errors are represented by Nothing. A richer -- error monad can be built using the Either type. data Maybe a Nothing :: Maybe a Just :: a -> Maybe a -- | Parsing of Strings, producing values. -- -- Derived instances of Read make the following assumptions, which -- derived instances of Show obey: -- --

If the constructor is defined to be an infix operator, then the -- derived Read instance will parse only infix applications of the -- constructor (not the prefix form).
Associativity is not used to reduce the occurrence of parentheses, -- although precedence may be.
If the constructor is defined using record syntax, the derived -- Read will parse only the record-syntax form, and furthermore, -- the fields must be given in the same order as the original -- declaration.
The derived Read instance allows arbitrary Haskell -- whitespace between tokens of the input string. Extra parentheses are -- also allowed.

-- -- For example, given the declarations -- --

--   infixr 5 :^:
--   data Tree a =  Leaf a  |  Tree a :^: Tree a
--

-- -- the derived instance of Read in Haskell 2010 is equivalent to -- --

--   instance (Read a) => Read (Tree a) where
--   
--           readsPrec d r =  readParen (d > app_prec)
--                            (\r -> [(Leaf m,t) |
--                                    ("Leaf",s) <- lex r,
--                                    (m,t) <- readsPrec (app_prec+1) s]) r
--   
--                         ++ readParen (d > up_prec)
--                            (\r -> [(u:^:v,w) |
--                                    (u,s) <- readsPrec (up_prec+1) r,
--                                    (":^:",t) <- lex s,
--                                    (v,w) <- readsPrec (up_prec+1) t]) r
--   
--             where app_prec = 10
--                   up_prec = 5
--

-- -- Note that right-associativity of :^: is unused. -- -- The derived instance in GHC is equivalent to -- --

--   instance (Read a) => Read (Tree a) where
--   
--           readPrec = parens $ (prec app_prec $ do
--                                    Ident "Leaf" <- lexP
--                                    m <- step readPrec
--                                    return (Leaf m))
--   
--                        +++ (prec up_prec $ do
--                                    u <- step readPrec
--                                    Symbol ":^:" <- lexP
--                                    v <- step readPrec
--                                    return (u :^: v))
--   
--             where app_prec = 10
--                   up_prec = 5
--   
--           readListPrec = readListPrecDefault
--

-- -- Why do both readsPrec and readPrec exist, and why does -- GHC opt to implement readPrec in derived Read instances -- instead of readsPrec? The reason is that readsPrec is -- based on the ReadS type, and although ReadS is mentioned -- in the Haskell 2010 Report, it is not a very efficient parser data -- structure. -- -- readPrec, on the other hand, is based on a much more efficient -- ReadPrec datatype (a.k.a "new-style parsers"), but its -- definition relies on the use of the RankNTypes language -- extension. Therefore, readPrec (and its cousin, -- readListPrec) are marked as GHC-only. Nevertheless, it is -- recommended to use readPrec instead of readsPrec -- whenever possible for the efficiency improvements it brings. -- -- As mentioned above, derived Read instances in GHC will -- implement readPrec instead of readsPrec. The default -- implementations of readsPrec (and its cousin, readList) -- will simply use readPrec under the hood. If you are writing a -- Read instance by hand, it is recommended to write it like so: -- --

--   instance Read T where
--     readPrec     = ...
--     readListPrec = readListPrecDefault
--

class Read a -- | Conversion of values to readable Strings. -- -- Derived instances of Show have the following properties, which -- are compatible with derived instances of Read: -- --

The result of show is a syntactically correct Haskell -- expression containing only constants, given the fixity declarations in -- force at the point where the type is declared. It contains only the -- constructor names defined in the data type, parentheses, and spaces. -- When labelled constructor fields are used, braces, commas, field -- names, and equal signs are also used.
If the constructor is defined to be an infix operator, then -- showsPrec will produce infix applications of the -- constructor.
the representation will be enclosed in parentheses if the -- precedence of the top-level constructor in x is less than -- d (associativity is ignored). Thus, if d is -- 0 then the result is never surrounded in parentheses; if -- d is 11 it is always surrounded in parentheses, -- unless it is an atomic expression.
If the constructor is defined using record syntax, then -- show will produce the record-syntax form, with the fields given -- in the same order as the original declaration.

-- -- For example, given the declarations -- --

--   infixr 5 :^:
--   data Tree a =  Leaf a  |  Tree a :^: Tree a
--

-- -- the derived instance of Show is equivalent to -- --

--   instance (Show a) => Show (Tree a) where
--   
--          showsPrec d (Leaf m) = showParen (d > app_prec) $
--               showString "Leaf " . showsPrec (app_prec+1) m
--            where app_prec = 10
--   
--          showsPrec d (u :^: v) = showParen (d > up_prec) $
--               showsPrec (up_prec+1) u .
--               showString " :^: "      .
--               showsPrec (up_prec+1) v
--            where up_prec = 5
--

-- -- Note that right-associativity of :^: is ignored. For example, -- --

show (Leaf 1 :^: Leaf 2 :^: Leaf 3) produces the -- string "Leaf 1 :^: (Leaf 2 :^: Leaf 3)".

class Show a -- | A String is a list of characters. String constants in Haskell -- are values of type String. type String = [Char] (+) :: Num a => a -> a -> a infixl 6 + (-) :: Num a => a -> a -> a infixl 6 - (*) :: Num a => a -> a -> a infixl 7 * -- | fractional division (/) :: Fractional a => a -> a -> a infixl 7 / (>) :: Ord a => a -> a -> Bool infix 4 > (>=) :: Ord a => a -> a -> Bool infix 4 >= (<) :: Ord a => a -> a -> Bool infix 4 < (<=) :: Ord a => a -> a -> Bool infix 4 <= (==) :: Eq a => a -> a -> Bool infix 4 == (/=) :: Eq a => a -> a -> Bool infix 4 /= -- | Function composition. (.) :: () => (b -> c) -> (a -> b) -> a -> c infixr 9 . -- | Application operator. This operator is redundant, since ordinary -- application (f x) means the same as (f $ x). -- However, $ has low, right-associative binding precedence, so it -- sometimes allows parentheses to be omitted; for example: -- --

--   f $ g $ h x  =  f (g (h x))
--

-- -- It is also useful in higher-order situations, such as map -- ($ 0) xs, or zipWith ($) fs xs. -- -- Note that ($) is levity-polymorphic in its result type, so -- that foo $ True where foo :: Bool -> Int# is well-typed ($) :: () => (a -> b) -> a -> b infixr 0 $ -- | Strict (call-by-value) application operator. It takes a function and -- an argument, evaluates the argument to weak head normal form (WHNF), -- then calls the function with that value. ($!) :: () => (a -> b) -> a -> b infixr 0 $! -- | Sequentially compose two actions, discarding any value produced by the -- first, like sequencing operators (such as the semicolon) in imperative -- languages. (>>) :: Monad m => m a -> m b -> m b infixl 1 >> -- | Sequentially compose two actions, passing any value produced by the -- first as an argument to the second. (>>=) :: Monad m => m a -> (a -> m b) -> m b infixl 1 >>= -- | Boolean "and" (&&) :: Bool -> Bool -> Bool infixr 3 && -- | Boolean "or" (||) :: Bool -> Bool -> Bool infixr 2 || -- | An infix synonym for fmap. -- -- The name of this operator is an allusion to $. Note the -- similarities between their types: -- --

--    ($)  ::              (a -> b) ->   a ->   b
--   (<$>) :: Functor f => (a -> b) -> f a -> f b
--

-- -- Whereas $ is function application, <$> is -- function application lifted over a Functor. -- --

Examples

-- -- Convert from a Maybe Int to a -- Maybe String using show: -- --

--   >>> show <$> Nothing
--   Nothing
--   
--   >>> show <$> Just 3
--   Just "3"
--

-- -- Convert from an Either Int Int to -- an Either Int String using -- show: -- --

--   >>> show <$> Left 17
--   Left 17
--   
--   >>> show <$> Right 17
--   Right "17"
--

-- -- Double each element of a list: -- --

--   >>> (*2) <$> [1,2,3]
--   [2,4,6]
--

-- -- Apply even to the second element of a pair: -- --

--   >>> even <$> (2,2)
--   (2,True)
--

(<$>) :: Functor f => (a -> b) -> f a -> f b infixl 4 <$> -- | Sequential application. -- -- A few functors support an implementation of <*> that is -- more efficient than the default one. (<*>) :: Applicative f => f (a -> b) -> f a -> f b infixl 4 <*> -- | Absolute value. abs :: Num a => a -> a -- | integer division truncated toward negative infinity div :: Integral a => a -> a -> a infixl 7 `div` -- | error stops execution and displays an error message. error :: HasCallStack => [Char] -> a -- | flip f takes its (first) two arguments in the reverse -- order of f. -- --

--   >>> flip (++) "hello" "world"
--   "worldhello"
--

flip :: () => (a -> b -> c) -> b -> a -> c fmap :: Functor f => (a -> b) -> f a -> f b -- | general coercion from integral types fromIntegral :: (Integral a, Num b) => a -> b -- | Identity function. -- --

--   id x = x
--

id :: () => a -> a -- | Map each element of a structure to a monadic action, evaluate these -- actions from left to right, and collect the results. For a version -- that ignores the results see mapM_. mapM :: (Traversable t, Monad m) => (a -> m b) -> t a -> m (t b) -- | Map each element of a structure to a monadic action, evaluate these -- actions from left to right, and ignore the results. For a version that -- doesn't ignore the results see mapM. -- -- As of base 4.8.0.0, mapM_ is just traverse_, specialized -- to Monad. mapM_ :: (Foldable t, Monad m) => (a -> m b) -> t a -> m () -- | integer modulus, satisfying -- --

--   (x `div` y)*y + (x `mod` y) == x
--

mod :: Integral a => a -> a -> a infixl 7 `mod` -- | Boolean "not" not :: Bool -> Bool -- | otherwise is defined as the value True. It helps to make -- guards more readable. eg. -- --

--   f x | x < 0     = ...
--       | otherwise = ...
--

otherwise :: Bool -- | Lift a value. pure :: Applicative f => a -> f a -- | The read function reads input from a string, which must be -- completely consumed by the input process. read fails with an -- error if the parse is unsuccessful, and it is therefore -- discouraged from being used in real applications. Use readMaybe -- or readEither for safe alternatives. -- --

--   >>> read "123" :: Int
--   123
--

-- --

--   >>> read "hello" :: Int
--   *** Exception: Prelude.read: no parse
--

read :: Read a => String -> a -- | Inject a value into the monadic type. return :: Monad m => a -> m a -- | The value of seq a b is bottom if a is bottom, and -- otherwise equal to b. In other words, it evaluates the first -- argument a to weak head normal form (WHNF). seq is -- usually introduced to improve performance by avoiding unneeded -- laziness. -- -- A note on evaluation order: the expression seq a b does -- not guarantee that a will be evaluated before -- b. The only guarantee given by seq is that the both -- a and b will be evaluated before seq -- returns a value. In particular, this means that b may be -- evaluated before a. If you need to guarantee a specific order -- of evaluation, you must use the function pseq from the -- "parallel" package. seq :: () => a -> b -> b -- | Evaluate each monadic action in the structure from left to right, and -- collect the results. For a version that ignores the results see -- sequence_. sequence :: (Traversable t, Monad m) => t (m a) -> m (t a) -- | Evaluate each monadic action in the structure from left to right, and -- ignore the results. For a version that doesn't ignore the results see -- sequence. -- -- As of base 4.8.0.0, sequence_ is just sequenceA_, -- specialized to Monad. sequence_ :: (Foldable t, Monad m) => t (m a) -> m () -- | A specialised variant of showsPrec, using precedence context -- zero, and returning an ordinary String. show :: Show a => a -> String -- | A special case of error. It is expected that compilers will -- recognize this and insert error messages which are more appropriate to -- the context in which undefined appears. undefined :: HasCallStack => a -- | The SomeException type is the root of the exception type -- hierarchy. When an exception of type e is thrown, behind the -- scenes it is encapsulated in a SomeException. data SomeException -- | When you want to acquire a resource, do some work with it, and then -- release the resource, it is a good idea to use bracket, because -- bracket will install the necessary exception handler to release -- the resource in the event that an exception is raised during the -- computation. If an exception is raised, then bracket will -- re-raise the exception (after performing the release). -- -- A common example is opening a file: -- --

--   bracket
--     (openFile "filename" ReadMode)
--     (hClose)
--     (\fileHandle -> do { ... })
--

-- -- The arguments to bracket are in this order so that we can -- partially apply it, e.g.: -- --

--   withFile name mode = bracket (openFile name mode) hClose
--

bracket :: () => IO a -> (a -> IO b) -> (a -> IO c) -> IO c -- | A variant of bracket where the return value from the first -- computation is not required. bracket_ :: () => IO a -> IO b -> IO c -> IO c -- | Throw an exception. Exceptions may be thrown from purely functional -- code, but may only be caught within the IO monad. throw :: Exception e => e -> a -- | Similar to catch, but returns an Either result which is -- (Right a) if no exception of type e was -- raised, or (Left ex) if an exception of type -- e was raised and its value is ex. If any other type -- of exception is raised than it will be propogated up to the next -- enclosing exception handler. -- --

--   try a = catch (Right `liftM` a) (return . Left)
--

try :: Exception e => IO a -> IO (Either e a) -- | forM is mapM with its arguments flipped. For a version -- that ignores the results see forM_. forM :: (Traversable t, Monad m) => t a -> (a -> m b) -> m (t b) -- | forM_ is mapM_ with its arguments flipped. For a version -- that doesn't ignore the results see forM. -- -- As of base 4.8.0.0, forM_ is just for_, specialized to -- Monad. forM_ :: (Foldable t, Monad m) => t a -> (a -> m b) -> m () -- | The reverse of when. unless :: Applicative f => Bool -> f () -> f () -- | Conditional execution of Applicative expressions. For example, -- --

--   when debug (putStrLn "Debugging")
--

-- -- will output the string Debugging if the Boolean value -- debug is True, and otherwise do nothing. when :: Applicative f => Bool -> f () -> f () -- | Return the value computed by a state transformer computation. The -- forall ensures that the internal state used by the ST -- computation is inaccessible to the rest of the program. runST :: () => (forall s. () => ST s a) -> a -- | A type that can be converted from JSON, with the possibility of -- failure. -- -- In many cases, you can get the compiler to generate parsing code for -- you (see below). To begin, let's cover writing an instance by hand. -- -- There are various reasons a conversion could fail. For example, an -- Object could be missing a required key, an Array could -- be of the wrong size, or a value could be of an incompatible type. -- -- The basic ways to signal a failed conversion are as follows: -- --

empty and mzero work, but are terse and -- uninformative;
fail yields a custom error message;
typeMismatch produces an informative message for cases when -- the value encountered is not of the expected type.

-- -- An example type and instance using typeMismatch: -- --

--   -- Allow ourselves to write Text literals.
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   data Coord = Coord { x :: Double, y :: Double }
--   
--   instance FromJSON Coord where
--       parseJSON (Object v) = Coord
--           <$> v .: "x"
--           <*> v .: "y"
--   
--       -- We do not expect a non-Object value here.
--       -- We could use mzero to fail, but typeMismatch
--       -- gives a much more informative error message.
--       parseJSON invalid    = typeMismatch "Coord" invalid
--

-- -- For this common case of only being concerned with a single type of -- JSON value, the functions withObject, withNumber, etc. -- are provided. Their use is to be preferred when possible, since they -- are more terse. Using withObject, we can rewrite the above -- instance (assuming the same language extension and data type) as: -- --

--   instance FromJSON Coord where
--       parseJSON = withObject "Coord" $ \v -> Coord
--           <$> v .: "x"
--           <*> v .: "y"
--

-- -- Instead of manually writing your FromJSON instance, there are -- two options to do it automatically: -- --

Data.Aeson.TH provides Template Haskell functions which -- will derive an instance at compile time. The generated instance is -- optimized for your type so it will probably be more efficient than the -- following option.
The compiler can provide a default generic implementation for -- parseJSON.

-- -- To use the second, simply add a deriving Generic -- clause to your datatype and declare a FromJSON instance for -- your datatype without giving a definition for parseJSON. -- -- For example, the previous example can be simplified to just: -- --

--   {-# LANGUAGE DeriveGeneric #-}
--   
--   import GHC.Generics
--   
--   data Coord = Coord { x :: Double, y :: Double } deriving Generic
--   
--   instance FromJSON Coord
--

-- -- The default implementation will be equivalent to parseJSON = -- genericParseJSON defaultOptions; If you need -- different options, you can customize the generic decoding by defining: -- --

--   customOptions = defaultOptions
--                   { fieldLabelModifier = map toUpper
--                   }
--   
--   instance FromJSON Coord where
--       parseJSON = genericParseJSON customOptions
--

class FromJSON a -- | A JSON "object" (key/value map). type Object = HashMap Text Value -- | A type that can be converted to JSON. -- -- Instances in general must specify toJSON and -- should (but don't need to) specify toEncoding. -- -- An example type and instance: -- --

--   -- Allow ourselves to write Text literals.
--   {-# LANGUAGE OverloadedStrings #-}
--   
--   data Coord = Coord { x :: Double, y :: Double }
--   
--   instance ToJSON Coord where
--     toJSON (Coord x y) = object ["x" .= x, "y" .= y]
--   
--     toEncoding (Coord x y) = pairs ("x" .= x <> "y" .= y)
--

-- -- Instead of manually writing your ToJSON instance, there are two -- options to do it automatically: -- --

Data.Aeson.TH provides Template Haskell functions which -- will derive an instance at compile time. The generated instance is -- optimized for your type so it will probably be more efficient than the -- following option.
The compiler can provide a default generic implementation for -- toJSON.

-- -- To use the second, simply add a deriving Generic -- clause to your datatype and declare a ToJSON instance. If you -- require nothing other than defaultOptions, it is sufficient to -- write (and this is the only alternative where the default -- toJSON implementation is sufficient): -- --

--   {-# LANGUAGE DeriveGeneric #-}
--   
--   import GHC.Generics
--   
--   data Coord = Coord { x :: Double, y :: Double } deriving Generic
--   
--   instance ToJSON Coord where
--       toEncoding = genericToEncoding defaultOptions
--

-- -- If on the other hand you wish to customize the generic decoding, you -- have to implement both methods: -- --

--   customOptions = defaultOptions
--                   { fieldLabelModifier = map toUpper
--                   }
--   
--   instance ToJSON Coord where
--       toJSON     = genericToJSON customOptions
--       toEncoding = genericToEncoding customOptions
--

-- -- Previous versions of this library only had the toJSON method. -- Adding toEncoding had two reasons: -- --

toEncoding is more efficient for the common case that the output -- of toJSON is directly serialized to a ByteString. -- Further, expressing either method in terms of the other would be -- non-optimal.
The choice of defaults allows a smooth transition for existing -- users: Existing instances that do not define toEncoding still -- compile and have the correct semantics. This is ensured by making the -- default implementation of toEncoding use toJSON. This -- produces correct results, but since it performs an intermediate -- conversion to a Value, it will be less efficient than directly -- emitting an Encoding. (this also means that specifying nothing -- more than instance ToJSON Coord would be sufficient as a -- generically decoding instance, but there probably exists no good -- reason to not specify toEncoding in new instances.)

class ToJSON a (.=) :: (KeyValue kv, ToJSON v) => Text -> v -> kv infixr 8 .= -- | Create a Value from a list of name/value Pairs. If -- duplicate keys arise, earlier keys and their associated values win. object :: [Pair] -> Value -- | A space-efficient representation of a Word8 vector, supporting -- many efficient operations. -- -- A ByteString contains 8-bit bytes, or by using the operations -- from Data.ByteString.Char8 it can be interpreted as containing -- 8-bit characters. data ByteString -- | A map from keys to values. A map cannot contain duplicate keys; each -- key can map to at most one value. data HashMap k v -- | O(log n) Return the value to which the specified key is mapped, -- or Nothing if this map contains no mapping for the key. lookup :: (Eq k, Hashable k) => k -> HashMap k v -> Maybe v -- | 64-bit signed integer type data Int64 -- | The fromJust function extracts the element out of a Just -- and throws an error if its argument is Nothing. -- --

Examples

-- -- Basic usage: -- --

--   >>> fromJust (Just 1)
--   1
--

-- --

--   >>> 2 * (fromJust (Just 10))
--   20
--

-- --

--   >>> 2 * (fromJust Nothing)
--   *** Exception: Maybe.fromJust: Nothing
--

fromJust :: () => Maybe a -> a -- | The isJust function returns True iff its argument is of -- the form Just _. -- --

Examples

-- -- Basic usage: -- --

--   >>> isJust (Just 3)
--   True
--

-- --

--   >>> isJust (Just ())
--   True
--

-- --

--   >>> isJust Nothing
--   False
--

-- -- Only the outer constructor is taken into consideration: -- --

--   >>> isJust (Just Nothing)
--   True
--

isJust :: () => Maybe a -> Bool -- | An associative operation. (<>) :: Semigroup a => a -> a -> a infixr 6 <> -- | A space efficient, packed, unboxed Unicode text type. data Text -- | O(n) Convert a String into a Text. Subject to -- fusion. Performs replacement on invalid scalar values. pack :: String -> Text -- | O(n) Convert a Text into a String. Subject to -- fusion. unpack :: Text -> String -- | Decode a ByteString containing UTF-8 encoded text that is known -- to be valid. -- -- If the input contains any invalid UTF-8 data, an exception will be -- thrown that cannot be caught in pure code. For more control over the -- handling of invalid data, use decodeUtf8' or -- decodeUtf8With. decodeUtf8 :: ByteString -> Text -- | Encode text using UTF-8 encoding. encodeUtf8 :: Text -> ByteString -- | Write a string the end of a file. appendFile :: FilePath -> Text -> IO () -- | Write a string to stdout, followed by a newline. putStrLn :: Text -> IO () -- | The readFile function reads a file and returns the contents of -- the file as a string. The entire file is read strictly, as with -- getContents. readFile :: FilePath -> IO Text -- | Write a string to a file. The file is truncated to zero length before -- writing begins. writeFile :: FilePath -> Text -> IO () -- | O(n) Convert a lazy Text into a strict Text. toStrict :: Text -> Text -- | A Builder is an efficient way to build lazy Text -- values. There are several functions for constructing builders, but -- only one to inspect them: to extract any data, you have to turn them -- into lazy Text values using toLazyText. -- -- Internally, a builder constructs a lazy Text by filling -- arrays piece by piece. As each buffer is filled, it is 'popped' off, -- to become a new chunk of the resulting lazy Text. All this is -- hidden from the user of the Builder. data Builder -- | O(1). A Builder taking a Text, satisfying -- --

toLazyText (fromText t) = fromChunks
--   [t]

fromText :: Text -> Builder -- | O(1). A Builder taking a lazy Text, -- satisfying -- --

```
toLazyText (fromLazyText t) = t
```

fromLazyText :: Text -> Builder -- | O(1). A Builder taking a String, satisfying -- --

toLazyText (fromString s) = fromChunks
--   [S.pack s]

fromString :: String -> Builder -- | O(n). Extract a lazy Text from a Builder with -- a default buffer size. The construction work takes place if and when -- the relevant part of the lazy Text is demanded. toLazyText :: Builder -> Text -- | This is the simplest representation of UTC. It consists of the day -- number, and a time offset from midnight. Note that if a day has a leap -- second added to it, it will have 86401 seconds. data UTCTime -- | Get the current UTCTime from the system clock. getCurrentTime :: IO UTCTime -- | The class Typeable allows a concrete representation of a type -- to be calculated. class Typeable (a :: k) -- | The type-safe cast operation cast :: (Typeable a, Typeable b) => a -> Maybe b -- | Boxed vectors, supporting efficient slicing. data Vector a -- | O(1) Indexing (!) :: () => Vector a -> Int -> a -- | O(n) Convert a list to a vector fromList :: () => [a] -> Vector a -- | O(n) Convert a vector to a list toList :: () => Vector a -> [a] -- | The trace function outputs the trace message given as its first -- argument, before returning the second argument as its result. -- -- For example, this returns the value of f x but first outputs -- the message. -- --

--   >>> let x = 123; f = show
--   
--   >>> trace ("calling f with x = " ++ show x) (f x)
--   "calling f with x = 123
--   123"
--

-- -- The trace function should only be used for debugging, or -- for monitoring execution. The function is not referentially -- transparent: its type indicates that it is a pure function but it has -- the side effect of outputting the trace message. trace :: () => String -> a -> a -- | A C string is a reference to an array of C characters terminated by -- NUL. type CString = Ptr CChar -- | Representable types of kind *. This class is derivable in GHC -- with the DeriveGeneric flag on. -- -- A Generic instance must satisfy the following laws: -- --

--   from . to ≡ id
--   to . from ≡ id
--

class Generic a -- | Formats a date into a Text string using specified formatting string -- -- Arguments: -- --

format :: Text: Format string
date :: UTCTime: Date to format

date :: UTCtime: Date to format

text :: Text: Text string containing a date in ISO8601 -- format

-- -- Return value: Parsed date dateParseISO8601 :: Text -> UTCTime -- | Reads contents of a specified file as a lazy ByteString (with -- streaming) and provides it to the specified callback -- -- Throws an error if specified file cannot be read -- -- Arguments: -- --

path :: Text: path to file
fun :: (Data.ByteString.Lazy.ByteString -> IO a): -- callback to process the file data

path :: Text: path to file
fun :: (Data.Text.Lazy.Text -> IO a): callback to -- process the file data

-- -- Return value: Result of the callback invocation ioWithFileText :: Text -> (Text -> IO a) -> IO a -- | Parses contents of a specified JSON file into a typed data -- -- Data type should be specified with a type annotation: -- -- Example: -- --

--   dt <- jsonDecodeFile "path/to/foo.json" :: IO Foo
--

-- -- Data must be an instance of FromJSON -- -- File contents are decoded as UTF-8 -- -- Throws an error if file cannot be read or data cannot be decoded -- -- Arguments: -- --

path :: Text: Path to JSON file

--   let dt = jsonDecodeText text :: Foo
--

-- -- Data must be an instance of FromJSON -- -- Throws an error if data cannot be decoded -- -- Arguments: -- --

text :: Text: JSON Text string to parse

data :: ToJSON: some data that supports JSON -- serialization with Aeson

--   let obj = object
--           [ "foo" .= (42 :: Int)
--           , "bar" .= ("baz" :: Text)
--           ]
--   let fooval = jsonGet obj "foo" :: Int
--   let barval = jsonGet obj "bar" :: Text
--

-- -- Arguments: -- --

val :: Aeson.Value: JSON value, must be a JSON -- object
field :: Text: Field name

-- -- Return value: Field value jsonGet :: forall a. FromJSON a => Value -> Text -> a -- | Lookups a key in a HashMap -- -- Throws an error if key not found in a specified HashMap -- -- Arguments: -- --

map :: HashMap Text v: Map with Text keys
key :: Text: Key to lookup

-- -- Return value: Map value that corresponds to the specified key mapGet :: HashMap Text v -> Text -> v -- | Checks whether specified path is absolute -- -- Only checks the path string itself, doesn't use FS API. -- -- Arguments: -- --

path :: Text: FS path to check

prefix :: Text: Path prefix, may be absolute
postfix :: Text: Path postfix, must not be absolute

-- -- Return value: Concatenated path pathConcat :: Text -> Text -> Text -- | Prepends an absolute prefix to the relative path -- -- Does nothing, if path is already absolute -- -- Arguments: -- --

prefix :: Text: Path prefix, must be absolute
postfix :: Text: Path postfix, may be absolute

-- -- Return value: Path with a specified prefix prepended, if path is -- relative, specified path unchanged otherwise pathPrepend :: Text -> Text -> Text -- | Stringifies a specified value -- -- If input is Text, String or ByteString, it -- is returned as a Text string without additional quotes around -- it -- -- Arguments: -- --

val :: a: Value to stringify

-- -- Return value: Text string representation of a specified value textShow :: (Show a, Typeable a) => a -> Text -- | Additional combinators and utilities for Parsec library module VtUtils.Parsec type Parser = Parsec Text () -- | Finds a line containing a specified substring -- -- Uses LF as a line separator -- -- Consumes whitespace after the line found -- -- Resulting line doesn't contain a line separator -- -- Arguments: -- --

needle :: Text: Substring to find

-- -- Return value: Line that contains a specified substring parsecLineContains :: Text -> Parser Text -- | Finds a line with a specified prefix -- -- Uses LF as a line separator -- -- Whitespace is stripped from the start of each line before checking for -- prefix -- -- Consumes whitespace after the line found -- -- Resulting line doesn't contain a line separator -- -- Arguments: -- --

prefix :: Text: Prefix to find

-- -- Return value: Line with the specified prefix parsecLinePrefix :: Text -> Parser Text -- | Finds a line that does not have a specified prefix -- -- Uses LF as a line separator -- -- Whitespace is stripped from the start of each line before checking for -- prefix -- -- Consumes whitespace after the line found -- -- Resulting line doesn't contain a line separator -- -- Arguments: -- --

prefix :: Text: Prefix that should be skipped

-- -- Return value: First line that does not have a specified prefix parsecLineNoPrefix :: Text -> Parser Text -- | Skips a specified number of lines -- -- Uses LF as a line separator -- -- Does not consume additional whitespace after the last line skipped (or -- between the lines) -- -- Arguments: -- --

count :: Int: Number of lines to skip

parsecSkipLines :: Int -> Parser () -- | Skips all input until the specified substring is found -- -- Warning: all look-ahead data is kept in memory -- -- Arguments: -- --

needle :: Text: Substring to find

-- -- Return value: First line that does not have a specified prefix parsecSkipManyTill :: Text -> Parser () -- | The parser parsecTry p behaves like parser p, except that it -- pretends that it hasn't consumed any input when an error occurs -- -- This is a re-export of Text.Parsec.try under a different name -- to not conflict with Control.Exception.try -- -- Arguments: -- --

parser :: Parser a: Parser to wrap into try

-- -- Return value: Resulting value from the specified parser parsecTry :: Parser a -> Parser a -- | Skips one or more whitespace characters -- -- Note: Lexemes from Text.Parsec.Token.TokenParser can be used -- instead parsecWhitespace :: Parser () -- | Formats ParseError into Text string -- -- Arguments: -- --

err :: ParseError: ParseError thrown by -- Parsec

-- -- Return value: Text representation of a specified error parsecErrorToText :: ParseError -> Text -- | Lazily reads contents from a specified file and parses it using the -- specified parser -- -- File contents are decoded as UTF-8 -- -- Throws an error on file IO error or parsing error -- -- Arguments: -- --

parser :: Parser a: Parser to use for the contents of the -- file
path :: ParseError: Path to a file to parse

-- -- Return value: Resulting value from the specified parser parsecParseFile :: Parser a -> Text -> IO a -- | Parser a specified strict Text string using a specified -- parser -- -- Note: parser is typed on a lazy Text input (so it can also be -- used with parsecParseFile) -- -- Throws an error on parsing error -- -- Arguments: -- --

parser :: Parser a: Parser to use for the contents of the -- file
text :: Text: Text string to parse

-- -- Return value: Resulting value from the specified parser parsecParseText :: Parser a -> Text -> a -- | SQL queries files utilities module VtUtils.Queries type Queries = HashMap Text Text -- | Parses a specified SQL file into a HashMap that contains all -- SQL queries as map entries -- -- SQL file example: -- --

--   --
--   -- test queries
--   --
--   
--   /** selectFoo */
--   select foo
--   from bar
--   
--   /** updateBar */
--   update bar
--   set foo = 42
--

-- -- Note: there must be an empty line after the initial comment lines on -- the top of the file -- -- Throws an error on file IO error or parsing error -- -- Arguments: -- --

path :: Text: Path to SQL file

-- -- Return value: HashMap containing SQL queries from a file queriesLoad :: Text -> IO Queries -- | HUnit utilities module VtUtils.HUnit -- | Runs all, group or one of specified HUnit tests depending on -- the command line arguments -- -- Example specifying argument to stack test invocation: -- --

--   stack test --ta "GroupName testName"
--

-- -- If no arguments are specified - all test are run.grlabel -- -- If single argument is specified - it is interpreted as a name of the -- group.grlabel -- -- If two argument are specified - first one is interpreted as a group -- name, and second one as a test name -- -- Throws an error on invalid command line argument -- -- Tests results are printed to stdout -- -- Arguments: -- --

tests :: Vector Test: HUnit tests to run

hunitMain :: Vector Test -> IO () -- | Runs all HUnit tests from a specified Vector -- -- Tests results are printed to stdout -- -- Arguments: -- --

tests :: Vector Test: HUnit tests to run

hunitRun :: Vector Test -> IO () -- | Runs a subset of HUnit tests with a specified label value -- -- Throws an error if no tests in the specified Vector have -- specified label -- -- Tests results are printed to stdout -- -- Arguments: -- --

tests :: Vector Test: HUnit tests
label :: Text: Group label

hunitRunGroup :: Vector Test -> Text -> IO () -- | Runs a single test from a specified Vector of HUnit -- tests -- -- Throws an error if a test with a specified group label and test label -- is not found in specified Vector of tests -- -- Tests results are printed to stdout -- -- Arguments: -- --

tests :: Vector Test: HUnit tests
grlabel :: Text: Group label
tslabel :: Text: Test label

hunitRunSingle :: Vector Test -> Text -> Text -> IO ()