pandoc-plot-0.9.2.0: A Pandoc filter to include figures generated from code blocks using your plotting toolkit of choice.

Copyright(c) Laurent P René de Cotret 2020
LicenseGNU GPL, version 2 or above
Maintainerlaurent.decotret@outlook.com
Stabilityunstable
Portabilityportable
Safe HaskellNone
LanguageHaskell2010

Text.Pandoc.Filter.Plot

Contents

Description

This module defines a Pandoc filter plotTransform 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:

  • matplotlib for matplotlib-based Python plots;
  • plotly_python for Plotly-based Python plots;
  • plotly_r for Plotly-based R plots;
  • matlabplot for MATLAB plots;
  • mathplot for Mathematica plots;
  • octaveplot for GNU Octave plots;
  • ggplot2 for ggplot2-based R plots;
  • gnuplot for gnuplot plots;
  • graphviz for Graphviz graphs;
  • bokeh for Bokeh-based Python plots;
  • plotsjl for Plots.jl-based Julia plots;

For example, in Markdown:

    This is a paragraph.

    ```{.matlabplot}
    figure()
    plot([1,2,3,4,5], [1,2,3,4,5], '-k')
    ```

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 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 the Configuration type.
  • 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.

Default values for the above attributes are stored in the Configuration datatype. These can be specified in a YAML file.

Here is an example code block which will render a figure using gnuplot, in Markdown:

    ```{.gnuplot format=png caption="Sinusoidal function" source=true}
    sin(x)

    set xlabel "x"
    set ylabel "y"
    ```
Synopsis

Operating on single Pandoc blocks

makePlot Source #

Arguments

:: Walkable Block a 
=> Configuration

Configuration for default values

-> a

Input block or document

-> IO a 

Highest-level function that can be walked over a Pandoc tree. All code blocks that have the appropriate class names will be considered figures, e.g. .matplotlib.

This function can be made to operation on whole Pandoc documents. However, you should prefer the plotTransform function for whole documents, as it is optimized for parallel operations.

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.

Operating on whole Pandoc documents

plotTransform Source #

Arguments

:: Configuration

Configuration for default values

-> 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.

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.

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

data Verbosity Source #

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 # 
Instance details

Defined in Text.Pandoc.Filter.Plot.Monad.Logging

Enum Verbosity Source # 
Instance details

Defined in Text.Pandoc.Filter.Plot.Monad.Logging

Eq Verbosity Source # 
Instance details

Defined in Text.Pandoc.Filter.Plot.Monad.Logging

Ord Verbosity Source # 
Instance details

Defined in Text.Pandoc.Filter.Plot.Monad.Logging

Show Verbosity Source # 
Instance details

Defined in Text.Pandoc.Filter.Plot.Monad.Logging

IsString Verbosity Source # 
Instance details

Defined in Text.Pandoc.Filter.Plot.Monad.Logging

FromJSON Verbosity Source # 
Instance details

Defined in Text.Pandoc.Filter.Plot.Monad.Logging

data LogSink Source #

Description of the possible ways to sink log messages.

Constructors

StdErr

Standard error stream.

LogFile FilePath

Appended to file.

Instances
Eq LogSink Source # 
Instance details

Defined in Text.Pandoc.Filter.Plot.Monad.Logging

Methods

(==) :: LogSink -> LogSink -> Bool #

(/=) :: LogSink -> LogSink -> Bool #

Show LogSink Source # 
Instance details

Defined in Text.Pandoc.Filter.Plot.Monad.Logging

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

PDF

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.

Instances
Bounded SaveFormat Source # 
Instance details

Defined in Text.Pandoc.Filter.Plot.Monad.Types

Enum SaveFormat Source # 
Instance details

Defined in Text.Pandoc.Filter.Plot.Monad.Types

Eq SaveFormat Source # 
Instance details

Defined in Text.Pandoc.Filter.Plot.Monad.Types

Show SaveFormat Source # 
Instance details

Defined in Text.Pandoc.Filter.Plot.Monad.Types

IsString SaveFormat Source # 
Instance details

Defined in Text.Pandoc.Filter.Plot.Monad.Types

Generic SaveFormat Source # 
Instance details

Defined in Text.Pandoc.Filter.Plot.Monad.Types

Associated Types

type Rep SaveFormat :: Type -> Type #

ToJSON SaveFormat Source # 
Instance details

Defined in Text.Pandoc.Filter.Plot.Monad.Types

FromJSON SaveFormat Source # 
Instance details

Defined in Text.Pandoc.Filter.Plot.Monad.Types

type Rep SaveFormat Source # 
Instance details

Defined in Text.Pandoc.Filter.Plot.Monad.Types

