DataQ

= DataQ

DataQ's allows to access fields of complex data structure, referencing the fields by means of fully qualified names based on a dot notation.

Given the following data structure as example:

[source,golang]
----
type Level3 struct {
	Delta int
}

type Level2 struct {
	Ypsilon int
	Omega   string
	Epsilon *Level3
}

type Level1 struct {
	Alfa  float64
	beta  string
	Gamma *Level2
	Zeta  map[string]float64
}}

var l2 = Level2{
		Ypsilon: 5,
		Omega:   "hello",
		Epsilon: nil,
	}
var l1 = Level1{
		Alfa:  1.0,
		beta:  "not accessible because not exported",
		Gamma: &l2,
		Zeta: map[string]float64{
			"key1": 10.5,
			"key2": 12.5,
		},
	}
----

Following actions are possible using DataQ:

[source,golang]
----
surfer := NewSurfer()

alfa, _ := s.GetFloat64("Alfa")
ypsilon, _ := s.GetInt64("Gamma.Ypsilon")
omega, _ := s.GetString("Gamma.Omega")
----

Beyond accessing a single field, DataQ allows to translate a data structure into a flat map[string]interface{} object, where:author: 

* keys are the fully qualified name of the original fields
* values can only be the primitive supported data

== Why DataQ?

DataQ may be useful when you have to handle data transfer objects coming from external API. Instead of remapping the DTO into an internal complete (or partial) data representation, it can be an interface{} and its fields can be accessed using DataQ.

Another possible scenario is Govaluate footnote:[https://github.com/Knetic/govaluate]. Govaluate evaluates arbitrary expressions, starting from a set of variables represented by a __map[string]interface{}__. Thinking of the cases where the desired variables come from a complex data structure, DataQ may help you translating the latter into a __map[string]interface{}__.

For instance, given the previous data structure, you may calculate the expression _Alfa + Gamma_Yplison_ in the following way:

[source,golang]
----
s := NewSurfer(WithSep("_"))
expr, _ := govaluate.NewEvaluableExpression("Alfa + Gamma_Ypsilon")
flat_data, _ s.GetFlatData(l1)
result, _ := expr.Evaluate(flat_data)
log.Print(result)
----

Note:: in this scenario the separator for the fully qualified names is "_", to avoid conflict with the mathematical syntax of Govaluate.

== How to install

[source,golang]
----
go get github.com/LosAngeles971/DataQ
----

Or: 

[source,golang]
----
go get github.com/LosAngeles971/DataQ@vx.y.z
----

== Technical constraints, limitations and documentations

Immutable:: DataQ only allows to read fields from a complex data structure, write operations are not permitted yet.

Supported data types for fields:: DataQ only to read the following data types:

* string
* float32
* float64
* int
* int64
* bool

Documentation of API:: https://github.com/LosAngeles971/DataQ/blob/main/.docs/DataQ.md

== Inspirational references

* https://github.com/Knetic/govaluate
* https://blog.gopheracademy.com/advent-2018/interfaces-and-reflect/
* https://github.com/jinzhu/copier/blob/master/copier.go
* https://code.rocketnine.space/tslocum/godoc-static