formatter

= Formatters Package
Alessandro Sanino <a.sanino@arduino.cc>
:source-highlighter: pygments
:pygments-style: manni

Formatters is a package which contains a useful and customizable set of formatters for your application.

. Formatter - A generic `interface` to format data.
. TextFormatter - Formats and Prints `interface{}` to Text String - Binded to `String()` method.
. JSONFormatter - Formats and Prints `interface{}` to JSON String - Binded to `json.Marshal()` method.

== Usage 
[source, go]
----
type TestType struct {
   field1 string `json:"field1,omitempty"` //same json tag as required by json.Marshal
   field2 int    `json:"field2"`           //same json tag as required by json.Marshal
}

var a Formatter = TextFormatter{}
var b JSONFormatter = JSONFormatter{} 

var test TestType{
    field1 : "test",
    field2 : 42,
}

var testString = a.Format(test) 
fmt.Println(testString) // Prints test.String()
a.Print(test) // Does the same.

testString = b.Format(test) 
fmt.Println(testString) // Prints { field1 : "test", field2 : "42" }
b.Print(test) // Does the same
----

=== The default formatter
There is a global formatter which can be used across other packages. You can set it with the `formatter.setFormatter(Formatter)` function.
[source, go]
----

type TestType struct {
   field1 string `json:"field1,omitempty"` //same json tag as required by json.Marshal
   field2 int    `json:"field2"`           //same json tag as required by json.Marshal
}

var test TestType{
    field1 : "test",
    field2 : 42,
}

formatter.setFormatter("text")
formatter.Print(test) // Prints string representation of the test struct, using String().
formatter.setFormatter("json")
formatter.Print(test) // Prints test struct as a JSON object.
----

== Custom Formatters
It is possible to add custom formatters with the `formatter.AddCustomFormatter(format, Formatter)` function.

Let's assume we want to add a YamlFormatter which parses to Yaml Objects.
[source, go]
----
// Solution 1 : YamlFormatter is a struct.
type YamlFormatter struct{}

func (yf YamlFormatter) Format(msg interface{}) (string, error) {
    // do something and return values.
}

//...
formatter.AddCustomFormatter("yaml", YamlFormatter{})
//...

// Solution 2 : YamlFormatter is a int8 or other primitive type, useful for formatters which does not need fields.
type YamlFormatter int8

func (yf YamlFormatter) Format(msg interface{}) (string, error) {
    // do something and return values.
}

//...
formatter.AddCustomFormatter("yaml", YamlFormatter(3)) // every int8 is valid, this is a cast.
----

== Printing Errors
Just use `formatter.PrintErrorMessage(string)` or `formatter.PrintError(error)` function.
[source, go]
----
var errormessage string = "Some error occurred"
formatter.PrintErrorMessage(errormessage) // Prints the error formatted properly.

err := functionWhichMayReturnAnError()
if err != nil {
    formatter.PrintError(err)
}
----

== Debug with JSON values
`JSONFormatter` by default does not print what it cannot parse (everything which is not a map or a struct).
If you are in a debugging session you will print an error message instead.
Sessions are opened by `formatterInstance.StartDebug()` and closed by `formatterInstance.EndDebug()`

[source, go]
----
formatter = JSONFormatter{}
formatter.StartDebug()
formatter.Print("Invalid String")
//Outputs "\"Invalid String\" is a non supported data, please use map or struct"
formatter.EndDebug()
----