Merge pull request #4 from dumim/develop

Getting things ready for first stable release

Author: dumim

.circleci/config.yml

@@ -1,4 +1,3 @@
-# Use the latest 2.1 version of CircleCI pipeline process engine. See: https://circleci.com/docs/2.0/configuration-reference
 version: 2.1
 jobs:
   build:
@@ -12,19 +11,17 @@ jobs:
             - go-mod-v4-{{ checksum "go.sum" }}
       - run:
           name: Install Dependencies
-          command: |
-            go mod download
-            go get github.com/mattn/goveralls
+          command: go get ./...
       - save_cache:
           key: go-mod-v4-{{ checksum "go.sum" }}
           paths:
             - "/go/pkg/mod"
+      - run:
+          name: Get coverage libs
+          command: go get github.com/mattn/goveralls
       - run:
           name: Run tests
-          command: |
-            mkdir -p /tmp/test-reports
-            gotestsum --junitfile /tmp/test-reports/unit-tests.xml
-            go test -v -cover -race -coverprofile=/home/ubuntu/coverage.out
-            /home/ubuntu/.go_workspace/bin/goveralls -coverprofile=/home/ubuntu/coverage.out -service=circle-ci -repotoken=$COVERALLS_TOKEN
-      - store_test_results:
-          path: /tmp/test-reports
+          command: go test -v -cover -race -coverprofile=coverage.out
+      - run:
+          name: Push coverage results
+          command: $GOPATH/bin/goveralls -coverprofile=coverage.out -service=circle-ci -repotoken=$COVERALLS_TOKEN

README.md

