go-playground
diff --git a/‎README.md‎
Lines changed: 146 additions & 99 deletions b/‎README.md‎
Lines changed: 146 additions & 99 deletions
@@ -2,7 +2,7 @@ Package validator
 ================
 <img align="right" src="https://raw.githubusercontent.com/go-playground/validator/v9/logo.png">
 [![Join the chat at https://gitter.im/bluesuncorp/validator](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/go-playground/validator?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
-![Project status](https://img.shields.io/badge/alpha-9.0.0-red.svg)
+![Project status](https://img.shields.io/badge/RC1-9.0.0-yellow.svg)
 [![Build Status](https://semaphoreci.com/api/v1/projects/ec20115f-ef1b-4c7d-9393-cc76aba74eb4/530054/badge.svg)](https://semaphoreci.com/joeybloggs/validator)
 [![Coverage Status](https://coveralls.io/repos/go-playground/validator/badge.svg?branch=v9&service=github)](https://coveralls.io/github/go-playground/validator?branch=v9)
 [![Go Report Card](https://goreportcard.com/badge/github.com/go-playground/validator)](https://goreportcard.com/report/github.com/go-playground/validator)
@@ -77,7 +77,7 @@ type User struct {
 	LastName       string     `validate:"required"`
 	Age            uint8      `validate:"gte=0,lte=130"`
 	Email          string     `validate:"required,email"`
-	FavouriteColor string     `validate:"hexcolor|rgb|rgba"`
+	FavouriteColor string     `validate:"iscolor"`                // alias for 'hexcolor|rgb|rgba|hsl|hsla'
 	Addresses      []*Address `validate:"required,dive,required"` // a person can have a home and cottage...
 }
 
@@ -89,16 +89,15 @@ type Address struct {
 	Phone  string `validate:"required"`
 }
 
+// use a single instance of Validate, it caches struct info
 var validate *validator.Validate
 
 func main() {
 
-	config := &validator.Config{TagName: "validate"}
-
-	validate = validator.New(config)
+	validate = validator.New()
 
 	validateStruct()
-	validateField()
+	validateVariable()
 }
 
 func validateStruct() {
@@ -114,24 +113,36 @@ func validateStruct() {
 		LastName:       "Smith",
 		Age:            135,
 		Email:          "[email protected]",
-		FavouriteColor: "#000",
+		FavouriteColor: "#000-",
 		Addresses:      []*Address{address},
 	}
 
 	// returns nil or ValidationErrors ( map[string]*FieldError )
-	errs := validate.Struct(user)
-
-	if errs != nil {
+	err := validate.Struct(user)
+	if err != nil {
+
+		// this check is only needed when your code could produce
+		// an invalid value for validation such as interface with nil
+		// value most including myself do not usually have code like this.
+		if _, ok := err.(*validator.InvalidValidationError); ok {
+			fmt.Println(err)
+			return
+		}
 
-		fmt.Println(errs) // output: Key: "User.Age" Error:Field validation for "Age" failed on the "lte" tag
-		//	                         Key: "User.Addresses[0].City" Error:Field validation for "City" failed on the "required" tag
-		err := errs.(validator.ValidationErrors)["User.Addresses[0].City"]
-		fmt.Println(err.Field) // output: City
-		fmt.Println(err.Tag)   // output: required
-		fmt.Println(err.Kind)  // output: string
-		fmt.Println(err.Type)  // output: string
-		fmt.Println(err.Param) // output:
-		fmt.Println(err.Value) // output:
+		for _, err := range err.(validator.ValidationErrors) {
+
+			fmt.Println(err.Namespace())
+			fmt.Println(err.Field())
+			fmt.Println(err.StructNamespace()) // can differ when a custom TagNameFunc is registered or
+			fmt.Println(err.StructField())     // by passing alt name to ReportError like below
+			fmt.Println(err.Tag())
+			fmt.Println(err.ActualTag())
+			fmt.Println(err.Kind())
+			fmt.Println(err.Type())
+			fmt.Println(err.Value())
+			fmt.Println(err.Param())
+			fmt.Println()
+		}
 
 		// from here you can create your own error messages in whatever language you wish
 		return
@@ -140,10 +151,11 @@ func validateStruct() {
 	// save user to database
 }
 
-func validateField() {
+func validateVariable() {
+
 	myEmail := "joeybloggs.gmail.com"
 
-	errs := validate.Field(myEmail, "required,email")
+	errs := validate.Var(myEmail, "required,email")
 
 	if errs != nil {
 		fmt.Println(errs) // output: Key: "" Error:Field validation for "" failed on the "email" tag
@@ -164,7 +176,7 @@ import (
 	"fmt"
 	"reflect"
 
-	"gopkg.in/go-playground/validator.v8"
+	"gopkg.in/go-playground/validator.v9"
 )
 
 // DbBackedUser User struct
@@ -173,32 +185,38 @@ type DbBackedUser struct {
 	Age  sql.NullInt64  `validate:"required"`
 }
 
-func main() {
+// use a single instance of Validate, it caches struct info
+var validate *validator.Validate
 
-	config := &validator.Config{TagName: "validate"}
+func main() {
 
-	validate := validator.New(config)
+	validate = validator.New()
 
 	// register all sql.Null* types to use the ValidateValuer CustomTypeFunc
 	validate.RegisterCustomTypeFunc(ValidateValuer, sql.NullString{}, sql.NullInt64{}, sql.NullBool{}, sql.NullFloat64{})
 
+	// build object for validation
 	x := DbBackedUser{Name: sql.NullString{String: "", Valid: true}, Age: sql.NullInt64{Int64: 0, Valid: false}}
-	errs := validate.Struct(x)
 
-	if len(errs.(validator.ValidationErrors)) > 0 {
-		fmt.Printf("Errs:\n%+v\n", errs)
+	err := validate.Struct(x)
+
+	if err != nil {
+		fmt.Printf("Err(s):\n%+v\n", err)
 	}
 }
 
 // ValidateValuer implements validator.CustomTypeFunc
 func ValidateValuer(field reflect.Value) interface{} {
+
 	if valuer, ok := field.Interface().(driver.Valuer); ok {
+
 		val, err := valuer.Value()
 		if err == nil {
 			return val
 		}
 		// handle the error how you want
 	}
+
 	return nil
 }
 ```
@@ -209,7 +227,6 @@ package main
 
 import (
 	"fmt"
-	"reflect"
 
 	"gopkg.in/go-playground/validator.v9"
 )
@@ -232,41 +249,19 @@ type Address struct {
 	Phone  string `validate:"required"`
 }
 
+// use a single instance of Validate, it caches struct info
 var validate *validator.Validate
 
 func main() {
 
-	config := &validator.Config{TagName: "validate"}
+	validate = validator.New()
 
-	validate = validator.New(config)
+	// register validation for 'User'
+	// NOTE: only have to register a non-pointer type for 'User', validator
+	// interanlly dereferences during it's type checks.
 	validate.RegisterStructValidation(UserStructLevelValidation, User{})
 
-	validateStruct()
-}
-
-// UserStructLevelValidation contains custom struct level validations that don't always
-// make sense at the field validation level. For Example this function validates that either
-// FirstName or LastName exist; could have done that with a custom field validation but then
-// would have had to add it to both fields duplicating the logic + overhead, this way it's
-// only validated once.
-//
-// NOTE: you may ask why wouldn't I just do this outside of validator, because doing this way
-// hooks right into validator and you can combine with validation tags and still have a
-// common error output format.
-func UserStructLevelValidation(v *validator.Validate, structLevel *validator.StructLevel) {
-
-	user := structLevel.CurrentStruct.Interface().(User)
-
-	if len(user.FirstName) == 0 && len(user.LastName) == 0 {
-		structLevel.ReportError(reflect.ValueOf(user.FirstName), "FirstName", "fname", "fnameorlname")
-		structLevel.ReportError(reflect.ValueOf(user.LastName), "LastName", "lname", "fnameorlname")
-	}
-
-	// plus can to more, even with different tag than "fnameorlname"
-}
-
-func validateStruct() {
-
+	// build 'User' info, normally posted data etc...
 	address := &Address{
 		Street: "Eavesdown Docks",
 		Planet: "Persphone",
@@ -283,62 +278,114 @@ func validateStruct() {
 		Addresses:      []*Address{address},
 	}
 
-	// returns nil or ValidationErrors ( map[string]*FieldError )
-	errs := validate.Struct(user)
+	// returns InvalidValidationError for bad validation input, nil or ValidationErrors ( []FieldError )
+	err := validate.Struct(user)
+	if err != nil {
 
-	if errs != nil {
+		// this check is only needed when your code could produce
+		// an invalid value for validation such as interface with nil
+		// value most including myself do not usually have code like this.
+		if _, ok := err.(*validator.InvalidValidationError); ok {
+			fmt.Println(err)
+			return
+		}
 
-		fmt.Println(errs) // output: Key: 'User.LastName' Error:Field validation for 'LastName' failed on the 'fnameorlname' tag
-		//	                         Key: 'User.FirstName' Error:Field validation for 'FirstName' failed on the 'fnameorlname' tag
-		err := errs.(validator.ValidationErrors)["User.FirstName"]
-		fmt.Println(err.Field) // output: FirstName
-		fmt.Println(err.Tag)   // output: fnameorlname
-		fmt.Println(err.Kind)  // output: string
-		fmt.Println(err.Type)  // output: string
-		fmt.Println(err.Param) // output:
-		fmt.Println(err.Value) // output:
+		for _, err := range err.(validator.ValidationErrors) {
+
+			fmt.Println(err.Namespace())
+			fmt.Println(err.Field())
+			fmt.Println(err.StructNamespace()) // can differ when a custom TagNameFunc is registered or
+			fmt.Println(err.StructField())     // by passing alt name to ReportError like below
+			fmt.Println(err.Tag())
+			fmt.Println(err.ActualTag())
+			fmt.Println(err.Kind())
+			fmt.Println(err.Type())
+			fmt.Println(err.Value())
+			fmt.Println(err.Param())
+			fmt.Println()
+		}
 
 		// from here you can create your own error messages in whatever language you wish
 		return
 	}
 
 	// save user to database
 }
+
+// UserStructLevelValidation contains custom struct level validations that don't always
+// make sense at the field validation level. For Example this function validates that either
+// FirstName or LastName exist; could have done that with a custom field validation but then
+// would have had to add it to both fields duplicating the logic + overhead, this way it's
+// only validated once.
+//
+// NOTE: you may ask why wouldn't I just do this outside of validator, because doing this way
+// hooks right into validator and you can combine with validation tags and still have a
+// common error output format.
+func UserStructLevelValidation(sl validator.StructLevel) {
+
+	user := sl.Current().Interface().(User)
+
+	if len(user.FirstName) == 0 && len(user.LastName) == 0 {
+		sl.ReportError(user.FirstName, "FirstName", "fname", "fnameorlname", "")
+		sl.ReportError(user.LastName, "LastName", "lname", "fnameorlname", "")
+	}
+
+	// plus can to more, even with different tag than "fnameorlname"
+}
 ```
 
 Benchmarks
 ------
-###### Run on MacBook Pro (Retina, 15-inch, Late 2013) 2.6 GHz Intel Core i7 16 GB 1600 MHz DDR3 using Go version go1.5.3 darwin/amd64
+###### Run on MacBook Pro (Retina, 15-inch, Late 2013) 2.6 GHz Intel Core i7 16 GB 1600 MHz DDR3 using Go version go1.6.3 darwin/amd64
 ```go
-PASS
-BenchmarkFieldSuccess-8                            	20000000	       118 ns/op	       0 B/op	       0 allocs/op
-BenchmarkFieldFailure-8                            	 2000000	       758 ns/op	     432 B/op	       4 allocs/op
-BenchmarkFieldDiveSuccess-8                        	  500000	      2471 ns/op	     464 B/op	      28 allocs/op
-BenchmarkFieldDiveFailure-8                        	  500000	      3172 ns/op	     896 B/op	      32 allocs/op
-BenchmarkFieldCustomTypeSuccess-8                  	 5000000	       300 ns/op	      32 B/op	       2 allocs/op
-BenchmarkFieldCustomTypeFailure-8                  	 2000000	       775 ns/op	     432 B/op	       4 allocs/op
-BenchmarkFieldOrTagSuccess-8                       	 1000000	      1122 ns/op	       4 B/op	       1 allocs/op
-BenchmarkFieldOrTagFailure-8                       	 1000000	      1167 ns/op	     448 B/op	       6 allocs/op
-BenchmarkStructLevelValidationSuccess-8            	 3000000	       548 ns/op	     160 B/op	       5 allocs/op
-BenchmarkStructLevelValidationFailure-8            	 3000000	       558 ns/op	     160 B/op	       5 allocs/op
-BenchmarkStructSimpleCustomTypeSuccess-8           	 2000000	       623 ns/op	      36 B/op	       3 allocs/op
-BenchmarkStructSimpleCustomTypeFailure-8           	 1000000	      1381 ns/op	     640 B/op	       9 allocs/op
-BenchmarkStructPartialSuccess-8                    	 1000000	      1036 ns/op	     272 B/op	       9 allocs/op
-BenchmarkStructPartialFailure-8                    	 1000000	      1734 ns/op	     730 B/op	      14 allocs/op
-BenchmarkStructExceptSuccess-8                     	 2000000	       888 ns/op	     250 B/op	       7 allocs/op
-BenchmarkStructExceptFailure-8                     	 1000000	      1036 ns/op	     272 B/op	       9 allocs/op
-BenchmarkStructSimpleCrossFieldSuccess-8           	 2000000	       773 ns/op	      80 B/op	       4 allocs/op
-BenchmarkStructSimpleCrossFieldFailure-8           	 1000000	      1487 ns/op	     536 B/op	       9 allocs/op
-BenchmarkStructSimpleCrossStructCrossFieldSuccess-8	 1000000	      1261 ns/op	     112 B/op	       7 allocs/op
-BenchmarkStructSimpleCrossStructCrossFieldFailure-8	 1000000	      2055 ns/op	     576 B/op	      12 allocs/op
-BenchmarkStructSimpleSuccess-8                     	 3000000	       519 ns/op	       4 B/op	       1 allocs/op
-BenchmarkStructSimpleFailure-8                     	 1000000	      1429 ns/op	     640 B/op	       9 allocs/op
-BenchmarkStructSimpleSuccessParallel-8             	10000000	       146 ns/op	       4 B/op	       1 allocs/op
-BenchmarkStructSimpleFailureParallel-8             	 2000000	       551 ns/op	     640 B/op	       9 allocs/op
-BenchmarkStructComplexSuccess-8                    	  500000	      3269 ns/op	     244 B/op	      15 allocs/op
-BenchmarkStructComplexFailure-8                    	  200000	      8436 ns/op	    3609 B/op	      60 allocs/op
-BenchmarkStructComplexSuccessParallel-8            	 1000000	      1024 ns/op	     244 B/op	      15 allocs/op
-BenchmarkStructComplexFailureParallel-8            	  500000	      3536 ns/op	    3609 B/op	      60 allocs/op
+BenchmarkFieldSuccess-8                                    	10000000	       147 ns/op	       0 B/op	       0 allocs/op
+BenchmarkFieldSuccessParallel-8                            	30000000	        42.5 ns/op	       0 B/op	       0 allocs/op
+BenchmarkFieldFailure-8                                    	 3000000	       417 ns/op	     192 B/op	       4 allocs/op
+BenchmarkFieldFailureParallel-8                            	10000000	       140 ns/op	     192 B/op	       4 allocs/op
+BenchmarkFieldDiveSuccess-8                                	 2000000	       876 ns/op	     201 B/op	      11 allocs/op
+BenchmarkFieldDiveSuccessParallel-8                        	 5000000	       277 ns/op	     201 B/op	      11 allocs/op
+BenchmarkFieldDiveFailure-8                                	 1000000	      1185 ns/op	     396 B/op	      16 allocs/op
+BenchmarkFieldDiveFailureParallel-8                        	 3000000	       402 ns/op	     397 B/op	      16 allocs/op
+BenchmarkFieldCustomTypeSuccess-8                          	 5000000	       321 ns/op	      32 B/op	       2 allocs/op
+BenchmarkFieldCustomTypeSuccessParallel-8                  	20000000	       104 ns/op	      32 B/op	       2 allocs/op
+BenchmarkFieldCustomTypeFailure-8                          	 3000000	       416 ns/op	     192 B/op	       4 allocs/op
+BenchmarkFieldCustomTypeFailureParallel-8                  	10000000	       150 ns/op	     192 B/op	       4 allocs/op
+BenchmarkFieldOrTagSuccess-8                               	 1000000	      1119 ns/op	      16 B/op	       1 allocs/op
+BenchmarkFieldOrTagSuccessParallel-8                       	 3000000	       462 ns/op	      16 B/op	       1 allocs/op
+BenchmarkFieldOrTagFailure-8                               	 2000000	       715 ns/op	     208 B/op	       5 allocs/op
+BenchmarkFieldOrTagFailureParallel-8                       	 3000000	       436 ns/op	     208 B/op	       5 allocs/op
+BenchmarkStructLevelValidationSuccess-8                    	 3000000	       399 ns/op	      32 B/op	       2 allocs/op
+BenchmarkStructLevelValidationSuccessParallel-8            	20000000	       140 ns/op	      32 B/op	       2 allocs/op
+BenchmarkStructLevelValidationFailure-8                    	 2000000	       749 ns/op	     288 B/op	       8 allocs/op
+BenchmarkStructLevelValidationFailureParallel-8            	 5000000	       296 ns/op	     288 B/op	       8 allocs/op
+BenchmarkStructSimpleCustomTypeSuccess-8                   	 2000000	       673 ns/op	      32 B/op	       2 allocs/op
+BenchmarkStructSimpleCustomTypeSuccessParallel-8           	10000000	       213 ns/op	      32 B/op	       2 allocs/op
+BenchmarkStructSimpleCustomTypeFailure-8                   	 1000000	      1056 ns/op	     392 B/op	       9 allocs/op
+BenchmarkStructSimpleCustomTypeFailureParallel-8           	 3000000	       450 ns/op	     408 B/op	      10 allocs/op
+BenchmarkStructPartialSuccess-8                            	 2000000	       789 ns/op	     256 B/op	       6 allocs/op
+BenchmarkStructPartialSuccessParallel-8                    	 5000000	       307 ns/op	     256 B/op	       6 allocs/op
+BenchmarkStructPartialFailure-8                            	 1000000	      1105 ns/op	     464 B/op	      11 allocs/op
+BenchmarkStructPartialFailureParallel-8                    	 5000000	       493 ns/op	     464 B/op	      11 allocs/op
+BenchmarkStructExceptSuccess-8                             	 1000000	      1212 ns/op	     480 B/op	      12 allocs/op
+BenchmarkStructExceptSuccessParallel-8                     	10000000	       282 ns/op	     240 B/op	       5 allocs/op
+BenchmarkStructExceptFailure-8                             	 1000000	      1004 ns/op	     448 B/op	      10 allocs/op
+BenchmarkStructExceptFailureParallel-8                     	 5000000	       452 ns/op	     448 B/op	      10 allocs/op
+BenchmarkStructSimpleCrossFieldSuccess-8                   	 2000000	       656 ns/op	      72 B/op	       3 allocs/op
+BenchmarkStructSimpleCrossFieldSuccessParallel-8           	 5000000	       211 ns/op	      72 B/op	       3 allocs/op
+BenchmarkStructSimpleCrossFieldFailure-8                   	 2000000	       968 ns/op	     288 B/op	       8 allocs/op
+BenchmarkStructSimpleCrossFieldFailureParallel-8           	 5000000	       406 ns/op	     288 B/op	       8 allocs/op
+BenchmarkStructSimpleCrossStructCrossFieldSuccess-8        	 1000000	      1000 ns/op	      80 B/op	       4 allocs/op
+BenchmarkStructSimpleCrossStructCrossFieldSuccessParallel-8	 5000000	       334 ns/op	      80 B/op	       4 allocs/op
+BenchmarkStructSimpleCrossStructCrossFieldFailure-8        	 1000000	      1324 ns/op	     304 B/op	       9 allocs/op
+BenchmarkStructSimpleCrossStructCrossFieldFailureParallel-8	 3000000	       520 ns/op	     304 B/op	       9 allocs/op
+BenchmarkStructSimpleSuccess-8                             	 3000000	       534 ns/op	       0 B/op	       0 allocs/op
+BenchmarkStructSimpleSuccessParallel-8                     	10000000	       144 ns/op	       0 B/op	       0 allocs/op
+BenchmarkStructSimpleFailure-8                             	 1000000	      1039 ns/op	     392 B/op	       9 allocs/op
+BenchmarkStructSimpleFailureParallel-8                     	 5000000	       419 ns/op	     392 B/op	       9 allocs/op
+BenchmarkStructComplexSuccess-8                            	  500000	      2678 ns/op	     128 B/op	       8 allocs/op
+BenchmarkStructComplexSuccessParallel-8                    	 2000000	       874 ns/op	     128 B/op	       8 allocs/op
+BenchmarkStructComplexFailure-8                            	  200000	      6342 ns/op	    2833 B/op	      53 allocs/op
+BenchmarkStructComplexFailureParallel-8                    	 1000000	      2875 ns/op	    2833 B/op	      53 allocs/op
 ```
 
 Complimentary Software