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


-- | A YAML 1.2.2 library written in Haskell. Main features:
--   
--   <ul>
--   <li>Conformance: the parser passes all cases of the <a>YAML test
--   suite</a>.</li>
--   <li>Performance: decoding and encoding are very fast, see the
--   <a>benchmarks</a>.</li>
--   <li>Decoding and encoding with the classes <tt>FromYaml</tt> and
--   <tt>ToYaml</tt>, with instances for common types.</li>
--   <li>Instances for your own data types, derived via
--   <tt>GenericYaml</tt>. Inspection tests check that the generic
--   representation optimizes away for common shapes of data types.</li>
--   <li>Errors with the line, the column and the path of the problem, e.g.
--   <tt>jobs[1].name</tt>. The decoder reports the errors of independent
--   parts together, e.g. every bad field of a record.</li>
--   <li>A syntax tree that keeps the comments and the empty lines. A
--   program can change a file and write it back with its comments, and a
--   decoded value can keep a part of the document as it was written.</li>
--   <li>Output that YAML 1.1 parsers read the same way, e.g. PyYAML and
--   go-yaml v2, which Kubernetes uses.</li>
--   <li>Safe for untrusted input. The time of a decode is close to linear
--   in the size of the input, and the memory is linear.</li>
--   </ul>
--   
--   See also <a>yamlet-aeson</a>, which decodes and encodes YAML with the
--   <tt>FromJSON</tt> and <tt>ToJSON</tt> instances of aeson, e.g. in a
--   program that moves from the yaml package to yamlet.
@package yamlet
@version 1.0.0.1


-- | The bytes of UTF-8 encoded YAML and the classes of characters that the
--   parser, the renderer and the error messages share.
--   
--   This module is intended for internal use only, and may change without
--   warning in subsequent releases.
module Yamlet.Internal.Chars
pattern TAB :: Word8
pattern LF :: Word8
pattern CR :: Word8
pattern SPACE :: Word8
pattern EXCL :: Word8
pattern DQUOTE :: Word8
pattern HASH :: Word8
pattern PERCENT :: Word8
pattern AMP :: Word8
pattern SQUOTE :: Word8
pattern STAR :: Word8
pattern PLUS :: Word8
pattern COMMA :: Word8
pattern MINUS :: Word8
pattern DOT :: Word8
pattern DIGIT_0 :: Word8
pattern DIGIT_1 :: Word8
pattern DIGIT_9 :: Word8
pattern COLON :: Word8
pattern LESS :: Word8
pattern GREATER :: Word8
pattern QUESTION :: Word8
pattern AT :: Word8
pattern UPPER_A :: Word8
pattern UPPER_F :: Word8
pattern UPPER_Z :: Word8
pattern LBRACKET :: Word8
pattern BACKSLASH :: Word8
pattern RBRACKET :: Word8
pattern GRAVE :: Word8
pattern LOWER_A :: Word8
pattern LOWER_F :: Word8
pattern LOWER_U :: Word8
pattern LOWER_Z :: Word8
pattern LBRACE :: Word8
pattern PIPE :: Word8
pattern RBRACE :: Word8
pattern DEL :: Word8
isWhite :: Word8 -> Bool
isBreak :: Word8 -> Bool
isAsciiByte :: Word8 -> Bool

-- | A predicate on bytes for a character, e.g. <a>isFlowIndicator</a> for
--   the emitter. A character beyond ASCII does not satisfy it.
asciiChar :: (Word8 -> Bool) -> Char -> Bool

-- | The byte starts a character in UTF-8, i.e. it is not a continuation
--   byte.
isCharStart :: Word8 -> Bool

-- | ns-char. Every byte of a multibyte character counts, because the input
--   contains printable characters only, except in quoted scalars, which
--   the parser checks after it parses the stream.
isNsChar :: Word8 -> Bool
isFlowIndicator :: Word8 -> Bool
isIndicator :: Word8 -> Bool
isDecDigit :: Word8 -> Bool
isHexDigit' :: Word8 -> Bool
hexValue :: Word8 -> Int
isWordChar :: Word8 -> Bool

-- | ns-uri-char without the escaped characters.
isUriChar :: Word8 -> Bool

-- | ns-tag-char without the escaped characters.
isTagChar :: Word8 -> Bool
isAnchorChar :: Word8 -> Bool

-- | The number of bytes of a byte order mark, U+FEFF in UTF-8.
bomLength :: Int

-- | A byte order mark at the index of the array, before the end index.
isBomIn :: Array -> Int -> Int -> Bool

-- | The index after the byte order marks at the index of the array, before
--   the end index.
skipBomsIn :: Array -> Int -> Int -> Int


-- | Helpers for the other modules.
--   
--   This module is intended for internal use only, and may change without
--   warning in subsequent releases.
module Yamlet.Internal.Utils

-- | <a>stripPrefix</a>. Before text 2.1.4, <a>stripPrefix</a> compares the
--   texts as streams of characters and allocates for each character. For
--   these versions this is the code of text 2.1.4, which compares the
--   UTF-8 bytes.
textStripPrefix :: Text -> Text -> Maybe Text

-- | <a>isPrefixOf</a>, with the code of text 2.1.4 as in
--   <a>textStripPrefix</a>.
textIsPrefixOf :: Text -> Text -> Bool

-- | The largest number of characters of an implicit key, from the YAML
--   1.2.2 specification.
maxImplicitKeyLength :: Int

-- | The largest number in a version of a <tt>%YAML</tt> directive.
--   
--   Without a limit, the largest number depends on the size of Int, which
--   differs between architectures. The limit is far above any version of
--   YAML, and a number below it times 10 fits in 32 bits.
maxVersion :: Int

-- | The size that an expansion of a small input can always add: the visits
--   that aliases add to a traversal, or the bytes that the prefixes of
--   <tt>%TAG</tt> directives add to the tags. A larger input can add as
--   much as it has.
--   
--   A traversal of 100000 nodes takes about 5 ms and 6 MB, measured with a
--   copy of the nodes. go-yaml allows about 400000 nodes from aliases in a
--   small document.
minExpansion :: Int

-- | The prefix of the tags of the core schema, and of the <tt>!!</tt>
--   handle.
coreTagPrefix :: Text

-- | The number of decimal places of <a>Pico</a>, the resolution of the
--   durations of the time library.
picoDecimals :: Int

-- | The number of decimal places of 1<i>n, or <a>Nothing</a> if 1</i>n has
--   no finite decimal form. It has one if n is 2^a * 5^b, and then it
--   needs max a b places.
decimalPlaces :: Integer -> Maybe Int

-- | The first code unit of a surrogate pair of UTF-16.
isHighSurrogate :: Int -> Bool

-- | The second code unit of a surrogate pair of UTF-16.
isLowSurrogate :: Int -> Bool

-- | The code point of a surrogate pair, by the formula of UTF-16.
fromSurrogates :: Int -> Int -> Int

-- | A code point that a character can have: in the range of Unicode, and
--   not a surrogate.
isScalarValue :: Int -> Bool

-- | The number of hex digits of the <tt>\x</tt>, <tt>\u</tt> and
--   <tt>\U</tt> escapes of a double-quoted scalar.
xEscapeDigits :: Int

-- | The number of hex digits of the <tt>\x</tt>, <tt>\u</tt> and
--   <tt>\U</tt> escapes of a double-quoted scalar.
uEscapeDigits :: Int

-- | The number of hex digits of the <tt>\x</tt>, <tt>\u</tt> and
--   <tt>\U</tt> escapes of a double-quoted scalar.
bigUEscapeDigits :: Int

-- | The number of hex digits of a <tt>%XX</tt> escape in a tag.
percentDigits :: Int

-- | The text in double quotes for a message, with the escapes of a
--   double-quoted scalar for a quote, a backslash and a character that
--   does not print, so that the message stays on one line. Unlike
--   <a>show</a>, it keeps the other characters that are not ASCII, e.g.
--   <tt>"zażółć"</tt>.
showText :: Text -> String

-- | A pair with both components evaluated.
strictPair :: a -> b -> (a, b)

-- | <a>map</a> with the spine and the elements of the result evaluated.
--   The results are in reverse until the end, so that the stack does not
--   grow with the length of the list.
strictMap :: (a -> b) -> [a] -> [b]

-- | The first component of a pair in a result. Unlike <tt><a>fmap</a>
--   <a>fst</a></tt>, it gives no selector thunk inside the result.
firstOfResult :: Either e (a, b) -> Either e a


-- | The types of the syntax tree.
--   
--   This module is intended for internal use only, and may change without
--   warning in subsequent releases.
module Yamlet.Internal.Syntax

-- | A document of a YAML stream.
data Document
Document :: !Maybe YamlVersion -> !Bool -> !Bool -> !Comments -> !Node -> Document

-- | The version from the <tt>%YAML</tt> directive.
[version] :: Document -> !Maybe YamlVersion

-- | The document starts with a <tt>---</tt> marker.
[explicitStart] :: Document -> !Bool

-- | The document ends with a <tt>...</tt> marker.
[explicitEnd] :: Document -> !Bool

-- | The lines before the directives or the <tt>---</tt> marker, the
--   comment on the line of the marker and the lines at the end of the
--   document: below the <tt>...</tt> marker, or below a flow collection
--   root.
[docComments] :: Document -> !Comments
[root] :: Document -> !Node

-- | The version of YAML that a document declares.
data YamlVersion
YamlVersion :: !Int -> !Int -> YamlVersion
[major] :: YamlVersion -> !Int
[minor] :: YamlVersion -> !Int

-- | A document with the given root, without directives, markers and
--   comments.
document :: Node -> Document

-- | A node of a document.
data Node
Node :: !Offset -> !Offset -> !Props -> !Comments -> !Content -> Node

-- | The position of the first character of the content.
[offset] :: Node -> !Offset

-- | The position after the last character of the content.
[endOffset] :: Node -> !Offset
[props] :: Node -> !Props
[comments] :: Node -> !Comments
[content] :: Node -> !Content

-- | The content of a node.
data Content

-- | A scalar with the positions in its text where the source continues on
--   a new line. A position counts the characters from the start of the
--   text, and the positions are in ascending order. The parser gives them
--   for the plain, quoted and folded styles, which join the lines of the
--   source, so that the renderer can write the text on the same lines. The
--   renderer ignores a position where the style of the output cannot start
--   a new line and keep the text.
ScalarLinesContent :: !ScalarStyle -> !Text -> ![Int] -> Content
SequenceContent :: !CollectionStyle -> ![Node] -> Content
MappingContent :: !CollectionStyle -> ![(Node, Node)] -> Content

-- | An alias, with the name of its anchor. An alias has no properties.
AliasContent :: !Text -> Content

-- | A scalar without positions of new lines. As a pattern, it matches
--   every scalar and ignores its positions.
pattern ScalarContent :: ScalarStyle -> Text -> Content

-- | The properties of a node.
data Props
Props :: !Maybe Text -> !Tag -> Props
[anchor] :: Props -> !Maybe Text
[tag] :: Props -> !Tag

-- | No anchor and no tag.
noProps :: Props

-- | The tag of a node after the tag handles are expanded.
data Tag

-- | The node has no tag.
NoTag :: Tag

-- | The <tt>!</tt> tag.
NonSpecificTag :: Tag

-- | A specific tag, e.g. <tt>tag:yaml.org,2002:str</tt> for
--   <tt>!!str</tt>. YAML has no syntax for the empty tag or a tag of one
--   character, e.g. <tt>x</tt> or <tt>!</tt>. The renderer writes such a
--   tag as <tt>!</tt>, which reads back as <a>NonSpecificTag</a>.
Tag :: !Text -> Tag

-- | The style of a scalar: without quotes, in single or double quotes, or
--   a literal (<tt>|</tt>) or folded (<tt>&gt;</tt>) block scalar.
data ScalarStyle
Plain :: ScalarStyle
SingleQuoted :: ScalarStyle
DoubleQuoted :: ScalarStyle
Literal :: ScalarStyle
Folded :: ScalarStyle

-- | The literal or the folded style.
isBlockScalar :: ScalarStyle -> Bool

-- | The style of a collection: with indentation, or with brackets and
--   commas.
data CollectionStyle
Block :: CollectionStyle
Flow :: CollectionStyle

-- | A node with the given content, without properties and comments.
contentNode :: Content -> Node

-- | A scalar in the given style. <a>renderSyntax</a> uses quotes if the
--   style cannot hold the text, and for a block scalar that is a key or an
--   entry of a flow collection.
--   
--   <pre>
--   &gt;&gt;&gt; T.putStr (renderSyntax defaultRenderOptions [document (mappingNode [(plainNode "key", scalarNode Plain "a: b")])])
--   key: 'a: b'
--   </pre>
scalarNode :: ScalarStyle -> Text -> Node

-- | A plain scalar.
plainNode :: Text -> Node

-- | A block sequence.
sequenceNode :: [Node] -> Node

-- | A block mapping.
mappingNode :: [(Node, Node)] -> Node

-- | The comments and the empty lines that belong to a node.
data Comments
Comments :: ![Line] -> !Maybe Text -> ![Line] -> Comments

-- | The lines above the node.
[before] :: Comments -> ![Line]

-- | The comment at the end of the line where the node ends, or of the
--   first line of a block collection or a block scalar. The renderer
--   writes each line break in it as a space. The line breaks are the
--   characters that <a>CommentLine</a> lists.
[inline] :: Comments -> !Maybe Text

-- | The lines below the node: after the last entry of a collection,
--   between the brackets of an empty collection, or below a scalar or an
--   alias in a block collection or at the root. The section
--   <a>Comments</a> gives the rules. The renderer writes such lines below
--   any node.
[after] :: Comments -> ![Line]

-- | No comments and no empty lines.
noComments :: Comments

-- | The node with the comments in place of its own. A record update of the
--   field is ambiguous where <a>Commented</a> is in scope.
withComments :: Comments -> Node -> Node

-- | A value with the comments of its mapping entry:
--   
--   <ul>
--   <li><a>before</a>: the lines above the entry,</li>
--   <li><a>inline</a>: the comment at the end of the line of the key, or
--   of the line where a value on several lines ends,</li>
--   <li><a>after</a>: the lines after the value, e.g. after the last entry
--   of a collection.</li>
--   </ul>
--   
--   A <a>Commented</a> value of a mapping entry has the comments of the
--   entry. A block list or mapping under the key has its own comments: the
--   lines below the key up to the last empty line above its first entry. A
--   <a>Commented</a> value inside the first one keeps them, so a type that
--   keeps both nests two <a>Commented</a> values:
--   
--   <pre>
--   &gt;&gt;&gt; input = "# The CI jobs.\njobs:\n  # Run on every push.\n\n  # Check the formatting.\n  - lint\n"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; T.putStr input
--   # The CI jobs.
--   jobs:
--     # Run on every push.
--   
--     # Check the formatting.
--     - lint
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; Right entries = decodeText @(M.Map T.Text (Commented (Commented [Commented T.Text]))) input
--   
--   &gt;&gt;&gt; Just jobs = M.lookup "jobs" entries
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; jobs.comments
--   Comments {before = [Comment "The CI jobs."], inline = Nothing, after = []}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; jobs.value.comments
--   Comments {before = [Comment "Run on every push.",EmptyLine], inline = Nothing, after = []}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; map (.comments) jobs.value.value
--   [Comments {before = [Comment "Check the formatting."], inline = Nothing, after = []}]
--   </pre>
--   
--   A value without a key, e.g. an item of a list, has the comments of its
--   node. The comments of a list or a mapping stay with it, not with its
--   first item or key: the lines up to the last empty line above its first
--   entry, and the comment on its first line, e.g. after its tag. A
--   <a>Commented</a> value of the whole list or mapping keeps them.
--   
--   By the rules in <a>Comments</a>, some lines read back with a change:
--   
--   <ul>
--   <li>The lines after a text of several lines, which the encoder writes
--   as a block scalar, read back as the lines above the next entry. After
--   the last entry, they belong to the end of the collection around the
--   entry.</li>
--   <li>The lines above a list or a mapping without a key can get an empty
--   line below them, e.g. at the top level. The empty line reads back as
--   the last of these lines.</li>
--   <li>The lines above the first item of a list or the first key of a
--   mapping that end with an empty line read back as the lines of the list
--   or the mapping. A <a>Commented</a> list or mapping keeps them. Under a
--   key, the inner of two nested <a>Commented</a> values keeps them, as
--   above. Otherwise they are lost.</li>
--   </ul>
--   
--   A comment is lost if its node has no place for it, i.e. if the node
--   does not decode into a node or a <a>Commented</a> value:
--   
--   <ul>
--   <li>the comments of a key without a Haskell field, e.g. the tag of a
--   constructor;</li>
--   <li>a comment at the end of a nested mapping, unless the field that
--   holds the mapping is <a>Commented</a>, because a record has no place
--   for the end of its mapping;</li>
--   <li>the comments of a record's mapping above its first key, e.g. a
--   comment at the top of a file above an empty line;</li>
--   <li>the comments of the key for a type such as <tt>data Name = Name
--   (Commented Text)</tt> that derives its instances through
--   <a>Generic</a>, because a derived instance for one constructor with
--   one field without a name does not give the key of its entry to the
--   value inside. Declare such a type as a newtype and derive its
--   instances with <tt>deriving newtype</tt>, which gives the key to the
--   value.</li>
--   </ul>
--   
--   In a map, use <a>Commented</a> on the key or on the value, not on
--   both. With both, the decoder gives the comments of the key to both,
--   and the encoder writes only those of the value, so a change to the
--   comments of the key is lost.
--   
--   A change of the value keeps the comments:
--   
--   <pre>
--   &gt;&gt;&gt; input = "# The port.\nport: 80 # the default\n"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   either printErrors (T.putStr . encodeText . M.map (fmap (+ 1))) $
--     decodeText @(M.Map T.Text (Commented Int)) input
--   :}
--   # The port.
--   port: 81 # the default
--   </pre>
--   
--   The order compares the values first and then the comments, e.g. in a
--   set.
data Commented a
Commented :: !a -> !Comments -> Commented a
[value] :: Commented a -> !a
[comments] :: Commented a -> !Comments

-- | A line of comments.
data Line
EmptyLine :: Line

-- | The number of <tt>#</tt> characters at the start of the comment, e.g.
--   2 for <tt>## Section</tt>, and the text after them, without the one
--   space after the <tt>#</tt> characters and without the white space at
--   its end. The renderer writes a count below 1 as 1. It writes a text
--   with line breaks as several comment lines with the same <tt>#</tt>
--   characters, and the parser reads them back as several comments.
--   U+0085, U+2028 and U+2029 count as line breaks here, because YAML 1.1
--   reads them as line breaks.
--   
--   The comment at the end of a line in <a>Comments</a> is a text without
--   a count. It keeps the <tt>#</tt> characters after the first one in its
--   text.
CommentLine :: !Int -> !Text -> Line

-- | A comment with one <tt>#</tt>. As a pattern, it matches every comment
--   and ignores the number of <tt>#</tt> characters.
pattern Comment :: Text -> Line

-- | The offset of a byte in the input text, in its UTF-8 encoding. For an
--   input in UTF-16 or UTF-32, the offset counts the bytes of the text
--   after <a>decodeInput</a>, not the bytes of the input.
newtype Offset
Offset :: Int -> Offset

-- | The offset of a node that does not come from an input.
noOffset :: Offset

-- | A value with the offset of its node, e.g. for the error of a check
--   that runs after the decode. The encoder writes only the value.
--   
--   <a>documentErrors</a> turns the offsets into errors with lines,
--   columns and paths. It needs the text and the document of the decode,
--   so decode with <a>decodeWithDocument</a>. Here the check gives an
--   offset and a message for each problem:
--   
--   <pre>
--   &gt;&gt;&gt; input = "paths:\n- src\n- /etc\n"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   case decodeWithDocument @(M.Map T.Text [Located T.Text]) input of
--     Right (config, doc) -&gt;
--       let errs =
--             [ (p.offset, "the path is outside the repository")
--             | p &lt;- concat (M.elems config)
--             , "/" `T.isPrefixOf` p.value
--             ]
--       in printErrors (documentErrors input doc errs)
--     Left errs -&gt; printErrors errs
--   :}
--   input.yaml:3:3: paths[1]: the path is outside the repository
--     |
--   3 | - /etc
--     |   ^
--   </pre>
--   
--   A value that no node gives, e.g. a value of <a>yamlDefault</a>, has
--   <a>noOffset</a>. Its error has no position, and <a>prettyError</a>
--   prints only the file and the message. A value inside an alias has the
--   offset of the alias, i.e. of the place where the document uses the
--   value.
--   
--   Two equal values at different places are not equal as <a>Located</a>
--   values, e.g. a set keeps both. The equality and the order compare the
--   values first and then the offsets. To compare only the values, e.g. in
--   a test, use the field <tt>value</tt>.
data Located a
Located :: !a -> !Offset -> Located a
[value] :: Located a -> !a
[offset] :: Located a -> !Offset

-- | Copy every text of a document, so that the document does not keep the
--   input alive.
copyDocument :: Document -> Document

