-- 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.3.0.0 -- | Error reporting utilities module VtUtils.Error -- | Formats error message to be used with Show -- -- Arguments: -- --

exc :: Typeable: Error record or exception
msg :: Text: Error message

-- -- Return value: String containing the type name of error and a message errorShow :: Typeable e => e -> Text -> String -- | 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 -- | Error record for dateParseISO8601 function data DateParseISO8601Error DateParseISO8601Error :: Text -> DateParseISO8601Error -- | Invalid date string specified for parsing [$sel:invalidDate:DateParseISO8601Error] :: DateParseISO8601Error -> Text -- | Parses Text string using ISO8601 format -- -- Expected input example: 2018-11-25 00:00:01 -- -- Arguments: -- --

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

-- -- Return value: Parsed date or error message dateParseISO8601 :: Text -> Either DateParseISO8601Error UTCTime instance GHC.Show.Show VtUtils.Date.DateParseISO8601Error -- | Foreign Function Interface utilities module VtUtils.FFI -- | Passes specified Storable value as a pointer (to that value) -- to the specified IO action -- -- Arguments: -- --

val :: Storable a: Input value
fun :: Ptr a -> IO b: IO action to run

-- -- Return value: Value returned from IO action ffiWithPtr :: Storable a => a -> (Ptr a -> IO b) -> IO b -- | Passes a pointer to a NULL pointer of a Storable type to the -- specified IO action -- -- Arguments: -- --

fun :: Ptr (Ptr a) -> IO b: IO action to run

-- -- Return value: Value returned from IO action ffiWithPtrPtr :: (Ptr (Ptr a) -> IO b) -> IO b -- | Passes specified Text string as a NUL-terminated UTF-8 string -- to the specified IO action -- -- Arguments: -- --

text :: Text: Input string
fun :: CString -> IO a: IO action to run

-- -- Return value: Value returned from IO action ffiWithUTF8 :: Text -> (CString -> IO a) -> IO a -- | Passes specified Text string as a NUL-terminated UTF-16 -- string to the specified IO action -- -- Arguments: -- --

text :: Text: Input string
fun :: Ptr Word16 -> IO a: IO action to run

-- -- Return value: Value returned from IO action ffiWithUTF16 :: Text -> (Ptr Word16 -> IO a) -> IO a -- | HashMap utilities module VtUtils.Map -- | Creates a HashMap from a Vector -- -- Creates a HashMap and fills it using the Vector -- elements as values and elements with key function as keys. -- -- If key function returns duplicate keys for some elements, previous -- entry is replaced with a new one. -- -- Arguments: -- --

vec :: Vector v: Input Vector
keyfun :: (Int -> v -> k): Key function that takes -- an element index and element and returns the map key

-- -- Return value: HashMap filled with elements from input -- Vector mapFromVector :: (Eq k, Hashable k) => Vector v -> (Int -> v -> k) -> HashMap k 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 -- -- Specified postfix must be non-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 -- | Exception for fsCopyDirectory function data FSCopyDirectoryDestException FSCopyDirectoryDestException :: Text -> FSCopyDirectoryDestException -- | Invalid destination directory [$sel:dest:FSCopyDirectoryDestException] :: FSCopyDirectoryDestException -> Text -- | Exception for fsCopyDirectory function data FSCopyDirectorySourceException FSCopyDirectorySourceException :: Text -> FSCopyDirectorySourceException -- | Invalid source directory [$sel:source:FSCopyDirectorySourceException] :: FSCopyDirectorySourceException -> Text -- | 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 () instance GHC.Exception.Type.Exception VtUtils.FS.FSCopyDirectoryDestException instance GHC.Show.Show VtUtils.FS.FSCopyDirectoryDestException instance GHC.Exception.Type.Exception VtUtils.FS.FSCopyDirectorySourceException instance GHC.Show.Show VtUtils.FS.FSCopyDirectorySourceException -- | Process spawning utilities module VtUtils.Process -- | Spawns a new process and waits for it to exit -- -- Arguments: -- --

executable :: Text: Path to executable binary
args :: Vector Text: Arguments to pass to executable
out :: Text Path to a file, where std output (both -- stdout and stderr) will be written

-- -- Return value: Process exit code processSpawnAndWait :: Text -> Vector Text -> Text -> IO Int -- | Text utilities module VtUtils.Text -- | Stringifies 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 -- | Splits specified Text string into a Vector of parts -- using specified delimiter -- -- Delimiter must be non-empty -- -- Arguments: -- --

haystack :: Text: string to split
needle :: Text delimiter

-- -- Return value: Vector Text vector containing the parts of the -- input string textSplit :: Text -> Text -> Vector Text -- | Concatenates specified Vector of string parts interspersing -- it with specified parameters -- -- If length of parameters Vector is less than a number of parts -- - 1, then remaining parameters are filled with empty strings. If -- parameters vector is too long, excessive parameters are ignored. -- -- Arguments: -- --

parts :: Vector Text: string parts
params :: Vector Text parameters to intersperse into the -- parts

-- -- Return value: Vector Text vector containing the parts of the -- input string textFormatParts :: Vector Text -> Vector Text -> Text -- | Formats specified template with specified parameters Vector -- -- Template must use {} string for placeholders. -- -- If length of parameters Vector is less than a number of holes -- in template, then remaining parameters are filled with empty strings. -- If parameters vector is too long, excessive parameters are ignored. -- -- Template preparation is relatively expensive, consider using -- textFormatParts for frequently used templates. -- -- Arguments: -- --

template :: Text: string parts
params :: Vector Text parameters to intersperse into the -- parts

-- -- Return value: Vector Text vector containing the parts of the -- input string textFormat :: Text -> Vector Text -> Text -- | Decodes ByteString into Text using UTF-8 -- encoding -- -- Invalid byte sequences are replaced with U+FFFD -- -- Arguments: -- --

bytes :: ByteString: Byte string

