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


-- | DNS name parsing and pattern matching utilities
--   
--   Domain name pattern matching, parsing and pretty printing utilities.
--   See the modules <a>Network.DNS.Pattern</a> and <a>Network.DNS</a> for
--   full documentation.
@package dns-patterns
@version 0.2.1


-- | This module is not part of public API and may change even between
--   patch versions.
module Network.DNS.Internal

-- | Domain label with case-insensitive <a>Eq</a> and <a>Ord</a> as per
--   <a>RFC4343</a>.
data DomainLabel
DomainLabel :: !ShortByteString -> !ShortByteString -> DomainLabel
[getDomainLabel_] :: DomainLabel -> !ShortByteString
[getDomainLabelCF_] :: DomainLabel -> !ShortByteString

-- | A domain parsed into labels. Each label is a <a>ShortByteString</a>
--   rather than <a>Text</a> or <a>String</a> because a label can contain
--   arbitrary bytes. However, the <a>Ord</a> and <a>Eq</a> instances do
--   limited case-folding according to <a>RFC4343</a>.
newtype Domain
Domain :: [DomainLabel] -> Domain

-- | Difference list à la Huhges
newtype DList a
DList :: ([a] -> [a]) -> DList a

-- | Turn a list into <a>DList</a>
toDList :: [a] -> DList a

-- | Turn <a>DList</a> back into a list.
fromDList :: DList a -> [a]

-- | Create a <a>DList</a> containing just the specified element
singleton :: a -> DList a
instance GHC.Classes.Ord Network.DNS.Internal.Domain
instance GHC.Classes.Eq Network.DNS.Internal.Domain
instance GHC.Base.Semigroup (Network.DNS.Internal.DList a)
instance GHC.Base.Monoid (Network.DNS.Internal.DList a)
instance GHC.Classes.Ord Network.DNS.Internal.DomainLabel
instance GHC.Classes.Eq Network.DNS.Internal.DomainLabel


-- | There is no standardized presentation and parsing format for domain
--   names. In this library we assume a domain name and pattern to be
--   specified as a text with an ASCII dot <tt>.</tt> acting as a separator
--   and terminator. We do not admit arbitrary unicode codepoints, only the
--   following subset of ASCII is acceptable per label: [a-z], [A-Z],
--   [0-9], '_', <a>-</a>, <a>*</a>
--   
--   Punycoding, if desired, must be taken care of the user.
--   
--   In addition, we allow a backslash to be used as an escaping character
--   for the following possible sequences:
--   
--   Escape sequences The domain name and pattern language here allows for
--   the following escape sequences
--   
--   <pre>
--   \.      gives a dot inside a label, rather than a label separator
--   \\      gives a backslash inside a label
--   \012    gives an arbitrary octet inside a label as specified by the three octets
--   </pre>
--   
--   For example: <tt>foo\.bar.quux.</tt> is a domain name comprised of two
--   labels <tt>foo.bar</tt> and <tt>quux</tt>
module Network.DNS

-- | A domain parsed into labels. Each label is a <a>ShortByteString</a>
--   rather than <a>Text</a> or <a>String</a> because a label can contain
--   arbitrary bytes. However, the <a>Ord</a> and <a>Eq</a> instances do
--   limited case-folding according to <a>RFC4343</a>.
data Domain

-- | Turn a <a>Domain</a> into a list of its labels.
--   
--   <pre>
--   getDomain . mkDomain ~~~ id
--   </pre>
--   
--   <pre>
--   mkDomain . getDomain ~~~ id
--   </pre>
getDomain :: Domain -> [DomainLabel]

-- | Turn a list of labels into a <a>Domain</a>.
--   
--   <pre>
--   getDomain . mkDomain ~~~ id
--   </pre>
--   
--   <pre>
--   mkDomain . getDomain ~~~ id
--   </pre>
mkDomain :: [DomainLabel] -> Domain

-- | Domain label with case-insensitive <a>Eq</a> and <a>Ord</a> as per
--   <a>RFC4343</a>.
data DomainLabel

-- | Get the wire-representation of a domain label.
getDomainLabel :: DomainLabel -> ShortByteString

