docs: add missing docs

Author: drlkf

LICENSE

@@ -15,7 +15,12 @@ author:         drlkf
 maintainer:     [email protected]
 copyright:      2024 drlkf
 license:        GPL-3
+license-file:   LICENSE
 build-type:     Simple
+tested-with:
+    GHC == 9.8
+  , GHC == 9.6
+  , GHC == 9.4
 extra-source-files:
     README.md
     CHANGELOG.md
@@ -34,14 +39,13 @@ library
       src
   ghc-options: -Wall -Wcompat -Widentities -Wincomplete-record-updates -Wincomplete-uni-patterns -Wmissing-export-lists -Wmissing-home-modules -Wpartial-fields -Wredundant-constraints
   build-depends:
-      aeson
+      aeson >=2.0 && <3
     , base >=4.7 && <5
-    , extra
-    , megaparsec
-    , parser-combinators
-    , text
-    , time
-    , uuid
+    , megaparsec >=9.0 && <10
+    , parser-combinators >=1.0 && <2
+    , text >=2.0 && <3
+    , time >=1.10 && <2
+    , uuid >=1.3 && <2
   default-language: Haskell2010
 
 test-suite megaparsec-utils-test
@@ -56,14 +60,13 @@ test-suite megaparsec-utils-test
   ghc-options: -Wall -Wcompat -Widentities -Wincomplete-record-updates -Wincomplete-uni-patterns -Wmissing-export-lists -Wmissing-home-modules -Wpartial-fields -Wredundant-constraints -threaded -rtsopts -with-rtsopts=-N
   build-depends:
       QuickCheck
-    , aeson
+    , aeson >=2.0 && <3
     , base >=4.7 && <5
-    , extra
     , hspec
-    , megaparsec
+    , megaparsec >=9.0 && <10
     , megaparsec-utils
-    , parser-combinators
-    , text
-    , time
-    , uuid
+    , parser-combinators >=1.0 && <2
+    , text >=2.0 && <3
+    , time >=1.10 && <2
+    , uuid >=1.3 && <2
   default-language: Haskell2010

megaparsec-utils.cabal

@@ -9,6 +9,10 @@ github:       drlkf/megaparsec-utils
 homepage:     https://github.com/drlkf/megaparsec-utils
 bug-reports:  https://github.com/drlkf/megaparsec-utils/issues
 category:     Parsing
+tested-with:
+  - GHC == 9.8
+  - GHC == 9.6
+  - GHC == 9.4
 
 extra-source-files:
   - README.md

package.yaml

