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


-- | reform is a type-safe HTML form generation and validation library
--   
--   reform follows in the footsteps of formlets and digestive-functors
--   &lt;= 0.2. It provides a type-safe and composable method for
--   generating an HTML form that includes validation.
@package reform
@version 0.2.7.1


-- | Module for the core result type, and related functions
module Text.Reform.Result

-- | Type for failing computations
data Result e ok
Error :: [(FormRange, e)] -> Result e ok
Ok :: ok -> Result e ok

-- | convert a <a>Result</a> to <a>Maybe</a> discarding the error message
--   on <a>Error</a>
getResult :: Result e ok -> Maybe ok

-- | An ID used to identify forms
data FormId

-- | The zero ID, i.e. the first ID that is usable
zeroId :: String -> FormId

-- | map a function over the <tt>[Integer]</tt> inside a <a>FormId</a>
mapId :: ([Integer] -> [Integer]) -> FormId -> FormId

-- | Stack indicating field. Head is most specific to this item
formIdList :: FormId -> [Integer]

-- | A range of ID's to specify a group of forms
data FormRange
FormRange :: FormId -> FormId -> FormRange

-- | Increment a form ID
incrementFormId :: FormId -> FormId

-- | create a <a>FormRange</a> from a <a>FormId</a>
unitRange :: FormId -> FormRange

-- | Check if a <a>FormId</a> is contained in a <a>FormRange</a>
isInRange :: FormId -> FormRange -> Bool

-- | Check if a <a>FormRange</a> is contained in another <a>FormRange</a>
isSubRange :: FormRange -> FormRange -> Bool

-- | Select the errors for a certain range
retainErrors :: FormRange -> [(FormRange, e)] -> [e]

-- | Select the errors originating from this form or from any of the
--   children of this form
retainChildErrors :: FormRange -> [(FormRange, e)] -> [e]
instance (GHC.Classes.Eq ok, GHC.Classes.Eq e) => GHC.Classes.Eq (Text.Reform.Result.Result e ok)
instance (GHC.Show.Show ok, GHC.Show.Show e) => GHC.Show.Show (Text.Reform.Result.Result e ok)
instance GHC.Show.Show Text.Reform.Result.FormRange
instance GHC.Classes.Eq Text.Reform.Result.FormRange
instance GHC.Classes.Ord Text.Reform.Result.FormId
instance GHC.Classes.Eq Text.Reform.Result.FormId
instance GHC.Base.Functor (Text.Reform.Result.Result e)
instance GHC.Base.Monad (Text.Reform.Result.Result e)
instance GHC.Base.Applicative (Text.Reform.Result.Result e)
instance GHC.Show.Show Text.Reform.Result.FormId


-- | This module contains two classes. <a>FormInput</a> is a class which is
--   parameterized over the <tt>input</tt> type used to represent form data
--   in different web frameworks. There should be one instance for each
--   framework, such as Happstack, Snap, WAI, etc.
--   
--   The <a>FormError</a> class is used to map error messages into an
--   application specific error type.
module Text.Reform.Backend

-- | an error type used to represent errors that are common to all backends
--   
--   These errors should only occur if there is a bug in the reform-*
--   packages. Perhaps we should make them an <tt>Exception</tt> so that we
--   can get rid of the <a>FormError</a> class.
data CommonFormError input
InputMissing :: FormId -> CommonFormError input
NoStringFound :: input -> CommonFormError input
NoFileFound :: input -> CommonFormError input
MultiFilesFound :: input -> CommonFormError input
MultiStringsFound :: input -> CommonFormError input
MissingDefaultValue :: CommonFormError input

-- | some default error messages for <a>CommonFormError</a>
commonFormErrorStr :: (input -> String) -> CommonFormError input -> String

-- | A Class to lift a <a>CommonFormError</a> into an application-specific
--   error type
class FormError e where type ErrorInputType e where {
    type family ErrorInputType e;
}
commonFormError :: FormError e => (CommonFormError (ErrorInputType e)) -> e

-- | Class which all backends should implement.
class FormInput input where type FileType input getInputString input = case getInputStrings input of { [] -> Left (commonFormError $ NoStringFound input) [s] -> Right s _ -> Left (commonFormError $ MultiStringsFound input) } getInputText input = case getInputTexts input of { [] -> Left (commonFormError $ NoStringFound input) [s] -> Right s _ -> Left (commonFormError $ MultiStringsFound input) } getInputTexts = map pack . getInputStrings where {
    type family FileType input;
}

-- | Parse the input into a string. This is used for simple text fields
--   among other things
getInputString :: (FormInput input, FormError error, ErrorInputType error ~ input) => input -> Either error String