-- | Get the <a>RFC4343</a> case-folded wire-representation of a domain
--   label.
getDomainLabelCF :: DomainLabel -> ShortByteString

-- | Smart constructor for <a>DomainLabel</a>
mkDomainLabel :: ShortByteString -> DomainLabel

-- | Unsafely construct a <a>DomainLabel</a>. The argument must already be
--   case-folded according to <a>RFC4343</a>.
unsafeMkDomainLabel :: ShortByteString -> DomainLabel

-- | Unsafely construct a <a>DomainLabel</a> from a single Word8. The
--   argument must already be case-folded according to <a>RFC4343</a>.
unsafeSingletonDomainLabel :: Word8 -> DomainLabel

-- | Case-folding of a domain according to <a>RFC4343</a>. Note
--   <a>Domain</a> will memoize a case-folded variant for <a>Eq</a>,
--   <a>Ord</a> and pretty printing already. This function is not useful to
--   most.
foldCase :: Domain -> Domain

-- | Case-folding of a domain label according to <a>RFC4343</a>. Note
--   <a>DomainLabel</a> will memoize a case-folded variant for <a>Eq</a>,
--   <a>Ord</a> and pretty printing already. This function is not useful to
--   most.
foldCaseLabel :: DomainLabel -> DomainLabel

-- | Parse an absolute domain. Convenience wrapper for <a>absDomainP</a>.
parseAbsDomain :: Text -> Either String Domain

-- | Version of parseAbsDomain that also considers a domain name without a
--   trailing dot to be absolute.
parseAbsDomainRelax :: Text -> Either String Domain

-- | Parse a singular domain label. Convenience wrapper for
--   <a>domainLabelP</a>.
parseDomainLabel :: Text -> Either String DomainLabel

-- | Attoparsec <a>Parser</a> for absolute domains. See
--   <a>parseAbsDomain</a> for a convenience wrapper. For a parser that
--   also admits domain forms without a leading dot, see
--   <a>absDomainRelaxP</a>.
absDomainP :: Parser Domain

-- | Attoparsec <a>Parser</a> for absolute domains. See
--   <a>parseAbsDomainRelax</a> for a convenience warpper. This variant
--   differs from <a>absDomainP</a> in that it does not care whether the
--   domain name ends in a dot.
absDomainRelaxP :: Parser Domain

-- | Attoparsec <a>Parser</a> for a singular domain label. See
--   <a>parseDomainLabel</a> for a convenince wrapper. Also see
--   <a>absDomainP</a>.
domainLabelP :: Parser DomainLabel

-- | Print an arbitrary domain into a presentation format.
--   
--   This function nearly roundtrips with <a>parseAbsDomain</a> up to
--   escape sequence equivalence
--   
--   <pre>
--   parseAbsDomain . pprDomain ~~~ id
--   </pre>
pprDomain :: Domain -> Text

-- | Print an arbitrary domain into a presentation format after
--   case-folding according to <a>RFC4343</a>.
--   
--   This function nearly roundtrips with <a>parseAbsDomain</a> up to
--   escape sequence equivalence and case folding.
--   
--   <pre>
--   parseAbsDomain . pprDomainCF ~~~ id
--   </pre>
pprDomainCF :: Domain -> Text

-- | Print a singular domain label into a presentation format.
pprDomainLabel :: DomainLabel -> Text

-- | Print a singular domain label into a presentation format after
--   case-folding according to <a>RFC4343</a>.
pprDomainLabelCF :: DomainLabel -> Text


-- | This module is not part of public API and may change even between
--   patch versions.
module Network.DNS.Pattern.Internal

-- | Domain label with case-insensitive <a>Eq</a> and <a>Ord</a> as per
--   <a>RFC4343</a>.
data DomainLabel
DomainLabel :: !ShortByteString -> !ShortByteString -> DomainLabel
[getDomainLabel_] :: DomainLabel -> !ShortByteString
[getDomainLabelCF_] :: DomainLabel -> !ShortByteString

-- | A domain parsed into labels. Each label is a <a>ShortByteString</a>
--   rather than <a>Text</a> or <a>String</a> because a label can contain
--   arbitrary bytes. However, the <a>Ord</a> and <a>Eq</a> instances do
--   limited case-folding according to <a>RFC4343</a>.
newtype Domain
Domain :: [DomainLabel] -> Domain