-- -- Return value: Text string textDecodeUtf8 :: ByteString -> Text -- | IO utilities module VtUtils.IO -- | Exception for ioWithFileBytes and ioWithFileText -- functions data IOWithFileException IOWithFileException :: Text -> SomeException -> IOWithFileException -- | Specified path [$sel:filePath:IOWithFileException] :: IOWithFileException -> Text -- | Exception record [$sel:exception:IOWithFileException] :: IOWithFileException -> SomeException -- | Reads contents of a specified file as a lazy ByteString (with -- streaming) and provides it to the specified callback -- -- Throws IOWithFileBytesException 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 IOWithFileBytesException 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 instance GHC.Exception.Type.Exception VtUtils.IO.IOWithFileException instance GHC.Show.Show VtUtils.IO.IOWithFileException -- | 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 -- -- 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 -- -- 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 -- -- 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 () -- | Exception for parsecParseFile function data ParsecParseFileException -- | Lazily reads contents from a specified file and parses it using the -- specified parser -- -- File contents are decoded as UTF-8 -- -- Throws an exception 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 -- | Error for parsecParseText function data ParsecParseTextError -- | 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) -- -- Returns 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 or parsing -- error parsecParseText :: Parser a -> Text -> Either ParsecParseTextError a instance GHC.Show.Show VtUtils.Parsec.ParsecParseTextError instance GHC.Exception.Type.Exception VtUtils.Parsec.ParsecParseFileException instance GHC.Show.Show VtUtils.Parsec.ParsecParseFileException -- | 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 -- | 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 -- | Exception for jsonDecodeFile function data JSONDecodeFileException JSONDecodeFileException :: Text -> Text -> JSONDecodeFileException -- | Specified file path [$sel:filePath:JSONDecodeFileException] :: JSONDecodeFileException -> Text -- | Decoding error [$sel:message:JSONDecodeFileException] :: JSONDecodeFileException -> Text -- | 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 exception 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 -- | Error for jsonDecodeText function data JSONDecodeError JSONDecodeError :: Text -> Text -> JSONDecodeError -- | Specified text [$sel:jsonText:JSONDecodeError] :: JSONDecodeError -> Text -- | Decoding error [$sel:message:JSONDecodeError] :: JSONDecodeError -> Text -- | Parses a JSON Text string into a typed data -- -- Data type should be specified with a type annotation: -- -- Example: -- --

--   let Right (dt :: Foo) = jsonDecodeText text
--

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

text :: Text: JSON Text string to parse

-- -- Return value: Decoded data or decoding error jsonDecodeText :: forall a. FromJSON a => Text -> Either JSONDecodeError a -- | Exception for jsonDecodeTextIO function data JSONDecodeTextIOException JSONDecodeTextIOException :: JSONDecodeError -> JSONDecodeTextIOException -- | Decoding error [$sel:err:JSONDecodeTextIOException] :: JSONDecodeTextIOException -> JSONDecodeError -- | Encodes a data into a JSON Text string -- -- Data must be an instance of ToJSON -- -- Arguments: -- --

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

-- -- Return value: JSON Text string jsonEncodeText :: ToJSON a => a -> Text -- | Error for jsonGet function data JSONGetError -- | Extract the field value from the specified JSON object -- -- Returns 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 Right (fooval :: Int) = jsonGet obj "foo"
--   let Right (barval :: Text) = jsonGet obj "bar"
--

-- -- Arguments: -- --

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

-- -- Return value: Field value or an error jsonGet :: forall a. FromJSON a => Value -> Text -> Either JSONGetError a -- | JSON options with unwrapUnaryRecords flag flipped to -- True jsonUnwrapUnaryOptions :: Options instance GHC.Show.Show VtUtils.JSON.JSONGetError instance GHC.Exception.Type.Exception VtUtils.JSON.JSONDecodeFileException instance GHC.Show.Show VtUtils.JSON.JSONDecodeFileException instance GHC.Exception.Type.Exception VtUtils.JSON.JSONDecodeTextIOException instance GHC.Show.Show VtUtils.JSON.JSONDecodeTextIOException instance GHC.Show.Show VtUtils.JSON.JSONDecodeError -- | HTTP utilities for server (WAI) and client module VtUtils.HTTP -- | Content-Type header for application/json type httpContentTypeJSON :: Header -- | URL path string of the specified HTTP request -- -- Arguments: -- --

req :: Request: HTTP request

-- -- Return value: URL path string httpRequestPath :: Request -> Text -- | Reads a body of the specified HTTP request as a Text string -- -- Arguments: -- --

req :: Request: HTTP request

-- -- Return value: Request body as a Text string httpRequestBodyText :: Request -> IO Text -- | Exception for httpRequestBodyJSON function data HTTPRequestBodyJSONException HTTPRequestBodyJSONException :: ByteString -> Text -> HTTPRequestBodyJSONException -- | Request body containing invalid JSON [$sel:requestBody:HTTPRequestBodyJSONException] :: HTTPRequestBodyJSONException -> ByteString -- | JSON parsing error message [$sel:message:HTTPRequestBodyJSONException] :: HTTPRequestBodyJSONException -> Text -- | Reads a body of the specified HTTP request and parses it as a JSON -- value -- -- Data type should be specified with a type annotation: -- -- Example: -- --

--   dt <- httpRequestBodyJSON req :: IO Foo
--

-- -- Data must be an instance of FromJSON -- -- Throws an exception if request body doesn't contain valid JSON. -- -- Arguments: -- --

req :: Request: HTTP request

-- -- Return value: Request body parsed as a JSON value httpRequestBodyJSON :: forall a. FromJSON a => Request -> IO a -- | Headers of the specified HTTP request as a Vector of -- (name, value) pairs -- -- Arguments: -- --

req :: Request: HTTP request

-- -- Return value: Request headers as a Vector of (name, -- value) pairs httpRequestHeaders :: Request -> Vector (Text, Text) -- | Headers of the specified HTTP request as a name -> value -- map -- -- Arguments: -- --