-- | Should be implemented
getInputStrings :: FormInput input => input -> [String]

-- | Parse the input value into <a>Text</a>
getInputText :: (FormInput input, FormError error, ErrorInputType error ~ input) => input -> Either error Text

-- | Can be overriden for efficiency concerns
getInputTexts :: FormInput input => input -> [Text]

-- | Get a file descriptor for an uploaded file
getInputFile :: (FormInput input, FormError error, ErrorInputType error ~ input) => input -> Either error (FileType input)
instance GHC.Show.Show input => GHC.Show.Show (Text.Reform.Backend.CommonFormError input)
instance GHC.Classes.Ord input => GHC.Classes.Ord (Text.Reform.Backend.CommonFormError input)
instance GHC.Classes.Eq input => GHC.Classes.Eq (Text.Reform.Backend.CommonFormError input)


-- | This module provides a type-indexed / parameterized version of the
--   <a>Functor</a> and <a>Applicative</a> classes.
module Control.Applicative.Indexed

-- | a class for a 'type-indexed' or <tt>paramaterized</tt> functor
--   
--   note: not sure what the most correct name is for this class, or if it
--   exists in a well supported library already.
class IndexedFunctor f

-- | imap is similar to fmap
imap :: IndexedFunctor f => (x -> y) -> (a -> b) -> f x a -> f y b

-- | a class for a 'type-indexed' or <tt>paramaterized</tt> applicative
--   functors
--   
--   note: not sure what the most correct name is for this class, or if it
--   exists in a well supported library already.
class (IndexedFunctor f) => IndexedApplicative f where (*>>) = liftIA2 (const id) (const id) (<<*) = liftIA2 const const

-- | similar to <a>pure</a>
ipure :: IndexedApplicative f => x -> a -> f x a

-- | similar to <a>&lt;*&gt;</a>
(<<*>>) :: IndexedApplicative f => f (x -> y) (a -> b) -> f x a -> f y b

-- | similar to <a>*&gt;</a>
(*>>) :: IndexedApplicative f => f x a -> f y b -> f y b

-- | similar to <a>&lt;*</a>
(<<*) :: IndexedApplicative f => f x a -> f y b -> f x a

-- | similar to <a>&lt;$&gt;</a>. An alias for <tt>imap id</tt>
(<<$>>) :: IndexedFunctor f => (a -> b) -> f y a -> f y b
infixl 4 <<$>>

-- | A variant of <a>&lt;&lt;*&gt;&gt;</a> with the arguments reversed.
(<<**>>) :: (IndexedApplicative f) => f x a -> f (x -> y) (a -> b) -> f y b

-- | Lift a function to actions. This function may be used as a value for
--   <a>imap</a> in a <a>IndexedFunctor</a> instance.
liftIA :: (IndexedApplicative f) => (a -> b) -> (x -> y) -> f a x -> f b y

-- | Lift a binary function to actions.
liftIA2 :: (IndexedApplicative f) => (a -> b -> c) -> (x -> y -> z) -> f a x -> f b y -> f c z

-- | Lift a binary function to actions.
liftIA3 :: (IndexedApplicative f) => (a -> b -> c -> d) -> (w -> x -> y -> z) -> f a w -> f b x -> f c y -> f d z

-- | a wrapper which lifts a value with an <a>Applicative</a> instance so
--   that it can be used as an <a>IndexedFunctor</a> or
--   <a>IndexedApplicative</a>
--   
--   <pre>
--   d :: WrappedApplicative Maybe y Char
--   d = WrappedApplicative (Just succ) &lt;&lt;*&gt;&gt; WrappedApplicative (Just 'c')
--   </pre>
newtype WrappedApplicative f index a
WrappedApplicative :: f a -> WrappedApplicative f index a
[unwrapApplicative] :: WrappedApplicative f index a -> f a
instance GHC.Show.Show (f a) => GHC.Show.Show (Control.Applicative.Indexed.WrappedApplicative f index a)
instance GHC.Read.Read (f a) => GHC.Read.Read (Control.Applicative.Indexed.WrappedApplicative f index a)
instance GHC.Classes.Ord (f a) => GHC.Classes.Ord (Control.Applicative.Indexed.WrappedApplicative f index a)
instance GHC.Classes.Eq (f a) => GHC.Classes.Eq (Control.Applicative.Indexed.WrappedApplicative f index a)
instance GHC.Base.Monad f => GHC.Base.Monad (Control.Applicative.Indexed.WrappedApplicative f index)
instance GHC.Base.Applicative f => GHC.Base.Applicative (Control.Applicative.Indexed.WrappedApplicative f index)
instance GHC.Base.Functor f => GHC.Base.Functor (Control.Applicative.Indexed.WrappedApplicative f index)
instance GHC.Base.Functor f => Control.Applicative.Indexed.IndexedFunctor (Control.Applicative.Indexed.WrappedApplicative f)
instance GHC.Base.Applicative f => Control.Applicative.Indexed.IndexedApplicative (Control.Applicative.Indexed.WrappedApplicative f)


