-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | SVG backend for diagrams drawing EDSL.
--   
--   This package provides a modular backend for rendering diagrams created
--   with the diagrams EDSL to SVG files. It uses <tt>blaze-svg</tt> to be
--   a fast, native Haskell backend, making it suitable for use on any
--   platform.
--   
--   The package provides the following modules:
--   
--   <ul>
--   <li><a>Diagrams.Backend.SVG.CmdLine</a> - if you're just getting
--   started with diagrams, begin here.</li>
--   <li><a>Diagrams.Backend.SVG</a> - look at this next. The general API
--   for the SVG backend.</li>
--   </ul>
--   
--   Additional documentation can be found in the README file distributed
--   with the source tarball or viewable on GitHub:
--   <a>https://github.com/diagrams/diagrams-svg/blob/master/README.md</a>.
@package diagrams-svg
@version 1.1


-- | A full-featured rendering backend for diagrams producing SVG files,
--   implemented natively in Haskell (making it easy to use on any
--   platform).
--   
--   To invoke the SVG backend, you have three options.
--   
--   <ul>
--   <li>You can use the <a>Diagrams.Backend.SVG.CmdLine</a> module to
--   create standalone executables which output SVG images when
--   invoked.</li>
--   <li>You can use the <a>renderSVG</a> function provided by this module,
--   which gives you more flexible programmatic control over when and how
--   images are output (making it easy to, for example, write a single
--   program that outputs multiple images, or one that outputs images
--   dynamically based on user input, and so on).</li>
--   <li>For the most flexibility (<i>e.g.</i> if you want access to the
--   resulting SVG value directly in memory without writing it to disk),
--   you can manually invoke the <a>renderDia</a> method from the
--   <a>Backend</a> instance for <tt>SVG</tt>. In particular,
--   <a>renderDia</a> has the generic type</li>
--   </ul>
--   
--   <pre>
--   renderDia :: b -&gt; Options b v -&gt; QDiagram b v m -&gt; Result b v
--   </pre>
--   
--   (omitting a few type class constraints). <tt>b</tt> represents the
--   backend type, <tt>v</tt> the vector space, and <tt>m</tt> the type of
--   monoidal query annotations on the diagram. <a>Options</a> and
--   <a>Result</a> are associated data and type families, respectively,
--   which yield the type of option records and rendering results specific
--   to any particular backend. For <tt>b ~ SVG</tt> and <tt>v ~ R2</tt>,
--   we have
--   
--   <pre>
--   data Options SVG R2 = SVGOptions
--                         { size :: SizeSpec2D   -- ^ The requested size.
--                         , svgDefinitions :: Maybe S.Svg
--                         -- ^ Custom definitions that will be added to the @defs@
--                         --  section of the output.
--                         }
--   </pre>
--   
--   <pre>
--   data family Render SVG R2 = R <a>SvgRenderM</a>
--   </pre>
--   
--   <pre>
--   type family Result SVG R2 = <a>Svg</a>
--   </pre>
--   
--   So the type of <a>renderDia</a> resolves to
--   
--   <pre>
--   renderDia :: SVG -&gt; Options SVG R2 -&gt; QDiagram SVG R2 m -&gt; <a>Svg</a>
--   </pre>
--   
--   which you could call like <tt>renderDia SVG (SVGOptions (Width 250))
--   myDiagram</tt>. (In some situations GHC may not be able to infer the
--   type <tt>m</tt>, in which case you can use a type annotation to
--   specify it; it may be useful to simply use the type synonym
--   <tt>Diagram SVG R2 = QDiagram SVG R2 Any</tt>.) This returns an
--   <a>Svg</a> value, which you can, <i>e.g.</i> render to a
--   <a>ByteString</a> using <a>renderSvg</a>.
module Diagrams.Backend.SVG

-- | <tt>SVG</tt> is simply a token used to identify this rendering backend
--   (to aid type inference).
data SVG
SVG :: SVG
type B = SVG

-- | Backend-specific rendering options.
size :: Lens' (Options SVG R2) SizeSpec2D
svgDefinitions :: Lens' (Options SVG R2) (Maybe Svg)

