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


-- | Static file serving subsite for Yesod Web Framework.
--   
--   API docs and the README are available at
--   <a>http://www.stackage.org/package/yesod-static</a>
@package yesod-static
@version 1.5.1.1

module Yesod.EmbeddedStatic.Types

-- | A location is a relative path within the static subsite at which
--   resource(s) are made available. The location can include slashes to
--   simulate directories but must not start or end with a slash.
type Location = String

-- | An embedded generator is executed at compile time to produce the
--   entries to embed.
type Generator = Q [Entry]

-- | A single resource embedded into the executable at compile time.
--   
--   This data type is a settings type. For more information, see
--   <a>http://www.yesodweb.com/book/settings-types</a>.
data Entry

-- | An optional haskell name. If the name is present, a variable of type
--   <tt>Route <a>EmbeddedStatic</a></tt> with the given name will be
--   created which points to this resource.
ebHaskellName :: Entry -> Maybe Name

-- | The location to serve the resource from.
ebLocation :: Entry -> Location

-- | The mime type of the resource.
ebMimeType :: Entry -> MimeType

-- | If the development argument to <a>mkEmbeddedStatic</a> is False, then
--   at compile time this action will be executed to load the content.
--   During development, this action will not be executed.
ebProductionContent :: Entry -> IO ByteString

-- | This must be a template haskell expression of type <tt>IO
--   <a>ByteString</a></tt>. If the development argument to
--   <a>mkEmbeddedStatic</a> is True, this action is executed on every
--   request to compute the content. Most of the time,
--   <a>ebProductionContent</a> and <a>ebDevelReload</a> should be the same
--   action but occasionally you might want additional processing inside
--   the <a>ebProductionContent</a> function like javascript/css
--   minification to only happen when building for production.
ebDevelReload :: Entry -> ExpQ

-- | Occasionally, during development an entry needs extra files/resources
--   available that are not present during production (for example, image
--   files that are embedded into the CSS at production but left unembedded
--   during development). If present, <tt>ebDevelExtraFiles</tt> must be a
--   template haskell expression of type <tt>[<a>Text</a>] -&gt; IO (Maybe
--   (<a>MimeType</a>, <a>ByteString</a>))</tt>. That is, a function taking
--   as input the list of path pieces and optionally returning a mime type
--   and content.
ebDevelExtraFiles :: Entry -> Maybe ExpQ
instance Data.Default.Class.Default Yesod.EmbeddedStatic.Types.Entry


-- | A generator is executed at compile time to load a list of entries to
--   embed into the subsite. This module contains several basic generators,
--   but the design of generators and entries is such that it is
--   straightforward to make custom generators for your own specific
--   purposes, see <a>this section</a>.
module Yesod.EmbeddedStatic.Generators

-- | A location is a relative path within the static subsite at which
--   resource(s) are made available. The location can include slashes to
--   simulate directories but must not start or end with a slash.
type Location = String

-- | Embed a single file. Equivalent to passing the same string twice to
--   <a>embedFileAt</a>.
embedFile :: FilePath -> Generator

-- | Embed a single file at a given location within the static subsite and
--   generate a route variable based on the location via <a>pathToName</a>.
--   The <tt>FilePath</tt> must be a relative path to the directory in
--   which you run <tt>cabal build</tt>. During development, the file
--   located at this filepath will be reloaded on every request. When
--   compiling for production, the contents of the file will be embedded
--   into the executable and so the file does not need to be distributed
--   along with the executable.
embedFileAt :: Location -> FilePath -> Generator

-- | Embed all files in a directory into the static subsite.
--   
--   Equivalent to passing the empty string as the location to
--   <a>embedDirAt</a>, so the directory path itself is not part of the
--   resource locations (and so also not part of the generated route
--   variable names).
embedDir :: FilePath -> Generator

