structure: clarifiy docs and add examples for omitnested tag option

structure.go

@@ -21,6 +21,13 @@ var (
 //   // Field is ignored by this package.
 //   Field bool `structure:"-"`
 //
+// A value with the option of "omitnested" stops iterating further if the type
+// is a struct. Example:
+//
+//   // Field is not processed further by this package.
+//   Field time.Time     `structure:"myName,omitnested"`
+//   Field *http.Request `structure:",omitnested"`
+//
 // Note that only exported fields of a struct can be accessed, non exported
 // fields will be neglected. It panics if s's kind is not struct.
 func Map(s interface{}) map[string]interface{} {
@@ -61,6 +68,13 @@ func Map(s interface{}) map[string]interface{} {
 //   // Field is ignored by this package.
 //   Field int `structure:"-"`
 //
+// A value with the option of "omitnested" stops iterating further if the type
+// is a struct. Example:
+//
+//   // Field is not processed further by this package.
+//   Field time.Time     `structure:"myName,omitnested"`
+//   Field *http.Request `structure:",omitnested"`
+//
 // Note that only exported fields of a struct can be accessed, non exported
 // fields  will be neglected.  It panics if s's kind is not struct.
 func Values(s interface{}) []interface{} {
@@ -94,6 +108,13 @@ func Values(s interface{}) []interface{} {
 //   // Field is ignored by this package.
 //   Field bool `structure:"-"`
 //
+// A value with the option of "omitnested" stops iterating further if the type
+// is a struct. Example:
+//
+//   // Field is not processed further by this package.
+//   Field time.Time     `structure:"myName,omitnested"`
+//   Field *http.Request `structure:",omitnested"`
+//
 // Note that only exported fields of a struct can be accessed, non exported
 // fields  will be neglected. It panics if s's kind is not struct.
 func Fields(s interface{}) []string {
@@ -126,6 +147,13 @@ func Fields(s interface{}) []string {
 //   // Field is ignored by this package.
 //   Field bool `structure:"-"`
 //
+// A value with the option of "omitnested" stops iterating further if the type
+// is a struct. Example:
+//
+//   // Field is not processed further by this package.
+//   Field time.Time     `structure:"myName,omitnested"`
+//   Field *http.Request `structure:",omitnested"`
+//
 // Note that only exported fields of a struct can be accessed, non exported
 // fields  will be neglected. It panics if s's kind is not struct.
 func IsZero(s interface{}) bool {
@@ -166,6 +194,13 @@ func IsZero(s interface{}) bool {
 //   // Field is ignored by this package.
 //   Field bool `structure:"-"`
 //
+// A value with the option of "omitnested" stops iterating further if the type
+// is a struct. Example:
+//
+//   // Field is not processed further by this package.
+//   Field time.Time     `structure:"myName,omitnested"`
+//   Field *http.Request `structure:",omitnested"`
+//
 // Note that only exported fields of a struct can be accessed, non exported
 // fields  will be neglected. It panics if s's kind is not struct.
 func HasZero(s interface{}) bool {

structure_example_test.go

@@ -56,6 +56,36 @@ func ExampleMap_tags() {
 
 }
 
+func ExampleMap_nested() {
+	// By default field with struct types are processed too. We can stop
+	// processing them via "omitnested" tag option.
+	type Server struct {
+		Name string    `structure:"server_name"`
+		ID   int32     `structure:"server_id"`
+		Time time.Time `structure:"time,omitnested"` // do not convert to map[string]interface{}
+	}
+
+	const shortForm = "2006-Jan-02"
+	t, _ := time.Parse("2006-Jan-02", "2013-Feb-03")
+
+	s := &Server{
+		Name: "Zeynep",
+		ID:   789012,
+		Time: t,
+	}
+
+	m := Map(s)
+
+	// access them by the custom tags defined above
+	fmt.Printf("%v\n", m["server_name"])
+	fmt.Printf("%v\n", m["server_id"])
+	fmt.Printf("%v\n", m["time"].(time.Time))
+	// Output:
+	// Zeynep
+	// 789012
+	// 2013-02-03 00:00:00 +0000 UTC
+}
+
 func ExampleValues() {
 	type Server struct {
 		Name    string
@@ -76,6 +106,35 @@ func ExampleValues() {
 	// Values: [Fatih 135790 false]
 }
 
+func ExampleValues_tags() {
+	type Location struct {
+		City    string
+		Country string
+	}
+
+	type Server struct {
+		Name     string
+		ID       int32
+		Enabled  bool
+		Location Location `structure:"-"` // values from location are not included anymore
+	}
+
+	s := &Server{
+		Name:     "Fatih",
+		ID:       135790,
+		Enabled:  false,
+		Location: Location{City: "Ankara", Country: "Turkey"},
+	}
+
+	// Let get all values from the struct s. Note that we don't include values
+	// from the Location field
+	m := Values(s)
+
+	fmt.Printf("Values: %+v\n", m)
+	// Output:
+	// Values: [Fatih 135790 false]
+}
+
 func ExampleFields() {
 	type Access struct {
 		Name         string
@@ -96,6 +155,33 @@ func ExampleFields() {
 	// Fields: [Name LastAccessed Number]
 }
 
+func ExampleFields_nested() {
+	type Person struct {
+		Name   string
+		Number int
+	}
+
+	type Access struct {
+		Person        Person `structure:",omitnested"`
+		HasPermission bool
+		LastAccessed  time.Time
+	}
+
+	s := &Access{
+		Person:        Person{Name: "fatih", Number: 1234567},
+		LastAccessed:  time.Now(),
+		HasPermission: true,
+	}
+
+	// Let's get all fields from the struct s. Note that we don't include the
+	// fields from the Person field anymore due to "omitnested" tag option.
+	m := Fields(s)
+
+	fmt.Printf("Fields: %+v\n", m)
+	// Output:
+	// Fields: [Person HasPermission LastAccessed]
+}
+
 func ExampleIsZero() {
 	type Server struct {
 		Name    string