req :: Request: HTTP request

-- -- Return value: Request headers as a name -> value map httpRequestHeadersMap :: Request -> HashMap Text Text -- | Exception for httpRequestBodyJSON function data HTTPResponseBodyException HTTPResponseBodyException :: Int -> Int -> Text -> ByteString -> HTTPResponseBodyException -- | Max allowed bytes to read [$sel:threshold:HTTPResponseBodyException] :: HTTPResponseBodyException -> Int -- | Bytes actually read [$sel:read:HTTPResponseBodyException] :: HTTPResponseBodyException -> Int -- | Caller-supplied label [$sel:label:HTTPResponseBodyException] :: HTTPResponseBodyException -> Text -- | Part of the response that was read [$sel:responsePart:HTTPResponseBodyException] :: HTTPResponseBodyException -> ByteString -- | Read a body of HTTP response as a lazy ByteString -- -- Throws an exception if specified threshold is exceeded. -- -- Arguments: -- --

label :: Text: Label used for error reporting on -- overly-large responses
resp :: Response BodyReader: HTTP response
threshold :: Int Max response body length in bytes

-- -- Return value: Response body as a lazy ByteString httpResponseBody :: Text -> Response BodyReader -> Int -> IO ByteString -- | Read a body of HTTP response as a Text string -- -- Arguments: -- --

label :: Text: Label used for error reporting on -- overly-large responses
resp :: Response BodyReader: HTTP response
threshold :: Int Max response body length in bytes

-- -- Return value: Response body as a Text string httpResponseBodyText :: Text -> Response BodyReader -> Int -> IO Text -- | Exception for httpResponseBodyJSON function data HTTPResponseBodyJSONException HTTPResponseBodyJSONException :: ByteString -> Text -> Text -> HTTPResponseBodyJSONException -- | Response body containing invalid JSON [$sel:response:HTTPResponseBodyJSONException] :: HTTPResponseBodyJSONException -> ByteString -- | Caller-supplied label [$sel:label:HTTPResponseBodyJSONException] :: HTTPResponseBodyJSONException -> Text -- | JSON parsing error message [$sel:message:HTTPResponseBodyJSONException] :: HTTPResponseBodyJSONException -> Text -- | Read a body of HTTP response as a JSON value -- -- Data type should be specified with a type annotation: -- -- Example: -- --

--   dt <- httpResponseBodyJSON label resp 1024 :: IO Foo
--

-- -- Data must be an instance of FromJSON -- -- Throws an exception if response body doesn't contain valid JSON. -- -- Arguments: -- --

label :: Text: Label used for error reporting on -- overly-large responses
resp :: Response BodyReader: HTTP response
threshold :: Int Max response body length in bytes

-- -- Return value: Response body as a JSON value httpResponseBodyJSON :: forall a. FromJSON a => Text -> Response BodyReader -> Int -> IO a -- | Headers of the specified HTTP response as a Vector of -- (name, value) pairs -- -- Arguments: -- --

req :: Response: HTTP request

-- -- Return value: Response headers as a Vector of (name, -- value) pairs httpResponseHeaders :: Response a -> Vector (Text, Text) -- | Headers of the specified HTTP response as a name -> value -- map -- -- Arguments: -- --

req :: Response: HTTP request

-- -- Return value: Response headers as a name -> value map httpResponseHeadersMap :: Response a -> HashMap Text Text instance GHC.Exception.Type.Exception VtUtils.HTTP.HTTPResponseBodyJSONException instance GHC.Show.Show VtUtils.HTTP.HTTPResponseBodyJSONException instance GHC.Exception.Type.Exception VtUtils.HTTP.HTTPResponseBodyException instance GHC.Show.Show VtUtils.HTTP.HTTPResponseBodyException instance GHC.Exception.Type.Exception VtUtils.HTTP.HTTPRequestBodyJSONException instance GHC.Show.Show VtUtils.HTTP.HTTPRequestBodyJSONException -- | 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 > -- | 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 $ (<) :: 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 /= -- | 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 -- | ceiling x returns the least integer not less than -- x ceiling :: (RealFrac a, Integral b) => a -> b -- | 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 -- | floor x returns the greatest integer not greater than -- x floor :: (RealFrac a, Integral b) => a -> b fmap :: Functor f => (a -> b) -> f a -> f b -- | general coercion from integral types fromIntegral :: (Integral a, Num b) => a -> b -- | Extract the first component of a pair. fst :: () => (a, b) -> a -- | Identity function. -- --

--   id x = x
--

id :: () => a -> a -- | Returns the size/length of a finite structure as an Int. The -- default implementation is optimized for structures that are similar to -- cons-lists, because there is no general way to do better. length :: Foldable t => t a -> Int -- | 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 -- | Extract the second component of a pair. snd :: () => (a, b) -> b -- | take n, applied to a list xs, returns the -- prefix of xs of length n, or xs itself if -- n > length xs: -- --

--   take 5 "Hello World!" == "Hello"
--   take 3 [1,2,3,4,5] == [1,2,3]
--   take 3 [1,2] == [1,2]
--   take 3 [] == []
--   take (-1) [1,2] == []
--   take 0 [1,2] == []
--

-- -- It is an instance of the more general genericTake, in which -- n may be of any integral type. take :: () => Int -> [a] -> [a] -- | 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 -- | This is the simplest of the exception-catching functions. It takes a -- single argument, runs it, and if an exception is raised the "handler" -- is executed, with the value of the exception passed as an argument. -- Otherwise, the result is returned as normal. For example: -- --

--   catch (readFile f)
--         (\e -> do let err = show (e :: IOException)
--                   hPutStr stderr ("Warning: Couldn't open " ++ f ++ ": " ++ err)
--                   return "")
--

