Knit.Report

This module re-exports the basic pieces to build reports using Pandoc as well as providing functions to do the "knitting"--produce the documents. That is, it is intended as one-stop-shopping for using this library to produce Html from various fragments which Pandoc can read.

Examples are available, and might be useful for seeing how all this works.

Notes:

1. You can add logging from within document creation using logLE.
2. The Knit.Report.Input.MarkDown.PandocMarkDown module is exported so if you want to use a different markdown flavor you may need to hide "addMarkDown" when you import this module.
3. If you use any other effects in your polysemy stack (e.g., Random or RandomFu), you will need to interpretrun them before calling knitHtmlknitHtmls.

Knit

knitHtml

Arguments

:: MonadIO m

=> Maybe Text

outer logging prefix

-> [LogSeverity]

what to output in log

-> PandocWriterConfig

configuration for the Pandoc Html Writer

-> Sem (KnitEffectDocStack m) ()

-> m (Either PandocError Text)

Create HTML Text from pandoc fragments In use, you may need a type-application to specify m. This allows use of any underlying monad to handle the Pandoc effects. NB: Resulting document is *Lazy* Text, as produced by the Blaze render function.

knitHtmls

Arguments

:: MonadIO m

=> Maybe Text

outer logging prefix

-> [LogSeverity]

what to output in log

-> PandocWriterConfig

configuration for the Pandoc Html Writer

-> Sem (KnitEffectDocsStack m) ()

-> m (Either PandocError [DocWithInfo PandocInfo Text])

Create multiple HTML docs (as Text) from the named sets of pandoc fragments. In use, you may need a type-application to specify m. This allows use of any underlying monad to handle the Pandoc effects. NB: Resulting documents are *Lazy* Text, as produced by the Blaze render function.

liftKnit :: Member (Embed m) r => m a -> Sem r a

lift an action in a base monad into a Polysemy monad. This is just a renaming for convenience.

knitError :: Member (Error PandocError) r => Text -> Sem r a

Throw an error with a specific message. This will emerge as a PandocSomeError in order to avoid complicating the error type. NB: The Member constraint is satisfied by KnitEffectStack m.

type KnitEffects r = (PandocEffects r, Members [UnusedId, Logger LogEntry, PrefixLog, Error PandocError, Embed IO] r)

Constraint alias for the effects we need (and run) when calling Knit. Anything inside a call to Knit can use any of these effects. Any other effects will need to be run before knitHtml(s)

type KnitOne r = (KnitEffects r, Member ToPandoc r)

Constraint alias for the effects we need to knit one document

type KnitMany r = (KnitEffects r, Member Pandocs r)

Constraint alias for the effects we need to knit multiple documents.

type KnitBase m effs = (MonadIO m, Member (Embed m) effs)

Constraints required to knit a document using effects from a base monad m.

Inputs

module Knit.Report.Input.Table.Colonnade

addMarkDown :: (PandocEffects effs, Member ToPandoc effs) => Text -> Sem effs ()

Add a Pandoc MarkDown fragment with default options

addStrictTextHtml :: (PandocEffects effs, Member ToPandoc effs) => Text -> Sem effs ()

Add Strict Text Html to current Pandoc

addLazyTextHtml :: (PandocEffects effs, Member ToPandoc effs) => Text -> Sem effs ()

Add Lazy Text Html to current Pandoc

addBlaze :: (PandocEffects effs, Member ToPandoc effs) => Html -> Sem effs ()

Add Blaze Html

addLucid :: (PandocEffects effs, Member ToPandoc effs) => Html () -> Sem effs ()

Add Lucid Html

addLatex :: (PandocEffects effs, Member ToPandoc effs) => Text -> Sem effs ()

Add LaTeX

addHvega

Arguments

:: (PandocEffects effs, Member ToPandoc effs, Member UnusedId effs)

=> Maybe Text

figure id, will get next unused with prefix "figure" if Nothing

-> Maybe Text

figure caption, none if Nothing

-> VegaLite

-> Sem effs Text

Add hvega (via html). Requires html since vega-lite renders using javascript.

