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


-- | Generate easy-to-remember, hard-to-guess passwords
--   
--   Generates pronounceable, hard-to-guess passwords--as hard as Vince
--   Carter's knee cartilage is.
@package elocrypt
@version 2.0.0


-- | Generate a letter frequency trigraph, based on a dictionary
module Data.Elocrypt.Trigraph

-- | Search for the character frequencies and return a weighted list
findWeights :: String -> Maybe [(Char, Rational)]

-- | Search for the character frequencies based on the first a two-letter
--   string
findFrequency :: String -> Maybe [Rational]

-- | Fix frequencies if they are all 0, since MonadRandom prohibits this.
--   In this case, use all 1s to give every item an equal weight
defaultFrequencies :: [Rational] -> [Rational]

-- | A map of character frequencies, based on a dictionary. The key is a
--   two-letter string, and the value is a list of probabilities (a-z).
--   It's form is:
--   
--   <pre>
--   [("aa", [2,0,3,0,0,0,1,0,0,0,0,1,1,1,0,0,0,3,2,0,0,0,0,0,0,0]),
--   ...
--    ("zz", [7,0,0,0,1,0,0,0,7,0,0,17,0,0,2,0,0,0,0,0,0,0,1,0,5,0])]
--   </pre>
frequencies :: [(String, [Rational])]


-- | Generate easy-to-remember, hard-to-guess passwords
module Data.Elocrypt

-- | Options for generating passwords or passphrases. Do not use this
--   constructor directly. Instead use <a>genOptions</a> to construct an
--   instance.
newtype GenOptions
GenOptions :: Bool -> GenOptions
[genCapitals] :: GenOptions -> Bool

-- | Default options for generating passwords or passphrases. This is the
--   preferred way to construct <a>GenOptions</a>.
genOptions :: GenOptions

-- | Generate a password using the generator g, returning the result and
--   the updated generator.
--   
--   <pre>
--   -- Generate a password of length 10 using the system generator
--   myGenPassword :: IO (String, StdGen)
--   myGenPassword = genPassword 10 genOptions `liftM` getStdGen
--   
--   </pre>
genPassword :: RandomGen g => Int -> GenOptions -> g -> (String, g)

-- | Plural version of genPassword. Generates an infinite list of passwords
--   using the generator g, returning the result and the updated generator.
--   
--   <pre>
--   -- Generate 10 passwords of length 10 using the system generator
--   myGenPasswords :: IO ([String], StdGen)
--   myGenPasswords = ((ls, g) -&gt; (ls, g) <a>liftM</a> genPasswords 10 10 genOptions <a>liftM</a> getStdGen
--   </pre>
genPasswords :: RandomGen g => Int -> Int -> GenOptions -> g -> ([String], g)

-- | Generate a password using the generator g, returning the result.
--   
--   <pre>
--   -- Generate a password of length 10 using the system generator
--   myNewPassword :: IO String
--   myNewPassword = newPassword 10 genOptions `liftM` getStdGen
--   
--   </pre>
newPassword :: RandomGen g => Int -> GenOptions -> g -> String

-- | Plural version of newPassword. Generates an infinite list of passwords
--   using the generator g, returning the result
--   
--   <pre>
--   -- Generate 10 passwords of length 10 using the system generator
--   myNewPasswords :: IO [String]
--   myNewPasswords = genPasswords 10 10 genOptions <a>liftM</a> getStdGen
--   </pre>
newPasswords :: RandomGen g => Int -> Int -> GenOptions -> g -> [String]

-- | Generate a password using the MonadRandom m. MonadRandom is exposed
--   here for extra control.
--   
--   <pre>
--   -- Generate a password of length 10 using the system generator
--   myPassword :: IO String
--   myPassword = evalRand (mkPassword 10 genOptions) `liftM` getStdGen
--   
--   </pre>
mkPassword :: MonadRandom m => Int -> GenOptions -> m String

-- | Plural version of mkPassword. Generate an infinite list of passwords
--   using the MonadRandom m. MonadRandom is exposed here for extra
--   control.
--   
--   <pre>
--   -- Generate an list of length 20 with passwords of length 10 using the system generator
--   myMkPasswords :: IO [String]
--   myMkPasswords = evalRand (mkPasswords 10 20 genOptions) `liftM` getStdGen
--   </pre>
mkPasswords :: MonadRandom m => Int -> Int -> GenOptions -> m [String]

-- | Generate a passphrase using the generator g, returning the result and
--   the updated generator.
--   
--   <pre>
--   -- Generate a passphrase of 10 words, each having a length between 6 and 12,
--   -- using the system generator
--   myGenPassphrase :: IO (String, StdGen)
--   myGenPassphrase = genPassword 10 6 10 genOptions `liftM` getStdGen
--   
--   </pre>
genPassphrase :: RandomGen g => Int -> Int -> Int -> GenOptions -> g -> ([String], g)

-- | Generate a passphrase using the generator g, returning the result.
--   
--   <pre>
--   -- Generate a passphrase of 10 words, each having a length between 6 an 12,
--   -- using the system generator.
--   myNewPassphrase :: IO String
--   myNewPassphrase = newPassphrase 10 6 12 `liftM` getStdGen
--   
--   </pre>
newPassphrase :: RandomGen g => Int -> Int -> Int -> GenOptions -> g -> [String]

-- | Generate a finite number of words of random length (between
--   <tt>min</tt> and <tt>max</tt> chars) using the MonadRandom m.
--   MonadRandom is exposed here for extra control.
--   
--   <pre>
--   -- Generate a passphrase of 10 words, each having a length between 6 and 12.
--   myPassphrase :: IO String
--   myPassphrase = evalRand (mkPassphrase 10 6 12) `liftM` getStdGen
--   
--   </pre>
mkPassphrase :: MonadRandom m => Int -> Int -> Int -> GenOptions -> m [String]

-- | Generate two random characters. Uses <a>trigragh</a> to generate a
--   weighted list.
first2 :: MonadRandom m => GenOptions -> m String

-- | Generate the last n characters using previous two characters and their
--   <a>trigraph</a>
lastN :: MonadRandom m => GenOptions -> Int -> String -> m String

-- | Generate a random character based on the previous two characters and
--   their <a>trigraph</a>
next :: MonadRandom m => GenOptions -> String -> m Char

-- | Randomly choose a letter from the trigraph
nextLetter :: MonadRandom m => String -> m Char

-- | Randomly capitalize a character 10% of the time
capitalizeR :: MonadRandom m => Bool -> Char -> m Char
instance GHC.Show.Show Data.Elocrypt.GenOptions
instance GHC.Classes.Eq Data.Elocrypt.GenOptions