| Copyright | (c) Laurent P René de Cotret 2020 |
|---|---|
| License | GNU GPL, version 2 or above |
| Maintainer | laurent.decotret@outlook.com |
| Stability | internal |
| Portability | portable |
| Safe Haskell | None |
| Language | Haskell2010 |
Text.Pandoc.Filter.Plot.Internal
Description
This module re-exports internal pandoc-plot functionality. The external use of content from this module is discouraged.
Synopsis
- scriptExtension :: Toolkit -> String
- comment :: Toolkit -> Text -> Text
- preambleSelector :: Toolkit -> Configuration -> Script
- supportedSaveFormats :: Toolkit -> [SaveFormat]
- scriptChecks :: Toolkit -> [Script -> CheckResult]
- parseExtraAttrs :: Toolkit -> Map Text Text -> Map Text Text
- command :: Toolkit -> OutputSpec -> PlotM Text
- capture :: Toolkit -> FigureSpec -> FilePath -> Script
- executable :: Toolkit -> PlotM FilePath
- toolkitAvailable :: Toolkit -> PlotM Bool
- availableToolkits :: Configuration -> IO [Toolkit]
- availableToolkitsM :: PlotM [Toolkit]
- unavailableToolkits :: Configuration -> IO [Toolkit]
- unavailableToolkitsM :: PlotM [Toolkit]
- data OutputSpec = OutputSpec {}
- data ScriptResult
- runTempScript :: FigureSpec -> PlotM ScriptResult
- runScriptIfNecessary :: FigureSpec -> PlotM ScriptResult
- toImage :: Format -> FigureSpec -> Block
- plotToolkit :: Block -> Maybe Toolkit
- parseFigureSpec :: Block -> PlotM (Maybe FigureSpec)
- captionReader :: Format -> Text -> Maybe [Inline]
- defaultReaderOptions :: ReaderOptions
- configuration :: FilePath -> IO Configuration
- configurationPathMeta :: Pandoc -> Maybe FilePath
- defaultConfiguration :: Configuration
- cleanOutputDirs :: Walkable Block b => Configuration -> b -> IO [FilePath]
- readDoc :: FilePath -> IO Pandoc
- data Configuration = Configuration {
- defaultDirectory :: !FilePath
- defaultWithSource :: !Bool
- defaultDPI :: !Int
- defaultSaveFormat :: !SaveFormat
- captionFormat :: !Format
- 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
- matplotlibExe :: !FilePath
- matlabExe :: !FilePath
- plotlyPythonExe :: !FilePath
- plotlyRExe :: !FilePath
- mathematicaExe :: !FilePath
- octaveExe :: !FilePath
- ggplot2Exe :: !FilePath
- gnuplotExe :: !FilePath
- graphvizExe :: !FilePath
- bokehExe :: !FilePath
- plotsjlExe :: !FilePath
- matplotlibTightBBox :: !Bool
- matplotlibTransparent :: !Bool
- type PlotM a = ReaderT RuntimeEnv IO a
- data RuntimeEnv = RuntimeEnv {
- envConfig :: Configuration
- envLogger :: Logger
- runPlotM :: Configuration -> PlotM a -> IO a
- runCommand :: Text -> PlotM (ExitCode, Text)
- data Verbosity
- data LogSink
- debug :: Text -> PlotM ()
- err :: Text -> PlotM ()
- warning :: Text -> PlotM ()
- info :: Text -> PlotM ()
- liftIO :: MonadIO m => IO a -> m a
- ask :: MonadReader r m => m r
- asks :: MonadReader r m => (r -> a) -> m a
- asksConfig :: (Configuration -> a) -> PlotM a
- data Toolkit
- = Matplotlib
- | Matlab
- | PlotlyPython
- | PlotlyR
- | Mathematica
- | Octave
- | GGPlot2
- | GNUPlot
- | Graphviz
- | Bokeh
- | Plotsjl
- type Script = Text
- data CheckResult
- data InclusionKey
- data FigureSpec = FigureSpec {
- toolkit :: !Toolkit
- caption :: !Text
- withSource :: !Bool
- script :: !Script
- saveFormat :: !SaveFormat
- directory :: !FilePath
- dpi :: !Int
- extraAttrs :: ![(Text, Text)]
- blockAttrs :: !Attr
- data SaveFormat
- figureContentHash :: FigureSpec -> Int
- cls :: Toolkit -> Text
- extension :: SaveFormat -> String
- toolkits :: [Toolkit]
- inclusionKeys :: [InclusionKey]
- isWindows :: Bool
Documentation
scriptExtension :: Toolkit -> String Source #
preambleSelector :: Toolkit -> Configuration -> Script Source #
The function that maps from configuration to the preamble.
supportedSaveFormats :: Toolkit -> [SaveFormat] Source #
Save formats supported by this renderer.
scriptChecks :: Toolkit -> [Script -> CheckResult] Source #
parseExtraAttrs :: Toolkit -> Map Text Text -> Map Text Text Source #
Parse code block headers for extra attributes that are specific to this renderer. By default, no extra attributes are parsed.
command :: Toolkit -> OutputSpec -> PlotM Text Source #
Generate the appropriate command-line command to generate a figure. The executable will need to be found first, hence the IO monad.
capture :: Toolkit -> FigureSpec -> FilePath -> Script Source #
Script fragment required to capture a figure.
executable :: Toolkit -> PlotM FilePath Source #
Path to the executable of a toolkit. If the executable can be found, then it will be the full path to it.
toolkitAvailable :: Toolkit -> PlotM Bool Source #
Check if a toolkit is available, based on the current configuration
availableToolkits :: Configuration -> IO [Toolkit] Source #
List of toolkits available on this machine. The executables to look for are taken from the configuration.
availableToolkitsM :: PlotM [Toolkit] Source #
Monadic version of availableToolkits.
unavailableToolkits :: Configuration -> IO [Toolkit] Source #
List of toolkits not available on this machine. The executables to look for are taken from the configur
unavailableToolkitsM :: PlotM [Toolkit] Source #
Monadic version of unavailableToolkits
data OutputSpec Source #
Internal description of all information needed to output a figure.
Constructors
| OutputSpec | |
Fields
| |
data ScriptResult Source #
Possible result of running a script
Constructors
| ScriptSuccess | |
| ScriptChecksFailed Text | |
| ScriptFailure Text Int | |
| ToolkitNotInstalled Toolkit |
Instances
| Show ScriptResult Source # | |
Defined in Text.Pandoc.Filter.Plot.Scripting Methods showsPrec :: Int -> ScriptResult -> ShowS # show :: ScriptResult -> String # showList :: [ScriptResult] -> ShowS # | |
Arguments
| :: Format | text format of the caption |
| -> FigureSpec | |
| -> Block |
Convert a FigureSpec to a Pandoc block component.
Note that the script to generate figure files must still
be run in another function.
plotToolkit :: Block -> Maybe Toolkit Source #
Determine which toolkit should be used to render the plot from a code block, if any.
parseFigureSpec :: Block -> PlotM (Maybe FigureSpec) Source #
Determine inclusion specifications from Block attributes.
If an environment is detected, but the save format is incompatible,
an error will be thrown.
captionReader :: Format -> Text -> Maybe [Inline] Source #
Reader a caption, based on input document format
defaultReaderOptions :: ReaderOptions Source #
Default reader options, straight out of Text.Pandoc.Options
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.
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
defaultConfiguration :: Configuration Source #
Default configuration values.
Since: 0.5.0.0
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.
readDoc :: FilePath -> IO Pandoc Source #
Read document, guessing what extensions and reader options are appropriate. If the file cannot be read for any reason, an error is thrown.
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 # | |
data RuntimeEnv Source #
Constructors
| RuntimeEnv | |
Fields
| |
Running external commands
runCommand :: Text -> PlotM (ExitCode, Text) Source #
Run a command within the PlotM monad. Stderr stream
is read and decoded, while Stdout is ignored.
Logging happens at the debug level.
Logging
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
| 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.
Lifting and other monadic operations
ask :: MonadReader r m => m r #
Retrieves the monad environment.
Arguments
| :: MonadReader r m | |
| => (r -> a) | The selector function to apply to the environment. |
| -> m a |
Retrieves a function of the current environment.
asksConfig :: (Configuration -> a) -> PlotM a Source #
Get access to configuration within the PlotM monad.
Base types
Enumeration of supported toolkits
Constructors
| Matplotlib | |
| Matlab | |
| PlotlyPython | |
| PlotlyR | |
| Mathematica | |
| Octave | |
| GGPlot2 | |
| GNUPlot | |
| Graphviz | |
| Bokeh | |
| Plotsjl |
Instances
data CheckResult Source #
Result of checking scripts for problems
Constructors
| CheckPassed | |
| CheckFailed Text |
Instances
| Eq CheckResult Source # | |
Defined in Text.Pandoc.Filter.Plot.Monad.Types | |
| Semigroup CheckResult Source # | |
Defined in Text.Pandoc.Filter.Plot.Monad.Types Methods (<>) :: CheckResult -> CheckResult -> CheckResult # sconcat :: NonEmpty CheckResult -> CheckResult # stimes :: Integral b => b -> CheckResult -> CheckResult # | |
| Monoid CheckResult Source # | |
Defined in Text.Pandoc.Filter.Plot.Monad.Types Methods mempty :: CheckResult # mappend :: CheckResult -> CheckResult -> CheckResult # mconcat :: [CheckResult] -> CheckResult # | |
data InclusionKey Source #
Description of any possible inclusion key, both in documents and in configuration files.
Constructors
| DirectoryK | |
| CaptionK | |
| SaveFormatK | |
| WithSourceK | |
| CaptionFormatK | |
| PreambleK | |
| DpiK | |
| ExecutableK | |
| MatplotlibTightBBoxK | |
| MatplotlibTransparentK |
Instances
| Bounded InclusionKey Source # | |
Defined in Text.Pandoc.Filter.Plot.Monad.Types | |
| Enum InclusionKey Source # | |
Defined in Text.Pandoc.Filter.Plot.Monad.Types Methods succ :: InclusionKey -> InclusionKey # pred :: InclusionKey -> InclusionKey # toEnum :: Int -> InclusionKey # fromEnum :: InclusionKey -> Int # enumFrom :: InclusionKey -> [InclusionKey] # enumFromThen :: InclusionKey -> InclusionKey -> [InclusionKey] # enumFromTo :: InclusionKey -> InclusionKey -> [InclusionKey] # enumFromThenTo :: InclusionKey -> InclusionKey -> InclusionKey -> [InclusionKey] # | |
| Eq InclusionKey Source # | |
Defined in Text.Pandoc.Filter.Plot.Monad.Types | |
| Show InclusionKey Source # | Keys that pandoc-plot will look for in code blocks. These are only exported for testing purposes. |
Defined in Text.Pandoc.Filter.Plot.Monad.Types Methods showsPrec :: Int -> InclusionKey -> ShowS # show :: InclusionKey -> String # showList :: [InclusionKey] -> ShowS # | |
data FigureSpec Source #
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.
Constructors
| FigureSpec | |
Fields
| |
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. |
Instances
figureContentHash :: FigureSpec -> Int Source #
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.
extension :: SaveFormat -> String Source #
Save format file extension
inclusionKeys :: [InclusionKey] Source #
List of all keys related to pandoc-plot that can be specified in source material.