module Knit.Report.Input.Visualization.Diagrams

Output

module Knit.Report.Output

pandocWriterToBlazeDocument

Arguments

:: PandocEffects effs

=> PandocWriterConfig

Configuration info for the Pandoc writer

-> Sem (ToPandoc ': effs) ()

Effects stack to run to get Pandoc

-> Sem effs Html

Blaze Html (in remaining effects)

Convert current Pandoc document (from the ToPandoc effect) into a Blaze Html document. Incudes support for template and template variables and changes to the default writer options.

mindocOptionsF :: WriterOptions -> WriterOptions

options for the mindoc template

writeAllPandocResultsWithInfoAsHtml :: Text -> [DocWithInfo PandocInfo Text] -> IO ()

Write each lazy text from a list of DocWithInfo to disk. File names come from the PandocInfo Directory is a function arguments. File extension is "html"

writePandocResultWithInfoAsHtml :: Text -> DocWithInfo PandocInfo Text -> IO ()

Write the Lazy Text in a DocWithInfo to disk, Name comes from the PandocInfo Directory is an argument to the function File extension is "html" Create the parent directory or directories, if necessary.

Effects

data Embed (m :: Type -> Type) (z :: Type -> Type) a

data Sem (r :: EffectRow) a

Instances

Monad (Sem f)

Defined in Polysemy.Internal

Methods

(>>=) :: Sem f a -> (a -> Sem f b) -> Sem f b

(>>) :: Sem f a -> Sem f b -> Sem f b

return :: a -> Sem f a

fail :: String -> Sem f a

Functor (Sem f)

Defined in Polysemy.Internal

Methods

fmap :: (a -> b) -> Sem f a -> Sem f b

(<$) :: a -> Sem f b -> Sem f a

Member Fixpoint r => MonadFix (Sem r)

Defined in Polysemy.Internal

Methods

mfix :: (a -> Sem r a) -> Sem r a

Member (Fail :: (Type -> Type) -> Type -> Type) r => MonadFail (Sem r)

Defined in Polysemy.Internal

Methods

fail :: String -> Sem r a

Applicative (Sem f)

Defined in Polysemy.Internal

Methods

pure :: a -> Sem f a

(<*>) :: Sem f (a -> b) -> Sem f a -> Sem f b

liftA2 :: (a -> b -> c) -> Sem f a -> Sem f b -> Sem f c

(*>) :: Sem f a -> Sem f b -> Sem f b

(<*) :: Sem f a -> Sem f b -> Sem f a

Member (Embed IO) r => MonadIO (Sem r)

Defined in Polysemy.Internal

Methods

liftIO :: IO a -> Sem r a

Member NonDet r => Alternative (Sem r)

Defined in Polysemy.Internal

Methods

empty :: Sem r a

(<|>) :: Sem r a -> Sem r a -> Sem r a

some :: Sem r a -> Sem r [a]

many :: Sem r a -> Sem r [a]

Member NonDet r => MonadPlus (Sem r)

Defined in Polysemy.Internal

Methods

mzero :: Sem r a

mplus :: Sem r a -> Sem r a -> Sem r a

type Member (e :: k) (r :: [k]) = MemberNoError e r

type Pandocs = Docs PandocInfo PandocWithRequirements

Type-alias for use with the Docs effect.

data PandocInfo

Type to hold info about each document that will be required for rendering and output

Constructors

PandocInfo

Fields

• pdiName :: Text
• pdiTemplateVars :: Map String String

data ToPandoc m r

Pandoc writer, add any read format to current doc

data Requirement

ADT to allow inputs to request support, if necessary or possible, in the output format. E.g., Latex output in Html needs MathJax. But Latex needs to nothing to output in Latex. Vega-lite needs some script headers to output in Html and can't be output in other formats. For now, we support all the things we can in any output format so this just results in a runtime test.

Constructors

VegaSupport

Supported only for Html output.

LatexSupport

Supported in Html output (via MathJax) and Latex output.

Instances

Bounded Requirement

Defined in Knit.Effect.Pandoc

Methods

minBound :: Requirement

maxBound :: Requirement

Enum Requirement

Defined in Knit.Effect.Pandoc

Methods

succ :: Requirement -> Requirement

pred :: Requirement -> Requirement

toEnum :: Int -> Requirement

fromEnum :: Requirement -> Int

enumFrom :: Requirement -> [Requirement]

enumFromThen :: Requirement -> Requirement -> [Requirement]

enumFromTo :: Requirement -> Requirement -> [Requirement]

enumFromThenTo :: Requirement -> Requirement -> Requirement -> [Requirement]

Eq Requirement

Defined in Knit.Effect.Pandoc

Methods

(==) :: Requirement -> Requirement -> Bool

(/=) :: Requirement -> Requirement -> Bool

Ord Requirement

Defined in Knit.Effect.Pandoc

Methods

compare :: Requirement -> Requirement -> Ordering

(<) :: Requirement -> Requirement -> Bool

(<=) :: Requirement -> Requirement -> Bool

(>) :: Requirement -> Requirement -> Bool

(>=) :: Requirement -> Requirement -> Bool

max :: Requirement -> Requirement -> Requirement

min :: Requirement -> Requirement -> Requirement

Show Requirement

Defined in Knit.Effect.Pandoc

Methods

showsPrec :: Int -> Requirement -> ShowS

show :: Requirement -> String

showList :: [Requirement] -> ShowS

data PandocWriteFormat a where

Supported formats for writing current Pandoc

Constructors

WriteDocX :: PandocWriteFormat ByteString

WriteMarkDown :: PandocWriteFormat Text

WriteCommonMark :: PandocWriteFormat Text

WriteRST :: PandocWriteFormat Text

WriteLaTeX :: PandocWriteFormat Text

WriteHtml5 :: PandocWriteFormat Html

WriteHtml5String :: PandocWriteFormat Text

Instances

Show (PandocWriteFormat a)

Defined in Knit.Effect.Pandoc

Methods

showsPrec :: Int -> PandocWriteFormat a -> ShowS

show :: PandocWriteFormat a -> String

showList :: [PandocWriteFormat a] -> ShowS

data PandocReadFormat a where

Supported formats for adding to current Pandoc

Constructors

ReadDocX :: PandocReadFormat ByteString

ReadMarkDown :: PandocReadFormat Text

ReadCommonMark :: PandocReadFormat Text

ReadRST :: PandocReadFormat Text

ReadLaTeX :: PandocReadFormat Text

ReadHtml :: PandocReadFormat Text

Instances

Show (PandocReadFormat a)

Defined in Knit.Effect.Pandoc

Methods

showsPrec :: Int -> PandocReadFormat a -> ShowS

show :: PandocReadFormat a -> String

showList :: [PandocReadFormat a] -> ShowS

newPandoc

Arguments

:: (PandocEffects effs, Member Pandocs effs)

=> PandocInfo

name and template variables for document

-> Sem (ToPandoc ': effs) ()

-> Sem effs ()

Add the Pandoc stored in the writer-style ToPandoc effect to the named docs collection with the given name.

data DocWithInfo i a

Data type to hold one document with info of type i and doc of type a.

Constructors

DocWithInfo

Fields

• dwiInfo :: i
• dwiDoc :: a

Instances

Functor (DocWithInfo i)

Defined in Knit.Effect.Docs

Methods

fmap :: (a -> b) -> DocWithInfo i a -> DocWithInfo i b

(<$) :: a -> DocWithInfo i b -> DocWithInfo i a

Foldable (DocWithInfo i)

Defined in Knit.Effect.Docs

Methods

fold :: Monoid m => DocWithInfo i m -> m

foldMap :: Monoid m => (a -> m) -> DocWithInfo i a -> m

foldr :: (a -> b -> b) -> b -> DocWithInfo i a -> b

foldr' :: (a -> b -> b) -> b -> DocWithInfo i a -> b

foldl :: (b -> a -> b) -> b -> DocWithInfo i a -> b

foldl' :: (b -> a -> b) -> b -> DocWithInfo i a -> b

foldr1 :: (a -> a -> a) -> DocWithInfo i a -> a

foldl1 :: (a -> a -> a) -> DocWithInfo i a -> a

toList :: DocWithInfo i a -> [a]

null :: DocWithInfo i a -> Bool

length :: DocWithInfo i a -> Int

elem :: Eq a => a -> DocWithInfo i a -> Bool

maximum :: Ord a => DocWithInfo i a -> a

minimum :: Ord a => DocWithInfo i a -> a

sum :: Num a => DocWithInfo i a -> a

product :: Num a => DocWithInfo i a -> a

Traversable (DocWithInfo i)

Defined in Knit.Effect.Docs

Methods

traverse :: Applicative f => (a -> f b) -> DocWithInfo i a -> f (DocWithInfo i b)

sequenceA :: Applicative f => DocWithInfo i (f a) -> f (DocWithInfo i a)

mapM :: Monad m => (a -> m b) -> DocWithInfo i a -> m (DocWithInfo i b)

sequence :: Monad m => DocWithInfo i (m a) -> m (DocWithInfo i a)

module Knit.Effect.PandocMonad

module Knit.Effect.PandocMonad

type LogWithPrefixesLE effs = LogWithPrefixes LogEntry effs

Constraint helper for LogEntry type with prefixes

data LogSeverity

Severity of message. Based on monad-logger.

Constructors

Diagnostic

Info

Warning

Error

Instances

Bounded LogSeverity

Defined in Knit.Effect.Logger

Methods

minBound :: LogSeverity

maxBound :: LogSeverity

Enum LogSeverity

Defined in Knit.Effect.Logger

Methods

succ :: LogSeverity -> LogSeverity

pred :: LogSeverity -> LogSeverity

toEnum :: Int -> LogSeverity

fromEnum :: LogSeverity -> Int

enumFrom :: LogSeverity -> [LogSeverity]

enumFromThen :: LogSeverity -> LogSeverity -> [LogSeverity]

enumFromTo :: LogSeverity -> LogSeverity -> [LogSeverity]

enumFromThenTo :: LogSeverity -> LogSeverity -> LogSeverity -> [LogSeverity]

Eq LogSeverity

Defined in Knit.Effect.Logger

Methods

(==) :: LogSeverity -> LogSeverity -> Bool

(/=) :: LogSeverity -> LogSeverity -> Bool

Ord LogSeverity

Defined in Knit.Effect.Logger

Methods

compare :: LogSeverity -> LogSeverity -> Ordering

(<) :: LogSeverity -> LogSeverity -> Bool

(<=) :: LogSeverity -> LogSeverity -> Bool

(>) :: LogSeverity -> LogSeverity -> Bool

(>=) :: LogSeverity -> LogSeverity -> Bool

max :: LogSeverity -> LogSeverity -> LogSeverity

min :: LogSeverity -> LogSeverity -> LogSeverity

Show LogSeverity

Defined in Knit.Effect.Logger

Methods

showsPrec :: Int -> LogSeverity -> ShowS

show :: LogSeverity -> String

showList :: [LogSeverity] -> ShowS

logAll :: [LogSeverity]

LogSeverity list used in order to output everything.

nonDiagnostic :: [LogSeverity]

LogSeverity list used to output all but Diagnostic. Diagnostic messages are sometimes useful for debugging but can get noisy depending on how you use it.

logLE :: Member (Logger LogEntry) effs => LogSeverity -> Text -> Sem effs ()

Add one log-entry of the LogEntry type.

wrapPrefix :: Member PrefixLog effs => Text -> Sem effs a -> Sem effs a

Add a prefix for the block of code.

filteredLogEntriesToIO :: MonadIO (Sem effs) => [LogSeverity] -> Sem (Logger LogEntry ': (PrefixLog ': effs)) x -> Sem effs x

Run the Logger and PrefixLog effects using the preferred handler and filter output in any Polysemy monad with IO in the union.

getNextUnusedId :: Member UnusedId r => Text -> Sem r Text

Get an unused id with prefix as specified. Useful for figures, etc.