Shakespeare

https://github.com/yesodweb/shakespeare
Admin
Shakespeare is a family of type-safe, compile-time interpolated template languages for Haskell that...
Tokens:64,037
Snippets:534
Trust Score:6.9
License:MIT
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### maybeH example

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-hamlet.md

Example usage of the maybeH helper, which runs an action on a Just value or a fallback on Nothing.

```haskell
maybeH (Just 5) (\n -> putStrLn (show n)) Nothing
```

--------------------------------

### mkMessageOpts example

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-shakespeare-i18n.md

Fully parameterized generator. The example disables record constructors via setUseRecordCons and passes the master type, type name, folder, and language.

```haskell
mkMessageOpts (setUseRecordCons False defMakeMessageOpts) "App" "App" "messages" "en"
```

--------------------------------

### mkMessageFor example

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-shakespeare-i18n.md

Creates a RenderMessage instance for an existing data type. The example defines an existing type and then calls mkMessageFor with the master type, existing type name, folder, and language.

```haskell
data Existing = ExistingText

mkMessageFor "App" "Existing" "messages" "en"
```

--------------------------------

### Message file format example (en.msg)

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-shakespeare-i18n.md

Example message format for the .msg file. It uses `ConstructorName: message text`, with optional variable interpolation using `#{var}`.

```text
WelcomeHomepage: Welcome to the homepage
EntryCreated title@Text: Your new blog post, #{title}, has been created
```

--------------------------------

### condH example

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-hamlet.md

Example usage of the condH helper, which checks a boolean condition and runs the corresponding action.

```haskell
condH [(isAdmin, putStrLn "admin")] (Just (putStrLn "guest"))
```

--------------------------------

### Full runtime Hamlet example

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-hamlet-runtime.md

Parses a template with variables, builds a Map of HamletData values, renders it, and prints the HTML. Requires OverloadedStrings and the listed imports.

```haskell
{-# LANGUAGE OverloadedStrings #-}
import Text.Hamlet.Runtime
import qualified Data.Map as Map
import Text.Blaze.Html.Renderer.String (renderHtml)

main :: IO ()
main = do
    template <- parseHamletTemplate defaultHamletSettings $ unlines
        [ "<p>Hello, #{name}"
        , "$if hungry"
        , "  <p>Available food:"
        , "  <ul>"
        , "    $forall food <- foods"
        , "      <li>#{food}"
        ]
    let hamletDataMap = Map.fromList
            [ ("name", "Michael")
            , ("hungry", toHamletData True)
            , ("foods", toHamletData ["Apples", "Bananas", "Carrots"])
            ]
    html <- renderHamletTemplate template hamletDataMap
    putStrLn $ renderHtml html
```

--------------------------------

### renderTextUrl usage example

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-shakespeare-text.md

Shows how to apply a URL renderer to a text template using renderTextUrl, converting the resulting Builder to lazy Text.

```haskell
renderTextUrl (\_ _ -> "http://example.com") (textTemplate)
```

--------------------------------

### mkMessage generator example

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-shakespeare-i18n.md

Generates a message datatype and RenderMessage instance from .msg files in the given folder. The example shows the required TemplateHaskell pragma and import, and the generated data type and instance are shown in comments.

```haskell
{-# LANGUAGE TemplateHaskell #-}
import Text.Shakespeare.I18N

mkMessage "App" "messages" "en"
-- generates: data AppMessage = AppMsgWelcomeHomepage { welcomeHomepageMessage :: Text }
-- plus instance RenderMessage App AppMessage
```

--------------------------------

### Example usage of parseHamletRT and renderHamletRT

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-hamlet-runtime.md

Shows how to parse a simple Hamlet template and render it with a variable binding. Uses defaultHamletSettings and a dummy URL renderer.

```haskell
import Text.Hamlet.RT
import Text.Hamlet (defaultHamletSettings)

main :: IO ()
main = do
    rt <- parseHamletRT defaultHamletSettings "<p>#{name}"
    html <- renderHamletRT rt [(["name"], HDHtml "world")] (error "no urls")
    print html
```

--------------------------------

### coffee QuasiQuoter: Inline CoffeeScript template with example

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-coffee.md

