-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A Pandoc filter to include figures generated from code blocks using your plotting toolkit of choice.
--   
--   A Pandoc filter to include figures generated from code blocks. Keep
--   the document and code in the same location. Output is captured and
--   included as a figure.
@package pandoc-plot
@version 0.6.0.0


-- | This module re-exports internal pandoc-plot functionality. The
--   external use of content from this module is discouraged.
module Text.Pandoc.Filter.Plot.Internal

-- | Enumeration of supported toolkits
data Toolkit
Matplotlib :: Toolkit
Matlab :: Toolkit
PlotlyPython :: Toolkit
PlotlyR :: Toolkit
Mathematica :: Toolkit
Octave :: Toolkit
GGPlot2 :: Toolkit
GNUPlot :: Toolkit
Graphviz :: Toolkit
type PlotM a = ReaderT PlotEnv IO a
data PlotEnv
PlotEnv :: !Toolkit -> !Configuration -> PlotEnv
[toolkit] :: PlotEnv -> !Toolkit
[config] :: PlotEnv -> !Configuration

-- | The <tt>Configuration</tt> 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 <tt>Configuration</tt> type from
--   file using the <tt>configuration</tt> function.
--   
--   You can store the path to a configuration file in metadata under the
--   key <tt>plot-configuration</tt>. For example, in Markdown:
--   
--   <pre>
--   ---
--   title: My document
--   author: John Doe
--   plot-configuration: <i>path</i>to/file.yml
--   ---     
--   </pre>
--   
--   The same can be specified via the command line using Pandoc's
--   <tt>-M</tt> flag:
--   
--   <pre>
--   pandoc --filter pandoc-plot -M plot-configuration="path/to/file.yml" ...
--   </pre>
--   
--   In this case, use <tt>configurationPathMeta</tt> to extact the path
--   from <tt>Pandoc</tt> documents.
data Configuration
Configuration :: !FilePath -> !Bool -> !Int -> !SaveFormat -> !Format -> !Script -> !Script -> !Script -> !Script -> !Script -> !Script -> !Script -> !Script -> !Script -> !FilePath -> !FilePath -> !FilePath -> !FilePath -> !FilePath -> !FilePath -> !FilePath -> !FilePath -> !FilePath -> !Bool -> !Bool -> Configuration

-- | The default directory where figures will be saved.
[defaultDirectory] :: Configuration -> !FilePath

-- | The default behavior of whether or not to include links to source code
--   and high-res
[defaultWithSource] :: Configuration -> !Bool

-- | The default dots-per-inch value for generated figures. Renderers might
--   ignore this.
[defaultDPI] :: Configuration -> !Int

-- | The default save format of generated figures.
[defaultSaveFormat] :: Configuration -> !SaveFormat

-- | Caption format, in the same notation as Pandoc format, e.g.
--   "markdown+tex_math_dollars"
[captionFormat] :: Configuration -> !Format

-- | The default preamble script for the matplotlib toolkit.
[matplotlibPreamble] :: Configuration -> !Script

-- | The default preamble script for the Plotly/Python toolkit.
[plotlyPythonPreamble] :: Configuration -> !Script

-- | The default preamble script for the Plotly/R toolkit.
[plotlyRPreamble] :: Configuration -> !Script

-- | The default preamble script for the MATLAB toolkit.
[matlabPreamble] :: Configuration -> !Script

-- | The default preamble script for the Mathematica toolkit.
[mathematicaPreamble] :: Configuration -> !Script

-- | The default preamble script for the GNU Octave toolkit.
[octavePreamble] :: Configuration -> !Script

-- | The default preamble script for the GGPlot2 toolkit.
[ggplot2Preamble] :: Configuration -> !Script

-- | The default preamble script for the gnuplot toolkit.
[gnuplotPreamble] :: Configuration -> !Script

-- | The default preamble script for the Graphviz toolkit.
[graphvizPreamble] :: Configuration -> !Script

-- | The executable to use to generate figures using the matplotlib
--   toolkit.
[matplotlibExe] :: Configuration -> !FilePath

-- | The executable to use to generate figures using the MATLAB toolkit.
[matlabExe] :: Configuration -> !FilePath

-- | The executable to use to generate figures using the Plotly/Python
--   toolkit.
[plotlyPythonExe] :: Configuration -> !FilePath

