harbl/src/Network/DNS/RBL/Domain/Letter.hs

   1 -- | The... also... the simplest module you'll ever see. It contains
   2 --   the 'Letter' type and a Parsec parser to parse one. We don't
   3 --   export its constructor because then you could do something dumb
   4 --   like stick a digit inside one.
   5 --
   6 --   These are defined in RFC1035, Section 2.3.1, \"Preferred name
   7 --   syntax\" <https://tools.ietf.org/html/rfc1035#section-2.3.1>:
   8 --
   9 --     <letter> ::= any one of the 52 alphabetic characters A through
  10 --     Z in upper case and a through z in lower case
  11 --
  12 module Network.DNS.RBL.Domain.Letter (
  13   Letter,
  14   letter )
  15 where
  16
  17 import Data.Char ( toLower )
  18 import qualified Text.Parsec as Parsec ( letter )
  19 import Text.Parsec.String ( Parser )
  20
  21 import Network.DNS.RBL.Pretty ( Pretty(..) )
  22
  23
  24 -- | A wrapper around a letter character.
  25 --
  26 --   ==== _Examples_
  27 --
  28 --   >>> Letter 'x'
  29 --   Letter 'x'
  30 --
  31 newtype Letter = Letter Char deriving (Show)
  32
  33
  34 -- | Pretty-printing for letters that we've already parsed. Just
  35 --   shows/prints the letter character.
  36 --
  37 --   ==== _Examples_
  38 --
  39 --   >>> let l = Letter 'x'
  40 --   >>> pretty_print l
  41 --   x
  42 --
  43 instance Pretty Letter where pretty_show (Letter l) = [l]
  44
  45
  46 -- | Parse a single letter, but wrap it in our 'Letter' type.
  47 --
  48 --   ==== _Examples_
  49 --
  50 --   >>> import Text.Parsec ( parseTest )
  51 --
  52 --   Letters are parsed correctly:
  53 --
  54 --   >>> parseTest letter "x"
  55 --   Letter 'x'
  56 --
  57 --   But digits are not:
  58 --
  59 --   >>> parseTest letter "1"
  60 --   parse error at (line 1, column 1):
  61 --   unexpected "1"
  62 --   expecting letter
  63 --
  64 letter :: Parser Letter
  65 letter = fmap Letter Parsec.letter
  66
  67
  68
  69 -- | The derived instance of 'Eq' for letters is incorrect. All
  70 --   comparisons should be made case-insensitively. The following
  71 --   is an excerpt from RFC1035:
  72 --
  73 --     2.3.3. Character Case
  74 --
  75 --     For all parts of the DNS that are part of the official
  76 --     protocol, all comparisons between character strings (e.g.,
  77 --     labels, domain names, etc.)  are done in a case-insensitive
  78 --     manner...
  79 --
  80 --   Since each part of DNS name is composed of our custom types, it
  81 --   suffices to munge the equality for 'Letter'. RFC4343
  82 --   <https://tools.ietf.org/html/rfc4343> clarifies the
  83 --   case-insensitivity rules, but the fact that we're treating DNS
  84 --   names as strings makes most of those problems go away (in
  85 --   exchange for new ones).
  86 --
  87 --   ==== _Examples_
  88 --
  89 --   >>> let l1 = Letter 'x'
  90 --   >>> let l2 = Letter 'x'
  91 --   >>> let l3 = Letter 'X'
  92 --   >>> let l4 = Letter 'X'
  93 --   >>> l1 == l2
  94 --   True
  95 --   >>> l1 == l3
  96 --   True
  97 --   >>> l1 == l4
  98 --   True
  99 --   >>> l3 == l4
 100 --   True
 101 --
 102 instance Eq Letter where
 103   (Letter l1) == (Letter l2) = (toLower l1) == (toLower l2)