diagrams-cairo-1.5: Cairo backend for diagrams drawing EDSL

Copyright | (c) 2013 Diagrams-cairo team (see LICENSE)
License | BSD-style (see LICENSE)
Maintainer | diagrams-discuss@googlegroups.com
Safe Haskell | None
Language | Haskell2010

Diagrams.Backend.Cairo.CmdLine

Contents

- General form of `main`
- Supported forms of `main`
- GIF support
- Backend tokens
- Orphan instances

Description

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

- `defaultMain` creates an executable which can render a single diagram at various options.
- `multiMain` is like `defaultMain` but allows for a list of diagrams from which the user can choose one to render.
- `animMain` is like `defaultMain` but for animations instead of diagrams.
- `gifMain` creates an executable to generate an animated GIF.
- `mainWith` is a generic form that does all of the above but with a slightly scarier type. See Diagrams.Backend.CmdLine. This form can also take a function type that has a suitable final result (any of arguments to the above types) and `Parseable` arguments.

If you want to generate diagrams programmatically---i.e. if you want to do anything more complex than what the below functions provide---you have several options.

- Use a function with `mainWith`. This may require making `Parseable` instances for custom argument types.
- Make a new `Mainable` instance. This may require a newtype wrapper on your diagram type to avoid the existing instances. This gives you more control over argument parsing, intervening steps, and diagram creation.
- Build option records and pass them along with a diagram to `mainRender` from Diagrams.Backend.CmdLine.
- A more flexible approach is to use the `renderCairo` function provided in the Diagrams.Backend.Cairo module.
- For the most flexibility, you can call the generic `renderDia` function directly; see Diagrams.Backend.Cairo for more information.

For a tutorial on command-line diagram creation see https://diagrams.github.io/doc/cmdline.html.

Synopsis

- mainWith :: Mainable d => d -> IO ()
- defaultMain :: QDiagram Cairo V2 Double Any -> IO ()
- multiMain :: [(String, QDiagram Cairo V2 Double Any)] -> IO ()
- animMain :: Animation Cairo V2 Double -> IO ()
- gifMain :: [(QDiagram Cairo V2 Double Any, GifDelay)] -> IO ()
- data GifOpts = GifOpts {
  - _dither :: Bool
  - _noLooping :: Bool
  - _loopRepeat :: Maybe Int
  }
- gifRender :: (DiagramOpts, GifOpts) -> [(QDiagram Cairo V2 Double Any, GifDelay)] -> IO ()
- data Cairo
- type B = Cairo

# 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`, `multiMain`, or `animMain` 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 Cairo
    f i c = ...

    main = mainWith f

We can run this program as follows:

    $ ghc --make MyDiagram

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

mainWith :: Mainable d => d -> IO () Source #

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 :: QDiagram Cairo V2 Double Any -> IO () Source #

multiMain :: [(String, QDiagram Cairo V2 Double Any)] -> IO () Source #

animMain :: Animation Cairo V2 Double -> IO () Source #

`animMain` is like `defaultMain`, but renders an animation instead of a diagram. It takes as input an animation and produces a command-line program which will crudely "render" the animation by rendering one image for each frame, named by extending the given output file name by consecutive integers. For example if the given output file name is `foo/blah.png`, the frames will be saved in `foo/blah001.png`, `foo/blah002.png`, and so on (the number of padding digits used depends on the total number of frames). It is up to the user to take these images and stitch them together into an actual animation format (using, e.g. `ffmpeg`).

Of course, this is a rather crude method of rendering animations; more sophisticated methods will likely be added in the future.

The `--fpu` option can be used to control how many frames will be output for each second (unit time) of animation.

gifMain :: [(QDiagram Cairo V2 Double Any, GifDelay)] -> IO () Source #

`gifMain` takes a list of diagram and delay time pairs and produces a command line program to generate an animated GIF, with options `GifOpts`. "Delay times are in 1/100ths of a second."

Example usage:

      $ ghc --make GifTest
      [1 of 1] Compiling Main             ( GifTest.hs, GifTest.o )
      Linking GifTest ...
      ./GifTest --help
      GifTest

      Usage: GifTest [-w|--width WIDTH] [-h|--height HEIGHT] [-o|--output OUTPUT]
      [--dither] [--looping-off] [--loop-repeat ARG]
      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
       --dither                 Turn on dithering.
       --looping-off            Turn looping off
       --loop-repeat ARG        Number of times to repeat

# GIF support

data GifOpts Source #

Extra options for animated GIFs.

Constructors

GifOpts |

Fields

- _dither :: Bool
- _noLooping :: Bool
- _loopRepeat :: Maybe Int

#### Instances

Instances details

