-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | ditto is a type-safe HTML form generation and validation library -- -- ditto 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 ditto @version 0.0.1.0 -- | Module for the core result type, and related functions module Ditto.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 FormId :: String -> NonEmpty Integer -> FormId -- | Global prefix for the form [formPrefix] :: FormId -> String -- | Stack indicating field. Head is most specific to this item [formIdList] :: FormId -> NonEmpty Integer FormIdCustom :: String -> FormId -- | The zero ID, i.e. the first ID that is usable zeroId :: String -> FormId -- | map a function over the NonEmpty Integer inside a -- FormId mapId :: (NonEmpty Integer -> NonEmpty Integer) -> FormId -> FormId -- | 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 (Ditto.Result.Result e ok) instance (GHC.Show.Show e, GHC.Show.Show ok) => GHC.Show.Show (Ditto.Result.Result e ok) instance GHC.Show.Show Ditto.Result.FormRange instance GHC.Classes.Eq Ditto.Result.FormRange instance GHC.Classes.Ord Ditto.Result.FormId instance GHC.Classes.Eq Ditto.Result.FormId instance GHC.Base.Functor (Ditto.Result.Result e) instance GHC.Base.Monad (Ditto.Result.Result e) instance GHC.Base.Applicative (Ditto.Result.Result e) instance GHC.Show.Show Ditto.Result.FormId -- | This module defines the Form type, its instances, core -- manipulation functions, and a bunch of helper utilities. module Ditto.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. -- -- -- -- 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: -- -- 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 pure 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 (Ditto.Core.View error v) instance GHC.Base.Semigroup v => GHC.Base.Semigroup (Ditto.Core.View error v) instance (GHC.Show.Show proofs, GHC.Show.Show a) => GHC.Show.Show (Ditto.Core.Proved proofs a) instance GHC.Base.Monad m => Data.Bifunctor.Bifunctor (Ditto.Core.Form m input view error) instance (GHC.Base.Monoid view, GHC.Base.Monad m) => Data.Biapplicative.Biapplicative (Ditto.Core.Form m input error view) instance GHC.Base.Functor m => GHC.Base.Functor (Ditto.Core.Form m input error view ()) instance (GHC.Base.Functor m, GHC.Base.Monoid view, GHC.Base.Monad m) => GHC.Base.Applicative (Ditto.Core.Form m input error view ()) instance GHC.Base.Functor (Ditto.Core.View e) instance (GHC.Base.Semigroup input, GHC.Base.Monad m) => GHC.Base.Semigroup (Ditto.Core.Environment m input) instance (GHC.Base.Semigroup input, GHC.Base.Monad m) => GHC.Base.Monoid (Ditto.Core.Environment m input) instance GHC.Base.Functor (Ditto.Core.Proved ()) -- | This module defines the Proof type, some proofs, and some -- helper functions. -- -- A Proof does three things: -- -- module Ditto.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 Ditto.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 ditto-* -- 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 { -- | input 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 (Ditto.Backend.CommonFormError input) instance GHC.Classes.Ord input => GHC.Classes.Ord (Ditto.Backend.CommonFormError input) instance GHC.Classes.Eq input => GHC.Classes.Eq (Ditto.Backend.CommonFormError input) module Ditto.Generalized.Named -- | used for constructing elements like <input -- type="text">, which pure a single input value. input :: (Monad m, FormError err) => (input -> Either err a) -> (FormId -> a -> view) -> a -> String -> Form m input err view () a -- | used for elements like <input type="submit"> which are -- not always present in the form submission data. inputMaybe :: (Monad m, FormError err) => (input -> Either err a) -> (FormId -> a -> view) -> a -> String -> Form m input err 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 -> String -> Form m input err view () () -- | used for <input type="file"> inputFile :: forall m input err view. (Monad m, FormInput input, FormError err, ErrorInputType err ~ input) => (FormId -> view) -> String -> Form m input err view () (FileType input) -- | used for groups of checkboxes, <select -- multiple="multiple"> boxes inputMulti :: forall m input err view a lbl. (Functor m, FormError err, ErrorInputType err ~ input, FormInput input, Monad m) => [(a, lbl)] -> (FormId -> [(FormId, Int, lbl, Bool)] -> view) -> (a -> Bool) -> String -> Form m input err view () [a] -- | radio buttons, single <select> boxes inputChoice :: forall a m err input lbl view. (Functor m, FormError err, ErrorInputType err ~ input, FormInput input, Monad m) => (a -> Bool) -> [(a, lbl)] -> (FormId -> [(FormId, Int, lbl, Bool)] -> view) -> String -> Form m input err view () a -- | radio buttons, single <select> boxes inputChoiceForms :: forall a m err input lbl view proof. (Functor m, Monad m, FormError err, ErrorInputType err ~ input, FormInput input) => a -> [(Form m input err view proof a, lbl)] -> (FormId -> [(FormId, Int, FormId, view, lbl, Bool)] -> view) -> String -> Form m input err view proof a -- | used to create <label> elements label :: Monad m => (FormId -> view) -> Form m input err view () () -- | used to add a list of err 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 => ([err] -> view) -> Form m input err view () () -- | similar to errors but includes err messages from children of -- the form as well. childErrors :: Monad m => ([err] -> view) -> Form m input err view () () module Ditto.Generalized -- | used for constructing elements like <input -- type="text">, which pure a single input value. input :: (Monad m, FormError err) => (input -> Either err a) -> (FormId -> a -> view) -> a -> Form m input err view () a -- | used for elements like <input type="submit"> which are -- not always present in the form submission data. inputMaybe :: (Monad m, FormError err) => (input -> Either err a) -> (FormId -> a -> view) -> a -> Form m input err 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 err view () () -- | used for <input type="file"> inputFile :: forall m input err view. (Monad m, FormInput input, FormError err, ErrorInputType err ~ input) => (FormId -> view) -> Form m input err view () (FileType input) -- | used for groups of checkboxes, <select -- multiple="multiple"> boxes inputMulti :: forall m input err view a lbl. (Functor m, FormError err, ErrorInputType err ~ input, FormInput input, Monad m) => [(a, lbl)] -> (FormId -> [(FormId, Int, lbl, Bool)] -> view) -> (a -> Bool) -> Form m input err view () [a] -- | radio buttons, single <select> boxes inputChoice :: forall a m err input lbl view. (Functor m, FormError err, ErrorInputType err ~ input, FormInput input, Monad m) => (a -> Bool) -> [(a, lbl)] -> (FormId -> [(FormId, Int, lbl, Bool)] -> view) -> Form m input err view () a -- | radio buttons, single <select> boxes inputChoiceForms :: forall a m err input lbl view proof. (Functor m, Monad m, FormError err, ErrorInputType err ~ input, FormInput input) => a -> [(Form m input err view proof a, lbl)] -> (FormId -> [(FormId, Int, FormId, view, lbl, Bool)] -> view) -> Form m input err view proof a -- | used to create <label> elements label :: Monad m => (FormId -> view) -> Form m input err view () () -- | used to add a list of err 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 => ([err] -> view) -> Form m input err view () () -- | similar to errors but includes err messages from children of -- the form as well. childErrors :: Monad m => ([err] -> view) -> Form m input err view () () module Ditto