-- | Copy every text of a node, so that the node does not keep the input
--   alive.
copyNode :: Node -> Node
copyComments :: Comments -> Comments
instance GHC.Internal.Enum.Bounded Yamlet.Internal.Syntax.CollectionStyle
instance GHC.Internal.Enum.Bounded Yamlet.Internal.Syntax.ScalarStyle
instance GHC.Internal.Enum.Enum Yamlet.Internal.Syntax.CollectionStyle
instance GHC.Internal.Enum.Enum Yamlet.Internal.Syntax.ScalarStyle
instance GHC.Classes.Eq Yamlet.Internal.Syntax.CollectionStyle
instance GHC.Classes.Eq a => GHC.Classes.Eq (Yamlet.Internal.Syntax.Commented a)
instance GHC.Classes.Eq Yamlet.Internal.Syntax.Comments
instance GHC.Classes.Eq Yamlet.Internal.Syntax.Content
instance GHC.Classes.Eq Yamlet.Internal.Syntax.Document
instance GHC.Classes.Eq Yamlet.Internal.Syntax.Line
instance GHC.Classes.Eq a => GHC.Classes.Eq (Yamlet.Internal.Syntax.Located a)
instance GHC.Classes.Eq Yamlet.Internal.Syntax.Node
instance GHC.Classes.Eq Yamlet.Internal.Syntax.Offset
instance GHC.Classes.Eq Yamlet.Internal.Syntax.Props
instance GHC.Classes.Eq Yamlet.Internal.Syntax.ScalarStyle
instance GHC.Classes.Eq Yamlet.Internal.Syntax.Tag
instance GHC.Classes.Eq Yamlet.Internal.Syntax.YamlVersion
instance GHC.Internal.Data.Foldable.Foldable Yamlet.Internal.Syntax.Commented
instance GHC.Internal.Data.Foldable.Foldable Yamlet.Internal.Syntax.Located
instance GHC.Internal.Base.Functor Yamlet.Internal.Syntax.Commented
instance GHC.Internal.Base.Functor Yamlet.Internal.Syntax.Located
instance GHC.Internal.Generics.Generic Yamlet.Internal.Syntax.CollectionStyle
instance GHC.Internal.Generics.Generic (Yamlet.Internal.Syntax.Commented a)
instance GHC.Internal.Generics.Generic Yamlet.Internal.Syntax.Comments
instance GHC.Internal.Generics.Generic Yamlet.Internal.Syntax.Content
instance GHC.Internal.Generics.Generic Yamlet.Internal.Syntax.Document
instance GHC.Internal.Generics.Generic Yamlet.Internal.Syntax.Line
instance GHC.Internal.Generics.Generic (Yamlet.Internal.Syntax.Located a)
instance GHC.Internal.Generics.Generic Yamlet.Internal.Syntax.Node
instance GHC.Internal.Generics.Generic Yamlet.Internal.Syntax.Offset
instance GHC.Internal.Generics.Generic Yamlet.Internal.Syntax.Props
instance GHC.Internal.Generics.Generic Yamlet.Internal.Syntax.ScalarStyle
instance GHC.Internal.Generics.Generic Yamlet.Internal.Syntax.Tag
instance GHC.Internal.Generics.Generic Yamlet.Internal.Syntax.YamlVersion
instance Control.DeepSeq.NFData Yamlet.Internal.Syntax.CollectionStyle
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Yamlet.Internal.Syntax.Commented a)
instance Control.DeepSeq.NFData Yamlet.Internal.Syntax.Comments
instance Control.DeepSeq.NFData Yamlet.Internal.Syntax.Content
instance Control.DeepSeq.NFData Yamlet.Internal.Syntax.Document
instance Control.DeepSeq.NFData Yamlet.Internal.Syntax.Line
instance Control.DeepSeq.NFData a => Control.DeepSeq.NFData (Yamlet.Internal.Syntax.Located a)
instance Control.DeepSeq.NFData Yamlet.Internal.Syntax.Node
instance Control.DeepSeq.NFData Yamlet.Internal.Syntax.Offset
instance Control.DeepSeq.NFData Yamlet.Internal.Syntax.Props
instance Control.DeepSeq.NFData Yamlet.Internal.Syntax.ScalarStyle
instance Control.DeepSeq.NFData Yamlet.Internal.Syntax.Tag
instance Control.DeepSeq.NFData Yamlet.Internal.Syntax.YamlVersion
instance GHC.Classes.Ord Yamlet.Internal.Syntax.CollectionStyle
instance GHC.Classes.Ord a => GHC.Classes.Ord (Yamlet.Internal.Syntax.Commented a)
instance GHC.Classes.Ord Yamlet.Internal.Syntax.Comments
instance GHC.Classes.Ord Yamlet.Internal.Syntax.Line
instance GHC.Classes.Ord a => GHC.Classes.Ord (Yamlet.Internal.Syntax.Located a)
instance GHC.Classes.Ord Yamlet.Internal.Syntax.Offset
instance GHC.Classes.Ord Yamlet.Internal.Syntax.ScalarStyle
instance GHC.Classes.Ord Yamlet.Internal.Syntax.Tag
instance GHC.Classes.Ord Yamlet.Internal.Syntax.YamlVersion
instance GHC.Internal.Show.Show Yamlet.Internal.Syntax.CollectionStyle
instance GHC.Internal.Show.Show a => GHC.Internal.Show.Show (Yamlet.Internal.Syntax.Commented a)
instance GHC.Internal.Show.Show Yamlet.Internal.Syntax.Comments
instance GHC.Internal.Show.Show Yamlet.Internal.Syntax.Content
instance GHC.Internal.Show.Show Yamlet.Internal.Syntax.Document
instance GHC.Internal.Show.Show Yamlet.Internal.Syntax.Line
instance GHC.Internal.Show.Show a => GHC.Internal.Show.Show (Yamlet.Internal.Syntax.Located a)
instance GHC.Internal.Show.Show Yamlet.Internal.Syntax.Node
instance GHC.Internal.Show.Show Yamlet.Internal.Syntax.Offset
instance GHC.Internal.Show.Show Yamlet.Internal.Syntax.Props
instance GHC.Internal.Show.Show Yamlet.Internal.Syntax.ScalarStyle
instance GHC.Internal.Show.Show Yamlet.Internal.Syntax.Tag
instance GHC.Internal.Show.Show Yamlet.Internal.Syntax.YamlVersion
instance GHC.Internal.Data.Traversable.Traversable Yamlet.Internal.Syntax.Commented
instance GHC.Internal.Data.Traversable.Traversable Yamlet.Internal.Syntax.Located


-- | A backtracking parser over the bytes of UTF-8 encoded text.
--   
--   This module is intended for internal use only, and may change without
--   warning in subsequent releases.
module Yamlet.Internal.Parser.Monad
data P a

-- | The input of the parser.
data Env
Env :: !Array -> !Int -> !Int -> !Int -> !Map Text Text -> Env
[array] :: Env -> !Array

-- | The index of the first byte of the input.
[base] :: Env -> !Int

-- | The index past the last byte that the parser can read.
[end] :: Env -> !Int

-- | The index past the last byte of the input. A document ends before it
--   at a document marker.
[streamEnd] :: Env -> !Int

-- | The tag handles of the current document.
[handles] :: Env -> !Map Text Text

-- | An error that no backtracking can recover from: an error at the index
--   with the message, or a failure at the index in the environment, whose
--   message the caller of the parser finds.
data ParseError
ParseError :: !Int -> !String -> ParseError
UnexpectedParseError :: !Env -> !Int -> ParseError

-- | Run a parser from the given index. Return the result, the index after
--   it and the furthest failure.
runParser :: Env -> Int -> P a -> Either ParseError (Maybe a, Int, Int)

-- | Ordered choice. Try the second parser if the first one fails.
(<|>) :: P a -> P a -> P a
infixl 3 <|>

-- | Zero or more times. Stop if the parser succeeds without input.
many :: P a -> P [a]

-- | Zero or more times, discard the results.
many_ :: P a -> P ()
optional :: P a -> P (Maybe a)
optional_ :: P a -> P ()
option :: a -> P a -> P a

-- | Succeed without input if the parser fails. An error of the parser
--   stays an error, as in <a>&lt;|&gt;</a>.
notFollowedBy :: P a -> P ()
env :: P Env
pos :: P Int
setPos :: Int -> P ()

-- | The furthest position at which a parser failed so far.
furthest :: P Int
advance :: Int -> P ()

-- | Add the bytes that the prefix of a <tt>%TAG</tt> directive adds to a
--   tag, and return the bytes that such prefixes added so far. A parser
--   that fails drops its bytes, so only the tags of the result count.
addTagBytes :: Int -> P Int

-- | The byte at the current position, 0 at the end of the input.
peek :: P Word8

-- | The byte at the given distance from the current position.
peekAt :: Int -> P Word8
failure :: P a
guardP :: Bool -> P ()

-- | Stop with an error at the given index.
throwAt :: Int -> String -> P a

-- | Stop at the index, with an error whose message the caller of the
--   parser finds.
throwUnexpected :: Int -> P a

-- | Run a parser that cannot read past the given index.
withEnd :: Int -> P a -> P a
withHandles :: Map Text Text -> P a -> P a
char :: Word8 -> P ()
skipWhile :: (Word8 -> Bool) -> P ()

-- | Move to the index that the function computes from the current one.
scan :: (Env -> Int -> Int) -> P ()

-- | The result of a scanning loop.
data Scanned a

-- | The value and the index after it.
Done :: !Int -> !a -> Scanned a

-- | The input does not match. The index is the location of the mismatch.
NoMatch :: !Int -> Scanned a

-- | An error at the index.
Failed :: !Int -> !String -> Scanned a

-- | Run a pure loop over the input from the current position.
withScan :: (Env -> Int -> Scanned a) -> P a
byteAt :: Env -> Int -> Word8

-- | The byte before the index, 0 at the start of the input.
byteBefore :: Env -> Int -> Word8
slice :: Env -> Int -> Int -> Text
toOffset :: Env -> Int -> Offset
instance GHC.Internal.Base.Applicative Yamlet.Internal.Parser.Monad.P
instance GHC.Internal.Base.Functor Yamlet.Internal.Parser.Monad.P
instance GHC.Internal.Base.Monad Yamlet.Internal.Parser.Monad.P


-- | Scans of the input around an index, outside of the parser monad.
--   
--   This module is intended for internal use only, and may change without
--   warning in subsequent releases.
module Yamlet.Internal.Parser.Scan
isBom :: Env -> Int -> Bool
skipBoms :: Env -> Int -> Int
skipSpaces :: Env -> Int -> Int
skipWhites :: Env -> Int -> Int

-- | The index after the line break at the index.
breakEnd :: Env -> Int -> Int
isStartOfLine :: Env -> Int -> Bool

-- | The start of the line that contains the index.
lineStartAt :: Env -> Int -> Int

-- | The start of the line above the line that starts at the index, which
--   is not the first line.
previousLineStart :: Env -> Int -> Int

-- | The index of the line break that ends the line of the index, or the
--   end of the input.
lineEndAt :: Env -> Int -> Int

-- | The start of the line below the line of the index, or the end of the
--   input.
nextLineStart :: Env -> Int -> Int

-- | The start of the closest line above the line that starts at the index
--   with content other than a comment. Byte order marks at the start of a
--   line do not count as content.
contentLineAbove :: Env -> Int -> Maybe Int

-- | The number of characters of a <tt>---</tt> or <tt>...</tt> marker.
markerLength :: Int

-- | A <tt>---</tt> or <tt>...</tt> marker at the start of a line.
isMarker :: Env -> Int -> Bool

-- | A <tt>---</tt> marker at the start of a line.
isStartMarker :: Env -> Int -> Bool

-- | A <tt>...</tt> marker at the start of a line.
isEndMarker :: Env -> Int -> Bool

-- | A byte order mark at the start of a line. Outside a quoted scalar, it
--   starts the prefix of the next document, so the content of a document
--   ends before it.
startsPrefix :: Env -> Int -> Bool

-- | Byte order marks at the index before something other than a document
--   marker or a directive. Such marks at the start of a line inside a
--   document are an error.
bomBeforeContent :: Env -> Int -> Bool

-- | A quoted scalar or a flow collection can end before the index: white
--   space, a comment, a line break, the end of the input, a colon or the
--   end of a flow entry follows.
canEndFlowNode :: Env -> Int -> Bool

-- | The input between the indices fits in an implicit key.
fitsKey :: Env -> Int -> Int -> Bool


-- | The messages of parse errors. The parser only knows the position at
--   which it failed, so these functions look at the input around it to
--   name the likely mistake, e.g. a missing colon after a key.
--   
--   This module is intended for internal use only, and may change without
--   warning in subsequent releases.
module Yamlet.Internal.Parser.Hints

-- | The location and the message of the error for the furthest position at
--   which the parser failed, and a tab before the position on its line
--   that can be the cause instead, with <a>tabMessage</a>.
unexpected :: Env -> Int -> (Maybe Int, (Int, String))

-- | The location and the message of the error at the index inside a flow
--   collection: a common mistake if the input there shows one, or else the
--   index and the given message.
flowError :: Env -> Int -> String -> (Int, String)

-- | The code point of a character, e.g. U+0007, for a character that an
--   error cannot show.
codePointName :: Char -> String

-- | The first tab from the first index to before the second.
firstTab :: Env -> Int -> Int -> Maybe Int
tabMessage :: String
keyLengthMessage :: String


-- | Building blocks of the YAML output.
--   
--   This module is intended for internal use only, and may change without
--   warning in subsequent releases.
module Yamlet.Internal.Emit

-- | The text reads back as the same text if it is a plain scalar on one
--   line, in a flow collection if the flag is set. The check ignores the
--   schema, so e.g. <tt>12</tt> passes.
plainSyntax :: Bool -> Text -> Bool

-- | A plain scalar on the lines that start at the positions, with the
--   lines after the first one at the given indentation, if the text can be
--   plain. It is in a flow collection if the flag is set.
plainLines :: Bool -> Int -> [Int] -> Text -> Maybe Builder

-- | A single-quoted scalar on one line, if the text has no line breaks.
singleQuoted :: Text -> Maybe Builder

-- | A single-quoted scalar on the lines that start at the positions, as in
--   <a>plainLines</a>, if single quotes can hold the text.
singleQuotedLines :: Int -> [Int] -> Text -> Maybe Builder

-- | The quoted form of a plain scalar whose text cannot be plain: in
--   single quotes, or in double quotes if the text has a tab or a
--   character that single quotes cannot hold. A tab in single quotes is
--   not visible.
quotedPlain :: Text -> Builder

-- | <a>quotedPlain</a> on the lines that start at the positions, as in
--   <a>plainLines</a>.
quotedPlainLines :: Int -> [Int] -> Text -> Builder

-- | A double-quoted scalar with escapes for the characters that need them.
doubleQuoted :: Text -> Builder

-- | A double-quoted scalar on the lines that start at the positions, as in
--   <a>plainLines</a>. The escapes of the tabs keep them at the ends of
--   the lines.
doubleQuotedLines :: Int -> [Int] -> Text -> Builder

-- | The header and the content lines of a literal block scalar, with the
--   content at the given indentation.
literalBlock :: Int -> Text -> Maybe (Builder, Builder)

-- | The header and the content lines of a folded block scalar, with the
--   content at the given indentation. It has no keep indicator. Each line
--   of the text becomes one line of the output, or several lines if the
--   lines start at the positions.
foldedBlock :: Int -> [Int] -> Text -> Maybe (Builder, Builder)

-- | A block scalar with the text has the keep indicator, so the empty
--   lines at its end are its content. Without content, the clip indicator
--   drops the line breaks too.
hasKeepIndicator :: Text -> Bool

-- | A block scalar with the text needs an indentation indicator, because
--   its first line with content starts with a space or a tab. YAML 1.2
--   does not need the indicator for a tab, but libyaml rejects the block
--   scalar without it. Parsers do not agree on the meaning of the
--   indicator at the top level, so a caller there writes such a text with
--   quotes.
needsIndentIndicator :: Text -> Bool

-- | The number of spaces that the content of a block collection or a block
--   scalar is indented by, relative to its parent. The output style is
--   fixed.
indentStep :: Int

-- | A tag in the shortest form that reads back as the same tag. A tag that
--   no text can hold, e.g. an empty tag, becomes the non-specific tag
--   <tt>!</tt>.
--   
--   A global tag that is not a valid URI needs the directive of
--   <a>tagDirective</a> in its document.
tagText :: Text -> Builder

-- | The handles for the tags of the node and the nodes in it that are not
--   valid URIs, each once.
tagHandles :: Node -> [Char]

-- | The <tt>%TAG</tt> directive of the handle for the tags that start with
--   the character, with the line break. The prefix is always an escape,
--   because e.g. a <tt>#</tt> after a space starts a comment.
tagDirective :: Char -> Builder

-- | c-printable without the line breaks and the byte order mark.
isPrintable :: Char -> Bool

-- | A printable character that needs no escape in a scalar. YAML 1.1 reads
--   U+2028 and U+2029 as line breaks, so they get escapes too.
isScalarChar :: Char -> Bool
spaces :: Int -> Builder


-- | Rendering of the syntax tree.
--   
--   This module is intended for internal use only, and may change without
--   warning in subsequent releases.
module Yamlet.Internal.Render

-- | The options of <a>renderSyntax</a>.
data RenderOptions
RenderOptions :: !Bool -> RenderOptions

-- | Write every non-empty collection in the block style. A collection in a
--   key then becomes an explicit key, e.g. <tt>? - a</tt>.
[forceBlock] :: RenderOptions -> !Bool

-- | Keep the collection styles of the tree.
defaultRenderOptions :: RenderOptions

-- | Render documents with their comments and empty lines.
--   
--   The output differs from the tree where YAML cannot hold it:
--   
--   <ul>
--   <li>A <tt>---</tt> marker is on a line of its own, with at most a
--   comment after it.</li>
--   <li>A scalar keeps its style if the style can hold its text, otherwise
--   it gets quotes. A block scalar that is a key or an entry of a flow
--   collection gets double quotes. A block scalar at the root gets quotes
--   in a few more cases, e.g. if its text starts with a space.</li>
--   <li>The empty lines from the comments right after a block scalar with
--   the <tt>+</tt> indicator go away, because they would become part of
--   the scalar.</li>
--   <li>A flow collection with comments inside becomes a block collection,
--   so that every comment has a line.</li>
--   <li>A flow collection without comments is on one line, apart from the
--   line breaks of its multi-line scalars, so the empty lines between its
--   entries go away.</li>
--   <li>A key of more than 1024 characters in a flow mapping becomes an
--   explicit key, e.g. <tt>{? key : value}</tt>, because YAML 1.1 parsers
--   reject a longer implicit key there too.</li>
--   <li>A comment that has no place at its node moves to a place that has
--   one, e.g. the lines above the value of a key go above the key if the
--   value is on the line of the key.</li>
--   <li>In the text of a comment, a character that YAML does not allow
--   becomes U+FFFD, and the white space at the end goes away. A line break
--   starts a new comment in a <a>CommentLine</a>, and becomes a space in
--   an inline comment.</li>
--   <li>An anchor name with a character that YAML does not allow in it,
--   e.g. a space, or that YAML 1.1 parsers read as the end of the name,
--   e.g. <tt>:</tt> or a line separator, becomes a new name in the anchor
--   and in its aliases. Names that only some parsers reject stay, e.g.
--   <tt>é</tt>, which libyaml rejects.</li>
--   <li>A version that the parser does not support, e.g. 2.0, has no
--   <tt>%YAML</tt> directive.</li>
--   </ul>
--   
--   With <a>forceBlock</a>, the flow collections become block collections:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   case parseDocumentsText "a: [1, {b: 2}]\n" of
--     Left err -&gt; putStrLn (prettyError "input.yaml" err)
--     Right docs -&gt;
--       T.putStr (renderSyntax defaultRenderOptions {forceBlock = True} docs)
--   :}
--   a:
--   - 1
--   - b: 2
--   </pre>
renderSyntax :: RenderOptions -> [Document] -> Text
instance GHC.Classes.Eq Yamlet.Internal.Render.Position
instance GHC.Classes.Eq Yamlet.Internal.Render.RenderOptions
instance GHC.Internal.Generics.Generic Yamlet.Internal.Render.RenderOptions
instance GHC.Internal.Show.Show Yamlet.Internal.Render.RenderOptions


-- | The renderer of the nodes of the encoder.
--   
--   This module is intended for internal use only, and may change without
--   warning in subsequent releases.
module Yamlet.Internal.Encoder

-- | Render documents. Documents after the first one start with a
--   <tt>---</tt> marker. The collections of <a>toYaml</a> are in the block
--   style.
--   
--   A document with comments, anchors, aliases, flow collections, scalars
--   on several lines or scalar styles that <a>toYaml</a> does not create
--   goes to <a>renderSyntax</a>. Other documents go to a faster renderer,
--   which gives the same output.
renderDocuments :: [Node] -> Text


-- | Attachment of comments and empty lines to the nodes of a document.
--   
--   The rules are in the documentation of <a>Yamlet.Syntax</a>. The parser
--   skips comments, so this module finds them again in the input, outside
--   of the scalars, and gives each one to a node.
--   
--   This module is intended for internal use only, and may change without
--   warning in subsequent releases.
module Yamlet.Internal.Comments

-- | Attach the comments of a document, and return the lines at its end
--   that belong to the next document. The flags tell if the document is
--   the first one and if another one follows it. The indices are the start
--   of the lines that belong to the document, its <tt>---</tt> marker, the
--   end of its root and its end.
attachComments :: Env -> Bool -> Bool -> Int -> Maybe Int -> Int -> Int -> Document -> (Document, [Line])

-- | The start of the first line from the index that is empty or has more
--   than a comment or a <tt>...</tt> marker. The index is the start of a
--   line.
gapEnd :: Env -> Int -> Int

-- | The documents with the lines above the first one.
linesAbove :: [Line] -> [Document] -> [Document]


-- | Errors with the position in the input that caused them.
module Yamlet.Error

-- | An error of the parser or the decoder.
--   
--   An error from the functions of this module keeps no part of the input
--   alive once it is in weak head normal form. Its message and its path
--   are evaluated then, because a message often contains a slice of the
--   input, e.g. a key, and a path comes from the syntax tree.
data Error
Error :: !Location -> !String -> !Text -> !Int -> !Path -> Error
[location] :: Error -> !Location
[message] :: Error -> !String

-- | The line of the input that contains the location.
[sourceLine] :: Error -> !Text

-- | The index of the location in the UTF-8 bytes of <a>sourceLine</a>. It
--   lets <a>prettyError</a> find the column without a scan of the whole
--   line.
[sourceIndex] :: Error -> !Int

-- | The path to the node of a decoder error. An error at a key has the
--   path of its mapping. The path is empty for an error of the parser and
--   for a node that a program built.
[path] :: Error -> !Path

-- | A position in the input. Lines and columns count from 1, and a column
--   counts characters, not bytes. Line 0 and column 0 mean that the error
--   has no position, e.g. because it comes from a node that a program
--   built, or from a parsed node that is decoded without its input.
data Location
Location :: !Offset -> !Int -> !Int -> Location
[offset] :: Location -> !Offset
[line] :: Location -> !Int
[column] :: Location -> !Int

-- | The keys and the indices from the root of a document to a node.
--   
--   The path of a node shares the path of its parent, so the paths of many
--   errors in a deep document take memory linear in its size.
data Path

-- | The steps of a path, from the root.
pathElements :: Path -> [PathElement]

-- | A path with the steps from the root.
pathFromElements :: [PathElement] -> Path

-- | A step of a path into a document.
data PathElement

-- | The value of a key that is a scalar, with the text of the key, e.g.
--   <tt>1</tt> for the integer key 1.
Key :: !Text -> PathElement

-- | The item of a sequence, from 0.
Index :: !Int -> PathElement

-- | The value of a key that is a collection, e.g. <tt>? [1, 2]</tt>. The
--   path has no steps into the key.
CollectionKey :: PathElement

-- | The value of a key that is an alias, with the name of the anchor.
AliasKey :: !Text -> PathElement

-- | Render an error in the format that editors recognize. The result does
--   not end with a line break. If the line is longer than 80 characters,
--   the excerpt shows only the 80 characters around the column. A control
--   character other than a tab shows as its symbol, e.g. U+241B for
--   escape, or as U+FFFD if Unicode has no symbol for it.
--   
--   <pre>
--   &gt;&gt;&gt; either printErrors print (decodeText @(M.Map T.Text [[Int]]) "jobs:\n  - [1]\n  - 42\n")
--   input.yaml:3:5: jobs[1]: expected a list, but got an integer
--     |
--   3 |   - 42
--     |     ^
--   </pre>
--   
--   An error with no position gives only the file and the message, e.g.
--   <tt>input.yaml: duplicate key "a"</tt>.
prettyError :: FilePath -> Error -> String

-- | A path in the form <tt>jobs[1].name</tt>. A key that is a collection
--   is <tt>?</tt>, and a key that is an alias is its alias, e.g.
--   <tt>*base</tt>.
--   
--   A key is in double quotes, e.g. <tt>"a.b"</tt>, if it:
--   
--   <ul>
--   <li>is empty,</li>
--   <li>has white space, a character that cannot be printed, or one of the
--   characters <tt>.[]"\</tt>,</li>
--   <li>starts with <tt>?</tt> or <tt>*</tt>.</li>
--   </ul>
--   
--   In the quotes, a character that cannot be printed has an escape as in
--   YAML, e.g. <tt>"a\nb"</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; renderPath (pathFromElements [Key "jobs", Index 1, Key "name"])
--   "jobs[1].name"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; renderPath (pathFromElements [Key "a.b", Key ""])
--   "\"a.b\".\"\""
--   </pre>
renderPath :: Path -> String

-- | Create an error at the given offset of the input.
errorAt :: Text -> Offset -> String -> Error

-- | Create errors at the given offsets of the input, in the order of the
--   list. One scan of the input locates all of them, and the errors on one
--   line share the copy of the line.
errorsAt :: Text -> [(Offset, String)] -> [Error]

-- | Create errors at the given offsets of a document, with their paths, in
--   the order of the list. The text is the input of the document, e.g. for
--   the offsets of <a>Located</a> values.
documentErrors :: Text -> Document -> [(Offset, String)] -> [Error]

-- | Compute the line and the column of an offset. The byte order marks at
--   the start of a line are not columns, because they are not content. For
--   <a>noOffset</a> or an offset beyond the end of the input, the line and
--   the column are 0.
locate :: Text -> Offset -> Location

-- | The path from the root to the node at the offset. If several nodes
--   start there, e.g. a block mapping and its first key, the outermost one
--   counts. A key does not add to the path, and a node inside a key that
--   is a collection has the path of the mapping.
nodePath :: Offset -> Node -> Path

