-- 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.7.2.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 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 -> PlotM 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 -> PlotM FilePath -- | Check if a toolkit is available, based on the current configuration toolkitAvailable :: Toolkit -> PlotM Bool -- | List of toolkits available on this machine. The executables to look -- for are taken from the configuration. availableToolkits :: Configuration -> IO [Toolkit] -- | Monadic version of availableToolkits. availableToolkitsM :: PlotM [Toolkit] -- | List of toolkits not available on this machine. The executables to -- look for are taken from the configur unavailableToolkits :: Configuration -> IO [Toolkit] -- | Monadic version of unavailableToolkits unavailableToolkitsM :: PlotM [Toolkit] -- | Internal description of all information needed to output a figure. data OutputSpec OutputSpec :: FigureSpec -> FilePath -> FilePath -> OutputSpec -- | 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 :: Text -> ScriptResult ScriptFailure :: Text -> Int -> ScriptResult ToolkitNotInstalled :: Toolkit -> ScriptResult runTempScript :: FigureSpec -> PlotM ScriptResult runScriptIfNecessary :: FigureSpec -> PlotM ScriptResult -- | Convert a FigureSpec 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 Block 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] -- | Default reader options, straight out of Text.Pandoc.Options defaultReaderOptions :: ReaderOptions -- | 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 -- 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" ...
--
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, -- as well as log files. 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 -- | 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. data Configuration Configuration :: !FilePath -> !Bool -> !Int -> !SaveFormat -> !Format -> !Verbosity -> !LogSink -> !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 -- | Level of logging verbosity. [logVerbosity] :: Configuration -> !Verbosity -- | Method of logging, i.e. printing to stderr or file. [logSink] :: Configuration -> !LogSink -- | 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 -- | pandoc-plot monad type PlotM a = ReaderT RuntimeEnv IO a data RuntimeEnv RuntimeEnv :: Configuration -> Logger -> RuntimeEnv [envConfig] :: RuntimeEnv -> Configuration [envLogger] :: RuntimeEnv -> Logger -- | Evaluate a PlotM action. runPlotM :: Configuration -> PlotM a -> IO a -- | Run a command within the PlotM monad. Stderr stream is read -- and decoded, while Stdout is ignored. Logging happens at the debug -- level. runCommand :: Text -> PlotM (ExitCode, Text) -- | Verbosity of the logger. data Verbosity -- | Log all messages, including debug messages. Debug :: Verbosity -- | Log information, warnings, and errors. Error :: Verbosity -- | Log information and warning messages. Warning :: Verbosity -- | Only log information messages. Info :: Verbosity -- | Don't log anything. Silent :: Verbosity -- | Description of the possible ways to sink log messages. data LogSink -- | Standard error stream. StdErr :: LogSink -- | Appended to file. LogFile :: FilePath -> LogSink debug :: Text -> PlotM () err :: Text -> PlotM () warning :: Text -> PlotM () info :: Text -> PlotM () -- | Lift a computation from the IO monad. liftIO :: MonadIO m => IO a -> m a -- | Retrieves the monad environment. ask :: MonadReader r m => m r -- | Retrieves a function of the current environment. asks :: MonadReader r m => (r -> a) -> m a -- | Get access to configuration within the PlotM monad. asksConfig :: (Configuration -> a) -> PlotM a -- | 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 Script = Text -- | Result of checking scripts for problems data CheckResult CheckPassed :: CheckResult CheckFailed :: Text -> 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 FigureSpec has been created, no -- configuration can overload it; hence, a FigureSpec completely -- encodes a particular figure. data FigureSpec FigureSpec :: !Toolkit -> !Text -> !Bool -> !Script -> !SaveFormat -> !FilePath -> !Int -> ![(Text, Text)] -> !Attr -> FigureSpec -- | Plotting toolkit to use for this figure. [toolkit] :: FigureSpec -> !Toolkit -- | 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 pandoc-plot 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 -- | Portable network graphics PNG :: SaveFormat -- | Portable document format PDF :: SaveFormat -- | Scalable vector graphics SVG :: SaveFormat -- | JPEG/JPG compressed image JPG :: SaveFormat -- | Encapsulated postscript EPS :: SaveFormat -- | GIF format GIF :: SaveFormat -- | Tagged image format TIF :: SaveFormat -- | WebP image format WEBP :: SaveFormat -- | Hash of the content of a FigureSpec. Note that unlike usual -- hashes, two FigureSpec with the same -- figureContentHash 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 -- | 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: -- -- -- -- 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: -- -- -- -- 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"
--   ```
--
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. .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. 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, -- as well as log files. 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 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. data Configuration Configuration :: !FilePath -> !Bool -> !Int -> !SaveFormat -> !Format -> !Verbosity -> !LogSink -> !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 -- | Level of logging verbosity. [logVerbosity] :: Configuration -> !Verbosity -- | Method of logging, i.e. printing to stderr or file. [logSink] :: Configuration -> !LogSink -- | 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 -- | Verbosity of the logger. data Verbosity -- | Log all messages, including debug messages. Debug :: Verbosity -- | Log information, warnings, and errors. Error :: Verbosity -- | Log information and warning messages. Warning :: Verbosity -- | Only log information messages. Info :: Verbosity -- | Don't log anything. Silent :: Verbosity -- | Description of the possible ways to sink log messages. data LogSink -- | Standard error stream. StdErr :: LogSink -- | Appended to file. LogFile :: FilePath -> LogSink -- | Generated figure file format supported by pandoc-plot. Note that not -- all formats are supported by all toolkits. data SaveFormat -- | Portable network graphics PNG :: SaveFormat -- | Portable document format PDF :: SaveFormat -- | Scalable vector graphics SVG :: SaveFormat -- | JPEG/JPG compressed image JPG :: SaveFormat -- | Encapsulated postscript EPS :: SaveFormat -- | GIF format GIF :: SaveFormat -- | Tagged image format TIF :: SaveFormat -- | WebP image format WEBP :: SaveFormat type Script = Text -- | 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 configur unavailableToolkits :: Configuration -> IO [Toolkit] -- | 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. make :: Block -> PlotM Block -- | Try to process the block with `pandoc-plot`, documenting the error. makeEither :: Block -> PlotM (Either PandocPlotError Block) data PandocPlotError ScriptRuntimeError :: Text -> Int -> PandocPlotError ScriptChecksFailedError :: Text -> 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 instance GHC.Show.Show Text.Pandoc.Filter.Plot.PandocPlotError