-- | Embed all files in a directory to a given location within the static
--   subsite.
--   
--   The directory tree rooted at the <a>FilePath</a> (which must be
--   relative to the directory in which you run <tt>cabal build</tt>) is
--   embedded into the static subsite at the given location. Also, route
--   variables will be created based on the final location of each file.
--   For example, if a directory "static" contains the files
--   
--   <ul>
--   <li>css/bootstrap.css</li>
--   <li>js/jquery.js</li>
--   <li>js/bootstrap.js</li>
--   </ul>
--   
--   then <tt>embedDirAt "somefolder" "static"</tt> will
--   
--   <ul>
--   <li>Make the file <tt>static/css/bootstrap.css</tt> available at the
--   location <tt>somefolder/css/bootstrap.css</tt> within the static
--   subsite and similarly for the other two files.</li>
--   <li>Create variables <tt>somefolder_css_bootstrap_css</tt>,
--   <tt>somefolder_js_jquery_js</tt>, <tt>somefolder_js_bootstrap_js</tt>
--   all of type <tt>Route EmbeddedStatic</tt>.</li>
--   <li>During development, the files will be reloaded on every request.
--   During production, the contents of all files will be embedded into the
--   executable.</li>
--   <li>During development, files that are added to the directory while
--   the server is running will not be detected. You need to recompile the
--   module which contains the call to <tt>mkEmbeddedStatic</tt>. This will
--   also generate new route variables for the new files.</li>
--   </ul>
embedDirAt :: Location -> FilePath -> Generator

-- | Concatinate a list of files and embed it at the location. Equivalent
--   to passing <tt>return</tt> to <a>concatFilesWith</a>.
concatFiles :: Location -> [FilePath] -> Generator

-- | Concatinate a list of files into a single <a>ByteString</a>, run the
--   resulting content through the given function, embed it at the given
--   location, and create a haskell variable name for the route based on
--   the location.
--   
--   The processing function is only run when compiling for production, and
--   the processing function is executed at compile time. During
--   development, on every request the files listed are reloaded,
--   concatenated, and served as a single resource at the given location
--   without being processed.
concatFilesWith :: Location -> (ByteString -> IO ByteString) -> [FilePath] -> Generator

-- | Convienient rexport of <a>minifym</a> with a type signature to work
--   with <a>concatFilesWith</a>.
jasmine :: ByteString -> IO ByteString

-- | Use <a>UglifyJS2</a> to compress javascript. Assumes <tt>uglifyjs</tt>
--   is located in the path and uses options <tt>["-m", "-c"]</tt> to both
--   mangle and compress and the option "-" to cause uglifyjs to read from
--   standard input.
uglifyJs :: ByteString -> IO ByteString

-- | Use <a>YUI Compressor</a> to compress javascript. Assumes a script
--   <tt>yuicompressor</tt> is located in the path. If not, you can still
--   use something like
--   
--   <pre>
--   compressTool "java" ["-jar", "/path/to/yuicompressor.jar", "--type", "js"]
--   </pre>
yuiJavascript :: ByteString -> IO ByteString

-- | Use <a>YUI Compressor</a> to compress CSS. Assumes a script
--   <tt>yuicompressor</tt> is located in the path.
yuiCSS :: ByteString -> IO ByteString

-- | Use <a>Closure</a> to compress javascript using the default options.
--   Assumes a script <tt>closure</tt> is located in the path. If not, you
--   can still run using
--   
--   <pre>
--   compressTool "java" ["-jar", "/path/to/compiler.jar"]
--   </pre>
closureJs :: ByteString -> IO ByteString

-- | Helper to convert a process into a compression function. The process
--   should be set up to take input from standard input and write to
--   standard output.
compressTool :: FilePath -> [String] -> ByteString -> IO ByteString

-- | Try a list of processing functions (like the compressions above) one
--   by one until one succeeds (does not raise an exception). Once a
--   processing function succeeds, none of the remaining functions are
--   used. If none succeeds, the input is just returned unprocessed. This
--   is helpful if you are distributing code on hackage and do not know
--   what compressors the user will have installed. You can list several
--   and they will be tried in order until one succeeds.
tryCompressTools :: [ByteString -> IO ByteString] -> ByteString -> IO ByteString

-- | Clean up a path to make it a valid haskell name by replacing all
--   non-letters and non-numbers by underscores. In addition, if the path
--   starts with a capital letter or number add an initial underscore.
pathToName :: FilePath -> Name


