@@ -5,7 +5,8 @@
55{-# LANGUAGE FlexibleContexts #-}
66
77{-
8−Copyright (C) 2016 Jesse Rosenthal <jrosenthal@jhu.edu>
8+Copyright (C) 2016-17 Jesse Rosenthal <jrosenthal@jhu.edu>
9+and John MacFarlane.
910
1011This program is free software; you can redistribute it and/or modify
1112it under the terms of the GNU General Public License as published by
@@ -24,7 +25,7 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
2425
2526{- |
2627 Module : Text.Pandoc.Class
27− Copyright : Copyright (C) 2016 Jesse Rosenthal
28+ Copyright : Copyright (C) 2016-17 Jesse Rosenthal, John MacFarlane
2829 License : GNU GPL, version 2 or above
2930
3031 Maintainer : Jesse Rosenthal <jrosenthal@jhu.edu>
@@ -122,36 +123,64 @@ import qualified Data.Map as M
122123import Text.Pandoc.Error
123124import qualified Debug.Trace
124125
126+-- | The PandocMonad typeclass contains all the potentially
127+-- IO-related functions used in pandoc's readers and writers.
128+-- Instances of this typeclass may implement these functions
129+-- in IO (as in 'PandocIO') or using an internal state that
130+-- represents a file system, time, and so on (as in 'PandocPure').
125131class (Functor m, Applicative m, Monad m, MonadError PandocError m)
126132 => PandocMonad m where
133+ -- | Lookup an environment variable.
127134 lookupEnv :: String -> m (Maybe String)
135+ -- | Get the current (UTC) time.
128136 getCurrentTime :: m UTCTime
137+ -- | Get the locale's time zone.
129138 getCurrentTimeZone :: m TimeZone
139+ -- | Return a new generator for random numbers.
130140 newStdGen :: m StdGen
141+ -- | Return a new unique integer.
131142 newUniqueHash :: m Int
143+ -- | Retrieve contents and mime type from a URL, raising
144+ -- an error on failure.
132145 openURL :: String -> m (B.ByteString, Maybe MimeType)
146+ -- | Read the lazy ByteString contents from a file path,
147+ -- raising an error on failure.
133148 readFileLazy :: FilePath -> m BL.ByteString
149+ -- | Read the strict ByteString contents from a file path,
150+ -- raising an error on failure.
134151 readFileStrict :: FilePath -> m B.ByteString
152+ -- | Read file from specified user data directory or,
153+ -- if not found there, from Cabal data directory.
135154 readDataFile :: Maybe FilePath -> FilePath -> m B.ByteString
155+ -- | Return a list of paths that match a glob, relative to
156+ -- the working directory. See 'System.FilePath.Glob' for
157+ -- the glob syntax.
136158 glob :: String -> m [FilePath]
159+ -- | Return the modification time of a file.
137160 getModificationTime :: FilePath -> m UTCTime
161+ -- | Get the value of the 'CommonState' used by all instances
162+ -- of 'PandocMonad'.
138163 getCommonState :: m CommonState
164+ -- | Set the value of the 'CommonState' used by all instances
165+ -- of 'PandocMonad'.
166+ -- | Get the value of a specific field of 'CommonState'.
139167 putCommonState :: CommonState -> m ()
140−
168+ -- | Get the value of a specific field of 'CommonState'.
141169 getsCommonState :: (CommonState -> a) -> m a
142170 getsCommonState f = f <$> getCommonState
143−
171+ -- | Modify the 'CommonState'.
144172 modifyCommonState :: (CommonState -> CommonState) -> m ()
145173 modifyCommonState f = getCommonState >>= putCommonState . f
146−
174+ -- Output a log message.
175+ logOutput :: LogMessage -> m ()
176+ -- Output a debug message to sterr, using 'Debug.Trace.trace'.
177+ -- Note: this writes to stderr even in pure instances.
147178 trace :: String -> m ()
148179 trace msg = do
149180 tracing <- getsCommonState stTrace
150181 when tracing $ Debug.Trace.trace ("[trace] " ++ msg) (return ())
151182
152− logOutput :: LogMessage -> m ()
153−
154−-- Functions defined for all PandocMonad instances
183+-- * Functions defined for all PandocMonad instances
155184
156185setVerbosity :: PandocMonad m => Verbosity -> m ()
157186setVerbosity verbosity =
@@ -194,10 +223,10 @@ setResourcePath ps = modifyCommonState $ \st -> st{stResourcePath = ps}
194223getResourcePath :: PandocMonad m => m [FilePath]
195224getResourcePath = getsCommonState stResourcePath
196225
197−getPOSIXTime :: (PandocMonad m) => m POSIXTime
226+getPOSIXTime :: PandocMonad m => m POSIXTime
198227getPOSIXTime = utcTimeToPOSIXSeconds <$> getCurrentTime
199228
200−getZonedTime :: (PandocMonad m) => m ZonedTime
229+getZonedTime :: PandocMonad m => m ZonedTime
201230getZonedTime = do
202231 t <- getCurrentTime
203232 tz <- getCurrentTimeZone