Text.Pandoc.Class

This module defines a type class, PandocMonad, for pandoc readers and writers. A pure instance PandocPure and an impure instance PandocIO are provided. This allows users of the library to choose whether they want conversions to perform IO operations (such as reading include files or images).

Documentation

data CommonState

CommonState represents state that is used by all instances of PandocMonad. Normally users should not need to interact with it directly; instead, auxiliary functions like setVerbosity and withMediaBag should be used.

Constructors

CommonState

Fields

• stLog :: [LogMessage]

  A list of log messages in reverse order

• stUserDataDir :: Maybe FilePath

  Directory to search for data files

• stSourceURL :: Maybe Text

  Absolute URL + dir of 1st source file

• stRequestHeaders :: [(Text, Text)]

  Headers to add for HTTP requests

• stNoCheckCertificate :: Bool

  Controls whether certificate validation is disabled

• stMediaBag :: MediaBag

  Media parsed from binary containers

• stTranslations :: Maybe (Lang, Maybe Translations)

  Translations for localization

• stInputFiles :: [FilePath]

  List of input files from command line

• stOutputFile :: Maybe FilePath

  Output file from command line

• stResourcePath :: [FilePath]

  Path to search for resources like included images

• stVerbosity :: Verbosity

  Verbosity level

• stTrace :: Bool

  Controls whether tracing messages are issued.

Instances

Default CommonState

Defined in Text.Pandoc.Class.CommonState

Methods

def :: CommonState

Peekable CommonState

Defined in Text.Pandoc.Lua.Marshaling.CommonState

Methods

peek :: StackIndex -> Lua CommonState

Pushable CommonState

Defined in Text.Pandoc.Lua.Marshaling.CommonState

Methods

push :: CommonState -> Lua ()

newtype PandocIO a

Constructors

PandocIO

Fields

• unPandocIO :: ExceptT PandocError (StateT CommonState IO) a

Instances

Monad PandocIO

Defined in Text.Pandoc.Class.PandocIO

Methods

(>>=) :: PandocIO a -> (a -> PandocIO b) -> PandocIO b

(>>) :: PandocIO a -> PandocIO b -> PandocIO b

return :: a -> PandocIO a

Functor PandocIO

Defined in Text.Pandoc.Class.PandocIO

Methods

fmap :: (a -> b) -> PandocIO a -> PandocIO b

(<$) :: a -> PandocIO b -> PandocIO a

Applicative PandocIO

Defined in Text.Pandoc.Class.PandocIO

Methods

pure :: a -> PandocIO a

(<*>) :: PandocIO (a -> b) -> PandocIO a -> PandocIO b

liftA2 :: (a -> b -> c) -> PandocIO a -> PandocIO b -> PandocIO c

(*>) :: PandocIO a -> PandocIO b -> PandocIO b

(<*) :: PandocIO a -> PandocIO b -> PandocIO a

MonadIO PandocIO

Defined in Text.Pandoc.Class.PandocIO

Methods

liftIO :: IO a -> PandocIO a

PandocMonad PandocIO

Defined in Text.Pandoc.Class.PandocIO

Methods

lookupEnv :: Text -> PandocIO (Maybe Text)

getCurrentTime :: PandocIO UTCTime

getCurrentTimeZone :: PandocIO TimeZone

newStdGen :: PandocIO StdGen

newUniqueHash :: PandocIO Int

openURL :: Text -> PandocIO (ByteString, Maybe MimeType)

readFileLazy :: FilePath -> PandocIO ByteString

readFileStrict :: FilePath -> PandocIO ByteString

glob :: String -> PandocIO [FilePath]

fileExists :: FilePath -> PandocIO Bool

getDataFileName :: FilePath -> PandocIO FilePath

getModificationTime :: FilePath -> PandocIO UTCTime

getCommonState :: PandocIO CommonState

putCommonState :: CommonState -> PandocIO ()

getsCommonState :: (CommonState -> a) -> PandocIO a

modifyCommonState :: (CommonState -> CommonState) -> PandocIO ()

logOutput :: LogMessage -> PandocIO ()

trace :: Text -> PandocIO ()

MonadError PandocError PandocIO

Defined in Text.Pandoc.Class.PandocIO

Methods

throwError :: PandocError -> PandocIO a

