| Copyright | (c) Laurent P René de Cotret 2019 - 2021 |
|---|---|
| License | GNU GPL, version 2 or above |
| Maintainer | laurent.decotret@outlook.com |
| Stability | unstable |
| Portability | portable |
| Safe Haskell | None |
| Language | Haskell2010 |
Text.Pandoc.Filter.Plot
Description
This module defines a Pandoc filter plotFilter and related functions
that can be used to walk over a Pandoc document and generate figures from
code blocks, using a multitude of plotting toolkits.
The syntax for code blocks is simple. Code blocks with the appropriate class
attribute will trigger the filter, e.g. matplotlib for matplotlib-based Python plots.
Here is an example, in Markdown, for a plot in MATLAB:
This is a paragraph.
```{.matlabplot}
figure()
plot([1,2,3,4,5], [1,2,3,4,5], '-k')
```
or a using GNUPlot:
```{.gnuplot format=png caption="Sinusoidal function" source=true}
sin(x)
set xlabel "x"
set ylabel "y"
```
The code block will be reworked into a script and the output figure will be captured. Optionally, the source code used to generate the figure will be linked in the caption.
Here are some of the possible attributes what pandoc-plot understands for ALL toolkits:
directory=...: Directory where to save the figure. This path should be specified with respect to the current working directory, and not with respect to the document.source=true|false: Whether or not to link the source code of this figure in the caption. Ideal for web pages, for example. Default is false.format=...: Format of the generated figure. This can be an extension or an acronym, e.g.format=PNG.caption="...": Specify a plot caption (or alternate text). Format for captions is specified in the documentation for theConfigurationtype.dpi=...: Specify a value for figure resolution, or dots-per-inch. Certain toolkits ignore this.dependencies=[...]: Specify files/directories on which a figure depends, e.g. data file. Figures will be re-rendered if one of those file/directory changes. These paths should be specified with respect to the current working directory, and not with respect to the document.preamble=...: Path to a file to include before the code block. Ideal to avoid repetition over many figures.file=...: Path to a file from which to read the content of the figure. The content of the code block will be ignored. This path should be specified with respect to the current working directory, and not with respect to the document.
All attributes are described in the online documentation, linked on the home page.
Synopsis
- plotFilter :: Configuration -> Maybe Format -> Pandoc -> IO Pandoc
- plotTransform :: Configuration -> Pandoc -> IO Pandoc
- cleanOutputDirs :: Walkable Block b => Configuration -> b -> IO [FilePath]
- configuration :: FilePath -> IO Configuration
- defaultConfiguration :: Configuration
- data Configuration = Configuration {
- defaultDirectory :: !FilePath
- defaultWithSource :: !Bool
- defaultDPI :: !Int
- defaultSaveFormat :: !SaveFormat
- defaultDependencies :: ![FilePath]
- captionFormat :: !Format
- sourceCodeLabel :: !Text
- strictMode :: !Bool
- logVerbosity :: !Verbosity
- logSink :: !LogSink
- matplotlibPreamble :: !Script
- plotlyPythonPreamble :: !Script
- plotlyRPreamble :: !Script
- matlabPreamble :: !Script
- mathematicaPreamble :: !Script
- octavePreamble :: !Script
- ggplot2Preamble :: !Script
- gnuplotPreamble :: !Script
- graphvizPreamble :: !Script
- bokehPreamble :: !Script
- plotsjlPreamble :: !Script
- plantumlPreamble :: !Script
- matplotlibExe :: !FilePath
- matlabExe :: !FilePath
- plotlyPythonExe :: !FilePath
- plotlyRExe :: !FilePath
- mathematicaExe :: !FilePath
- octaveExe :: !FilePath
- ggplot2Exe :: !FilePath
- gnuplotExe :: !FilePath
- graphvizExe :: !FilePath
- bokehExe :: !FilePath
- plotsjlExe :: !FilePath
- plantumlExe :: !FilePath
- matplotlibCmdArgs :: !Text
- matlabCmdArgs :: !Text
- plotlyPythonCmdArgs :: !Text
- plotlyRCmdArgs :: !Text
- mathematicaCmdArgs :: !Text
- octaveCmdArgs :: !Text
- ggplot2CmdArgs :: !Text
- gnuplotCmdArgs :: !Text
- graphvizCmdArgs :: !Text
- bokehCmdArgs :: !Text
- plotsjlCmdArgs :: !Text
- plantumlCmdArgs :: !Text
- matplotlibTightBBox :: !Bool
- matplotlibTransparent :: !Bool
- data Verbosity
- data LogSink
- data SaveFormat
- type Script = Text
- data Toolkit
- = Matplotlib
- | Matlab
- | PlotlyPython
- | PlotlyR
- | Mathematica
- | Octave
- | GGPlot2
- | GNUPlot
- | Graphviz
- | Bokeh
- | Plotsjl
- | PlantUML
- availableToolkits :: Configuration -> IO [Toolkit]
- unavailableToolkits :: Configuration -> IO [Toolkit]
- toolkits :: [Toolkit]
- supportedSaveFormats :: Toolkit -> [SaveFormat]
- pandocPlotVersion :: Version
- make :: Block -> PlotM Block
- makeEither :: Block -> PlotM (Either PandocPlotError Block)
- data PandocPlotError
Operating on whole Pandoc documents
Arguments
| :: Configuration | Configuration for default values |
| -> Maybe Format | Final converted format, if known |
| -> Pandoc | Input document |
| -> IO Pandoc |
Walk over an entire Pandoc document, transforming appropriate code blocks into figures. This function will operate on blocks in parallel if possible.
If the target conversion format is known, then this function can provide better defaults and error messages. For example, hyperlinks to source code will only be created if the final target format supports it (e.g. HTML).
Failing to render a figure does not stop the filter, so that you may run the filter on documents without having all necessary toolkits installed. In this case, error messages are printed to stderr, and blocks are left unchanged.
Since: 1.3.0
Arguments
| :: Configuration | Configuration for default values |
| -> Pandoc | Input document |
| -> IO Pandoc |
Deprecated: plotTransform has been deprecated in favour of plotFilter, which is aware of conversion format.plotTransform will be removed in an upcoming major update.
Walk over an entire Pandoc document, transforming appropriate code blocks into figures. This function will operate on blocks in parallel if possible.
Failing to render a figure does not stop the filter, so that you may run the filter on documents without having all necessary toolkits installed. In this case, error messages are printed to stderr, and blocks are left unchanged.
__Note that this function is DEPRECATED in favour of plotFilter. It will be
removed in the next major update (v2+).__
Cleaning output directories
cleanOutputDirs :: Walkable Block b => Configuration -> b -> IO [FilePath] Source #
Clean all output related to pandoc-plot. This includes output directories specified in the configuration and in the document/block, as well as log files. Note that *all* files in pandoc-plot output directories will be removed.
The cleaned directories are returned.
Runtime configuration
configuration :: FilePath -> IO Configuration Source #
Read configuration from a YAML file. The keys are exactly the same as for code blocks.
If a key is not present, its value will be set to the default value. Parsing errors result in thrown exceptions.
defaultConfiguration :: Configuration Source #
Default configuration values.
Since: 0.5.0.0
data Configuration Source #
The Configuration type holds the default values to use
when running pandoc-plot. These values can be overridden in code blocks.
You can create an instance of the Configuration type from file using the configuration function.
You can store the path to a configuration file in metadata under the key plot-configuration. For example, in Markdown:
---
title: My document
author: John Doe
plot-configuration: pathtofile.yml
---
The same can be specified via the command line using Pandoc's -M flag:
pandoc --filter pandoc-plot -M plot-configuration="path/to/file.yml" ...
In this case, use configurationPathMeta to extact the path from Pandoc documents.
Constructors
| Configuration | |
Fields
| |
Instances
| Eq Configuration Source # | |
Defined in Text.Pandoc.Filter.Plot.Monad Methods (==) :: Configuration -> Configuration -> Bool # (/=) :: Configuration -> Configuration -> Bool # | |
| Show Configuration Source # | |
Defined in Text.Pandoc.Filter.Plot.Monad Methods showsPrec :: Int -> Configuration -> ShowS # show :: Configuration -> String # showList :: [Configuration] -> ShowS # | |
Verbosity of the logger.
Constructors
| Debug | Log all messages, including debug messages. |
| Info | Log information, warning, and error messages. |
| Warning | Log warning and error messages. |
| Error | Only log errors. |
| Silent | Don't log anything. |
Instances
| Bounded Verbosity Source # | |
| Enum Verbosity Source # | |
Defined in Text.Pandoc.Filter.Plot.Monad.Logging Methods succ :: Verbosity -> Verbosity # pred :: Verbosity -> Verbosity # fromEnum :: Verbosity -> Int # enumFrom :: Verbosity -> [Verbosity] # enumFromThen :: Verbosity -> Verbosity -> [Verbosity] # enumFromTo :: Verbosity -> Verbosity -> [Verbosity] # enumFromThenTo :: Verbosity -> Verbosity -> Verbosity -> [Verbosity] # | |
| Eq Verbosity Source # | |
| Ord Verbosity Source # | |
Defined in Text.Pandoc.Filter.Plot.Monad.Logging | |
| Show Verbosity Source # | |
| IsString Verbosity Source # | |
Defined in Text.Pandoc.Filter.Plot.Monad.Logging Methods fromString :: String -> Verbosity # | |
| FromJSON Verbosity Source # | |
Description of the possible ways to sink log messages.
data SaveFormat Source #
Generated figure file format supported by pandoc-plot. Note that not all formats are supported by all toolkits.
Constructors
| PNG | Portable network graphics |
Portable document format | |
| SVG | Scalable vector graphics |
| JPG | JPEG/JPG compressed image |
| EPS | Encapsulated postscript |
| GIF | GIF format |
| TIF | Tagged image format |
| WEBP | WebP image format |
| HTML | HTML for interactive plots. |
| LaTeX | LaTeX text and pdf graphics |
Instances
Determining available plotting toolkits
Enumeration of supported toolkits
Constructors
| Matplotlib | |
| Matlab | |
| PlotlyPython | |
| PlotlyR | |
| Mathematica | |
| Octave | |
| GGPlot2 | |
| GNUPlot | |
| Graphviz | |
| Bokeh | |
| Plotsjl | |
| PlantUML |
Instances
availableToolkits :: Configuration -> IO [Toolkit] Source #
List of toolkits available on this machine. The executables to look for are taken from the configuration.
unavailableToolkits :: Configuration -> IO [Toolkit] Source #
List of toolkits not available on this machine. The executables to look for are taken from the configur
supportedSaveFormats :: Toolkit -> [SaveFormat] Source #
Save formats supported by this renderer.
Version information
pandocPlotVersion :: Version Source #
The version of the pandoc-plot package.
Since: 0.8.0.0
For embedding, testing and internal purposes ONLY. Might change without notice.
make :: Block -> PlotM Block Source #
Try to process the block with `pandoc-plot`. If a failure happens (or the block) was not meant to become a figure, return the block as-is unless running in strict mode. In strict mode, any failure (for example, due to a missing plotting toolkit) will halt execution.
New in version 1.2.0: this function will detect nested code blocks, for example in Div blocks.
makeEither :: Block -> PlotM (Either PandocPlotError Block) Source #
Try to process the block with `pandoc-plot`, documenting the error.
This function does not transform code blocks nested in
other blocks (e.g. Divs)
data PandocPlotError Source #
Constructors
| ScriptRuntimeError Text Int | |
| ScriptChecksFailedError Text | |
| ToolkitNotInstalledError Toolkit | |
| IncompatibleSaveFormatError SaveFormat Toolkit |
Instances
| Show PandocPlotError Source # | |
Defined in Text.Pandoc.Filter.Plot Methods showsPrec :: Int -> PandocPlotError -> ShowS # show :: PandocPlotError -> String # showList :: [PandocPlotError] -> ShowS # | |