-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Source code error pretty printing
--   
--   An extremely customizable error pretty printer that can handle many
--   kinds of error formatting. It can handle errors that are connected,
--   disconnected, and those spanning multiple lines.
--   
--   You can get started by importing the <a>Errata</a> module.
@package errata
@version 0.1.0.0


-- | A class for source text types. You should not need to use this, except
--   to add new source types.
module Errata.Source

-- | A class for manipulating and converting source text.
--   
--   For <tt>ByteString</tt> source types, you should convert it to one of
--   the built-in instances with your encoding of choice.
class Source s

-- | Splits the source into lines.
sourceToLines :: Source s => s -> [s]

-- | Converts the source text to <a>Text</a> (strict). The given source
--   text is a single line of the source.
sourceToText :: Source s => s -> Text
instance Errata.Source.Source GHC.Base.String
instance Errata.Source.Source Data.Text.Internal.Text
instance Errata.Source.Source Data.Text.Internal.Lazy.Text


-- | Type definitions. Most of these are re-exported in <a>Errata</a>, so
--   you should not need to import this module, unless you need some of the
--   helper functions for making new functionality on top of Errata.
module Errata.Types

-- | A collection of information for pretty printing an error.
data Errata
Errata :: Maybe Text -> Block -> [Block] -> Maybe Text -> Errata

-- | The message that appears above all the blocks.
[errataHeader] :: Errata -> Maybe Text

-- | The main error block, which will be used for sorting errors.
[errataBlock] :: Errata -> Block

-- | Extra blocks in the source code to display. Blocks themselves are not
--   sorted.
[errataBlocks] :: Errata -> [Block]

-- | The message that appears below all the blocks.
[errataBody] :: Errata -> Maybe Text

-- | Information about a block in the source code, such as pointers and
--   messages.
--   
--   Each block has a style associated with it.
data Block
Block :: Style -> (FilePath, Int, Int) -> [Pointer] -> Maybe Text -> Block

-- | The style of the block.
[blockStyle] :: Block -> Style

-- | The filepath, line, and column of the block. These start at 1.
--   
--   This is used for sorting errors, as well as to create the text that
--   details the location.
[blockLocation] :: Block -> (FilePath, Int, Int)

-- | The block's pointers. These are used to "point out" parts of the
--   source code in this block.
--   
--   The locations of each of these pointers must be non-overlapping. If
--   the pointers are touching at a boundary however, that is allowed.
[blockPointers] :: Block -> [Pointer]

-- | The message for the block. This will appear below the source lines.
[blockBody] :: Block -> Maybe Text

-- | A pointer is the span of the source code at a line, from one column to
--   another. Each of the positions start at 1.
--   
--   A pointer may also have a label that will display inline.
--   
--   A pointer may also be connected to all the other pointers within the
--   same block.
data Pointer
Pointer :: Int -> Int -> Int -> Bool -> Maybe Text -> Pointer

-- | The line of the pointer.
[pointerLine] :: Pointer -> Int

-- | The starting column of the pointer.
[pointerColStart] :: Pointer -> Int

-- | The ending column of the pointer.
[pointerColEnd] :: Pointer -> Int

-- | Whether this pointer connects with other pointers.
[pointerConnect] :: Pointer -> Bool

-- | An optional label for the pointer.
[pointerLabel] :: Pointer -> Maybe Text

-- | Gets the column span for a <a>Pointer</a>.
pointerColumns :: Pointer -> (Int, Int)

-- | Stylization options for a block, e.g. characters to use.
data Style
Style :: ((FilePath, Int, Int) -> Text) -> (Int -> Text) -> ([(Int, Int)] -> Text -> Text) -> Text -> Text -> Text -> Text -> Text -> Text -> Text -> Text -> Style

-- | Shows the location of a block at a file, line, and column.
[styleLocation] :: Style -> (FilePath, Int, Int) -> Text

-- | Shows the line number <i>n</i> for a source line. The result should
--   visually be the same length as just <tt>show n</tt>.
[styleNumber] :: Style -> Int -> Text

