Diagrams.Builder

Tools for dynamically building diagrams, for e.g. creating preprocessors to interpret diagrams code embedded in documents.

Building diagrams

buildDiagram

Arguments

:: (Typeable b, Typeable v, InnerSpace v, OrderedField (Scalar v), Backend b v, Show (Options b v))

=> b

Backend token

-> v

Dummy vector to fix the vector type

-> Options b v

Backend-specific options to use

-> [String]

Source code snippets. Each should be a syntactically valid Haskell module. They will be combined intelligently, i.e. not just pasted together textually but combining pragmas, imports, etc. separately.

-> String

Diagram expression to interpret

-> [String]

Extra LANGUAGE pragmas to use (NoMonomorphismRestriction is used by default.)

-> [String]

Additional imports (Diagrams.Prelude is imported by default).

-> (String -> IO (x, Maybe (Options b v -> Options b v)))

A function to decide whether a particular diagram needs to be regenerated. It will be passed the final assembled source for the diagram (but with the module name set to Main instead of something auto-generated, so that hashing the source will produce consistent results across runs). It can return some information (such as a hash of the source) via the x result, which will be passed through to the result of buildDiagram. More importantly, it decides whether the diagram should be built: a result of Just means the diagram should be built; Nothing means it should not. In the case that it should be built, it returns a function for updating the rendering options. This could be used, e.g., to request a filename based on a hash of the source.

Two standard decision functions are provided for convenience: alwaysRegenerate returns no extra information and always decides to regenerate the diagram; hashedRegenerate creates a hash of the diagram source and looks for a file with that name in a given directory.

-> IO (BuildResult b v x)

Build a diagram by writing the given source code to a temporary module and interpreting the given expression. Can return either a parse error if the source does not parse, an interpreter error, or the final result.

data BuildResult b v x

Potential results of a dynamic diagram building operation.

Constructors

ParseErr String

Parsing of the code failed.

InterpErr InterpreterError

Interpreting the code failed. See ppInterpError.

Skipped x

This diagram did not need to be regenerated.

OK x (Result b v)

A successful build, yielding a backend-specific result and some extra information.

ppInterpError :: InterpreterError -> String

Pretty-print an InterpreterError.

Regeneration decision functions

alwaysRegenerate :: String -> IO ((), Maybe (a -> a))

Convenience function suitable to be given as the final argument to buildDiagram. It implements the simple policy of always rebuilding every diagram.

hashedRegenerate

Arguments

:: (String -> a -> a)

A function for computing an update to rendering options, given a new base filename computed from a hash of the diagram source.

-> FilePath

The directory in which to look for generated files

-> String

The "source" to hash. Note that this does not actually have to be valid source code. A common trick is to concatenate the actual source code with String representations of any other information on which the diagram depends.

-> IO (String, Maybe (a -> a))

Convenience function suitable to be given as the final argument to buildDiagram. It works by hashing the given diagram source, and looking in the specified directory for any file whose base name is equal to the hash. If there is such a file, it specifies that the diagram should not be rebuilt. Otherwise, it specifies that the diagram should be rebuilt, and uses the provided function to update the rendering options based on the generated hash. (Most likely, one would want to set the requested output file to the hash followed by some extension.) It also returns the generated hash.

Interpreting diagrams

These functions constitute the internals of diagrams-builder. End users should not usually need to call them directly; use buildDiagram instead.

setDiagramImports

Arguments

:: MonadInterpreter m

=> String

Filename of the module containing the diagrams

-> [String]

Additional necessary imports. Prelude, Diagrams.Prelude, Diagrams.Core.Types, and Data.Monoid are included by default.

-> m ()

Set up the module to be interpreted, in the context of the necessary imports.

interpretDiagram

Arguments

:: forall b v . (Typeable b, Typeable v, InnerSpace v, OrderedField (Scalar v), Backend b v)

=> b

Backend token

-> v

Dummy vector to identify the vector space

-> Options b v

Rendering options

-> FilePath

Filename of the module containing the example

-> [String]

Additional imports needed

-> String

Expression of type Diagram b v to be compiled

-> IO (Either InterpreterError (Result b v))

Interpret a diagram expression based on the contents of a given source file, using some backend to produce a result.

Tools for creating standalone builder executables

data Build

Record of command-line options.

Constructors

Build

Fields

width :: Maybe Double

height :: Maybe Double

srcFile :: String

expr :: String

outFile :: String

dir :: String

Instances

Data Build

Typeable Build

defaultBuildOpts :: Build

Default command-line options record.