Parseable GifOpts Source # | Command line parser for `GifOpts`. `--dither` turn dithering on. `--looping-off` turn looping off, i.e play GIF once. `--loop-repeat` number of times to repeat the GIF after the first playing. this option is only used if `--looping-off` is not set.
Instance details Defined in Diagrams.Backend.Cairo.CmdLine Methods parser :: Parser GifOpts Source #

gifRender :: (DiagramOpts, GifOpts) -> [(QDiagram Cairo V2 Double Any, GifDelay)] -> IO () Source #

# Backend tokens

data Cairo Source #

This data declaration is simply used as a token to distinguish the cairo backend: (1) when calling functions where the type inference engine would otherwise have no way to know which backend you wanted to use, and (2) as an argument to the `Backend` and `Renderable` type classes.

#### Instances

Instances details

Read Cairo Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal Methods readsPrec :: Int -> ReadS Cairo Source # readList :: ReadS [Cairo] Source # readPrec :: ReadPrec Cairo Source # readListPrec :: ReadPrec [Cairo] Source #
Show Cairo Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal Methods showsPrec :: Int -> Cairo -> ShowS Source # show :: Cairo -> String Source # showList :: [Cairo] -> ShowS Source #
Eq Cairo Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal Methods (==) :: Cairo -> Cairo -> Bool Source # (/=) :: Cairo -> Cairo -> Bool Source #
Ord Cairo Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal Methods compare :: Cairo -> Cairo -> Ordering Source # (<) :: Cairo -> Cairo -> Bool Source # (<=) :: Cairo -> Cairo -> Bool Source # (>) :: Cairo -> Cairo -> Bool Source # (>=) :: Cairo -> Cairo -> Bool Source # max :: Cairo -> Cairo -> Cairo Source # min :: Cairo -> Cairo -> Cairo Source #
Backend Cairo V2 Double Source # |

Instance details

Defined in Diagrams.Backend.Cairo.Internal

Associated Types

data Render Cairo V2 Double |
Instance details Defined in Diagrams.Backend.Cairo.Internal data Render Cairo V2 Double = C (RenderM ())
type Result Cairo V2 Double |
Instance details Defined in Diagrams.Backend.Cairo.Internal type Result Cairo V2 Double = (IO (), Render ())
data Options Cairo V2 Double |

Instance details

Defined in Diagrams.Backend.Cairo.Internal

data Options Cairo V2 Double = CairoOptions {

- _cairoFileName :: String
- _cairoSizeSpec :: SizeSpec V2 Double
- _cairoOutputType :: OutputType
- _cairoBypassAdjust :: Bool

}

Methods