-- -- Note that we have to give a type signature to e, or the -- program will not typecheck as the type is ambiguous. While it is -- possible to catch exceptions of any type, see the section "Catching -- all exceptions" (in Control.Exception) for an explanation of -- the problems with doing so. -- -- For catching exceptions in pure (non-IO) expressions, see the -- function evaluate. -- -- Note that due to Haskell's unspecified evaluation order, an expression -- may throw one of several possible exceptions: consider the expression -- (error "urk") + (1 `div` 0). Does the expression throw -- ErrorCall "urk", or DivideByZero? -- -- The answer is "it might throw either"; the choice is -- non-deterministic. If you are catching any type of exception then you -- might catch either. If you are calling catch with type IO -- Int -> (ArithException -> IO Int) -> IO Int then the -- handler may get run with DivideByZero as an argument, or an -- ErrorCall "urk" exception may be propogated further up. If -- you call it again, you might get a the opposite behaviour. This is ok, -- because catch is an IO computation. catch :: Exception e => IO a -> (e -> IO a) -> IO a -- | 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 -- | A variant of throw that can only be used within the IO -- monad. -- -- Although throwIO has a type that is an instance of the type of -- throw, the two functions are subtly different: -- --

--   throw e   `seq` x  ===> throw e
--   throwIO e `seq` x  ===> x
--

-- -- The first example will cause the exception e to be raised, -- whereas the second one won't. In fact, throwIO will only cause -- an exception to be raised when it is used within the IO monad. -- The throwIO variant should be used in preference to -- throw to raise an exception within the IO monad because -- it guarantees ordering with respect to other IO operations, -- whereas throw does not. throwIO :: Exception e => e -> IO 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 () -- | Direct MonadPlus equivalent of filter. -- --

Examples

-- -- The filter function is just mfilter specialized to the -- list monad: -- --

--   filter = ( mfilter :: (a -> Bool) -> [a] -> [a] )
--

-- -- An example using mfilter with the Maybe monad: -- --

--   >>> mfilter odd (Just 1)
--   Just 1
--   >>> mfilter odd (Just 2)
--   Nothing
--

mfilter :: MonadPlus m => (a -> Bool) -> m a -> m a -- | 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 () -- | Lift a computation from the IO monad. liftIO :: MonadIO m => IO a -> m a -- | 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 -- | Lift a computation from the argument monad to the constructed monad. lift :: (MonadTrans t, Monad m) => m a -> t m 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: -- --

fail yields a custom error message: it is the recommended -- way of reporting a failure;
empty (or mzero) is uninformative: use it when the -- error is meant to be caught by some (<|>);
typeMismatch can be used to report a failure when the -- encountered value is not of the expected JSON type; unexpected -- is an appropriate alternative when more than one type may be expected, -- or to keep the expected type implicit.

-- -- prependFailure (or modifyFailure) add more information -- to a parser's error messages. -- -- An example type and instance using typeMismatch and -- prependFailure: -- --

--   -- 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 empty to fail, but typeMismatch
--       -- gives a much more informative error message.
--       parseJSON invalid    =
--           prependFailure "parsing Coord failed, "
--               (typeMismatch "Object" invalid)
--

-- -- For this common case of only being concerned with a single type of -- JSON value, the functions withObject, withScientific, -- 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 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 -- | A JSON value represented as a Haskell value. data Value (.=) :: (KeyValue kv, ToJSON v) => Text -> v -> kv infixr 8 .= -- | A configurable generic JSON decoder. This function applied to -- defaultOptions is used as the default for parseJSON when -- the type is an instance of Generic. genericParseJSON :: (Generic a, GFromJSON Zero (Rep a)) => Options -> Value -> Parser a -- | A configurable generic JSON creator. This function applied to -- defaultOptions is used as the default for toJSON when -- the type is an instance of Generic. genericToJSON :: (Generic a, GToJSON Value Zero (Rep a)) => Options -> a -> Value -- | Create a Value from a list of name/value Pairs. If -- duplicate keys arise, earlier keys and their associated values win. object :: [Pair] -> Value parseJSON :: FromJSON a => Value -> Parser a -- | Convert a Haskell value to a JSON-friendly intermediate type. toJSON :: ToJSON a => a -> Value -- | A drop-in replacement for aeson's encode function, producing -- JSON-ByteStrings for human readers. -- -- Follows the default configuration in defConfig. encodePretty :: ToJSON a => a -> ByteString -- | Bitwise "and" (.&.) :: Bits a => a -> a -> a infixl 7 .&. -- | Bitwise "or" (.|.) :: Bits a => a -> a -> a infixl 5 .|. -- | 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 -- | O(n). Construct a new ByteString from a -- CString. The resulting ByteString is an immutable -- copy of the original CString, and is managed on the Haskell -- heap. The original CString must be null terminated. packCString :: CString -> IO ByteString -- | O(n). Construct a new ByteString from a -- CStringLen. The resulting ByteString is an immutable -- copy of the original CStringLen. The ByteString is a -- normal Haskell value and will be managed on the Haskell heap. packCStringLen :: CStringLen -> IO ByteString -- | O(n) construction Use a ByteString with a function -- requiring a null-terminated CString. The CString is -- a copy and will be freed automatically; it must not be stored or used -- after the subcomputation finishes. useAsCString :: () => ByteString -> (CString -> IO a) -> IO a -- | O(n) construction Use a ByteString with a function -- requiring a CStringLen. As for useAsCString this -- function makes a copy of the original ByteString. It must not -- be stored or used after the subcomputation finishes. useAsCStringLen :: () => ByteString -> (CStringLen -> IO a) -> IO a -- | Return True if the given value is a Right-value, -- False otherwise. -- --

Examples

-- -- Basic usage: -- --

--   >>> isRight (Left "foo")
--   False
--   
--   >>> isRight (Right 3)
--   True
--

-- -- Assuming a Left value signifies some sort of error, we can use -- isRight to write a very simple reporting function that only -- outputs "SUCCESS" when a computation has succeeded. -- -- This example shows how isRight might be used to avoid pattern -- matching when one does not care about the value contained in the -- constructor: -- --