Shows the `coffee` quasi-quoter in a specific. It requires `QuasiQuotes` and the `Text.Coffee` import, plus `Text.Julius` for the `JavascriptUrl` type and renderer. The example defines a template that prints the sum of a variable `x` (a pulled variable) and a home constant `b`. The compiled form shows the quoted) and the compiled form shows how `%{x}` is replaced with `shakespeare_var_a` and the body is wrapped in a function.

```haskell
{-# LANGUAGE QuasiQuotes #-}
import Text.Coffee
import Text.Julius (JavascriptUrl, renderJavascriptUrl)

coffeeTpl :: JavascriptUrl MyRoute
coffeeTpl = [coffee|
    b = 1
    console.log(%{x} + b)
|]
```

```haskell
-- compiled form (see below); this is a comment:
-- ;(function(shakespeare_var_a){
--   var b = 1;
--   console.log(shakespeare_var_a + b);
-- })(a);
```

--------------------------------

### toAttributes example

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-hamlet.md

Example usage of the toAttributes function, converting a tuple to a list of attribute pairs.

```haskell
toAttributes ("class", "active")  -- [("class","active")]
```

--------------------------------

### Usage of shamlet, hamlet, and ihamlet quasi-quoters

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-hamlet.md

Shows how to enable the QuasiQuotes extension and use the shamlet, hamlet, and ihamlet quasi-quoters to create Html, HtmlUrl, and HtmlUrlI18n values. Requires defining a route type and a Render instance; the example defines MyRoute with Home and a render function.

```haskell
{-# LANGUAGE QuasiQuotes #-}
import Text.Hamlet
import Text.Blaze.Html.Renderer.String (renderHtml)

data MyRoute = Home

render :: Render MyRoute
render Home _ = "/home"

html :: Html
html = [shamlet|<p>Hello #{var}|]

urlHtml :: HtmlUrl MyRoute
urlHtml = [hamlet|<a href=@{Home}>Home</a>|]

i18nHtml :: HtmlUrlI18n MyMsg MyRoute
i18nHtml = [ihamlet|@{Home} _{Greeting}|]
```

--------------------------------

### sbt bar-alignment example

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-shakespeare-text.md

Demonstrates the bar-alignment behavior of `sbt` (and `lbt`). Each line drops everything up to and including the first `|`, and blank leading lines collapse. The result is strict `TS.Text`.

```haskell
-- | All lines after the first are aligned: the pipe column is stripped.
s = [sbt|
    |line one
    |line two
    |]
-- s == "line one\nline two\n" :: Text
```

--------------------------------

### text quasi-quoter URL interpolation example

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-shakespeare-text.md

Shows the `text` quasi-quoter, which keeps URL/mixin interpolation with `@{...}` and wraps into `RenderUrl url -> Builder`. It is not `justVarInterpolation`. The example renders a URL using `renderTextUrl`.

```haskell
data MyRoute = Home

renderUrl :: RenderUrl MyRoute
renderUrl Home _ = "/home"

tpl :: TextUrl MyRoute
tpl = [text|Go to @{Home} now|]

main :: IO ()
main = print (renderTextUrl renderUrl tpl)
-- "Go to /home now"
```

--------------------------------

### Lucius quasiquoter with mkSize

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-lucius.md

Examples of using the lucius quasiquoter with mkSize for sizes. Requires QuasiQuotes and TemplateHaskell extensions.

```haskell
{-# LANGUAGE QuasiQuotes, TemplateHaskell #-}
[lucius|p{margin:$(mkSize "2em")}|]          -- p{margin:2em}
[lucius|body{width:$(mkSize "50%")}|]        -- body{width:50.000000%}
```

--------------------------------

### Render a JavascriptUrl with a dummy renderer in main

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-julius.md

Renders the jsTpl template with a dummy renderer that always returns "/home" and prints the result. This is a standalone usage example without type-safe routes.

```haskell
main :: IO ()
main = TL.putStrLn (renderJavascriptUrl (\_ _ -> "/home") jsTpl)
```

--------------------------------

### stext quasi-quoter example

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-shakespeare-text.md

Shows the basic usage of the `stext` quasi-quoter. It produces lazy `TL.Text` and interpolates variables with `#{...}`. The output is printed to stdout.

