Diagrams.Backend.PGF.CmdLine

Convenient creation of command-line-driven executables for rendering diagrams using the PGF backend.

General form of main

The mainWith method unifies all of the other forms of main and is now the recommended way to build a command-line diagrams program. It works as a direct replacement for defaultMain or multiMain as well as allowing more general arguments. For example, given a function that produces a diagram when given an Int and a Colour Double, mainWith will produce a program that looks for additional number and color arguments.

... definitions ...
f :: Int -> Colour Double -> Diagram PGF
f i c = ...

main = mainWith f

We can run this program as follows:

$ ghc --make mydiagram

# output image.tex built by `f 20 red`
$ ./MyDiagram -o image.tex -w 200 20 red

mainWith :: (Mainable d, Parseable (MainOpts d)) => d -> IO ()

Main entry point for command-line diagram creation. This is the method that users will call from their program main. For instance an expected user program would take the following form.

import Diagrams.Prelude
import Diagrams.Backend.TheBestBackend.CmdLine

d :: Diagram B R2
d = ...

main = mainWith d

Most backends should be able to use the default implementation. A different implementation should be used to handle more complex interactions with the user.

Supported forms of main

defaultMain :: Diagram PGF -> IO ()

This is the simplest way to render diagrams, and is intended to be used like so:

... definitions ...

main = defaultMain myDiagram

Compiling this file will result in an executable which takes various command-line options for setting the size, output file, and so on, and renders myDiagram with the specified options.

Pass --help to the generated executable to see all available options. Currently it looks something like

mydiagram

Usage: mydiagram [-?|--help] [-w|--width WIDTH] [-h|--height HEIGHT]
                 [-o|--output OUTPUT] [-f|--format FORMAT] [-a|--standalone]
                 [-r|--readable] [-l|--loop] [-s|--src ARG]
                 [-i|--interval INTERVAL]
  Command-line diagram generation.

Available options:
  -?,--help                Show this help text
  -w,--width WIDTH         Desired WIDTH of the output image
  -h,--height HEIGHT       Desired HEIGHT of the output image
  -o,--output OUTPUT       OUTPUT file
  -f,--format FORMAT       l for LaTeX, c for ConTeXt, p for plain
                           TeX (default: LaTeX)
  -a,--standalone          Produce standalone .tex output
  -r,--readable            Indent lines
  -l,--loop                Run in a self-recompiling loop
  -s,--src ARG             Source file to watch
  -i,--interval INTERVAL   When running in a loop, check for changes every
                           INTERVAL seconds.

For example, a common scenario is

$ ghc --make mydiagram

  # output image.tex with a width of 400bp (and auto-determined height)
  # (bp = big point = 1px at 72dpi)
$ ./mydiagram -o image.tex -w 400

mainWithSurf :: Surface -> Diagram PGF -> IO ()

Allows you to pick a surface the diagram will be rendered with. (This

onlineMain :: OnlineTex (Diagram PGF) -> IO ()

Same as defaultMain but takes an online pgf diagram.

onlineMainWithSurf :: Surface -> OnlineTex (Diagram PGF) -> IO ()

Same as mainWithSurf but takes an online pgf diagram.

multiMain :: [(String, Diagram PGF)] -> IO ()

multiMain is like defaultMain, except instead of a single diagram it takes a list of diagrams paired with names as input. The generated executable then takes a --selection option specifying the name of the diagram that should be rendered. The list of available diagrams may also be printed by passing the option --list.

Example usage:

$ ghc --make MultiTest
[1 of 1] Compiling Main             ( MultiTest.hs, MultiTest.o )
Linking MultiTest ...
$ ./MultiTest --list
Available diagrams:
  foo bar
$ ./MultiTest --selection bar -o Bar.tex -w 200

module Diagrams.Backend.PGF