lucid-svg-0.7.0.0: DSL for SVG using lucid for HTML

Copyright(c) 2015 Jeffrey Rosenbluth
LicenseBSD-style (see LICENSE)
Maintainerjeffrey.rosenbluth@gmail.com
Safe HaskellNone
LanguageHaskell2010

Lucid.Svg

Contents

Description

DSL for creating SVG.

Synopsis

Intro

SVG elements and attributes in Lucid-Svg are written with a postfix ‘_’. Some examples:

path_, circle_, color_, scale_

Note: If you're testing in the REPL you need to add a type annotation to indicate that you want SVG. In normal code your top-level declaration signatures handle that.

Plain text is written using the OverloadedStrings and ExtendedDefaultRules extensions, and is automatically escaped:

As in Lucid, elements nest by function application:

>>> g_ (text_ "Hello SVG") :: Svg ()
<g><text>Hello SVG</text></g>

and elements are juxtaposed via monoidal append or monadic sequencing:

>>> text_ "Hello" <> text_ "SVG" :: Svg ()
<text>Hello</text><text>SVG</text>
>>> do text_ "Hello"; text_ "SVG" :: Svg ()
<text>Hello</text><text>SVG</text>

Attributes are set by providing an argument list. In contrast to HTML many SVG elements have no content, only attributes.

>>> rect_ [width_ "100%", height_ "100%", fill_ "red"] :: Svg ()
<rect height="100%" width="100%" fill="red"></rect>

Attributes and elements that share the same name are not conflicting unless they appear on the list in the note below:

>>> mask_ [mask_ "attribute"] "element" :: Svg ()
<mask mask="attribute">element</mask>

Note: The following element and attribute names overlap and cannot be handled polymorphically since doing so would create conflicting functional dependencies. The unqualifed name refers to the element. We qualify the attribute name as A. For example, path_ and path_.

colorProfile_, cursor_, filter_, path_, and style_

Path data can be constructed using the functions in Path and combined monoidally:

path_ (
  [ d_ (mA 10 80 <> qA 52.5 10 95 80 <> tA 180 80 <> z)
  , stroke_ "blue"
  , fill_ "orange"
  ])
<path d="M 10,80 Q 52.5,10 95,80 T 180,80 Z" stroke="blue" fill="orange"></path>

A slightly longer example:

import Lucid.Svg

svg :: Svg () -> Svg ()
svg content = do
  doctype_
  with (svg11_ content) [version_ "1.1", width_ "300" , height_ "200"]

contents :: Svg ()
contents = do
  rect_ [width_ "100%", height_ "100%", fill_ "red"]
  circle_ [cx_ "150", cy_ "100", r_ "80", fill_ "green"]
  text_ [x_ "150", y_ "125", fontSize_ "60", textAnchor_ "middle", fill_ "white"] "SVG"


main :: IO ()
main = do
  print $ svg contents

Rendering

Re-exports

From Lucid.Base

renderText :: Html a -> Text #

Render the HTML to a lazy Text.

This is a convenience function defined in terms of execHtmlT, runIdentity and toLazyByteString, and decodeUtf8. Check the source if you're interested in the lower-level behaviour.

renderBS :: Html a -> ByteString #

Render the HTML to a lazy ByteString.

This is a convenience function defined in terms of execHtmlT, runIdentity and toLazyByteString. Check the source if you're interested in the lower-level behaviour.

renderTextT :: Monad m => HtmlT m a -> m Text #

Render the HTML to a lazy Text, but in a monad.

This is a convenience function defined in terms of execHtmlT and toLazyByteString, and decodeUtf8. Check the source if you're interested in the lower-level behaviour.

renderBST :: Monad m => HtmlT m a -> m ByteString #

Render the HTML to a lazy ByteString, but in a monad.

This is a convenience function defined in terms of execHtmlT and toLazyByteString. Check the source if you're interested in the lower-level behaviour.

renderToFile :: FilePath -> Html a -> IO () #

Render the HTML to a lazy ByteString.

This is a convenience function defined in terms of execHtmlT, runIdentity and toLazyByteString. Check the source if you're interested in the lower-level behaviour.

Running

execHtmlT #

Arguments

:: Monad m 
=> HtmlT m a

The HTML to generate.

-> m Builder

The a is discarded.

Build the HTML. Analogous to execState.

You might want to use this is if you want to do something with the raw Builder. Otherwise for simple cases you can just use renderText or renderBS.

evalHtmlT #

Arguments

:: Monad m 
=> HtmlT m a

HTML monad to evaluate.

-> m a

Ignore the HTML output and just return the value.

Evaluate the HTML to its return value. Analogous to evalState.

Use this if you want to ignore the HTML output of an action completely and just get the result.

For using with the Html type, you'll need runIdentity e.g.

>>> runIdentity (evalHtmlT (p_ "Hello!"))
()

runHtmlT :: HtmlT m a -> m (HashMap Text Text -> Builder, a) #

This is the low-level way to run the HTML transformer, finally returning an element builder and a value. You can pass mempty for this argument for a top-level call. See evalHtmlT and execHtmlT for easier to use functions.

Types

data Attribute :: * #