```haskell
{-# LANGUAGE QuasiQuotes #-}
import Text.Shakespeare.Text
import qualified Data.Text.Lazy.IO as TLIO

main :: IO ()
main = do
    let x = "world"
    TLIO.putStrLn [stext|Hello, #{x}!|]
-- Hello, world!
```

--------------------------------

### Interpolate raw JavaScript with rawJS

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-julius.md

Shows how to use rawJS to insert raw JavaScript code without escaping. The example defines a function and interpolates it into a template.

```haskell
let code = "function () { return 1; }" :: Text
    js'  = [julius|var f = #{rawJS code};|]
```

--------------------------------

### luciusMixin quasi-quoter example

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-lucius.md

Creates a Mixin value using the luciusMixin quasi-quoter. The body is wrapped as mixin{...} before parsing.

```haskell
mymixin :: Mixin
mymixin = [luciusMixin|foo{color:red}^{other}|]
```

--------------------------------

### Universal Text instance for RenderMessage

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-shakespeare-i18n.md

This provides the example definition that shows the `Text` instance of `RenderMessage` for a universal text message; the source is given as `(110, 115)` matching) but the actual code snippet is not visible. The snippet is the intended for the source line that defines the universal `Message` instance.

```haskell
instance master ~ master' => RenderMessage master (SomeMessage master')
```

--------------------------------

### lucius quasi-quoter example with renderCssUrl

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-lucius.md

Expression-only quasi-quoter generating a CssUrl value. Requires QuasiQuotes language extension and a renderUrl function. Outputs rendered CSS with URL interpolation.

```haskell
{-# LANGUAGE QuasiQuotes #-}
import Text.Lucius
import qualified Data.Text.Lazy as TL

data MyRoute = Home

renderUrl :: CssUrl MyRoute  -- (url -> [(Text,Text)] -> Text)
renderUrl Home _ = "/home"

css :: CssUrl MyRoute
css = [lucius|foo{bar:baz;background:url(@{Home})}|]

main :: IO ()
main = TL.putStrLn (renderCssUrl renderUrl css)
-- foo{bar:baz;background:url("/home")}
```

--------------------------------

### royFile: Compile-time template file loading

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-roy.md

Uses the `royFile` function to read and compile a Roy template file at compile time. The example shows the splice syntax with a file path and a type annotation.

```haskell
$(royFile "static/main.roy") :: JavascriptUrl MyRoute
```

--------------------------------

### shakespeareFromString: Compile template string to Q Exp

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-shakespeare.md

Compiles a template string, running preFilter first and stripping \r characters on Windows. This is what quoteExp of shakespeare calls. The example shows using it with Language.Haskell.TH.

```haskell
import Language.Haskell.TH

exp <- shakespeareFromString settings "Hello #{name}"
```

--------------------------------

### shakespeare: Create expression-only quasi-quoter

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-shakespeare.md

Creates an expression-only quasi-quoter from settings. Requires the QuasiQuotes language extension. The example shows configuring toBuilder, wrap, and unwrap, and includes a comment showing usage with RenderUrl.

```haskell
{-# LANGUAGE QuasiQuotes #-}
import Text.Shakespeare
import qualified Data.Text.Lazy as TL

myQQ :: QuasiQuoter
myQQ = shakespeare defaultShakespeareSettings { toBuilder = [|Data.Text.Lazy.Builder.fromText|], wrap = [|id|], unwrap = [|id|] }

-- [myQQ|Hello #{name} @{url}|] :: RenderUrl url -> Builder
```

--------------------------------

### coffeeFile: Compile a CoffeeScript template files

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-coffee.md

Reads the given CoffeeScript file at compile time and generates a function template. The example shows the splice creating a `JavascriptUrl MyRoute` value.

```haskell
$(coffeeFile "static/main.coffee") :: JavascriptUrl MyRoute
```

--------------------------------

### cassius QuasiQuoter usage with renderCssUrl

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-cassius.md

Complete example of using the `cassius` QuasiQuoter to define a `CssUrl` value. The template uses indentation (two spaces per level) and interpolates `colorRed` and the `Home` route via `url(@{Home})`. The output is rendered with `renderCssUrl` and shows the generated CSS.