--   >>> import Control.Monad ( when )
--   
--   >>> let report e = when (isRight e) $ putStrLn "SUCCESS"
--   
--   >>> report (Left "parse error")
--   
--   >>> report (Right 1)
--   SUCCESS
--

isRight :: () => Either a b -> Bool -- | Extracts the element out of a Right and throws an error if its -- argument take the form Left _. -- -- Using Control.Lens: -- --

--   fromRight' x ≡ x^?!_Right
--

-- --

--   >>> fromRight' (Right 12)
--   12
--

fromRight' :: () => Either a b -> b -- | Left-associative fold of a structure but with strict application of -- the operator. -- -- This ensures that each step of the fold is forced to weak head normal -- form before being applied, avoiding the collection of thunks that -- would otherwise occur. This is often what you want to strictly reduce -- a finite list to a single, monolithic result (e.g. length). -- -- For a general Foldable structure this should be semantically -- identical to, -- --

--   foldl f z = foldl' f z . toList
--

foldl' :: Foldable t => (b -> a -> b) -> b -> t a -> b -- | Right-associative fold of a structure, but with strict application of -- the operator. foldr' :: Foldable t => (a -> b -> b) -> b -> t a -> b -- | 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 <> -- | Fold a list using the monoid. -- -- For most types, the default definition for mconcat will be -- used, but the function is included in the class definition so that an -- optimized version can be provided for specific types. mconcat :: Monoid a => [a] -> a -- | 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 -- | Encode text using UTF-8 encoding. encodeUtf8 :: Text -> ByteString -- | O(n) Decode a C string with explicit length, which is assumed -- to have been encoded as UTF-8. If decoding fails, a -- UnicodeException is thrown. peekCStringLen :: CStringLen -> IO Text -- | Marshal a Text into a C string encoded as UTF-8 in temporary -- storage, with explicit length information. The encoded string may -- contain NUL bytes, and is not followed by a trailing NUL byte. -- -- The temporary storage is freed when the subcomputation terminates -- (either normally or via an exception), so the pointer to the temporary -- storage must not be used after this function returns. withCStringLen :: () => Text -> (CStringLen -> IO a) -> IO a -- | Write a string the end of a file. appendFile :: FilePath -> Text -> IO () -- | Read a single line of user input from stdin. getLine :: IO Text -- | 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 -- | POSIX time is the nominal time since 1970-01-01 00:00 UTC -- -- To convert from a CTime or EpochTime, use -- realToFrac. type POSIXTime = NominalDiffTime posixSecondsToUTCTime :: POSIXTime -> UTCTime utcTimeToPOSIXSeconds :: UTCTime -> POSIXTime -- | 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) Left fold with strict accumulator (function applied to -- each element and its index) ifoldl' :: () => (a -> Int -> b -> a) -> a -> Vector b -> a -- | O(n) Convert a vector to a list toList :: () => Vector a -> [a] -- | O(1) Vector with exactly one element singleton :: () => a -> Vector a -- | A Word is an unsigned integral type, with the same size as -- Int. data Word -- | 8-bit unsigned integer type data Word8 -- | 16-bit unsigned integer type data Word16 -- | 32-bit unsigned integer type data Word32 -- | 64-bit unsigned integer type data Word64 -- | 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 value of type Ptr a represents a pointer to an -- object, or an array of objects, which may be marshalled to or from -- Haskell values of type a. -- -- The type a will often be an instance of class Storable -- which provides the marshalling operations. However this is not -- essential, and you can provide your own operations to access the -- pointer. For example you might write small foreign functions to get or -- set the fields of a C struct. data Ptr a -- | The castPtr function casts a pointer from one type to another. castPtr :: () => Ptr a -> Ptr b -- | Turns a plain memory reference into a foreign pointer that may be -- associated with finalizers by using addForeignPtrFinalizer. newForeignPtr_ :: () => Ptr a -> IO (ForeignPtr a) -- | The constant nullPtr contains a distinguished value of -- Ptr that is not associated with a valid memory location. nullPtr :: () => Ptr a -- | Read a value from the given memory location. -- -- Note that the peek and poke functions might require properly aligned -- addresses to function correctly. This is architecture dependent; thus, -- portable code should ensure that when peeking or poking values of some -- type a, the alignment constraint for a, as given by -- the function alignment is fulfilled. peek :: Storable a => Ptr a -> IO a -- | Write the given value to the given memory location. Alignment -- restrictions might apply; see peek. poke :: Storable a => Ptr a -> a -> IO () -- | Advances the given address by the given offset in bytes. plusPtr :: () => Ptr a -> Int -> Ptr b -- | casts a Ptr to an IntPtr ptrToIntPtr :: () => Ptr a -> IntPtr -- | A C string is a reference to an array of C characters terminated by -- NUL. type CString = Ptr CChar -- | A string with explicit length information in bytes instead of a -- terminating NUL (allowing NUL characters in the middle of the string). type CStringLen = (Ptr CChar, Int) -- | Haskell type representing the C char type. newtype CChar CChar :: Int8 -> CChar -- | Haskell type representing the C int type. newtype CInt CInt :: Int32 -> CInt -- | Haskell type representing the C long type. newtype CLong CLong :: Int64 -> CLong -- | Haskell type representing the C short type. newtype CShort CShort :: Int16 -> CShort -- | Haskell type representing the C size_t type. newtype CSize CSize :: Word64 -> CSize -- | Haskell type representing the C unsigned char type. newtype CUChar CUChar :: Word8 -> CUChar -- | Haskell type representing the C unsigned int type. newtype CUInt CUInt :: Word32 -> CUInt -- | Haskell type representing the C unsigned long type. newtype CULong CULong :: Word64 -> CULong -- | Haskell type representing the C unsigned short type. newtype CUShort CUShort :: Word16 -> CUShort -- | Copies the given number of bytes from the second area (source) into -- the first (destination); the copied areas may not overlap copyBytes :: () => Ptr a -> Ptr a -> Int -> IO () -- | The member functions of this class facilitate writing values of -- primitive types to raw memory (which may have been allocated with the -- above mentioned routines) and reading values from blocks of raw -- memory. The class, furthermore, includes support for computing the -- storage requirements and alignment restrictions of storable types. -- -- Memory addresses are represented as values of type Ptr -- a, for some a which is an instance of class -- Storable. The type argument to Ptr helps provide some -- valuable type safety in FFI code (you can't mix pointers of different -- types without an explicit cast), while helping the Haskell type system -- figure out which marshalling method is needed for a given pointer. -- -- All marshalling between Haskell and a foreign language ultimately -- boils down to translating Haskell data structures into the binary -- representation of a corresponding data structure of the foreign -- language and vice versa. To code this marshalling in Haskell, it is -- necessary to manipulate primitive data types stored in unstructured -- memory blocks. The class Storable facilitates this manipulation -- on all types for which it is instantiated, which are the standard -- basic types of Haskell, the fixed size Int types -- (Int8, Int16, Int32, Int64), the fixed -- size Word types (Word8, Word16, Word32, -- Word64), StablePtr, all types from -- Foreign.C.Types, as well as Ptr. class Storable a -- | Computes the alignment constraint of the argument. An alignment -- constraint x is fulfilled by any address divisible by -- x. The value of the argument is not used. alignment :: Storable a => a -> Int -- | Read a value from a memory location given by a base address and -- offset. The following equality holds: -- --