-- | This module defines the <a>Form</a> type, its instances, core
--   manipulation functions, and a bunch of helper utilities.
module Text.Reform.Core

-- | Proved records a value, the location that value came from, and
--   something that was proved about the value.
data Proved proofs a
Proved :: proofs -> FormRange -> a -> Proved proofs a
[proofs] :: Proved proofs a -> proofs
[pos] :: Proved proofs a -> FormRange
[unProved] :: Proved proofs a -> a

-- | Utility Function: trivially prove nothing about ()
unitProved :: FormId -> Proved () ()

-- | inner state used by <a>Form</a>.
type FormState m input = ReaderT (Environment m input) (StateT FormRange m)

-- | used to represent whether a value was found in the form submission
--   data, missing from the form submission data, or expected that the
--   default value should be used
data Value a
Default :: Value a
Missing :: Value a
Found :: a -> Value a

-- | Utility function: Get the current input
getFormInput :: Monad m => FormState m input (Value input)

-- | Utility function: Gets the input of an arbitrary <a>FormId</a>.
getFormInput' :: Monad m => FormId -> FormState m input (Value input)

-- | Utility function: Get the current range
getFormRange :: Monad m => FormState m i FormRange

-- | The environment is where you get the actual input per form.
--   
--   The <a>NoEnvironment</a> constructor is typically used when generating
--   a view for a GET request, where no data has yet been submitted. This
--   will cause the input elements to use their supplied default values.
--   
--   Note that <tt>NoEnviroment</tt> is different than supplying an empty
--   environment.
data Environment m input
Environment :: (FormId -> m (Value input)) -> Environment m input
NoEnvironment :: Environment m input

-- | Not quite sure when this is useful and so hard to say if the rules for
--   combining things with Missing/Default are correct

-- | Utility function: returns the current <a>FormId</a>. This will only
--   make sense if the form is not composed
getFormId :: Monad m => FormState m i FormId

-- | Utility function: increment the current <a>FormId</a>.
incFormId :: Monad m => FormState m i ()

-- | A view represents a visual representation of a form. It is composed of
--   a function which takes a list of all errors and then produces a new
--   view
newtype View error v
View :: ([(FormRange, error)] -> v) -> View error v
[unView] :: View error v -> [(FormRange, error)] -> v

-- | a <a>Form</a> contains a <a>View</a> combined with a validation
--   function which will attempt to extract a value from submitted form
--   data.
--   
--   It is highly parameterized, allowing it work in a wide variety of
--   different configurations. You will likely want to make a type alias
--   that is specific to your application to make type signatures more
--   manageable.
--   
--   <ul>
--   <li><i><tt>m</tt></i> A monad which can be used by the validator</li>
--   <li><i><tt>input</tt></i> A framework specific type for representing
--   the raw key/value pairs from the form data</li>
--   <li><i><tt>error</tt></i> A application specific type for error
--   messages</li>
--   <li><i><tt>view</tt></i> The type of data being generated for the view
--   (HSP, Blaze Html, Heist, etc)</li>
--   <li><i><tt>proof</tt></i> A type which names what has been proved
--   about the return value. <tt>()</tt> means nothing has been
--   proved.</li>
--   <li><i><tt>a</tt></i> Value return by form when it is successfully
--   decoded, validated, etc.</li>
--   </ul>
--   
--   This type is very similar to the <a>Form</a> type from
--   <tt>digestive-functors &lt;= 0.2</tt>. If <tt>proof</tt> is
--   <tt>()</tt>, then <a>Form</a> is an applicative functor and can be
--   used almost exactly like <tt>digestive-functors &lt;= 0.2</tt>.
newtype Form m input error view proof a
Form :: FormState m input (View error view, m (Result error (Proved proof a))) -> Form m input error view proof a
[unForm] :: Form m input error view proof a -> FormState m input (View error view, m (Result error (Proved proof a)))
bracketState :: Monad m => FormState m input a -> FormState m input a

-- | Run a form
runForm :: (Monad m) => Environment m input -> Text -> Form m input error view proof a -> m (View error view, m (Result error (Proved proof a)))