-- | The paths of <a>nodePath</a> for several offsets, in the order of the
--   offsets, from one walk of the tree.
nodePaths :: [Offset] -> Node -> [Path]
instance GHC.Classes.Eq Yamlet.Error.Error
instance GHC.Classes.Eq Yamlet.Error.Location
instance GHC.Classes.Eq Yamlet.Error.Path
instance GHC.Classes.Eq Yamlet.Error.PathElement
instance GHC.Internal.Generics.Generic Yamlet.Error.Error
instance GHC.Internal.Generics.Generic Yamlet.Error.Location
instance GHC.Internal.Generics.Generic Yamlet.Error.PathElement
instance Control.DeepSeq.NFData Yamlet.Error.Error
instance Control.DeepSeq.NFData Yamlet.Error.Location
instance Control.DeepSeq.NFData Yamlet.Error.Path
instance Control.DeepSeq.NFData Yamlet.Error.PathElement
instance GHC.Internal.Show.Show Yamlet.Error.Error
instance GHC.Internal.Show.Show Yamlet.Error.Location
instance GHC.Internal.Show.Show Yamlet.Error.Path
instance GHC.Internal.Show.Show Yamlet.Error.PathElement


-- | The parser of YAML 1.2.2 streams.
--   
--   The functions follow the productions of the specification and keep
--   their names, e.g. <tt>nsFlowNode</tt> implements
--   <tt>ns-flow-node(n,c)</tt>. A few productions are fused into loops
--   over the bytes of the input for speed. Each production is a top-level
--   function, also if only one function uses it, so that the parser reads
--   like the grammar of the specification.
--   
--   This module is intended for internal use only, and may change without
--   warning in subsequent releases.
module Yamlet.Internal.Parser

-- | Parse all documents of a stream.
parseStream :: Text -> Either Error [Document]

-- | A content line of a block scalar: the number of empty lines before it
--   and its text after the indentation.
data BlockLine
BlockLine :: !Int -> !Text -> BlockLine

-- | The text of a folded block scalar and the positions where its lines
--   start.
foldedText :: [BlockLine] -> (Text, [Int])
instance GHC.Classes.Eq Yamlet.Internal.Parser.Chomping
instance GHC.Classes.Eq Yamlet.Internal.Parser.Ctx


-- | Detection of the encoding of the input.
--   
--   This module is intended for internal use only, and may change without
--   warning in subsequent releases.
module Yamlet.Internal.Input

-- | Decode the bytes of a stream to text. The encoding is UTF-8, UTF-16 or
--   UTF-32, detected as the YAML specification describes.
decodeInput :: ByteString -> Either Error Text


-- | The representation of a YAML stream that keeps every detail of the
--   presentation: the styles of scalars and collections, the lines of
--   scalars, anchors, aliases, unresolved tags, comments and empty lines.
--   The <a>FromYaml</a> and <a>ToYaml</a> classes read and write the nodes
--   of this tree.
--   
--   Most texts in the tree share the memory of the input, so a node keeps
--   the whole input alive. To keep a text longer than the tree, copy it
--   with <a>copy</a>, or copy the whole tree with <a>copyDocument</a>.
--   Copy only what the program keeps: a copy of a whole tree usually needs
--   more memory than the input it frees.
--   
--   A document that the renderer writes back keeps its comments, empty
--   lines and styles:
--   
--   <pre>
--   &gt;&gt;&gt; input = "# The server.\nhost: localhost # only local\n\nports: [80, 443]\n"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   case parseDocumentsText input of
--     Left err -&gt; putStrLn (prettyError "input.yaml" err)
--     Right docs -&gt; T.putStr (renderSyntax defaultRenderOptions docs)
--   :}
--   # The server.
--   host: localhost # only local
--   
--   ports: [80, 443]
--   </pre>
--   
--   The section <a>Comments</a> gives the rules that decide the node of
--   each comment.
module Yamlet.Syntax

-- | Parse the documents of a stream. The encoding is UTF-8, UTF-16 or
--   UTF-32, detected as the YAML specification describes.
--   
--   <a>errorAt</a> and <a>decodeDocument</a> need the text of the input.
--   To report errors with the lines of the input, decode the input with
--   <a>decodeInput</a> and parse it with <a>parseDocumentsText</a>.
parseDocuments :: ByteString -> Either Error [Document]

-- | Parse the documents of a stream.
--   
--   <pre>
--   &gt;&gt;&gt; length &lt;$&gt; parseDocumentsText "a\n---\nb\n"
--   Right 2
--   </pre>
parseDocumentsText :: Text -> Either Error [Document]

-- | Decode the bytes of a stream to text. The encoding is UTF-8, UTF-16 or
--   UTF-32, detected as the YAML specification describes.
decodeInput :: ByteString -> Either Error Text

-- | Copy every text of a document, so that the document does not keep the
--   input alive.
copyDocument :: Document -> Document

-- | Copy every text of a node, so that the node does not keep the input
--   alive.
copyNode :: Node -> Node

-- | Render documents with their comments and empty lines.
--   
--   The output differs from the tree where YAML cannot hold it:
--   
--   <ul>
--   <li>A <tt>---</tt> marker is on a line of its own, with at most a
--   comment after it.</li>
--   <li>A scalar keeps its style if the style can hold its text, otherwise
--   it gets quotes. A block scalar that is a key or an entry of a flow
--   collection gets double quotes. A block scalar at the root gets quotes
--   in a few more cases, e.g. if its text starts with a space.</li>
--   <li>The empty lines from the comments right after a block scalar with
--   the <tt>+</tt> indicator go away, because they would become part of
--   the scalar.</li>
--   <li>A flow collection with comments inside becomes a block collection,
--   so that every comment has a line.</li>
--   <li>A flow collection without comments is on one line, apart from the
--   line breaks of its multi-line scalars, so the empty lines between its
--   entries go away.</li>
--   <li>A key of more than 1024 characters in a flow mapping becomes an
--   explicit key, e.g. <tt>{? key : value}</tt>, because YAML 1.1 parsers
--   reject a longer implicit key there too.</li>
--   <li>A comment that has no place at its node moves to a place that has
--   one, e.g. the lines above the value of a key go above the key if the
--   value is on the line of the key.</li>
--   <li>In the text of a comment, a character that YAML does not allow
--   becomes U+FFFD, and the white space at the end goes away. A line break
--   starts a new comment in a <a>CommentLine</a>, and becomes a space in
--   an inline comment.</li>
--   <li>An anchor name with a character that YAML does not allow in it,
--   e.g. a space, or that YAML 1.1 parsers read as the end of the name,
--   e.g. <tt>:</tt> or a line separator, becomes a new name in the anchor
--   and in its aliases. Names that only some parsers reject stay, e.g.
--   <tt>é</tt>, which libyaml rejects.</li>
--   <li>A version that the parser does not support, e.g. 2.0, has no
--   <tt>%YAML</tt> directive.</li>
--   </ul>
--   
--   With <a>forceBlock</a>, the flow collections become block collections:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   case parseDocumentsText "a: [1, {b: 2}]\n" of
--     Left err -&gt; putStrLn (prettyError "input.yaml" err)
--     Right docs -&gt;
--       T.putStr (renderSyntax defaultRenderOptions {forceBlock = True} docs)
--   :}
--   a:
--   - 1
--   - b: 2
--   </pre>
renderSyntax :: RenderOptions -> [Document] -> Text

-- | The options of <a>renderSyntax</a>.
data RenderOptions
RenderOptions :: !Bool -> RenderOptions

-- | Write every non-empty collection in the block style. A collection in a
--   key then becomes an explicit key, e.g. <tt>? - a</tt>.
[forceBlock] :: RenderOptions -> !Bool

-- | Keep the collection styles of the tree.
defaultRenderOptions :: RenderOptions

-- | A document of a YAML stream.
data Document
Document :: !Maybe YamlVersion -> !Bool -> !Bool -> !Comments -> !Node -> Document

-- | The version from the <tt>%YAML</tt> directive.
[version] :: Document -> !Maybe YamlVersion

-- | The document starts with a <tt>---</tt> marker.
[explicitStart] :: Document -> !Bool

-- | The document ends with a <tt>...</tt> marker.
[explicitEnd] :: Document -> !Bool

-- | The lines before the directives or the <tt>---</tt> marker, the
--   comment on the line of the marker and the lines at the end of the
--   document: below the <tt>...</tt> marker, or below a flow collection
--   root.
[docComments] :: Document -> !Comments
[root] :: Document -> !Node

-- | The version of YAML that a document declares.
data YamlVersion
YamlVersion :: !Int -> !Int -> YamlVersion
[major] :: YamlVersion -> !Int
[minor] :: YamlVersion -> !Int

-- | A document with the given root, without directives, markers and
--   comments.
document :: Node -> Document

-- | A node of a document.
data Node
Node :: !Offset -> !Offset -> !Props -> !Comments -> !Content -> Node

-- | The position of the first character of the content.
[offset] :: Node -> !Offset

-- | The position after the last character of the content.
[endOffset] :: Node -> !Offset
[props] :: Node -> !Props
[comments] :: Node -> !Comments
[content] :: Node -> !Content

-- | The content of a node.
data Content

-- | A scalar with the positions in its text where the source continues on
--   a new line. A position counts the characters from the start of the
--   text, and the positions are in ascending order. The parser gives them
--   for the plain, quoted and folded styles, which join the lines of the
--   source, so that the renderer can write the text on the same lines. The
--   renderer ignores a position where the style of the output cannot start
--   a new line and keep the text.
ScalarLinesContent :: !ScalarStyle -> !Text -> ![Int] -> Content
SequenceContent :: !CollectionStyle -> ![Node] -> Content
MappingContent :: !CollectionStyle -> ![(Node, Node)] -> Content

-- | An alias, with the name of its anchor. An alias has no properties.
AliasContent :: !Text -> Content

-- | A scalar without positions of new lines. As a pattern, it matches
--   every scalar and ignores its positions.
pattern ScalarContent :: ScalarStyle -> Text -> Content

-- | The properties of a node.
data Props
Props :: !Maybe Text -> !Tag -> Props
[anchor] :: Props -> !Maybe Text
[tag] :: Props -> !Tag

-- | No anchor and no tag.
noProps :: Props

-- | The tag of a node after the tag handles are expanded.
data Tag

-- | The node has no tag.
NoTag :: Tag

-- | The <tt>!</tt> tag.
NonSpecificTag :: Tag

-- | A specific tag, e.g. <tt>tag:yaml.org,2002:str</tt> for
--   <tt>!!str</tt>. YAML has no syntax for the empty tag or a tag of one
--   character, e.g. <tt>x</tt> or <tt>!</tt>. The renderer writes such a
--   tag as <tt>!</tt>, which reads back as <a>NonSpecificTag</a>.
Tag :: !Text -> Tag

-- | The style of a scalar: without quotes, in single or double quotes, or
--   a literal (<tt>|</tt>) or folded (<tt>&gt;</tt>) block scalar.
data ScalarStyle
Plain :: ScalarStyle
SingleQuoted :: ScalarStyle
DoubleQuoted :: ScalarStyle
Literal :: ScalarStyle
Folded :: ScalarStyle

-- | The style of a collection: with indentation, or with brackets and
--   commas.
data CollectionStyle
Block :: CollectionStyle
Flow :: CollectionStyle

-- | A node with the given content, without properties and comments.
contentNode :: Content -> Node

-- | A scalar in the given style. <a>renderSyntax</a> uses quotes if the
--   style cannot hold the text, and for a block scalar that is a key or an
--   entry of a flow collection.
--   
--   <pre>
--   &gt;&gt;&gt; T.putStr (renderSyntax defaultRenderOptions [document (mappingNode [(plainNode "key", scalarNode Plain "a: b")])])
--   key: 'a: b'
--   </pre>
scalarNode :: ScalarStyle -> Text -> Node

-- | A plain scalar.
plainNode :: Text -> Node

-- | A folded block scalar (<tt>&gt;-</tt>) with the given lines. The empty
--   lines at the end are dropped, because <tt>&gt;-</tt> strips them.
--   
--   <pre>
--   &gt;&gt;&gt; T.putStr (renderSyntax defaultRenderOptions [document (mappingNode [(plainNode "options", foldedNode ["--health-cmd pg_isready", "--health-interval 5s"])])])
--   options: &gt;-
--     --health-cmd pg_isready
--     --health-interval 5s
--   </pre>
foldedNode :: [Text] -> Node

-- | A block sequence.
sequenceNode :: [Node] -> Node

-- | A block mapping.
mappingNode :: [(Node, Node)] -> Node

-- | The offset of a byte in the input text, in its UTF-8 encoding. For an
--   input in UTF-16 or UTF-32, the offset counts the bytes of the text
--   after <a>decodeInput</a>, not the bytes of the input.
newtype Offset
Offset :: Int -> Offset

-- | The offset of a node that does not come from an input.
noOffset :: Offset

-- | The comments and the empty lines that belong to a node.
data Comments
Comments :: ![Line] -> !Maybe Text -> ![Line] -> Comments

-- | The lines above the node.
[before] :: Comments -> ![Line]

-- | The comment at the end of the line where the node ends, or of the
--   first line of a block collection or a block scalar. The renderer
--   writes each line break in it as a space. The line breaks are the
--   characters that <a>CommentLine</a> lists.
[inline] :: Comments -> !Maybe Text

-- | The lines below the node: after the last entry of a collection,
--   between the brackets of an empty collection, or below a scalar or an
--   alias in a block collection or at the root. The section
--   <a>Comments</a> gives the rules. The renderer writes such lines below
--   any node.
[after] :: Comments -> ![Line]

-- | No comments and no empty lines.
noComments :: Comments

-- | The node with the comments in place of its own. A record update of the
--   field is ambiguous where <a>Commented</a> is in scope.
withComments :: Comments -> Node -> Node

-- | A line of comments.
data Line
EmptyLine :: Line

-- | The number of <tt>#</tt> characters at the start of the comment, e.g.
--   2 for <tt>## Section</tt>, and the text after them, without the one
--   space after the <tt>#</tt> characters and without the white space at
--   its end. The renderer writes a count below 1 as 1. It writes a text
--   with line breaks as several comment lines with the same <tt>#</tt>
--   characters, and the parser reads them back as several comments.
--   U+0085, U+2028 and U+2029 count as line breaks here, because YAML 1.1
--   reads them as line breaks.
--   
--   The comment at the end of a line in <a>Comments</a> is a text without
--   a count. It keeps the <tt>#</tt> characters after the first one in its
--   text.
CommentLine :: !Int -> !Text -> Line

-- | A comment with one <tt>#</tt>. As a pattern, it matches every comment
--   and ignores the number of <tt>#</tt> characters.
pattern Comment :: Text -> Line


-- | The values of YAML documents: the content with resolved tags, without
--   the styles, comments and positions of the syntax tree.
--   
--   A <a>Value</a> has <a>FromYaml</a> and <a>ToYaml</a> instances, e.g.
--   to read a document whose structure a program does not know:
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Value "!point {x: 1, y: 2.5}\n"
--   Right (Tagged "!point" (Mapping [(String "x",Int 1),(String "y",Float (Finite 2.5))]))
--   </pre>
--   
--   An alias becomes a copy of the value that it refers to:
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Value "base: &amp;b [1, 2]\ncopy: *b\n"
--   Right (Mapping [(String "base",Sequence [Int 1,Int 2]),(String "copy",Sequence [Int 1,Int 2])])
--   </pre>
--   
--   A small input with many aliases can give a large value. To prevent
--   this, the decoder limits the aliases. Each node and each character of
--   a scalar, a tag or an anchor counts as one unit. The aliases can add
--   100000 units to a document. For a document with more units, they can
--   add as many units as the document has. The documents of a stream share
--   the limit, as if they were one document. A document beyond the limit
--   is an error.
module Yamlet.Value

-- | The value of a node.
--   
--   <a>Eq</a> and <a>Ord</a> compare the entries of mappings in order, so
--   two mappings with the same entries in a different order are not equal,
--   unlike in YAML.
data Value
Null :: Value
Bool :: !Bool -> Value
Int :: !Integer -> Value
Float :: !FloatValue -> Value
String :: !Text -> Value
Sequence :: ![Value] -> Value

-- | The entries of a mapping in the order of the input. The keys are
--   unique. The encoder does not check this for a mapping that a program
--   builds, and a mapping with two equal keys does not read back. Keys are
--   equal as in YAML, e.g. two mappings with the same entries in a
--   different order are equal keys.
Mapping :: ![(Value, Value)] -> Value

-- | A value with a tag that is not the tag of the core schema for it, e.g.
--   <tt>!point {x: 1}</tt>. A scalar with a tag that the schema does not
--   know is a <a>String</a> inside, e.g. <tt>!secret abc</tt>.
--   
--   The encoder writes the tag. Some values read back with a change:
--   
--   <ul>
--   <li>A value with its own tag of the core schema reads back without
--   <a>Tagged</a>, e.g. <tt>Tagged intTag (Int 1)</tt> as <tt>Int
--   1</tt>.</li>
--   <li>A value that does not fit a tag of the core schema does not read
--   back, e.g. a <a>String</a> with <a>intTag</a>.</li>
--   <li>A scalar other than a <a>String</a> with a tag that the schema
--   does not know reads back as a <a>String</a>, e.g. <tt>Tagged "!x" (Int
--   5)</tt> as <tt>Tagged "!x" (String "5")</tt>.</li>
--   <li>YAML has no syntax for the empty tag or a tag of one character,
--   e.g. <tt>x</tt> or <tt>!</tt>. The encoder drops such a tag, e.g.
--   <tt>Tagged "" (Int 1)</tt> reads back as <tt>Int 1</tt>.</li>
--   <li>A node has one tag, so the encoder writes only the outermost tag
--   that it does not drop, e.g. <tt>Tagged "!a" (Tagged "!b" (Sequence
--   []))</tt> reads back as <tt>Tagged "!a" (Sequence [])</tt>.</li>
--   </ul>
Tagged :: !Text -> !Value -> Value

-- | The value of a floating-point number. A finite value is exact, e.g.
--   <tt>0.1</tt> is exactly one tenth.
--   
--   Arithmetic on a <a>Scientific</a> with a huge exponent, e.g.
--   <tt>1e1000000000</tt>, can use all memory. Convert a value from an
--   untrusted input with <a>floatValueToRealFloat</a> or with the bounded
--   conversions of <a>Data.Scientific</a>.
data FloatValue

-- | A finite value other than negative zero.
--   
--   The encoder writes a value whose exponent in scientific notation is
--   beyond the range from -1000 to 1000, e.g. <tt>1.0e+1001</tt>, but the
--   decoder rejects it. The decoder never gives such a value, and a
--   <a>Double</a> is always in the range.
Finite :: !Scientific -> FloatValue

-- | Negative zero, e.g. <tt>-0.0</tt>, which a <a>Scientific</a> cannot
--   hold.
NegativeZero :: FloatValue
Infinity :: FloatValue
NegativeInfinity :: FloatValue
NaN :: FloatValue

-- | The nearest value of a floating-point type, e.g. <a>Double</a>,
--   infinite if the value is out of its range. The decimal converts to the
--   type directly, so it is rounded once, e.g. a <a>Float</a> does not go
--   by way of a <a>Double</a>.
--   
--   <pre>
--   &gt;&gt;&gt; map (floatValueToRealFloat @Double) [Finite 0.1, Finite 1e400, NegativeZero]
--   [0.1,Infinity,-0.0]
--   </pre>
floatValueToRealFloat :: RealFloat a => FloatValue -> a

-- | The value of a floating-point number, e.g. a <a>Double</a>. A finite
--   number becomes the shortest decimal that reads back as the same
--   number, e.g. <tt>0.1</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; map (realFloatToFloatValue @Double) [0.1, -0, 1 / 0]
--   [Finite 0.1,NegativeZero,Infinity]
--   </pre>
realFloatToFloatValue :: RealFloat a => a -> FloatValue

-- | The kind of a value in plain words, for error messages, e.g. "a list".
--   The tag of <a>Tagged</a> does not change it.
--   
--   <pre>
--   &gt;&gt;&gt; describe (Tagged "!point" (Mapping []))
--   "a mapping"
--   </pre>
describe :: Value -> String

-- | The tag of a value: the tag of <a>Tagged</a>, or else the tag of the
--   core schema, e.g. <a>intTag</a> for an <a>Int</a>.
--   
--   <pre>
--   &gt;&gt;&gt; map valueTag [Int 1, Tagged "!point" (Mapping [])]
--   ["tag:yaml.org,2002:int","!point"]
--   </pre>
valueTag :: Value -> Text

-- | <tt>tag:yaml.org,2002:null</tt>.
nullTag :: Text

-- | <tt>tag:yaml.org,2002:bool</tt>.
boolTag :: Text

-- | <tt>tag:yaml.org,2002:int</tt>.
intTag :: Text

-- | <tt>tag:yaml.org,2002:float</tt>.
floatTag :: Text

-- | <tt>tag:yaml.org,2002:str</tt>.
strTag :: Text

-- | <tt>tag:yaml.org,2002:seq</tt>.
seqTag :: Text

-- | <tt>tag:yaml.org,2002:map</tt>.
mapTag :: Text
instance GHC.Classes.Eq Yamlet.Value.FloatValue
instance GHC.Classes.Eq Yamlet.Value.Value
instance GHC.Internal.Generics.Generic Yamlet.Value.FloatValue
instance GHC.Internal.Generics.Generic Yamlet.Value.Value
instance Control.DeepSeq.NFData Yamlet.Value.FloatValue
instance Control.DeepSeq.NFData Yamlet.Value.Value
instance GHC.Classes.Ord Yamlet.Value.FloatValue
instance GHC.Classes.Ord Yamlet.Value.Value
instance GHC.Internal.Show.Show Yamlet.Value.FloatValue
instance GHC.Internal.Show.Show Yamlet.Value.Value


-- | The core schema of YAML 1.2.2.
--   
--   This module is intended for internal use only, and may change without
--   warning in subsequent releases.
module Yamlet.Internal.Schema

-- | The value of a plain scalar without a tag. Not every such scalar is a
--   string, e.g. <tt>null</tt>, <tt>true</tt>, <tt>12</tt>, <tt>0x1F</tt>
--   and <tt>1.5e3</tt> are not. Quoted and block scalars are always
--   strings.
--   
--   A float whose exponent in scientific notation is beyond the range from
--   -1000 to 1000, e.g. <tt>1e1001</tt>, <tt>10e1000</tt> or
--   <tt>1e-1001</tt>, becomes infinity or zero, as a double does. The
--   decoders reject such a number, because its value is not exact.
--   
--   <pre>
--   &gt;&gt;&gt; map resolvePlain ["", "true", "0x1F", "1.5e3", ".inf", "yes", "9.10.3"]
--   [Null,Bool True,Int 31,Float (Finite 1500.0),Float Infinity,String "yes",String "9.10.3"]
--   </pre>
resolvePlain :: Text -> Value

-- | The value of a scalar with the given resolved tag, e.g.
--   <tt>tag:yaml.org,2002:int</tt>. Return <a>Nothing</a> if the text is
--   not valid for a tag of the core schema. A scalar with another tag is a
--   string.
--   
--   A float beyond the limit becomes infinity or zero, as in
--   <a>resolvePlain</a>.
--   
--   <pre>
--   &gt;&gt;&gt; [resolveTagged floatTag "1", resolveTagged intTag "abc", resolveTagged seqTag "x", resolveTagged "!point" "1"]
--   [Just (Float (Finite 1.0)),Nothing,Nothing,Just (String "1")]
--   </pre>
resolveTagged :: Text -> Text -> Maybe Value

-- | The value of a plain scalar, <a>Left</a> if the value is not exact.
resolvePlainExact :: Text -> Either Value Value

-- | The value of a scalar with a tag, <a>Left</a> if the value is not
--   exact.
resolveTaggedExact :: Text -> Text -> Maybe (Either Value Value)