adjustDia :: (Additive V2, Monoid' m, Num Double) => Cairo -> Options Cairo V2 Double -> QDiagram Cairo V2 Double m -> (Options Cairo V2 Double, Transformation V2 Double, QDiagram Cairo V2 Double m) Source #

renderRTree :: Cairo -> Options Cairo V2 Double -> RTree Cairo V2 Double Annotation -> Result Cairo V2 Double Source #

Mainable [(QDiagram Cairo V2 Double Any, GifDelay)] Source # |

Instance details

Defined in Diagrams.Backend.Cairo.CmdLine

Associated Types

type MainOpts [(QDiagram Cairo V2 Double Any, GifDelay)] |
Instance details Defined in Diagrams.Backend.Cairo.CmdLine type MainOpts [(QDiagram Cairo V2 Double Any, GifDelay)] = (DiagramOpts, GifOpts)

Methods

mainArgs :: Parseable (MainOpts [(QDiagram Cairo V2 Double Any, GifDelay)]) => proxy [(QDiagram Cairo V2 Double Any, GifDelay)] -> IO (MainOpts [(QDiagram Cairo V2 Double Any, GifDelay)]) Source #

mainRender :: MainOpts [(QDiagram Cairo V2 Double Any, GifDelay)] -> [(QDiagram Cairo V2 Double Any, GifDelay)] -> IO () Source #

mainWith :: [(QDiagram Cairo V2 Double Any, GifDelay)] -> IO () Source #

Mainable [(String, QDiagram Cairo V2 Double Any)] Source # |

Instance details

Defined in Diagrams.Backend.Cairo.CmdLine

Associated Types

type MainOpts [(String, QDiagram Cairo V2 Double Any)] |
Instance details Defined in Diagrams.Backend.Cairo.CmdLine type MainOpts [(String, QDiagram Cairo V2 Double Any)] = (MainOpts (QDiagram Cairo V2 Double Any), DiagramMultiOpts)

Methods

mainArgs :: Parseable (MainOpts [(String, QDiagram Cairo V2 Double Any)]) => proxy [(String, QDiagram Cairo V2 Double Any)] -> IO (MainOpts [(String, QDiagram Cairo V2 Double Any)]) Source #

mainRender :: MainOpts [(String, QDiagram Cairo V2 Double Any)] -> [(String, QDiagram Cairo V2 Double Any)] -> IO () Source #

mainWith :: [(String, QDiagram Cairo V2 Double Any)] -> IO () Source #

Renderable (Text Double) Cairo Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal Methods render :: Cairo -> Text Double -> Render Cairo (V (Text Double)) (N (Text Double)) Source #
Renderable (Path V2 Double) Cairo Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal Methods render :: Cairo -> Path V2 Double -> Render Cairo (V (Path V2 Double)) (N (Path V2 Double)) Source #
Renderable (Trail V2 Double) Cairo Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal Methods render :: Cairo -> Trail V2 Double -> Render Cairo (V (Trail V2 Double)) (N (Trail V2 Double)) Source #
Renderable (DImage Double Embedded) Cairo Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal Methods render :: Cairo -> DImage Double Embedded -> Render Cairo (V (DImage Double Embedded)) (N (DImage Double Embedded)) Source #
Renderable (DImage Double External) Cairo Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal Methods render :: Cairo -> DImage Double External -> Render Cairo (V (DImage Double External)) (N (DImage Double External)) Source #
Mainable (Animation Cairo V2 Double) Source # |

Instance details

Defined in Diagrams.Backend.Cairo.CmdLine

Associated Types

type MainOpts (Animation Cairo V2 Double) |
Instance details Defined in Diagrams.Backend.Cairo.CmdLine type MainOpts (Animation Cairo V2 Double) = (DiagramOpts, DiagramAnimOpts)

Methods

mainArgs :: Parseable (MainOpts (Animation Cairo V2 Double)) => proxy (Animation Cairo V2 Double) -> IO (MainOpts (Animation Cairo V2 Double)) Source #

mainRender :: MainOpts (Animation Cairo V2 Double) -> Animation Cairo V2 Double -> IO () Source #

mainWith :: Animation Cairo V2 Double -> IO () Source #

Monoid (Render Cairo V2 Double) Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal Methods mempty :: Render Cairo V2 Double Source # mappend :: Render Cairo V2 Double -> Render Cairo V2 Double -> Render Cairo V2 Double Source # mconcat :: [Render Cairo V2 Double] -> Render Cairo V2 Double Source #
Semigroup (Render Cairo V2 Double) Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal Methods (<>) :: Render Cairo V2 Double -> Render Cairo V2 Double -> Render Cairo V2 Double Source # sconcat :: NonEmpty (Render Cairo V2 Double) -> Render Cairo V2 Double Source # stimes :: Integral b => b -> Render Cairo V2 Double -> Render Cairo V2 Double Source #
Show (Options Cairo V2 Double) Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal Methods showsPrec :: Int -> Options Cairo V2 Double -> ShowS Source # show :: Options Cairo V2 Double -> String Source # showList :: [Options Cairo V2 Double] -> ShowS Source #
Eq (Options Cairo V2 Double) Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal Methods (==) :: Options Cairo V2 Double -> Options Cairo V2 Double -> Bool Source # (/=) :: Options Cairo V2 Double -> Options Cairo V2 Double -> Bool Source #
Hashable (Options Cairo V2 Double) Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal Methods hashWithSalt :: Int -> Options Cairo V2 Double -> Int Source # hash :: Options Cairo V2 Double -> Int Source #
Renderable (Segment Closed V2 Double) Cairo Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal Methods render :: Cairo -> Segment Closed V2 Double -> Render Cairo (V (Segment Closed V2 Double)) (N (Segment Closed V2 Double)) Source #
Mainable (QDiagram Cairo V2 Double Any) Source # |

Instance details

Defined in Diagrams.Backend.Cairo.CmdLine

Associated Types

type MainOpts (QDiagram Cairo V2 Double Any) |
Instance details Defined in Diagrams.Backend.Cairo.CmdLine type MainOpts (QDiagram Cairo V2 Double Any) = DiagramOpts

Methods

mainArgs :: Parseable (MainOpts (QDiagram Cairo V2 Double Any)) => proxy (QDiagram Cairo V2 Double Any) -> IO (MainOpts (QDiagram Cairo V2 Double Any)) Source #

mainRender :: MainOpts (QDiagram Cairo V2 Double Any) -> QDiagram Cairo V2 Double Any -> IO () Source #

mainWith :: QDiagram Cairo V2 Double Any -> IO () Source #

type N Cairo Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal type N Cairo = Double
type V Cairo Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal type V Cairo = V2
data Options Cairo V2 Double Source # |

Instance details

Defined in Diagrams.Backend.Cairo.Internal

data Options Cairo V2 Double = CairoOptions {

- _cairoFileName :: String
- _cairoSizeSpec :: SizeSpec V2 Double
- _cairoOutputType :: OutputType
- _cairoBypassAdjust :: Bool

}

data Render Cairo V2 Double Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal data Render Cairo V2 Double = C (RenderM ())
type Result Cairo V2 Double Source # |
Instance details Defined in Diagrams.Backend.Cairo.Internal type Result Cairo V2 Double = (IO (), Render ())
type MainOpts [(QDiagram Cairo V2 Double Any, GifDelay)] Source # |
Instance details Defined in Diagrams.Backend.Cairo.CmdLine type MainOpts [(QDiagram Cairo V2 Double Any, GifDelay)] = (DiagramOpts, GifOpts)
type MainOpts [(String, QDiagram Cairo V2 Double Any)] Source # |
Instance details Defined in Diagrams.Backend.Cairo.CmdLine type MainOpts [(String, QDiagram Cairo V2 Double Any)] = (MainOpts (QDiagram Cairo V2 Double Any), DiagramMultiOpts)
type MainOpts (Animation Cairo V2 Double) Source # |
Instance details Defined in Diagrams.Backend.Cairo.CmdLine type MainOpts (Animation Cairo V2 Double) = (DiagramOpts, DiagramAnimOpts)
type MainOpts (QDiagram Cairo V2 Double Any) Source # |
Instance details Defined in Diagrams.Backend.Cairo.CmdLine type MainOpts (QDiagram Cairo V2 Double Any) = DiagramOpts

type B = Cairo Source #

# Orphan instances

Mainable [(QDiagram Cairo V2 Double Any, GifDelay)] Source # |

Instance details

Associated Types

type MainOpts [(QDiagram Cairo V2 Double Any, GifDelay)] |
Instance details Defined in Diagrams.Backend.Cairo.CmdLine type MainOpts [(QDiagram Cairo V2 Double Any, GifDelay)] = (DiagramOpts, GifOpts)

Methods

mainArgs :: Parseable (MainOpts [(QDiagram Cairo V2 Double Any, GifDelay)]) => proxy [(QDiagram Cairo V2 Double Any, GifDelay)] -> IO (MainOpts [(QDiagram Cairo V2 Double Any, GifDelay)]) Source #

mainRender :: MainOpts [(QDiagram Cairo V2 Double Any, GifDelay)] -> [(QDiagram Cairo V2 Double Any, GifDelay)] -> IO () Source #

mainWith :: [(QDiagram Cairo V2 Double Any, GifDelay)] -> IO () Source #

Mainable [(String, QDiagram Cairo V2 Double Any)] Source # |

Instance details

Associated Types

type MainOpts [(String, QDiagram Cairo V2 Double Any)] |
Instance details Defined in Diagrams.Backend.Cairo.CmdLine type MainOpts [(String, QDiagram Cairo V2 Double Any)] = (MainOpts (QDiagram Cairo V2 Double Any), DiagramMultiOpts)

Methods

mainArgs :: Parseable (MainOpts [(String, QDiagram Cairo V2 Double Any)]) => proxy [(String, QDiagram Cairo V2 Double Any)] -> IO (MainOpts [(String, QDiagram Cairo V2 Double Any)]) Source #

mainRender :: MainOpts [(String, QDiagram Cairo V2 Double Any)] -> [(String, QDiagram Cairo V2 Double Any)] -> IO () Source #

mainWith :: [(String, QDiagram Cairo V2 Double Any)] -> IO () Source #

Mainable (Animation Cairo V2 Double) Source # |

Instance details

Associated Types

type MainOpts (Animation Cairo V2 Double) |
Instance details Defined in Diagrams.Backend.Cairo.CmdLine type MainOpts (Animation Cairo V2 Double) = (DiagramOpts, DiagramAnimOpts)

Methods

mainArgs :: Parseable (MainOpts (Animation Cairo V2 Double)) => proxy (Animation Cairo V2 Double) -> IO (MainOpts (Animation Cairo V2 Double)) Source #

mainRender :: MainOpts (Animation Cairo V2 Double) -> Animation Cairo V2 Double -> IO () Source #

mainWith :: Animation Cairo V2 Double -> IO () Source #

Mainable (QDiagram Cairo V2 Double Any) Source # |

Instance details

Associated Types

type MainOpts (QDiagram Cairo V2 Double Any) |
Instance details Defined in Diagrams.Backend.Cairo.CmdLine type MainOpts (QDiagram Cairo V2 Double Any) = DiagramOpts

Methods

mainArgs :: Parseable (MainOpts (QDiagram Cairo V2 Double Any)) => proxy (QDiagram Cairo V2 Double Any) -> IO (MainOpts (QDiagram Cairo V2 Double Any)) Source #

mainRender :: MainOpts (QDiagram Cairo V2 Double Any) -> QDiagram Cairo V2 Double Any -> IO () Source #

mainWith :: QDiagram Cairo V2 Double Any -> IO () Source #