Construct a parser for a field. Combine multiple fields using applicative syntax like so:

type LoginFields = '["username", "password", "remember_me"]

data LoginForm = LoginForm
  { loginUsername   :: Text
  , loginPassword   :: Text
  , loginRememberMe :: Bool
  }

loginForm :: Monad m => FormParser LoginFields Text m LoginForm
loginForm = LoginForm
  <$> field #username notEmpty
  <*> field #password notEmpty
  <*> field' #remember_me

notEmpty :: Monad m => Text -> ExceptT Text m Text
notEmpty txt =
  if T.null txt
    then throwError "This field cannot be empty"
    else return txt

Referring to the types in the function's signature, s is extracted from JSON Value for you automatically using its FromJSON instance. The field value is taken in assumption that top level Value is a dictionary, and field name is a key in that dictionary. So for example a valid JSON input for the form shown above could be this:

{
  "username": "Bob",
  "password": "123",
  "remember_me": true
}

Once the value of type s is extracted, the validation phase beings. The supplied checker (you can easily compose them with (>=>), as they are Kleisli arrows) is applied to the s value and validation either succeeds producing an a value, or we collect an error as a value of e type.

To run a form composed from fields, see runForm.

field fieldName check = withCheck fieldName check (field' fieldName)

The same as field, but does not require a checker.

field' fieldName = subParser fieldName value

Interpret the current field as a value of type a.

Use a given parser to parse a field. Suppose that you have a parser loginForm that parses a structure like this one:

{
  "username": "Bob",
  "password": "123",
  "remember_me": true
}

Then subParser #login loginForm will parse this:

{
  "login": {
     "username": "Bob",
     "password": "123",
     "remember_me": true
   }
}

Transform a form by applying a checker on its result.

passwordsMatch (a, b) = do
  if a == b
    then return a
    else throwError "Passwords don't match!"

passwordForm =
  withCheck #password_confirmation passwordsMatch
    ((,) <$> field #password notEmpty
         <*> field #password_confirmation notEmpty)

Note that you must specify the field name on which to add a validation error message in case the check fails. The field name should be relative and point to a field in the argument parser, not full path from top-level of the form. For example this form:

biggerForm = subParser #password_form passwordForm

will report validation error for the field "password_form.password_confirmation" if the check fails (note that "password_form" is correctly prepended to the field path).

Run a parser on given input.

Run form purely.

Since: 1.1.0

Project field path from a FieldName.

Project textual representation of path to a field.

The type represents the parser that you can run on a Value with help of runForm. The only way for the user of the library to create a parser is via the field function and its friends, see below. Users can combine existing parsers using applicative notation.

FormParser is parametrized by four type variables:

• names—collection of field names we can use in a form to be parsed with this parser.
• e—type of validation errors.
• m—underlying monad, FormParser is not a monad itself, so it's not a monad transformer, but validation can make use of the m monad.
• a—result of parsing.

FormParser is not a monad because it's not possible to write a Monad instance with the properties that we want (validation errors should not lead to short-cutting behavior).

Result of parsing. names is the collection of allowed field names, e is the type of validation errors, and a is the type of parsing result.

FieldName names represents a non-empty vector of Text components that serve as a path to some field in a JSON structure. Every component is guaranteed to be in the names, which is a set of strings on type level. The purpose if this type is to avoid typos and to force users to update field names everywhere when they decide to change them. The only way to obtain a value of the type FieldName is by using OverloadedLabels. Note that you can combine field names using (<>).

showFieldName (#login_form <> #username) = "login_form.username"

The type function computes a Constraint which is satisfied when its first argument is contained in its second argument. Otherwise a friendly type error is displayed.