-- 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
--   http://www.stackage.org/package/yesod-static
@package yesod-static
@version 1.6.0.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
--   http://www.yesodweb.com/book/settings-types.
data Entry

-- | An optional haskell name. If the name is present, a variable of type
--   Route EmbeddedStatic 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 mkEmbeddedStatic 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 IO
--   ByteString. If the development argument to
--   mkEmbeddedStatic is True, this action is executed on every
--   request to compute the content. Most of the time,
--   ebProductionContent and ebDevelReload should be the same
--   action but occasionally you might want additional processing inside
--   the ebProductionContent 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, ebDevelExtraFiles must be a
--   template haskell expression of type [Text] -> IO (Maybe
--   (MimeType, ByteString)). 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 this section.
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
--   embedFileAt.
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 pathToName.
--   The FilePath must be a relative path to the directory in
--   which you run cabal build. 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
--   embedDirAt, 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 FilePath (which must be
--   relative to the directory in which you run cabal build) 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
--   
--   
--   
- css/bootstrap.css
--   
- js/jquery.js
--   
- js/bootstrap.js
--   
--   
--   then embedDirAt "somefolder" "static" will
--   
--   
--   
- Make the file static/css/bootstrap.css available at the
--   location somefolder/css/bootstrap.css within the static
--   subsite and similarly for the other two files.
--   
- Create variables somefolder_css_bootstrap_css,
--   somefolder_js_jquery_js, somefolder_js_bootstrap_js
--   all of type Route EmbeddedStatic.
--   
- During development, the files will be reloaded on every request.
--   During production, the contents of all files will be embedded into the
--   executable.
--   
- 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 mkEmbeddedStatic. This will
--   also generate new route variables for the new files.
--   
embedDirAt :: Location -> FilePath -> Generator

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

-- | Concatinate a list of files into a single ByteString, 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 minifym with a type signature to work
--   with concatFilesWith.
jasmine :: ByteString -> IO ByteString

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

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

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

-- | Use Closure to compress javascript using the default options.
--   Assumes a script closure is located in the path. If not, you
--   can still run using
--   
--   
--   compressTool "java" ["-jar", "/path/to/compiler.jar"]
--   
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 urlParamRenderOverride 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 ".ssh") 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 type-safe URLs associated with a site argument.
data family Route a :: Type
type StaticRoute = Route Static

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

-- | Same as static, 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:
--   
--   
--   >>> combineStylesheets' development def 'StaticR [style1_css, style2_css]
--   
--   
--   Where development 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:
--   
--   
--   >>> combineScripts' development def 'StaticR [script1_js, script2_js]
--   
--   
--   Where development 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:
--   
--   http://www.yesodweb.com/book/settings-types
--   
--   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 static 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
--   
--   
--   staticFiles "static/"
--   
--   
--   and you had files "static/style.css" and
--   "static/js/script.js", then the following top-level
--   definitions would be created:
--   
--   
--   style_css    = StaticRoute ["style.css"]    []
--   js_script_js = StaticRoute ["js", "script.js"] []
--   
--   
--   Note that dots (.), dashes (-) and slashes
--   (/) are replaced by underscores (_) to create valid
--   Haskell identifiers.
staticFiles :: FilePath -> Q [Dec]

-- | Same as staticFiles, 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
--   "static/js/jquery.js" and
--   "static/css/normalize.css", you would use:
--   
--   
--   staticFilesList "static" ["js/jquery.js", "css/normalize.css"]
--   
--   
--   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]

-- | Similar to staticFilesList, but takes a mapping of unmunged
--   names to fingerprinted file names.
staticFilesMap :: FilePath -> Map FilePath FilePath -> Q [Dec]

-- | Similar to staticFilesMergeMap, but also generates identifiers
--   for all files in the specified directory that don't have a
--   fingerprinted version.
staticFilesMergeMap :: FilePath -> Map FilePath FilePath -> Q [Dec]

-- | Same as staticFiles, but doesn't append an ETag to the query
--   string.
--   
--   Using publicFiles 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 Static 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 Static based on embedding all of the static files'
--   contents in the executable at compile time.
--   
--   You should use Yesod.EmbeddedStatic instead, it is much more
--   powerful.
--   
--   Nota Bene: if you replace the scaffolded static 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
--   static/tmp which for static is fine since they are
--   served out of the directory itself. With embedded static, that will
--   not work. You can easily change addStaticContent to _ _ _
--   -> return Nothing 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 Data.Default.Class.Default Yesod.Static.CombineSettings
instance Yesod.Routes.Class.RenderRoute Yesod.Static.Static
instance Yesod.Routes.Class.ParseRoute Yesod.Static.Static
instance Yesod.Core.Class.Dispatch.YesodSubDispatch Yesod.Static.Static master

-- | 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
--   mkEmbeddedStatic 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 static-embed.hs.
--   
--   To add this to a scaffolded project, replace the code in
--   Settings/StaticFiles.hs with a call to
--   mkEmbeddedStatic with the list of all your generators, use the
--   type EmbeddedStatic in your site datatype for
--   getStatic, update the route for /static to use the
--   type EmbeddedStatic, use embedStaticContent for
--   addStaticContent in Foundation.hs, use the routes
--   generated by mkEmbeddedStatic and exported by
--   Settings/StaticFiles.hs to link to your static content, and
--   finally update Application.hs use the variable binding
--   created by mkEmbeddedStatic which contains the created
--   EmbeddedStatic.
--   
--   It is recommended that you serve static resources from a separate
--   domain to save time on transmitting cookies. You can use
--   urlParamRenderOverride 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 EmbeddedStatic 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 EmbeddedStatic 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:
--   
--   
--   
- js/jquery.js
--   
- css/bootstrap.css
--   
- img/logo.png
--   
--   
--   then a call to
--   
--   
--   #ifdef DEVELOPMENT
--   #define DEV_BOOL True
--   #else
--   #define DEV_BOOL False
--   #endif
--   mkEmbeddedStatic DEV_BOOL "myStatic" [embedDir "static"]
--   
--   
--   will produce variables
--   
--   
--   myStatic :: EmbeddedStatic
--   js_jquery_js :: Route EmbeddedStatic
--   css_bootstrap_css :: Route EmbeddedStatic
--   img_logo_png :: Route EmbeddedStatic
--   
mkEmbeddedStatic :: Bool -> String -> [Generator] -> Q [Dec]

-- | Use this for addStaticContent to have the widget static
--   content be served by the embedded static subsite. For example,
--   
--   
--   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
--       ...
--   
embedStaticContent :: (site -> EmbeddedStatic) -> (Route EmbeddedStatic -> Route site) -> (ByteString -> Either a ByteString) -> AddStaticContent site
instance Yesod.Core.Class.Dispatch.YesodSubDispatch Yesod.EmbeddedStatic.Internal.EmbeddedStatic master

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

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

-- | Equivalent to passing return to absoluteUrlsWith.
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