-- | Render a diagram as an SVG, writing to the specified output file and
--   using the requested size.
renderSVG :: FilePath -> SizeSpec2D -> Diagram SVG R2 -> IO ()
instance Generic ChoiceString
instance Datatype D1ChoiceString
instance Constructor C1_0ChoiceString
instance Constructor C1_1ChoiceString
instance Constructor C1_2ChoiceString
instance Constructor C1_3ChoiceString
instance Constructor C1_4ChoiceString
instance Constructor C1_5ChoiceString
instance Constructor C1_6ChoiceString
instance Constructor C1_7ChoiceString
instance Renderable (DImage Embedded) SVG
instance Renderable Text SVG
instance Renderable (Path R2) SVG
instance Hashable (MarkupM a)
instance Hashable ChoiceString
instance Hashable StaticString
instance Hashable (Options SVG R2)
instance Backend SVG R2
instance Monoid (Render SVG R2)
instance Typeable SVG
instance Show SVG


-- | Convenient creation of command-line-driven executables for rendering
--   diagrams using the SVG backend.
--   
--   <ul>
--   <li><a>defaultMain</a> creates an executable which can render a single
--   diagram at various options.</li>
--   <li><a>multiMain</a> is like <a>defaultMain</a> but allows for a list
--   of diagrams from which the user can choose one to render.</li>
--   <li><a>mainWith</a> is a generic form that does all of the above but
--   with a slightly scarier type. See <a>Diagrams.Backend.CmdLine</a>.
--   This form can also take a function type that has a subtable final
--   result (any of arguments to the above types) and <a>Parseable</a>
--   arguments.</li>
--   </ul>
--   
--   If you want to generate diagrams programmatically---<i>i.e.</i> if you
--   want to do anything more complex than what the below functions
--   provide---you have several options.
--   
--   <ul>
--   <li>Use a function with <a>mainWith</a>. This may require making
--   <a>Parseable</a> instances for custom argument types.</li>
--   <li>Make a new <a>Mainable</a> 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.</li>
--   <li>Build option records and pass them along with a diagram to
--   <a>mainRender</a> from <a>Diagrams.Backend.CmdLine</a>.</li>
--   <li>You can use <a>renderSVG</a> to render a diagram to a file
--   directly; see <a>Diagrams.Backend.SVG</a>.</li>
--   <li>A more flexible approach is to directly call <a>renderDia</a>; see
--   <a>Diagrams.Backend.SVG</a> for more information.</li>
--   </ul>
--   
--   For a tutorial on command-line diagram creation see
--   <a>http://projects.haskell.org/diagrams/doc/cmdline.html</a>.
module Diagrams.Backend.SVG.CmdLine

-- | Main entry point for command-line diagram creation. This is the method
--   that users will call from their program <tt>main</tt>. For instance an
--   expected user program would take the following form.
--   
--   <pre>
--    import Diagrams.Prelude
--    import Diagrams.Backend.TheBestBackend.CmdLine
--   
--   d :: Diagram B R2
--    d = ...
--   
--   main = mainWith d
--   </pre>
--   
--   Most backends should be able to use the default implementation. A
--   different implementation should be used to handle more complex
--   interactions with the user.
mainWith :: (Mainable d, Parseable (MainOpts d)) => d -> IO ()

-- | This is the simplest way to render diagrams, and is intended to be
--   used like so:
--   
--   <pre>
--   ... definitions ...
--   
--   main = defaultMain myDiagram
--   </pre>
--   
--   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 <tt>myDiagram</tt> with the specified options.
--   
--   Pass <tt>--help</tt> to the generated executable to see all available
--   options. Currently it looks something like
--   
--   <pre>
--    ./Program
--   
--   Usage: ./Program [-w|--width WIDTH] [-h|--height HEIGHT] [-o|--output OUTPUT] [--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
--      -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.
--   </pre>
--   
--   For example, a common scenario is
--   
--   <pre>
--    $ ghc --make MyDiagram
--   
--   # output image.svg with a width of 400pt (and auto-determined height)
--    $ ./MyDiagram -o image.svg -w 400
--   </pre>
defaultMain :: Diagram SVG R2 -> IO ()

-- | <tt>multiMain</tt> is like <a>defaultMain</a>, except instead of a
--   single diagram it takes a list of diagrams paired with names as input.
--   The generated executable then takes a <tt>--selection</tt> option
--   specifying the name of the diagram that should be rendered. The list
--   of available diagrams may also be printed by passing the option
--   <tt>--list</tt>.
--   
--   Example usage:
--   
--   <pre>
--   $ 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.eps -w 200
--   </pre>
multiMain :: [(String, Diagram SVG R2)] -> IO ()

-- | <tt>SVG</tt> is simply a token used to identify this rendering backend
--   (to aid type inference).
data SVG
type B = SVG
instance Mainable [(String, Diagram SVG R2)]
instance Mainable (Diagram SVG R2)
