diff --git a/ChangeLog.md b/ChangeLog.md --- a/ChangeLog.md +++ b/ChangeLog.md @@ -1,3 +1,7 @@ +### 2.0.8 + +* Improve docs in Text.Hamlet [#180](https://github.com/yesodweb/shakespeare/pull/180) + ### 2.0.7 * Include aeson's JSON encoding and escape `<`, `>` and `&` to avoid XSS attacks diff --git a/Text/Hamlet.hs b/Text/Hamlet.hs --- a/Text/Hamlet.hs +++ b/Text/Hamlet.hs @@ -12,16 +12,18 @@ , xshamletFile -- * Hamlet , HtmlUrl + , Render , hamlet , hamletFile , hamletFileReload - , ihamletFileReload , xhamlet , xhamletFile -- * I18N Hamlet , HtmlUrlI18n + , Translate , ihamlet , ihamletFile + , ihamletFileReload -- * Type classes , ToAttributes (..) -- * Internal, for making more @@ -275,9 +277,18 @@ html <- [|attrsToHtml . toAttributes|] return $ hrFromHtml hr `AppE` (html `AppE` derefToExp scope d) +-- | "Simple Hamlet" quasi-quoter. May only be used to generate expressions. +-- +-- Generated expressions have type 'Html'. +-- +-- @ +-- >>> 'putStrLn' ('Text.Blaze.Html.Renderer.renderHtml' ['shamlet'|\Hello, world!|]) +-- \Hello, world!\ +-- @ shamlet :: QuasiQuoter shamlet = hamletWithSettings htmlRules defaultHamletSettings +-- | Like 'shamlet', but produces XHTML. xshamlet :: QuasiQuoter xshamlet = hamletWithSettings htmlRules xhtmlHamletSettings @@ -286,9 +297,23 @@ i <- [|id|] return $ HamletRules i ($ (Env Nothing Nothing)) (\_ b -> return b) +-- | Hamlet quasi-quoter. May only be used to generate expressions. +-- +-- Generated expression have type @'HtmlUrl' url@, for some @url@. +-- +-- @ +-- data MyRoute = Home +-- +-- render :: 'Render' MyRoute +-- render Home _ = \"/home\" +-- +-- >>> 'putStrLn' ('Text.Blaze.Html.Renderer.String.renderHtml' (['hamlet'|\Home|] render)) +-- \Home\<\/a\> +-- @ hamlet :: QuasiQuoter hamlet = hamletWithSettings hamletRules defaultHamletSettings +-- | Like 'hamlet', but produces XHTML. xhamlet :: QuasiQuoter xhamlet = hamletWithSettings hamletRules xhtmlHamletSettings @@ -313,6 +338,27 @@ urender $ \ur' -> return ((asHtmlUrl' `AppE` e) `AppE` ur') em _ _ = error "bad Env" +-- | Hamlet quasi-quoter with internationalization. May only be used to generate +-- expressions. +-- +-- Generated expressions have type @'HtmlUrlI18n' msg url@, for some @msg@ and +-- @url@. +-- +-- @ +-- data MyMsg = Hi | Bye +-- +-- data MyRoute = Home +-- +-- renderEnglish :: 'Translate' MyMsg +-- renderEnglish Hi = \"hi\" +-- renderEnglish Bye = \"bye\" +-- +-- renderUrl :: 'Render' MyRoute +-- renderUrl Home _ = \"/home\" +-- +-- >>> 'putStrLn' ('Text.Blaze.Html.Renderer.renderHtml' (['ihamlet'|@{Home} _{Hi} _{Bye}|] renderEnglish renderUrl)) +-- \/home hi bye \ +-- @ ihamlet :: QuasiQuoter ihamlet = hamletWithSettings ihamletRules defaultHamletSettings @@ -370,26 +416,47 @@ contents <- fmap TL.unpack $ qRunIO $ readUtf8File fp hamletFromString qhr set contents +-- | Like 'hamlet', but reads an external file at compile time. +-- +-- @ +-- $('hamletFile' \"foo.hamlet\") :: 'HtmlUrl' MyRoute +-- @ hamletFile :: FilePath -> Q Exp hamletFile = hamletFileWithSettings hamletRules defaultHamletSettings +-- | Like 'hamletFile', but the external file is parsed at runtime. Allows for +-- more rapid development, but should not be used in production. hamletFileReload :: FilePath -> Q Exp hamletFileReload = hamletFileReloadWithSettings runtimeRules defaultHamletSettings where runtimeRules = HamletRuntimeRules { hrrI18n = False } +-- | Like 'ihamletFile', but the external file is parsed at runtime. Allows for +-- more rapid development, but should not be used in production. ihamletFileReload :: FilePath -> Q Exp ihamletFileReload = hamletFileReloadWithSettings runtimeRules defaultHamletSettings where runtimeRules = HamletRuntimeRules { hrrI18n = True } +-- | Like 'hamletFile', but produces XHTML. xhamletFile :: FilePath -> Q Exp xhamletFile = hamletFileWithSettings hamletRules xhtmlHamletSettings +-- | Like 'shamlet', but reads an external file at compile time. +-- +-- @ +-- $('shamletFile' \"foo.hamlet\") :: 'Html' +-- @ shamletFile :: FilePath -> Q Exp shamletFile = hamletFileWithSettings htmlRules defaultHamletSettings +-- | Like 'shamletFile', but produces XHTML. xshamletFile :: FilePath -> Q Exp xshamletFile = hamletFileWithSettings htmlRules xhtmlHamletSettings +-- | Like 'ihamlet', but reads an external file at compile time. +-- +-- @ +-- $('ihamletFile' \"foo.hamlet\") :: 'HtmlUrlI18n' MyMsg MyRoute +-- @ ihamletFile :: FilePath -> Q Exp ihamletFile = hamletFileWithSettings ihamletRules defaultHamletSettings diff --git a/shakespeare.cabal b/shakespeare.cabal --- a/shakespeare.cabal +++ b/shakespeare.cabal @@ -1,5 +1,5 @@ name: shakespeare -version: 2.0.7 +version: 2.0.8 license: MIT license-file: LICENSE author: Michael Snoyman @@ -12,7 +12,7 @@ . Note there is no dependency on haskell-src-extras. Instead Shakespeare believes logic should stay out of templates and has its own minimal Haskell parser. . - Packages that use this: shakespeare-js, shakespeare-css, shakespeare-text, hamlet, and xml-hamlet + Packages that use this: xml-hamlet . Please see the documentation at for more details. @@ -51,7 +51,7 @@ , transformers , vector , unordered-containers - , scientific + , scientific >= 0.3.0.0 exposed-modules: Text.Shakespeare.I18N Text.Shakespeare.Text @@ -105,29 +105,6 @@ description: render tests through coffeescript render function -- cabal configure --enable-tests -ftest_coffee && cabal build && dist/build/test/test default: False - --- Commented out due to concerns that the Hackage page looks too intimidating. - --- flag servius --- description: build the servius web server --- default: True --- --- Executable servius --- Main-is: servius.hs --- hs-source-dirs: app --- if flag(servius) --- buildable: True --- else --- buildable: False --- Build-depends: base >= 4 && < 5 --- , wai-app-static >= 2.0.1 && < 2.1 --- , bytestring >= 0.9.1.4 --- , text >= 0.7 --- , http-types --- , shakespeare --- , wai >= 1.3 && < 2.2 --- , blaze-html >= 0.5 --- , blaze-builder test-suite test hs-source-dirs: test