def validate(schema=None, validators=None, form=None, variable_decode=False,
             dict_char='.', list_char='-', post_only=True, state=None,
             on_get=False, post_gatekeeper= False, auto_error= True, 
             **htmlfill_kwargs):
    """Validate input either for a FormEncode schema, or individual validators

    @validate is used as an action decorator to attempt the validation of a 
    schema or validator list.
    
    this decorator wraps validate_form, and by default calls validate_error
    
    please read the docstring on validate_form for kwargs info    

    ``auto_error``
        Automatically calls validation_error, which redispatches to the form.
        This is enabled by default, preserving backwards compatibility.

    Example:

    .. code-block:: Python

        class SomeController(BaseController):

            def create(self, id):
                return render('/myform.mako')

            @validate(schema=model.forms.myshema(), form='create')
            def update(self, id):
                # Do something with self.form_result
                pass
    """
    def wrapper(func, self, *args, **kwargs):
        """Decorator Wrapper function"""
        validate_form( self , schema=schema, validators=validators, form=form, 
             variable_decode=variable_decode, dict_char=dict_char, list_char=list_char, 
             post_only=post_only, state=state, on_get=on_get, 
             **htmlfill_kwargs )

        if pylons.c.form_errors:
            log.debug("Errors found in validation, parsing form with htmlfill "
                      "for errors")
            request = pylons.request._current_obj()
            request.environ['REQUEST_METHOD'] = 'GET'

            if auto_error:
                return validation_error( self, form= form, errors= pylons.c.form_errors, *args, **kwargs)
            else:
                # pass, it'll return the func as normal
                pass 
        return func(self, *args, **kwargs)
    return decorator(wrapper)


    
def validate_form( self, schema=None, validators=None, form=None, 
             variable_decode=False, dict_char=None, list_char=None, 
             post_only=True, state=None, on_get=False, post_gatekeeper= False, 
             **htmlfill_kwargs ):
    """Validate input either for a FormEncode schema, or individual validators

    Given a form schema or dict of validators, validate will attempt to
    validate the schema or validator list.

    If validation was successful, the valid result dict will be saved
    as ``self.form_result``. Otherwise, the action will be re-run as if it was
    a GET, and the output will be filled by FormEncode's htmlfill to fill in
    the form field errors.
    
    the first argument is self -- a pylons controller object

    ``schema``
        Refers to a FormEncode Schema object to use during validation.
    ``form``
        Method used to display the form, which will be used to get the 
        HTML representation of the form for error filling.
    ``variable_decode``
        Boolean to indicate whether FormEncode's variable decode function 
        should be run on the form input before validation.
    ``dict_char``
        Passed through to FormEncode. Toggles the form field naming 
        scheme used to determine what is used to represent a dict. This
        option is only applicable when used with variable_decode=True.
    ``list_char``
        Passed through to FormEncode. Toggles the form field naming
        scheme used to determine what is used to represent a list. This
        option is only applicable when used with variable_decode=True.
    ``post_only``
        Boolean that indicates whether or not GET (query) variables should
        be included during validation.
        
        .. warning::
            ``post_only`` applies to *where* the arguments to be
            validated come from. It does *not* restrict the form to only
            working with post, merely only checking POST vars.
    ``state``
        Passed through to FormEncode for use in validators that utilize
        a state object.
    ``on_get``
        Whether to validate on GET requests. By default only POST requests
        are validated.
    ``post_gatekeeper``
        Boolean that indicates to fail on GET requests.  

    Example:

    .. code-block:: Python

        class SomeController(BaseController):

            def create(self, id):
                return render('/myform.mako')

            @validate(schema=model.forms.myshema(), form='create')
            def update(self, id):
                # Do something with self.form_result
                pass
    """
    request = pylons.request._current_obj()
    pylons.c.form_errors= {}
    
    if not pylons.c.pylons_forms:
        pylons.c.pylons_forms= {}

    # Zuul, Gozer would be proud of you.
    if post_gatekeeper and request.environ['REQUEST_METHOD'] == 'GET':
        pylons.c.form_errors['ErrorMain']= 'GETing a POST only form'
        return False

    # Skip the validation if on_get is False and its a GET
    if not on_get and request.environ['REQUEST_METHOD'] == 'GET':
        return func(self, *args, **kwargs)
    
    # If they want post args only, use just the post args
    if post_only:
        params = request.POST
    else:
        params = request.params
    
    is_unicode_params = isinstance(params, UnicodeMultiDict)
    params = params.mixed()
    if variable_decode:
        log.debug("Running variable_decode on params")
        decoded = variabledecode.variable_decode(params, dict_char,
                                                 list_char)
    else:
        decoded = params

    
    if schema:
        log.debug("Validating against a schema")
        try:
            self.form_result = schema.to_python(decoded, state)
        except formencode.Invalid, e:
            pylons.c.form_errors = e.unpack_errors(variable_decode, dict_char, list_char)
    if validators:
        log.debug("Validating against provided validators")
        if isinstance(validators, dict):
            if not hasattr(self, 'form_result'):
                self.form_result = {}
            for field, validator in validators.iteritems():
                try:
                    self.form_result[field] = \
                        validator.to_python(decoded.get(field), state)
                except formencode.Invalid, error:
                    pylons.c.form_errors[field] = error

    validation_store = compute_validation_store( schema=schema, validators=validators )
    pylons.c.pylons_forms[validation_store] = {
        'errors': pylons.c.form_errors.copy(),
        'result': {},
        'is_unicode_params' : is_unicode_params,
        'is_validated' : True,
        'params' : params.copy(),
    }
    if hasattr(self, 'form_result'):
       pylons.c.pylons_forms[validation_store]['result']= self.form_result

    pylons.c.form_validated = True
    pylons.c.form_params = params
    pylons.c.form_is_unicode_params = is_unicode_params
    pylons.c.form_last_validated= validation_store
    
    if pylons.c.form_errors:
        return False
    return True
    