--   peekByteOff addr off = peek (addr `plusPtr` off)
--

peekByteOff :: Storable a => Ptr b -> Int -> IO a -- | Write a value to a memory location given by a base address and offset. -- The following equality holds: -- --

--   pokeByteOff addr off x = poke (addr `plusPtr` off) x
--

pokeByteOff :: Storable a => Ptr b -> Int -> a -> IO () -- | Computes the storage requirements (in bytes) of the argument. The -- value of the argument is not used. sizeOf :: Storable a => a -> Int -- | 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 -- | Keeps track of open connections for keep-alive. -- -- If possible, you should share a single Manager between multiple -- threads and requests. -- -- Since 0.1.0 data Manager -- | Create a Manager. The Manager will be shut down -- automatically via garbage collection. -- -- Creating a new Manager is a relatively expensive operation, you -- are advised to share a single Manager between requests instead. -- -- The first argument to this function is often -- defaultManagerSettings, though add-on libraries may provide a -- recommended replacement. -- -- Since 0.1.0 newManager :: ManagerSettings -> IO Manager -- | Same as parseRequest, but parse errors cause an impure -- exception. Mostly useful for static strings which are known to be -- correctly formatted. parseRequest_ :: String -> Request -- | Perform a Request using a connection acquired from the given -- Manager, and then provide the Response to the given -- function. This function is fully exception safe, guaranteeing that the -- response will be closed when the inner function exits. It is defined -- as: -- --

--   withResponse req man f = bracket (responseOpen req man) responseClose f
--

-- -- It is recommended that you use this function in place of explicit -- calls to responseOpen and responseClose. -- -- You will need to use functions such as brRead to consume the -- response body. -- -- Since 0.1.0 withResponse :: () => Request -> Manager -> (Response BodyReader -> IO a) -> IO a -- | The WAI application. -- -- Note that, since WAI 3.0, this type is structured in continuation -- passing style to allow for proper safe resource handling. This was -- handled in the past via other means (e.g., ResourceT). As a -- demonstration: -- --

--   app :: Application
--   app req respond = bracket_
--       (putStrLn "Allocating scarce resource")
--       (putStrLn "Cleaning up")
--       (respond $ responseLBS status200 [] "Hello World")
--

type Application = Request -> Response -> IO ResponseReceived -> IO ResponseReceived -- | Information on the request sent by the client. This abstracts away the -- details of the underlying implementation. data Request -- | The size of the request body. In the case of chunked bodies, the size -- will not be known. -- -- Since 1.4.0 data RequestBodyLength ChunkedBody :: RequestBodyLength KnownLength :: Word64 -> RequestBodyLength -- | Get the request body as a lazy ByteString. This uses lazy I/O under -- the surface, and therefore all typical warnings regarding lazy I/O -- apply. -- -- Since 1.4.1 lazyRequestBody :: Request -> IO ByteString -- | Parsed query string information. queryString :: Request -> Query -- | Extra path information sent by the client. The meaning varies slightly -- depending on backend; in a standalone server setting, this is most -- likely all information after the domain name. In a CGI application, -- this would be the information following the path to the CGI executable -- itself. -- -- Middlewares and routing tools should not modify this raw value, as it -- may be used for such things as creating redirect destinations by -- applications. Instead, if you are writing a middleware or routing -- framework, modify the pathInfo instead. This is the approach -- taken by systems like Yesod subsites. -- -- Note: At the time of writing this documentation, there is at -- least one system (Network.Wai.UrlMap from wai-extra) -- that does not follow the above recommendation. Therefore, it is -- recommended that you test the behavior of your application when using -- rawPathInfo and any form of library that might modify the -- Request. rawPathInfo :: Request -> ByteString -- | The size of the request body. In the case of a chunked request body, -- this may be unknown. -- -- Since 1.4.0 requestBodyLength :: Request -> RequestBodyLength -- | A list of headers (a pair of key and value) in an HTTP request. requestHeaders :: Request -> RequestHeaders -- | Request method such as GET. requestMethod :: Request -> Method -- | Creating Response from ByteString. This is a wrapper for -- responseBuilder. responseLBS :: Status -> ResponseHeaders -> ByteString -> Response -- | This combinator implements choice. The parser p <|> q -- first applies p. If it succeeds, the value of p is -- returned. If p fails without consuming any input, -- parser q is tried. This combinator is defined equal to the -- mplus member of the MonadPlus class and the -- (<|>) member of Alternative. -- -- The parser is called predictive since q is only tried -- when parser p didn't consume any input (i.e.. the look ahead -- is 1). This non-backtracking behaviour allows for both an efficient -- implementation of the parser combinators and the generation of good -- error messages. (<|>) :: () => ParsecT s u m a -> ParsecT s u m a -> ParsecT s u m a infixr 1 <|> -- | The parser p <?> msg behaves as parser p, but -- whenever the parser p fails without consuming any -- input, it replaces expect error messages with the expect error -- message msg. -- -- This is normally used at the end of a set alternatives where we want -- to return an error message in terms of a higher level construct rather -- than returning all possible characters. For example, if the -- expr parser from the try example would fail, the error -- message is: '...: expecting expression'. Without the -- (<?>) combinator, the message would be like '...: -- expecting "let" or letter', which is less friendly. () :: () => ParsecT s u m a -> String -> ParsecT s u m a infix 0 -- | 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

