Copyright | (c) Adam Conner-Sax 2019 |
---|---|
License | BSD-3-Clause |
Maintainer | adam_conner_sax@yahoo.com |
Stability | experimental |
Safe Haskell | None |
Language | Haskell2010 |
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:
- The Knit.Effect.RandomFu effect is not imported since the names might clash with Polysemy.Random. Import either effect directly if you need it.
- You can add logging from within document creation using
logLE
. - 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.
- If you use any other effects in your polysemy stack (e.g., Random or RandomFu), you will need to interpretrun them before calling knitHtmlknitHtmls.
Synopsis
- knitHtml :: MonadIO m => Maybe Text -> [LogSeverity] -> PandocWriterConfig -> Sem (KnitEffectDocStack m) () -> m (Either PandocError Text)
- knitHtmls :: MonadIO m => Maybe Text -> [LogSeverity] -> PandocWriterConfig -> Sem (KnitEffectDocsStack m) () -> m (Either PandocError [DocWithInfo PandocInfo Text])
- liftKnit :: Member (Lift m) r => m a -> Sem r a
- knitError :: Member (Error PandocError) r => Text -> Sem r a
- type KnitEffects r = (PandocEffects r, Member UnusedId r)
- type KnitOne r = (KnitEffects r, Member ToPandoc r)
- type KnitMany r = (KnitEffects r, Member Pandocs r)
- type KnitBase m effs = (MonadIO m, Member (Lift m) effs)
- module Knit.Report.Input.Table.Colonnade
- addMarkDown :: (PandocEffects effs, Member ToPandoc effs) => Text -> Sem effs ()
- addStrictTextHtml :: (PandocEffects effs, Member ToPandoc effs) => Text -> Sem effs ()
- addLazyTextHtml :: (PandocEffects effs, Member ToPandoc effs) => Text -> Sem effs ()
- addBlaze :: (PandocEffects effs, Member ToPandoc effs) => Html -> Sem effs ()
- addLucid :: (PandocEffects effs, Member ToPandoc effs) => Html () -> Sem effs ()
- addLatex :: (PandocEffects effs, Member ToPandoc effs) => Text -> Sem effs ()
- addHvega :: (PandocEffects effs, Member ToPandoc effs, Member UnusedId effs) => Maybe Text -> Maybe Text -> VegaLite -> Sem effs Text
- module Knit.Report.Input.Visualization.Diagrams
- module Knit.Report.Output
- pandocWriterToBlazeDocument :: PandocEffects effs => PandocWriterConfig -> Sem (ToPandoc ': effs) () -> Sem effs Html
- mindocOptionsF :: WriterOptions -> WriterOptions
- writeAllPandocResultsWithInfoAsHtml :: Text -> [DocWithInfo PandocInfo Text] -> IO ()
- writePandocResultWithInfoAsHtml :: Text -> DocWithInfo PandocInfo Text -> IO ()
- data Sem (r :: [(Type -> Type) -> Type -> Type]) a
- data Lift (m :: Type -> Type) (z :: Type -> Type) a
- type Member (e :: (Type -> Type) -> Type -> Type) (r :: [(Type -> Type) -> Type -> Type]) = Member' e r
- type Pandocs = Docs PandocInfo PandocWithRequirements
- data PandocInfo = PandocInfo {}
- data ToPandoc m r
- data Requirement
- data PandocWriteFormat a where
- data PandocReadFormat a where
- newPandoc :: (PandocEffects effs, Member Pandocs effs) => PandocInfo -> Sem (ToPandoc ': effs) () -> Sem effs ()
- data DocWithInfo i a = DocWithInfo {}
- module Knit.Effect.PandocMonad
- module Knit.Effect.PandocMonad
- type LogWithPrefixesLE effs = LogWithPrefixes LogEntry effs
- data LogSeverity
- = Diagnostic
- | Info
- | Warning
- | Error
- logAll :: [LogSeverity]
- nonDiagnostic :: [LogSeverity]
- logLE :: Member (Logger LogEntry) effs => LogSeverity -> Text -> Sem effs ()
- wrapPrefix :: Member PrefixLog effs => Text -> Sem effs a -> Sem effs a
- filteredLogEntriesToIO :: MonadIO (Sem effs) => [LogSeverity] -> Sem (Logger LogEntry ': (PrefixLog ': effs)) x -> Sem effs x
- getNextUnusedId :: Member UnusedId r => Text -> Sem r Text
Knit
:: 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.
:: 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 (Lift m) r => m a -> Sem r a Source #
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 Source #
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, Member UnusedId r) Source #
Constraint alias for the effects we need when calling Knit
type KnitOne r = (KnitEffects r, Member ToPandoc r) Source #
Constraint alias for the effects we need to knit one document
type KnitMany r = (KnitEffects r, Member Pandocs r) Source #
Constraint alias for the effects we need to knit multiple documents.
type KnitBase m effs = (MonadIO m, Member (Lift m) effs) Source #
Constraints required to knit a document using effects from a base monad m.
Inputs
addMarkDown :: (PandocEffects effs, Member ToPandoc effs) => Text -> Sem effs () Source #
Add a Pandoc MarkDown fragment with default options
addStrictTextHtml :: (PandocEffects effs, Member ToPandoc effs) => Text -> Sem effs () Source #
Add Strict Text Html to current Pandoc
addLazyTextHtml :: (PandocEffects effs, Member ToPandoc effs) => Text -> Sem effs () Source #
Add Lazy Text Html to current Pandoc
addBlaze :: (PandocEffects effs, Member ToPandoc effs) => Html -> Sem effs () Source #
Add Blaze Html
addLucid :: (PandocEffects effs, Member ToPandoc effs) => Html () -> Sem effs () Source #
Add Lucid Html
:: (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.
Output
module Knit.Report.Output
pandocWriterToBlazeDocument Source #
:: 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 Source #
options for the mindoc template
writeAllPandocResultsWithInfoAsHtml :: Text -> [DocWithInfo PandocInfo Text] -> IO () Source #
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 () Source #
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 Sem (r :: [(Type -> Type) -> Type -> Type]) a #
Instances
Monad (Sem f) | |
Functor (Sem f) | |
Member Fixpoint r => MonadFix (Sem r) | |
Defined in Polysemy.Internal | |
Member NonDet r => MonadFail (Sem r) | |
Defined in Polysemy.Internal | |
Applicative (Sem f) | |
Member (Lift IO) r => MonadIO (Sem r) | |
Defined in Polysemy.Internal | |
Member NonDet r => Alternative (Sem r) | |
Member NonDet r => MonadPlus (Sem r) | |
type Member (e :: (Type -> Type) -> Type -> Type) (r :: [(Type -> Type) -> Type -> Type]) = Member' e r #
type Pandocs = Docs PandocInfo PandocWithRequirements Source #
Type-alias for use with the Docs
effect.
data PandocInfo Source #
Type to hold info about each document that will be required for rendering and output
data Requirement Source #
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.
VegaSupport | Supported only for Html output. |
LatexSupport | Supported in Html output (via MathJax) and Latex output. |
Instances
data PandocWriteFormat a where Source #
Supported formats for writing current Pandoc
Instances
Show (PandocWriteFormat a) Source # | |
Defined in Knit.Effect.Pandoc showsPrec :: Int -> PandocWriteFormat a -> ShowS # show :: PandocWriteFormat a -> String # showList :: [PandocWriteFormat a] -> ShowS # |
data PandocReadFormat a where Source #
Supported formats for adding to current Pandoc
Instances
Show (PandocReadFormat a) Source # | |
Defined in Knit.Effect.Pandoc showsPrec :: Int -> PandocReadFormat a -> ShowS # show :: PandocReadFormat a -> String # showList :: [PandocReadFormat a] -> ShowS # |
:: (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 Source #
Data type to hold one document with info of type i
and doc of type a
.
Instances
Functor (DocWithInfo i) Source # | |
Defined in Knit.Effect.Docs fmap :: (a -> b) -> DocWithInfo i a -> DocWithInfo i b # (<$) :: a -> DocWithInfo i b -> DocWithInfo i a # | |
Foldable (DocWithInfo i) Source # | |
Defined in Knit.Effect.Docs 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) Source # | |
Defined in Knit.Effect.Docs 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 Source #
Constraint helper for LogEntry
type with prefixes
data LogSeverity Source #
Severity of message. Based on monad-logger.
Instances
logAll :: [LogSeverity] Source #
LogSeverity list used in order to output everything.
nonDiagnostic :: [LogSeverity] Source #
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 () Source #
Add one log-entry of the LogEntry
type.
wrapPrefix :: Member PrefixLog effs => Text -> Sem effs a -> Sem effs a Source #
Add a prefix for the block of code.