A simple attribute. Don't use the constructor, use makeAttribute.

Constructors

Attribute ~Text ~Text 

Instances

Eq Attribute 
Show Attribute 
Hashable Attribute 
Term Text Attribute

Some terms (like style_, title_) can be used for attributes as well as elements.

Methods

term :: Text -> Text -> Attribute #

termWith :: Text -> [Attribute] -> Text -> Attribute #

TermRaw Text Attribute

Some termRaws (like style_, title_) can be used for attributes as well as elements.

(Monad m, (~) * f (HtmlT m a)) => Term [Attribute] (f -> HtmlT m a)

Given attributes, expect more child input.

Methods

term :: Text -> [Attribute] -> f -> HtmlT m a #

termWith :: Text -> [Attribute] -> [Attribute] -> f -> HtmlT m a #

(Monad m, ToHtml f, (~) * a ()) => TermRaw [Attribute] (f -> HtmlT m a)

Given attributes, expect more child input.

Methods

termRaw :: Text -> [Attribute] -> f -> HtmlT m a #

termRawWith :: Text -> [Attribute] -> [Attribute] -> f -> HtmlT m a #

Classes

class Term arg result | result -> arg where #

Used to construct HTML terms.

Simplest use: p_ = term "p" yields p_.

Very overloaded for three cases:

  • The first case is the basic arg of [(Text,Text)] which will return a function that wants children.
  • The second is an arg which is HtmlT m (), in which case the term accepts no attributes and just the children are used for the element.
  • Finally, this is also used for overloaded attributes, like style_ or title_. If a return type of (Text,Text) is inferred then an attribute will be made.

The instances look intimidating but actually the constraints make it very general so that type inference works well even in the presence of things like OverloadedLists and such.

Minimal complete definition

termWith

Methods

term :: Text -> arg -> result #

Used for constructing elements e.g. term "p" yields p_.

termWith :: Text -> [Attribute] -> arg -> result #

Use this if you want to make an element which inserts some pre-prepared attributes into the element.

Instances

Term Text Attribute

Some terms (like style_, title_) can be used for attributes as well as elements.

Methods

term :: Text -> Text -> Attribute #

termWith :: Text -> [Attribute] -> Text -> Attribute #

(Monad m, (~) * f (HtmlT m a)) => Term [Attribute] (f -> HtmlT m a)

Given attributes, expect more child input.

Methods

term :: Text -> [Attribute] -> f -> HtmlT m a #

termWith :: Text -> [Attribute] -> [Attribute] -> f -> HtmlT m a #

Monad m => Term (HtmlT m a) (HtmlT m a)

Given children immediately, just use that and expect no attributes.

Methods

term :: Text -> HtmlT m a -> HtmlT m a #

termWith :: Text -> [Attribute] -> HtmlT m a -> HtmlT m a #

class ToHtml a where #

Can be converted to HTML.

Minimal complete definition

toHtml, toHtmlRaw

Methods

toHtml :: Monad m => a -> HtmlT m () #

toHtmlRaw :: Monad m => a -> HtmlT m () #

Instances

ToHtml String 

Methods

toHtml :: Monad m => String -> HtmlT m () #

toHtmlRaw :: Monad m => String -> HtmlT m () #

ToHtml ByteString

This instance requires the ByteString to contain UTF-8 encoded text, for the toHtml method. The toHtmlRaw method doesn't care, but the overall HTML rendering methods in this module assume UTF-8.

Methods

toHtml :: Monad m => ByteString -> HtmlT m () #

toHtmlRaw :: Monad m => ByteString -> HtmlT m () #

ToHtml ByteString

This instance requires the ByteString to contain UTF-8 encoded text, for the toHtml method. The toHtmlRaw method doesn't care, but the overall HTML rendering methods in this module assume UTF-8.

Methods

toHtml :: Monad m => ByteString -> HtmlT m () #

toHtmlRaw :: Monad m => ByteString -> HtmlT m () #

ToHtml Text 

Methods

toHtml :: Monad m => Text -> HtmlT m () #

toHtmlRaw :: Monad m => Text -> HtmlT m () #

ToHtml Text 

Methods

toHtml :: Monad m => Text -> HtmlT m () #

toHtmlRaw :: Monad m => Text -> HtmlT m () #

((~) * a (), (~) (* -> *) m Identity) => ToHtml (HtmlT m a) 

Methods

toHtml :: Monad m => HtmlT m a -> HtmlT m () #

toHtmlRaw :: Monad m => HtmlT m a -> HtmlT m () #

class With a where #

With an element use these attributes. An overloaded way of adding attributes either to an element accepting attributes-and-children or one that just accepts attributes. See the two instances.

Minimal complete definition

with

Methods

with :: a -> [Attribute] -> a #

With the given element(s), use the given attributes.

Instances

Monad m => With (HtmlT m a -> HtmlT m a)

For the contentful elements: div_

Methods

with :: (HtmlT m a -> HtmlT m a) -> [Attribute] -> HtmlT m a -> HtmlT m a #

Monad m => With (HtmlT m a)

For the contentless elements: br_

Methods

with :: HtmlT m a -> [Attribute] -> HtmlT m a #