type Rep SaveFormat = D1 (MetaData "SaveFormat" "Text.Pandoc.Filter.Plot.Monad.Types" "pandoc-plot-0.9.2.0-JEBP1T4NDZR3B9zlfudzYB" False) (((C1 (MetaCons "PNG" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "PDF" PrefixI False) (U1 :: Type -> Type)) :+: (C1 (MetaCons "SVG" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "JPG" PrefixI False) (U1 :: Type -> Type))) :+: ((C1 (MetaCons "EPS" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "GIF" PrefixI False) (U1 :: Type -> Type)) :+: (C1 (MetaCons "TIF" PrefixI False) (U1 :: Type -> Type) :+: (C1 (MetaCons "WEBP" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "HTML" PrefixI False) (U1 :: Type -> Type)))))

type Script = Text Source #

Source context for plotting scripts

Determining available plotting toolkits

data Toolkit Source #

Enumeration of supported toolkits

Instances
Bounded Toolkit Source # 
Instance details

Defined in Text.Pandoc.Filter.Plot.Monad.Types

Enum Toolkit Source # 
Instance details

Defined in Text.Pandoc.Filter.Plot.Monad.Types

Eq Toolkit Source # 
Instance details

Defined in Text.Pandoc.Filter.Plot.Monad.Types

Methods

(==) :: Toolkit -> Toolkit -> Bool #

(/=) :: Toolkit -> Toolkit -> Bool #

Show Toolkit Source #

This instance should only be used to display toolkit names

Instance details

Defined in Text.Pandoc.Filter.Plot.Monad.Types

Generic Toolkit Source # 
Instance details

Defined in Text.Pandoc.Filter.Plot.Monad.Types

Associated Types

type Rep Toolkit :: Type -> Type #

Methods

from :: Toolkit -> Rep Toolkit x #

to :: Rep Toolkit x -> Toolkit #

type Rep Toolkit Source # 
Instance details

Defined in Text.Pandoc.Filter.Plot.Monad.Types

type Rep Toolkit = D1 (MetaData "Toolkit" "Text.Pandoc.Filter.Plot.Monad.Types" "pandoc-plot-0.9.2.0-JEBP1T4NDZR3B9zlfudzYB" False) (((C1 (MetaCons "Matplotlib" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "Matlab" PrefixI False) (U1 :: Type -> Type)) :+: (C1 (MetaCons "PlotlyPython" PrefixI False) (U1 :: Type -> Type) :+: (C1 (MetaCons "PlotlyR" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "Mathematica" PrefixI False) (U1 :: Type -> Type)))) :+: ((C1 (MetaCons "Octave" PrefixI False) (U1 :: Type -> Type) :+: (C1 (MetaCons "GGPlot2" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "GNUPlot" PrefixI False) (U1 :: Type -> Type))) :+: (C1 (MetaCons "Graphviz" PrefixI False) (U1 :: Type -> Type) :+: (C1 (MetaCons "Bokeh" PrefixI False) (U1 :: Type -> Type) :+: C1 (MetaCons "Plotsjl" PrefixI False) (U1 :: Type -> Type)))))

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

toolkits :: [Toolkit] Source #

List of supported toolkits.

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 testing and internal purposes ONLY

Running the PlotM monad

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.

makeEither :: Block -> PlotM (Either PandocPlotError Block) Source #

Try to process the block with `pandoc-plot`, documenting the error.

type PlotM a = StateT PlotState (ReaderT RuntimeEnv IO) a Source #

pandoc-plot monad

runPlotM :: Configuration -> PlotM a -> IO a Source #

Evaluate a PlotM action.

Code block parameters

inclusionKeys :: [InclusionKey] Source #

List of all keys related to pandoc-plot that can be specified in source material.

Utilities

extension :: SaveFormat -> String Source #

Save format file extension

readDoc :: FilePath -> IO Pandoc Source #

Read a document, guessing what extensions and reader options are appropriate. If the file cannot be read for any reason, an error is thrown.

captionReader :: Format -> Text -> Maybe [Inline] Source #

Reader a caption, based on input document format

cls :: Toolkit -> Text Source #

Class name which will trigger the filter

configurationPathMeta :: Pandoc -> Maybe FilePath Source #

Extact path to configuration from the metadata in a Pandoc document. The path to the configuration file should be under the plot-configuration key. In case there is no such metadata, return the default configuration.

For example, at the top of a markdown file:

    ---
    title: My document
    author: John Doe
    plot-configuration: pathto/file.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" ...

Since: 0.6.0.0

executable :: Toolkit -> PlotM (Maybe Executable) Source #

Path to (directory, executable) of a toolkit.

Embedding HTML content

extractPlot :: Text -> Text Source #

Extract the plot-relevant content from inside of a full HTML document. Scripts contained in the head tag are extracted, as well as the entirety of the body tag.