```haskell
{-# LANGUAGE QuasiQuotes #-}
import Text.Cassius
import qualified Data.Text.Lazy as TL

data MyRoute = Home

renderUrl :: MyRoute -> [(Text, Text)] -> Text
renderUrl Home _ = "/home"

css :: CssUrl MyRoute
css = [cassius|
    foo
        bar: baz
        color: #{colorRed}
        background-image: url(@{Home})
|]

main :: IO ()
main = TL.putStrLn $ renderCssUrl renderUrl css
-- foo {
--     bar: baz;
--     color: #f00;
--     background-image: url("/home");
-- }
```

--------------------------------

### tscJSX QuasiQuoter usage example

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-typescript.md

Example of using the tscJSX QuasiQuoter to inline TypeScript with JSX syntax. The template contains a JSX element and is compiled with JSX support.

```haskell
tplJSX :: JavascriptUrl MyRoute
tplJSX = [tscJSX|
    var el = <div className="x">hello</div>;
|]
```

--------------------------------

### tsc QuasiQuoter usage example

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-typescript.md

Example of using the tsc QuasiQuoter to inline TypeScript. The template is wrapped in a function, and interpolation uses #{a}. The output shows the generated JavaScript with the variable renamed to shakespeare_var_a.

```haskell
{-# LANGUAGE QuasiQuotes #-}
import Text.TypeScript
import Text.Julius (JavascriptUrl, renderJavascriptUrl)

data MyRoute = Home

tpl :: JavascriptUrl MyRoute
tpl = [tsc|
    var b = 1
    console.log(#{a} + b)
|]

main :: IO IO
main = putStrLn $ TL.unpack (renderJavascriptUrl (\_ _ -> "/") tpl)
-- ;(function(shakespeare_var_a){
--   var b = 1;
--   console.log(shakespeare_var_a + b);
-- })(a);
```

--------------------------------

### codegenSt quasi-quoter example

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-shakespeare-text.md

Illustrates the `codegenSt` quasi-quoter, a strict `TS.Text` variant of `codegen`. It uses codegen interpolation characters `~{...}` for variables, `*{...}` for URLs, and `&{...}` for ints. This is a hypothetical snippet generation example.

```haskell
$(codegenSt|module Foo where ~{imports}|)  -- hypothetical snippet generation
```

--------------------------------

### textFileDebug :: FilePath -> Q Exp

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-shakespeare-text.md

`= textFileReload`. **Deprecated** — "Please use textFileReload instead".

```APIDOC
## textFileDebug :: FilePath -> Q Exp

### Description
`= textFileReload`. **Deprecated** — "Please use textFileReload instead".

### Method
Template Haskell function

### Parameters
- **FilePath** - The path to the file to compile.

### Response
Returns a `Q Exp` that, when spliced, produces a value of type `TextUrl url`.

```

--------------------------------

### Lucius quasiquoter with color

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-lucius.md

