From: Michael Orlitzky Date: Fri, 20 Dec 2013 03:54:08 +0000 (-0500) Subject: Add more code comments. X-Git-Tag: 0.0.2~40 X-Git-Url: http://gitweb.michael.orlitzky.com/?p=dead%2Fhtsn.git;a=commitdiff_plain;h=a2c2a1a6865be7b4cd17fb72de635bb9385728b9 Add more code comments. --- diff --git a/src/CommandLine.hs b/src/CommandLine.hs index 40a1ac8..071c520 100644 --- a/src/CommandLine.hs +++ b/src/CommandLine.hs @@ -1,3 +1,5 @@ +-- | Parse the command-line options, and display help text if +-- necessary. module CommandLine ( get_args ) where @@ -13,33 +15,44 @@ import System.Console.CmdArgs ( typ, typDir ) --- Get the version from Cabal. +-- This let's us get the version from Cabal. import Paths_htsn (version) import Data.Version (showVersion) import OptionalConfiguration (OptionalConfiguration(..)) + +-- | The description of the program, displayed as part of the help. description :: String description = "Parse XML files from The Sports Network." +-- | The name of this program. program_name :: String program_name = "htsn" +-- | A summary string output as part of the help. my_summary :: String my_summary = program_name ++ "-" ++ (showVersion version) + +-- | A description of the "password" option. password_help :: String password_help = "Password to use when connecting to the feed" +-- | A description of the "output_directory" option. output_directory_help :: String output_directory_help = "Directory in which to output the XML files; must be writable" +-- | A description of the "username" option. username_help :: String username_help = "Username to use when connecting to the feed" +-- | A data structure representing the possible command-line +-- options. The CmdArgs library is doing heavy magic beneath the +-- hood here. arg_spec :: OptionalConfiguration arg_spec = OptionalConfiguration { @@ -52,6 +65,7 @@ arg_spec = &= details [description] - +-- | A convenience function; our only export. Meant to be used in +-- 'main' to retrieve the command-line arguments. get_args :: IO OptionalConfiguration get_args = cmdArgs arg_spec diff --git a/src/Configuration.hs b/src/Configuration.hs index 71dbbc9..7b237c5 100644 --- a/src/Configuration.hs +++ b/src/Configuration.hs @@ -1,7 +1,7 @@ -- | This module defines the 'Configuration' type, which is just a -- wrapper around all of the configuration options we accept on the --- command line. We thread this throughout the rest of the program. - +-- command line. +-- module Configuration ( Configuration(..), merge_optional ) @@ -25,6 +25,10 @@ data Configuration = instance Default Configuration where def = Configuration def def "." def + +-- | Merge a Configuration with an OptionalConfiguration. This is more +-- or less the Monoid instance for OptionalConfiguration, but since +-- the two types are different, we have to repeat ourselves. merge_optional :: Configuration -> OC.OptionalConfiguration -> Configuration diff --git a/src/Main.hs b/src/Main.hs index 3749812..1b7458f 100644 --- a/src/Main.hs +++ b/src/Main.hs @@ -44,6 +44,9 @@ import TSN.FeedHosts (FeedHosts(..)) import TSN.Xml (parse_xmlfid, xml_prologue) +-- | Receive a single line of text from a Handle, echoing it to stdout +-- in the process. +-- recv_line :: Handle -> IO String recv_line h = do line <- hGetLine h @@ -51,6 +54,13 @@ recv_line h = do return line +-- | Takes a Configuration, and an XML document (as a String). The XML +-- document is written to the output directory, as specified by the +-- Configuration. +-- +-- This can fail, but we don't purposefully throw any exceptions. If +-- something goes wrong, we would rather log it and keep going. +-- save_document :: Configuration -> String -> IO () save_document cfg doc = case maybe_path of @@ -67,8 +77,11 @@ save_document cfg doc = filename = fmap (++ ".xml") xmlfid maybe_path = fmap ((output_directory cfg) ) filename + -- | Loop forever, writing the buffer to file whenever a new XML --- prologue is seen. +-- prologue is seen. This is the low-level "loop forever" function +-- that we stay in as long as we are connected to one feed. +-- loop :: Configuration -> Handle -> [String] -> IO () loop !cfg !h !buffer = do line <- recv_line h @@ -83,7 +96,8 @@ loop !cfg !h !buffer = do save_document cfg document loop cfg h [line] -- empty the buffer before looping again else - loop cfg h (line : buffer) -- append line to the head of the buffer and loop + -- append line to the head of the buffer and loop + loop cfg h (line : buffer) log_in :: Configuration -> Handle -> IO () @@ -152,12 +166,14 @@ connect_and_loop cfg host = do -- | A wrapper around threadDelay which takes seconds instead of -- microseconds as its argument. +-- thread_sleep :: Int -> IO () thread_sleep seconds = do let microseconds = seconds * (10 ^ (6 :: Int)) threadDelay microseconds +-- | The entry point of the program. main :: IO () main = do rc_cfg <- OC.from_rc @@ -187,12 +203,21 @@ main = do -- set in either the config file or on the command-line. let cfg = (def :: Configuration) `merge_optional` opt_config + -- This may be superstition (and I believe stderr is unbuffered), + -- but it can't hurt. hSetBuffering stderr NoBuffering hSetBuffering stdout NoBuffering + -- Begin connecting to our feed hosts, starting with the first one. round_robin cfg 0 where + -- | This is the top-level "loop forever" function. If an + -- exception is thrown, it will propagate up to this point, where + -- it will be logged and ignored in style. + -- + -- Afterwards, we recurse (call ourself) again to loop more forevers. + -- round_robin :: Configuration -> Int -> IO () round_robin cfg feed_host_idx = do let hosts = get_feed_hosts $ feed_hosts cfg diff --git a/src/TSN/FeedHosts.hs b/src/TSN/FeedHosts.hs index 0b2056e..58831e5 100644 --- a/src/TSN/FeedHosts.hs +++ b/src/TSN/FeedHosts.hs @@ -34,11 +34,18 @@ instance Default FeedHosts where instance DCT.Configured FeedHosts where + -- | This allows us to read a FeedHosts object out of a Configurator + -- config file. By default Configurator wouldn't know what to do, + -- so we have to tell it that we expect a list, and if that list + -- has strings in it, we can apply the FeedHosts constructor to + -- it. convert (DCT.List xs) = + -- mapM gives us a Maybe [String] here. fmap FeedHosts (mapM convert_string xs) where convert_string :: DCT.Value -> Maybe String convert_string = DCT.convert + -- If we read anything other than a list of values out of the file, + -- fail. convert _ = Nothing - diff --git a/src/TSN/Xml.hs b/src/TSN/Xml.hs index 1f057f9..ead8015 100644 --- a/src/TSN/Xml.hs +++ b/src/TSN/Xml.hs @@ -1,3 +1,6 @@ +-- | Minimal XML functionality needed to parse each document's +-- XML_File_ID. +-- module TSN.Xml ( parse_xmlfid, xml_prologue )