catchError :: PandocIO a -> (PandocError -> PandocIO a) -> PandocIO a

runIO :: PandocIO a -> IO (Either PandocError a)

Evaluate a PandocIO operation.

runIOorExplode :: PandocIO a -> IO a

Evaluate a PandocIO operation, handling any errors by exiting with an appropriate message and error status.

extractMedia :: FilePath -> Pandoc -> PandocIO Pandoc

Extract media from the mediabag into a directory.

class (Functor m, Applicative m, Monad m, MonadError PandocError m) => PandocMonad m where

The PandocMonad typeclass contains all the potentially IO-related functions used in pandoc's readers and writers. Instances of this typeclass may implement these functions in IO (as in PandocIO) or using an internal state that represents a file system, time, and so on (as in PandocPure).

Minimal complete definition

lookupEnv, getCurrentTime, getCurrentTimeZone, newStdGen, newUniqueHash, openURL, readFileLazy, readFileStrict, glob, fileExists, getDataFileName, getModificationTime, getCommonState, putCommonState, logOutput

Methods

lookupEnv :: Text -> m (Maybe Text)

Lookup an environment variable.

getCurrentTime :: m UTCTime

Get the current (UTC) time.

getCurrentTimeZone :: m TimeZone

Get the locale's time zone.

newStdGen :: m StdGen

Return a new generator for random numbers.

newUniqueHash :: m Int

Return a new unique integer.

openURL :: Text -> m (ByteString, Maybe MimeType)

Retrieve contents and mime type from a URL, raising an error on failure.

readFileLazy :: FilePath -> m ByteString

Read the lazy ByteString contents from a file path, raising an error on failure.

readFileStrict :: FilePath -> m ByteString

Read the strict ByteString contents from a file path, raising an error on failure.

glob :: String -> m [FilePath]

Return a list of paths that match a glob, relative to the working directory. See Glob for the glob syntax.

fileExists :: FilePath -> m Bool

Returns True if file exists.

getDataFileName :: FilePath -> m FilePath

Returns the path of data file.

getModificationTime :: FilePath -> m UTCTime

Return the modification time of a file.

getCommonState :: m CommonState

Get the value of the CommonState used by all instances of PandocMonad.

putCommonState :: CommonState -> m ()

Set the value of the CommonState used by all instances of PandocMonad. | Get the value of a specific field of CommonState.

getsCommonState :: (CommonState -> a) -> m a

Get the value of a specific field of CommonState.

modifyCommonState :: (CommonState -> CommonState) -> m ()

Modify the CommonState.

logOutput :: LogMessage -> m ()

Output a log message.

trace :: Text -> m ()

Output a debug message to sterr, using trace, if tracing is enabled. Note: this writes to stderr even in pure instances.

Instances

PandocMonad PandocPure

Defined in Text.Pandoc.Class.PandocPure

Methods

lookupEnv :: Text -> PandocPure (Maybe Text)

getCurrentTime :: PandocPure UTCTime

getCurrentTimeZone :: PandocPure TimeZone

newStdGen :: PandocPure StdGen

newUniqueHash :: PandocPure Int

openURL :: Text -> PandocPure (ByteString, Maybe MimeType)

readFileLazy :: FilePath -> PandocPure ByteString

readFileStrict :: FilePath -> PandocPure ByteString

glob :: String -> PandocPure [FilePath]

fileExists :: FilePath -> PandocPure Bool

getDataFileName :: FilePath -> PandocPure FilePath

getModificationTime :: FilePath -> PandocPure UTCTime

getCommonState :: PandocPure CommonState

putCommonState :: CommonState -> PandocPure ()

getsCommonState :: (CommonState -> a) -> PandocPure a

modifyCommonState :: (CommonState -> CommonState) -> PandocPure ()

logOutput :: LogMessage -> PandocPure ()

trace :: Text -> PandocPure ()

PandocMonad PandocIO

Defined in Text.Pandoc.Class.PandocIO

Methods

lookupEnv :: Text -> PandocIO (Maybe Text)

getCurrentTime :: PandocIO UTCTime

getCurrentTimeZone :: PandocIO TimeZone

newStdGen :: PandocIO StdGen

newUniqueHash :: PandocIO Int

openURL :: Text -> PandocIO (ByteString, Maybe MimeType)