-- | A plain scalar that starts with the character can be a number. Only
--   such a scalar can have a value that is not exact.
startsNumber :: Char -> Bool

-- | A plain scalar with the text is a string, e.g. <tt>9.10.3</tt> is a
--   string, but <tt>9.10</tt> and <tt>true</tt> are not. The check ignores
--   the syntax, so e.g. <tt>a: b</tt> passes. For both checks, use
--   <a>isPlainSafe</a>.
--   
--   <pre>
--   &gt;&gt;&gt; map isPlainString ["9.10.3", "9.10", "true", "a: b"]
--   [True,False,False,True]
--   </pre>
isPlainString :: Text -> Bool

-- | The string reads back as the same string if it is a plain scalar in
--   the block style, as a value or as a key. A key without <tt>?</tt> must
--   also have at most 1024 characters, which the check does not count. In
--   a flow collection the characters <tt>,[]{}</tt> need quotes too, so
--   the check does not apply there.
--   
--   <pre>
--   &gt;&gt;&gt; map isPlainSafe ["a:b", "a: b", "- a", "a #b", "9.10"]
--   [True,False,False,False,False]
--   </pre>
isPlainSafe :: Text -> Bool

-- | As <a>isPlainSafe</a>, and common YAML 1.1 parsers also read the plain
--   scalar as a string, e.g. not <tt>yes</tt> as a boolean or
--   <tt>12:30</tt> as a number. The encoder writes a string without quotes
--   only if it passes this check.
--   
--   <pre>
--   &gt;&gt;&gt; map isPlainPortable ["a:b", "yes", "12:30", "2024-01-01", "9.10.3"]
--   [True,False,False,False,True]
--   </pre>
isPlainPortable :: Text -> Bool

-- | A word that YAML 1.1 reads as a boolean, but YAML 1.2 as a string,
--   e.g. <tt>yes</tt> or <tt>off</tt>.
isYaml11Bool :: Text -> Bool

-- | A common YAML 1.1 parser reads a plain scalar with the text as a value
--   that is not a string, e.g. the boolean <tt>yes</tt>, the base-60
--   number <tt>12:30</tt> or the date <tt>2024-01-01</tt>. The patterns
--   cover what PyYAML, Ruby's Psych and go-yaml v2, which Kubernetes uses,
--   accept. The YAML 1.1 types themselves are not enough: the parsers
--   accept more, e.g. <tt>1,000</tt> in Psych and <tt>0X1F</tt> in go-yaml
--   v2, and the type of floats accepts too much, e.g. <tt>1.2.3</tt>.
isYaml11NonString :: Text -> Bool

-- | A common YAML 1.1 parser reads a plain scalar with the text as a
--   timestamp and can build it. PyYAML has the years from 1 to 9999 of
--   Python, and it rejects the hour 24, a leap second and a time zone of
--   24 hours. Psych reads the hour 24 and a leap second as a later time.
--   
--   <pre>
--   &gt;&gt;&gt; map isYaml11Timestamp ["2024-01-01", "2024-01-01T12:30:00Z", "0000-01-01", "2016-12-31T23:59:60Z", "12:30"]
--   [True,True,False,False,False]
--   </pre>
isYaml11Timestamp :: Text -> Bool

-- | The error for a number beyond <a>maxExponent</a>.
exponentOutOfRange :: String


-- | The core schema of YAML 1.2.2: the rules that give a scalar its value.
--   
--   A decoder applies these rules to every scalar. A program that writes
--   YAML can use them to check how a plain scalar reads back, e.g.
--   <tt>9.10</tt> is a number, not a string.
module Yamlet.Schema

-- | The value of a plain scalar without a tag. Not every such scalar is a
--   string, e.g. <tt>null</tt>, <tt>true</tt>, <tt>12</tt>, <tt>0x1F</tt>
--   and <tt>1.5e3</tt> are not. Quoted and block scalars are always
--   strings.
--   
--   A float whose exponent in scientific notation is beyond the range from
--   -1000 to 1000, e.g. <tt>1e1001</tt>, <tt>10e1000</tt> or
--   <tt>1e-1001</tt>, becomes infinity or zero, as a double does. The
--   decoders reject such a number, because its value is not exact.
--   
--   <pre>
--   &gt;&gt;&gt; map resolvePlain ["", "true", "0x1F", "1.5e3", ".inf", "yes", "9.10.3"]
--   [Null,Bool True,Int 31,Float (Finite 1500.0),Float Infinity,String "yes",String "9.10.3"]
--   </pre>
resolvePlain :: Text -> Value

-- | The value of a scalar with the given resolved tag, e.g.
--   <tt>tag:yaml.org,2002:int</tt>. Return <a>Nothing</a> if the text is
--   not valid for a tag of the core schema. A scalar with another tag is a
--   string.
--   
--   A float beyond the limit becomes infinity or zero, as in
--   <a>resolvePlain</a>.
--   
--   <pre>
--   &gt;&gt;&gt; [resolveTagged floatTag "1", resolveTagged intTag "abc", resolveTagged seqTag "x", resolveTagged "!point" "1"]
--   [Just (Float (Finite 1.0)),Nothing,Nothing,Just (String "1")]
--   </pre>
resolveTagged :: Text -> Text -> Maybe Value

-- | A plain scalar with the text is a string, e.g. <tt>9.10.3</tt> is a
--   string, but <tt>9.10</tt> and <tt>true</tt> are not. The check ignores
--   the syntax, so e.g. <tt>a: b</tt> passes. For both checks, use
--   <a>isPlainSafe</a>.
--   
--   <pre>
--   &gt;&gt;&gt; map isPlainString ["9.10.3", "9.10", "true", "a: b"]
--   [True,False,False,True]
--   </pre>
isPlainString :: Text -> Bool

-- | The string reads back as the same string if it is a plain scalar in
--   the block style, as a value or as a key. A key without <tt>?</tt> must
--   also have at most 1024 characters, which the check does not count. In
--   a flow collection the characters <tt>,[]{}</tt> need quotes too, so
--   the check does not apply there.
--   
--   <pre>
--   &gt;&gt;&gt; map isPlainSafe ["a:b", "a: b", "- a", "a #b", "9.10"]
--   [True,False,False,False,False]
--   </pre>
isPlainSafe :: Text -> Bool

-- | As <a>isPlainSafe</a>, and common YAML 1.1 parsers also read the plain
--   scalar as a string, e.g. not <tt>yes</tt> as a boolean or
--   <tt>12:30</tt> as a number. The encoder writes a string without quotes
--   only if it passes this check.
--   
--   <pre>
--   &gt;&gt;&gt; map isPlainPortable ["a:b", "yes", "12:30", "2024-01-01", "9.10.3"]
--   [True,False,False,False,True]
--   </pre>
isPlainPortable :: Text -> Bool


-- | The values of the nodes of a syntax tree.
--   
--   This module is intended for internal use only, and may change without
--   warning in subsequent releases.
module Yamlet.Internal.View

-- | The value of a node with its tag resolved. The items and the entries
--   of a collection stay nodes of the syntax tree. A tag that the schema
--   does not know does not matter, e.g. <tt>!secret abc</tt> is a string.
data View
NullView :: View
BoolView :: !Bool -> View
IntView :: !Integer -> View
FloatView :: !FloatValue -> View
StringView :: !Text -> View
SequenceView :: ![Node] -> View
MappingView :: ![(Node, Node)] -> View

-- | An alias, e.g. in a node from <a>parseDocuments</a>. <a>runParser</a>
--   replaces the aliases, so a parser never sees one.
AliasView :: !Text -> View

-- | The view of a node.
view :: Node -> View

-- | The value of a scalar with the tag and the style, without the tag.
scalarValue :: Tag -> ScalarStyle -> Text -> Value

-- | The kind of a node in plain words, e.g. "a list".
--   
--   <pre>
--   &gt;&gt;&gt; map describeNode &lt;$&gt; decodeText @[Node] "- [1, 2]\n- 3.5\n- ~\n- !!str 12\n"
--   Right ["a list","a floating-point number","null","a string"]
--   </pre>
describeNode :: Node -> String

-- | The node is null.
isNullNode :: Node -> Bool

-- | The text of a string node.
stringValue :: Node -> Maybe Text

-- | A key or an item as the input writes it, for an error: a string in
--   quotes, an alias with its <tt>*</tt> and another scalar as it is. A
--   collection and an empty scalar have no text.
inputText :: Node -> Maybe String
instance GHC.Classes.Eq Yamlet.Internal.View.View
instance GHC.Internal.Generics.Generic Yamlet.Internal.View.View
instance GHC.Internal.Show.Show Yamlet.Internal.View.View


-- | The class <a>ToYaml</a>, its instances and the parts of the encoder
--   that the generic instances share with it. <a>Yamlet.Encode</a> exports
--   the public parts.
--   
--   This module is intended for internal use only, and may change without
--   warning in subsequent releases.
module Yamlet.Internal.ToYaml

-- | Types that can be converted to a node. A type with a <a>Generic</a>
--   instance can derive the instance via <a>GenericYaml</a>.
--   
--   An instance for a record writes a mapping with <a>mapping</a> and
--   <a>.=</a>:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   data Server = Server {host :: T.Text, port :: Int, tags :: [T.Text]}
--   instance ToYaml Server where
--     toYaml s = mapping ["host" .= s.host, "port" .= s.port, "tags" .= s.tags]
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; T.putStr (encodeText (Server "example.com" 80 ["web", "yes"]))
--   host: example.com
--   port: 80
--   tags:
--   - web
--   - 'yes'
--   </pre>
--   
--   The string <tt>yes</tt> gets quotes, because YAML 1.1 parsers read it
--   as a boolean.
class ToYaml a
toYaml :: ToYaml a => a -> Node

-- | Convert a list. The instance for <a>Char</a> creates a string instead.
toYamlList :: ToYaml a => [a] -> Node

-- | Convert the value of a mapping entry, with the node of its key, e.g.
--   to put comments on the key as <a>Commented</a> does. <a>.=</a>, the
--   derived encoders and the instances for maps use it. The default
--   returns the key unchanged.
toYamlField :: ToYaml a => Node -> a -> (Node, Node)

-- | An entry of a mapping with a string key.
(.=) :: ToYaml a => Text -> a -> (Node, Node)
infixr 8 .=

-- | A mapping with the entries in the given order. A mapping with two
--   equal keys does not read back.
mapping :: [(Node, Node)] -> Node

-- | A string as a literal block scalar if it has a line break. A text of
--   only line breaks is in double quotes, because quotes are easier to
--   read than empty lines. Otherwise it is a plain scalar if the schema
--   reads the text as a string, and in single quotes if not. The renderer
--   puts a plain scalar in quotes if its text cannot be plain, e.g. <tt>a:
--   b</tt>. It uses double quotes for a text with a tab or a character
--   that single quotes cannot hold.
--   
--   A text that YAML 1.1 reads as another type, e.g. <tt>yes</tt> or
--   <tt>12:30</tt>, is in quotes too, because many parsers still follow
--   YAML 1.1.
string :: Text -> Node

-- | A scalar in a style that reads back as the value. For a collection or
--   a tagged value, use <a>toSyntax</a>.
scalar :: Value -> Node
instance Yamlet.Internal.ToYaml.ToYaml GHC.Internal.Data.Semigroup.Internal.All
instance Yamlet.Internal.ToYaml.ToYaml GHC.Internal.Data.Semigroup.Internal.Any
instance Yamlet.Internal.ToYaml.ToYaml GHC.Types.Bool
instance Yamlet.Internal.ToYaml.ToYaml Data.Time.Calendar.CalendarDiffDays.CalendarDiffDays
instance Yamlet.Internal.ToYaml.ToYaml Data.Time.LocalTime.Internal.CalendarDiffTime.CalendarDiffTime
instance Yamlet.Internal.ToYaml.ToYaml GHC.Types.Char
instance Yamlet.Internal.ToYaml.ToYaml a => Yamlet.Internal.ToYaml.ToYaml (Yamlet.Internal.Syntax.Commented a)
instance forall k a (b :: k). Yamlet.Internal.ToYaml.ToYaml a => Yamlet.Internal.ToYaml.ToYaml (GHC.Internal.Data.Functor.Const.Const a b)
instance Yamlet.Internal.ToYaml.ToYaml Data.Time.Calendar.Days.Day
instance Yamlet.Internal.ToYaml.ToYaml Data.Time.Calendar.Week.DayOfWeek
instance Yamlet.Internal.ToYaml.ToYaml Data.Time.Clock.Internal.DiffTime.DiffTime
instance Yamlet.Internal.ToYaml.ToYaml GHC.Types.Double
instance Yamlet.Internal.ToYaml.ToYaml a => Yamlet.Internal.ToYaml.ToYaml (GHC.Internal.Data.Ord.Down a)
instance Yamlet.Internal.ToYaml.ToYaml a => Yamlet.Internal.ToYaml.ToYaml (GHC.Internal.Data.Semigroup.Internal.Dual a)
instance (Yamlet.Internal.ToYaml.ToYaml a, Yamlet.Internal.ToYaml.ToYaml b) => Yamlet.Internal.ToYaml.ToYaml (GHC.Internal.Data.Either.Either a b)
instance Yamlet.Internal.ToYaml.ToYaml a => Yamlet.Internal.ToYaml.ToYaml (GHC.Internal.Data.Monoid.First a)
instance Yamlet.Internal.ToYaml.ToYaml a => Yamlet.Internal.ToYaml.ToYaml (Data.Semigroup.First a)
instance forall k (a :: k). Data.Fixed.HasResolution a => Yamlet.Internal.ToYaml.ToYaml (Data.Fixed.Fixed a)
instance Yamlet.Internal.ToYaml.ToYaml GHC.Types.Float
instance Yamlet.Internal.ToYaml.ToYaml a => Yamlet.Internal.ToYaml.ToYaml (GHC.Internal.Data.Functor.Identity.Identity a)
instance Yamlet.Internal.ToYaml.ToYaml GHC.Types.Int
instance Yamlet.Internal.ToYaml.ToYaml GHC.Internal.Int.Int16
instance Yamlet.Internal.ToYaml.ToYaml GHC.Internal.Int.Int32
instance Yamlet.Internal.ToYaml.ToYaml GHC.Internal.Int.Int64
instance Yamlet.Internal.ToYaml.ToYaml GHC.Internal.Int.Int8
instance Yamlet.Internal.ToYaml.ToYaml v => Yamlet.Internal.ToYaml.ToYaml (Data.IntMap.Internal.IntMap v)
instance Yamlet.Internal.ToYaml.ToYaml Data.IntSet.Internal.IntSet
instance Yamlet.Internal.ToYaml.ToYaml GHC.Num.Integer.Integer
instance Yamlet.Internal.ToYaml.ToYaml a => Yamlet.Internal.ToYaml.ToYaml (GHC.Internal.Data.Monoid.Last a)
instance Yamlet.Internal.ToYaml.ToYaml a => Yamlet.Internal.ToYaml.ToYaml (Data.Semigroup.Last a)
instance Yamlet.Internal.ToYaml.ToYaml a => Yamlet.Internal.ToYaml.ToYaml [a]
instance Yamlet.Internal.ToYaml.ToYaml Data.Time.LocalTime.Internal.LocalTime.LocalTime
instance Yamlet.Internal.ToYaml.ToYaml a => Yamlet.Internal.ToYaml.ToYaml (Yamlet.Internal.Syntax.Located a)
instance (Yamlet.Internal.ToYaml.ToYaml k, Yamlet.Internal.ToYaml.ToYaml v) => Yamlet.Internal.ToYaml.ToYaml (Data.Map.Internal.Map k v)
instance Yamlet.Internal.ToYaml.ToYaml a => Yamlet.Internal.ToYaml.ToYaml (Data.Semigroup.Max a)
instance Yamlet.Internal.ToYaml.ToYaml a => Yamlet.Internal.ToYaml.ToYaml (GHC.Internal.Maybe.Maybe a)
instance Yamlet.Internal.ToYaml.ToYaml a => Yamlet.Internal.ToYaml.ToYaml (Data.Semigroup.Min a)
instance Yamlet.Internal.ToYaml.ToYaml Data.Time.Calendar.Month.Month
instance Yamlet.Internal.ToYaml.ToYaml GHC.Num.Natural.Natural
instance Yamlet.Internal.ToYaml.ToYaml Yamlet.Internal.Syntax.Node
instance Yamlet.Internal.ToYaml.ToYaml Data.Time.Clock.Internal.NominalDiffTime.NominalDiffTime
instance Yamlet.Internal.ToYaml.ToYaml a => Yamlet.Internal.ToYaml.ToYaml (GHC.Internal.Base.NonEmpty a)
instance Yamlet.Internal.ToYaml.ToYaml GHC.Types.Ordering
instance Yamlet.Internal.ToYaml.ToYaml a => Yamlet.Internal.ToYaml.ToYaml (GHC.Internal.Data.Semigroup.Internal.Product a)
instance Yamlet.Internal.ToYaml.ToYaml Data.Time.Calendar.Quarter.Quarter
instance Yamlet.Internal.ToYaml.ToYaml Data.Time.Calendar.Quarter.QuarterOfYear
instance (GHC.Internal.Real.Integral a, Yamlet.Internal.ToYaml.ToYaml a) => Yamlet.Internal.ToYaml.ToYaml (GHC.Internal.Real.Ratio a)
instance Yamlet.Internal.ToYaml.ToYaml Data.Scientific.Scientific
instance Yamlet.Internal.ToYaml.ToYaml a => Yamlet.Internal.ToYaml.ToYaml (Data.Sequence.Internal.Seq a)
instance Yamlet.Internal.ToYaml.ToYaml a => Yamlet.Internal.ToYaml.ToYaml (Data.Set.Internal.Set a)
instance Yamlet.Internal.ToYaml.ToYaml a => Yamlet.Internal.ToYaml.ToYaml (GHC.Internal.Data.Semigroup.Internal.Sum a)
instance Yamlet.Internal.ToYaml.ToYaml Data.Text.Internal.Lazy.Text
instance Yamlet.Internal.ToYaml.ToYaml Data.Text.Internal.Text
instance Yamlet.Internal.ToYaml.ToYaml Data.Time.LocalTime.Internal.TimeOfDay.TimeOfDay
instance Yamlet.Internal.ToYaml.ToYaml a => Yamlet.Internal.ToYaml.ToYaml (Data.Tree.Tree a)
instance (Yamlet.Internal.ToYaml.ToYaml a1, Yamlet.Internal.ToYaml.ToYaml a2, Yamlet.Internal.ToYaml.ToYaml a3, Yamlet.Internal.ToYaml.ToYaml a4, Yamlet.Internal.ToYaml.ToYaml a5, Yamlet.Internal.ToYaml.ToYaml a6, Yamlet.Internal.ToYaml.ToYaml a7, Yamlet.Internal.ToYaml.ToYaml a8, Yamlet.Internal.ToYaml.ToYaml a9, Yamlet.Internal.ToYaml.ToYaml a10) => Yamlet.Internal.ToYaml.ToYaml (a1, a2, a3, a4, a5, a6, a7, a8, a9, a10)
instance (Yamlet.Internal.ToYaml.ToYaml a1, Yamlet.Internal.ToYaml.ToYaml a2) => Yamlet.Internal.ToYaml.ToYaml (a1, a2)
instance (Yamlet.Internal.ToYaml.ToYaml a1, Yamlet.Internal.ToYaml.ToYaml a2, Yamlet.Internal.ToYaml.ToYaml a3) => Yamlet.Internal.ToYaml.ToYaml (a1, a2, a3)
instance (Yamlet.Internal.ToYaml.ToYaml a1, Yamlet.Internal.ToYaml.ToYaml a2, Yamlet.Internal.ToYaml.ToYaml a3, Yamlet.Internal.ToYaml.ToYaml a4) => Yamlet.Internal.ToYaml.ToYaml (a1, a2, a3, a4)
instance (Yamlet.Internal.ToYaml.ToYaml a1, Yamlet.Internal.ToYaml.ToYaml a2, Yamlet.Internal.ToYaml.ToYaml a3, Yamlet.Internal.ToYaml.ToYaml a4, Yamlet.Internal.ToYaml.ToYaml a5) => Yamlet.Internal.ToYaml.ToYaml (a1, a2, a3, a4, a5)
instance (Yamlet.Internal.ToYaml.ToYaml a1, Yamlet.Internal.ToYaml.ToYaml a2, Yamlet.Internal.ToYaml.ToYaml a3, Yamlet.Internal.ToYaml.ToYaml a4, Yamlet.Internal.ToYaml.ToYaml a5, Yamlet.Internal.ToYaml.ToYaml a6) => Yamlet.Internal.ToYaml.ToYaml (a1, a2, a3, a4, a5, a6)
instance (Yamlet.Internal.ToYaml.ToYaml a1, Yamlet.Internal.ToYaml.ToYaml a2, Yamlet.Internal.ToYaml.ToYaml a3, Yamlet.Internal.ToYaml.ToYaml a4, Yamlet.Internal.ToYaml.ToYaml a5, Yamlet.Internal.ToYaml.ToYaml a6, Yamlet.Internal.ToYaml.ToYaml a7) => Yamlet.Internal.ToYaml.ToYaml (a1, a2, a3, a4, a5, a6, a7)
instance (Yamlet.Internal.ToYaml.ToYaml a1, Yamlet.Internal.ToYaml.ToYaml a2, Yamlet.Internal.ToYaml.ToYaml a3, Yamlet.Internal.ToYaml.ToYaml a4, Yamlet.Internal.ToYaml.ToYaml a5, Yamlet.Internal.ToYaml.ToYaml a6, Yamlet.Internal.ToYaml.ToYaml a7, Yamlet.Internal.ToYaml.ToYaml a8) => Yamlet.Internal.ToYaml.ToYaml (a1, a2, a3, a4, a5, a6, a7, a8)
instance (Yamlet.Internal.ToYaml.ToYaml a1, Yamlet.Internal.ToYaml.ToYaml a2, Yamlet.Internal.ToYaml.ToYaml a3, Yamlet.Internal.ToYaml.ToYaml a4, Yamlet.Internal.ToYaml.ToYaml a5, Yamlet.Internal.ToYaml.ToYaml a6, Yamlet.Internal.ToYaml.ToYaml a7, Yamlet.Internal.ToYaml.ToYaml a8, Yamlet.Internal.ToYaml.ToYaml a9) => Yamlet.Internal.ToYaml.ToYaml (a1, a2, a3, a4, a5, a6, a7, a8, a9)
instance Yamlet.Internal.ToYaml.ToYaml Data.Time.Clock.Internal.UTCTime.UTCTime
instance Yamlet.Internal.ToYaml.ToYaml Data.UUID.Types.Internal.UUID
instance Yamlet.Internal.ToYaml.ToYaml ()
instance Yamlet.Internal.ToYaml.ToYaml Yamlet.Value.Value
instance Yamlet.Internal.ToYaml.ToYaml GHC.Internal.Base.Void
instance Yamlet.Internal.ToYaml.ToYaml GHC.Types.Word
instance Yamlet.Internal.ToYaml.ToYaml GHC.Internal.Word.Word16
instance Yamlet.Internal.ToYaml.ToYaml GHC.Internal.Word.Word32
instance Yamlet.Internal.ToYaml.ToYaml GHC.Internal.Word.Word64
instance Yamlet.Internal.ToYaml.ToYaml GHC.Internal.Word.Word8
instance Yamlet.Internal.ToYaml.ToYaml Data.Time.LocalTime.Internal.ZonedTime.ZonedTime


-- | Conversion of Haskell values to nodes.
module Yamlet.Encode