-- | The executable to use to generate figures using the Plotly/R toolkit.
[plotlyRExe] :: Configuration -> !FilePath

-- | The executable to use to generate figures using the Mathematica
--   toolkit.
[mathematicaExe] :: Configuration -> !FilePath

-- | The executable to use to generate figures using the GNU Octave
--   toolkit.
[octaveExe] :: Configuration -> !FilePath

-- | The executable to use to generate figures using the GGPlot2 toolkit.
[ggplot2Exe] :: Configuration -> !FilePath

-- | The executable to use to generate figures using the gnuplot toolkit.
[gnuplotExe] :: Configuration -> !FilePath

-- | The executable to use to generate figures using the Graphviz toolkit.
[graphvizExe] :: Configuration -> !FilePath

-- | Whether or not to make Matplotlib figures tight by default.
[matplotlibTightBBox] :: Configuration -> !Bool

-- | Whether or not to make Matplotlib figures transparent by default.
[matplotlibTransparent] :: Configuration -> !Bool
type Script = Text

-- | Result of checking scripts for problems
data CheckResult
CheckPassed :: CheckResult
CheckFailed :: String -> CheckResult

-- | Description of any possible inclusion key, both in documents and in
--   configuration files.
data InclusionKey
DirectoryK :: InclusionKey
CaptionK :: InclusionKey
SaveFormatK :: InclusionKey
WithSourceK :: InclusionKey
CaptionFormatK :: InclusionKey
PreambleK :: InclusionKey
DpiK :: InclusionKey
ExecutableK :: InclusionKey
MatplotlibTightBBoxK :: InclusionKey
MatplotlibTransparentK :: InclusionKey

-- | Datatype containing all parameters required to run pandoc-plot.
--   
--   It is assumed that once a <tt>FigureSpec</tt> has been created, no
--   configuration can overload it; hence, a <tt>FigureSpec</tt> completely
--   encodes a particular figure.
data FigureSpec
FigureSpec :: !Text -> !Bool -> !Script -> !SaveFormat -> !FilePath -> !Int -> ![(Text, Text)] -> !Attr -> FigureSpec

-- | Figure caption.
[caption] :: FigureSpec -> !Text

-- | Append link to source code in caption.
[withSource] :: FigureSpec -> !Bool

-- | Source code for the figure.
[script] :: FigureSpec -> !Script

-- | Save format of the figure.
[saveFormat] :: FigureSpec -> !SaveFormat

-- | Directory where to save the file.
[directory] :: FigureSpec -> !FilePath

-- | Dots-per-inch of figure.
[dpi] :: FigureSpec -> !Int

-- | Renderer-specific extra attributes.
[extraAttrs] :: FigureSpec -> ![(Text, Text)]

-- | Attributes not related to <tt>pandoc-plot</tt> will be propagated.
[blockAttrs] :: FigureSpec -> !Attr

-- | Generated figure file format supported by pandoc-plot. Note that not
--   all formats are supported by all toolkits.
data SaveFormat
PNG :: SaveFormat
PDF :: SaveFormat
SVG :: SaveFormat
JPG :: SaveFormat
EPS :: SaveFormat
GIF :: SaveFormat
TIF :: SaveFormat
WEBP :: SaveFormat

-- | Hash of the content of a <tt>FigureSpec</tt>. Note that unlike usual
--   hashes, two <tt>FigureSpec</tt> with the same
--   <tt>figureContentHash</tt> does not mean that they are equal!
--   
--   Not all parts of a FigureSpec are related to running code. For
--   example, changing the caption should not require running the figure
--   again.
figureContentHash :: FigureSpec -> Int

-- | Class name which will trigger the filter
cls :: Toolkit -> Text

-- | Save format file extension
extension :: SaveFormat -> String
toolkits :: [Toolkit]

-- | List of all keys related to pandoc-plot that can be specified in
--   source material.
inclusionKeys :: [InclusionKey]
isWindows :: Bool
scriptExtension :: Toolkit -> String
comment :: Toolkit -> Text -> Text

-- | The function that maps from configuration to the preamble.
preambleSelector :: Toolkit -> Configuration -> Script

-- | Save formats supported by this renderer.
supportedSaveFormats :: Toolkit -> [SaveFormat]
scriptChecks :: Toolkit -> [Script -> CheckResult]