-- | Serve static files from a Yesod app.
--   
--   This is great for developing your application, but also for a
--   dead-simple deployment. Caching headers are automatically taken care
--   of.
--   
--   If you are running a proxy server (like Apache or Nginx), you may want
--   to have that server do the static serving instead.
--   
--   In fact, in an ideal setup you'll serve your static files from a
--   separate domain name to save time on transmitting cookies. In that
--   case, you may wish to use <a>urlParamRenderOverride</a> to redirect
--   requests to this subsite to a separate domain name.
--   
--   Note that this module's static subsite ignores all files and
--   directories that are hidden by Unix conventions (i.e. start with a
--   dot, such as <tt>".ssh"</tt>) and the directory "tmp" on the root of
--   the directory with static files.
module Yesod.Static

-- | Type used for the subsite with static contents.
newtype Static
Static :: StaticSettings -> Static

-- | The <a>type-safe URLs</a> associated with a site argument.
type StaticRoute = Route Static

-- | Produce a default value of <a>Static</a> for a given file folder.
--   
--   Does not have index files or directory listings. The static files'
--   contents <i>must not</i> change, however new files can be added.
static :: FilePath -> IO Static

-- | Same as <a>static</a>, but does not assumes that the files do not
--   change and checks their modification time whenever a request is made.
staticDevel :: FilePath -> IO Static

-- | Combine multiple CSS files together. Common usage would be:
--   
--   <pre>
--   &gt;&gt;&gt; combineStylesheets' development def 'StaticR [style1_css, style2_css]
--   </pre>
--   
--   Where <tt>development</tt> is a variable in your site indicated
--   whether you are in development or production mode.
--   
--   Since 1.2.0
combineStylesheets' :: Bool -> CombineSettings -> Name -> [Route Static] -> Q Exp

-- | Combine multiple JS files together. Common usage would be:
--   
--   <pre>
--   &gt;&gt;&gt; combineScripts' development def 'StaticR [script1_js, script2_js]
--   </pre>
--   
--   Where <tt>development</tt> is a variable in your site indicated
--   whether you are in development or production mode.
--   
--   Since 1.2.0
combineScripts' :: Bool -> CombineSettings -> Name -> [Route Static] -> Q Exp

-- | Data type for holding all settings for combining files.
--   
--   This data type is a settings type. For more information, see:
--   
--   <a>http://www.yesodweb.com/book/settings-types</a>
--   
--   Since 1.2.0
data CombineSettings

-- | File path containing static files.
--   
--   Default: static
--   
--   Since 1.2.0
csStaticDir :: CombineSettings -> FilePath

-- | Post processing to be performed on CSS files.
--   
--   Default: Pass-through.
--   
--   Since 1.2.0
csCssPostProcess :: CombineSettings -> [FilePath] -> ByteString -> IO ByteString

-- | Post processing to be performed on Javascript files.
--   
--   Default: Pass-through.
--   
--   Since 1.2.0
csJsPostProcess :: CombineSettings -> [FilePath] -> ByteString -> IO ByteString

-- | Pre-processing to be performed on CSS files.
--   
--   Default: convert all occurences of <i>static</i> to ../
--   
--   Since 1.2.0
csCssPreProcess :: CombineSettings -> Text -> IO Text

-- | Pre-processing to be performed on Javascript files.
--   
--   Default: Pass-through.
--   
--   Since 1.2.0
csJsPreProcess :: CombineSettings -> Text -> IO Text

-- | Subfolder to put combined files into.
--   
--   Default: combined
--   
--   Since 1.2.0
csCombinedFolder :: CombineSettings -> FilePath

-- | Template Haskell function that automatically creates routes for all of
--   your static files.
--   
--   For example, if you used
--   
--   <pre>
--   staticFiles "static/"
--   </pre>
--   
--   and you had files <tt>"static/style.css"</tt> and
--   <tt>"static/js/script.js"</tt>, then the following top-level
--   definitions would be created:
--   
--   <pre>
--   style_css    = StaticRoute ["style.css"]    []
--   js_script_js = StaticRoute ["js", "script.js"] []
--   </pre>
--   
--   Note that dots (<tt>.</tt>), dashes (<tt>-</tt>) and slashes
--   (<tt>/</tt>) are replaced by underscores (<tt>_</tt>) to create valid
--   Haskell identifiers.
staticFiles :: FilePath -> Q [Dec]

