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


-- | Translate between binary data and a human-readable
--   collection of words.
--   
--   Translate between binary data and a human-readable collection of
--   words.
--   
--   The PGP Word List consists of two phonetic alphabets, each with one
--   word per possible byte value. A string of bytes is translated with
--   these alphabets, alternating between them at each byte.
--   
--   The PGP words corresponding to the bytes <tt>5B 1D CA 6E</tt> are
--   "erase breakaway spellbind headwaters", for example.
--   
--   For further information, see <a>Wikipedia</a>.
@package pgp-wordlist
@version 0.1.0.2


-- | A type of list that contains two alternating element types.
module Data.Text.PgpWordlist.Internal.AltList

-- | List of elements of alternating element types.
data AltList a b
Nil :: AltList a b
(:<>) :: a -> AltList b a -> AltList a b

-- | Simple conversion function. Inverse of <a>toList</a>.
fromList :: [a] -> AltList a a

-- | Simple conversion function. Inverse of <a>fromList</a>.
toList :: AltList a a -> [a]

-- | Map over every other element of an <a>AltList</a>, starting with the
--   first entry.
--   
--   <pre>
--   <a>first</a> f ≡ <a>bimap</a> f <a>id</a>
--   </pre>
first :: (a -> a') -> AltList a b -> AltList a' b

-- | Map over every other element of an <a>AltList</a>, starting with the
--   second entry.
--   
--   <pre>
--   <a>second</a> g ≡ <a>bimap</a> <a>id</a> g
--   </pre>
second :: (b -> b') -> AltList a b -> AltList a b'

-- | Map over the both types of entries of an <a>AltList</a>.
--   
--   <pre>
--   <a>bimap</a> f g ≡ <a>second</a> g . <a>first</a> f
--   </pre>
bimap :: (a -> a') -> (b -> b') -> AltList a b -> AltList a' b'

-- | The <a>Bifunctor</a> analogon to <a>sequenceA</a>.
bisequence :: Applicative f => AltList (f a) (f b) -> f (AltList a b)

-- | The <a>Bifunctor</a> analogon to <a>traverse</a>.
bitraverse :: Applicative f => (a -> f c) -> (b -> f d) -> AltList a b -> f (AltList c d)
instance (GHC.Show.Show b, GHC.Show.Show a) => GHC.Show.Show (Data.Text.PgpWordlist.Internal.AltList.AltList a b)
instance (GHC.Classes.Ord b, GHC.Classes.Ord a) => GHC.Classes.Ord (Data.Text.PgpWordlist.Internal.AltList.AltList a b)
instance (GHC.Classes.Eq b, GHC.Classes.Eq a) => GHC.Classes.Eq (Data.Text.PgpWordlist.Internal.AltList.AltList a b)
instance Data.Bifunctor.Bifunctor Data.Text.PgpWordlist.Internal.AltList.AltList

module Data.Text.PgpWordlist.Internal.Types

-- | Abstract representation of a PGP word list.
newtype PgpWordlist
PgpWordlist :: (AltList EvenWord OddWord) -> PgpWordlist

-- | Possible translation errors from a list of PGP words to binary format.
data TranslationError

-- | Word is not recognized
BadWord :: Text -> TranslationError

-- | Word is recognized, but from the wrong alphabet. Duplicates,
--   omissions, and neighbour transpositions are often cause for this.
BadParity :: Text -> Word8 -> TranslationError

-- | Word that is supposed to occur in an even position
newtype EvenWord
EvenWord :: Text -> EvenWord
[unEvenWord] :: EvenWord -> Text

-- | Word that is supposed to occur in an odd position
newtype OddWord
OddWord :: Text -> OddWord
[unOddWord] :: OddWord -> Text
instance GHC.Show.Show Data.Text.PgpWordlist.Internal.Types.PgpWordlist
instance GHC.Classes.Ord Data.Text.PgpWordlist.Internal.Types.PgpWordlist
instance GHC.Classes.Eq Data.Text.PgpWordlist.Internal.Types.PgpWordlist
instance GHC.Show.Show Data.Text.PgpWordlist.Internal.Types.OddWord
instance GHC.Classes.Ord Data.Text.PgpWordlist.Internal.Types.OddWord
instance GHC.Classes.Eq Data.Text.PgpWordlist.Internal.Types.OddWord
instance GHC.Show.Show Data.Text.PgpWordlist.Internal.Types.EvenWord
instance GHC.Classes.Ord Data.Text.PgpWordlist.Internal.Types.EvenWord
instance GHC.Classes.Eq Data.Text.PgpWordlist.Internal.Types.EvenWord
instance GHC.Show.Show Data.Text.PgpWordlist.Internal.Types.TranslationError
instance GHC.Classes.Ord Data.Text.PgpWordlist.Internal.Types.TranslationError
instance GHC.Classes.Eq Data.Text.PgpWordlist.Internal.Types.TranslationError


-- | Bimap between <a>Word8</a> an an arbitrary (ordered) type. Values of
--   type <a>Word8Bimap</a> have to be constructed carefully to contain
--   values for all 256 <a>Word8</a> values, or the API will not be safe to
--   use.
module Data.Text.PgpWordlist.Internal.Word8Bimap

-- | Bimap where one of the keys is (of the size of) a <a>Word8</a>.
data Word8Bimap a

-- | Create a <a>Word8Bimap</a> from an association list.
--   
--   The list must contain all <a>Word8</a> in order to make the API
--   operating on the result safe.
unsafeConstruct :: Ord a => [(Word8, a)] -> Word8Bimap a

-- | Get the value corresponding to an index.
lookupL :: Word8Bimap a -> Word8 -> a

-- | Get the index corresponding to a value, if present.
lookupR :: Ord a => Word8Bimap a -> a -> Maybe Word8

module Data.Text.PgpWordlist.Internal.Words

-- | Database of PGP words
wordList :: [(Word8, EvenWord, OddWord)]


-- | Core functionality for conversion between binary formats and PGP word
--   lists.
module Data.Text.PgpWordlist.Internal.Convert

-- | Inverse of <a>fromText</a>, modulo whitespace count.
--   
--   <pre>
--   &gt;&gt;&gt; toText (BSL.pack [104, 101, 108, 108, 111])
--   "frighten glossary glucose handiwork gremlin"
--   </pre>
toText :: ByteString -> Text

-- | Convert a text of whitespace-separated words to their binary
--   representation. The whitespace splitting behaviour is given by
--   <a>words</a>.
--   
--   <pre>
--   &gt;&gt;&gt; fromText (T.pack "frighten glossary glucose handiwork gremlin")
--   Right "hello"
--   </pre>
--   
--   Invalid words are recognized:
--   
--   <pre>
--   &gt;&gt;&gt; fromText (T.pack "frighten dragon glucose handiwork gremlin")
--   Left (BadWord "dragon")
--   </pre>
--   
--   Typical mistakes include accidentally swapping numbers, which leads to
--   a parity error:
--   
--   <pre>
--   &gt;&gt;&gt; fromText (T.pack "frighten glucose glossary handiwork gremlin")
--   Left (BadParity "glucose" 108)
--   </pre>
fromText :: Text -> Either TranslationError ByteString

-- | Look up the word corresponding to a byte.
toEvenWord :: Word8 -> EvenWord

-- | Look up the word corresponding to a byte.
toOddWord :: Word8 -> OddWord

-- | Simple conversion, taking into account invalid words.
fromEvenWord :: Text -> Either TranslationError Word8

-- | Simple conversion, taking into account invalid words.
fromOddWord :: Text -> Either TranslationError Word8

-- | Look up a word in both databases.
lookupEvenOdd :: Text -> (Maybe Word8, Maybe Word8)

-- | Mapping from and to <a>EvenWord</a>s
evenMap :: Word8Bimap EvenWord

-- | Mapping from and to <a>OddWord</a>s
oddMap :: Word8Bimap OddWord


-- | Translate between binary data and a human-readable collection of
--   words.
module Data.Text.PgpWordlist

-- | Inverse of <a>fromText</a>, modulo whitespace count.
--   
--   <pre>
--   &gt;&gt;&gt; toText (BSL.pack [104, 101, 108, 108, 111])
--   "frighten glossary glucose handiwork gremlin"
--   </pre>
toText :: ByteString -> Text

-- | Convert a text of whitespace-separated words to their binary
--   representation. The whitespace splitting behaviour is given by
--   <a>words</a>.
--   
--   <pre>
--   &gt;&gt;&gt; fromText (T.pack "frighten glossary glucose handiwork gremlin")
--   Right "hello"
--   </pre>
--   
--   Invalid words are recognized:
--   
--   <pre>
--   &gt;&gt;&gt; fromText (T.pack "frighten dragon glucose handiwork gremlin")
--   Left (BadWord "dragon")
--   </pre>
--   
--   Typical mistakes include accidentally swapping numbers, which leads to
--   a parity error:
--   
--   <pre>
--   &gt;&gt;&gt; fromText (T.pack "frighten glucose glossary handiwork gremlin")
--   Left (BadParity "glucose" 108)
--   </pre>
fromText :: Text -> Either TranslationError ByteString

-- | Possible translation errors from a list of PGP words to binary format.
data TranslationError

-- | Word is not recognized
BadWord :: Text -> TranslationError

-- | Word is recognized, but from the wrong alphabet. Duplicates,
--   omissions, and neighbour transpositions are often cause for this.
BadParity :: Text -> Word8 -> TranslationError