-- | Types that can be converted to a node. A type with a <a>Generic</a>
--   instance can derive the instance via <a>GenericYaml</a>.
--   
--   An instance for a record writes a mapping with <a>mapping</a> and
--   <a>.=</a>:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   data Server = Server {host :: T.Text, port :: Int, tags :: [T.Text]}
--   instance ToYaml Server where
--     toYaml s = mapping ["host" .= s.host, "port" .= s.port, "tags" .= s.tags]
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; T.putStr (encodeText (Server "example.com" 80 ["web", "yes"]))
--   host: example.com
--   port: 80
--   tags:
--   - web
--   - 'yes'
--   </pre>
--   
--   The string <tt>yes</tt> gets quotes, because YAML 1.1 parsers read it
--   as a boolean.
class ToYaml a
toYaml :: ToYaml a => a -> Node

-- | Convert a list. The instance for <a>Char</a> creates a string instead.
toYamlList :: ToYaml a => [a] -> Node

-- | Convert the value of a mapping entry, with the node of its key, e.g.
--   to put comments on the key as <a>Commented</a> does. <a>.=</a>, the
--   derived encoders and the instances for maps use it. The default
--   returns the key unchanged.
toYamlField :: ToYaml a => Node -> a -> (Node, Node)

-- | An entry of a mapping with a string key.
(.=) :: ToYaml a => Text -> a -> (Node, Node)
infixr 8 .=

-- | A mapping with the entries in the given order. A mapping with two
--   equal keys does not read back.
mapping :: [(Node, Node)] -> Node


-- | The checks of a syntax tree before the decoder reads it, and the
--   values of its nodes.
--   
--   This module is intended for internal use only, and may change without
--   warning in subsequent releases.
module Yamlet.Internal.Compose

-- | Check that the tags of a node are valid and that the keys of every
--   mapping are unique, and replace each alias with the node that it
--   refers to. The result has no aliases. A node without aliases comes
--   back unchanged.
--   
--   The arguments are the limit of the visits that the aliases can add,
--   see <a>aliasLimit</a>, and the visits that the aliases of the
--   documents before added. The result also gives the visits that the
--   aliases added with this document.
prepareWithin :: Int -> Int -> Node -> Either Failure (Node, Int)

-- | The limit of the visits of a traversal that the aliases of the
--   documents can add together: as many visits as the documents have, or a
--   fixed minimum for small documents. A node is one visit and each
--   character of its scalar, tag and anchor is one more, because the
--   decoder copies the texts of each alias. Without a limit, the visits of
--   a small input can be exponential in its size. The documents of a
--   stream share the limit, so that many small documents cannot add the
--   minimum each.
aliasLimit :: [Node] -> Int

-- | The value of a node that passed <a>prepareWithin</a>, so it has no
--   aliases and its keys are unique already.
representPrepared :: Node -> Either Failure Value

-- | The offset of the node that caused an error and the message, and the
--   notes that go after it, e.g. the first key of a duplicate key.
type Failure = NonEmpty (Offset, String)

-- | The hint after the message of an error at a key <tt>&lt;&lt;</tt>.
--   YAML 1.1 used it to merge mappings, and some tools still do, but in
--   YAML 1.2 it is a string.
noMergeKeys :: String
instance GHC.Classes.Eq Yamlet.Internal.Compose.Shape
instance GHC.Classes.Ord Yamlet.Internal.Compose.Shape


-- | The class <a>FromYaml</a>, its instances and the parts of the decoder
--   that the generic instances share with it. <a>Yamlet.Decode</a> exports
--   the public parts.
--   
--   This module is intended for internal use only, and may change without
--   warning in subsequent releases.
module Yamlet.Internal.FromYaml

-- | Types that can be parsed from a node. A type with a <a>Generic</a>
--   instance can derive the instance via <a>GenericYaml</a>.
--   
--   An instance for a record reads a mapping with <a>withMapping</a>:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   data Server = Server {host :: T.Text, port :: Int, tags :: [T.Text]}
--     deriving stock (Show)
--   instance FromYaml Server where
--     parseYaml = withMapping $ \o -&gt;
--       rejectUnknownKeys ["host", "port", "tags"] o
--         *&gt; ( Server
--                &lt;$&gt; parseField o "host"
--                &lt;*&gt; parseFieldDefault o "port" 80
--                &lt;*&gt; parseFieldDefault o "tags" []
--            )
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Server "host: example.com\ntags:\n- web\n"
--   Right (Server {host = "example.com", port = 80, tags = ["web"]})
--   </pre>
--   
--   The decoder reports the errors of all fields together:
--   
--   <pre>
--   &gt;&gt;&gt; either printErrors print (decodeText @Server "hots: example.com\nport: http\n")
--   input.yaml:1:1: unknown key "hots", did you mean "host"?
--     |
--   1 | hots: example.com
--     | ^
--   input.yaml:1:1: missing key "host"
--     |
--   1 | hots: example.com
--     | ^
--   input.yaml:2:7: port: expected an integer, but got a string
--     |
--   2 | port: http
--     |       ^
--   </pre>
--   
--   The instances of the library copy the texts that they keep, so a
--   decoded value does not keep the input in memory. A value from a
--   hand-written instance can keep the input while it has unevaluated
--   parts, e.g. a lazy list. Evaluate such a value, e.g. with
--   <a>force</a>, to release the input.
class FromYaml a
parseYaml :: FromYaml a => Node -> Parser a

-- | Parse a list. The instance for <a>Char</a> parses a string instead.
parseYamlList :: FromYaml a => Node -> Parser [a]

-- | Parse the value of a mapping entry, with its key, e.g. to keep the
--   comments of the key as <a>Commented</a> does. <a>parseField</a> and
--   the other lookups without a parser argument, the derived decoders and
--   the instances for maps use it. The default ignores the key.
parseYamlField :: FromYaml a => Node -> Node -> Parser a

-- | A parser of nodes. Its errors point to the node that the parser works
--   on, unless <a>failAt</a> names another one.
--   
--   The parser has no <a>Alternative</a> instance. To try another parser
--   after a failure, use <a>orElse</a>. To reject a value, fail with a
--   message that says why:
--   
--   <pre>
--   port &lt;- parseYaml n
--   unless (port &gt; 0 &amp;&amp; port &lt; 65536) $ fail "the port must be from 1 to 65535"
--   </pre>
--   
--   The applicative operators collect the errors of both parts:
--   <a>&lt;*&gt;</a>, <a>*&gt;</a>, <a>&lt;*</a>, <a>liftA2</a>, and the
--   functions that use them, e.g. <a>traverse</a>, <a>mapM</a> on a list
--   and <a>for_</a>. This parser gives the errors of the unknown keys and
--   of all fields together:
--   
--   <pre>
--   rejectUnknownKeys ["name", "paths"] o
--     *&gt; (Config &lt;$&gt; parseField o "name" &lt;*&gt; parseField o "paths")
--   </pre>
--   
--   <a>&gt;&gt;=</a> and <a>&gt;&gt;</a> stop at the first error. A
--   statement of a <tt>do</tt> block also stops, e.g. the check of the
--   port above. The functions that use <a>&gt;&gt;</a> also stop, e.g.
--   <a>mapM_</a> and <a>forM_</a>.
--   
--   The choice between them changes only the errors, never the result.
--   With <tt>ApplicativeDo</tt>, GHC turns the independent statements of a
--   <tt>do</tt> block that ends with <a>pure</a> into <a>&lt;*&gt;</a>.
--   Then they collect errors.
data Parser a

-- | Run a parser on a node. Each error is the offset of the node that
--   caused it and the message. The errors are in the order of the offsets,
--   and equal errors come only once. A note on an error comes right after
--   it, e.g. the first key of a duplicate key.
--   
--   First, the function makes the checks of <a>decodeDocument</a> on the
--   node, e.g. for duplicate keys. It also replaces each alias with the
--   node that the alias refers to. If a check fails, the result has only
--   the error of that check, with its notes.
runParser :: (Node -> Parser a) -> Node -> Either (NonEmpty (Offset, String)) a

-- | <a>runParser</a> with the visits of the aliases as for
--   <a>prepareWithin</a>.
runParserWithin :: Int -> Int -> (Node -> Parser a) -> Node -> Either (NonEmpty (Offset, String)) (a, Int)

-- | Run a parser on a node, so that <a>fail</a> points to the node.
parseNode :: (Node -> Parser a) -> Node -> Parser a

-- | Fail with an error that points to the given node.
failAt :: Node -> String -> Parser a

-- | Fail with an error that the node is not of the expected kind, e.g.
--   <tt>typeMismatch "a list" n</tt> gives "expected a list, but got a
--   string".
typeMismatch :: String -> Node -> Parser a

-- | Run the second parser if the first one fails. A port can be a number
--   or a name:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   newtype Port = Port (Either Integer T.Text)
--     deriving stock (Show)
--   instance FromYaml Port where
--     parseYaml n =
--       Port &lt;$&gt; ((Left &lt;$&gt; withInt pure n) `orElse` (Right &lt;$&gt; withText pure n))
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Port "8080"
--   Right (Port (Left 8080))
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Port "http"
--   Right (Port (Right "http"))
--   </pre>
--   
--   If both parsers fail, the result has only the errors of the second
--   one:
--   
--   <pre>
--   &gt;&gt;&gt; either printErrors print (decodeText @Port "[80]")
--   input.yaml:1:1: expected a string, but got a list
--     |
--   1 | [80]
--     | ^
--   </pre>
orElse :: Parser a -> Parser a -> Parser a
infixl 3 `orElse`

-- | Run the parser if the node is null.
withNull :: Parser a -> Node -> Parser a

-- | The value of a boolean.
withBool :: (Bool -> Parser a) -> Node -> Parser a

-- | The value of an integer.
withInt :: (Integer -> Parser a) -> Node -> Parser a

-- | The nearest double. An integer counts as a floating-point number too.
withFloat :: (Double -> Parser a) -> Node -> Parser a

-- | The exact value of a finite number. An integer counts too, and
--   negative zero becomes 0.
--   
--   A conversion to an exact type, e.g. with <a>truncate</a>, is safe for
--   untrusted input. An integer has the digits of its text, and the
--   decoder rejects a float whose exponent in scientific notation is
--   beyond the range from -1000 to 1000, also in a node that a program
--   built.
withScientific :: (Scientific -> Parser a) -> Node -> Parser a

-- | The text of a string. The text is a copy, so it does not keep the
--   input alive. For a plain scalar that YAML reads as a number or a
--   boolean, e.g. <tt>3.10</tt>, the error suggests quotes.
withText :: (Text -> Parser a) -> Node -> Parser a

-- | A string that is one of the names, e.g. the tags of the constructors.
--   For another node, the error suggests quotes only if the quoted text is
--   a name, e.g. not for <tt>null</tt>. Otherwise it lists the names.
withName :: [Text] -> (Text -> Parser a) -> Node -> Parser a

-- | The value that goes with the string in the list of pairs, e.g. for
--   names that the program knows only at run time. An empty list rejects
--   every value. The errors are the same as for the constructors of an
--   enumeration. An unknown name gets the closest name or the list of
--   names:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   newtype Size = Size Int
--     deriving stock (Show)
--   instance FromYaml Size where
--     parseYaml = oneOf [("small", Size 1), ("large", Size 2)]
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Size "large"
--   Right (Size 2)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; either printErrors print (decodeText @Size "lage")
--   input.yaml:1:1: unknown value "lage", did you mean "large"?
--     |
--   1 | lage
--     | ^
--   </pre>
oneOf :: [(Text, a)] -> Node -> Parser a

-- | The items of a sequence. As for <a>withMapping</a>, the comments of
--   the sequence stay with it, not with its first item.
withSequence :: ([Node] -> Parser a) -> Node -> Parser a

-- | The entries of a mapping. As for <a>withText</a>, the tag of a string
--   key does not matter, so two string keys with the same text are an
--   error, e.g. <tt>a</tt> and <tt>!foo a</tt>.
--   
--   The comments of the mapping stay with it, not with its first key, e.g.
--   a comment at the top of a file. A record has no place for them.
withMapping :: (Object -> Parser a) -> Node -> Parser a

-- | A mapping with fast access to the values of string keys.
data Object
Object :: !Node -> ![(Node, Node)] -> !Map Text (Node, Node) -> ![(Node, Value)] -> !Bool -> Object
[node] :: Object -> !Node
[entries] :: Object -> ![(Node, Node)]
[index] :: Object -> !Map Text (Node, Node)

-- | The scalar keys that are not strings, for the error of a lookup.
[otherKeys] :: Object -> ![(Node, Value)]

-- | Two string keys have the same text.
[duplicates] :: Object -> !Bool

-- | The node of the mapping.
objectNode :: Object -> Node

-- | The entries of the mapping in the order of the input.
objectEntries :: Object -> [(Node, Node)]

-- | The string keys of the mapping in the order of the input.
objectKeys :: Object -> [Text]

-- | The value of a key, or <a>Nothing</a> if the key is missing. As for
--   <a>parseField</a>, a key with the same text that is not a string, e.g.
--   <tt>404</tt>, is an error, so that its value does not go away.
lookupKey :: Object -> Text -> Parser (Maybe Node)

-- | The value of a key. It is an error if the key is missing.
parseField :: FromYaml a => Object -> Text -> Parser a

-- | The value of a key, or <a>Nothing</a> if the key is missing or its
--   value is null.
parseFieldMaybe :: FromYaml a => Object -> Text -> Parser (Maybe a)

-- | The value of a key, or <a>Nothing</a> if the key is missing. Unlike
--   <a>parseFieldMaybe</a>, a null value goes to the parser of the value,
--   e.g. <tt><a>Maybe</a> a</tt> gives <tt><a>Just</a> <a>Nothing</a></tt>
--   for a null value.
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   newtype Limit = Limit (Maybe (Maybe Int))
--     deriving stock (Show)
--   instance FromYaml Limit where
--     parseYaml = withMapping $ \o -&gt; Limit &lt;$&gt; parseFieldIfPresent o "limit"
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Limit "limit: null\n"
--   Right (Limit (Just Nothing))
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Limit "{}"
--   Right (Limit Nothing)
--   </pre>
parseFieldIfPresent :: FromYaml a => Object -> Text -> Parser (Maybe a)

-- | The value of a key, or the default if the key is missing or its value
--   is null.
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   newtype Server = Server Int
--     deriving stock (Show)
--   instance FromYaml Server where
--     parseYaml = withMapping $ \o -&gt; Server &lt;$&gt; parseFieldDefault o "port" 80
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Server "{}"
--   Right (Server 80)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Server "port: null\n"
--   Right (Server 80)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Server "port: 8080\n"
--   Right (Server 8080)
--   </pre>
parseFieldDefault :: FromYaml a => Object -> Text -> a -> Parser a

-- | Like <a>parseField</a>, with the given parser for the value, e.g. to
--   check a value without a new type for it. The errors of the parser
--   point to the value. The parser gets only the value, so it cannot keep
--   the comments of the key, as a <a>Commented</a> field does with
--   <a>parseField</a>.
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   newtype Port = Port Int
--     deriving stock (Show)
--   instance FromYaml Port where
--     parseYaml = withMapping $ \o -&gt; Port &lt;$&gt; parseFieldWith number o "port"
--       where
--         number :: Node -&gt; Parser Int
--         number = withInt $ \i -&gt;
--           if i &gt;= 1 &amp;&amp; i &lt;= 65535
--             then pure (fromInteger i)
--             else fail "expected a port from 1 to 65535"
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Port "port: 80\n"
--   Right (Port 80)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; either printErrors print (decodeText @Port "port: 70000\n")
--   input.yaml:1:7: port: expected a port from 1 to 65535
--     |
--   1 | port: 70000
--     |       ^
--   </pre>
parseFieldWith :: (Node -> Parser a) -> Object -> Text -> Parser a

-- | Like <a>parseFieldMaybe</a>, with the given parser for the value, as
--   in <a>parseFieldWith</a>. The result is <a>Nothing</a> if the key is
--   missing or its value is null. The parser never gets a null value, so a
--   missing key and a null value mean the same.
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   newtype Job = Job (Maybe Int)
--     deriving stock (Show)
--   instance FromYaml Job where
--     parseYaml = withMapping $ \o -&gt; Job &lt;$&gt; parseFieldMaybeWith positive o "retries"
--       where
--         positive :: Node -&gt; Parser Int
--         positive = withInt $ \i -&gt;
--           if i &gt; 0 then pure (fromInteger i) else fail "expected a positive number"
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Job "{}"
--   Right (Job Nothing)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Job "retries: null\n"
--   Right (Job Nothing)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Job "retries: 3\n"
--   Right (Job (Just 3))
--   </pre>
--   
--   To give a null value to the parser, use
--   <a>parseFieldIfPresentWith</a>.
parseFieldMaybeWith :: (Node -> Parser a) -> Object -> Text -> Parser (Maybe a)

-- | Like <a>parseFieldIfPresent</a>, with the given parser for the value,
--   as in <a>parseFieldWith</a>. The result is <a>Nothing</a> only if the
--   key is missing. A null value goes to the parser, so the parser can
--   give it a meaning of its own. Here a missing key takes the default
--   limit, and null means no limit:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   data Limit = Unlimited | Limit Int
--     deriving stock (Show)
--   newtype Job = Job (Maybe Limit)
--     deriving stock (Show)
--   instance FromYaml Job where
--     parseYaml = withMapping $ \o -&gt; Job &lt;$&gt; parseFieldIfPresentWith limit o "limit"
--       where
--         limit :: Node -&gt; Parser Limit
--         limit n = case view n of
--           NullView -&gt; pure Unlimited
--           _ -&gt; withInt (pure . Limit . fromInteger) n
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Job "{}"
--   Right (Job Nothing)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Job "limit: null\n"
--   Right (Job (Just Unlimited))
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Job "limit: 3\n"
--   Right (Job (Just (Limit 3)))
--   </pre>
--   
--   With <a>parseFieldMaybeWith</a>, the null value would give
--   <a>Nothing</a>, the same as the missing key.
parseFieldIfPresentWith :: (Node -> Parser a) -> Object -> Text -> Parser (Maybe a)

-- | Like <a>parseFieldDefault</a>, with the given parser for the value, as
--   in <a>parseFieldWith</a>. The parser never gets a null value.
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   newtype Job = Job Int
--     deriving stock (Show)
--   instance FromYaml Job where
--     parseYaml = withMapping $ \o -&gt; Job &lt;$&gt; parseFieldDefaultWith positive o "retries" 1
--       where
--         positive :: Node -&gt; Parser Int
--         positive = withInt $ \i -&gt;
--           if i &gt; 0 then pure (fromInteger i) else fail "expected a positive number"
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Job "{}"
--   Right (Job 1)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Job "retries: 3\n"
--   Right (Job 3)
--   </pre>
parseFieldDefaultWith :: (Node -> Parser a) -> Object -> Text -> a -> Parser a

-- | Fail at each key that is not in the list. If a key in the list is
--   close to an unknown key, e.g. "host" to "hots", its error suggests it.
--   Otherwise the error lists the known keys. An empty list accepts only
--   an empty mapping, e.g. for a value written as <tt>{}</tt>.
--   
--   A key that is not a string, but has the text of a known key, e.g.
--   <tt>true</tt>, is left to the lookup of that key, e.g.
--   <a>parseField</a> or <a>lookupKey</a>, which reports it.
rejectUnknownKeys :: [Text] -> Object -> Parser ()

-- | The values of the items, with the errors of all items, as with
--   <a>mapM</a>. Unlike <a>mapM</a>, the stack does not grow with the
--   number of items, because the errors and the values are in accumulators
--   until the end. A decoder of a list is <tt>withSequence (parseItems
--   parseYaml)</tt>.
parseItems :: (Node -> Parser a) -> [Node] -> Parser [a]

-- | The value of an entry, with errors that point to the value.
parseEntry :: FromYaml a => (Node, Node) -> Parser a

-- | The entry of a string key, or <a>Nothing</a> if the key is missing. A
--   key with the same text that is not a string, e.g. 404, is an error, so
--   that its value does not go away. Only the same text counts, e.g. not
--   True for true, because quotes would not make True the key true.
findKey :: Object -> Text -> Parser (Maybe (Node, Node))

-- | The error for a key that is not in the index of string keys. As for
--   <a>findKey</a>, a key with the same text that is not a string is the
--   error instead.
missingKey :: Object -> Text -> Parser a

-- | The error at the node for a name that is none of the known names, e.g.
--   an unknown value, with the known name that is close to it, or else all
--   known names.
unknownName :: String -> [Text] -> Node -> Text -> Parser a

-- | The error for a plain scalar without a tag that is one of the names,
--   but not a string, e.g. <tt>true</tt>. Quotes would make it the name.
unquotedName :: [Text] -> Node -> Maybe String

-- | The value of a parser on a node that passed <a>prepareWithin</a>, if
--   it has no errors.
succeeds :: (Node -> Parser a) -> Node -> Maybe a

-- | The parser with the note after each of its errors at the offset, e.g.
--   to say how the decoder read the node of the error.
withNote :: Offset -> (Offset, String) -> Parser a -> Parser a

