From: Michael Orlitzky Date: Mon, 13 Jan 2014 04:16:13 +0000 (-0500) Subject: Update documentation. X-Git-Tag: 0.0.1~84 X-Git-Url: https://gitweb.michael.orlitzky.com/?a=commitdiff_plain;h=e3272460a03b4bdded1902467310a4190feb333f;p=dead%2Fhtsn-import.git Update documentation. --- diff --git a/src/CommandLine.hs b/src/CommandLine.hs index cfb43b3..660458b 100644 --- a/src/CommandLine.hs +++ b/src/CommandLine.hs @@ -1,9 +1,11 @@ -- | Parse the command-line options, and display help text if -- necessary. +-- module CommandLine ( get_args ) where +-- System imports. import System.Console.CmdArgs ( (&=), args, @@ -15,50 +17,58 @@ import System.Console.CmdArgs ( summary, typ, typFile ) +import Paths_htsn_import ( version ) -- These let us get the +import Data.Version ( showVersion ) -- version from Cabal. --- This let's us get the version from Cabal. -import Paths_htsn_import (version) -import Data.Version (showVersion) - +-- Local imports. import OptionalConfiguration ( OptionalConfiguration(..) ) + -- | The description of the program, displayed as part of the help. description :: String description = "Import XML files from The Sports Network into an RDBMS." + -- | The name of this program. program_name :: String program_name = "htsn-import" + -- | A summary string output as part of the help. my_summary :: String my_summary = program_name ++ "-" ++ (showVersion version) + -- | A description of the "backend" option. backend_help :: String backend_help = "Database choice, either \"Sqlite\" or \"Postgres\"." + -- | A description of the "connection_string" option. connection_string_help :: String connection_string_help = "A database-specific connection string (depends on the backend)." + -- | A description of the "log_file" option. log_file_help :: String log_file_help = "Log to the given file." + -- | A description of the "log_level" option. log_level_help :: String log_level_help = "How verbose should the logs be? One of INFO, WARNING, ERROR." + -- | A description of the "remove" option. remove_help :: String remove_help = "Remove files that have been successfully imported." + -- | A description of the "syslog" option. syslog_help :: String syslog_help = @@ -68,6 +78,7 @@ syslog_help = -- | 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 { @@ -85,5 +96,6 @@ arg_spec = -- | 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 4d76c73..4d9a1c6 100644 --- a/src/Configuration.hs +++ b/src/Configuration.hs @@ -7,17 +7,21 @@ module Configuration ( merge_optional ) where +-- System imports. import System.Console.CmdArgs.Default ( Default(..) ) import System.Log ( Priority( INFO ) ) +-- Local imports. import Backend ( Backend(..) ) import ConnectionString ( ConnectionString ) import qualified OptionalConfiguration as OC ( OptionalConfiguration(..), merge_maybes ) --- | The main configuration data type. This will be passed to most of --- the important functions once it has been created. + +-- | The main configuration data type. It contains all options that +-- can be set in a config file or on the command line. +-- data Configuration = Configuration { backend :: Backend, @@ -41,8 +45,9 @@ instance Default Configuration where -- | Merge a Configuration with an OptionalConfiguration. This is more --- or less the Monoid instance for OptionalConfiguration, but since +-- 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/ConnectionString.hs b/src/ConnectionString.hs index 26f81d6..702cd0e 100644 --- a/src/ConnectionString.hs +++ b/src/ConnectionString.hs @@ -1,12 +1,15 @@ {-# LANGUAGE DeriveDataTypeable #-} {-# LANGUAGE OverloadedStrings #-} --- | Definition of and instances for the ConnectionString type. +-- | Definition of and instances for the ConnectionString type. This +-- type is simply a wrapper around a 'String', but the newtype +-- allows us to give it a separate 'Default' instance. -- module ConnectionString ( ConnectionString(..) ) where +-- System imports. -- DC is needed only for the DCT.Configured instance of String. import qualified Data.Configurator as DC() import qualified Data.Configurator.Types as DCT ( @@ -17,6 +20,7 @@ import Data.Data (Data) import System.Console.CmdArgs.Default (Default(..)) import Data.Typeable (Typeable) + -- | A newtype around a string that allows us to give a more -- appropriate default value for a connection string. -- @@ -24,6 +28,7 @@ newtype ConnectionString = ConnectionString { get_connection_string :: String } deriving (Data, Show, Typeable) + instance Default ConnectionString where -- | This default is appropriate for SQLite databases which require -- no authentication and live entirely in a file (or in this case, diff --git a/src/OptionalConfiguration.hs b/src/OptionalConfiguration.hs index 213f203..49355f2 100644 --- a/src/OptionalConfiguration.hs +++ b/src/OptionalConfiguration.hs @@ -15,6 +15,7 @@ module OptionalConfiguration ( merge_maybes ) where +-- System imports. import qualified Data.Configurator as DC ( Worth(Optional), load, @@ -33,6 +34,7 @@ import System.IO.Error ( catchIOError ) import System.Log ( Priority(..) ) import Text.Read ( readMaybe ) +-- Local imports. import Backend ( Backend(..) ) import ConnectionString ( ConnectionString ) import Network.Services.TSN.Report ( report_error ) @@ -44,10 +46,10 @@ import Network.Services.TSN.Report ( report_error ) deriving instance Data Priority deriving instance Typeable Priority --- | The same as Configuration, except everything is optional. It's easy to --- merge two of these by simply dropping the Nothings in favor of --- the Justs. The 'feed_hosts' are left un-maybed so that cmdargs --- can parse more than one of them. +-- | The same as 'Configuration', except everything is optional. It's +-- easy to merge two of these by simply dropping the 'Nothing's in +-- favor of the 'Just's. The 'xml_files' are left un-maybed so that +-- cmdargs can parse more than one of them. -- data OptionalConfiguration = OptionalConfiguration { @@ -71,8 +73,8 @@ merge_maybes Nothing (Just x) = Just x merge_maybes (Just _) (Just y) = Just y --- | The Monoid instance for these lets us "combine" two --- OptionalConfigurations. The "combine" operation that we'd like to +-- | The Monoid instance for these lets us \"combine\" two +-- OptionalConfigurations. The \"combine\" operation that we'd like to -- perform is, essentially, to mash them together. So if we have two -- OptionalConfigurations, each half full, we could combine them -- into one big one. diff --git a/src/TSN/Codegen.hs b/src/TSN/Codegen.hs index 9095cef..0e8026d 100644 --- a/src/TSN/Codegen.hs +++ b/src/TSN/Codegen.hs @@ -36,6 +36,7 @@ tsn_db_field_namer :: String -> String -> Int -> String -> Int -> String tsn_db_field_namer _ _ _ fieldname _ = (join "_") . tail . (split "_") $ fieldname + -- | An expression field name creator. \"Expression\" in the context -- of Groundhog means a constructor/type that you can use in queries -- and update statement. We take the field name (from a record type) diff --git a/src/TSN/DbImport.hs b/src/TSN/DbImport.hs index 8884a9e..62cc8a1 100644 --- a/src/TSN/DbImport.hs +++ b/src/TSN/DbImport.hs @@ -1,4 +1,21 @@ -- | Definition of the DbImport typeclass. +-- +-- When we parse an XML tree, there are two functions that we would +-- like to call on the result independent of its type. First, we +-- would like to be able to run the database migrations for that +-- type. The migrations are kept separate from insertion because, at +-- some later point, it make make sense to disable automatic +-- migrations. +-- +-- Next we want to import the thing. +-- +-- Neither of these should depend on the type -- we should just be +-- able to call 'dbmigrate' followed by 'dbimport' on the +-- datastructure and have the right thing happen. That is the +-- purpose of the 'DbImport' typeclass. It allows the XML types to +-- define their own \"migrate me\" and \"insert me\" functions that +-- the rest of the application doesn't have to care about. +-- module TSN.DbImport ( DbImport(..), ImportResult(..), @@ -31,20 +48,20 @@ data ImportResult = -- The second field should contain info. --- | Instances of this type know how to insert themselves into a --- Groundhog database. +-- | Instances of this type know how to run their own database +-- migrations and insert themselves into a database. -- class DbImport a where -- | Import an instance of type @a@. dbimport :: (PersistBackend m) => a -> m ImportResult -- | This must migrate *all* stuffs that can potentially be - -- created/used by the type @a@. + -- created/used by the type @a@. dbmigrate :: (MonadIO m, PersistBackend m) => a -> m () -- | The simplest possible implementation of 'dbimport', for types --- which happen to be members of the XmlImport typeclass. +-- which happen to be members of the 'XmlImport' typeclass. -- dbimport_generic :: (XmlImport a, MonadIO m, PersistBackend m) => a @@ -54,6 +71,7 @@ dbimport_generic x = insert_xml x >> return ImportSucceeded -- | A migration runner that will use our normal info reporting -- mechanism. +-- run_dbmigrate :: (MonadIO m, PersistBackend m) => Migration m -> m () run_dbmigrate = runMigration pretty_migration_logger diff --git a/src/TSN/Picklers.hs b/src/TSN/Picklers.hs index 16a25ef..1193abf 100644 --- a/src/TSN/Picklers.hs +++ b/src/TSN/Picklers.hs @@ -6,6 +6,7 @@ module TSN.Picklers ( xp_team_id ) where +-- System imports. import Data.Time.Clock ( UTCTime ) import Data.Time.Format ( formatTime, parseTime ) import System.Locale ( defaultTimeLocale ) @@ -32,7 +33,7 @@ xp_date = from_date = formatTime defaultTimeLocale format --- | Parse a team_id. This *should* just be an 'Int', but TSN is doing +-- | Parse a team_id. This /should/ just be an 'Int', but TSN is doing -- something weird. First of all, player IDs do look like normal -- 'Int's. But the team IDs are all stuck in the triple digits, and -- double-digit team IDs appear to be padded to three characters diff --git a/src/TSN/XmlImport.hs b/src/TSN/XmlImport.hs index 4300e87..022ddad 100644 --- a/src/TSN/XmlImport.hs +++ b/src/TSN/XmlImport.hs @@ -1,6 +1,8 @@ {-# LANGUAGE FlexibleContexts #-} {-# LANGUAGE GADTs #-} +-- | Definition of the XmlImport class. +-- module TSN.XmlImport ( XmlImport(..) ) where @@ -14,6 +16,20 @@ import Database.Groundhog.Core ( PersistBackend, PersistEntity ) import Xml ( FromXml(..) ) +-- | In Groundhog, there is a typeclass of things you can insert into +-- the database. What we usually have, though, is an XML +-- representation of something that has a Groundhog analogue that we +-- could insert into the database. It would be real nice if we could +-- just insert the XML thing and not have to convert back and +-- forth. That's what the 'XmlImport' class lets you do. +-- +-- Moreover, there is a contraint on the class that the type must +-- also be a member of the 'FromXml' class. This allows us to define +-- default implementations of \"insert me\" generically. Given any +-- XML thing that can be converted to a database thing, we just do +-- the conversion and then insert normally (however Groundhog would +-- do it). +-- class (FromXml a, PersistEntity (Db a)) => XmlImport a where -- | This is similar to the signature for Groundhog's 'insert' -- function, except the 'AutoKey' we return is for our 'Db'