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


-- | hint-based build service for the diagrams graphics EDSL.
--   
--   <tt>diagrams-builder</tt> provides backend-agnostic tools for
--   dynamically turning code into rendered diagrams, using the
--   <tt>hint</tt> wrapper to the GHC API. It supports conditional
--   recompilation using hashing of diagrams source code, to avoid
--   recompiling code that has not changed. It is useful for creating tools
--   which compile diagrams code embedded in other documents. For example,
--   it is used by the <tt>BlogLiterately-diagrams</tt> package (a plugin
--   for <tt>BlogLiterately</tt>) to compile diagrams embedded in
--   Markdown-formatted blog posts.
--   
--   Executables specific to the cairo, SVG, postscript, and rasterific
--   backends are included (more executables specific to other backends may
--   be included in the future). All take an input file and an expression
--   to render, and output an image file. If you want these executables you
--   must explicitly enable the <tt>-fcairo</tt>, <tt>-fsvg</tt>,
--   <tt>-fpostscript</tt>, or <tt>-frasterific</tt> flags.
--   
--   A LaTeX package, <tt>diagrams-latex.sty</tt>, is also provided in the
--   <tt>latex/</tt> directory of the source distribution, which renders
--   diagrams code found within <tt>diagram</tt> environments. Note that
--   <tt>diagrams-latex.sty</tt> is licensed under the GPL.
@package diagrams-builder
@version 0.8.0.3


-- | Tools for creating standalone command-line diagram builder utilities.
module Diagrams.Builder.CmdLine

-- | Record of command-line options.
data Build
Build :: Maybe Double -> Maybe Double -> String -> String -> String -> String -> Build
[width] :: Build -> Maybe Double
[height] :: Build -> Maybe Double
[srcFile] :: Build -> String
[expr] :: Build -> String
[outFile] :: Build -> String
[dir] :: Build -> String

-- | Default command-line options record.
defaultBuildOpts :: Build
instance Data.Data.Data Diagrams.Builder.CmdLine.Build


-- | Options for dynamic creation of diagrams.
module Diagrams.Builder.Opts

-- | Synonym for more perspicuous types.
--   
--   We use <tt>Int</tt> values for hashes because that's what the
--   <tt>Hashable</tt> package uses. Assuming diagram hashes are uniformly
--   distributed, on a 64-bit system one needs to build on the order of
--   billions of diagrams before the probability of a hash collision
--   exceeds 1/2, and for anything up to tens of millions of diagrams the
--   probability of a collision is under 0.1%. On 32-bit systems those
--   become tens of thousands and thousands, respectively.
type Hash = Int

-- | Options to control the behavior of <tt>buildDiagram</tt>. Create one
--   with <a>mkBuildOpts</a> followed by using the provided lenses to
--   override more fields; for example,
--   
--   <pre>
--   mkBuildOpts SVG zeroV (Options ...)
--     &amp; imports .~ ["Foo.Bar", "Baz.Quux"]
--     &amp; diaExpr .~ "square 6 # fc green"
--   </pre>
data BuildOpts b v n
BuildOpts :: b -> v n -> Options b v n -> [String] -> [String] -> [String] -> [(String, String)] -> Hash -> IO (Maybe (Options b v n -> Options b v n)) -> String -> QDiagram b v n Any -> QDiagram b v n Any -> BuildOpts b v n

-- | Backend token
[backendToken] :: BuildOpts b v n -> b

-- | Dummy vector argument to fix the vector space type
[vectorToken] :: BuildOpts b v n -> v n
[_backendOpts] :: BuildOpts b v n -> Options b v n
[_snippets] :: BuildOpts b v n -> [String]
[_pragmas] :: BuildOpts b v n -> [String]
[_imports] :: BuildOpts b v n -> [String]
[_qimports] :: BuildOpts b v n -> [(String, String)]
[_decideRegen] :: BuildOpts b v n -> Hash -> IO (Maybe (Options b v n -> Options b v n))
[_diaExpr] :: BuildOpts b v n -> String
[_postProcess] :: BuildOpts b v n -> QDiagram b v n Any -> QDiagram b v n Any

-- | Create a <tt>BuildOpts</tt> record with default options:
--   
--   <ul>
--   <li>no snippets</li>
--   <li>no pragmas</li>
--   <li>no imports</li>
--   <li>always regenerate</li>
--   <li>the diagram expression <tt>circle 1</tt></li>
--   <li>no postprocessing</li>
--   </ul>
mkBuildOpts :: b -> v n -> Options b v n -> BuildOpts b v n