readFileLazy :: FilePath -> PandocIO ByteString

readFileStrict :: FilePath -> PandocIO ByteString

glob :: String -> PandocIO [FilePath]

fileExists :: FilePath -> PandocIO Bool

getDataFileName :: FilePath -> PandocIO FilePath

getModificationTime :: FilePath -> PandocIO UTCTime

getCommonState :: PandocIO CommonState

putCommonState :: CommonState -> PandocIO ()

getsCommonState :: (CommonState -> a) -> PandocIO a

modifyCommonState :: (CommonState -> CommonState) -> PandocIO ()

logOutput :: LogMessage -> PandocIO ()

trace :: Text -> PandocIO ()

(MonadTrans t, PandocMonad m, Functor (t m), MonadError PandocError (t m), Monad (t m), Applicative (t m)) => PandocMonad (t m)

Defined in Text.Pandoc.Class.PandocMonad

Methods

lookupEnv :: Text -> t m (Maybe Text)

getCurrentTime :: t m UTCTime

getCurrentTimeZone :: t m TimeZone

newStdGen :: t m StdGen

newUniqueHash :: t m Int

openURL :: Text -> t m (ByteString, Maybe MimeType)

readFileLazy :: FilePath -> t m ByteString

readFileStrict :: FilePath -> t m ByteString

glob :: String -> t m [FilePath]

fileExists :: FilePath -> t m Bool

getDataFileName :: FilePath -> t m FilePath

getModificationTime :: FilePath -> t m UTCTime

getCommonState :: t m CommonState

putCommonState :: CommonState -> t m ()

getsCommonState :: (CommonState -> a) -> t m a

modifyCommonState :: (CommonState -> CommonState) -> t m ()

logOutput :: LogMessage -> t m ()

trace :: Text -> t m ()

PandocMonad m => PandocMonad (ParsecT s st m)

Defined in Text.Pandoc.Class.PandocMonad

Methods

lookupEnv :: Text -> ParsecT s st m (Maybe Text)

getCurrentTime :: ParsecT s st m UTCTime

getCurrentTimeZone :: ParsecT s st m TimeZone

newStdGen :: ParsecT s st m StdGen

newUniqueHash :: ParsecT s st m Int

openURL :: Text -> ParsecT s st m (ByteString, Maybe MimeType)

readFileLazy :: FilePath -> ParsecT s st m ByteString

readFileStrict :: FilePath -> ParsecT s st m ByteString

glob :: String -> ParsecT s st m [FilePath]

fileExists :: FilePath -> ParsecT s st m Bool

getDataFileName :: FilePath -> ParsecT s st m FilePath

getModificationTime :: FilePath -> ParsecT s st m UTCTime

getCommonState :: ParsecT s st m CommonState

putCommonState :: CommonState -> ParsecT s st m ()

getsCommonState :: (CommonState -> a) -> ParsecT s st m a

modifyCommonState :: (CommonState -> CommonState) -> ParsecT s st m ()

logOutput :: LogMessage -> ParsecT s st m ()

trace :: Text -> ParsecT s st m ()

getPOSIXTime :: PandocMonad m => m POSIXTime

Get the POSIX time.

getZonedTime :: PandocMonad m => m ZonedTime

Get the zoned time.

readFileFromDirs :: PandocMonad m => [FilePath] -> FilePath -> m (Maybe Text)

Read file, checking in any number of directories.

report :: PandocMonad m => LogMessage -> m ()

Log a message using logOutput. Note that logOutput is called only if the verbosity level exceeds the level of the message, but the message is added to the list of log messages that will be retrieved by getLog regardless of its verbosity level.

setTrace :: PandocMonad m => Bool -> m ()

Determine whether tracing is enabled. This affects the behavior of trace. If tracing is not enabled, trace does nothing.

setRequestHeader

Arguments

:: PandocMonad m

=> Text

Header name

-> Text

Value

-> m ()

Set request header to use in HTTP requests.

setNoCheckCertificate :: PandocMonad m => Bool -> m ()

Determine whether certificate validation is disabled

getLog :: PandocMonad m => m [LogMessage]

Get the accumulated log messages (in temporal order).

setVerbosity :: PandocMonad m => Verbosity -> m ()

Set the verbosity level.

getVerbosity :: PandocMonad m => m Verbosity

