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


-- | Retrieve, store and manage real quantum random data.
--   
--   Retrieve, store and manage real quantum random data, originating from
--   vacuum fluctuations of the electromagnetic field and served by
--   Australian National University.
--   
--   The package is designed to ensure quantum random data is promptly
--   available for your application by keeping a sufficient amount locally.
--   When depleted to a specified level, more data is downloaded
--   concurrently over SSL. It can be configured by specifying the minimum
--   store size (below which more data are retrieved) the target store size
--   (the size of the store after retrieval) and the default display style.
--   
--   For more information on the API service on which this package is
--   based, visit the ANU QRN webpage at <a>http://qrng.anu.edu.au/</a>.
@package quantum-random
@version 0.6.4


-- | Provides a data type describing the parsing errors that are possible,
--   though unlikely, to be encountered.
--   
--   Note that since network requests are handled by the
--   <tt>http-conduit</tt> package, the corresponding
--   <tt>HttpException</tt> is also one a user may wish to handle.
--   
--   Usually to be imported via the <a>Quantum.Random</a> module.
module Quantum.Random.Exceptions

-- | Represents two possible error conditions that may be encountered: in
--   interpreting data retrived from ANU, or while reading the local
--   settings file.
data QRException
ParseResponseError :: String -> QRException
ParseSettingsError :: String -> QRException

-- | Perform an IO computation that might encounter a problem corresponding
--   to a <a>Exception</a>. If so, throw the exception, if not just return
--   the value.
throwLeft :: Exception e => IO (Either e a) -> IO a
instance GHC.Show.Show Quantum.Random.Exceptions.QRException
instance GHC.Exception.Exception Quantum.Random.Exceptions.QRException


-- | Functionality for display of binary data. Seeing a visual
--   representation of quantum random data lets a user visually verify that
--   it is indeed random.
--   
--   Usually to be imported via the <a>Quantum.Random</a> module.
module Quantum.Random.Display

-- | Represents the supported methods for displaying binary data. All
--   styles show data separated by byte except for <a>Hex</a>.
data DisplayStyle
Colors :: DisplayStyle
Spins :: DisplayStyle
Bits :: DisplayStyle
Hex :: DisplayStyle
ColorSpins :: DisplayStyle
ColorBits :: DisplayStyle
ColorHex :: DisplayStyle

-- | Parse a string to one of the supported display styles.
parseStyle :: String -> Maybe DisplayStyle

-- | Display a given list of bytes with the specified display style.
display :: DisplayStyle -> [Word8] -> IO ()
instance GHC.Classes.Eq Quantum.Random.Display.DisplayStyle
instance GHC.Show.Show Quantum.Random.Display.DisplayStyle
instance GHC.Generics.Generic Quantum.Random.Display.DisplayStyle
instance Data.Aeson.Types.FromJSON.FromJSON Quantum.Random.Display.DisplayStyle
instance Data.Aeson.Types.ToJSON.ToJSON Quantum.Random.Display.DisplayStyle


-- | This module provides functionality for retrieving and parsing the
--   quantum random number data from the Australian National University QRN
--   server.
--   
--   This module can be used when one only wants to use live data directly
--   from the server, without using any of the data store functionality.
--   
--   In most other cases it should be imported via the
--   <a>Quantum.Random</a> module.
module Quantum.Random.ANU

-- | Fetch quantum random data from ANU server as a linked list of bytes
--   via HTTPS. Network problems may result in an <tt>HttpException</tt>.
--   An invalid response triggers a <a>QRException</a>.
fetchQR :: Int -> IO [Word8]

-- | Fetch QRN data from ANU server as a linked list of booleans via HTTPS.
--   Network problems may result in an <tt>HttpException</tt>. An invalid
--   response triggers a <a>QRException</a>.
fetchQRBits :: Int -> IO [Bool]


-- | This module provides functionality for quantum random data operations
--   involving the local data store and/or the settings file.
--   
--   It also provides a way to coordinate access to these local files. See
--   <a>AccessControl</a> for details. Any IO operation that uses these
--   files can used in a coordinated way by wrapping them in a
--   <a>withAccess</a>.
--   
--   Some of these functions already come in special access-controlled
--   variants because they only require access in particular branches or
--   phases of execution. In particular we have <a>addSafely</a>,
--   <a>extractSafely</a> and <a>observeSafely</a>.
--   
--   Finally, there is functionality to ensure that a forked thread is
--   allowed to finish, in case main would otherwise return too soon. This
--   is primarily needed to provide <a>addConcurrently</a>, but it can be
--   re-used by forking a thread with <a>forkSafely</a> and exiting the
--   program with <a>exitSafely</a>.
--   
--   Usually to be imported via the <a>Quantum.Random</a> module.
module Quantum.Random.Store

-- | Get path of local store file set up by cabal on installation.
getStoreFile :: IO FilePath

-- | Retrieve quantum random data from local store as a raw bytestring.
getStore :: IO ByteString

-- | Retrieve quantum random data from local store as a list of bytes.
getStoreBytes :: IO [Word8]

