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


-- | Haskell utilities for building embedded Elm programs.
--   
--   This package provides utilities for serving Elm programs directly from
--   your Haskell binary. It uses TemplateHaskell to compile your Elm
--   program at build time, and construct a WAI Middleware which intercepts
--   requests appropriate to the Elm program, and passing other requests to
--   a downstream WAI Application. It is useful for bundling the browser
--   side of a web application with its backing web services
--   implementation.
@package om-elm
@version 2.1.0.0


-- | Core compile-time utilities for embedding Elm programs in Haskell.
--   
--   This module runs the <tt>elm</tt> compiler during Template Haskell
--   splices and returns the compiled output as a <a>String</a>. It is the
--   low-level building block used by higher-level modules such as
--   <a>System.Elm.Middleware</a>.
--   
--   <h2>Quick start</h2>
--   
--   1) Ensure <tt>elm</tt> is available when GHC runs Template Haskell. If
--   you use Cabal, add <a>requireElm</a> to your <tt>Setup.hs</tt> (see
--   <a>System.Elm.Middleware</a> for details).
--   
--   2) Call <a>compileElm</a> from a Template Haskell splice:
--   
--   <pre>
--   import Language.Haskell.TH
--   import System.Elm.Compile
--   
--   embeddedJs :: Q String
--   embeddedJs = compileElm Dev JavaScript "frontend/Main.elm"
--   </pre>
--   
--   3) Splice the result into your program:
--   
--   <pre>
--   myJs :: String
--   myJs = $(embeddedJs)
--   </pre>
--   
--   <h2>Choosing a <a>Mode</a></h2>
--   
--   <a>Mode</a> controls which flags are passed to <tt>elm make</tt>:
--   
--   <ul>
--   <li><a>Dev</a> — no extra flags (the default for local
--   development)</li>
--   <li><a>Debug</a> — passes <tt>--debug</tt> (debug runtime, better
--   errors)</li>
--   <li><a>Optimize</a> — passes <tt>--optimize</tt> (smaller, faster
--   output)</li>
--   </ul>
--   
--   Examples:
--   
--   <pre>
--   compileElm Dev JavaScript "frontend/Main.elm"
--   
--   compileElm Debug JavaScript "frontend/Main.elm"
--   
--   compileElm Optimize JavaScript "frontend/Main.elm"
--   </pre>
--   
--   <h2>Choosing an <a>ElmOutputFormat</a></h2>
--   
--   <a>ElmOutputFormat</a> selects whether <tt>elm make</tt> produces a
--   standalone JavaScript bundle or a complete HTML page:
--   
--   <ul>
--   <li><a>JavaScript</a> — compile to <tt>.js</tt> (typical for SPAs
--   loaded by your own HTML template)</li>
--   <li><a>Html</a> — compile to a self-contained <tt>.html</tt> page</li>
--   </ul>
--   
--   Examples:
--   
--   <pre>
--   -- JavaScript bundle for a custom HTML shell
--   compileElm Dev JavaScript "frontend/Main.elm"
--   
--   -- Full HTML page served as-is
--   compileElm Dev Html "frontend/Main.elm"
--   </pre>
--   
--   <h2>Embedding in other types</h2>
--   
--   <a>compileElm</a> returns a plain <a>String</a>. Convert it however
--   your application needs:
--   
--   <pre>
--   import qualified Data.Text as T
--   
--   embeddedText :: Q T.Text
--   embeddedText = T.pack &lt;$&gt; compileElm Dev JavaScript "frontend/Main.elm"
--   </pre>
--   
--   <pre>
--   import qualified Data.ByteString.Char8 as BS8
--   
--   embeddedBytes :: Q BS8.ByteString
--   embeddedBytes = BS8.pack &lt;$&gt; compileElm Dev JavaScript "frontend/Main.elm"
--   </pre>
--   
--   <h2>Using with typed splices</h2>
--   
--   For a typed expression splice, bind the compiled content in <tt>Q</tt>
--   and lift it:
--   
--   <pre>
--   import Language.Haskell.TH
--   
--   myJs :: String
--   myJs = $(do
--     js &lt;- compileElm Optimize JavaScript "frontend/Main.elm"
--     [| js |]
--     )
--   </pre>
--   
--   <h2>Recompilation</h2>
--   
--   <a>compileElm</a> registers the <tt>.elm</tt> source file as a
--   Template Haskell dependency via <a>addDependentFile</a>. GHC can
--   re-run the splice when that file changes, but that only effectively
--   works if the <tt>.elm</tt> file is also listed under
--   <tt>extra-source-files</tt> in your <tt>.cabal</tt> file — otherwise
--   Cabal may not rebuild the Haskell module when the Elm source changes.
--   
--   Example:
--   
--   <pre>
--   extra-source-files:
--     frontend/Main.elm
--   </pre>
--   
--   <h2>Relationship to <a>System.Elm.Middleware</a></h2>
--   
--   If you want to serve compiled Elm as WAI <tt>Middleware</tt>, use
--   <a>System.Elm.Middleware</a> instead — it wraps <a>compileElm</a> for
--   that purpose. Use this module when you want the compiled output
--   directly (for example, embedding JavaScript in a HTML template you
--   write yourself, or serving it through your own HTTP layer).
module System.Elm.Compile
data Mode
Optimize :: Mode
Dev :: Mode
Debug :: Mode
data ElmOutputFormat
JavaScript :: ElmOutputFormat
Html :: ElmOutputFormat