-- | Parse code block headers for extra attributes that are specific to
--   this renderer. By default, no extra attributes are parsed.
parseExtraAttrs :: Toolkit -> Map Text Text -> Map Text Text

-- | Generate the appropriate command-line command to generate a figure.
--   The executable will need to be found first, hence the IO monad.
command :: Toolkit -> OutputSpec -> IO Text

-- | Script fragment required to capture a figure.
capture :: Toolkit -> FigureSpec -> FilePath -> Script

-- | Path to the executable of a toolkit. If the executable can be found,
--   then it will be the full path to it.
executable :: Toolkit -> Configuration -> IO FilePath

-- | Check if a toolkit is available, based on the current configuration
toolkitAvailable :: Toolkit -> Configuration -> IO Bool

-- | List of toolkits available on this machine. The executables to look
--   for are taken from the configuration.
availableToolkits :: Configuration -> IO [Toolkit]

-- | List of toolkits not available on this machine. The executables to
--   look for are taken from the configuration.
unavailableToolkits :: Configuration -> IO [Toolkit]

-- | Internal description of all information needed to output a figure.
data OutputSpec
OutputSpec :: Configuration -> FigureSpec -> FilePath -> FilePath -> OutputSpec

-- | Pandoc-plot configuration
[oConfiguration] :: OutputSpec -> Configuration

-- | Figure spec
[oFigureSpec] :: OutputSpec -> FigureSpec

-- | Path to the script to render
[oScriptPath] :: OutputSpec -> FilePath

-- | Figure output path
[oFigurePath] :: OutputSpec -> FilePath

-- | Possible result of running a script
data ScriptResult
ScriptSuccess :: ScriptResult
ScriptChecksFailed :: String -> ScriptResult
ScriptFailure :: String -> Int -> ScriptResult
ToolkitNotInstalled :: Toolkit -> ScriptResult
runTempScript :: FigureSpec -> PlotM ScriptResult
runScriptIfNecessary :: FigureSpec -> PlotM ScriptResult

-- | Convert a <tt>FigureSpec</tt> to a Pandoc block component. Note that
--   the script to generate figure files must still be run in another
--   function.
toImage :: Format -> FigureSpec -> Block

-- | Determine which toolkit should be used to render the plot from a code
--   block, if any.
plotToolkit :: Block -> Maybe Toolkit

-- | Determine inclusion specifications from <tt>Block</tt> attributes. If
--   an environment is detected, but the save format is incompatible, an
--   error will be thrown.
parseFigureSpec :: Block -> PlotM (Maybe FigureSpec)

-- | Reader a caption, based on input document format
captionReader :: Format -> Text -> Maybe [Inline]

-- | 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.
configuration :: FilePath -> IO Configuration

-- | Extact path to configuration from the metadata in a Pandoc document.
--   The path to the configuration file should be under the
--   <tt>plot-configuration</tt> key. In case there is no such metadata,
--   return the default configuration.
--   
--   For example, at the top of a markdown file:
--   
--   <pre>
--   ---
--   title: My document
--   author: John Doe
--   plot-configuration: <i>path</i>to/file.yml
--   ---     
--   </pre>
--   
--   The same can be specified via the command line using Pandoc's
--   <tt>-M</tt> flag:
--   
--   <pre>
--   pandoc --filter pandoc-plot -M plot-configuration="path/to/file.yml" ...
--   </pre>
configurationPathMeta :: Pandoc -> Maybe FilePath

-- | Default configuration values.
defaultConfiguration :: Configuration

-- | Clean all output related to pandoc-plot. This includes output
--   directories specified in the configuration and in the document/block.
--   Note that *all* files in pandoc-plot output directories will be
--   removed.
--   
--   The cleaned directories are returned.
cleanOutputDirs :: Walkable Block b => Configuration -> b -> IO [FilePath]

-- | Read document, guessing what extensions and reader options are
--   appropriate. If the file cannot be read for any reason, an error is
--   thrown.
readDoc :: FilePath -> IO Pandoc