@@ -1,15 +1,17 @@
 [![Documentation](https://godoc.org/github.com/dumim/tagconv?status.svg)](http://godoc.org/github.com/dumim/tagconv)
 [![Go Report Card](https://goreportcard.com/badge/github.com/dumim/tagconv)](https://goreportcard.com/report/github.com/dumim/tagconv)
+[![Coverage Status](https://coveralls.io/repos/github/dumim/tagconv/badge.svg?branch=main)](https://coveralls.io/github/dumim/tagconv?branch=main)
 [![MIT License](https://img.shields.io/apm/l/atomic-design-ui.svg?)](https://github.com/tterb/atomic-design-ui/blob/master/LICENSEs)
 
 # TagConv
 Convert any Go Struct to a Map based on custom struct tags with dot notation.
 
 ## Background
-This package tries to simplify certain use-cases where a struct needs to be mapped manually to a different struct, which holds the same data but is organised differently.
-(eg: mapping data from the db to a presentable API output)
+This package tries to simplify certain use-cases where the same struct needs to be organised/represented differently (eg: mapping data from the db to a presentable API JSON output).
+This would normally have to be done by having two different structs and manually mapping the data between each other.
 
-This package allows you to use custom struct tags (which could be any string) to define the mapping.
+
+This package allows you to use any custom struct tag to define the mapping.
 This mapping follows the dot-notation convention. Example:
 ```go
 Hello string `mytag:"hello.world"`
@@ -22,13 +24,106 @@ The above will result in a map with the JSON equivalent of:
     }
 }
 ```
-## Usage/Examples
+Any number of custom tags can be used to represent the same struct in unlimited number of different ways. For examples, see below.
+
+
+## Usage & Examples
 
 Import the package
 ```go
 import "github.com/dumim/tagconv"
 ```
 
+Define your struct with custom struct tags:
+
+```go
+type MyStruct struct {
+    Age   string `foo:"age"`
+    Year  int    `foo:"dob.year"`
+    Month int    `foo:"dob.month"`
+}
+
+obj := MyStruct{
+    Age:   "22",
+    Year:  1998,
+    Month: 1,
+}
+
+tagName = "foo"
+myMap, err := ToMap(obj, tagName)
+if err != nil {
+    panic()
+}
+```
+This will result in a map that looks like:
+```go
+myMap = map[string]interface{}{
+	"age": "22",
+	"dob": map[string]interface{}{
+	    "year": 1998,
+	    "month": 1,
+    }
+}
+```
+Converting to JSON ...
+```go
+myMapJSON, err := json.MarshalIndent(myMap, "", "    ")
+    if err != nil {
+    panic()
+}
+fmt.Print(myMapJSON)
+```
+... will result in something similar to:
+```json
+{
+  "age": "22",
+  "dob": {
+    "year": 1998,
+    "month": 1
+  }
+}
+```
+
+---
+### Multiple struct tags
+
+You can use multiple struct tags for different representation of the same struct:
+For example, similar to the previous example:
+```go
+type MyStructMultiple struct {
+    Age   string `foo:"age" bar:"details.my_age"`
+}
+
+obj := MyStruct{
+    Age:   "22",
+}
+```
+Using `tagconv` for `obj` over the `foo` tag (`ToMap(obj, "foo")`) will result in:
+```json
+{
+  "age": "22"
+}
+```
+whereas using `bar` (`ToMap(obj, "bar")`) on the same `obj` will result in:
+```json
+{
+  "details": {
+    "my_age": "22"
+  }
+}
+```
+---
+### Tag options
+- If a nested struct has a tag, this will create a parent-child relationship with that tag and the tags of the fields within that struct.
+- Dot notation will create a parent-child relationship for every `.`.
+- Not setting any tag will ignore that field, unless if it's a struct; then it will go inside the struct to check its tags
+- `-` will explicitly ignore that field. As opposed to above, it will not look inside even if the field is of struct type.
+
+For an example that includes all the above scenarios see the code below:
+
+
+### More complex example
+
 Given a deeply-nested complex struct with custom tags like below:
 ```go
 type Obj struct {
@@ -88,9 +183,7 @@ myMapJSON, err := json.MarshalIndent(myMap, "", "    ")
 if err != nil {
     panic()
 }
-
 fmt.Print(myMapJSON)
-
 ```
 This will produce a result similar to:
 ```json
@@ -122,6 +215,13 @@ This will produce a result similar to:
     ]
 }
 ```
+---
+
+## Testing
+Run the go tests using `go test ./.. -v`
+
+
+---
 
 ## Acknowledgements
 

go.mod

@@ -3,7 +3,6 @@ module github.com/dumim/tagconv
 go 1.15
 
 require (
-	github.com/fatih/structs v1.1.0
 	github.com/imdario/mergo v0.3.12
 	github.com/stretchr/testify v1.7.0
 )

map.go

@@ -7,7 +7,7 @@ import (
 	"strings"
 )
 
-var tagName = ""
+var tagName = "" // initialise the struct tag value
 
 // getMapOfAllKeyValues builds a map of the fully specified key and the value from the struct tag
 // the struct tags with the full dot notation will be used as the key, and the value as the value
@@ -28,13 +28,13 @@ var tagName = ""
 			{"name":"world", "value":2}
 		}
 */
-func getMapOfAllKeyValues(s interface{}) (*map[string]interface{}, error) {
+func getMapOfAllKeyValues(s interface{}) *map[string]interface{} {
 	var vars = make(map[string]interface{}) // this will hold the variables as a map (JSON)
 
 	// get value of object
 	t := reflect.ValueOf(s)
 	if t.IsZero() {
-		return nil, fmt.Errorf("empty struct sent")
+		return nil
 	}
 	// Iterate over all available fields and read the tag value
 	for i := 0; i < t.NumField(); i++ {
@@ -52,9 +52,9 @@ func getMapOfAllKeyValues(s interface{}) (*map[string]interface{}, error) {
 		// and check for its fields inside for tags
 		if tag == "" {
 			if t.Field(i).Kind() == reflect.Struct {
-				// TODO: check for error
+				// only check if the value can be obtained without panicking (eg: for unexported fields)
 				if t.Field(i).CanInterface() {
-					qVars, _ := getMapOfAllKeyValues(t.Field(i).Interface()) //recursive call
+					qVars := getMapOfAllKeyValues(t.Field(i).Interface()) //recursive call
 					for k, v := range *qVars {
 						vars[k] = v
 					}
@@ -65,14 +65,15 @@ func getMapOfAllKeyValues(s interface{}) (*map[string]interface{}, error) {
 		} else {
 			// recursive check nested fields in case this is a struct
 			if t.Field(i).Kind() == reflect.Struct {
-				// TODO: check for error
+				// only check if the value can be obtained without panicking (eg: for unexported fields)
 				if t.Field(i).CanInterface() {
-					qVars, _ := getMapOfAllKeyValues(t.Field(i).Interface())
+					qVars := getMapOfAllKeyValues(t.Field(i).Interface()) //recursive call
 					for k, v := range *qVars {
 						vars[fmt.Sprintf("%s.%s", tag, k)] = v // prepend the parent tag name
 					}
 				}
 			} else {
+				// only check if the value can be obtained without panicking (eg: for unexported fields)
 				if t.Field(i).CanInterface() {
 					vars[tag] = t.Field(i).Interface()
 				}
@@ -93,8 +94,8 @@ func getMapOfAllKeyValues(s interface{}) (*map[string]interface{}, error) {
 			// iterate through the slice
 			for i := 0; i < s.Len(); i++ {
 				if t.Field(i).CanInterface() {
-					m, _ := getMapOfAllKeyValues(s.Index(i).Interface()) // get the map value of the object, recursively
-					sliceOfMap = append(sliceOfMap, *m)                  // append to the slice
+					m := getMapOfAllKeyValues(s.Index(i).Interface()) // get the map value of the object, recursively
+					sliceOfMap = append(sliceOfMap, *m)               // append to the slice
 				}
 			}
 			finalMap[k] = sliceOfMap
@@ -103,7 +104,7 @@ func getMapOfAllKeyValues(s interface{}) (*map[string]interface{}, error) {
 		}
 	}
 
-	return &finalMap, nil
+	return &finalMap
 }
 
 // buildMap builds the parent map and calls buildNestedMap to create the child maps based on dot notation
@@ -124,10 +125,7 @@ func buildMap(s []string, value interface{}, parent *map[string]interface{}) err
 // for a more comprehensive example, please see the
 func ToMap(obj interface{}, tag string) (*map[string]interface{}, error) {
 	tagName = tag
-	s, err := getMapOfAllKeyValues(obj)
-	if err != nil {
-		return nil, err
-	}
+	s := getMapOfAllKeyValues(obj)
 
 	var parentMap = make(map[string]interface{})
 	for k, v := range *s {

map_test.go

@@ -32,9 +32,9 @@ type Example struct {
 	//three    int    `custom:"three"` // unexported, TODO: handle panic
 }
 
-// TestStructToMap calls ToMap function and checks against the expcted result
+// TestFullStructToMap calls ToMap function and checks against the expected result
 // The struct used tries to cover all the scenarios
-func TestStructToMap(t *testing.T) {
+func TestFullStructToMap(t *testing.T) {
 
 	// the initial object
 	initial := Example{
@@ -103,3 +103,60 @@ func TestStructToMap(t *testing.T) {
 	// compare
 	require.JSONEqf(t, expectedJSON, string(actualJSON), "JSON mismatch")
 }
+
+// TestMultipleTagsStructToMap calls ToMap function and checks against the expected result
+// The struct used tries to use multiple struct tags for different responses
+func TestMultipleTagsStructToMap(t *testing.T) {
+	type MyStruct struct {
+		Age   string `foo:"age" bar:"details.myAge"`
+		Year  int    `foo:"dob.year" bar:"details.birthYear"`
+		Month int    `foo:"dob.month" bar:"-"`
+	}
+
+	obj := MyStruct{
+		Age:   "22",
+		Year:  1998,
+		Month: 1,
+	}
+
+	// expected response
+	expectedJSONOne := `{
+		  "age": "22",
+		  "dob": {
+			"year": 1998,
+			"month": 1
+		  }
+		}
+	`
+	expectedJSONTwo := `{
+		  "details": {
+			"myAge": "22",
+			"birthYear": 1998
+		  }
+		}
+	`
+
+	// get the map from custom tags for tag "foo"
+	actualOne, err := ToMap(obj, "foo")
+	if err != nil {
+		t.Fail()
+	}
+	actualJSONOne, err := json.Marshal(actualOne)
+	if err != nil {
+		t.Fail()
+	}
+
+	// get the map from custom tags for tag "bar"
+	actualTwo, err := ToMap(obj, "bar")
+	if err != nil {
+		t.Fail()
+	}
+	actualJSONTwo, err := json.Marshal(actualTwo)
+	if err != nil {
+		t.Fail()
+	}
+
+	// compare
+	require.JSONEqf(t, expectedJSONOne, string(actualJSONOne), "JSON mismatch for foo tags")
+	require.JSONEqf(t, expectedJSONTwo, string(actualJSONTwo), "JSON mismatch for bar tags")
+}