-- | Backend-specific options to use.
backendOpts :: Lens' (BuildOpts b v n) (Options b v n)

-- | Source code snippets. Each should be a syntactically valid Haskell
--   module. They will be combined intelligently, <i>i.e.</i> not just
--   pasted together textually but combining pragmas, imports, <i>etc.</i>
--   separately.
snippets :: Lens' (BuildOpts b v n) [String]

-- | Extra <tt>LANGUAGE</tt> pragmas to use
--   (<tt>NoMonomorphismRestriction</tt> is automatically enabled.)
pragmas :: Lens' (BuildOpts b v n) [String]

-- | Additional module imports (note that <a>Diagrams.Prelude</a> is
--   automatically imported).
imports :: Lens' (BuildOpts b v n) [String]

-- | Additional qualified module imports (module name, qualified name).
qimports :: Lens' (BuildOpts b v n) [(String, String)]

-- | A function to decide whether a particular diagram needs to be
--   regenerated. It will be passed a hash of the final assembled source
--   for the diagram (but with the module name set to <tt>Main</tt> instead
--   of something auto-generated, so that hashing the source will produce
--   consistent results across runs), plus any options, local imports, and
--   other things which could affect the result of rendering. It can return
--   some information (such as a hash of the source) via the <tt>x</tt>
--   result, which will be passed through to the result of
--   <tt>buildDiagram</tt>. More importantly, it decides whether the
--   diagram should be built: a result of <a>Just</a> means the diagram
--   <i>should</i> be built; <a>Nothing</a> means it should not. In the
--   case that it should be built, it returns a function for updating the
--   rendering options. This could be used, <i>e.g.</i>, to request a
--   filename based on a hash of the source.
--   
--   Two standard decision functions are provided for convenience:
--   <a>alwaysRegenerate</a> returns no extra information and always
--   decides to regenerate the diagram; <a>hashedRegenerate</a> creates a
--   hash of the diagram source and looks for a file with that name in a
--   given directory.
decideRegen :: Lens' (BuildOpts b v n) (Hash -> IO (Maybe (Options b v n -> Options b v n)))

-- | The diagram expression to interpret. All the given import sand
--   snippets will be in scope, with the given LANGUAGE pragmas enabled.
--   The expression may have either of the types <tt>Diagram b</tt> or
--   <tt>IO (Diagram b)</tt>.
diaExpr :: Lens' (BuildOpts b v n) String

-- | A function to apply to the interpreted diagram prior to rendering. For
--   example, you might wish to apply <tt>pad 1.1 . centerXY</tt>. This is
--   preferred over directly modifying the string expression to be
--   interpreted, since it gives better typechecking, and works no matter
--   whether the expression represents a diagram or an IO action.
postProcess :: Lens' (BuildOpts b v n) (QDiagram b v n Any -> QDiagram b v n Any)

-- | Convenience function suitable to be given as the final argument to
--   <tt>buildDiagram</tt>. It implements the simple policy of always
--   rebuilding every diagram.
alwaysRegenerate :: Hash -> IO (Maybe (a -> a))

-- | Convenience function suitable to be given as the final argument to
--   <tt>buildDiagram</tt>. It works by converting the hash value to a
--   zero-padded hexadecimal string and looking in the specified directory
--   for any file whose base name is equal to the hash. If there is such a
--   file, it specifies that the diagram should not be rebuilt. Otherwise,
--   it specifies that the diagram should be rebuilt, and uses the provided
--   function to update the rendering options based on the generated hash
--   string. (Most likely, one would want to set the requested output file
--   to the hash followed by some extension.)
hashedRegenerate :: (String -> a -> a) -> FilePath -> Hash -> IO (Maybe (a -> a))
hashToHexStr :: Hash -> String


-- | Tools used by diagrams-builder for manipulating Haskell modules.
module Diagrams.Builder.Modules

-- | Extend some snippets of source code into a proper module, by combining
--   them intelligently (preserving imports, pragmas, <i>etc.</i>),
--   (possibly) giving it a different name, and adding <tt>LANGUAGE</tt>
--   pragmas and imports if necessary. Only those pragmas and imports which
--   are not already included in the code will be added.
--   
--   Returns the updated module, or an error message if parsing failed.
createModule :: Maybe String -> BuildOpts b v n -> Either String Module
emptyModule :: Module

-- | Run the haskell-src-exts parser on a <tt>String</tt> representing some
--   Haskell code, producing a <tt>Module</tt> or an error message.
doModuleParse :: String -> Either String Module