-- | This module defines a Pandoc filter <tt>plotTransform</tt> 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:
--   
--   <ul>
--   <li><tt>matplotlib</tt> for matplotlib-based Python plots;</li>
--   <li><tt>plotly_python</tt> for Plotly-based Python plots;</li>
--   <li><tt>matlabplot</tt> for MATLAB plots;</li>
--   <li><tt>mathplot</tt> for Mathematica plots;</li>
--   <li><tt>octaveplot</tt> for GNU Octave plots;</li>
--   <li><tt>ggplot2</tt> for ggplot2-based R plots;</li>
--   <li><tt>gnuplot</tt> for gnuplot plots;</li>
--   </ul>
--   
--   For example, in Markdown:
--   
--   <pre>
--   This is a paragraph.
--   
--   ```{.matlabplot}
--   figure()
--   plot([1,2,3,4,5], [1,2,3,4,5], '-k)
--   ```
--   </pre>
--   
--   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:
--   
--   <ul>
--   <li><tt>directory=...</tt> : Directory where to save the figure.</li>
--   <li><tt>source=true|false</tt> : Whether or not to link the source
--   code of this figure in the caption. Ideal for web pages, for example.
--   Default is false.</li>
--   <li><tt>format=...</tt>: Format of the generated figure. This can be
--   an extension or an acronym, e.g. <tt>format=PNG</tt>.</li>
--   <li><tt>caption="..."</tt>: Specify a plot caption (or alternate
--   text). Format for captions is specified in the documentation for the
--   <tt>Configuration</tt> type.</li>
--   <li><tt>dpi=...</tt>: Specify a value for figure resolution, or
--   dots-per-inch. Certain toolkits ignore this.</li>
--   <li><tt>preamble=...</tt>: Path to a file to include before the code
--   block. Ideal to avoid repetition over many figures.</li>
--   </ul>
--   
--   Default values for the above attributes are stored in the
--   <tt>Configuration</tt> datatype. These can be specified in a YAML
--   file.
--   
--   Here is an example code block which will render a figure using
--   gnuplot, in Markdown:
--   
--   <pre>
--   ```{.gnuplot format=png caption="Sinusoidal function" source=true}
--   sin(x)
--   
--   set xlabel "x"
--   set ylabel "y"
--   ```
--   </pre>
module Text.Pandoc.Filter.Plot

-- | 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. <tt>.matplotlib</tt>.
--   
--   This function can be made to operation on whole <tt>Pandoc</tt>
--   documents. However, you should prefer the <tt>plotTransform</tt>
--   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.
makePlot :: Walkable Block a => Configuration -> a -> IO a

-- | 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.
plotTransform :: Configuration -> Pandoc -> IO Pandoc

-- | Clean all output related to pandoc-plot. This includes output
--   directories specified in the configuration and in the document/block.
--   Note that *all* files in pandoc-plot output directories will be
--   removed.
--   
--   The cleaned directories are returned.
cleanOutputDirs :: Walkable Block b => Configuration -> b -> IO [FilePath]

-- | 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.
configuration :: FilePath -> IO Configuration

-- | Default configuration values.
defaultConfiguration :: Configuration

-- | The <tt>Configuration</tt> 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 <tt>Configuration</tt> type from
--   file using the <tt>configuration</tt> function.
--   
--   You can store the path to a configuration file in metadata under the
--   key <tt>plot-configuration</tt>. For example, in Markdown:
--   
--   <pre>
--   ---
--   title: My document
--   author: John Doe
--   plot-configuration: <i>path</i>to/file.yml
--   ---     
--   </pre>
--   
--   The same can be specified via the command line using Pandoc's
--   <tt>-M</tt> flag:
--   
--   <pre>
--   pandoc --filter pandoc-plot -M plot-configuration="path/to/file.yml" ...
--   </pre>
--   
--   In this case, use <tt>configurationPathMeta</tt> to extact the path
--   from <tt>Pandoc</tt> documents.
data Configuration
Configuration :: !FilePath -> !Bool -> !Int -> !SaveFormat -> !Format -> !Script -> !Script -> !Script -> !Script -> !Script -> !Script -> !Script -> !Script -> !Script -> !FilePath -> !FilePath -> !FilePath -> !FilePath -> !FilePath -> !FilePath -> !FilePath -> !FilePath -> !FilePath -> !Bool -> !Bool -> Configuration

-- | The default directory where figures will be saved.
[defaultDirectory] :: Configuration -> !FilePath

-- | The default behavior of whether or not to include links to source code
--   and high-res
[defaultWithSource] :: Configuration -> !Bool

