Diagrams.Backend.PGF

A full-featured PGF backend for diagrams producing PGF code suitable for LaTeX, ConTeXt or plain TeX consumption.

To invoke the PGF backend, you have a number of options.

• You can use renderPGF or renderPGF' to render a Diagram to a ".tex" or ".pdf" file;
• You can use the most flexible renderDia function to access the resulting PGF code directly in memory as a bytestring Builder.
• Use mainWith or defaultMain to make a command line application. See CmdLine for more info.

The Surface provides the necessary information for rendering PGF code and building a PDF using "texrunner". See Surface for more info.

Rendering token & options

data PGF

This data declaration is simply used as a token to distinguish this rendering engine.

Constructors

PGF

Instances

Show PGF

TypeableFloat n => Backend PGF V2 n

TypeableFloat n => Renderable (Text n) PGF

Does not support full alignment. Text is not escaped.

TypeableFloat n => Renderable (Hbox n) PGF

RealFloat n => Renderable (DImage n Embedded) PGF

Supported: ImageRGB8. (Other types from DynamicImage will error)

RealFloat n => Renderable (DImage n External) PGF

Supported: .pdf, .jpg, .png.

TypeableFloat n => Renderable (Path V2 n) PGF

Monoid (Render PGF V2 n)

Fractional n => Default (Options PGF V2 n)

Hashable n => Hashable (Options PGF V2 n)

type V PGF = V2

type N PGF = Double

data Options PGF V2 = PGFOptions {

• _surface :: Surface
• _sizeSpec :: SizeSpec V2 n
• _readable :: Bool
• _standalone :: Bool

}

data Render PGF V2 = R (Render n)

type Result PGF V2 n = Builder

type MainOpts [(String, QDiagram PGF V2 n Any)] = (MainOpts (QDiagram PGF V2 n Any), DiagramMultiOpts)

type MainOpts (OnlineTex (QDiagram PGF V2 n Any))

type MainOpts (Surface, QDiagram PGF V2 n Any)

type MainOpts (Surface, OnlineTex (QDiagram PGF V2 n Any))

type MainOpts (QDiagram PGF V2 n Any)

type B = PGF

Rendering functions

renderPGF

Arguments

:: (TypeableFloat n, Monoid' m)

=> FilePath

path to output

-> SizeSpec V2 n

size of output

-> QDiagram PGF V2 n m

Diagram to render

-> IO ()

Render a pgf diagram and write it to the given filepath. Same as renderPGF' but uses the default options.

renderPGF' :: (TypeableFloat n, Monoid' m) => FilePath -> Options PGF V2 n -> QDiagram PGF V2 n m -> IO ()

Render a pgf diagram and write it to the given filepath. If the file has the extension .pdf, a PDF is generated in a temporary directory using options from the given surface, otherwise, the tex output is saved using the surface's TexFormat.

renderPGFSurf

Arguments

