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


-- | A database of USB identifiers
--   
--   Functions to find the names associated with numerical vendor
--   identifiers.
@package usb-id-database
@version 0.1


-- | A database of USB identifiers.
--   
--   Databases with vendor names and identifiers can be loaded from string,
--   file or directly from <a>http://www.usb.org</a>.
--   
--   Example usage:
--   
--   <pre>
--   module Main where
--   
--   import System.USB.IDDB
--   import Data.ByteString.Char8 (pack, unpack)
--   
--   main :: IO ()
--   main = do -- Acquire the default database
--             db &lt;- <a>vdbDefault</a>
--             -- Print the name of vendor 0x1D6B
--             <a>putStrLn</a> $ 'maybe "unknown ID!" unpack
--                      $ <a>vendorName</a> db 0x1D6B
--             -- Print the ID of "The Linux Foundation"
--             <a>putStrLn</a> $ <a>maybe</a> "unknown name!" <a>show</a>
--                      $ <a>vendorID</a> db (pack "The Linux Foundation")
--   </pre>
--   
--   EBNF grammar of the textual representation of a vendor database:
--   
--   <pre>
--   vendor database = {row};
--   row             = vendor id, "|", vendor name;
--   vendor id       = natural number;
--   vendor name     = ASCII string;
--   natural number  = positive digit, {digit}
--   positive digit  = "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
--   digit           = "0" | positive digit;
--   </pre>
module System.USB.IDDB

-- | A numerical identifier for a vendor.
type VendorID = Int

-- | The name of a company/entity which has acquired an official ID from
--   the USB Implementors Forum.
type VendorName = ByteString

-- | A database of USB vendors. Associates numerical vendor ID's with
--   vendor names and vice versa.
type VendorDB = Bimap VendorID VendorName

-- | Construct a vendor database from a string.
vdbFromString :: ByteString -> Maybe VendorDB

-- | Load a vendor database from file. If the file can not be read for some
--   reason an error will be thrown.
vdbFromFile :: FilePath -> IO (Maybe VendorDB)

-- | Construct a vendor database from the list of companies available at
--   <a>http://www.usb.org/developers/tools/comp_dump</a>. The website
--   informs us that: <i>"Remember this list changes almost daily, be</i>
--   <i>sure to get a fresh copy when you use the tools"</i>. However, the
--   list seems to be quite stable. Using this function more than once a
--   day is probably overkill.
vdbFromUsbDotOrg :: IO (Maybe VendorDB)

-- | Load a vendor database from a static file which is supplied with the
--   package.
vdbDefault :: IO VendorDB

-- | Convert a vendor database to its textual representation.
vdbToString :: VendorDB -> ByteString

-- | Write a database to a file. If this file is not accessible an error
--   will be thrown.
vdbToFile :: FilePath -> VendorDB -> IO ()

-- | Retrieve the name of a vendor given its ID.
vendorName :: VendorDB -> VendorID -> Maybe VendorName

-- | Retrieve the ID of a vendor given its name.
vendorID :: VendorDB -> VendorName -> Maybe VendorID