-- | Remove all the literate comments and bird tracks from a literate
--   Haskell file. Has no effect on non-literate source.
unLit :: String -> String

-- | Replace the name of a module.
replaceModuleName :: String -> Module -> Module

-- | Delete module exports.
deleteExports :: Module -> Module

-- | Add some <tt>LANGUAGE</tt> pragmas to a module if necessary.
addPragmas :: [String] -> Module -> Module

-- | Add some imports to a module if necessary.
addImports :: [(String, Maybe String)] -> Module -> Module

-- | Combine two modules into one, with a left bias in the case of things
--   that can't be sensibly combined (<i>e.g.</i> the module name). Note
--   that combining multiple imports of the same module with different
--   import specifications (qualification, hiding, explicit import) is
--   unlikely to work sensibly.
combineModules :: Module -> Module -> Module

-- | Convert a <tt>ModuleName</tt> to a <tt>String</tt>.
getModuleName :: ModuleName -> String


-- | Tools for dynamically building diagrams, for <i>e.g.</i> creating
--   preprocessors to interpret diagrams code embedded in documents.
module Diagrams.Builder

-- | Options to control the behavior of <tt>buildDiagram</tt>. Create one
--   with <a>mkBuildOpts</a> followed by using the provided lenses to
--   override more fields; for example,
--   
--   <pre>
--   mkBuildOpts SVG zeroV (Options ...)
--     &amp; imports .~ ["Foo.Bar", "Baz.Quux"]
--     &amp; diaExpr .~ "square 6 # fc green"
--   </pre>
data BuildOpts b v n
BuildOpts :: b -> v n -> Options b v n -> [String] -> [String] -> [String] -> [(String, String)] -> Hash -> IO (Maybe (Options b v n -> Options b v n)) -> String -> QDiagram b v n Any -> QDiagram b v n Any -> BuildOpts b v n

-- | Backend token
[backendToken] :: BuildOpts b v n -> b

-- | Dummy vector argument to fix the vector space type
[vectorToken] :: BuildOpts b v n -> v n
[_backendOpts] :: BuildOpts b v n -> Options b v n
[_snippets] :: BuildOpts b v n -> [String]
[_pragmas] :: BuildOpts b v n -> [String]
[_imports] :: BuildOpts b v n -> [String]
[_qimports] :: BuildOpts b v n -> [(String, String)]
[_decideRegen] :: BuildOpts b v n -> Hash -> IO (Maybe (Options b v n -> Options b v n))
[_diaExpr] :: BuildOpts b v n -> String
[_postProcess] :: BuildOpts b v n -> QDiagram b v n Any -> QDiagram b v n Any

-- | Create a <tt>BuildOpts</tt> record with default options:
--   
--   <ul>
--   <li>no snippets</li>
--   <li>no pragmas</li>
--   <li>no imports</li>
--   <li>always regenerate</li>
--   <li>the diagram expression <tt>circle 1</tt></li>
--   <li>no postprocessing</li>
--   </ul>
mkBuildOpts :: b -> v n -> Options b v n -> BuildOpts b v n

-- | Backend-specific options to use.
backendOpts :: Lens' (BuildOpts b v n) (Options b v n)

-- | Source code snippets. Each should be a syntactically valid Haskell
--   module. They will be combined intelligently, <i>i.e.</i> not just
--   pasted together textually but combining pragmas, imports, <i>etc.</i>
--   separately.
snippets :: Lens' (BuildOpts b v n) [String]

-- | Extra <tt>LANGUAGE</tt> pragmas to use
--   (<tt>NoMonomorphismRestriction</tt> is automatically enabled.)
pragmas :: Lens' (BuildOpts b v n) [String]

-- | Additional module imports (note that <a>Diagrams.Prelude</a> is
--   automatically imported).
imports :: Lens' (BuildOpts b v n) [String]

-- | Additional qualified module imports (module name, qualified name).
qimports :: Lens' (BuildOpts b v n) [(String, String)]