-- | Compute the size of the current data store.
storeSize :: IO Int

-- | Save the data store to another file, specified by the provided path.
--   Asks for overwrite confirmation if the file already exists.
save :: String -> IO ()

-- | Display status information: Current store size, minimum size setting,
--   target size setting, default display style and data file path.
status :: IO ()

-- | Insert data into local store as a raw bytestring, overwriting any
--   current contents.
putStore :: ByteString -> IO ()

-- | Insert data into local store as a list of bytes, overwriting any
--   current contents.
putStoreBytes :: [Word8] -> IO ()

-- | Append the supplied bytestring to the store file.
appendToStore :: ByteString -> IO ()

-- | Retrieve the specified number of QRN bytes and add them to the store.
addToStore :: Int -> IO ()

-- | Like <a>addToStore</a>, but uses <a>AccessControl</a> to ensure that
--   file writing doesn't interfere with other operations.
addSafely :: AccessControl -> Int -> IO ()

-- | Fork a thread to add data to the store concurrently.
addConcurrently :: AccessControl -> Int -> IO ThreadId

-- | Calculate the amount of data needed to reach target store size and
--   retrieve it from ANU.
fill :: IO ()

-- | Refill data store to target size, discarding data already present.
refill :: IO ()

-- | Load binary data from specified file path, append it to the data
--   store.
load :: String -> IO ()

-- | Remove all data from the store.
clearStore :: IO ()

-- | Get the specified number of QRN bytes, either from the store and/or by
--   obtaining more from ANU as needed. As the name implies, the obtained
--   bytes are removed from the store. If the store is left with fewer than
--   the minimum number of QRN bytes it is filled back to the target size.
extract :: Int -> IO [Word8]

-- | Access-controlled version of <a>extract</a>.
extractSafely :: AccessControl -> Int -> IO [Word8]

-- | Destructively view the specified number of bytes, via <a>extract</a>.
--   The name connotes the irreversibility of quantum measurement.
--   Measuring quantum data (analogously, viewing or using) expends them as
--   a randomness resource. Thus they are discarded. Use <a>peek</a> if
--   instead you wish the data to be kept.
observe :: Maybe DisplayStyle -> Int -> IO ()

-- | Destructively view the specified number of bytes, via
--   <a>extractSafely</a>. Access-controlled version of <a>observe</a>.
observeSafely :: AccessControl -> Maybe DisplayStyle -> Int -> IO ()

-- | Non-destructively view the specified number of bytes.
peek :: Maybe DisplayStyle -> Int -> IO ()

-- | Non-destructively view all data in the store.
peekAll :: Maybe DisplayStyle -> IO ()

-- | Like <a>display</a> only taking a <a>Maybe</a> <a>DisplayStyle</a> as
--   the first argument, where <a>Nothing</a> signifies using the default
--   display style.
display_ :: Maybe DisplayStyle -> [Word8] -> IO ()

-- | Query the settings file for the minimum store size setting.
getMinStoreSize :: IO Int

-- | Query the settings file for the target store size setting.
getTargetStoreSize :: IO Int

-- | Query the settings file for the default display style.
getDefaultStyle :: IO DisplayStyle

-- | Update the minimum store size setting in the settings file.
setMinStoreSize :: Int -> IO ()

-- | Update the target store size setting in the settings file.
setTargetStoreSize :: Int -> IO ()

-- | Update the default <a>DisplayStyle</a> setting in the settings file.
setDefaultStyle :: DisplayStyle -> IO ()

-- | Restore default settings.
restoreDefaults :: IO ()

-- | Restore default settings and <a>refill</a> the store.
reinitialize :: IO ()

-- | A data type to coordinate access to the local files, implemented with
--   an <a>MVar</a> <tt>()</tt>. When the unit is present, access is
--   available. IO operations that need access to the store or settings
--   file remove it from the <a>MVar</a> before doing so, and then replace
--   it when they're done. Then whenever two such operations might
--   otherwise interfere, they will instead wait their turn to obtain the
--   access. This functionality is implemented with
--   <a>initAccessControl</a> and <a>withAccess</a>.
--   
--   Secondarily, it also contains another <a>MVar</a> <tt>()</tt> used to
--   prevent premature program exit when a forked thread is running,
--   implemented as <a>forkSafely</a> and <a>exitSafely</a>. The
--   <tt>qrand</tt> executable uses this to ensure that a concurrent
--   operation to add data from ANU can finish.
data AccessControl

-- | Initiate the access control system.
initAccessControl :: IO AccessControl

-- | Perform the supplied IO action only when access is granted.
withAccess :: AccessControl -> IO a -> IO a

-- | Perform the supplied IO action in a new thread while preventing
--   premature program exit in conjunction with <a>exitSafely</a>.
forkSafely :: AccessControl -> IO () -> IO ThreadId

-- | Exit with this operation to ensure a thread forked with
--   <a>forkSafely</a> can finish before <tt>main</tt> returns.
exitSafely :: AccessControl -> IO ()


-- | This module reexports all the public modules in the package.
module Quantum.Random