-- -- Return value: String containing a date in ISO8601 format dateFormatISO8601 :: UTCTime -> Text -- | Parses Text string using ISO8601 format -- -- Expected input example: 2018-11-25 00:00:01 -- -- Arguments: -- --

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

-- -- Return value: Parsed date or error message dateParseISO8601 :: Text -> Either DateParseISO8601Error UTCTime -- | Formats error message to be used with Show -- -- Arguments: -- --

exc :: Typeable: Error record or exception
msg :: Text: Error message

-- -- Return value: String containing the type name of error and a message errorShow :: Typeable e => e -> Text -> String -- | Passes specified Storable value as a pointer (to that value) -- to the specified IO action -- -- Arguments: -- --

val :: Storable a: Input value
fun :: Ptr a -> IO b: IO action to run

fun :: Ptr (Ptr a) -> IO b: IO action to run

text :: Text: Input string
fun :: CString -> IO a: IO action to run

text :: Text: Input string
fun :: Ptr Word16 -> IO a: IO action to run

-- -- Return value: Value returned from IO action ffiWithUTF16 :: Text -> (Ptr Word16 -> IO a) -> IO a -- | 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 () -- | Content-Type header for application/json type httpContentTypeJSON :: Header -- | Reads a body of the specified HTTP request and parses it as a JSON -- value -- -- Data type should be specified with a type annotation: -- -- Example: -- --

--   dt <- httpRequestBodyJSON req :: IO Foo
--

-- -- Data must be an instance of FromJSON -- -- Throws an exception if request body doesn't contain valid JSON. -- -- Arguments: -- --

req :: Request: HTTP request

-- -- Return value: Request body parsed as a JSON value httpRequestBodyJSON :: forall a. FromJSON a => Request -> IO a -- | Reads a body of the specified HTTP request as a Text string -- -- Arguments: -- --

req :: Request: HTTP request

-- -- Return value: Request body as a Text string httpRequestBodyText :: Request -> IO Text -- | URL path string of the specified HTTP request -- -- Arguments: -- --

req :: Request: HTTP request

-- -- Return value: URL path string httpRequestPath :: Request -> Text -- | Headers of the specified HTTP request as a Vector of -- (name, value) pairs -- -- Arguments: -- --

req :: Request: HTTP request

req :: Request: HTTP request

-- -- Return value: Request headers as a name -> value map httpRequestHeadersMap :: Request -> HashMap Text Text -- | Read a body of HTTP response as a lazy ByteString -- -- Throws an exception if specified threshold is exceeded. -- -- Arguments: -- --

label :: Text: Label used for error reporting on -- overly-large responses
resp :: Response BodyReader: HTTP response
threshold :: Int Max response body length in bytes

-- -- Return value: Response body as a lazy ByteString httpResponseBody :: Text -> Response BodyReader -> Int -> IO ByteString -- | Read a body of HTTP response as a JSON value -- -- Data type should be specified with a type annotation: -- -- Example: -- --

--   dt <- httpResponseBodyJSON label resp 1024 :: IO Foo
--

-- -- Data must be an instance of FromJSON -- -- Throws an exception if response body doesn't contain valid JSON. -- -- Arguments: -- --

label :: Text: Label used for error reporting on -- overly-large responses
resp :: Response BodyReader: HTTP response
threshold :: Int Max response body length in bytes

-- -- Return value: Response body as a JSON value httpResponseBodyJSON :: forall a. FromJSON a => Text -> Response BodyReader -> Int -> IO a -- | Read a body of HTTP response as a Text string -- -- Arguments: -- --

label :: Text: Label used for error reporting on -- overly-large responses
resp :: Response BodyReader: HTTP response
threshold :: Int Max response body length in bytes

-- -- Return value: Response body as a Text string httpResponseBodyText :: Text -> Response BodyReader -> Int -> IO Text -- | Headers of the specified HTTP response as a Vector of -- (name, value) pairs -- -- Arguments: -- --

req :: Response: HTTP request

req :: Response: HTTP request

-- -- Return value: Response headers as a name -> value map httpResponseHeadersMap :: Response a -> HashMap Text Text -- | Reads contents of a specified file as a lazy ByteString (with -- streaming) and provides it to the specified callback -- -- Throws IOWithFileBytesException 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 exception 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 Right (dt :: Foo) = jsonDecodeText text
--

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

text :: Text: JSON Text string to parse

-- -- Return value: Decoded data or decoding error jsonDecodeText :: forall a. FromJSON a => Text -> Either JSONDecodeError a -- | Encodes a data into a JSON Text string -- -- Data must be an instance of ToJSON -- -- 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 -- -- Returns 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 Right (fooval :: Int) = jsonGet obj "foo"
--   let Right (barval :: Text) = jsonGet obj "bar"
--

-- -- Arguments: -- --

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

