Permalink
Browse files

Haddock first draft for Text.Coffee

  • Loading branch information...
1 parent ffb669f commit 2d43058dd0d612378935c5e140eb108f73369b3c @chreekat chreekat committed Jan 26, 2012
Showing with 42 additions and 11 deletions.
  1. +42 −11 shakespeare-js/Text/Coffee.hs
@@ -3,27 +3,37 @@
{-# LANGUAGE FlexibleInstances #-}
{-# LANGUAGE CPP #-}
{-# OPTIONS_GHC -fno-warn-missing-fields #-}
--- | A Shakespearean module for Coffeesript, introducing type-safe, compile-time
--- variable interpolation. It is very similar to "Text.Julius", save that
--- the template code is first compiled to Javascript with the system tool @coffee@.
+-- | A Shakespearean module for CoffeeScript, introducing type-safe,
+-- compile-time variable and url interpolation. It is very similar to
+-- "Text.Julius", save that the template is first compiled to Javascript with
+-- the system tool @coffee@.
--
-- To use this module, @coffee@ must be installed on your system.
--
-- @#{...}@ is the Shakespearean standard for variable interpolation, but
--- Coffeescript already uses that sequence for string interpolation. Therefore,
+-- CoffeeScript already uses that sequence for string interpolation. Therefore,
-- Shakespearean interpolation is introduced with @%{...}@.
--
+-- Further reading:
+--
-- 1. Shakespearean templates: <http://www.yesodweb.com/book/templates>
--
--- 2. Coffeescript:<http://coffeescript.org/>
+-- 2. CoffeeScript: <http://coffeescript.org/>
module Text.Coffee
- ( ToCoffee (..)
- , CoffeeUrl
- , Coffeescript
- , coffee
+ ( -- * Functions
+ -- ** Template-Reading Functions
+ -- | These QuasiQuoter and Template Haskell methods return values of
+ -- type @'CoffeeUrl' url@. See the Yesod book for details.
+ coffee
, coffeeFile
, coffeeFileDebug
+ -- ** Rendering Functions
, renderCoffee
+ -- * Datatypes
+ , Coffeescript
+ , CoffeeUrl
+ -- * Typeclass for interpolated variables
+ , ToCoffee (..)
) where
import Language.Haskell.TH.Quote (QuasiQuoter (..))
@@ -35,21 +45,36 @@ import System.Process (readProcess)
import Data.Monoid
import Text.Shakespeare
-renderCoffee :: (url -> [(TS.Text, TS.Text)] -> TS.Text) -> CoffeeUrl url -> IO TL.Text
+-- | While variable interpolation happens upon reading a template, route
+-- interpolation happens in this step. If using this module standalone, apart
+-- from type-safe routes, a dummy renderer can be used:
+--
+-- > renderCoffee (\_ _ -> undefined) coffeeUrl
+--
+-- When using Yesod, a renderer is generated for you, which can be accessed
+-- within the GHandler monad: 'Yesod.Handler.getUrlRenderParams'.
+renderCoffee
+ :: (url -> [(TS.Text, TS.Text)] -> TS.Text) -- ^ Url renderer
+ -> CoffeeUrl url -- ^ Value returned from template reader function
+ -> IO TL.Text -- ^ @CoffeeScript@ with variables and routes fully resolved
renderCoffee r s = do
out <- readProcess "coffee" ["-epb", TL.unpack $ toLazyText $ unCoffee $ s r] []
return $ TL.pack out
where unCoffee (Coffeescript c) = c
+-- | Newtype wrapper of 'Builder'.
newtype Coffeescript = Coffeescript { unCoffeescript :: Builder }
deriving Monoid
+-- | Return type of template-reading functions.
type CoffeeUrl url = (url -> [(TS.Text, TS.Text)] -> TS.Text) -> Coffeescript
--- the types that can be placed in a template
+-- | A typeclass for types that can be interpolated in CoffeeScript templates.
class ToCoffee c where
toCoffee :: c -> Builder
+
instance ToCoffee [Char] where toCoffee = fromLazyText . TL.pack
+
instance ToCoffee TS.Text where toCoffee = fromText
instance ToCoffee TL.Text where toCoffee = fromLazyText
@@ -64,17 +89,23 @@ settings = do
, unwrap = unWrapExp
}
+-- | Read inline, quasiquoted CoffeeScript.
coffee :: QuasiQuoter
coffee = QuasiQuoter { quoteExp = \s -> do
rs <- settings
quoteExp (shakespeare rs) s
}
+-- | Read in a CoffeeScript template file. This function reads the file once, at
+-- compile time.
coffeeFile :: FilePath -> Q Exp
coffeeFile fp = do
rs <- settings
shakespeareFile rs fp
+-- | Read in a CoffeeScript template file. This impure function uses
+-- unsafePerformIO to re-read the file on every call, allowing for rapid
+-- iteration.
coffeeFileDebug :: FilePath -> Q Exp
coffeeFileDebug fp = do
rs <- settings

0 comments on commit 2d43058

Please sign in to comment.