-- | The null node for a missing value.
nullNode :: Node
instance GHC.Internal.Base.Applicative Yamlet.Internal.FromYaml.Parser
instance Yamlet.Internal.FromYaml.FromYaml GHC.Internal.Data.Semigroup.Internal.All
instance Yamlet.Internal.FromYaml.FromYaml GHC.Internal.Data.Semigroup.Internal.Any
instance Yamlet.Internal.FromYaml.FromYaml GHC.Types.Bool
instance Yamlet.Internal.FromYaml.FromYaml Data.Time.Calendar.CalendarDiffDays.CalendarDiffDays
instance Yamlet.Internal.FromYaml.FromYaml Data.Time.LocalTime.Internal.CalendarDiffTime.CalendarDiffTime
instance Yamlet.Internal.FromYaml.FromYaml GHC.Types.Char
instance Yamlet.Internal.FromYaml.FromYaml a => Yamlet.Internal.FromYaml.FromYaml (Yamlet.Internal.Syntax.Commented a)
instance forall k a (b :: k). Yamlet.Internal.FromYaml.FromYaml a => Yamlet.Internal.FromYaml.FromYaml (GHC.Internal.Data.Functor.Const.Const a b)
instance Yamlet.Internal.FromYaml.FromYaml Data.Time.Calendar.Days.Day
instance Yamlet.Internal.FromYaml.FromYaml Data.Time.Calendar.Week.DayOfWeek
instance Yamlet.Internal.FromYaml.FromYaml Data.Time.Clock.Internal.DiffTime.DiffTime
instance Yamlet.Internal.FromYaml.FromYaml GHC.Types.Double
instance Yamlet.Internal.FromYaml.FromYaml a => Yamlet.Internal.FromYaml.FromYaml (GHC.Internal.Data.Ord.Down a)
instance Yamlet.Internal.FromYaml.FromYaml a => Yamlet.Internal.FromYaml.FromYaml (GHC.Internal.Data.Semigroup.Internal.Dual a)
instance (Yamlet.Internal.FromYaml.FromYaml a, Yamlet.Internal.FromYaml.FromYaml b) => Yamlet.Internal.FromYaml.FromYaml (GHC.Internal.Data.Either.Either a b)
instance Yamlet.Internal.FromYaml.FromYaml a => Yamlet.Internal.FromYaml.FromYaml (GHC.Internal.Data.Monoid.First a)
instance Yamlet.Internal.FromYaml.FromYaml a => Yamlet.Internal.FromYaml.FromYaml (Data.Semigroup.First a)
instance forall k (a :: k). Data.Fixed.HasResolution a => Yamlet.Internal.FromYaml.FromYaml (Data.Fixed.Fixed a)
instance Yamlet.Internal.FromYaml.FromYaml GHC.Types.Float
instance Yamlet.Internal.FromYaml.FromYaml a => Yamlet.Internal.FromYaml.FromYaml (GHC.Internal.Data.Functor.Identity.Identity a)
instance Yamlet.Internal.FromYaml.FromYaml GHC.Types.Int
instance Yamlet.Internal.FromYaml.FromYaml GHC.Internal.Int.Int16
instance Yamlet.Internal.FromYaml.FromYaml GHC.Internal.Int.Int32
instance Yamlet.Internal.FromYaml.FromYaml GHC.Internal.Int.Int64
instance Yamlet.Internal.FromYaml.FromYaml GHC.Internal.Int.Int8
instance Yamlet.Internal.FromYaml.FromYaml v => Yamlet.Internal.FromYaml.FromYaml (Data.IntMap.Internal.IntMap v)
instance Yamlet.Internal.FromYaml.FromYaml Data.IntSet.Internal.IntSet
instance Yamlet.Internal.FromYaml.FromYaml GHC.Num.Integer.Integer
instance Yamlet.Internal.FromYaml.FromYaml a => Yamlet.Internal.FromYaml.FromYaml (GHC.Internal.Data.Monoid.Last a)
instance Yamlet.Internal.FromYaml.FromYaml a => Yamlet.Internal.FromYaml.FromYaml (Data.Semigroup.Last a)
instance Yamlet.Internal.FromYaml.FromYaml a => Yamlet.Internal.FromYaml.FromYaml [a]
instance Yamlet.Internal.FromYaml.FromYaml Data.Time.LocalTime.Internal.LocalTime.LocalTime
instance Yamlet.Internal.FromYaml.FromYaml a => Yamlet.Internal.FromYaml.FromYaml (Yamlet.Internal.Syntax.Located a)
instance (GHC.Classes.Ord k, Yamlet.Internal.FromYaml.FromYaml k, Yamlet.Internal.FromYaml.FromYaml v) => Yamlet.Internal.FromYaml.FromYaml (Data.Map.Internal.Map k v)
instance Yamlet.Internal.FromYaml.FromYaml a => Yamlet.Internal.FromYaml.FromYaml (Data.Semigroup.Max a)
instance Yamlet.Internal.FromYaml.FromYaml a => Yamlet.Internal.FromYaml.FromYaml (GHC.Internal.Maybe.Maybe a)
instance Yamlet.Internal.FromYaml.FromYaml a => Yamlet.Internal.FromYaml.FromYaml (Data.Semigroup.Min a)
instance Yamlet.Internal.FromYaml.FromYaml Data.Time.Calendar.Month.Month
instance Yamlet.Internal.FromYaml.FromYaml GHC.Num.Natural.Natural
instance Yamlet.Internal.FromYaml.FromYaml Yamlet.Internal.Syntax.Node
instance Yamlet.Internal.FromYaml.FromYaml Data.Time.Clock.Internal.NominalDiffTime.NominalDiffTime
instance Yamlet.Internal.FromYaml.FromYaml a => Yamlet.Internal.FromYaml.FromYaml (GHC.Internal.Base.NonEmpty a)
instance Yamlet.Internal.FromYaml.FromYaml GHC.Types.Ordering
instance Yamlet.Internal.FromYaml.FromYaml a => Yamlet.Internal.FromYaml.FromYaml (GHC.Internal.Data.Semigroup.Internal.Product a)
instance Yamlet.Internal.FromYaml.FromYaml Data.Time.Calendar.Quarter.Quarter
instance Yamlet.Internal.FromYaml.FromYaml Data.Time.Calendar.Quarter.QuarterOfYear
instance (GHC.Internal.Real.Integral a, Yamlet.Internal.FromYaml.FromYaml a) => Yamlet.Internal.FromYaml.FromYaml (GHC.Internal.Real.Ratio a)
instance Yamlet.Internal.FromYaml.FromYaml Data.Scientific.Scientific
instance Yamlet.Internal.FromYaml.FromYaml a => Yamlet.Internal.FromYaml.FromYaml (Data.Sequence.Internal.Seq a)
instance (GHC.Classes.Ord a, Yamlet.Internal.FromYaml.FromYaml a) => Yamlet.Internal.FromYaml.FromYaml (Data.Set.Internal.Set a)
instance Yamlet.Internal.FromYaml.FromYaml a => Yamlet.Internal.FromYaml.FromYaml (GHC.Internal.Data.Semigroup.Internal.Sum a)
instance Yamlet.Internal.FromYaml.FromYaml Data.Text.Internal.Lazy.Text
instance Yamlet.Internal.FromYaml.FromYaml Data.Text.Internal.Text
instance Yamlet.Internal.FromYaml.FromYaml Data.Time.LocalTime.Internal.TimeOfDay.TimeOfDay
instance Yamlet.Internal.FromYaml.FromYaml a => Yamlet.Internal.FromYaml.FromYaml (Data.Tree.Tree a)
instance (Yamlet.Internal.FromYaml.FromYaml a1, Yamlet.Internal.FromYaml.FromYaml a2, Yamlet.Internal.FromYaml.FromYaml a3, Yamlet.Internal.FromYaml.FromYaml a4, Yamlet.Internal.FromYaml.FromYaml a5, Yamlet.Internal.FromYaml.FromYaml a6, Yamlet.Internal.FromYaml.FromYaml a7, Yamlet.Internal.FromYaml.FromYaml a8, Yamlet.Internal.FromYaml.FromYaml a9, Yamlet.Internal.FromYaml.FromYaml a10) => Yamlet.Internal.FromYaml.FromYaml (a1, a2, a3, a4, a5, a6, a7, a8, a9, a10)
instance (Yamlet.Internal.FromYaml.FromYaml a1, Yamlet.Internal.FromYaml.FromYaml a2) => Yamlet.Internal.FromYaml.FromYaml (a1, a2)
instance (Yamlet.Internal.FromYaml.FromYaml a1, Yamlet.Internal.FromYaml.FromYaml a2, Yamlet.Internal.FromYaml.FromYaml a3) => Yamlet.Internal.FromYaml.FromYaml (a1, a2, a3)
instance (Yamlet.Internal.FromYaml.FromYaml a1, Yamlet.Internal.FromYaml.FromYaml a2, Yamlet.Internal.FromYaml.FromYaml a3, Yamlet.Internal.FromYaml.FromYaml a4) => Yamlet.Internal.FromYaml.FromYaml (a1, a2, a3, a4)
instance (Yamlet.Internal.FromYaml.FromYaml a1, Yamlet.Internal.FromYaml.FromYaml a2, Yamlet.Internal.FromYaml.FromYaml a3, Yamlet.Internal.FromYaml.FromYaml a4, Yamlet.Internal.FromYaml.FromYaml a5) => Yamlet.Internal.FromYaml.FromYaml (a1, a2, a3, a4, a5)
instance (Yamlet.Internal.FromYaml.FromYaml a1, Yamlet.Internal.FromYaml.FromYaml a2, Yamlet.Internal.FromYaml.FromYaml a3, Yamlet.Internal.FromYaml.FromYaml a4, Yamlet.Internal.FromYaml.FromYaml a5, Yamlet.Internal.FromYaml.FromYaml a6) => Yamlet.Internal.FromYaml.FromYaml (a1, a2, a3, a4, a5, a6)
instance (Yamlet.Internal.FromYaml.FromYaml a1, Yamlet.Internal.FromYaml.FromYaml a2, Yamlet.Internal.FromYaml.FromYaml a3, Yamlet.Internal.FromYaml.FromYaml a4, Yamlet.Internal.FromYaml.FromYaml a5, Yamlet.Internal.FromYaml.FromYaml a6, Yamlet.Internal.FromYaml.FromYaml a7) => Yamlet.Internal.FromYaml.FromYaml (a1, a2, a3, a4, a5, a6, a7)
instance (Yamlet.Internal.FromYaml.FromYaml a1, Yamlet.Internal.FromYaml.FromYaml a2, Yamlet.Internal.FromYaml.FromYaml a3, Yamlet.Internal.FromYaml.FromYaml a4, Yamlet.Internal.FromYaml.FromYaml a5, Yamlet.Internal.FromYaml.FromYaml a6, Yamlet.Internal.FromYaml.FromYaml a7, Yamlet.Internal.FromYaml.FromYaml a8) => Yamlet.Internal.FromYaml.FromYaml (a1, a2, a3, a4, a5, a6, a7, a8)
instance (Yamlet.Internal.FromYaml.FromYaml a1, Yamlet.Internal.FromYaml.FromYaml a2, Yamlet.Internal.FromYaml.FromYaml a3, Yamlet.Internal.FromYaml.FromYaml a4, Yamlet.Internal.FromYaml.FromYaml a5, Yamlet.Internal.FromYaml.FromYaml a6, Yamlet.Internal.FromYaml.FromYaml a7, Yamlet.Internal.FromYaml.FromYaml a8, Yamlet.Internal.FromYaml.FromYaml a9) => Yamlet.Internal.FromYaml.FromYaml (a1, a2, a3, a4, a5, a6, a7, a8, a9)
instance Yamlet.Internal.FromYaml.FromYaml Data.Time.Clock.Internal.UTCTime.UTCTime
instance Yamlet.Internal.FromYaml.FromYaml Data.UUID.Types.Internal.UUID
instance Yamlet.Internal.FromYaml.FromYaml ()
instance Yamlet.Internal.FromYaml.FromYaml Yamlet.Value.Value
instance Yamlet.Internal.FromYaml.FromYaml GHC.Internal.Base.Void
instance Yamlet.Internal.FromYaml.FromYaml GHC.Types.Word
instance Yamlet.Internal.FromYaml.FromYaml GHC.Internal.Word.Word16
instance Yamlet.Internal.FromYaml.FromYaml GHC.Internal.Word.Word32
instance Yamlet.Internal.FromYaml.FromYaml GHC.Internal.Word.Word64
instance Yamlet.Internal.FromYaml.FromYaml GHC.Internal.Word.Word8
instance Yamlet.Internal.FromYaml.FromYaml Data.Time.LocalTime.Internal.ZonedTime.ZonedTime
instance GHC.Internal.Base.Functor Yamlet.Internal.FromYaml.Parser
instance GHC.Internal.Control.Monad.Fail.MonadFail Yamlet.Internal.FromYaml.Parser
instance GHC.Internal.Base.Monad Yamlet.Internal.FromYaml.Parser


-- | Conversion of nodes to Haskell values, with errors that point to the
--   node that caused them.
module Yamlet.Decode

-- | Types that can be parsed from a node. A type with a <a>Generic</a>
--   instance can derive the instance via <a>GenericYaml</a>.
--   
--   An instance for a record reads a mapping with <a>withMapping</a>:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   data Server = Server {host :: T.Text, port :: Int, tags :: [T.Text]}
--     deriving stock (Show)
--   instance FromYaml Server where
--     parseYaml = withMapping $ \o -&gt;
--       rejectUnknownKeys ["host", "port", "tags"] o
--         *&gt; ( Server
--                &lt;$&gt; parseField o "host"
--                &lt;*&gt; parseFieldDefault o "port" 80
--                &lt;*&gt; parseFieldDefault o "tags" []
--            )
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Server "host: example.com\ntags:\n- web\n"
--   Right (Server {host = "example.com", port = 80, tags = ["web"]})
--   </pre>
--   
--   The decoder reports the errors of all fields together:
--   
--   <pre>
--   &gt;&gt;&gt; either printErrors print (decodeText @Server "hots: example.com\nport: http\n")
--   input.yaml:1:1: unknown key "hots", did you mean "host"?
--     |
--   1 | hots: example.com
--     | ^
--   input.yaml:1:1: missing key "host"
--     |
--   1 | hots: example.com
--     | ^
--   input.yaml:2:7: port: expected an integer, but got a string
--     |
--   2 | port: http
--     |       ^
--   </pre>
--   
--   The instances of the library copy the texts that they keep, so a
--   decoded value does not keep the input in memory. A value from a
--   hand-written instance can keep the input while it has unevaluated
--   parts, e.g. a lazy list. Evaluate such a value, e.g. with
--   <a>force</a>, to release the input.
class FromYaml a
parseYaml :: FromYaml a => Node -> Parser a

-- | Parse a list. The instance for <a>Char</a> parses a string instead.
parseYamlList :: FromYaml a => Node -> Parser [a]

-- | Parse the value of a mapping entry, with its key, e.g. to keep the
--   comments of the key as <a>Commented</a> does. <a>parseField</a> and
--   the other lookups without a parser argument, the derived decoders and
--   the instances for maps use it. The default ignores the key.
parseYamlField :: FromYaml a => Node -> Node -> Parser a

-- | A parser of nodes. Its errors point to the node that the parser works
--   on, unless <a>failAt</a> names another one.
--   
--   The parser has no <a>Alternative</a> instance. To try another parser
--   after a failure, use <a>orElse</a>. To reject a value, fail with a
--   message that says why:
--   
--   <pre>
--   port &lt;- parseYaml n
--   unless (port &gt; 0 &amp;&amp; port &lt; 65536) $ fail "the port must be from 1 to 65535"
--   </pre>
--   
--   The applicative operators collect the errors of both parts:
--   <a>&lt;*&gt;</a>, <a>*&gt;</a>, <a>&lt;*</a>, <a>liftA2</a>, and the
--   functions that use them, e.g. <a>traverse</a>, <a>mapM</a> on a list
--   and <a>for_</a>. This parser gives the errors of the unknown keys and
--   of all fields together:
--   
--   <pre>
--   rejectUnknownKeys ["name", "paths"] o
--     *&gt; (Config &lt;$&gt; parseField o "name" &lt;*&gt; parseField o "paths")
--   </pre>
--   
--   <a>&gt;&gt;=</a> and <a>&gt;&gt;</a> stop at the first error. A
--   statement of a <tt>do</tt> block also stops, e.g. the check of the
--   port above. The functions that use <a>&gt;&gt;</a> also stop, e.g.
--   <a>mapM_</a> and <a>forM_</a>.
--   
--   The choice between them changes only the errors, never the result.
--   With <tt>ApplicativeDo</tt>, GHC turns the independent statements of a
--   <tt>do</tt> block that ends with <a>pure</a> into <a>&lt;*&gt;</a>.
--   Then they collect errors.
data Parser a

-- | Run a parser on a node. Each error is the offset of the node that
--   caused it and the message. The errors are in the order of the offsets,
--   and equal errors come only once. A note on an error comes right after
--   it, e.g. the first key of a duplicate key.
--   
--   First, the function makes the checks of <a>decodeDocument</a> on the
--   node, e.g. for duplicate keys. It also replaces each alias with the
--   node that the alias refers to. If a check fails, the result has only
--   the error of that check, with its notes.
runParser :: (Node -> Parser a) -> Node -> Either (NonEmpty (Offset, String)) a

-- | Run a parser on a node, so that <a>fail</a> points to the node.
parseNode :: (Node -> Parser a) -> Node -> Parser a

-- | Fail with an error that points to the given node.
failAt :: Node -> String -> Parser a

-- | Fail with an error that the node is not of the expected kind, e.g.
--   <tt>typeMismatch "a list" n</tt> gives "expected a list, but got a
--   string".
typeMismatch :: String -> Node -> Parser a

-- | Run the second parser if the first one fails. A port can be a number
--   or a name:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   newtype Port = Port (Either Integer T.Text)
--     deriving stock (Show)
--   instance FromYaml Port where
--     parseYaml n =
--       Port &lt;$&gt; ((Left &lt;$&gt; withInt pure n) `orElse` (Right &lt;$&gt; withText pure n))
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Port "8080"
--   Right (Port (Left 8080))
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Port "http"
--   Right (Port (Right "http"))
--   </pre>
--   
--   If both parsers fail, the result has only the errors of the second
--   one:
--   
--   <pre>
--   &gt;&gt;&gt; either printErrors print (decodeText @Port "[80]")
--   input.yaml:1:1: expected a string, but got a list
--     |
--   1 | [80]
--     | ^
--   </pre>
orElse :: Parser a -> Parser a -> Parser a
infixl 3 `orElse`

-- | The value of a node with its tag resolved. The items and the entries
--   of a collection stay nodes of the syntax tree. A tag that the schema
--   does not know does not matter, e.g. <tt>!secret abc</tt> is a string.
data View
NullView :: View
BoolView :: !Bool -> View
IntView :: !Integer -> View
FloatView :: !FloatValue -> View
StringView :: !Text -> View
SequenceView :: ![Node] -> View
MappingView :: ![(Node, Node)] -> View

-- | An alias, e.g. in a node from <a>parseDocuments</a>. <a>runParser</a>
--   replaces the aliases, so a parser never sees one.
AliasView :: !Text -> View

-- | The view of a node.
view :: Node -> View

-- | The kind of a node in plain words, e.g. "a list".
--   
--   <pre>
--   &gt;&gt;&gt; map describeNode &lt;$&gt; decodeText @[Node] "- [1, 2]\n- 3.5\n- ~\n- !!str 12\n"
--   Right ["a list","a floating-point number","null","a string"]
--   </pre>
describeNode :: Node -> String

-- | Run the parser if the node is null.
withNull :: Parser a -> Node -> Parser a

-- | The value of a boolean.
withBool :: (Bool -> Parser a) -> Node -> Parser a

-- | The value of an integer.
withInt :: (Integer -> Parser a) -> Node -> Parser a

-- | The nearest double. An integer counts as a floating-point number too.
withFloat :: (Double -> Parser a) -> Node -> Parser a

-- | The exact value of a finite number. An integer counts too, and
--   negative zero becomes 0.
--   
--   A conversion to an exact type, e.g. with <a>truncate</a>, is safe for
--   untrusted input. An integer has the digits of its text, and the
--   decoder rejects a float whose exponent in scientific notation is
--   beyond the range from -1000 to 1000, also in a node that a program
--   built.
withScientific :: (Scientific -> Parser a) -> Node -> Parser a

-- | The text of a string. The text is a copy, so it does not keep the
--   input alive. For a plain scalar that YAML reads as a number or a
--   boolean, e.g. <tt>3.10</tt>, the error suggests quotes.
withText :: (Text -> Parser a) -> Node -> Parser a

-- | The value that goes with the string in the list of pairs, e.g. for
--   names that the program knows only at run time. An empty list rejects
--   every value. The errors are the same as for the constructors of an
--   enumeration. An unknown name gets the closest name or the list of
--   names:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   newtype Size = Size Int
--     deriving stock (Show)
--   instance FromYaml Size where
--     parseYaml = oneOf [("small", Size 1), ("large", Size 2)]
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Size "large"
--   Right (Size 2)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; either printErrors print (decodeText @Size "lage")
--   input.yaml:1:1: unknown value "lage", did you mean "large"?
--     |
--   1 | lage
--     | ^
--   </pre>
oneOf :: [(Text, a)] -> Node -> Parser a

-- | The items of a sequence. As for <a>withMapping</a>, the comments of
--   the sequence stay with it, not with its first item.
withSequence :: ([Node] -> Parser a) -> Node -> Parser a

-- | The values of the items, with the errors of all items, as with
--   <a>mapM</a>. Unlike <a>mapM</a>, the stack does not grow with the
--   number of items, because the errors and the values are in accumulators
--   until the end. A decoder of a list is <tt>withSequence (parseItems
--   parseYaml)</tt>.
parseItems :: (Node -> Parser a) -> [Node] -> Parser [a]

-- | The entries of a mapping. As for <a>withText</a>, the tag of a string
--   key does not matter, so two string keys with the same text are an
--   error, e.g. <tt>a</tt> and <tt>!foo a</tt>.
--   
--   The comments of the mapping stay with it, not with its first key, e.g.
--   a comment at the top of a file. A record has no place for them.
withMapping :: (Object -> Parser a) -> Node -> Parser a

-- | A mapping with fast access to the values of string keys.
data Object

-- | The node of the mapping.
objectNode :: Object -> Node

-- | The entries of the mapping in the order of the input.
objectEntries :: Object -> [(Node, Node)]

-- | The string keys of the mapping in the order of the input.
objectKeys :: Object -> [Text]

-- | The value of a key, or <a>Nothing</a> if the key is missing. As for
--   <a>parseField</a>, a key with the same text that is not a string, e.g.
--   <tt>404</tt>, is an error, so that its value does not go away.
lookupKey :: Object -> Text -> Parser (Maybe Node)

-- | The value of a key. It is an error if the key is missing.
parseField :: FromYaml a => Object -> Text -> Parser a

-- | The value of a key, or <a>Nothing</a> if the key is missing or its
--   value is null.
parseFieldMaybe :: FromYaml a => Object -> Text -> Parser (Maybe a)

-- | The value of a key, or <a>Nothing</a> if the key is missing. Unlike
--   <a>parseFieldMaybe</a>, a null value goes to the parser of the value,
--   e.g. <tt><a>Maybe</a> a</tt> gives <tt><a>Just</a> <a>Nothing</a></tt>
--   for a null value.
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   newtype Limit = Limit (Maybe (Maybe Int))
--     deriving stock (Show)
--   instance FromYaml Limit where
--     parseYaml = withMapping $ \o -&gt; Limit &lt;$&gt; parseFieldIfPresent o "limit"
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Limit "limit: null\n"
--   Right (Limit (Just Nothing))
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Limit "{}"
--   Right (Limit Nothing)
--   </pre>
parseFieldIfPresent :: FromYaml a => Object -> Text -> Parser (Maybe a)

-- | The value of a key, or the default if the key is missing or its value
--   is null.
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   newtype Server = Server Int
--     deriving stock (Show)
--   instance FromYaml Server where
--     parseYaml = withMapping $ \o -&gt; Server &lt;$&gt; parseFieldDefault o "port" 80
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Server "{}"
--   Right (Server 80)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Server "port: null\n"
--   Right (Server 80)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Server "port: 8080\n"
--   Right (Server 8080)
--   </pre>
parseFieldDefault :: FromYaml a => Object -> Text -> a -> Parser a

-- | Like <a>parseField</a>, with the given parser for the value, e.g. to
--   check a value without a new type for it. The errors of the parser
--   point to the value. The parser gets only the value, so it cannot keep
--   the comments of the key, as a <a>Commented</a> field does with
--   <a>parseField</a>.
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   newtype Port = Port Int
--     deriving stock (Show)
--   instance FromYaml Port where
--     parseYaml = withMapping $ \o -&gt; Port &lt;$&gt; parseFieldWith number o "port"
--       where
--         number :: Node -&gt; Parser Int
--         number = withInt $ \i -&gt;
--           if i &gt;= 1 &amp;&amp; i &lt;= 65535
--             then pure (fromInteger i)
--             else fail "expected a port from 1 to 65535"
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Port "port: 80\n"
--   Right (Port 80)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; either printErrors print (decodeText @Port "port: 70000\n")
--   input.yaml:1:7: port: expected a port from 1 to 65535
--     |
--   1 | port: 70000
--     |       ^
--   </pre>
parseFieldWith :: (Node -> Parser a) -> Object -> Text -> Parser a

-- | Like <a>parseFieldMaybe</a>, with the given parser for the value, as
--   in <a>parseFieldWith</a>. The result is <a>Nothing</a> if the key is
--   missing or its value is null. The parser never gets a null value, so a
--   missing key and a null value mean the same.
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   newtype Job = Job (Maybe Int)
--     deriving stock (Show)
--   instance FromYaml Job where
--     parseYaml = withMapping $ \o -&gt; Job &lt;$&gt; parseFieldMaybeWith positive o "retries"
--       where
--         positive :: Node -&gt; Parser Int
--         positive = withInt $ \i -&gt;
--           if i &gt; 0 then pure (fromInteger i) else fail "expected a positive number"
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Job "{}"
--   Right (Job Nothing)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Job "retries: null\n"
--   Right (Job Nothing)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Job "retries: 3\n"
--   Right (Job (Just 3))
--   </pre>
--   
--   To give a null value to the parser, use
--   <a>parseFieldIfPresentWith</a>.
parseFieldMaybeWith :: (Node -> Parser a) -> Object -> Text -> Parser (Maybe a)