-- | Compile an Elm program at Template Haskell time.
--   
--   This function invokes <tt>elm make</tt>, reads the compiler output
--   from a temporary build directory, and returns the contents as a
--   <a>String</a>. The caller is responsible for interpreting the result —
--   for example, choosing an HTTP content type or converting to
--   <tt>Text</tt>.
--   
--   <h2>Parameters</h2>
--   
--   <ul>
--   <li><b>mode</b> — compiler flags (<a>Dev</a>, <a>Debug</a>, or
--   <a>Optimize</a>)</li>
--   <li><b>format</b> — output shape (<a>JavaScript</a> or
--   <a>Html</a>)</li>
--   <li><b>elmFile</b> — path to the <tt>.elm</tt> entrypoint, relative to
--   the project root (same path you would pass to <tt>elm make</tt> on the
--   command line)</li>
--   </ul>
--   
--   <h2>Basic examples</h2>
--   
--   Compile a JavaScript bundle with default (dev) settings:
--   
--   <pre>
--   compileElm Dev JavaScript "frontend/Main.elm"
--   </pre>
--   
--   Compile an optimized JavaScript bundle:
--   
--   <pre>
--   compileElm Optimize JavaScript "frontend/Main.elm"
--   </pre>
--   
--   Compile a self-contained HTML page:
--   
--   <pre>
--   compileElm Dev Html "frontend/Main.elm"
--   </pre>
--   
--   <h2>Splicing into top-level definitions</h2>
--   
--   <pre>
--   myJs :: String
--   myJs = $(compileElm Dev JavaScript "frontend/Main.elm")
--   </pre>
--   
--   <pre>
--   myHtml :: String
--   myHtml = $(compileElm Dev Html "frontend/Main.elm")
--   </pre>
--   
--   <h2>Splicing into a larger Template Haskell computation</h2>
--   
--   <pre>
--   import Language.Haskell.TH
--   
--   myJs :: String
--   myJs = $(do
--     js &lt;- compileElm Optimize JavaScript "frontend/Main.elm"
--     [| js |]
--     )
--   </pre>
--   
--   <h2>Combining mode and format</h2>
--   
--   <pre>
--   -- Debug runtime, JavaScript output
--   compileElm Debug JavaScript "frontend/Main.elm"
--   
--   -- Optimized production build, HTML output
--   compileElm Optimize Html "frontend/Main.elm"
--   
--   -- Dev build, JavaScript output (most common for SPAs)
--   compileElm Dev JavaScript "frontend/Main.elm"
--   </pre>
--   
--   <h2>Requirements</h2>
--   
--   <ul>
--   <li>The <tt>elm</tt> executable must be on <tt>PATH</tt> when GHC runs
--   this splice.</li>
--   <li>The <tt>elmFile</tt> path must exist at compile time.</li>
--   <li>GHC can re-run the splice when <tt>elmFile</tt> changes (via
--   <a>addDependentFile</a>), but that only effectively works if
--   <tt>elmFile</tt> is also listed under <tt>extra-source-files</tt> in
--   your <tt>.cabal</tt> file (see the module documentation for an
--   example).</li>
--   </ul>
--   
--   See the module documentation for setup instructions and more embedding
--   examples.
compileElm :: Mode -> ElmOutputFormat -> FilePath -> Q String
instance GHC.Show.Show System.Elm.Compile.Mode
instance GHC.Classes.Eq System.Elm.Compile.Mode
instance GHC.Show.Show System.Elm.Compile.ElmOutputFormat
instance GHC.Classes.Eq System.Elm.Compile.ElmOutputFormat