-- | Stylize a source line.
--   
--   Column pointers of the text that are being underlined are given for
--   highlighting purposes. The result of this should visually take up the
--   same space as the original line.
[styleLine] :: Style -> [(Int, Int)] -> Text -> Text

-- | The text to use as an ellipsis in the position of line numbers for
--   when lines are omitted. This should visually be one character.
[styleEllipsis] :: Style -> Text

-- | The prefix before the source lines.
[styleLinePrefix] :: Style -> Text

-- | The text to underline a character in a pointer. This should visually
--   be one character.
[styleUnderline] :: Style -> Text

-- | The text to use as a vertical bar when connecting pointers. This
--   should visually be one character.
[styleVertical] :: Style -> Text

-- | The text to use as a horizontal bar when connecting pointers. This
--   should visually be one character.
[styleHorizontal] :: Style -> Text

-- | The text to use as a connector downwards and rightwards when
--   connecting pointers. This should visually be one character.
[styleDownRight] :: Style -> Text

-- | The text to use as a connector upwards and rightwards when connecting
--   pointers. This should visually be one character.
[styleUpRight] :: Style -> Text

-- | The text to use as a connector upwards, downwards, and rightwards when
--   connecting pointers. This should visually be one character.
[styleUpDownRight] :: Style -> Text

-- | Adds highlighting to spans of text by enclosing it with some text e.g
--   ANSI escape codes.
highlight :: Text -> Text -> [(Int, Int)] -> Text -> Text


-- | Functions for rendering the errors. You should not need to import
--   this, as these functions are lower-level.
--   
--   This module is internal, and may break across non-breaking versions.
module Errata.Internal.Render

-- | Renders errors.
renderErrors :: Source source => source -> [Errata] -> Builder

-- | A single pretty error from metadata and source lines.
renderErrata :: Source source => Seq source -> Errata -> Builder

-- | A single pretty block from block data and source lines.
renderBlock :: Source source => Seq source -> Block -> Builder

-- | The source lines for a block.
renderSourceLines :: Source source => Seq source -> Block -> NonEmpty Pointer -> Builder


-- | This module is for creating pretty error messages. We assume very
--   little about the format you want to use, so much of this module is to
--   allow you to customize your error messages.
--   
--   To get started, see the documentation for <a>prettyErrors</a>. When
--   using this module, we recommend you turn on the
--   <tt>OverloadedStrings</tt> extension and import <a>Data.Text</a> at
--   the very least due to the use of <a>Text</a> (strict).
--   
--   The overall workflow to use the printer is to convert your error type
--   to <a>Errata</a>, which entails converting your errors to
--   <a>Errata</a> by filling in messages and <a>Block</a>s. You can create
--   <a>Errata</a> and <a>Block</a> from their constructors, or use the
--   convenience functions for common usecases, like <a>errataSimple</a>
--   and <a>blockSimple</a>.
module Errata

-- | A collection of information for pretty printing an error.
data Errata
Errata :: Maybe Text -> Block -> [Block] -> Maybe Text -> Errata

-- | The message that appears above all the blocks.
[errataHeader] :: Errata -> Maybe Text

-- | The main error block, which will be used for sorting errors.
[errataBlock] :: Errata -> Block

-- | Extra blocks in the source code to display. Blocks themselves are not
--   sorted.
[errataBlocks] :: Errata -> [Block]

-- | The message that appears below all the blocks.
[errataBody] :: Errata -> Maybe Text

-- | Creates a simple error that has a single block, with an optional
--   header or body.
errataSimple :: Maybe Text -> Block -> Maybe Text -> Errata

-- | Information about a block in the source code, such as pointers and
--   messages.
--   
--   Each block has a style associated with it.
data Block
Block :: Style -> (FilePath, Int, Int) -> [Pointer] -> Maybe Text -> Block

-- | The style of the block.
[blockStyle] :: Block -> Style

-- | The filepath, line, and column of the block. These start at 1.
--   
--   This is used for sorting errors, as well as to create the text that
--   details the location.
[blockLocation] :: Block -> (FilePath, Int, Int)

