-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Generic programming for the web
--   
--   This package implements generic functions for web programming. Based
--   on the <tt>regular</tt> library [1], we provide generic functions for
--   generating <tt>HTML</tt>, <tt>Formlets</tt>, and <tt>JSON</tt>. For a
--   larger example, see the <tt>Example.lhs</tt> [2] file on github.
--   
--   1. <a>http://hackage.haskell.org/package/regular</a>
--   
--   2.
--   <a>http://github.com/chriseidhof/regular-web/blob/master/Example.lhs</a>
--   
--   <i>Example</i>
--   
--   Consider the following datatypes:
--   
--   <pre>
--   data Person = Person
--       _name   :: String
--     , _age    :: Int
--     , _isMale :: Bool
--     , _place  :: Place
--   
--   data Place = Place
--       _city      :: String
--     , _country   :: String
--     , _continent :: String
--   </pre>
--   
--   We can now derive a <tt>Regular</tt> instance for the <tt>Person</tt>
--   datatype using Template Haskell:
--   
--   <pre>
--   $(deriveAll ''Place  "PFPlace")
--   $(deriveAll ''Person "PFPerson")
--   </pre>
--   
--   <pre>
--   type instance PF Place  = PFPlace
--   type instance PF Person = PFPerson
--   </pre>
--   
--   We can construct an example person:
--   
--   <pre>
--   location :: Place
--   location = Place "Utrecht" "The Netherlands" "Europe"
--   chris    :: Person
--   chris    = Person "chris" 25 True location
--   </pre>
--   
--   <pre>
--   And, as an example, we can generate |HTML| and |JSON| values:
--   </pre>
--   
--   <pre>
--   locationHtml :: X.Html
--   locationHtml = ghtml location
--   </pre>
--   
--   <pre>
--   personHtml :: X.Html
--   personHtml = ghtml chris
--   </pre>
--   
--   <pre>
--   locationJSON :: JSValue
--   locationJSON = gto location
--   </pre>
@package regular-web
@version 0.1


-- | Summary: Functions for generating HTML.
module Generics.Regular.Views

-- | The function <a>ghtml</a> converts an a value into <a>Html</a>
ghtml :: (Regular a, GHtml (PF a)) => a -> Html

-- | The class <a>Html</a> converts a simple value a into <a>Html</a>.
class Html a
html :: (Html a) => a -> Html

-- | The class <a>GHtml</a> converts a simple value a into <a>Html</a>.
class GHtml f
instance (Selector s, GTable f) => GTable (S s f)
instance (GTable f, GTable g) => GTable (f :*: g)
instance (Table a) => GTable (K a)
instance (Constructor c, GTable f) => GTable (C c f)
instance GTable I
instance Table Bool
instance Table Int
instance Table String
instance Table Float
instance (Selector s, GHtml f) => GHtml (S s f)
instance (GHtml f, GHtml g) => GHtml (f :+: g)
instance (GHtml f, GHtml g) => GHtml (f :*: g)
instance (Html a) => GHtml (K a)
instance (Constructor c, GHtml f) => GHtml (C c f)
instance GHtml I
instance Html String
instance Html Bool
instance Html Int
instance Html Float


-- | Generic generation of <a>JSON</a> values. Note that the generic
--   functions are only defined for record datatypes that contain a single
--   constructor.
--   
--   The code that is generated by <a>gto</a> should be parseable by
--   <a>gfrom</a>.
module Generics.Regular.JSON

-- | The function <a>gfrom</a> tries to parse a <a>JSValue</a>. The
--   <a>Result</a> datatype is used for error-messages if parsing fails.
gfrom :: (Regular a, GJSON (PF a)) => JSValue -> Result a

-- | The function <a>gto</a> generates a <a>JSValue</a> for all types that
--   are an instance of <a>GJSON</a>.
gto :: (Regular a, GJSON (PF a)) => a -> JSValue

-- | This class is used for both generation and parsing of <a>JSON</a>.
class GJSON f
instance (GJSON f) => GJSON (C c f)
instance (Selector s, GJSON f) => GJSON (S s f)
instance (GJSON (S s f), GJSON g) => GJSON (S s f :*: g)
instance (JSON a) => GJSON (K a)
instance GJSON U


