Text.DocL

Haskell mini-language to create HTML documents with a mixture of markup and plots based on the C3.js library.

See the github page for an introduction.

Notes:

• The generated documents relies on https://cdnjs.com/ to serve C3.js and friends.
• This library should not be used on a public facing server with input supplied by the user. The library has not been properly vetted for security issues.

Documentation

data Doc

Base type representing a document. This type allows composition via the Monoid instance.

Instances

Monoid Doc

Markup

text :: String -> Doc

Creates a Doc representing plain text. The string will be properly escaped.

header :: String -> Doc

Creates a Doc representing <h1> header tag. The string will be properly escaped.

markdown :: String -> Doc

Converts a string in markdown syntax to a Doc.

html :: Html -> Doc

Creates a Doc representing raw html.

Output

render :: Doc -> ByteString

Render a document to a lazy ByteString.

renderToFile :: FilePath -> Doc -> IO ()

If the file exists, it will be overwritten.

Plotting

data Column a

Represent a column of a dataset where each row has type a. See col for details.

col :: String -> (a -> Double) -> Column a

Data sets are supplied to plot as a collection of elements of type a. This function sets up a Column, which knows how to extract one Double value from each value of type a in the collection.

The first argument to col is the header of the column, which is used in the legend of the plot.

The simplest plot that can be created consist of one column for the x values and one column for the y values.

 -- Plot x² vs x.
 plot [1..10] (col "x" id) [col "x²" $ \x -> x*x]

col' :: ToObj b => String -> (a -> b) -> Column a

Polymorphic version of col. This allows, for instance, Int and String values to be used in plots. It is up to the caller to ensure that the values make sense to C3.js.

plot :: Foldable f => f a -> Column a -> [Column a] -> Doc

plot ds x ys

Plots the data in ds using the column x for the values on the x-axis and with one line on the plot for each column in ys. See also col.

plot' :: Foldable f => f a -> Column a -> [Column a] -> [Prop] -> Doc

Same as plot, but takes a final argument which is merged with the configuration object supplied to C3.js. This allows the caller to customize the plot.

 -- Plot x² vs x with the points hidden.
 plot' [1..10] (col "x" id) [col "x²" $ \x -> x*x] $
   ["point" /: ["show" /: False]]

See http://c3js.org/reference.html for the many properties that can be used here.

rawPlot :: [Prop] -> Doc

This function sends an object with the supplied properties directly to C3.js. This is the do-it-yourself option which exposes all of C3.js. The object receives a "bindto" property, targeting a <div> tag placed appropriately.

Utilities

linspace :: Fractional a => a -> a -> Int -> [a]

linspace x y n generates n evenly spaced values from x to y.

Re-exports from Text.DocL.Javascript

(/:) :: ToObj a => String -> a -> Prop

Constructs a Prop.

>>> toObj ["tail" /: True, "nose" /: "wet"]
{"nose":"wet","tail":true}

javascript :: String -> Obj

Raw unescaped javascript.

>>> toObj ["speak" /: javascript "function(){alert('Woof!');}"]
{"speak":function(){alert('Woof!');}}