-- -- Return value: Field value or an error jsonGet :: forall a. FromJSON a => Value -> Text -> Either JSONGetError a -- | JSON options with unwrapUnaryRecords flag flipped to -- True jsonUnwrapUnaryOptions :: Options -- | Creates a HashMap from a Vector -- -- Creates a HashMap and fills it using the Vector -- elements as values and elements with key function as keys. -- -- If key function returns duplicate keys for some elements, previous -- entry is replaced with a new one. -- -- Arguments: -- --

vec :: Vector v: Input Vector
keyfun :: (Int -> v -> k): Key function that takes -- an element index and element and returns the map key

-- -- Return value: HashMap filled with elements from input -- Vector mapFromVector :: (Eq k, Hashable k) => Vector v -> (Int -> v -> k) -> HashMap k v type Parser = Parsec Text () -- | Finds a line containing a specified substring -- -- Uses LF as a line separator -- -- Resulting line doesn't contain a line separator -- -- Arguments: -- --

needle :: Text: Substring to find

prefix :: Text: Prefix to find

prefix :: Text: Prefix that should be skipped

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

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 () -- | Lazily reads contents from a specified file and parses it using the -- specified parser -- -- File contents are decoded as UTF-8 -- -- Throws an exception 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) -- -- Returns 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 or parsing -- error parsecParseText :: Parser a -> Text -> Either ParsecParseTextError a -- | 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 -- -- Specified postfix must be non-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 -- | Spawns a new process and waits for it to exit -- -- Arguments: -- --

executable :: Text: Path to executable binary
args :: Vector Text: Arguments to pass to executable
out :: Text Path to a file, where std output (both -- stdout and stderr) will be written

-- -- Return value: Process exit code processSpawnAndWait :: Text -> Vector Text -> Text -> IO Int -- | Decodes ByteString into Text using UTF-8 -- encoding -- -- Invalid byte sequences are replaced with U+FFFD -- -- Arguments: -- --

bytes :: ByteString: Byte string

-- -- Return value: Text string textDecodeUtf8 :: ByteString -> Text -- | Formats specified template with specified parameters Vector -- -- Template must use {} string for placeholders. -- -- If length of parameters Vector is less than a number of holes -- in template, then remaining parameters are filled with empty strings. -- If parameters vector is too long, excessive parameters are ignored. -- -- Template preparation is relatively expensive, consider using -- textFormatParts for frequently used templates. -- -- Arguments: -- --

template :: Text: string parts
params :: Vector Text parameters to intersperse into the -- parts

-- -- Return value: Vector Text vector containing the parts of the -- input string textFormat :: Text -> Vector Text -> Text -- | Concatenates specified Vector of string parts interspersing -- it with specified parameters -- -- If length of parameters Vector is less than a number of parts -- - 1, then remaining parameters are filled with empty strings. If -- parameters vector is too long, excessive parameters are ignored. -- -- Arguments: -- --

parts :: Vector Text: string parts
params :: Vector Text parameters to intersperse into the -- parts

-- -- Return value: Vector Text vector containing the parts of the -- input string textFormatParts :: Vector Text -> Vector Text -> Text -- | Stringifies 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

haystack :: Text: string to split
needle :: Text delimiter

-- -- Return value: Vector Text vector containing the parts of the -- input string textSplit :: Text -> Text -> Vector Text -- | Vector utilities module VtUtils.Vector -- | Finds the fist two elements which have the same key value for the -- specified key function -- -- Arguments: -- --

vec :: Vector a: Vector to search duplicate in
keyfun :: (Int -> a -> k) Key function, takes index -- and element as an input

-- -- Return value: two indices pointing the duplicate elements, -- Nothing if no duplicates were found vectorFirstDuplicate :: (Eq k, Hashable k) => Vector a -> (Int -> a -> k) -> Maybe (Int, Int) -- | HUnit utilities module VtUtils.HUnit -- | Exception which indicates that specified test group is invalid data HUnitGroupLabelNotSpecifiedException -- | Exception thrown on the duplicate group label data HUnitDuplicateGroupLabelException -- | Exception thrown if specified label not found data HUnitLabelNotFoundException -- | Exception thrown if specified group does not contain a list of tests data HUnitNonListGroupException -- | Exception for hunitCatchException function data HUnitExpectedExceptionNotThrown -- | Runs the specified action and catches and returs exception of the -- specified type -- -- Throws an exception, if exception of specified type is not thrown by -- the specified action -- -- Arguments: -- --

msg :: Text: Error message to include with exception that -- is thrown on error
action :: IO a IO action that should throw the -- exception

-- -- Return value: exception record thrown by the specified action hunitCatchException :: Exception e => Text -> IO a -> IO e -- | Exception for hunitMain function data HUnitMainException -- | 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 exception 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 exception if no tests in the specified Vector have -- specified label or if some tests in the specified Vector have -- no label at all -- -- 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 exception 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 () instance GHC.Show.Show VtUtils.HUnit.HUnitExpectedExceptionNotThrown instance GHC.Exception.Type.Exception VtUtils.HUnit.HUnitExpectedExceptionNotThrown instance GHC.Exception.Type.Exception VtUtils.HUnit.HUnitMainException instance GHC.Show.Show VtUtils.HUnit.HUnitMainException instance GHC.Exception.Type.Exception VtUtils.HUnit.HUnitNonListGroupException instance GHC.Show.Show VtUtils.HUnit.HUnitNonListGroupException instance GHC.Exception.Type.Exception VtUtils.HUnit.HUnitLabelNotFoundException instance GHC.Show.Show VtUtils.HUnit.HUnitLabelNotFoundException instance GHC.Exception.Type.Exception VtUtils.HUnit.HUnitDuplicateGroupLabelException instance GHC.Show.Show VtUtils.HUnit.HUnitDuplicateGroupLabelException instance GHC.Exception.Type.Exception VtUtils.HUnit.HUnitGroupLabelNotSpecifiedException instance GHC.Show.Show VtUtils.HUnit.HUnitGroupLabelNotSpecifiedException