-- 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.4.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

-- | The empty source, used when a pointer references an out-of-bounds
--   line.
emptySource :: Source s => 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

-- | Line number, starts at 1, increments every new line character.
type Line = Int

-- | Column number, starts at 1, increments every <a>Char</a>.
type Column = Int

-- | Header text. Generally goes above things.
type Header = Text

-- | Body text. Generally goes below things.
type Body = Text

-- | Label text. Generally goes inline with things.
type Label = Text

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

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

-- | Blocks in the source code to display.
[errataBlocks] :: Errata -> [Block]

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

-- | 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, Line, Column) -> Maybe Header -> [Pointer] -> Maybe Body -> Block

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

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

-- | The header message for the block.
--   
--   This will appear below the location and above the source lines.
[blockHeader] :: Block -> Maybe Header

-- | 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 body message for the block.
--   
--   This will appear below the source lines.
[blockBody] :: Block -> Maybe Body

-- | 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 :: Line -> Column -> Column -> Bool -> Maybe Label -> PointerStyle -> Pointer

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

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

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

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

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

-- | A style for this pointer.
[pointerStyle] :: Pointer -> PointerStyle

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

-- | Gets physical information about a pointer.
pointerData :: Pointer -> (Line, Column, Column, Bool, Maybe Label)

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

-- | Shows the location of a block at a file, line, and column.
--   
--   This is put on its own line just above the source lines.
[styleLocation] :: Style -> (FilePath, Line, Column) -> 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 -> Line -> Text

-- | Stylize a source line.
--   
--   The style and the column span (sorted, starting at 1) of the text that
--   is being underlined are given for highlighting purposes (see
--   <a>highlight</a>). They can be ignored for source code highlighting
--   instead, for example. The result of this should visually take up the
--   same space as the original line.
[styleLine] :: Style -> [(PointerStyle, (Column, Column))] -> 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.
--   
--   Before it may be the line number, and after it the source line.
[styleLinePrefix] :: 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

-- | The number of spaces a tab character is equivalent to.
--   
--   Your source will have tabs replaced with this many spaces.
[styleTabWidth] :: Style -> Int

-- | Maximum number of extra lines that can be added after the first line
--   when skipping lines between two lines.
[styleExtraLinesAfter] :: Style -> Int

-- | Maximum number of extra lines that can be added before the second line
--   when skipping lines between two lines.
[styleExtraLinesBefore] :: Style -> Int

-- | Whether to add a padding line before the first source line.
[stylePaddingTop] :: Style -> Bool

-- | Whether to add a padding line after the last source line.
[stylePaddingBottom] :: Style -> Bool

-- | Whether to enable decorations at all in this block.
--   
--   This includes the pointer connectors (as in <a>Style</a>) and the
--   underlines, connectors, and labels (as in <a>PointerStyle</a>).
--   However, highlighting will still be applied.
[styleEnableDecorations] :: Style -> Bool

-- | Whether to enable the line prefix.
[styleEnableLinePrefix] :: Style -> Bool

-- | Stylization options for an individual pointer, e.g. characters to use.
data PointerStyle
PointerStyle :: (Text -> Text) -> Text -> Text -> Text -> Bool -> PointerStyle

-- | Stylize the text that this pointer is underlining.
--   
--   This is only used if <a>styleLine</a> uses the given pointer styles,
--   for example with <a>highlight</a>. The result of this should visually
--   take up the same space as the original text.
[styleHighlight] :: PointerStyle -> Text -> Text

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

-- | The text to use as a connector upwards and hooking to the right for
--   the label of a pointer that drops down.
--   
--   This probably looks best as one character.
[styleHook] :: PointerStyle -> Text

-- | The text to use as a vertical bar when connecting a pointer that drops
--   down to its label.
--   
--   This should visually be one character.
[styleConnector] :: PointerStyle -> Text

-- | Whether to use the hook for labels that drop down, or simply start the
--   label directly under the connector.
[styleEnableHook] :: PointerStyle -> Bool
instance GHC.Show.Show Errata.Types.Pointer
instance GHC.Show.Show Errata.Types.Block
instance GHC.Show.Show Errata.Types.Errata
instance GHC.Show.Show Errata.Types.Style
instance GHC.Show.Show Errata.Types.PointerStyle