-- | Same as <a>staticFiles</a>, but takes an explicit list of files to
--   create identifiers for. The files path given are relative to the
--   static folder. For example, to create routes for the files
--   <tt>"static/js/jquery.js"</tt> and
--   <tt>"static/css/normalize.css"</tt>, you would use:
--   
--   <pre>
--   staticFilesList \"static\" [\"js\/jquery.js\", \"css\/normalize.css\"]
--   </pre>
--   
--   This can be useful when you have a very large number of static files,
--   but only need to refer to a few of them from Haskell.
staticFilesList :: FilePath -> [FilePath] -> Q [Dec]

-- | Same as <a>staticFiles</a>, but doesn't append an ETag to the query
--   string.
--   
--   Using <a>publicFiles</a> will speed up the compilation, since there
--   won't be any need for hashing files during compile-time. However,
--   since the ETag ceases to be part of the URL, the <a>Static</a> subsite
--   won't be able to set the expire date too far on the future. Browsers
--   still will be able to cache the contents, however they'll need send a
--   request to the server to see if their copy is up-to-date.
publicFiles :: FilePath -> Q [Dec]
base64md5 :: ByteString -> String

-- | Produce a <a>Static</a> based on embedding all of the static files'
--   contents in the executable at compile time.
--   
--   You should use <a>Yesod.EmbeddedStatic</a> instead, it is much more
--   powerful.
--   
--   Nota Bene: if you replace the scaffolded <a>static</a> call in
--   Settings/StaticFiles.hs you will need to change the scaffolded
--   addStaticContent. Otherwise, some of your assets will be 404'ed. This
--   is because by default yesod will generate compile those assets to
--   <tt>static/tmp</tt> which for <a>static</a> is fine since they are
--   served out of the directory itself. With embedded static, that will
--   not work. You can easily change <tt>addStaticContent</tt> to <tt>_ _ _
--   -&gt; return Nothing</tt> as a workaround. This will cause yesod to
--   embed those assets into the generated HTML file itself.
embed :: FilePath -> Q Exp
instance GHC.Read.Read (Yesod.Routes.Class.Route Yesod.Static.Static)
instance GHC.Show.Show (Yesod.Routes.Class.Route Yesod.Static.Static)
instance GHC.Classes.Eq (Yesod.Routes.Class.Route Yesod.Static.Static)
instance Yesod.Routes.Class.RenderRoute Yesod.Static.Static
instance Yesod.Routes.Class.ParseRoute Yesod.Static.Static
instance (Control.Monad.Catch.MonadThrow m, Control.Monad.IO.Class.MonadIO m, Control.Monad.Trans.Control.MonadBaseControl GHC.Types.IO m) => Yesod.Core.Class.Dispatch.YesodSubDispatch Yesod.Static.Static (Yesod.Core.Types.HandlerT master m)
instance Data.Default.Class.Default Yesod.Static.CombineSettings


-- | A subsite which serves static content which is embedded at compile
--   time.
--   
--   At compile time, you supply a list of files, directories, processing
--   functions (like javascript minification), and even custom content
--   generators. You can also specify the specific relative locations
--   within the static subsite where these resources should appear. The
--   <a>mkEmbeddedStatic</a> function then computes the resources and
--   embeds them directly into the executable at compile time, so that the
--   original files do not need to be distributed along with the
--   executable. The content is also compressed and hashed at compile time,
--   so that during runtime the compressed content can be sent directly on
--   the wire with the appropriate HTTP header. The precomputed hash is
--   used for an ETag so the client does not redownload the content
--   multiple times. There is also a development mode which does not embed
--   the contents but recomputes it on every request. A simple example
--   using an embedded static subsite is <a>static-embed.hs</a>.
--   
--   To add this to a scaffolded project, replace the code in
--   <tt>Settings/StaticFiles.hs</tt> with a call to
--   <a>mkEmbeddedStatic</a> with the list of all your generators, use the
--   type <a>EmbeddedStatic</a> in your site datatype for
--   <tt>getStatic</tt>, update the route for <tt>/static</tt> to use the
--   type <a>EmbeddedStatic</a>, use <a>embedStaticContent</a> for
--   <a>addStaticContent</a> in <tt>Foundation.hs</tt>, use the routes
--   generated by <a>mkEmbeddedStatic</a> and exported by
--   <tt>Settings/StaticFiles.hs</tt> to link to your static content, and
--   finally update <tt>Application.hs</tt> use the variable binding
--   created by <a>mkEmbeddedStatic</a> which contains the created
--   <a>EmbeddedStatic</a>.
--   
--   It is recommended that you serve static resources from a separate
--   domain to save time on transmitting cookies. You can use
--   <a>urlParamRenderOverride</a> to do so, by redirecting routes to this
--   subsite to a different domain (but the same path) and then pointing
--   the alternative domain to this server. In addition, you might consider
--   using a reverse proxy like varnish or squid to cache the static
--   content, but the embedded content in this subsite is cached and served
--   directly from memory so is already quite fast.
module Yesod.EmbeddedStatic