Get the verbosity level.

getMediaBag :: PandocMonad m => m MediaBag

Retrieve the media bag.

setMediaBag :: PandocMonad m => MediaBag -> m ()

Initialize the media bag.

insertMedia :: PandocMonad m => FilePath -> Maybe MimeType -> ByteString -> m ()

Insert an item into the media bag.

setUserDataDir :: PandocMonad m => Maybe FilePath -> m ()

Set the user data directory in common state.

getUserDataDir :: PandocMonad m => m (Maybe FilePath)

Get the user data directory from common state.

fetchItem :: PandocMonad m => Text -> m (ByteString, Maybe MimeType)

Fetch an image or other item from the local filesystem or the net. Returns raw content and maybe mime type.

getInputFiles :: PandocMonad m => m [FilePath]

Retrieve the input filenames.

setInputFiles :: PandocMonad m => [FilePath] -> m ()

Set the input filenames.

getOutputFile :: PandocMonad m => m (Maybe FilePath)

Retrieve the output filename.

setOutputFile :: PandocMonad m => Maybe FilePath -> m ()

Set the output filename.

setResourcePath :: PandocMonad m => [FilePath] -> m ()

Set the resource path searched by fetchItem.

getResourcePath :: PandocMonad m => m [FilePath]

Retrieve the resource path searched by fetchItem.

readDefaultDataFile :: PandocMonad m => FilePath -> m ByteString

Read file from from the default data files.

readDataFile :: PandocMonad m => FilePath -> m ByteString

Read file from user data directory or, if not found there, from the default data files.

fillMediaBag :: PandocMonad m => Pandoc -> m Pandoc

Traverse tree, filling media bag for any images that aren't already in the media bag.

toLang :: PandocMonad m => Maybe Text -> m (Maybe Lang)

Convert BCP47 string to a Lang, issuing warning if there are problems.

setTranslations :: PandocMonad m => Lang -> m ()

Select the language to use with translateTerm. Note that this does not read a translation file; that is only done the first time translateTerm is used.

translateTerm :: PandocMonad m => Term -> m Text

Get a translation from the current term map. Issue a warning if the term is not defined.

makeCanonical :: FilePath -> FilePath

Canonicalizes a file path by removing redundant . and ...

getTimestamp :: PandocMonad m => m UTCTime

Get the time from the SOURCE_DATE_EPOCH environment variable. The variable should contain a unix time stamp, the number of seconds since midnight Jan 01 1970 UTC. If the variable is not set or cannot be parsed as a unix time stamp, the current time is returned. This function is designed to make possible reproducible builds in formats that include a creation timestamp.

data PureState

The PureState contains ersatz representations of things that would normally be obtained through IO.

Constructors

PureState

Fields

• stStdGen :: StdGen
• stWord8Store :: [Word8]

  should be infinite, i.e. [1..]

• stUniqStore :: [Int]

  should be infinite and contain every element at most once, e.g. [1..]

• stEnv :: [(Text, Text)]
• stTime :: UTCTime
• stTimeZone :: TimeZone
• stReferenceDocx :: Archive
• stReferencePptx :: Archive
• stReferenceODT :: Archive
• stFiles :: FileTree
• stUserDataFiles :: FileTree
• stCabalDataFiles :: FileTree

Instances

Default PureState

Defined in Text.Pandoc.Class.PandocPure

Methods

def :: PureState

getPureState :: PandocPure PureState

Retrieve the underlying state of the PandocPure type.

getsPureState :: (PureState -> a) -> PandocPure a

Retrieve a value from the underlying state of the PandocPure type.

putPureState :: PureState -> PandocPure ()

Set a new state for the PandocPure type.

modifyPureState :: (PureState -> PureState) -> PandocPure ()

Modify the underlying state of the PandocPure type.

newtype PandocPure a

Constructors

PandocPure

Fields

• unPandocPure :: ExceptT PandocError (StateT CommonState (State PureState)) a

Instances

Monad PandocPure

Defined in Text.Pandoc.Class.PandocPure

Methods

(>>=) :: PandocPure a -> (a -> PandocPure b) -> PandocPure b

(>>) :: PandocPure a -> PandocPure b -> PandocPure b

return :: a -> PandocPure a

Functor PandocPure

Defined in Text.Pandoc.Class.PandocPure