-- | Premade styles for blocks and pointers.
module Errata.Styles

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

-- | Pointers using only ASCII characters.
basicPointer :: PointerStyle

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

-- | Pointers using Unicode characters and ANSI colors.
fancyPointer :: PointerStyle

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

-- | Red pointers using Unicode characters and ANSI colors.
fancyRedPointer :: PointerStyle

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

-- | Yellow pointers using Unicode characters and ANSI colors.
fancyYellowPointer :: PointerStyle

-- | Adds highlighting to spans of text by modifying it with the given
--   styles' highlights.
highlight :: [(PointerStyle, (Column, Column))] -> 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 a collection of <a>Errata</a>.
renderErrors :: Source source => source -> [Errata] -> Builder

-- | Renders a single <a>Errata</a>.
renderErrata :: Source source => IntMap [source] -> Errata -> [IntMap [Pointer]] -> [Line] -> [Line] -> Builder

-- | Renders a single block.
renderBlock :: Source source => IntMap [source] -> Block -> IntMap [Pointer] -> (Line, Line) -> Builder

-- | Renders the source lines for a block.
renderSourceLines :: forall source. Source source => [(Line, source)] -> Block -> Int -> IntMap [Pointer] -> Maybe Builder

-- | Group the pointers of a block by the line they appear on.
groupBlockPointers :: Block -> IntMap [Pointer]

-- | Turns a list into a list of tail slices of the original list, with
--   each element at index <tt>i</tt> dropping the first <tt>i</tt>
--   elements of the original list and tailing an <a>emptySource</a>.
--   
--   This allows for correct behavior on out-of-source-bounds pointers.
slices :: Source a => [a] -> [[a]]

-- | Create a source table from the given line span and source lines.
makeSourceTable :: Source a => Line -> Line -> [a] -> IntMap [a]


-- | 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 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>.
--   
--   For premade styles for blocks and pointers, take a look at
--   <a>Errata.Styles</a>.
--   
--   For easier reading, we define:
--   
--   <pre>
--   type Line = Int
--   type Column = Int
--   type Header = Text
--   type Body = Text
--   type Label = Text
--   </pre>
module Errata

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

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

-- | Blocks in the source code to display.
[errataBlocks] :: Errata -> [Block]

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

-- | Creates a simple error that has a single block, with an optional
--   header or body.
errataSimple :: Maybe Header -> Block -> Maybe Body -> 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, Line, Column) -> Maybe Header -> [Pointer] -> Maybe Body -> Block

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

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

-- | The header message for the block.
--   
--   This will appear below the location and above the source lines.
[blockHeader] :: Block -> Maybe Header

-- | 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 body message for the block.
--   
--   This will appear below the source lines.
[blockBody] :: Block -> Maybe Body

-- | A simple block that points to only one line and optionally has a
--   label, header, or body message.
blockSimple :: Style -> PointerStyle -> FilePath -> Maybe Header -> (Line, Column, Column, Maybe Label) -> Maybe Body -> Block

-- | A variant of <a>blockSimple</a> that only points at one column.
blockSimple' :: Style -> PointerStyle -> FilePath -> Maybe Header -> (Line, Column, Maybe Label) -> Maybe Body -> Block

-- | A block that points to two parts of the source that are visually
--   connected together.
blockConnected :: Style -> PointerStyle -> FilePath -> Maybe Header -> (Line, Column, Column, Maybe Label) -> (Line, Column, Column, Maybe Label) -> Maybe Body -> Block

-- | A variant of <a>blockConnected</a> where the pointers point at only
--   one column.
blockConnected' :: Style -> PointerStyle -> FilePath -> Maybe Header -> (Line, Column, Maybe Label) -> (Line, Column, Maybe Label) -> Maybe Body -> 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 -> PointerStyle -> FilePath -> Maybe Header -> (Line, Column, Column, Maybe Label) -> (Line, Column, Column, Maybe Label) -> Maybe Label -> Maybe Body -> Block

