README

binding Build Status Sourcegraph

Middleware binding provides request data binding and validation for Macaron.

Installation
go get github.com/go-macaron/binding

Getting Help

Credits

This package is a modified version of martini-contrib/binding.

License

This project is under the Apache License, Version 2.0. See the LICENSE file for the full license text.

Expand ▾ Collapse ▴

Documentation

Overview

    Package binding is a middleware that provides request data binding and validation for Macaron.

    Index

    Constants

    View Source
    const (
    	// Type mismatch errors.
    	ERR_CONTENT_TYPE    = "ContentTypeError"
    	ERR_DESERIALIZATION = "DeserializationError"
    	ERR_INTERGER_TYPE   = "IntegerTypeError"
    	ERR_BOOLEAN_TYPE    = "BooleanTypeError"
    	ERR_FLOAT_TYPE      = "FloatTypeError"
    
    	// Validation errors.
    	ERR_REQUIRED       = "RequiredError"
    	ERR_ALPHA_DASH     = "AlphaDashError"
    	ERR_ALPHA_DASH_DOT = "AlphaDashDotError"
    	ERR_SIZE           = "SizeError"
    	ERR_MIN_SIZE       = "MinSizeError"
    	ERR_MAX_SIZE       = "MaxSizeError"
    	ERR_RANGE          = "RangeError"
    	ERR_EMAIL          = "EmailError"
    	ERR_URL            = "UrlError"
    	ERR_IN             = "InError"
    	ERR_NOT_INT        = "NotInError"
    	ERR_INCLUDE        = "IncludeError"
    	ERR_EXCLUDE        = "ExcludeError"
    	ERR_DEFAULT        = "DefaultError"
    )
    View Source
    const (
    	STATUS_UNPROCESSABLE_ENTITY = 422
    )

    Variables

    View Source
    var (
    	AlphaDashPattern    = regexp.MustCompile("[^\\d\\w-_]")
    	AlphaDashDotPattern = regexp.MustCompile("[^\\d\\w-_\\.]")
    	EmailPattern        = regexp.MustCompile("[\\w!#$%&'*+/=?^_`{|}~-]+(?:\\.[\\w!#$%&'*+/=?^_`{|}~-]+)*@(?:[\\w](?:[\\w-]*[\\w])?\\.)+[a-zA-Z0-9](?:[\\w-]*[\\w])?")
    )
    View Source
    var MaxMemory = int64(1024 * 1024 * 10)

      Maximum amount of memory to use when parsing a multipart form. Set this to whatever value you prefer; default is 10 MB.

      View Source
      var (
      	URLPattern = regexp.MustCompile(`^` + urlSchemaRx + `?` + urlUsernameRx + `?` + `((` + urlIPRx + `|(\[` + ipRx + `\])|(([a-zA-Z0-9]([a-zA-Z0-9-_]+)?[a-zA-Z0-9]([-\.][a-zA-Z0-9]+)*)|(` + urlSubdomainRx + `?))?(([a-zA-Z\x{00a1}-\x{ffff}0-9]+-?-?)*[a-zA-Z\x{00a1}-\x{ffff}0-9]+)(?:\.([a-zA-Z\x{00a1}-\x{ffff}]{1,}))?))\.?` + urlPortRx + `?` + urlPathRx + `?$`)
      )

      Functions

      func AddParamRule

      func AddParamRule(r *ParamRule)

        AddParamRule adds new validation rule.

        func AddRule

        func AddRule(r *Rule)

          AddRule adds new validation rule.

          func Bind

          func Bind(obj interface{}, ifacePtr ...interface{}) macaron.Handler

            Bind wraps up the functionality of the Form and Json middleware according to the Content-Type and verb of the request. A Content-Type is required for POST and PUT requests. Bind invokes the ErrorHandler middleware to bail out if errors occurred. If you want to perform your own error handling, use Form or Json middleware directly. An interface pointer can be added as a second argument in order to map the struct to a specific interface.

            func BindIgnErr

            func BindIgnErr(obj interface{}, ifacePtr ...interface{}) macaron.Handler

              BindIgnErr will do the exactly same thing as Bind but without any error handling, which user has freedom to deal with them. This allows user take advantages of validation.

              func Form

              func Form(formStruct interface{}, ifacePtr ...interface{}) macaron.Handler

                Form is middleware to deserialize form-urlencoded data from the request. It gets data from the form-urlencoded body, if present, or from the query string. It uses the http.Request.ParseForm() method to perform deserialization, then reflection is used to map each field into the struct with the proper type. Structs with primitive slice types (bool, float, int, string) can support deserialization of repeated form keys, for example: key=val1&key=val2&key=val3 An interface pointer can be added as a second argument in order to map the struct to a specific interface.

                func Json

                func Json(jsonStruct interface{}, ifacePtr ...interface{}) macaron.Handler

                  Json is middleware to deserialize a JSON payload from the request into the struct that is passed in. The resulting struct is then validated, but no error handling is actually performed here. An interface pointer can be added as a second argument in order to map the struct to a specific interface.

                  func MultipartForm

                  func MultipartForm(formStruct interface{}, ifacePtr ...interface{}) macaron.Handler

                    MultipartForm works much like Form, except it can parse multipart forms and handle file uploads. Like the other deserialization middleware handlers, you can pass in an interface to make the interface available for injection into other handlers later.

                    func SetNameMapper

                    func SetNameMapper(nm NameMapper)

                      SetNameMapper sets name mapper.

                      func Validate

                      func Validate(obj interface{}) macaron.Handler

                        Validate is middleware to enforce required fields. If the struct passed in implements Validator, then the user-defined Validate method is executed, and its errors are mapped to the context. This middleware performs no error handling: it merely detects errors and maps them.

                        func Version

                        func Version() string

                        Types

                        type Error

                        type Error struct {
                        	// An error supports zero or more field names, because an
                        	// error can morph three ways: (1) it can indicate something
                        	// wrong with the request as a whole, (2) it can point to a
                        	// specific problem with a particular input field, or (3) it
                        	// can span multiple related input fields.
                        	FieldNames []string `json:"fieldNames,omitempty"`
                        
                        	// The classification is like an error code, convenient to
                        	// use when processing or categorizing an error programmatically.
                        	// It may also be called the "kind" of error.
                        	Classification string `json:"classification,omitempty"`
                        
                        	// Message should be human-readable and detailed enough to
                        	// pinpoint and resolve the problem, but it should be brief. For
                        	// example, a payload of 100 objects in a JSON array might have
                        	// an error in the 41st object. The message should help the
                        	// end user find and fix the error with their request.
                        	Message string `json:"message,omitempty"`
                        }

                        func (Error) Error

                        func (e Error) Error() string

                          Error returns this error's message.

                          func (Error) Fields

                          func (e Error) Fields() []string

                            Fields returns the list of field names this error is associated with.

                            func (Error) Kind

                            func (e Error) Kind() string

                              Kind returns this error's classification.

                              type ErrorHandler

                              type ErrorHandler interface {
                              	// Error handles validation errors with custom process.
                              	Error(*macaron.Context, Errors)
                              }

                                ErrorHandler is the interface that has custom error handling process.

                                type Errors

                                type Errors []Error

                                  Errors may be generated during deserialization, binding, or validation. This type is mapped to the context so you can inject it into your own handlers and use it in your application if you want all your errors to look the same.

                                  func RawValidate

                                  func RawValidate(obj interface{}) Errors

                                    RawValidate is same as Validate but does not require a HTTP context, and can be used independently just for validation. This function does not support Validator interface.

                                    func (*Errors) Add

                                    func (e *Errors) Add(fieldNames []string, classification, message string)

                                      Add adds an error associated with the fields indicated by fieldNames, with the given classification and message.

                                      func (*Errors) Has

                                      func (e *Errors) Has(class string) bool

                                        Has determines whether an Errors slice has an Error with a given classification in it; it does not search on messages or field names.

                                        func (*Errors) Len

                                        func (e *Errors) Len() int

                                          Len returns the number of errors.

                                          type NameMapper

                                          type NameMapper func(string) string

                                            NameMapper represents a form tag name mapper.

                                            type ParamRule

                                            type ParamRule struct {
                                            	// IsMatch checks if rule matches.
                                            	IsMatch func(string) bool
                                            	// IsValid applies validation rule to condition.
                                            	IsValid func(Errors, string, string, interface{}) (bool, Errors)
                                            }

                                              ParamRule does same thing as Rule but passes rule itself to IsValid method.

                                              type ParamRuleMapper

                                              type ParamRuleMapper []*ParamRule

                                              type Rule

                                              type Rule struct {
                                              	// IsMatch checks if rule matches.
                                              	IsMatch func(string) bool
                                              	// IsValid applies validation rule to condition.
                                              	IsValid func(Errors, string, interface{}) (bool, Errors)
                                              }

                                                Rule represents a validation rule.

                                                type RuleMapper

                                                type RuleMapper []*Rule

                                                  RuleMapper and ParamRuleMapper represent validation rule mappers, it allwos users to add custom validation rules.

                                                  type Validator

                                                  type Validator interface {
                                                  	// Validate validates that the request is OK. It is recommended
                                                  	// that validation be limited to checking values for syntax and
                                                  	// semantics, enough to know that you can make sense of the request
                                                  	// in your application. For example, you might verify that a credit
                                                  	// card number matches a valid pattern, but you probably wouldn't
                                                  	// perform an actual credit card authorization here.
                                                  	Validate(*macaron.Context, Errors) Errors
                                                  }

                                                    Validator is the interface that handles some rudimentary request validation logic so your application doesn't have to.