Methods

fmap :: (a -> b) -> PandocPure a -> PandocPure b

(<$) :: a -> PandocPure b -> PandocPure a

Applicative PandocPure

Defined in Text.Pandoc.Class.PandocPure

Methods

pure :: a -> PandocPure a

(<*>) :: PandocPure (a -> b) -> PandocPure a -> PandocPure b

liftA2 :: (a -> b -> c) -> PandocPure a -> PandocPure b -> PandocPure c

(*>) :: PandocPure a -> PandocPure b -> PandocPure b

(<*) :: PandocPure a -> PandocPure b -> PandocPure a

PandocMonad PandocPure

Defined in Text.Pandoc.Class.PandocPure

Methods

lookupEnv :: Text -> PandocPure (Maybe Text)

getCurrentTime :: PandocPure UTCTime

getCurrentTimeZone :: PandocPure TimeZone

newStdGen :: PandocPure StdGen

newUniqueHash :: PandocPure Int

openURL :: Text -> PandocPure (ByteString, Maybe MimeType)

readFileLazy :: FilePath -> PandocPure ByteString

readFileStrict :: FilePath -> PandocPure ByteString

glob :: String -> PandocPure [FilePath]

fileExists :: FilePath -> PandocPure Bool

getDataFileName :: FilePath -> PandocPure FilePath

getModificationTime :: FilePath -> PandocPure UTCTime

getCommonState :: PandocPure CommonState

putCommonState :: CommonState -> PandocPure ()

getsCommonState :: (CommonState -> a) -> PandocPure a

modifyCommonState :: (CommonState -> CommonState) -> PandocPure ()

logOutput :: LogMessage -> PandocPure ()

trace :: Text -> PandocPure ()

MonadError PandocError PandocPure

Defined in Text.Pandoc.Class.PandocPure

Methods

throwError :: PandocError -> PandocPure a

catchError :: PandocPure a -> (PandocError -> PandocPure a) -> PandocPure a

data FileTree

Basis of the mock file system used by PandocPure.

Instances

Semigroup FileTree

Defined in Text.Pandoc.Class.PandocPure

Methods

(<>) :: FileTree -> FileTree -> FileTree

sconcat :: NonEmpty FileTree -> FileTree

stimes :: Integral b => b -> FileTree -> FileTree

Monoid FileTree

Defined in Text.Pandoc.Class.PandocPure

Methods

mempty :: FileTree

mappend :: FileTree -> FileTree -> FileTree

mconcat :: [FileTree] -> FileTree

data FileInfo

Captures all file-level information necessary for a PandocMonad conforming mock file system.

Constructors

FileInfo

Fields

• infoFileMTime :: UTCTime
• infoFileContents :: ByteString

addToFileTree :: FileTree -> FilePath -> IO FileTree

Add the specified file to the FileTree. If file is a directory, add its contents recursively.

insertInFileTree :: FilePath -> FileInfo -> FileTree -> FileTree

Insert an ersatz file into the FileTree.

runPure :: PandocPure a -> Either PandocError a

Run a PandocPure operation.

data Translations

Instances

Show Translations

Defined in Text.Pandoc.Translations

Methods

showsPrec :: Int -> Translations -> ShowS

show :: Translations -> String

showList :: [Translations] -> ShowS

Generic Translations

Defined in Text.Pandoc.Translations

Associated Types

type Rep Translations :: Type -> Type

Methods

from :: Translations -> Rep Translations x

to :: Rep Translations x -> Translations

Semigroup Translations

Defined in Text.Pandoc.Translations

Methods

(<>) :: Translations -> Translations -> Translations

sconcat :: NonEmpty Translations -> Translations

stimes :: Integral b => b -> Translations -> Translations

Monoid Translations

Defined in Text.Pandoc.Translations

Methods

mempty :: Translations

mappend :: Translations -> Translations -> Translations

mconcat :: [Translations] -> Translations

FromYAML Translations

Defined in Text.Pandoc.Translations

Methods

parseYAML :: Node Pos -> Parser Translations

FromJSON Translations

Defined in Text.Pandoc.Translations

Methods

parseJSON :: Value -> Parser Translations

parseJSONList :: Value -> Parser [Translations]

type Rep Translations

Defined in Text.Pandoc.Translations

type Rep Translations