@@ -1,7 +1,18 @@
 {-# LANGUAGE FlexibleContexts #-}
 
+{- |
+Module      : Text.Megaparsec.Time
+Description : Various parsers for types related to time.
+Copyright   : (c) drlkf, 2024
+License     : GPL-3
+Maintainer  : [email protected]
+Stability   : experimental
+-}
+
 module Text.Megaparsec.Time
-  ( dateParser
+  ( DayResult
+
+  , dateParser
   , dayParser
   , durationParser
   , gregorianDayParser
@@ -14,8 +25,8 @@ module Text.Megaparsec.Time
 import           Control.Applicative       (optional, (<|>))
 import           Control.Monad             (replicateM, void)
 import           Control.Monad.Combinators (choice, some)
+import           Data.Char                 (toLower)
 import           Data.Functor              (($>))
-import           Data.List.Extra           (lower)
 import           Data.Maybe                (fromMaybe)
 import           Data.Time                 (Day, DayOfWeek (..),
                                             NominalDiffTime, TimeOfDay (..),
@@ -26,13 +37,22 @@ import           Text.Megaparsec.Char      (char, digitChar, space, space1,
                                             string')
 import           Text.Megaparsec.Utils     (posNumParser)
 
+-- | Representation of a parser result with either a number of days relative to
+-- the current day, or a 'DayOfWeek'.
 type DayResult = Either Int DayOfWeek
 
+-- | Parse a tuple containing a day or not, and a 'TimeOfDay'.
 dateParser
   :: Ord e
   => Parsec e String (Maybe DayResult, TimeOfDay)
 dateParser = (,) <$> optional (try (dayParser <* space1)) <*> timeParser
 
+-- | Parse a day using one of the following, all case-insensitive:
+--
+--   * a short (3-letters) or long day name e.g @mon@ or @monday@
+--   * @yesterday@ or @tomorrow@
+--   * a day number relative to the current day i.e @+2@ is two days from today
+--   * an absolute number for a 'DayOfWeek', refer to its 'Num' instance for more information.
 dayParser
   :: Ord e
   => Parsec e String DayResult
@@ -43,14 +63,16 @@ dayParser = choice
   , Left  <$> (string' "tomorrow" $> 1)
   , Right <$> absoluteDay
   , Left  <$> relativeDay
-  ] where shortDay = choice $ map (ciString (lower . take 3 . show)) weekDays
-          longDay  = choice $ map (ciString (lower . show)) weekDays
+  ] where shortDay = choice $ map (ciString (fmap toLower . take 3 . show)) weekDays
+          longDay  = choice $ map (ciString (fmap toLower . show)) weekDays
           ciString f d = try (string' (f d)) $> d
           weekDays = [Monday .. Friday]
           sign = (char '-' $> negate) <|> (char '+' $> id)
           absoluteDay = toEnum . read <$> some digitChar
           relativeDay = ($) <$> sign <*> (read <$> some digitChar)
 
+-- | Parse a 'NominalDiffTime' using strings like @1h23m45s@, with all
+-- components being optional as long as one is present.
 durationParser
   :: Ord e
   => Parsec e String NominalDiffTime
@@ -60,14 +82,15 @@ durationParser = try hours <|> try minutes <|> secondsParser
           m <- fromMaybe zero <$> optional (try minutes)
           s <- fromMaybe zero <$> optional secondsParser
 
-          return $ h + m + s
+          return (h + m + s)
 
         minutes = do
           m <- minutesParser <* space
           s <- fromMaybe zero <$> optional secondsParser
 
-          return $ m + s
+          return (m + s)
 
+-- | Parse a Gregorian 'Day' from a @%d\/%m\/%Y@ format.
 gregorianDayParser
   :: Ord e
   => Parsec e String Day
@@ -76,30 +99,34 @@ gregorianDayParser = do
   parseTimeM False defaultTimeLocale "%F" s <|>
     parseTimeM False defaultTimeLocale "%d/%m/%Y" s
 
+-- | Parse a 'NominalDiffTime' from a number of hours from a string like @1h@.
 hoursParser
   :: Ord e
   => Parsec e String NominalDiffTime
 hoursParser = secondsToNominalDiffTime . (* 3600) <$> posNumParser <* char 'h'
 
+-- | Parse a 'NominalDiffTime' from a number of minutes from a string like @1m@.
 minutesParser
   :: Ord e
   => Parsec e String NominalDiffTime
 minutesParser = secondsToNominalDiffTime . (* 60) <$> posNumParser <* char 'm'
 
+-- | Parse a 'NominalDiffTime' from a number of seconds from a string like @1s@.
 secondsParser
   :: Ord e
   => Parsec e String NominalDiffTime
 secondsParser = secondsToNominalDiffTime <$> posNumParser <* optional (char 's')
 
+-- | Parse a 'TimeOfDay' from a string like @01:23@.
 timeParser
   :: Ord e
   => Parsec e String TimeOfDay
 timeParser = do
-  h <- read <$> replicateM 2 digitChar
-  void $ char ':'
+  h <- read <$> replicateM 2 digitChar <* char ':'
   m <- read <$> replicateM 2 digitChar
 
   return $ TimeOfDay h m 0
 
+-- | Zero seconds in 'NominalDiffTime'.
 zero :: NominalDiffTime
 zero = secondsToNominalDiffTime 0

src/Text/Megaparsec/Time.hs

@@ -2,6 +2,15 @@
 {-# LANGUAGE ScopedTypeVariables #-}
 {-# LANGUAGE TypeFamilies        #-}
 
+{- |
+Module      : Text.Megaparsec.Utils
+Description : Various generic parsers and combinators.
+Copyright   : (c) drlkf, 2024
+License     : GPL-3
+Maintainer  : [email protected]
+Stability   : experimental
+-}
+
 module Text.Megaparsec.Utils
   ( boolParser
   , boundedEnumShowParser
@@ -62,7 +71,7 @@ commaSeparated
   -> Parsec e String (NonEmpty a)
 commaSeparated p = (:|) <$> p <*> many (char ',' >> p)
 
--- | Parse any occurrence of a given parser. Consumes any input before occurence.
+-- | Parse any occurrence of a given parser. Consumes any input before occurrence.
 occurrence
   :: Ord e
   => Parsec e String a
@@ -94,27 +103,24 @@ posNumParser
   => Parsec e String a
 posNumParser = read <$> some digitChar
 
--- | Parse an integer, without any spaces between minus sign and digits.
+-- | Parse an integer, without any space between minus sign and digits.
 numParser
   :: Ord e
   => Parsec e String Int
 numParser = (char '-' >> negate <$> posNumParser) <|> posNumParser
 
--- | Convert a 'Parsec' parser into a 'Parser' suited for 'FromJSON' instances.
+-- | Convert a 'Parsec' parser into a 'Parser' suited for 'Data.Aeson.FromJSON'
+-- instances.
 parsecToJSONParser
   :: ShowErrorComponent e
-  -- ^ Parser name.
-  => String
-  -- ^ Parser.
-  -> Parsec e String a
-  -- ^ Input value.
-  -> Value
-  -> Parser a
+  => String            -- ^ Parser name.
+  -> Parsec e String a -- ^ Parser.
+  -> (Value -> Parser a)
 parsecToJSONParser n p =
   withText n $ either (fail . errorBundlePretty) pure . runParser p n . T.unpack
 
 -- | Convert a 'Parsec' parser into a 'ReadS' parser. Useful for defining 'Read'
--- instances with 'Megaparsec'.
+-- instances with 'Text.Megaparsec'.
 parsecToReadsPrec
   :: Parsec e String a
   -> ReadS a

src/Text/Megaparsec/Utils.hs

@@ -6,8 +6,8 @@ module Text.Megaparsec.TimeSpec
 
 import           Control.Monad        (forM_)
 import           Data.Bifunctor       (Bifunctor (first))
+import           Data.Char            (toLower)
 import           Data.Either          (isLeft)
-import           Data.List.Extra      (lower)
 import           Data.Time            (Day, DayOfWeek (..), TimeOfDay (..),
                                        defaultTimeLocale, formatTime,
                                        fromGregorian, secondsToNominalDiffTime)
@@ -92,8 +92,10 @@ spec = do
         Right (Right d)
 
       it "lowercase" . forAll (arbitrary `suchThat` weekday) $ \d ->
-        parseOrPrettyError dayParser (lower (formatTime defaultTimeLocale format d)) `shouldBe`
-        Right (Right d)
+        parseOrPrettyError
+        dayParser
+        (fmap toLower (formatTime defaultTimeLocale format d))
+        `shouldBe` Right (Right d)
 
       it "weekend" . forAll (arbitrary `suchThat` (not . weekday)) $ \d ->
         parseOrPrettyError dayParser (formatTime defaultTimeLocale format d) `shouldSatisfy`