-- | Like <a>parseFieldIfPresent</a>, with the given parser for the value,
--   as in <a>parseFieldWith</a>. The result is <a>Nothing</a> only if the
--   key is missing. A null value goes to the parser, so the parser can
--   give it a meaning of its own. Here a missing key takes the default
--   limit, and null means no limit:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   data Limit = Unlimited | Limit Int
--     deriving stock (Show)
--   newtype Job = Job (Maybe Limit)
--     deriving stock (Show)
--   instance FromYaml Job where
--     parseYaml = withMapping $ \o -&gt; Job &lt;$&gt; parseFieldIfPresentWith limit o "limit"
--       where
--         limit :: Node -&gt; Parser Limit
--         limit n = case view n of
--           NullView -&gt; pure Unlimited
--           _ -&gt; withInt (pure . Limit . fromInteger) n
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Job "{}"
--   Right (Job Nothing)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Job "limit: null\n"
--   Right (Job (Just Unlimited))
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Job "limit: 3\n"
--   Right (Job (Just (Limit 3)))
--   </pre>
--   
--   With <a>parseFieldMaybeWith</a>, the null value would give
--   <a>Nothing</a>, the same as the missing key.
parseFieldIfPresentWith :: (Node -> Parser a) -> Object -> Text -> Parser (Maybe a)

-- | Like <a>parseFieldDefault</a>, with the given parser for the value, as
--   in <a>parseFieldWith</a>. The parser never gets a null value.
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   newtype Job = Job Int
--     deriving stock (Show)
--   instance FromYaml Job where
--     parseYaml = withMapping $ \o -&gt; Job &lt;$&gt; parseFieldDefaultWith positive o "retries" 1
--       where
--         positive :: Node -&gt; Parser Int
--         positive = withInt $ \i -&gt;
--           if i &gt; 0 then pure (fromInteger i) else fail "expected a positive number"
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Job "{}"
--   Right (Job 1)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Job "retries: 3\n"
--   Right (Job 3)
--   </pre>
parseFieldDefaultWith :: (Node -> Parser a) -> Object -> Text -> a -> Parser a

-- | Fail at each key that is not in the list. If a key in the list is
--   close to an unknown key, e.g. "host" to "hots", its error suggests it.
--   Otherwise the error lists the known keys. An empty list accepts only
--   an empty mapping, e.g. for a value written as <tt>{}</tt>.
--   
--   A key that is not a string, but has the text of a known key, e.g.
--   <tt>true</tt>, is left to the lookup of that key, e.g.
--   <a>parseField</a> or <a>lookupKey</a>, which reports it.
rejectUnknownKeys :: [Text] -> Object -> Parser ()


-- | Instances of <a>FromYaml</a> and <a>ToYaml</a> from the <a>Generic</a>
--   representation of a type.
--   
--   A type derives the instances via <a>GenericYaml</a>, and its instance
--   of <a>GenericYamlOptions</a> gives the options:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   data Server = Server {host :: T.Text, port :: Int}
--     deriving stock (Generic, Show)
--     deriving anyclass (GenericYamlOptions)
--     deriving (FromYaml, ToYaml) via GenericYaml Server
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Server "host: localhost\nport: 80\n"
--   Right (Server {host = "localhost", port = 80})
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; T.putStr (encodeText (Server "localhost" 80))
--   host: localhost
--   port: 80
--   </pre>
--   
--   A type with other options defines <a>yamlOptions</a> in its instance
--   of <a>GenericYamlOptions</a>:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   data Build = Build {sourcePaths :: [T.Text], ghcOptions :: [T.Text]}
--     deriving stock (Generic)
--     deriving (ToYaml) via GenericYaml Build
--   instance GenericYamlOptions Build where
--     yamlOptions = defaultYamlOptions {fieldLabelModifier = snakeCase}
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; T.putStr (encodeText (Build ["src"] ["-Wall"]))
--   source_paths:
--   - src
--   ghc_options:
--   - -Wall
--   </pre>
--   
--   <h1>Encoding</h1>
--   
--   The encoding of a type depends on its constructors and their fields:
--   
--   <ul>
--   <li>A record is a mapping of its fields, e.g. <tt>{host: localhost,
--   port: 80}</tt>.</li>
--   <li>A type whose constructors have no fields is a string with the name
--   of the constructor, e.g. <tt>TurnLeft</tt>. This includes a type with
--   one such constructor, which aeson writes as an empty list.</li>
--   <li>A type with several constructors is a mapping with the name of the
--   constructor under the tag key, next to the fields of the constructor,
--   e.g. <tt>{tag: Circle, radius: 1}</tt>. A constructor with a field
--   without a name has its field under the contents key, e.g. <tt>{tag:
--   Forward, contents: 10}</tt>.</li>
--   <li>A type with one constructor and a field without a name is its
--   field.</li>
--   <li>With the encoding <a>TaggedFlat</a>, the entries of a field
--   without a name go in the mapping of the constructor, e.g. <tt>{tag:
--   Ahead, distance: 10}</tt> for <tt>Ahead (Distance 10)</tt>.</li>
--   <li>With the encoding <a>SingleField</a>, a constructor is a mapping
--   with its name as the only key, e.g. <tt>{Circle: {radius: 1}}</tt> or
--   <tt>{Forward: 10}</tt>, and a constructor without fields is its name,
--   e.g. <tt>Dot</tt>. aeson writes such a constructor as <tt>{Dot:
--   []}</tt>.</li>
--   </ul>
--   
--   The default encoding of a sum type is <a>TaggedObject</a>:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   data Shape = Circle {radius :: Double} | Dot
--     deriving stock (Generic)
--     deriving anyclass (GenericYamlOptions)
--     deriving (ToYaml) via GenericYaml Shape
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; T.putStr (encodeText [Circle 1, Dot])
--   - tag: Circle
--     radius: 1.0
--   - tag: Dot
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   data Move = Forward Int | Stop
--     deriving stock (Generic)
--     deriving anyclass (GenericYamlOptions)
--     deriving (ToYaml) via GenericYaml Move
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; T.putStr (encodeText [Forward 10, Stop])
--   - tag: Forward
--     contents: 10
--   - tag: Stop
--   </pre>
--   
--   The instance of <a>GenericYamlOptions</a> chooses another encoding:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   data Distance = Distance {distance :: Int}
--     deriving stock (Generic)
--     deriving anyclass (GenericYamlOptions)
--     deriving (ToYaml) via GenericYaml Distance
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   data Step = Ahead Distance | Halt
--     deriving stock (Generic)
--     deriving (ToYaml) via GenericYaml Step
--   instance GenericYamlOptions Step where
--     type SumEncoding Step = TaggedFlat
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; T.putStr (encodeText [Ahead (Distance 10), Halt])
--   - tag: Ahead
--     distance: 10
--   - tag: Halt
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   data Figure = Round {radius :: Double} | Named T.Text | Point
--     deriving stock (Generic)
--     deriving (ToYaml) via GenericYaml Figure
--   instance GenericYamlOptions Figure where
--     type SumEncoding Figure = SingleField
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; T.putStr (encodeText [Round 1, Named "x", Point])
--   - Round:
--       radius: 1.0
--   - Named: x
--   - Point
--   </pre>
--   
--   <h1>Shapes</h1>
--   
--   Every constructor must have no fields, one field without a name, or
--   named fields. A type with several constructors cannot mix named fields
--   with a field without a name, but a constructor without fields fits
--   with both. <a>SingleField</a> allows the mix, because each constructor
--   has its own value. <a>TaggedFlat</a> needs constructors with one field
--   without a name or no fields.
--   
--   Another shape is a compile error that names the constructors, e.g. a
--   constructor with several fields without names. Give such fields names,
--   or with <a>TaggedFlat</a>, put them in a record type and make it the
--   one field of the constructor.
--   
--   <h1>Missing keys</h1>
--   
--   A missing field takes its value from the <a>yamlDefault</a> of the
--   type that has the field, if that type has a default. Otherwise the
--   field decodes as if its value is null. A missing contents key does the
--   same. Thus a field of type <a>Maybe</a> is optional, and a missing
--   field of another type is an error, even if the type of the field has
--   its own <a>yamlDefault</a>: only the default of the type that has the
--   field counts.
--   
--   A type with a default configuration derives the decoder like this:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   data Config = Config {name :: T.Text, retries :: Int, proxy :: Maybe T.Text}
--     deriving stock (Generic, Show)
--     deriving (FromYaml) via GenericYaml Config
--   instance GenericYamlOptions Config where
--     yamlDefault = Just (Config "app" 3 (Just "proxy.local"))
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Config "retries: 5\n"
--   Right (Config {name = "app", retries = 5, proxy = Just "proxy.local"})
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Config "proxy: null\n"
--   Right (Config {name = "app", retries = 3, proxy = Nothing})
--   </pre>
--   
--   A field with the value <a>requiredField</a> has no default:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   data Account = Account {user :: T.Text, shell :: T.Text}
--     deriving stock (Generic, Show)
--     deriving (FromYaml) via GenericYaml Account
--   instance GenericYamlOptions Account where
--     yamlDefault = Just (Account requiredField "/bin/sh")
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Account "user: alice\n"
--   Right (Account {user = "alice", shell = "/bin/sh"})
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; either printErrors print (decodeText @Account "shell: /bin/zsh\n")
--   input.yaml:1:1: missing key "user"
--     |
--   1 | shell: /bin/zsh
--     | ^
--   </pre>
--   
--   A present key that holds a mapping takes the missing keys of that
--   mapping from the default of its own type, not from the outer default:
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   data Endpoint = Endpoint {host :: T.Text, port :: Int}
--     deriving stock (Generic, Show)
--     deriving (FromYaml) via GenericYaml Endpoint
--   instance GenericYamlOptions Endpoint where
--     yamlDefault = Just (Endpoint "localhost" 80)
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   data Service = Service {name :: T.Text, endpoint :: Endpoint}
--     deriving stock (Generic, Show)
--     deriving (FromYaml) via GenericYaml Service
--   instance GenericYamlOptions Service where
--     yamlDefault = Just (Service "app" (Endpoint "example.com" 443))
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Service "endpoint:\n  port: 8080\n"
--   Right (Service {name = "app", endpoint = Endpoint {host = "localhost", port = 8080}})
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Service "name: web\n"
--   Right (Service {name = "web", endpoint = Endpoint {host = "example.com", port = 443}})
--   </pre>
--   
--   With <a>TaggedFlat</a>, the keys of a field without a name are next to
--   the tag, but they belong to the field. The missing keys of the field
--   also come from the default of its type. The outer default applies to
--   such a field only if the constructor has no keys besides the tag.
--   
--   An explicit null is not a missing key, so it goes to the decoder of
--   the field. E.g. <tt>proxy: null</tt> gives <a>Nothing</a> for a field
--   of type <a>Maybe</a>, and <tt>proxy:</tt> without a value gives
--   <a>Nothing</a> too. An empty document is also null, so a type with a
--   default does not decode from it.
module Yamlet.Generic

-- | A newtype to derive <a>FromYaml</a> and <a>ToYaml</a> with
--   <tt>deriving via</tt>. The instances come from the <a>Generic</a>
--   representation of the type and its instance of
--   <a>GenericYamlOptions</a>.
newtype GenericYaml a
GenericYaml :: a -> GenericYaml a

-- | The configuration of the generic instances of <a>FromYaml</a> and
--   <a>ToYaml</a> for a type: the options and the default value.
class GenericYamlOptions a where {
    
    -- | How a tagged constructor goes in a mapping, <a>TaggedObject</a> by
    --   default.
    type SumEncoding a :: SumEncodingKind;
    type SumEncoding a = 'TaggedObject;
}

-- | The options of the type, <a>defaultYamlOptions</a> by default.
yamlOptions :: GenericYamlOptions a => YamlOptions

-- | The value that gives the fields of missing keys, e.g. the default
--   configuration. Without it, a missing key decodes like null. A key with
--   the value null is not missing. For a sum type, the default applies
--   only to the constructor of the default value.
yamlDefault :: GenericYamlOptions a => Maybe a

-- | How a type is encoded and decoded.
--   
--   The instances do not check the options. Options that give two keys of
--   a mapping or two constructors the same text encode values that do not
--   read back, as the fields below describe.
data YamlOptions
YamlOptions :: !String -> String -> !String -> String -> !Text -> !Text -> !Bool -> !Bool -> !Bool -> YamlOptions

-- | The key of a field from the name of the field. If two fields of a
--   constructor get the same key, e.g. <tt>fooBar</tt> and
--   <tt>foo_bar</tt> with <a>snakeCase</a>, the constructor encodes as a
--   mapping with two equal keys, which does not read back.
[fieldLabelModifier] :: YamlOptions -> !String -> String

-- | The tag of a constructor from the name of the constructor. If two
--   constructors get the same tag, e.g. <tt>FooBar</tt> and
--   <tt>Foo_bar</tt> with <a>snakeCase</a>, the decoder reads the tag as
--   the first of them.
[constructorTagModifier] :: YamlOptions -> !String -> String

-- | The key of the tag, <tt>tag</tt> by default. A record with a field of
--   the same key encodes as a mapping with two equal keys, which does not
--   read back.
[tagKey] :: YamlOptions -> !Text

-- | The key of the fields of a tagged constructor without field names,
--   <tt>contents</tt> by default. If it is the same as <a>tagKey</a>, such
--   a constructor encodes as a mapping with two equal keys, which does not
--   read back.
[contentsKey] :: YamlOptions -> !Text

-- | Give a type with one constructor a tag too, unless the constructor has
--   no fields. Off by default.
[tagSingleConstructors] :: YamlOptions -> !Bool

-- | Leave out a field whose value is null, e.g. <a>Nothing</a>. Off by
--   default. A null field with comments stays, e.g. a <a>Commented</a>
--   field with the value <a>Nothing</a> and a comment. So does a null
--   field with an anchor, which an alias elsewhere can refer to.
--   
--   With <a>yamlDefault</a>, a null field stays unless its default is null
--   without comments. Otherwise the value would not read back: the decoder
--   fills a missing key from the default, so e.g. a field <a>Nothing</a>
--   with the default <tt>Just 1</tt> would read back as <tt>Just 1</tt>. A
--   value that encodes as its default still reads back as the default,
--   e.g. a field <a>Nothing</a> of type <tt>Maybe (Maybe a)</tt> with the
--   default <tt>Just Nothing</tt>, because both encode as null.
[omitNullFields] :: YamlOptions -> !Bool

-- | Reject a key that is not a field of the constructor. On by default.
--   
--   Turn it off for a document with keys that the type does not model,
--   e.g. keys that only hold anchors. The decoder then ignores such keys,
--   and an encode of the value leaves them out.
[rejectUnknownFields] :: YamlOptions -> !Bool

-- | The options with the defaults that the fields of <a>YamlOptions</a>
--   name.
defaultYamlOptions :: YamlOptions

-- | How a tagged constructor goes in a mapping. The choice is a type, see
--   <a>SumEncoding</a>, because it changes the shapes of the constructors
--   that a type can have.
data SumEncodingKind

-- | The fields go next to the tag, e.g. <tt>{tag: Circle, radius: 1}</tt>,
--   and a field without a name goes under the contents key, e.g. <tt>{tag:
--   Forward, contents: 10}</tt>.
--   
--   An enumeration is a string, but a constructor without fields in a type
--   with fields is a mapping, e.g. <tt>{tag: Stop}</tt>. To keep the
--   encoding of an enumeration when you add a constructor with fields, use
--   <a>SingleField</a>.
TaggedObject :: SumEncodingKind

-- | The entries of a field without a name go next to the tag, e.g.
--   <tt>{tag: Ahead, distance: 10}</tt> for <tt>Ahead (Distance 10)</tt>.
--   The constructors must have one field without a name or no fields,
--   otherwise the derived instances are a type error.
--   
--   The field must encode as a mapping with a key and without an anchor or
--   a tag, and no key can be the tag key or the contents key. Otherwise
--   the constructor encodes as with <a>TaggedObject</a>. Thus the field of
--   a type with the same tag key stays under the contents key, and so do a
--   mapping with an anchor that an alias can refer to and a <a>Tagged</a>
--   value.
--   
--   Only the entries of the mapping go next to the tag. The comments of
--   the mapping are lost, e.g. the comments of a <a>Commented</a> value.
--   <a>TaggedObject</a> keeps them.
--   
--   The decoder reads a mapping with the contents key as with
--   <a>TaggedObject</a>, and the other keys are unknown keys. Without the
--   contents key, the other keys are the field, so a field that is not a
--   mapping needs the contents key. An error at the mapping itself, e.g.
--   that a mapping is not an integer, has a note at the tag that says so.
--   
--   The keys of the mapping belong to the field, so the options of its
--   type apply to them, e.g. <a>rejectUnknownFields</a>.
TaggedFlat :: SumEncodingKind

-- | A mapping with one key, the tag, and the fields as its value, e.g.
--   <tt>{Circle: {radius: 1}}</tt>. A field without a name is the value,
--   e.g. <tt>{Forward: 10}</tt>, and a constructor without fields is its
--   tag, e.g. <tt>Dot</tt>. The tag key and the contents key play no part.
--   
--   Each constructor has its own value, so the constructors of a type can
--   mix named fields with a field without a name. A second key in the
--   mapping is an error. <a>rejectUnknownFields</a> applies to the named
--   fields in the value.
--   
--   The key of a constructor with named fields is not a field, so its
--   comments are lost. The key of a field without a name goes to the
--   field, e.g. for a <a>Commented</a> value.
SingleField :: SumEncodingKind

-- | The value of a field without a default in <a>yamlDefault</a>. A
--   missing key of the field is an error, also if the field accepts null,
--   e.g. for a field of type <a>Maybe</a>. The encoder with
--   <a>omitNullFields</a> keeps such a field.
--   
--   The value throws an exception when it is evaluated, also in your own
--   code that uses <a>yamlDefault</a>. The generic instances evaluate each
--   field of the default to find the required fields, so:
--   
--   <ul>
--   <li>The field must be <a>requiredField</a> itself, e.g. <tt>Just
--   requiredField</tt> is not a valid default value for the field of type
--   <tt>Maybe Text</tt>.</li>
--   <li>The field must be lazy and not a field of a newtype.</li>
--   </ul>
--   
--   With <a>TaggedFlat</a>, the keys next to the tag can belong to a field
--   without a name, e.g. <tt>distance</tt> in <tt>{tag: Ahead, distance:
--   10}</tt> for <tt>Ahead (Distance 10)</tt>. To require such a key, use
--   <a>requiredField</a> in the default of the type of the field, e.g.
--   <tt>Distance</tt>, not of the sum type.
requiredField :: a

-- | The words of a name in lower case, separated by underscores, e.g.
--   <tt>source_paths</tt> for <tt>sourcePaths</tt> or
--   <tt>SourcePaths</tt>, and <tt>http_server</tt> for
--   <tt>HTTPServer</tt>. The rules are the same as for <tt>camelTo2
--   '_'</tt> of aeson.
--   
--   <pre>
--   &gt;&gt;&gt; map snakeCase ["sourcePaths", "SourcePaths", "HTTPServer", "ghcVersion2"]
--   ["source_paths","source_paths","http_server","ghc_version2"]
--   </pre>
snakeCase :: String -> String

-- | Like <a>snakeCase</a>, but with hyphens, e.g. <tt>source-paths</tt>
--   for <tt>sourcePaths</tt>.
--   
--   <pre>
--   &gt;&gt;&gt; kebabCase "sourcePaths"
--   "source-paths"
--   </pre>
kebabCase :: String -> String

-- | The generic encoder, e.g. for an instance by hand that encodes some
--   values in another way.
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   data Size = Size {width :: Int, height :: Int}
--     deriving stock (Generic)
--     deriving anyclass (GenericYamlOptions)
--   instance ToYaml Size where
--     toYaml s
--       | s.width == 0 &amp;&amp; s.height == 0 = toYaml ("empty" :: T.Text)
--       | otherwise = genericToYaml s
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; T.putStr (encodeText [Size 0 0, Size 1 2])
--   - empty
--   - width: 1
--     height: 2
--   </pre>
genericToYaml :: forall a (f :: Type -> Type). (Generic a, GenericYamlOptions a, GDatatype (Rep a), Constructors (Rep a) ~ f, GConstructors f, GEncoding (SumEncoding a) f, GToConstructor f) => a -> Node

-- | The generic decoder, e.g. for an instance by hand with a check after
--   the decode.
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   data Range = Range {low :: Int, high :: Int}
--     deriving stock (Generic, Show)
--     deriving anyclass (GenericYamlOptions)
--   instance FromYaml Range where
--     parseYaml n = do
--       r &lt;- genericParseYaml n
--       if r.low &lt;= r.high then pure r else failAt n "expected low &lt;= high"
--   :}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Range "low: 1\nhigh: 2\n"
--   Right (Range {low = 1, high = 2})
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; either printErrors print (decodeText @Range "low: 3\nhigh: 2\n")
--   input.yaml:1:1: expected low &lt;= high
--     |
--   1 | low: 3
--     | ^
--   </pre>
genericParseYaml :: forall a (f :: Type -> Type). (Generic a, GenericYamlOptions a, GDatatype (Rep a), Constructors (Rep a) ~ f, GConstructors f, GEncoding (SumEncoding a) f, GFromConstructor f) => Node -> Parser a

-- | The layer of the data type at the top of a representation, and the
--   constructors below it. This class and the others of the representation
--   appear in the constraints of <a>genericToYaml</a> and
--   <a>genericParseYaml</a>. Their methods are internal.
class GDatatype (r :: Type -> Type) where {
    type Constructors (r :: Type -> Type) :: Type -> Type;
}

-- | The names and the number of the constructors of a representation.
class GConstructors (f :: k)

-- | The value of <a>SumEncoding</a>, if the constructors allow it.
class GEncoding (e :: SumEncodingKind) (f :: k)

-- | The encoder of the constructors of a representation.
class GToConstructor (f :: k -> Type)

-- | The decoder of the constructors of a representation.
class GFromConstructor (f :: k -> Type)

-- | The names and the number of the fields of a constructor.
class GFields (f :: k)

-- | The encoder of the fields of a constructor.
--   
--   The shape check allows named fields, no fields, or one field without a
--   name. The default methods are for the kind of fields that never calls
--   them.
class GToFields (f :: k -> Type)

