-- 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
--   <= 0.2. It provides a type-safe and composable method for
--   generating an HTML form that includes validation.
@package reform
@version 0.2.7.4

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

-- | a class for a 'type-indexed' or paramaterized 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 paramaterized 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

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

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

-- | similar to *>
(*>>) :: IndexedApplicative f => f x a -> f y b -> f y b

-- | similar to <*
(<<*) :: IndexedApplicative f => f x a -> f y b -> f x a
infixl 4 <<*
infixl 4 *>>
infixl 4 <<*>>

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

-- | A variant of <<*>> 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
--   imap in a IndexedFunctor 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 Applicative instance so
--   that it can be used as an IndexedFunctor or
--   IndexedApplicative
--   
--   
--   d :: WrappedApplicative Maybe y Char
--   d = WrappedApplicative (Just succ) <<*>> WrappedApplicative (Just 'c')
--   
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)

-- | 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 Result to Maybe discarding the error message
--   on Error
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 [Integer] inside a FormId
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 FormRange from a FormId
unitRange :: FormId -> FormRange

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

-- | Check if a FormRange is contained in another FormRange
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 e, GHC.Classes.Eq ok) => GHC.Classes.Eq (Text.Reform.Result.Result e ok)
instance (GHC.Show.Show e, GHC.Show.Show ok) => 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 defines the Form 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 Form.
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 FormId.
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 NoEnvironment 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 NoEnviroment is different than supplying an empty
--   environment.
data Environment m input
Environment :: (FormId -> m (Value input)) -> Environment m input
NoEnvironment :: Environment m input

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

-- | Utility function: increment the current FormId.
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 Form contains a View 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.
--   
--   
--   
- m A monad which can be used by the validator
--   
- input A framework specific type for representing
--   the raw key/value pairs from the form data
--   
- error A application specific type for error
--   messages
--   
- view The type of data being generated for the view
--   (HSP, Blaze Html, Heist, etc)
--   
- proof A type which names what has been proved
--   about the return value. () means nothing has been
--   proved.
--   
- a Value return by form when it is successfully
--   decoded, validated, etc.
--   
--   
--   This type is very similar to the Form type from
--   digestive-functors <= 0.2. If proof is
--   (), then Form is an applicative functor and can be
--   used almost exactly like digestive-functors <= 0.2.
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:
--   
--   
--   
- Left view on failure. The view will have
--   already been applied to the errors.
--   
- Right a on success.
--   
eitherForm :: Monad m => Environment m input -> Text -> Form m input error view proof a -> m (Either view a)

-- | create a Form from some view.
--   
--   This is typically used to turn markup like <br> into a
--   Form.
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 Forms on the left and right hand side will share the same
--   FormId. This is useful for elements like <label
--   for="someid">, 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 ++>.
(<++) :: (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 <fieldset> 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
--   FormState
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.Base.Semigroup v => GHC.Base.Semigroup (Text.Reform.Core.View error v)
instance (GHC.Show.Show proofs, GHC.Show.Show a) => GHC.Show.Show (Text.Reform.Core.Proved proofs a)
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 ())
instance GHC.Base.Functor (Text.Reform.Core.View e)
instance (GHC.Base.Semigroup input, GHC.Base.Monad m) => GHC.Base.Semigroup (Text.Reform.Core.Environment m input)
instance (GHC.Base.Semigroup input, GHC.Base.Monad m) => GHC.Base.Monoid (Text.Reform.Core.Environment m input)
instance GHC.Base.Functor (Text.Reform.Core.Proved ())

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

-- | A Proof 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 Proof has a unique data-type associated with it
--   which names the proof, such as:
--   
--   
--   data NotNull = NotNull
--   
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 Proof to a Form
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 Form using a Proof, and the replace the
--   proof with ().
--   
--   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 Form result using a monadic Either
--   function.
transformEitherM :: Monad m => Form m input error view anyProof a -> (a -> m (Either error b)) -> Form m input error view () b

-- | transform the Form result using an Either 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 String is a decimal number
data Decimal
Decimal :: Decimal

-- | proof that a String 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 RealFrac number
realFrac :: (Monad m, RealFrac a) => (String -> error) -> Proof m error RealFractional String a

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

-- | This module contains two classes. FormInput is a class which is
--   parameterized over the input 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 FormError 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 Exception so that we
--   can get rid of the FormError 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 CommonFormError
commonFormErrorStr :: (input -> String) -> CommonFormError input -> String

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

-- | Class which all backends should implement.
class FormInput input where {
    
    -- | <tt>input</tt> is here the type that is used to represent a value
    --   uploaded by the client in the request.
    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 Text
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 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 <input
--   type="text">, 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 <input type="submit"> 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 <input type="reset"> 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 <input type="file">
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, <select
--   multiple="multiple"> 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 <select> 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 <select> 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 <label> elements
label :: Monad m => (FormId -> view) -> Form m input error view () ()

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

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

module Text.Reform
