Standard options most diagrams are likely to have.

Command line parser for DiagramOpts. Width is option --width or -w. Height is option --height or -h (note we change help to be -? due to this). Output is option --output or -o.

Extra options for a program that can offer a choice between multiple diagrams.

Command line parser for DiagramMultiOpts. Selection is option --selection or -S. List is --list or -L.

Extra options for animations.

Command line parser for DiagramAnimOpts Frames per unit is --fpu or -f.

Extra options for command-line looping.

CommandLine parser for DiagramLoopOpts Loop is --loop or -l. Source is --src or -s. Interval is -i defaulting to one second.

Parseable instances give a command line parser for a type. If a custom parser for a common type is wanted a newtype wrapper could be used to make a new Parseable instance. Notice that we do not want as many instances as Read because we want to limit ourselves to things that make sense to parse from the command line.

Parses a hexadecimal color. The string can start with "0x" or "#" or just be a string of hexadecimal values. If four or three digits are given each digit is repeated to form a full 24 or 32 bit color. For example, "0xfc4" is the same as "0xffcc44". When eight or six digits are given each pair of digits is a color or alpha channel with the order being red, green, blue, alpha.

This class represents the various ways we want to support diagram creation from the command line. It has the right instances to select between creating single static diagrams, multiple static diagrams, static animations, and functions that produce diagrams as long as the arguments are Parseable.

Backends are expected to create Mainable instances for the types that are suitable for generating output in the backend's format. For instance, Postscript can handle single diagrams, pages of diagrams, animations as separate files, and association lists. This implies instances for Diagram Postscript R2, [Diagram Postscript R2], Animation Postscript R2, and [(String,Diagram Postscript R2)]. We can consider these as the base cases for the function instance.

The associated type MainOpts describes the options which need to be parsed from the command-line and passed to mainRender.

This class allows us to abstract over functions that take some arguments and produce a final value. When some d is an instance of ToResult we get a type Args d that is a type of all the arguments at once, and a type ResultOf d that is the type of the final result from some base case instance.

defaultAnimMainRender is an implementation of mainRender which renders an animation as numbered frames, named by extending the given output file name by consecutive integers. For example if the given output file name is foo/blah.ext, the frames will be saved in foo/blah001.ext, foo/blah002.ext, 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 from DiagramAnimOpts can be used to control how many frames will be output for each second (unit time) of animation.

This function requires a lens into the structure that the particular backend uses for it's diagram base case. If MainOpts (QDiagram b v n Any) ~ DiagramOpts then this lens will simply be output. For a backend supporting looping it will most likely be _1 . output. This lens is required because the implementation works by modifying the output field and running the base mainRender. Typically a backend can write its Animation B V instance as

  instance Mainable (Animation B V) where
      type MainOpts (Animation B V) = (DiagramOpts, DiagramAnimOpts)
      mainRender = defaultAnimMainRender output
  

We do not provide this instance in general so that backends can choose to opt-in to this form or provide a different instance that makes more sense.

defaultMultiMainRender is an implementation of mainRender where 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.

Typically a backend can write its [(String,QDiagram b v n Any)] instance as

  instance Mainable [(String,QDiagram b v n Any)] where
      type MainOpts [(String,QDiagram b v n Any)] = (DiagramOpts, DiagramMultiOpts)
      mainRender = defaultMultiMainRender
  

We do not provide this instance in general so that backends can choose to opt-in to this form or provide a different instance that makes more sense.