-- | Run a form
runForm' :: (Monad m) => Environment m input -> Text -> Form m input error view proof a -> m (view, Maybe a)

-- | Just evaluate the form to a view. This usually maps to a GET request
--   in the browser.
viewForm :: (Monad m) => Text -> Form m input error view proof a -> m view

-- | Evaluate a form
--   
--   Returns:
--   
--   <ul>
--   <li><i><tt>Left view</tt></i> on failure. The <tt>view</tt> will have
--   already been applied to the errors.</li>
--   <li><i><tt>Right a</tt></i> on success.</li>
--   </ul>
eitherForm :: (Monad m) => Environment m input -> Text -> Form m input error view proof a -> m (Either view a)

-- | create a <a>Form</a> from some <tt>view</tt>.
--   
--   This is typically used to turn markup like <tt>&lt;br&gt;</tt> into a
--   <a>Form</a>.
view :: (Monad m) => view -> Form m input error view () ()

-- | Append a unit form to the left. This is useful for adding labels or
--   error fields.
--   
--   The <tt>Forms</tt> on the left and right hand side will share the same
--   <a>FormId</a>. This is useful for elements like <tt>&lt;label
--   for="someid"&gt;</tt>, which need to refer to the id of another
--   element.
(++>) :: (Monad m, Monoid view) => Form m input error view () () -> Form m input error view proof a -> Form m input error view proof a
infixl 6 ++>

-- | Append a unit form to the right. See <a>++&gt;</a>.
(<++) :: (Monad m, Monoid view) => Form m input error view proof a -> Form m input error view () () -> Form m input error view proof a
infixr 5 <++