-- | The block's pointers. These are used to "point out" parts of the
--   source code in this block.
--   
--   The locations of each of these pointers must be non-overlapping. If
--   the pointers are touching at a boundary however, that is allowed.
[blockPointers] :: Block -> [Pointer]

-- | The message for the block. This will appear below the source lines.
[blockBody] :: Block -> Maybe Text

-- | A simple block that points to only one line and optionally has a label
--   or a body message.
blockSimple :: Style -> FilePath -> Int -> (Int, Int) -> Maybe Text -> Maybe Text -> Block

-- | A variant of <a>blockSimple</a> that only points at one column.
blockSimple' :: Style -> FilePath -> Int -> Int -> Maybe Text -> Maybe Text -> Block

-- | A block that points to two parts of the source that are visually
--   connected together.
blockConnected :: Style -> FilePath -> (Int, Int, Int, Maybe Text) -> (Int, Int, Int, Maybe Text) -> Maybe Text -> Block

-- | A variant of <a>blockConnected</a> where the pointers point at only
--   one column.
blockConnected' :: Style -> FilePath -> (Int, Int, Maybe Text) -> (Int, Int, Maybe Text) -> Maybe Text -> Block

-- | A block that points to two parts of the source that are visually
--   connected together.
--   
--   If the two parts of the source happen to be on the same line, the
--   pointers are merged into one.
blockMerged :: Style -> FilePath -> (Int, Int, Int, Maybe Text) -> (Int, Int, Int, Maybe Text) -> Maybe Text -> Maybe Text -> Block

-- | A variant of <a>blockMerged</a> where the pointers point at only one
--   column.
blockMerged' :: Style -> FilePath -> (Int, Int, Maybe Text) -> (Int, Int, Maybe Text) -> Maybe Text -> Maybe Text -> Block

-- | A pointer is the span of the source code at a line, from one column to
--   another. Each of the positions start at 1.
--   
--   A pointer may also have a label that will display inline.
--   
--   A pointer may also be connected to all the other pointers within the
--   same block.
data Pointer
Pointer :: Int -> Int -> Int -> Bool -> Maybe Text -> Pointer

-- | The line of the pointer.
[pointerLine] :: Pointer -> Int

-- | The starting column of the pointer.
[pointerColStart] :: Pointer -> Int

-- | The ending column of the pointer.
[pointerColEnd] :: Pointer -> Int

-- | Whether this pointer connects with other pointers.
[pointerConnect] :: Pointer -> Bool

-- | An optional label for the pointer.
[pointerLabel] :: Pointer -> Maybe Text

-- | Stylization options for a block, e.g. characters to use.
data Style
Style :: ((FilePath, Int, Int) -> Text) -> (Int -> Text) -> ([(Int, Int)] -> Text -> Text) -> Text -> Text -> Text -> Text -> Text -> Text -> Text -> Text -> Style

-- | Shows the location of a block at a file, line, and column.
[styleLocation] :: Style -> (FilePath, Int, Int) -> Text

-- | Shows the line number <i>n</i> for a source line. The result should
--   visually be the same length as just <tt>show n</tt>.
[styleNumber] :: Style -> Int -> Text

-- | Stylize a source line.
--   
--   Column pointers of the text that are being underlined are given for
--   highlighting purposes. The result of this should visually take up the
--   same space as the original line.
[styleLine] :: Style -> [(Int, Int)] -> Text -> Text

-- | The text to use as an ellipsis in the position of line numbers for
--   when lines are omitted. This should visually be one character.
[styleEllipsis] :: Style -> Text

-- | The prefix before the source lines.
[styleLinePrefix] :: Style -> Text

-- | The text to underline a character in a pointer. This should visually
--   be one character.
[styleUnderline] :: Style -> Text

-- | The text to use as a vertical bar when connecting pointers. This
--   should visually be one character.
[styleVertical] :: Style -> Text

-- | The text to use as a horizontal bar when connecting pointers. This
--   should visually be one character.
[styleHorizontal] :: Style -> Text