:: (TypeableFloat n, Monoid' m)

=> FilePath

path to output

-> SizeSpec V2 n

size of output

-> Surface

surface to render with

-> QDiagram PGF V2 n m

diagram to render

-> IO ()

Render a pgf diagram and write it to the given filepath. Same as renderPGF but takes a Surface.

Options

Options for changing how the diagram is rendered. Options PGF is an instance of Default:

def = PGFOptions {
  _surface    = latexSurface
  _sizeSpec   = absolute
  _readable   = True
  _standalone = False
  }

You can edit the default options using lenses.

readable :: Lens' (Options PGF V2 n) Bool

Lens onto whether the lines of the TeX output are indented.

sizeSpec :: Lens' (Options PGF V2 n) (SizeSpec V2 n)

Lens onto the SizeSpec2D.

surface :: Lens' (Options PGF V2 n) Surface

Lens onto the surface used to render.

standalone :: Lens' (Options PGF V2 n) Bool

Lens onto whether a standalone TeX document should be produced.

Surfaces

These surfaces should be suitable for basic diagrams. For more complicated options see Surface.

data Surface

Instances

Default Surface

Latex is the default surface.

Hashable Surface

type MainOpts (Surface, QDiagram PGF V2 n Any)

type MainOpts (Surface, OnlineTex (QDiagram PGF V2 n Any))

surfOnlineTex :: Surface -> OnlineTex a -> a

Get the result of an OnlineTex using the given surface.

Predefined surfaces

latexSurface :: Surface

Default surface for latex files by calling pdflatex.

Sample output

command: pdflatex

% preamble
documentclass{article}
usepackage{pgfcore}
pagenumbering{gobble}

% pageSize
pdfpagewidth=100bp
pdfpageheight=80bp
textheight=80bp
pdfhorigin=-76.6bp
pdfvorigin=-52.8bp

% beginDoc
begin{document}

<Latex pgf code>

% endDoc
end{document}

contextSurface :: Surface

Default surface for latex files by calling pdflatex.

Sample output

command: context --pipe --once

% preamble
usemodule[pgf]
setuppagenumbering[location=]

% pageSize
definepapersize[diagram][width=100bp,height=80bp]
setuppapersize[diagram][diagram]
setuplayout
  [ topspace=0bp
  , backspace=0bp
  , header=0bp
  , footer=0bp
  , width=100bp
  , height=80bp
  ]

% beginDoc
starttext

<Context pgf code>

% endDoc
stoptext

plaintexSurface :: Surface

Default surface for latex files by calling pdflatex.

Sample output

command: pdftex

% preamble
input eplain
beginpackages
usepackage{color}
endpackages
input pgfcore
deffrac2{{begingroup 2}}nopagenumbers

% pageSize
pdfpagewidth=100bp
pdfpageheight=80bp
pdfhorigin=-20bp
pdfvorigin=0bp

% beginDoc


pgf code

% endDoc
bye

Lenses

command :: Lens' Surface String

System command to call for rendering PDFs for OnlineTex.

arguments :: Lens' Surface [String]

List of arguments for the command.

preamble :: Lens' Surface String

Preamble for the tex document. This should at least import pgfcore.

Online TeX

By using OnlineTex, diagrams is able to query tex for sizes of hboxs and give them the corresponding envelopes. These can then be used as any other diagram with the correct size.

Online diagrams use the Surface to run tex in online mode and get feedback for hbox sizes. To run it you can use renderOnlinePGF, renderOnlinePGF' or onlineMain from CmdLine.

See https://github.com/diagrams/diagrams-pgf/tree/master/examples for examples.

data OnlineTex a :: * -> *

Type for dealing with Tex's pipping interface, the current streams are availble though the MonadReader instance.

Instances

Monad OnlineTex

Functor OnlineTex

Applicative OnlineTex

MonadIO OnlineTex

MonadReader TexStreams OnlineTex

type ResultOf (OnlineTex d) = IO (ResultOf d)

type Args (OnlineTex d) = (Surface, Args d)

type MainOpts (OnlineTex (QDiagram PGF V2 n Any))

type MainOpts (Surface, OnlineTex (QDiagram PGF V2 n Any))

renderOnlinePGF :: (TypeableFloat n, Monoid' m) => FilePath -> SizeSpec V2 n -> OnlineTex (QDiagram PGF V2 n m) -> IO ()

Render an online PGF diagram and save it. Same as renderOnlinePGF' using default options.

renderOnlinePGF' :: (TypeableFloat n, Monoid' m) => FilePath -> Options PGF V2 n -> OnlineTex (QDiagram PGF V2 n m) -> IO ()

Same as renderOnlinePDF but takes Options PGF.

Hbox

data Hbox n

Primitive for placing raw Tex commands in a hbox.

Instances

Fractional n => Transformable (Hbox n)

Fractional n => Renderable (Hbox n) NullBackend

TypeableFloat n => Renderable (Hbox n) PGF

type V (Hbox n) = V2

type N (Hbox n) = n

hboxOnline :: (TypeableFloat n, Renderable (Hbox n) b) => String -> OnlineTex (QDiagram b V2 n Any)

Hbox with bounding box envelope.

hboxPoint :: (OrderedField n, Typeable n, Renderable (Hbox n) b) => String -> QDiagram b V2 n Any

Raw Tex commands in a hbox with no envelope. Transformations are applied normally. This primitive ignores FontSize.

hboxSurf :: (TypeableFloat n, Renderable (Hbox n) b) => Surface -> String -> QDiagram b V2 n Any

Hbox with bounding box envelope. Note that each box requires a call to Tex. For multiple boxes consider using onlineHbox to get multiple boxes from a single call. (uses unsafePerformIO)