-- | This module contains utilities for compiling and bundling Elm programs
--   directly into your Haskell executable binary. It is useful for the
--   case where you want to bundle a front-end Elm web app along with the
--   backing services that support it, and especially for when the two
--   components are part of the same codebase. It produces WAI Middleware,
--   and is thus compatible with a wide range server-side frameworks.
--   
--   Usage is designed to be as simple as possible. There are 3 steps:
--   
--   1) Change your .cabal file to use a "Custom" build type, and add the
--   appropriate custom build dependencies.
--   
--   <pre>
--   build-type: Custom
--   ...
--   custom-setup
--     setup-depends:
--       Cabal,
--       base,
--       om-elm
--   </pre>
--   
--   2) Modify your <tt>Setup.hs</tt> file, using <a>requireElm</a>.
--   
--   3) Include a <a>Middleware</a> template-haskell splice, using
--   <a>elmSiteDev</a>, in the appropriate place in your code.
--   
--   See the function documnetation for more details.
module System.Elm.Middleware

-- | Add the elm program requirements to a set of build hooks. This is
--   expected to be used in your Setup.hs file thusly:
--   
--   <pre>
--   import Distribution.Simple (defaultMainWithHooks, simpleUserHooks)
--   import System.Elm.Middleware (requireElm)
--   
--   main = defaultMainWithHooks (requireElm simpleUserHooks)
--   </pre>
requireElm :: UserHooks -> UserHooks

-- | Like <a>elmSiteDev</a>, but serve the debug elm runtime.
elmSiteDebug :: Map PathInfo FilePath -> Q (TExp Middleware)

-- | Template Haskell method to create a <a>Middleware</a> that serves a
--   set of elm programs. The elm programs are compiled into HTML at
--   compile time, and that HTML is included directly in your executable.
--   
--   The parameter is a map of <a>pathInfo</a>s to elm program module file.
--   The elm program located at the file is served whenever the pathInfo
--   matches that of the request. Any non-matching request is forwarded to
--   the downstream <a>Application</a>.
--   
--   The typed template-haskell splice:
--   
--   <pre>
--   $$(elmSiteDev $ Map.fromList [
--       (["app.js"], "elm/Your/Elm/Module/App.elm")
--     ])
--   </pre>
--   
--   will construct a WAI <a>Middleware</a> which serves the compiled elm
--   program on <tt>/app.js</tt>.
--   
--   Neither the <tt>--optimize</tt> nor the <tt>--debug</tt> flags are
--   passed to the elm compiler.
elmSiteDev :: Map PathInfo FilePath -> Q (TExp Middleware)

-- | Like <a>elmSiteDev</a>, but pass <tt>--optimize</tt> to the elm
--   compiler.
elmSiteOptimize :: Map PathInfo FilePath -> Q (TExp Middleware)

-- | A WAI uri path, as per the meaning of <a>pathInfo</a>.
type PathInfo = [Text]