-- | Generic generation of formlets
--   <a>http://hackage.haskell.org/package/formlets</a>. These functions
--   are only defined for record datatypes that contain a single
--   constructor.
--   
--   Consider the datatype <tt>Person</tt>:
--   
--   <pre>
--   data Person = Person {
--      _name   :: String
--    , _age    :: Int
--    , _isMale :: Bool
--   } deriving (Show, Eq)
--   </pre>
--   
--   We prefix all our fields with an underscore (<tt>_</tt>), so that our
--   datatype will play nice with <tt>fclabels</tt>.
--   
--   <pre>
--   $(deriveAll ''Person "PFPerson")
--   </pre>
--   
--   <pre>
--   type instance PF Person = PFPerson
--   </pre>
--   
--   We can construct an example person:
--   
--   <pre>
--   chris    :: Person
--   chris    = Person "chris" 25 True
--   </pre>
--   
--   <pre>
--   personForm :: XFormlet Identity Person
--   personForm = gformlet
--   </pre>
--   
--   We can print <tt>formHtml</tt> to get the <tt>Html</tt> of the form
--   with the <tt>chris</tt> value already filled in:
--   
--   <pre>
--   formHtml :: X.Html
--   (_, Identity formHtml, _) = F.runFormState [] (personForm (Just chris))
--   </pre>
module Generics.Regular.Formlets
gform :: (Regular a, GFormlet (PF a), Functor m, Applicative m, Monad m) => Maybe a -> XForm m a
gformlet :: (Regular a, GFormlet (PF a), Functor m, Applicative m, Monad m) => XFormlet m a
class GFormlet f
type XForm m a = XHtmlForm m a
type XFormlet m a = XHtmlFormlet m a

-- | Generic forms almost never match the real world. If you want to change
--   a generic form, you can either implement it from scratch, or use the
--   <a>projectedForm</a> function.
--   
--   As an example, we will to remove the age field from the form, and
--   change the _isMale field to a Yes/No choice instead of a True/False
--   choice. The datatype <a>YesNo</a> is defined in this module.
--   
--   <pre>
--   data PersonView = PersonView {
--      __name   :: String
--    , __isMale :: YesNo
--   }
--   </pre>
--   
--   <pre>
--   $(deriveAll ''PersonView "PFPersonView")
--   type instance PF PersonView = PFPersonView
--   </pre>
--   
--   We can now use <tt>fclabels</tt> to convert back and forth between
--   <tt>Person</tt> and <tt>PersonView</tt>. First, we use Template
--   Haskell to generate some accessor functions:
--   
--   <pre>
--   $(mkLabels [''Person])
--   </pre>
--   
--   This is the bidirectional function between <tt>Person</tt> and
--   <tt>PersonView</tt>. How to write such a function is explained in the
--   well-documented <tt>fclabels</tt> package at
--   <a>http://hackage.haskell.org/package/fclabels</a>.
--   
--   <pre>
--   toView :: Person :-&gt; PersonView
--   toView = Label (PersonView &lt;$&gt; __name `for` name &lt;*&gt; __isMale `for` (boolToYesNo `iso` isMale))
--   </pre>
--   
--   Now that we have a function with type <tt>Person :-&gt;
--   PersonView</tt>, we can render a form for <tt>personView</tt> and
--   update the original person. Note that the argument is not a
--   <tt>Maybe</tt> value, in contrast with the <tt>gformlet</tt> function.
--   
--   <pre>
--   personForm' :: Person -&gt; XForm Identity Person
--   personForm' = projectedForm toView
--   </pre>
--   
--   <pre>
--   formHtml' :: X.Html
--   (_, Identity formHtml', _) = F.runFormState [] (personForm' chris)
--   </pre>
projectedForm :: (Regular a, GFormlet (PF a), Applicative m, Monad m) => (b :-> a) -> b -> XForm m b
class Formlet a
formlet :: (Formlet a, Functor m, Applicative m, Monad m) => XFormlet m a

-- | This datatype is used to display <a>Bool</a> values as <tt>Yes</tt> or
--   <tt>No</tt>.
data YesNo
Yes :: YesNo
No :: YesNo

-- | This is an <tt>fclabels</tt> function that converts between
--   <a>Bool</a> and <a>YesNo</a> values.
boolToYesNo :: Bool :<->: YesNo
instance Eq YesNo
instance Show YesNo
instance Bounded YesNo
instance Enum YesNo
instance Formlet YesNo
instance (Selector s, GFormlet f) => GFormlet (S s f)
instance (GFormlet (S s f), GFormlet g) => GFormlet (S s f :*: g)
instance (Formlet a) => GFormlet (K a)
instance (Constructor c, GFormlet f) => GFormlet (C c f)
instance Formlet String
instance Formlet Int
instance Formlet Bool