-- | The subsite for the embedded static file server.
data EmbeddedStatic

-- | Construct a route to an embedded resource.
embeddedResourceR :: [Text] -> [(Text, Text)] -> Route EmbeddedStatic

-- | Creates an <a>EmbeddedStatic</a> by running, at compile time, a list
--   of generators. Each generator produces a list of entries to embed into
--   the executable.
--   
--   This template haskell splice creates a variable binding holding the
--   resulting <a>EmbeddedStatic</a> and in addition creates variable
--   bindings for all the routes produced by the generators. For example,
--   if a directory called static has the following contents:
--   
--   <ul>
--   <li>js/jquery.js</li>
--   <li>css/bootstrap.css</li>
--   <li>img/logo.png</li>
--   </ul>
--   
--   then a call to
--   
--   <pre>
--   #ifdef DEVELOPMENT
--   #define DEV_BOOL True
--   #else
--   #define DEV_BOOL False
--   #endif
--   mkEmbeddedStatic DEV_BOOL "myStatic" [embedDir "static"]
--   </pre>
--   
--   will produce variables
--   
--   <pre>
--   myStatic :: EmbeddedStatic
--   js_jquery_js :: Route EmbeddedStatic
--   css_bootstrap_css :: Route EmbeddedStatic
--   img_logo_png :: Route EmbeddedStatic
--   </pre>
mkEmbeddedStatic :: Bool -> String -> [Generator] -> Q [Dec]

-- | Use this for <a>addStaticContent</a> to have the widget static content
--   be served by the embedded static subsite. For example,
--   
--   <pre>
--   import Yesod
--   import Yesod.EmbeddedStatic
--   import Text.Jasmine (minifym)
--   
--   data MySite = { ..., getStatic :: EmbeddedStatic, ... }
--   
--   mkYesod "MySite" [parseRoutes|
--   ...
--   /static StaticR EmbeddedStatic getStatic
--   ...
--   |]
--   
--   instance Yesod MySite where
--       ...
--       addStaticContent = embedStaticContent getStatic StaticR mini
--           where mini = if development then Right else minifym
--       ...
--   </pre>
embedStaticContent :: Yesod site => (site -> EmbeddedStatic) -> (Route EmbeddedStatic -> Route site) -> (ByteString -> Either a ByteString) -> AddStaticContent site
instance Yesod.Core.Class.Yesod.Yesod master => Yesod.Core.Class.Dispatch.YesodSubDispatch Yesod.EmbeddedStatic.Internal.EmbeddedStatic (Yesod.Core.Types.HandlerT master GHC.Types.IO)


-- | Manipulate CSS urls.
--   
--   <ul>
--   <li>Make relative urls absolute (useful when combining assets)</li>
--   </ul>
module Yesod.EmbeddedStatic.Css.AbsoluteUrl

-- | Equivalent to passing the same string twice to <a>absoluteUrlsAt</a>.
absoluteUrls :: FilePath -> Generator

-- | Equivalent to passing <tt>return</tt> to <a>absoluteUrlsWith</a>.
absoluteUrlsAt :: Location -> FilePath -> Generator

-- | Automatically make relative urls absolute
--   
--   During development, leave CSS as is.
--   
--   When CSS is organized into a directory structure, it will work
--   properly for individual requests for each file. During production, we
--   want to combine and minify CSS as much as possible. The combination
--   process combines files from different directories, messing up relative
--   urls. This pre-processor makes relative urls absolute
absoluteUrlsWith :: Location -> FilePath -> Maybe (CssGeneration -> IO ByteString) -> Generator

-- | Anchors relative CSS image urls
absCssUrlsFileProd :: FilePath -> FilePath -> IO ByteString
absCssUrlsProd :: FilePath -> Text -> Text