-- | The decoder of the fields of a constructor.
--   
--   The shape check allows named fields, no fields, or one field without a
--   name. The default methods are for the kind of fields that never calls
--   them.
class GFromFields (f :: k -> Type)
class Generic a
instance GHC.Classes.Eq Yamlet.Generic.SumEncodingKind
instance GHC.Internal.Exception.Type.Exception Yamlet.Generic.RequiredField
instance (GHC.Internal.Generics.Generic a, Yamlet.Generic.GenericYamlOptions a, Yamlet.Generic.GDatatype (GHC.Internal.Generics.Rep a), Yamlet.Generic.Constructors (GHC.Internal.Generics.Rep a) GHC.Types.~ f, Yamlet.Generic.GConstructors f, Yamlet.Generic.GEncoding (Yamlet.Generic.SumEncoding a) f, Yamlet.Generic.GFromConstructor f, Yamlet.Internal.FromYaml.FromYaml a) => Yamlet.Internal.FromYaml.FromYaml (Yamlet.Generic.GenericYaml a)
instance forall k (f :: k -> *) (g :: k -> *). (Yamlet.Generic.GConstructors f, Yamlet.Generic.GConstructors g) => Yamlet.Generic.GConstructors (f GHC.Internal.Generics.:+: g)
instance forall k (name :: GHC.Types.Symbol) (f :: k -> *) (fixity :: GHC.Internal.Generics.FixityI) (isRecord :: GHC.Types.Bool). (GHC.Internal.TypeLits.KnownSymbol name, Yamlet.Generic.GFields f) => Yamlet.Generic.GConstructors (GHC.Internal.Generics.C1 ('GHC.Internal.Generics.MetaCons name fixity isRecord) f)
instance Yamlet.Generic.GConstructors GHC.Internal.Generics.V1
instance GHC.Internal.TypeLits.KnownSymbol name => Yamlet.Generic.GDatatype (GHC.Internal.Generics.D1 ('GHC.Internal.Generics.MetaData name m p nt) f)
instance Yamlet.Generic.ValidShape (Yamlet.Generic.SingleShape f) => Yamlet.Generic.GEncoding 'Yamlet.Generic.SingleField f
instance Yamlet.Generic.ValidShape (Yamlet.Generic.GShape 'Yamlet.Generic.TaggedFlat f) => Yamlet.Generic.GEncoding 'Yamlet.Generic.TaggedFlat f
instance Yamlet.Generic.ValidShape (Yamlet.Generic.GShape 'Yamlet.Generic.TaggedObject f) => Yamlet.Generic.GEncoding 'Yamlet.Generic.TaggedObject f
instance forall k (f :: k -> *) (g :: k -> *). (Yamlet.Generic.GFields f, Yamlet.Generic.GFields g) => Yamlet.Generic.GFields (f GHC.Internal.Generics.:*: g)
instance forall k (name :: GHC.Types.Symbol) (u :: GHC.Internal.Generics.SourceUnpackedness) (s :: GHC.Internal.Generics.SourceStrictness) (d :: GHC.Internal.Generics.DecidedStrictness) (f :: k -> *). GHC.Internal.TypeLits.KnownSymbol name => Yamlet.Generic.GFields (GHC.Internal.Generics.S1 ('GHC.Internal.Generics.MetaSel ('GHC.Internal.Maybe.Just name) u s d) f)
instance forall k (u :: GHC.Internal.Generics.SourceUnpackedness) (s :: GHC.Internal.Generics.SourceStrictness) (d :: GHC.Internal.Generics.DecidedStrictness) (f :: k -> *). Yamlet.Generic.GFields (GHC.Internal.Generics.S1 ('GHC.Internal.Generics.MetaSel 'GHC.Internal.Maybe.Nothing u s d) f)
instance Yamlet.Generic.GFields GHC.Internal.Generics.U1
instance forall k (f :: k -> *) (g :: k -> *). (Yamlet.Generic.GFromConstructor f, Yamlet.Generic.GFromConstructor g) => Yamlet.Generic.GFromConstructor (f GHC.Internal.Generics.:+: g)
instance forall k (name :: GHC.Types.Symbol) (f :: k -> *) (fixity :: GHC.Internal.Generics.FixityI) (isRecord :: GHC.Types.Bool). (GHC.Internal.TypeLits.KnownSymbol name, Yamlet.Generic.GFields f, Yamlet.Generic.GFromFields f) => Yamlet.Generic.GFromConstructor (GHC.Internal.Generics.C1 ('GHC.Internal.Generics.MetaCons name fixity isRecord) f)
instance Yamlet.Generic.GFromConstructor GHC.Internal.Generics.V1
instance forall k (f :: k -> *) (g :: k -> *). (Yamlet.Generic.GFromFields f, Yamlet.Generic.GFromFields g) => Yamlet.Generic.GFromFields (f GHC.Internal.Generics.:*: g)
instance (GHC.Internal.TypeLits.KnownSymbol name, Yamlet.Internal.FromYaml.FromYaml a) => Yamlet.Generic.GFromFields (GHC.Internal.Generics.S1 ('GHC.Internal.Generics.MetaSel ('GHC.Internal.Maybe.Just name) u s d) (GHC.Internal.Generics.Rec0 a))
instance Yamlet.Internal.FromYaml.FromYaml a => Yamlet.Generic.GFromFields (GHC.Internal.Generics.S1 ('GHC.Internal.Generics.MetaSel 'GHC.Internal.Maybe.Nothing u s d) (GHC.Internal.Generics.Rec0 a))
instance Yamlet.Generic.GFromFields GHC.Internal.Generics.U1
instance forall k (f :: k -> *) (g :: k -> *). (Yamlet.Generic.GToConstructor f, Yamlet.Generic.GToConstructor g) => Yamlet.Generic.GToConstructor (f GHC.Internal.Generics.:+: g)
instance forall k (name :: GHC.Types.Symbol) (f :: k -> *) (fixity :: GHC.Internal.Generics.FixityI) (isRecord :: GHC.Types.Bool). (GHC.Internal.TypeLits.KnownSymbol name, Yamlet.Generic.GFields f, Yamlet.Generic.GToFields f) => Yamlet.Generic.GToConstructor (GHC.Internal.Generics.C1 ('GHC.Internal.Generics.MetaCons name fixity isRecord) f)
instance Yamlet.Generic.GToConstructor GHC.Internal.Generics.V1
instance forall k (f :: k -> *) (g :: k -> *). (Yamlet.Generic.GToFields f, Yamlet.Generic.GToFields g) => Yamlet.Generic.GToFields (f GHC.Internal.Generics.:*: g)
instance (GHC.Internal.TypeLits.KnownSymbol name, Yamlet.Internal.ToYaml.ToYaml a) => Yamlet.Generic.GToFields (GHC.Internal.Generics.S1 ('GHC.Internal.Generics.MetaSel ('GHC.Internal.Maybe.Just name) u s d) (GHC.Internal.Generics.Rec0 a))
instance Yamlet.Internal.ToYaml.ToYaml a => Yamlet.Generic.GToFields (GHC.Internal.Generics.S1 ('GHC.Internal.Generics.MetaSel 'GHC.Internal.Maybe.Nothing u s d) (GHC.Internal.Generics.Rec0 a))
instance Yamlet.Generic.GToFields GHC.Internal.Generics.U1
instance GHC.Internal.Generics.Generic Yamlet.Generic.YamlOptions
instance GHC.Internal.Show.Show Yamlet.Generic.RequiredField
instance GHC.Internal.Show.Show Yamlet.Generic.SumEncodingKind
instance (GHC.Internal.Generics.Generic a, Yamlet.Generic.GenericYamlOptions a, Yamlet.Generic.GDatatype (GHC.Internal.Generics.Rep a), Yamlet.Generic.Constructors (GHC.Internal.Generics.Rep a) GHC.Types.~ f, Yamlet.Generic.GConstructors f, Yamlet.Generic.GEncoding (Yamlet.Generic.SumEncoding a) f, Yamlet.Generic.GToConstructor f, Yamlet.Internal.ToYaml.ToYaml a) => Yamlet.Internal.ToYaml.ToYaml (Yamlet.Generic.GenericYaml a)
instance Yamlet.Generic.ValidShape ('Yamlet.Generic.NamedFields name)
instance Yamlet.Generic.ValidShape 'Yamlet.Generic.NoFields
instance Yamlet.Generic.ValidShape ('Yamlet.Generic.UnnamedField name)


-- | A YAML 1.2.2 library.
--   
--   The library handles two typical use cases well:
--   
--   <ol>
--   <li>Decoding a document that describes a
--   configuration:<pre>&gt;&gt;&gt; :{ data Config = Config { name ::
--   T.Text , paths :: [FilePath] } deriving stock (Generic, Show) deriving
--   (FromYaml) via GenericYaml Config instance GenericYamlOptions Config
--   where yamlDefault = Just Config {name = requiredField, paths = ["."]}
--   :} </pre><pre>&gt;&gt;&gt; input = "name: app\n"
--   </pre><pre>&gt;&gt;&gt; T.putStr input name: app
--   </pre><pre>&gt;&gt;&gt; either printErrors print (decodeText @Config
--   input) Config {name = "app", paths = ["."]} </pre>When a document
--   fails to decode, you get multiple errors pointing at what failed and
--   why:<pre>&gt;&gt;&gt; input = "paths:\n- src\n- 42\nport: 80\n"
--   </pre><pre>&gt;&gt;&gt; T.putStr input paths: - src - 42 port: 80
--   </pre><pre>&gt;&gt;&gt; either printErrors print (decodeText @Config
--   input) input.yaml:1:1: missing key "name" | 1 | paths: | ^
--   input.yaml:3:3: paths[1]: expected a string, but got an integer, quote
--   the value, e.g. '42' | 3 | - 42 | ^ input.yaml:4:1: unknown key
--   "port", expected one of: name, paths | 4 | port: 80 | ^ </pre></li>
--   <li>Decoding a document into a Haskell type and encoding it back. A
--   type can keep the comments of a value with <a>Commented</a>, and a
--   part of the document as it was written with
--   <a>Node</a>:<pre>&gt;&gt;&gt; :{ data Workflow = Workflow { name ::
--   Commented T.Text , matrix :: Node } deriving stock (Generic) deriving
--   anyclass (GenericYamlOptions) deriving (FromYaml, ToYaml) via
--   GenericYaml Workflow :} </pre><pre>&gt;&gt;&gt; input = "# The name in
--   the UI.\nname: build # short\nmatrix:\n # Each system runs the jobs.\n
--   os: [linux, macos]\n ghc: ['9.10', '9.12']\n" </pre><pre>&gt;&gt;&gt;
--   T.putStr input # The name in the UI. name: build # short matrix: #
--   Each system runs the jobs. os: [linux, macos] ghc: ['9.10', '9.12']
--   </pre><pre>&gt;&gt;&gt; Right workflow = decodeText @Workflow input
--   </pre>The decoded name keeps the comment above its key and the comment
--   after its value:<pre>&gt;&gt;&gt; print workflow.name Commented {value
--   = "build", comments = Comments {before = [Comment "The name in the
--   UI."], inline = Just "short", after = []}} </pre><pre>&gt;&gt;&gt;
--   T.putStr (encodeText workflow) # The name in the UI. name: build #
--   short matrix: # Each system runs the jobs. os: [linux, macos] ghc:
--   ['9.10', '9.12'] </pre></li>
--   </ol>
--   
--   The record types of the library, e.g. <a>Error</a> and
--   <a>YamlOptions</a>, have no field selectors. Read a field with the
--   <tt>OverloadedRecordDot</tt> extension, e.g. <tt>err.message</tt>, and
--   set one with the record syntax, e.g. <tt>defaultYamlOptions
--   {fieldLabelModifier = snakeCase}</tt>, or with the generic optics of
--   <a>optics-core</a>, e.g. <tt>defaultYamlOptions &amp;
--   #fieldLabelModifier .~ snakeCase</tt>.
module Yamlet

-- | Decode a stream with one document. An empty stream is null.
--   
--   If the input has a syntax error or fails a check that
--   <a>decodeDocument</a> describes, the result has only that error, with
--   its notes, e.g. the first key of a duplicate key. Otherwise the result
--   has every error that the <a>Parser</a> collects, in the order of their
--   positions.
--   
--   <pre>
--   &gt;&gt;&gt; decode @[Int] "- 1\n- 2\n"
--   Right [1,2]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; decode @(Maybe Int) ""
--   Right Nothing
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; either printErrors print (decode @[Int] "- 1\n- x\n- true\n")
--   input.yaml:2:3: [1]: expected an integer, but got a string
--     |
--   2 | - x
--     |   ^
--   input.yaml:3:3: [2]: expected an integer, but got a boolean
--     |
--   3 | - true
--     |   ^
--   </pre>
decode :: FromYaml a => ByteString -> Either (NonEmpty Error) a

-- | Decode every document of a stream. The errors are as for
--   <a>decode</a>, from the first document that fails. The parser reads
--   the whole stream first, so a syntax error in any document comes before
--   the errors of the others.
--   
--   <pre>
--   &gt;&gt;&gt; decodeAll @Int "1\n---\n2\n"
--   Right [1,2]
--   </pre>
decodeAll :: FromYaml a => ByteString -> Either (NonEmpty Error) [a]

-- | Decode a stream with one document. An empty stream is null. The errors
--   are as for <a>decode</a>.
--   
--   <pre>
--   &gt;&gt;&gt; decodeText @Value "ports: [80, 443]\nenabled: yes\n"
--   Right (Mapping [(String "ports",Sequence [Int 80,Int 443]),(String "enabled",String "yes")])
--   </pre>
decodeText :: FromYaml a => Text -> Either (NonEmpty Error) a

-- | Decode every document of a stream. The errors are as for
--   <a>decodeAll</a>.
decodeAllText :: FromYaml a => Text -> Either (NonEmpty Error) [a]

-- | Decode the bytes of a stream to text. The encoding is UTF-8, UTF-16 or
--   UTF-32, detected as the YAML specification describes.
decodeInput :: ByteString -> Either Error Text

-- | Decode the file as <a>decode</a> does. The file is read as bytes, so
--   the encoding does not depend on the locale. It is UTF-8, UTF-16 or
--   UTF-32, detected as the YAML specification describes.
--   
--   For the errors, give the same path to <a>prettyError</a>:
--   
--   <pre>
--   decodeFile @Config path &gt;&gt;= \case
--     Left errs -&gt; mapM_ (putStrLn . prettyError path) errs
--     Right config -&gt; ...
--   </pre>
decodeFile :: FromYaml a => FilePath -> IO (Either (NonEmpty Error) a)

-- | Decode every document of the file as <a>decodeAll</a> does, with the
--   encoding of <a>decodeFile</a>.
decodeAllFile :: FromYaml a => FilePath -> IO (Either (NonEmpty Error) [a])

-- | Decode a stream with one document as <a>decodeText</a> does, and give
--   the document too, e.g. for <a>documentErrors</a> or to write the file
--   back with its comments. An empty stream is a document with null. A
--   stream of only comments is empty too, so the document does not keep
--   them, as the section <a>Comments</a> says.
decodeWithDocument :: FromYaml a => Text -> Either (NonEmpty Error) (a, Document)

-- | Decode a document of a syntax tree, e.g. to read the values of a file
--   and keep its comments from one parse.
--   
--   As for a parsed input, the decoder checks the document first. The
--   check fails for:
--   
--   <ul>
--   <li>a duplicate key,</li>
--   <li>an undefined alias,</li>
--   <li>an alias inside the node that it refers to, e.g. <tt>&amp;a
--   [*a]</tt>,</li>
--   <li>aliases beyond the limit in <a>Yamlet.Value</a>,</li>
--   <li>a value that is not valid for its tag,</li>
--   <li>a float whose exponent in scientific notation is beyond the range
--   from -1000 to 1000.</li>
--   </ul>
--   
--   The text is the input of the document. An error takes its line from
--   the text. For a document that the program built, the text can be
--   empty. If such a document contains the nodes of a parsed input, pass
--   that input, so that their errors get their lines. The errors are as
--   for <a>decode</a>.
--   
--   The document has the limit of the aliases to itself. For the documents
--   of a stream, use <a>decodeDocuments</a>, so that they share the limit.
decodeDocument :: FromYaml a => Text -> Document -> Either (NonEmpty Error) a

-- | Decode the documents of a syntax tree as <a>decodeDocument</a> does,
--   e.g. the documents of a stream from <a>parseDocumentsText</a>. The
--   documents share the limit of the aliases, as the documents of a stream
--   do. The errors are as for <a>decodeAll</a>.
decodeDocuments :: FromYaml a => Text -> [Document] -> Either (NonEmpty Error) [a]

-- | Encode a value as a document.
--   
--   <pre>
--   &gt;&gt;&gt; encode [1, 2 :: Int]
--   "- 1\n- 2\n"
--   </pre>
encode :: ToYaml a => a -> ByteString

-- | Encode values as a stream of documents.
encodeAll :: ToYaml a => [a] -> ByteString

-- | Encode a value as a document.
--   
--   <pre>
--   &gt;&gt;&gt; T.putStr (encodeText (mapping ["name" .= ("app" :: T.Text), "ports" .= [80, 443 :: Int]]))
--   name: app
--   ports:
--   - 80
--   - 443
--   </pre>
encodeText :: ToYaml a => a -> Text

-- | Encode values as a stream of documents.
--   
--   <pre>
--   &gt;&gt;&gt; T.putStr (encodeAllText [1, 2 :: Int])
--   1
--   ---
--   2
--   </pre>
encodeAllText :: ToYaml a => [a] -> Text

-- | Encode a value as a document in the file, in UTF-8. The file is
--   written as bytes, so the encoding does not depend on the locale.
encodeFile :: ToYaml a => FilePath -> a -> IO ()

-- | Encode values as a stream of documents in the file, as
--   <a>encodeFile</a> does.
encodeAllFile :: ToYaml a => FilePath -> [a] -> IO ()

-- | A node of a document.
data Node

-- | The offset of a byte in the input text, in its UTF-8 encoding. For an
--   input in UTF-16 or UTF-32, the offset counts the bytes of the text
--   after <a>decodeInput</a>, not the bytes of the input.
newtype Offset
Offset :: Int -> Offset

-- | The offset of a node that does not come from an input.
noOffset :: Offset

-- | A value with the offset of its node, e.g. for the error of a check
--   that runs after the decode. The encoder writes only the value.
--   
--   <a>documentErrors</a> turns the offsets into errors with lines,
--   columns and paths. It needs the text and the document of the decode,
--   so decode with <a>decodeWithDocument</a>. Here the check gives an
--   offset and a message for each problem:
--   
--   <pre>
--   &gt;&gt;&gt; input = "paths:\n- src\n- /etc\n"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   case decodeWithDocument @(M.Map T.Text [Located T.Text]) input of
--     Right (config, doc) -&gt;
--       let errs =
--             [ (p.offset, "the path is outside the repository")
--             | p &lt;- concat (M.elems config)
--             , "/" `T.isPrefixOf` p.value
--             ]
--       in printErrors (documentErrors input doc errs)
--     Left errs -&gt; printErrors errs
--   :}
--   input.yaml:3:3: paths[1]: the path is outside the repository
--     |
--   3 | - /etc
--     |   ^
--   </pre>
--   
--   A value that no node gives, e.g. a value of <a>yamlDefault</a>, has
--   <a>noOffset</a>. Its error has no position, and <a>prettyError</a>
--   prints only the file and the message. A value inside an alias has the
--   offset of the alias, i.e. of the place where the document uses the
--   value.
--   
--   Two equal values at different places are not equal as <a>Located</a>
--   values, e.g. a set keeps both. The equality and the order compare the
--   values first and then the offsets. To compare only the values, e.g. in
--   a test, use the field <tt>value</tt>.
data Located a
Located :: !a -> !Offset -> Located a
[value] :: Located a -> !a
[offset] :: Located a -> !Offset

-- | A value with the comments of its mapping entry:
--   
--   <ul>
--   <li><a>before</a>: the lines above the entry,</li>
--   <li><a>inline</a>: the comment at the end of the line of the key, or
--   of the line where a value on several lines ends,</li>
--   <li><a>after</a>: the lines after the value, e.g. after the last entry
--   of a collection.</li>
--   </ul>
--   
--   A <a>Commented</a> value of a mapping entry has the comments of the
--   entry. A block list or mapping under the key has its own comments: the
--   lines below the key up to the last empty line above its first entry. A
--   <a>Commented</a> value inside the first one keeps them, so a type that
--   keeps both nests two <a>Commented</a> values:
--   
--   <pre>
--   &gt;&gt;&gt; input = "# The CI jobs.\njobs:\n  # Run on every push.\n\n  # Check the formatting.\n  - lint\n"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; T.putStr input
--   # The CI jobs.
--   jobs:
--     # Run on every push.
--   
--     # Check the formatting.
--     - lint
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; Right entries = decodeText @(M.Map T.Text (Commented (Commented [Commented T.Text]))) input
--   
--   &gt;&gt;&gt; Just jobs = M.lookup "jobs" entries
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; jobs.comments
--   Comments {before = [Comment "The CI jobs."], inline = Nothing, after = []}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; jobs.value.comments
--   Comments {before = [Comment "Run on every push.",EmptyLine], inline = Nothing, after = []}
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; map (.comments) jobs.value.value
--   [Comments {before = [Comment "Check the formatting."], inline = Nothing, after = []}]
--   </pre>
--   
--   A value without a key, e.g. an item of a list, has the comments of its
--   node. The comments of a list or a mapping stay with it, not with its
--   first item or key: the lines up to the last empty line above its first
--   entry, and the comment on its first line, e.g. after its tag. A
--   <a>Commented</a> value of the whole list or mapping keeps them.
--   
--   By the rules in <a>Comments</a>, some lines read back with a change:
--   
--   <ul>
--   <li>The lines after a text of several lines, which the encoder writes
--   as a block scalar, read back as the lines above the next entry. After
--   the last entry, they belong to the end of the collection around the
--   entry.</li>
--   <li>The lines above a list or a mapping without a key can get an empty
--   line below them, e.g. at the top level. The empty line reads back as
--   the last of these lines.</li>
--   <li>The lines above the first item of a list or the first key of a
--   mapping that end with an empty line read back as the lines of the list
--   or the mapping. A <a>Commented</a> list or mapping keeps them. Under a
--   key, the inner of two nested <a>Commented</a> values keeps them, as
--   above. Otherwise they are lost.</li>
--   </ul>
--   
--   A comment is lost if its node has no place for it, i.e. if the node
--   does not decode into a node or a <a>Commented</a> value:
--   
--   <ul>
--   <li>the comments of a key without a Haskell field, e.g. the tag of a
--   constructor;</li>
--   <li>a comment at the end of a nested mapping, unless the field that
--   holds the mapping is <a>Commented</a>, because a record has no place
--   for the end of its mapping;</li>
--   <li>the comments of a record's mapping above its first key, e.g. a
--   comment at the top of a file above an empty line;</li>
--   <li>the comments of the key for a type such as <tt>data Name = Name
--   (Commented Text)</tt> that derives its instances through
--   <a>Generic</a>, because a derived instance for one constructor with
--   one field without a name does not give the key of its entry to the
--   value inside. Declare such a type as a newtype and derive its
--   instances with <tt>deriving newtype</tt>, which gives the key to the
--   value.</li>
--   </ul>
--   
--   In a map, use <a>Commented</a> on the key or on the value, not on
--   both. With both, the decoder gives the comments of the key to both,
--   and the encoder writes only those of the value, so a change to the
--   comments of the key is lost.
--   
--   A change of the value keeps the comments:
--   
--   <pre>
--   &gt;&gt;&gt; input = "# The port.\nport: 80 # the default\n"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; :{
--   either printErrors (T.putStr . encodeText . M.map (fmap (+ 1))) $
--     decodeText @(M.Map T.Text (Commented Int)) input
--   :}
--   # The port.
--   port: 81 # the default
--   </pre>
--   
--   The order compares the values first and then the comments, e.g. in a
--   set.
data Commented a
Commented :: !a -> !Comments -> Commented a
[value] :: Commented a -> !a
[comments] :: Commented a -> !Comments

-- | The comments and the empty lines that belong to a node.
data Comments
Comments :: ![Line] -> !Maybe Text -> ![Line] -> Comments

-- | The lines above the node.
[before] :: Comments -> ![Line]

-- | The comment at the end of the line where the node ends, or of the
--   first line of a block collection or a block scalar. The renderer
--   writes each line break in it as a space. The line breaks are the
--   characters that <a>CommentLine</a> lists.
[inline] :: Comments -> !Maybe Text

-- | The lines below the node: after the last entry of a collection,
--   between the brackets of an empty collection, or below a scalar or an
--   alias in a block collection or at the root. The section
--   <a>Comments</a> gives the rules. The renderer writes such lines below
--   any node.
[after] :: Comments -> ![Line]

-- | No comments and no empty lines.
noComments :: Comments

-- | A line of comments.
data Line
EmptyLine :: Line

-- | The number of <tt>#</tt> characters at the start of the comment, e.g.
--   2 for <tt>## Section</tt>, and the text after them, without the one
--   space after the <tt>#</tt> characters and without the white space at
--   its end. The renderer writes a count below 1 as 1. It writes a text
--   with line breaks as several comment lines with the same <tt>#</tt>
--   characters, and the parser reads them back as several comments.
--   U+0085, U+2028 and U+2029 count as line breaks here, because YAML 1.1
--   reads them as line breaks.
--   
--   The comment at the end of a line in <a>Comments</a> is a text without
--   a count. It keeps the <tt>#</tt> characters after the first one in its
--   text.
CommentLine :: !Int -> !Text -> Line

-- | A comment with one <tt>#</tt>. As a pattern, it matches every comment
--   and ignores the number of <tt>#</tt> characters.
pattern Comment :: Text -> Line
