Add documentation for cross struct validation tags + Struct Partials

doc.go

@@ -21,7 +21,7 @@ Custom Functions
 Custom functions can be added
 
 	// Structure
-	func customFunc(topStruct reflect.Value, currentStruct reflect.Value, field reflect.Value, fieldType reflect.Type, fieldKind reflect.Kind, param string) bool {
+	func customFunc(v *Validate, topStruct reflect.Value, currentStructOrField reflect.Value, field reflect.Value, fieldType reflect.Type, fieldKind reflect.Kind, param string) bool {
 
 		if whatever {
 			return false
@@ -36,18 +36,41 @@ Custom functions can be added
 
 Cross Field Validation
 
-Cross Field Validation can be implemented, for example Start & End Date range validation
+Cross Field Validation can be done via the following tags: eqfield, nefield, gtfield, gtefield,
+ltfield, ltefield, eqcsfield, necsfield, gtcsfield, ftecsfield, ltcsfield and ltecsfield. If
+however some custom cross field validation is required, it can be done using a custom validation.
+
+Why not just have cross fields validation tags i.e. only eqcsfield and not eqfield; the reason is
+efficiency, if you want to check a field within the same struct eqfield only has to find the field
+on the same struct, 1 level; but if we used eqcsfield it could be multiple levels down.
+
+	type Inner struct {
+		StartDate time.Time
+	}
+
+	type Outer struct {
+		InnerStructField *Inner
+		CreatedAt time.Time      `validate:"ltecsfield=InnerStructField.StartDate"`
+	}
+
+	now := time.Now()
+
+	inner := &Inner{
+		StartDate: now,
+	}
+
+	outer := &Outer{
+		InnerStructField: inner,
+		CreatedAt: now,
+	}
+
+	errs := validate.Struct(outer)
 
 	// NOTE: when calling validate.Struct(val) topStruct will be the top level struct passed
 	//       into the function
 	//       when calling validate.FieldWithValue(val, field, tag) val will be
 	//       whatever you pass, struct, field...
 	//       when calling validate.Field(field, tag) val will be nil
-	//
-	// Because of the specific requirements and field names within each persons project that
-	// uses this library it is likely that custom functions will need to be created for your
-	// Cross Field Validation needs, however there are some build in Generic Cross Field validations,
-	// see Baked In Validators eqfield, nefield, gtfield, gtefield, ltfield, ltefield and Tags below
 
 Multiple Validators
 
@@ -201,6 +224,10 @@ Here is a list of the current built in validators:
 		Validation on Password field using validate.Struct Usage(eqfield=ConfirmPassword)
 		Validating by field validate.FieldWithValue(password, confirmpassword, "eqfield")
 
+	eqcsfield
+		This does the same as eqfield except that it validates the field provided relative
+		to the top level struct. (Usage: eqcsfield=InnerStructField.Field)
+
 	nefield
 		This will validate the field value against another fields value either within
 		a struct or passed in field.
@@ -208,6 +235,10 @@ Here is a list of the current built in validators:
 		Validation on Color field using validate.Struct Usage(nefield=Color2)
 		Validating by field validate.FieldWithValue(color1, color2, "nefield")
 
+	necsfield
+		This does the same as nefield except that it validates the field provided relative
+		to the top level struct. (Usage: necsfield=InnerStructField.Field)
+
 	gtfield
 		Only valid for Numbers and time.Time types, this will validate the field value
 		against another fields value either within a struct or passed in field.
@@ -215,6 +246,10 @@ Here is a list of the current built in validators:
 		Validation on End field using validate.Struct Usage(gtfield=Start)
 		Validating by field validate.FieldWithValue(start, end, "gtfield")
 
+	gtcsfield
+		This does the same as gtfield except that it validates the field provided relative
+		to the top level struct. (Usage: gtcsfield=InnerStructField.Field)
+
 	gtefield
 		Only valid for Numbers and time.Time types, this will validate the field value
 		against another fields value either within a struct or passed in field.
@@ -222,6 +257,10 @@ Here is a list of the current built in validators:
 		Validation on End field using validate.Struct Usage(gtefield=Start)
 		Validating by field validate.FieldWithValue(start, end, "gtefield")
 
+	gtecsfield
+		This does the same as gtefield except that it validates the field provided relative
+		to the top level struct. (Usage: gtecsfield=InnerStructField.Field)
+
 	ltfield
 		Only valid for Numbers and time.Time types, this will validate the field value
 		against another fields value either within a struct or passed in field.
@@ -229,6 +268,10 @@ Here is a list of the current built in validators:
 		Validation on End field using validate.Struct Usage(ltfield=Start)
 		Validating by field validate.FieldWithValue(start, end, "ltfield")
 
+	ltcsfield
+		This does the same as ltfield except that it validates the field provided relative
+		to the top level struct. (Usage: ltcsfield=InnerStructField.Field)
+
 	ltefield
 		Only valid for Numbers and time.Time types, this will validate the field value
 		against another fields value either within a struct or passed in field.
@@ -236,6 +279,10 @@ Here is a list of the current built in validators:
 		Validation on End field using validate.Struct Usage(ltefield=Start)
 		Validating by field validate.FieldWithValue(start, end, "ltefield")
 
+	ltecsfield
+		This does the same as ltefield except that it validates the field provided relative
+		to the top level struct. (Usage: ltecsfield=InnerStructField.Field)
+
 	alpha
 		This validates that a string value contains alpha characters only
 		(Usage: alpha)

validator.go

@@ -93,6 +93,7 @@ type Config struct {
 type CustomTypeFunc func(field reflect.Value) interface{}
 
 // Func accepts all values needed for file and cross field validation
+// v             = validator instance, needed but some built in functions for it's custom types
 // topStruct     = top level struct when validating by struct otherwise nil
 // currentStruct = current level struct when validating by struct otherwise optional comparison value
 // field         = field value for validation
@@ -209,7 +210,9 @@ func (v *Validate) FieldWithValue(val interface{}, field interface{}, tag string
 	return errs
 }
 
-// StructPartial validates the fields that are listed by name in the map including nested structs, unless otherwise specified. Items in the map that are NOT found in the struct will cause a panic.
+// StructPartial validates the fields passed in only, ignoring all others.
+// Fields may be provided in a namespaced fashion relative to the  struct provided
+// i.e. NestedStruct.Field or NestedArrayField[0].Struct.Name
 func (v *Validate) StructPartial(current interface{}, fields ...string) ValidationErrors {
 
 	sv, _ := v.extractType(reflect.ValueOf(current))
@@ -263,7 +266,9 @@ func (v *Validate) StructPartial(current interface{}, fields ...string) Validati
 	return errs
 }
 
-// StructExcept validates the fields in the struct that are NOT listed by name in the map including nested structs, unless otherwise specified. Items in the map that are NOT found in the struct will cause a panic.
+// StructExcept validates all fields except the ones passed in.
+// Fields may be provided in a namespaced fashion relative to the  struct provided
+// i.e. NestedStruct.Field or NestedArrayField[0].Struct.Name
 func (v *Validate) StructExcept(current interface{}, fields ...string) ValidationErrors {
 
 	sv, _ := v.extractType(reflect.ValueOf(current))