-- | Change the view of a form using a simple function
--   
--   This is useful for wrapping a form inside of a &lt;fieldset&gt; or
--   other markup element.
mapView :: (Monad m, Functor m) => (view -> view') -> Form m input error view proof a -> Form m input error view' proof a

-- | Utility Function: turn a view and return value into a successful
--   <a>FormState</a>
mkOk :: (Monad m) => FormId -> view -> a -> FormState m input (View error view, m (Result error (Proved () a)))
instance GHC.Base.Monoid v => GHC.Base.Monoid (Text.Reform.Core.View error v)
instance (GHC.Show.Show a, GHC.Show.Show proofs) => GHC.Show.Show (Text.Reform.Core.Proved proofs a)
instance GHC.Base.Functor (Text.Reform.Core.Proved ())
instance (GHC.Base.Monoid input, GHC.Base.Monad m) => GHC.Base.Monoid (Text.Reform.Core.Environment m input)
instance GHC.Base.Functor (Text.Reform.Core.View e)
instance GHC.Base.Monad m => Control.Applicative.Indexed.IndexedFunctor (Text.Reform.Core.Form m input view error)
instance (GHC.Base.Monoid view, GHC.Base.Monad m) => Control.Applicative.Indexed.IndexedApplicative (Text.Reform.Core.Form m input error view)
instance GHC.Base.Functor m => GHC.Base.Functor (Text.Reform.Core.Form m input error view ())
instance (GHC.Base.Functor m, GHC.Base.Monoid view, GHC.Base.Monad m) => GHC.Base.Applicative (Text.Reform.Core.Form m input error view ())


-- | This module provides helper functions for HTML input elements. These
--   helper functions are not specific to any particular web framework or
--   html library.
module Text.Reform.Generalized

-- | used for constructing elements like <tt>&lt;input
--   type="text"&gt;</tt>, which return a single input value.
input :: (Monad m, FormError error) => (input -> Either error a) -> (FormId -> a -> view) -> a -> Form m input error view () a

-- | used for elements like <tt>&lt;input type="submit"&gt;</tt> which are
--   not always present in the form submission data.
inputMaybe :: (Monad m, FormError error) => (input -> Either error a) -> (FormId -> a -> view) -> a -> Form m input error view () (Maybe a)

-- | used for elements like <tt>&lt;input type="reset"&gt;</tt> which take
--   a value, but are never present in the form data set.
inputNoData :: (Monad m) => (FormId -> a -> view) -> a -> Form m input error view () ()

-- | used for <tt>&lt;input type="file"&gt;</tt>
inputFile :: forall m input error view. (Monad m, FormInput input, FormError error, ErrorInputType error ~ input) => (FormId -> view) -> Form m input error view () (FileType input)

-- | used for groups of checkboxes, <tt>&lt;select
--   multiple="multiple"&gt;</tt> boxes
inputMulti :: forall m input error view a lbl. (Functor m, FormError error, ErrorInputType error ~ input, FormInput input, Monad m) => [(a, lbl)] -> (FormId -> [(FormId, Int, lbl, Bool)] -> view) -> (a -> Bool) -> Form m input error view () [a]

-- | radio buttons, single <tt>&lt;select&gt;</tt> boxes
inputChoice :: forall a m error input lbl view. (Functor m, FormError error, ErrorInputType error ~ input, FormInput input, Monad m) => (a -> Bool) -> [(a, lbl)] -> (FormId -> [(FormId, Int, lbl, Bool)] -> view) -> Form m input error view () a

-- | radio buttons, single <tt>&lt;select&gt;</tt> boxes
inputChoiceForms :: forall a m error input lbl view proof. (Functor m, Monad m, FormError error, ErrorInputType error ~ input, FormInput input) => a -> [(Form m input error view proof a, lbl)] -> (FormId -> [(FormId, Int, FormId, view, lbl, Bool)] -> view) -> Form m input error view proof a

-- | used to create <tt>&lt;label&gt;</tt> elements
label :: Monad m => (FormId -> view) -> Form m input error view () ()

-- | used to add a list of error messages to a <a>Form</a>
--   
--   This function automatically takes care of extracting only the errors
--   that are relevent to the form element it is attached to via
--   <a>&lt;++</a> or <a>++&gt;</a>.
errors :: Monad m => ([error] -> view) -> Form m input error view () ()

-- | similar to <a>errors</a> but includes error messages from children of
--   the form as well.
childErrors :: Monad m => ([error] -> view) -> Form m input error view () ()


-- | This module defines the <a>Proof</a> type, some proofs, and some
--   helper functions.
--   
--   A <a>Proof</a> does three things:
--   
--   <ul>
--   <li>verifies that the input value meets some criteria</li>
--   <li>optionally transforms the input value to another value while
--   preserving that criteria</li>
--   <li>puts the proof name in type-signature where the type-checker can
--   use it</li>
--   </ul>
module Text.Reform.Proof

-- | A <a>Proof</a> attempts to prove something about a value.
--   
--   If successful, it can also transform the value to a new value. The
--   proof should hold for the new value as well.
--   
--   Generally, each <a>Proof</a> has a unique data-type associated with it
--   which names the proof, such as:
--   
--   <pre>
--   data NotNull = NotNull
--   </pre>
data Proof m error proof a b
Proof :: proof -> (a -> m (Either error b)) -> Proof m error proof a b

-- | name of the thing to prove
[proofName] :: Proof m error proof a b -> proof

-- | function which provides the proof
[proofFunction] :: Proof m error proof a b -> a -> m (Either error b)

-- | apply a <a>Proof</a> to a <a>Form</a>
prove :: (Monad m) => Form m input error view q a -> Proof m error proof a b -> Form m input error view proof b

-- | transform a <a>Form</a> using a <a>Proof</a>, and the replace the
--   proof with <tt>()</tt>.
--   
--   This is useful when you want just want classic digestive-functors
--   behaviour.
transform :: (Monad m) => Form m input error view anyProof a -> Proof m error proof a b -> Form m input error view () b

-- | transform the <a>Form</a> result using a monadic <a>Either</a>
--   function.
transformEitherM :: (Monad m) => Form m input error view anyProof a -> (a -> m (Either error b)) -> Form m input error view () b

-- | transform the <a>Form</a> result using an <a>Either</a> function.
transformEither :: (Monad m) => Form m input error view anyProof a -> (a -> Either error b) -> Form m input error view () b

-- | proof that a list is not empty
data NotNull
NotNull :: NotNull

-- | prove that a list is not empty
notNullProof :: (Monad m) => error -> Proof m error NotNull [a] [a]

-- | proof that a <a>String</a> is a decimal number
data Decimal
Decimal :: Decimal

-- | proof that a <a>String</a> is a Real/Fractional number
data RealFractional
RealFractional :: RealFractional

-- | proof that a number is also (allowed to be) signed
data Signed a
Signed :: a -> Signed a

-- | read an unsigned number in decimal notation
decimal :: (Monad m, Eq i, Num i) => (String -> error) -> Proof m error Decimal String i

-- | read signed decimal number
signedDecimal :: (Monad m, Eq i, Real i) => (String -> error) -> Proof m error (Signed Decimal) String i

-- | read <a>RealFrac</a> number
realFrac :: (Monad m, RealFrac a) => (String -> error) -> Proof m error RealFractional String a

-- | read a signed <a>RealFrac</a> number
realFracSigned :: (Monad m, RealFrac a) => (String -> error) -> Proof m error (Signed RealFractional) String a

module Text.Reform