-- | A function to decide whether a particular diagram needs to be
--   regenerated. It will be passed a hash of the final assembled source
--   for the diagram (but with the module name set to <tt>Main</tt> instead
--   of something auto-generated, so that hashing the source will produce
--   consistent results across runs), plus any options, local imports, and
--   other things which could affect the result of rendering. It can return
--   some information (such as a hash of the source) via the <tt>x</tt>
--   result, which will be passed through to the result of
--   <tt>buildDiagram</tt>. More importantly, it decides whether the
--   diagram should be built: a result of <a>Just</a> means the diagram
--   <i>should</i> be built; <a>Nothing</a> means it should not. In the
--   case that it should be built, it returns a function for updating the
--   rendering options. This could be used, <i>e.g.</i>, to request a
--   filename based on a hash of the source.
--   
--   Two standard decision functions are provided for convenience:
--   <a>alwaysRegenerate</a> returns no extra information and always
--   decides to regenerate the diagram; <a>hashedRegenerate</a> creates a
--   hash of the diagram source and looks for a file with that name in a
--   given directory.
decideRegen :: Lens' (BuildOpts b v n) (Hash -> IO (Maybe (Options b v n -> Options b v n)))

-- | The diagram expression to interpret. All the given import sand
--   snippets will be in scope, with the given LANGUAGE pragmas enabled.
--   The expression may have either of the types <tt>Diagram b</tt> or
--   <tt>IO (Diagram b)</tt>.
diaExpr :: Lens' (BuildOpts b v n) String

-- | A function to apply to the interpreted diagram prior to rendering. For
--   example, you might wish to apply <tt>pad 1.1 . centerXY</tt>. This is
--   preferred over directly modifying the string expression to be
--   interpreted, since it gives better typechecking, and works no matter
--   whether the expression represents a diagram or an IO action.
postProcess :: Lens' (BuildOpts b v n) (QDiagram b v n Any -> QDiagram b v n Any)

-- | Convenience function suitable to be given as the final argument to
--   <tt>buildDiagram</tt>. It implements the simple policy of always
--   rebuilding every diagram.
alwaysRegenerate :: Hash -> IO (Maybe (a -> a))

-- | Convenience function suitable to be given as the final argument to
--   <tt>buildDiagram</tt>. It works by converting the hash value to a
--   zero-padded hexadecimal string and looking in the specified directory
--   for any file whose base name is equal to the hash. If there is such a
--   file, it specifies that the diagram should not be rebuilt. Otherwise,
--   it specifies that the diagram should be rebuilt, and uses the provided
--   function to update the rendering options based on the generated hash
--   string. (Most likely, one would want to set the requested output file
--   to the hash followed by some extension.)
hashedRegenerate :: (String -> a -> a) -> FilePath -> Hash -> IO (Maybe (a -> a))
hashToHexStr :: Hash -> String

-- | Build a diagram by writing the given source code to a temporary module
--   and interpreting the given expression, which can be of type
--   <tt>Diagram b v</tt> or <tt>IO (Diagram b v)</tt>. Can return either a
--   parse error if the source does not parse, an interpreter error, or the
--   final result.
buildDiagram :: (Typeable b, Data (v n), Data n, Metric v, HasLinearMap v, Typeable v, OrderedField n, Backend b v n, Hashable (Options b v n)) => BuildOpts b v n -> IO (BuildResult b v n)

-- | Potential results of a dynamic diagram building operation.
data BuildResult b v n

-- | Parsing of the code failed.
ParseErr :: String -> BuildResult b v n

-- | Interpreting the code failed. See <a>ppInterpError</a>.
InterpErr :: InterpreterError -> BuildResult b v n

-- | This diagram did not need to be regenerated; includes the hash.
Skipped :: Hash -> BuildResult b v n

-- | A successful build, yielding the hash and a backend-specific result.
OK :: Hash -> (Result b v n) -> BuildResult b v n

-- | Pretty-print an <tt>InterpreterError</tt>.
ppInterpError :: InterpreterError -> String

-- | Set up the module to be interpreted, in the context of the necessary
--   imports.
setDiagramImports :: MonadInterpreter m => String -> [(String, Maybe String)] -> m ()

-- | Interpret a diagram expression based on the contents of a given source
--   file, using some backend to produce a result. The expression can be of
--   type <tt>Diagram b v n</tt> or <tt>IO (Diagram b v n)</tt>.
interpretDiagram :: forall b v n. (Typeable b, Typeable v, HasLinearMap v, Data (v n), Data n, Metric v, OrderedField n, Backend b v n) => BuildOpts b v n -> FilePath -> IO (Either InterpreterError (Result b v n))

-- | Record of command-line options.
data Build
Build :: Maybe Double -> Maybe Double -> String -> String -> String -> String -> Build
[width] :: Build -> Maybe Double
[height] :: Build -> Maybe Double
[srcFile] :: Build -> String
[expr] :: Build -> String
[outFile] :: Build -> String
[dir] :: Build -> String

-- | Default command-line options record.
defaultBuildOpts :: Build