-- | A variant of <a>blockMerged</a> where the pointers point at only one
--   column.
blockMerged' :: Style -> PointerStyle -> FilePath -> Maybe Header -> (Line, Column, Maybe Label) -> (Line, Column, Maybe Label) -> Maybe Label -> Maybe Body -> 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 :: Line -> Column -> Column -> Bool -> Maybe Label -> PointerStyle -> Pointer

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

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

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

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

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

-- | A style for this pointer.
[pointerStyle] :: Pointer -> PointerStyle

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

-- | Shows the location of a block at a file, line, and column.
--   
--   This is put on its own line just above the source lines.
[styleLocation] :: Style -> (FilePath, Line, Column) -> 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 -> Line -> Text

-- | Stylize a source line.
--   
--   The style and the column span (sorted, starting at 1) of the text that
--   is being underlined are given for highlighting purposes (see
--   <a>highlight</a>). They can be ignored for source code highlighting
--   instead, for example. The result of this should visually take up the
--   same space as the original line.
[styleLine] :: Style -> [(PointerStyle, (Column, Column))] -> 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.
--   
--   Before it may be the line number, and after it the source line.
[styleLinePrefix] :: 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

-- | The number of spaces a tab character is equivalent to.
--   
--   Your source will have tabs replaced with this many spaces.
[styleTabWidth] :: Style -> Int

-- | Maximum number of extra lines that can be added after the first line
--   when skipping lines between two lines.
[styleExtraLinesAfter] :: Style -> Int

-- | Maximum number of extra lines that can be added before the second line
--   when skipping lines between two lines.
[styleExtraLinesBefore] :: Style -> Int

-- | Whether to add a padding line before the first source line.
[stylePaddingTop] :: Style -> Bool

-- | Whether to add a padding line after the last source line.
[stylePaddingBottom] :: Style -> Bool

-- | Whether to enable decorations at all in this block.
--   
--   This includes the pointer connectors (as in <a>Style</a>) and the
--   underlines, connectors, and labels (as in <a>PointerStyle</a>).
--   However, highlighting will still be applied.
[styleEnableDecorations] :: Style -> Bool

-- | Whether to enable the line prefix.
[styleEnableLinePrefix] :: Style -> Bool

-- | Stylization options for an individual pointer, e.g. characters to use.
data PointerStyle
PointerStyle :: (Text -> Text) -> Text -> Text -> Text -> Bool -> PointerStyle

-- | Stylize the text that this pointer is underlining.
--   
--   This is only used if <a>styleLine</a> uses the given pointer styles,
--   for example with <a>highlight</a>. The result of this should visually
--   take up the same space as the original text.
[styleHighlight] :: PointerStyle -> Text -> Text

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

-- | The text to use as a connector upwards and hooking to the right for
--   the label of a pointer that drops down.
--   
--   This probably looks best as one character.
[styleHook] :: PointerStyle -> Text

-- | The text to use as a vertical bar when connecting a pointer that drops
--   down to its label.
--   
--   This should visually be one character.
[styleConnector] :: PointerStyle -> Text

-- | Whether to use the hook for labels that drop down, or simply start the
--   label directly under the connector.
[styleEnableHook] :: PointerStyle -> Bool

-- | 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.Text as T
--   import qualified Data.Text.Lazy.IO as TL
--   import           <a>Errata</a>
--   
--   toErrata :: ParseError -&gt; <a>Errata</a>
--   toErrata (ParseError fp l c unexpected expected) =
--       <a>errataSimple</a>
--           (Just "an error occured!")
--           (<a>blockSimple</a> <a>basicStyle</a> <a>basicPointer</a> fp
--               (Just "error: invalid syntax")
--               (l, c, c + T.length unexpected, Just "this one")
--               (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 $ <a>prettyErrors</a> source (map toErrata 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>
--   an error occured!
--   --&gt; ./comma.json:2:18
--   error: invalid syntax
--     |
--   2 |     "bad": [1, 2,]
--     |                  ^ this one
--   unexpected ]
--   expected null, true, false, ", -, digit, [, {
--   </pre>
prettyErrors :: Source source => source -> [Errata] -> Text