-- | A pattern for a singular label.
data LabelPattern

-- | Represents an exact label that must be matched.
DomLiteral :: DomainLabel -> LabelPattern

-- | Represents a single asterisk glob matching any arbitrary domain at a
--   given level.
DomGlob :: LabelPattern

-- | Represents a double asterisk matching any arbitrary subdomain at a
--   given level.
DomGlobStar :: LabelPattern

-- | A domain pattern.
newtype DomainPattern
DomainPattern :: [LabelPattern] -> DomainPattern
[getDomainPattern] :: DomainPattern -> [LabelPattern]
instance GHC.Classes.Ord Network.DNS.Pattern.Internal.LabelPattern
instance GHC.Classes.Eq Network.DNS.Pattern.Internal.LabelPattern
instance GHC.Classes.Ord Network.DNS.Pattern.Internal.DomainPattern
instance GHC.Classes.Eq Network.DNS.Pattern.Internal.DomainPattern


-- | Patterns can be simple absolute domain names, where labels are
--   replaceable with a single glob <tt>*</tt> or a globstar <tt>**</tt>. A
--   single glob will match any label in its place, where globstar will
--   greedily match as many labels as possible towards the left.
--   
--   Admits the escape sequences from domain names. See <a>DNS</a>.
--   
--   Note: Currently a globstar is only supported on the left-most label.
--   
--   Examples of valid patterns are:
--   
--   <pre>
--   *.foo.bar.
--   **.foo.bar.
--   foo.*.bar.
--   foo.bar.*.
--   </pre>
module Network.DNS.Pattern

-- | A domain pattern.
newtype DomainPattern
DomainPattern :: [LabelPattern] -> DomainPattern
[getDomainPattern] :: DomainPattern -> [LabelPattern]

-- | A pattern for a singular label.
data LabelPattern

-- | Represents an exact label that must be matched.
DomLiteral :: DomainLabel -> LabelPattern

-- | Represents a single asterisk glob matching any arbitrary domain at a
--   given level.
DomGlob :: LabelPattern

-- | Represents a double asterisk matching any arbitrary subdomain at a
--   given level.
DomGlobStar :: LabelPattern

-- | Test whether a given domain matches a <a>DomainPattern</a>
matchesPattern :: Domain -> DomainPattern -> Bool

-- | Given a pattern and a DNS zone specified by a domain name, test
--   whether or not the pattern is applicable beneath that zone.
--   
--   <pre>
--   foo.*.bar.  applicable inside zone          quux.bar.
--   foo.bar.    applicable inside zone          bar.
--   bar.        applicable inside zone          bar.
--   foo.bar.    not applicable inside zone      quux.
--   </pre>
patternWorksInside :: DomainPattern -> Domain -> Bool

-- | Test whether a single label matches a label pattern
labelMatchesPattern :: DomainLabel -> LabelPattern -> Bool

-- | Parse a domain pattern. Convenience wrapper for 'patternP.
parsePattern :: Text -> Either String DomainPattern

-- | Attoparsec <a>Parser</a> for domain patterns. See <a>parsePattern</a>
--   for a convenince wrapper.
patternP :: Parser DomainPattern

-- | Print domain pattern.
--   
--   This function nearly roundtrips with <a>parsePattern</a> up to escape
--   sequence equivalence.
--   
--   <pre>
--   parsePattern . pprPattern ~~~ id
--   </pre>
pprPattern :: DomainPattern -> Text

-- | Print domain pattern after into presentation format after case-folding
--   according to <a>RFC4343</a>.
--   
--   This function nearly roundtrips with <a>parsePattern</a> up to escape
--   sequence equivalence and case folding.
--   
--   <pre>
--   parsePattern . pprPatternCF ~~~ id
--   </pre>
pprPatternCF :: DomainPattern -> Text

-- | Print a singular domain label pattern into a presentation format.
pprLabelPattern :: LabelPattern -> Text

-- | Print a singular domain label pattern into a presentation format after
--   case-folding according to <a>RFC4343</a>.
pprLabelPatternCF :: LabelPattern -> Text