-- | The default dots-per-inch value for generated figures. Renderers might
--   ignore this.
[defaultDPI] :: Configuration -> !Int

-- | The default save format of generated figures.
[defaultSaveFormat] :: Configuration -> !SaveFormat

-- | Caption format, in the same notation as Pandoc format, e.g.
--   "markdown+tex_math_dollars"
[captionFormat] :: Configuration -> !Format

-- | The default preamble script for the matplotlib toolkit.
[matplotlibPreamble] :: Configuration -> !Script

-- | The default preamble script for the Plotly/Python toolkit.
[plotlyPythonPreamble] :: Configuration -> !Script

-- | The default preamble script for the Plotly/R toolkit.
[plotlyRPreamble] :: Configuration -> !Script

-- | The default preamble script for the MATLAB toolkit.
[matlabPreamble] :: Configuration -> !Script

-- | The default preamble script for the Mathematica toolkit.
[mathematicaPreamble] :: Configuration -> !Script

-- | The default preamble script for the GNU Octave toolkit.
[octavePreamble] :: Configuration -> !Script

-- | The default preamble script for the GGPlot2 toolkit.
[ggplot2Preamble] :: Configuration -> !Script

-- | The default preamble script for the gnuplot toolkit.
[gnuplotPreamble] :: Configuration -> !Script

-- | The default preamble script for the Graphviz toolkit.
[graphvizPreamble] :: Configuration -> !Script

-- | The executable to use to generate figures using the matplotlib
--   toolkit.
[matplotlibExe] :: Configuration -> !FilePath

-- | The executable to use to generate figures using the MATLAB toolkit.
[matlabExe] :: Configuration -> !FilePath

-- | The executable to use to generate figures using the Plotly/Python
--   toolkit.
[plotlyPythonExe] :: Configuration -> !FilePath

-- | The executable to use to generate figures using the Plotly/R toolkit.
[plotlyRExe] :: Configuration -> !FilePath

-- | The executable to use to generate figures using the Mathematica
--   toolkit.
[mathematicaExe] :: Configuration -> !FilePath

-- | The executable to use to generate figures using the GNU Octave
--   toolkit.
[octaveExe] :: Configuration -> !FilePath

-- | The executable to use to generate figures using the GGPlot2 toolkit.
[ggplot2Exe] :: Configuration -> !FilePath

-- | The executable to use to generate figures using the gnuplot toolkit.
[gnuplotExe] :: Configuration -> !FilePath

-- | The executable to use to generate figures using the Graphviz toolkit.
[graphvizExe] :: Configuration -> !FilePath

-- | Whether or not to make Matplotlib figures tight by default.
[matplotlibTightBBox] :: Configuration -> !Bool

-- | Whether or not to make Matplotlib figures transparent by default.
[matplotlibTransparent] :: Configuration -> !Bool

-- | Generated figure file format supported by pandoc-plot. Note that not
--   all formats are supported by all toolkits.
data SaveFormat
PNG :: SaveFormat
PDF :: SaveFormat
SVG :: SaveFormat
JPG :: SaveFormat
EPS :: SaveFormat
GIF :: SaveFormat
TIF :: SaveFormat
WEBP :: SaveFormat
type Script = Text

-- | Force to use a particular toolkit to render appropriate code blocks.
--   
--   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.
make :: Toolkit -> Configuration -> Block -> IO Block
make' :: Toolkit -> Configuration -> Block -> IO (Either PandocPlotError Block)
data PandocPlotError
ScriptRuntimeError :: String -> Int -> PandocPlotError
ScriptChecksFailedError :: String -> PandocPlotError
ToolkitNotInstalledError :: Toolkit -> PandocPlotError

-- | Read document, guessing what extensions and reader options are
--   appropriate. If the file cannot be read for any reason, an error is
--   thrown.
readDoc :: FilePath -> IO Pandoc

-- | List of toolkits available on this machine. The executables to look
--   for are taken from the configuration.
availableToolkits :: Configuration -> IO [Toolkit]

-- | List of toolkits not available on this machine. The executables to
--   look for are taken from the configuration.
unavailableToolkits :: Configuration -> IO [Toolkit]
instance GHC.Show.Show Text.Pandoc.Filter.Plot.PandocPlotError