def compute_validation_store( schema=None, validators=None ):
    """compute a validation store field
    """
    validation_store_schema= ''
    validation_store_validators= ''
    if schema:
        validation_store_schema = "%s"%schema.__class__
    if validators:
        if isinstance(validators, dict):
            validation_store_validators= []
            for field, validator in validators.iteritems():
                validation_store_validators.append(field)
            validation_store_validators.sort()
            validation_store_validators = ':'.join(validation_store)

    validation_store= '%s|%s' % ( validation_store_schema , validation_store_validators )
    return validation_store

def validation_error( self, form=None, errors= None, schema=None , validators= None, *args, **htmlfill_kwargs):
    """redispatch to a form generating function
    
    this requires that the form was validated with validate_form to set 
    certain environment variables in pylons.c
    
    Example:

    .. code-block:: Python

        class SomeController(BaseController):

            def form_print(self, id):
                return render('/myform.mako')

            @validate(schema=model.forms.myshema(), form='form_print')
            def form_submit(self, id):
                result= database_query()
                if not result:
                    errors= {'login' : "oh no you don't" }
                    return validation_error( 
                        self, 
                        form= 'form_print', 
                        errors= errors
                    ) 
    """
    # If there's no form supplied, just continue with the current
    # function call.
    if not form:
        raise ValueError( 'form is required' )

    if not errors:
        raise ValueError( 'errors dict is required' )
    
    validation_store = pylons.c.form_last_validated
    if schema or validators:
        validation_store = compute_validation_store( schema=schema, validators=validators )

    if validation_store not in pylons.c.pylons_forms:
        raise ValueError( 'form has not been validated' )

    request = pylons.request._current_obj()
    
    request.environ['pylons.routes_dict']['action'] = form
    response = self._dispatch_call()
    # XXX: Legacy WSGIResponse support
    legacy_response = False
    if hasattr(response, 'wsgi_response'):
        form_content = ''.join(response.content)
        legacy_response = True
    else:
        form_content = response
        response = pylons.response._current_obj()

    # Ensure htmlfill can safely combine the form_content, params and
    # errors variables (that they're all of the same string type)
    if not pylons.c.pylons_forms[validation_store]['is_unicode_params']:
        log.debug("Raw string form params: ensuring the '%s' form and "
                  "FormEncode errors are converted to raw strings for "
                  "htmlfill", form)
        encoding = determine_response_charset(response)

        # WSGIResponse's content may (unlikely) be unicode
        if isinstance(form_content, unicode):
            form_content = form_content.encode(encoding,
                                               response.errors)

        # FormEncode>=0.7 errors are unicode (due to being localized
        # via ugettext). Convert any of the possible formencode
        # unpack_errors formats to contain raw strings
        errors = encode_formencode_errors(errors, encoding,
                                          response.errors)
    elif not isinstance(form_content, unicode):
        log.debug("Unicode form params: ensuring the '%s' form is "
                  "converted to unicode for htmlfill", form)
        encoding = determine_response_charset(response)
        form_content = form_content.decode(encoding)

    print pylons.c.pylons_forms[validation_store]
    defaults= pylons.c.pylons_forms[validation_store]['result'].copy()
    for item in errors.keys():
        if item in defaults:
           del defaults[item]

    form_content = htmlfill.render(form_content, defaults=defaults,
                                   errors=errors, **htmlfill_kwargs)
    if legacy_response:
        # Let the Controller merge the legacy response
        response.content = form_content
        return response
    else:
        return form_content