-- | The text to use as a connector downwards and rightwards when
--   connecting pointers. This should visually be one character.
[styleDownRight] :: Style -> Text

-- | The text to use as a connector upwards and rightwards when connecting
--   pointers. This should visually be one character.
[styleUpRight] :: Style -> Text

-- | The text to use as a connector upwards, downwards, and rightwards when
--   connecting pointers. This should visually be one character.
[styleUpDownRight] :: Style -> Text

-- | A basic style using only ASCII characters.
--   
--   Errors should look like so:
--   
--   <pre>
--   error header message
--   --&gt; file.ext:1:16
--     |
--   1 |   line 1 foo bar do
--     |  ________________^^ start label
--   2 | | line 2
--     | |      ^ unconnected label
--   3 | | line 3
--   . | |______^ middle label
--   6 | | line 6
--   7 | | line 7 baz end
--     | |______^_____^^^ end label
--     |        |
--     |        | inner label
--   block body message
--   error body message
--   </pre>
basicStyle :: Style

-- | A fancy style using Unicode characters.
--   
--   Errors should look like so:
--   
--   <pre>
--   error header message
--   → file.ext:1:16
--     │
--   1 │   line 1 foo bar do
--     │ ┌────────────────^^ start label
--   2 │ │ line 2
--     │ │      ^ unconnected label
--   3 │ │ line 3
--   . │ ├──────^ middle label
--   6 │ │ line 6
--   7 │ │ line 7 baz end
--     │ └──────^─────^^^ end label
--     │        │
--     │        └ inner label
--   block body message
--   error body message
--   </pre>
fancyStyle :: Style

-- | A fancy style using Unicode characters and ANSI colors, similar to
--   <a>fancyStyle</a>. Most things are colored red.
fancyRedStyle :: Style

-- | A fancy style using Unicode characters and ANSI colors, similar to
--   <a>fancyStyle</a>. Most things are colored yellow.
fancyYellowStyle :: Style

-- | Pretty prints errors. The original source is required. Returns
--   <a>Text</a> (lazy). If the list is empty, an empty string is returned.
--   
--   Suppose we had an error of this type:
--   
--   <pre>
--   data ParseError = ParseError
--       { peFile       :: FilePath
--       , peLine       :: Int
--       , peCol        :: Int
--       , peUnexpected :: T.Text
--       , peExpected   :: [T.Text]
--       }
--   </pre>
--   
--   Then we can create a simple pretty printer like so:
--   
--   <pre>
--   import qualified Data.List.NonEmpty as N
--   import qualified Data.Text as T
--   import qualified Data.Text.Lazy.IO as TL
--   import           Errata
--   
--   toErrata :: ParseError -&gt; Errata
--   toErrata (ParseError fp l c unexpected expected) =
--       errataSimple
--           (Just "error: invalid syntax")
--           (blockSimple basicStyle fp l (c, c + T.length unexpected) Nothing
--               (Just $ "unexpected " &lt;&gt; unexpected &lt;&gt; "\nexpected " &lt;&gt; T.intercalate ", " expected))
--           Nothing
--   
--   printErrors :: T.Text -&gt; [ParseError] -&gt; IO ()
--   printErrors source es = TL.putStrLn $ prettyErrors source (toErrata &lt;$&gt; es)
--   </pre>
--   
--   Note that in the above example, we have <tt>OverloadedStrings</tt>
--   enabled to reduce uses of <a>pack</a>.
--   
--   An example error message from this might be:
--   
--   <pre>
--   error: invalid syntax
--   --&gt; ./comma.json:2:18
--     |
--   2 |     "bad": [1, 2,]
--     |                  ^
--   unexpected ]
--   expected null, true, false, ", -, digit, [, {
--   </pre>
prettyErrors :: Source source => source -> [Errata] -> Text

-- | A variant of <a>prettyErrors</a> for non-empty lists. You can ensure
--   the output is never an empty string.
prettyErrorsNE :: Source source => source -> NonEmpty Errata -> Text