Example of using the lucius quasiquoter with a color interpolation. Renders to body{color:#f00}.

```haskell
[lucius|body{color:#{colorRed}}|]  -- body{color:#f00}
```

--------------------------------

### coffeeFileReload :: FilePath -> Q Exp

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-coffee.md

Reads the template file on every call using unsafePerformIO, allowing rapid iteration during development. Not for production use.

```APIDOC
## coffeeFileReload :: FilePath -> Q Exp

### Description
Reads the template file on every call using `unsafePerformIO`, allowing rapid iteration during development. Not for production use.

### Usage
```haskell
$(coffeeFileReload "static/main.coffee") :: JavascriptUrl MyRoute
```
```

--------------------------------

### preFilter :: Maybe FilePath -> ShakespeareSettings -> String -> IO String

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-shakespeare.md

Runs pre-conversion on a template string. If `preConversion` is `Nothing`, returns the template unchanged. Otherwise rewrites variables and optionally wraps the body.

```APIDOC
## `preFilter :: Maybe FilePath -> ShakespeareSettings -> String -> IO String`

### Description
Runs pre-conversion on a template string. If `preConversion` is `Nothing`, returns the template unchanged. Otherwise rewrites variables and optionally wraps the body.

### Function Signature
```haskell
preFilter :: Maybe FilePath -> ShakespeareSettings -> String -> IO String
```

### Parameters
- **Maybe FilePath** - Used only for error reporting.
- **ShakespeareSettings** - Settings controlling pre-conversion (e.g., `preEscapeIgnoreBalanced`, `preEscapeIgnoreLine`, `WrapInsertion`).
- **String** - The template string to process.

### Return Value
The processed template string.

### Rewriting Details
- Rewrites `#{x}` → `shakespeare_var_x` (filtered to alphanumerics).
- Only `@{` and `#{`/`^{` are rewritten; any other input hits `error $ "did not expect: " <> err`.
- With `Just WrapInsertion{..}` and `addParens = True`, strips trailing semicolons/whitespace before wrapping; otherwise appends `(var1, var2);\n`.
- External-command failures are reported by `readProcessError`.
```

--------------------------------

### Desugared version of $component usage

Source: https://github.com/yesodweb/shakespeare/blob/master/ChangeLog.md

Shows the conceptual desugaring of the $component example into plain Haskell using whamlet and function application.

```haskell
^{ modalWidget $ \modal ->
     [whamlet|
       ^{ modalHeader modal [whamlet| <h1>This is the title |] }
       ^{ modalBody   modal [whamlet| <p>This is the content |] }
     |]
 }
<p>outside
```

--------------------------------

### readFileQ :: FilePath -> Q String

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-shakespeare-base.md

Reads a file at compile time, resolving the path relative to the project directory.

```APIDOC
## `readFileQ :: FilePath -> Q String`

### Description
Reads a file at compile time, converting newlines. The path is resolved relative to the project directory via `makeRelativeToProject`. @since 2.0.19.

### Parameters
- `FilePath` - The path to the file to read.

### Returns
- `Q String` - The file contents as a String in the Q monad.

### Example
haskell
str <- readFileQ "templates/foo.hamlet"


### Source
`Text/Shakespeare/Base.hs:305`
```

--------------------------------

### royFileReload :: FilePath -> Q Exp

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-roy.md

Development-only template loading that re-reads and re-compiles the file at runtime on modification. Uses `unsafePerformIO` for rapid iteration.

```APIDOC
## Function: royFileReload

### Description
Development-only template loading that re-reads and re-compiles the file at runtime on modification. Uses `unsafePerformIO` for rapid iteration.

### Signature
```haskell
royFileReload :: FilePath -> Q Exp
```

### Parameters
- **FilePath** - Path to the Roy template file.

### Notes
- This is an impure function that uses `unsafePerformIO`.
- Intended for development only; not for production use.
- Runtime failures follow the `Shakespeare` reload error model.

```

--------------------------------

### coffeeFileDebug :: FilePath -> Q Exp

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-coffee.md

Deprecated alias for coffeeFileReload. Use coffeeFileReload instead.

```APIDOC
## coffeeFileDebug :: FilePath -> Q Exp

### Description
Deprecated alias for `coffeeFileReload`. Use `coffeeFileReload` instead.

### Usage
```haskell
$(coffeeFileDebug "static/main.coffee") :: JavascriptUrl MyRoute
```
```

--------------------------------

### cassiusFileReload :: FilePath -> Q Exp

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-cassius.md

Alias for cassiusFileDebug.

```APIDOC
## cassiusFileReload :: FilePath -> Q Exp

### Description
Alias for cassiusFileDebug.
```

--------------------------------

### cassiusUsedIdentifiers identifier scanning

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-cassius.md

Example of `cassiusUsedIdentifiers` scanning a Cassius string and returning the used identifiers. The output shows the identifier `c` with type `VTPlain`.

```haskell
cassiusUsedIdentifiers "foo\n  color: #{c}"
-- [(DerefIdent (Ident "c"), VTPlain)]
```

--------------------------------

### cassiusFileDebug :: FilePath -> Q Exp

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-cassius.md

Compile-time stub plus runtime file re-parse for development only.

```APIDOC
## cassiusFileDebug :: FilePath -> Q Exp

### Description
Compile-time stub plus runtime file re-parse (development only). Uses cssFileDebug True [|parseTopLevels Unordered|] (parseTopLevels Unordered).
```

--------------------------------

### roySettings: Pre-conversion settings for Roy

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-roy.md

Defines the `roySettings` value, based on `javascriptSettings`, with `varChar` set to '#', and a `preConversion` that runs the `roy` tool with `--stdio` and `--browser` flags. The wrapper insertion uses Roy lambda syntax and adds parentheses.

```haskell
jsettings { varChar = '#'
          , preConversion = Just PreConvert {
              preConvert = ReadProcess "roy" ["--stdio", "--browser"]
            , preEscapeIgnoreBalanced = "'\""
            , preEscapeIgnoreLine = "//"
            , wrapInsertion = Just WrapInsertion {
                wrapInsertionIndent = Just "  "
              , wrapInsertionStartBegin = "(\\"
              , wrapInsertionSeparator = " "
              , wrapInsertionStartClose = " ->\n"
              , wrapInsertionEnd = ")"
              , wrapInsertionAddParens = True
              }
            }
          }
```

--------------------------------

### cassiusMixin mixin creation and usage

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-cassius.md

Example of creating a mixin with `cassiusMixin` and using it in a `cassius` template via `^{mymixin}`. The mixin defines a `.red` class with `color: red`.

```haskell
mymixin :: Mixin
mymixin = [cassiusMixin|
    .red
        color: red
|]

css :: CssUrl MyRoute
css = [cassius| .use  ^{mymixin} |]
```

--------------------------------

### textFile :: FilePath -> Q Exp

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-shakespeare-text.md

Compiles a file at compile time; value of type `TextUrl url`.

```APIDOC
## textFile :: FilePath -> Q Exp

### Description
Compiles a file at compile time; value of type `TextUrl url`.

### Method
Template Haskell function

### Parameters
- **FilePath** - The path to the file to compile.

### Request Example
```haskell
$(textFile "emailBody.text") :: TextUrl MyRoute
```

### Response
Returns a `Q Exp` that, when spliced, produces a value of type `TextUrl url`.

```

--------------------------------

### coffeeSettings: Pre-configured Pre-conversion settings

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-coffee.md

Settings that adapt `javascriptSettings` for CoffeeScript: uses `%` as variable delimiter, runs the `coffee -spb` command in a pre-conversion step, and wraps the input as an arrow function. It handles `%{a}` variables by wrapping them with `shakespeare_var_a` placeholders, ignoring quoted/backticked strings and comments, and inside the body interpolation is performed. This setting is normally internal, but exported under the `test_export` flag.

```haskell
jsettings { varChar = '%'
          , preConversion = Just PreConvert {
              preConvert = ReadProcess "coffee" ["-spb"]
            , preEscapeIgnoreBalanced = "'\"`"    -- don't insert backticks for variables already inside strings or backticks
            , preEscapeIgnoreLine = "#"           -- ignore commented lines
            , wrapInsertion = Just WrapInsertion {
                wrapInsertionIndent = Just "  "
              , wrapInsertionStartBegin = "("
              , wrapInsertionSeparator = ", "
              , wrapInsertionStartClose = ") =>"
              , wrapInsertionEnd = ""
              , wrapInsertionAddParens = False
              }
            }
          }
```

--------------------------------

### shakespeareFile: Compile template file at compile time

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-shakespeare.md

Reads the file at compile time via readFileRecompileQ, tracking it as a GHC dependency, and compiles it. The example shows a splice with a RenderUrl type.

```haskell
$(shakespeareFile settings "foo.julius") :: RenderUrl url -> Builder
```

--------------------------------

### Parse deref expression with parseDeref

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-shakespeare-base.md

Example usage of parseDeref, the full expression parser. It skips leading spaces/tabs and parses a deref expression, returning a Right value with the parsed structure.

```haskell
parse (parseDeref :: UserParser () Deref) "" "Foo.bar 42"  -- Right (DerefBranch (DerefModulesIdent ["Foo"] (Ident "bar")) (DerefIntegral 42))
```

--------------------------------

### settings :: Q ShakespeareSettings

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-shakespeare-text.md

Interpolation settings for text templates, based on defaultShakespeareSettings with custom toBuilder, wrap, and unwrap.

```APIDOC
## settings :: Q ShakespeareSettings

### Description
Interpolation settings for text templates, based on `defaultShakespeareSettings` with custom `toBuilder`, `wrap`, and `unwrap`.

### Definition
```haskell
settings :: Q ShakespeareSettings
```

### Details
- `toBuilder = [|toText|]`
- `wrap = [|id|]`
- `unwrap = [|id|]`
```

--------------------------------

### shakespeareUsedIdentifiers: Extract identifiers used in template

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-shakespeare.md

Parses a template and returns every identifier it uses with its VarType, useful for systems like yesod devel. The example shows the result for a template with #{foo} and @{bar}.

```haskell
let used = shakespeareUsedIdentifiers defaultShakespeareSettings "a #{foo} @{bar}"
-- used == [ (DerefIdent (Ident "foo"), VTPlain)
--         , (DerefIdent (Ident "bar"), VTUrl) ]
```

--------------------------------

### i2b :: String -> String

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-cassius.md

Converts indentation-based Cassius into brace-based Lucius.

```APIDOC
## i2b :: String -> String

### Description
Converts indentation-based Cassius into brace-based Lucius. Lines are indented by 2 spaces per level; nested groups open a { and close with ; (or nothing if parent line already ends with ;). Comments are stripped, blank lines preserved. Tabs are not special-cased; only spaces count.
```

--------------------------------

### hamletWithSettings

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-hamlet.md

Builds a quasi-quoter from parsing rules and settings. All top-level quasi-quoters are defined via this function.

```APIDOC
## hamletWithSettings

### Description
Builds a quasi-quoter from parsing rules and settings. All top-level quasi-quoters are defined via this function (e.g. `shamlet = hamletWithSettings htmlRules defaultHamletSettings`).

### Signature
`Q HamletRules -> HamletSettings -> QuasiQuoter`

### Parameters
- **Q HamletRules** - Required - Parsing rules for the template.
- **HamletSettings** - Required - Settings for the template.

### Returns
`QuasiQuoter` - A quasi-quoter for embedding Hamlet templates.
```

--------------------------------

### Existential type SomeMessage definition

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-shakespeare-i18n.md

Defines the existential type `SomeMessage master` wrapping any message that has a message is `RenderMessage master msg` instance. It also supplies an example type for `msgs` using the wrapper.

```haskell
data SomeMessage master = forall msg. RenderMessage master msg => SomeMessage msg
```

```haskell
msgs :: [SomeMessage App]
msgs = ["hello", SomeMessage Hi]
```

--------------------------------

### cassiusFile :: FilePath -> Q Exp

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-cassius.md

Reads a file at compile time and applies the cassius quasi-quoter to its content.

```APIDOC
## cassiusFile :: FilePath -> Q Exp

### Description
Reads the file at compile time (readFileRecompileQ) and applies quoteExp cassius to its content.

### Usage
```haskell
$(cassiusFile "style.cassius") :: CssUrl MyRoute
```
```

--------------------------------

### shakespeareFile :: ShakespeareSettings -> FilePath -> Q Exp

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-shakespeare.md

Reads a template file at compile time and compiles it. The file is tracked as a GHC dependency for recompilation.

```APIDOC
## `shakespeareFile :: ShakespeareSettings -> FilePath -> Q Exp`

### Description
Reads a template file at compile time and compiles it. The file is tracked as a GHC dependency for recompilation.

### Function Signature
```haskell
shakespeareFile :: ShakespeareSettings -> FilePath -> Q Exp
```

### Parameters
- **ShakespeareSettings** - Settings controlling template compilation.
- **FilePath** - Path to the template file.

### Usage Example
```haskell
$(shakespeareFile settings "foo.julius") :: RenderUrl url -> Builder
```
```

--------------------------------

### Runtime Lucius with mixin support using luciusRTMixin

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-lucius.md

Renders a Lucius template at runtime with mixin support. The Bool argument controls minification. Scope values are RTValue, either RTVRaw or RTVMixin. The example shows a mixin being passed and rendered.

```haskell
import Text.Lucius (luciusRTMixin, RTValue (..))
import Text.Lucius (luciusMixin)  -- via QuasiQuotes

let mix = [luciusMixin|a{color:red}|]
case luciusRTMixin (TL.pack "x{^{m}}") True [("m", RTVMixin mix)] of
  Left err -> ...
  Right css -> ...  -- "x{a{color:red}}"
```

--------------------------------

### roy: Inline quasi-quoted Roy template

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-roy.md

Shows how to use the `roy` QuasiQuoter to embed a Roy template that is compiled to JavaScript at compile time. The generated value is of type `JavascriptUrl MyRoute`, and the example renders it with `renderJavascriptUrl`. The output shows the generated JavaScript wrapper.

```haskell
{-# LANGUAGE QuasiQuotes #-}
import Text.Roy
import Text.Julius (JavascriptUrl, renderJavascriptUrl)

data MyRoute = Home

renderUrl :: MyRoute -> [(Text, Text)] -> Text
renderUrl Home _ = "/home"

tpl :: JavascriptUrl MyRoute
tpl = [roy|
    let b = 1
    console.log(#{a} + b)
|]

main :: IO ()
main = putStrLn $ TL.unpack (renderJavascriptUrl renderUrl tpl)
-- ;(function(shakespeare_var_a){
--   var b = 1;
--   console.log(shakespeare_var_a + b);
-- })(a);
```

--------------------------------

### maybeH :: Monad m => Maybe v -> (v -> m ()) -> Maybe (m ()) -> m ()

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-hamlet.md

Runs the action with the value inside Just; on Nothing runs the third argument if supplied. Backs $maybe.

```APIDOC
## maybeH :: Monad m => Maybe v -> (v -> m ()) -> Maybe (m ()) -> m ()

### Description
Runs the action with the value inside Just; on Nothing runs the third argument if supplied. Backs $maybe.

### Method
function

### Signature
maybeH :: Monad m => Maybe v -> (v -> m ()) -> Maybe (m ()) -> m ()

### Parameters
- **value** (Maybe v) - Required - The optional value to pattern match on.
- **justAction** (v -> m ()) - Required - Action to run when value is Just.
- **nothingAction** (Maybe (m ())) - Optional - Action to run when value is Nothing.

### Returns
- **m ()** - The result of the chosen action.

### Example
```haskell
maybeH (Just 5) (\n -> putStrLn (show n)) Nothing
```
```

--------------------------------

### shakespeareFileReload :: ShakespeareSettings -> FilePath -> Q Exp

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-shakespeare.md

Generates a stub that re-parses the template file at runtime on every first call after modification. Intended for development use only, not for production.

```APIDOC
## `shakespeareFileReload :: ShakespeareSettings -> FilePath -> Q Exp`

### Description
Generates a stub that re-parses the template file at runtime on every first call after modification. Intended for development use only, not for production.

### Function Signature
```haskell
shakespeareFileReload :: ShakespeareSettings -> FilePath -> Q Exp
```

### Parameters
- **ShakespeareSettings** - Settings controlling template compilation.
- **FilePath** - Path to the template file.

### Notes
- Uses `shakespeareRuntime` and a process-global mtime → parsed-content cache.
- Any identifiers used by the template must be provided; the generated value is a `Shakespeare url` where each variable is looked up in the supplied `[(Deref, VarExp url)]` list.
- Raises `nothingError` if the expected variant is missing.
```

--------------------------------

### readFileQ: Read template file at compile time

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-shakespeare-base.md

Reads a template file at compile time. The path is resolved relative to the project directory via makeRelativeToProject. Available since 2.0.19.

```haskell
str <- readFileQ "templates/foo.hamlet"
```

--------------------------------

### mkMessageFor

Source: https://github.com/yesodweb/shakespeare/blob/master/_autodocs/api-reference/text-shakespeare-i18n.md

Creates a RenderMessage instance for an existing message data type using the specified folder and language.

```APIDOC
## mkMessageFor :: String -> String -> FilePath -> Lang -> Q [Dec]

### Description
Creates a `RenderMessage` instance for an **existing** data type. Given the master type, the existing message type name, and a message folder.

### Parameters
- **master** (String) - The master type name to use in the `RenderMessage` instance.
- **existingType** (String) - The name of the existing data type.
- **folder** (FilePath) - The directory containing `.msg` files.
- **lang** (Lang) - The default language.

### Returns
- `Q [Dec]` - Template Haskell code to generate the instance.

### Example
```haskell
data Existing = ExistingText

mkMessageFor "App" "Existing" "messages" "en"
```
```
Tokens:
Raw