Created Modifiers (markdown)

Modifiers.md

@@ -0,0 +1,71 @@
+### What is a KSQL Modifier?
+
+A KSQL modifier is a special tag you can add to any of the attributes of your struct to alter the behavior of KSQL when reading or writing that attribute into the database. To use it, it is necessary to add the name of the modifier on the `ksql` tag after a comma, e.g.:
+
+```
+`ksql:"column_name,json"`
+```
+
+KSQL comes with a few built-in Modifiers and an API for creating your own modifiers if necessary.
+
+Applying a Modifier to a struct attribute will cause KSQL to use this modifier when Inserting, Updating and Querying that field.
+
+A Modifier can therefore be used for:
+
+1. Making any type of conversion on the attribute value before sending it to the database.
+2. Making any type of conversion on the attribute value when reading it from the database.
+3. Informing KSQL that this attribute should be ignored during Insertions and/or Updates.
+
+This feature was created as a generic solution to the problem of modifying how some attributes are written/read from the database.
+They should be easier to use than the `sql.Valuer` and `sql.Scanner` interfaces for two reasons:
+
+1. They are not coupled to the type of the attribute, but to the attribute itself.
+2. They are reusable: You create it once and you can use it in many attributes of many different types.
+
+### List of Built-in Modifiers
+
+- `json`: It will convert any type to JSON before writing to the database and unmarshal it back from JSON when reading, this makes it
+  easy to save structs as JSON in the database if this fits your use-case.
+- `timeNowUTC`: It only works if on attributes of type `time.Time` and it sets this attribute to `time.Now().UTC()` every time before insertions and updates. This modifier was created to be used on `UpdatedAt` timestamp fields.
+- `timeNowUTC/skipUpdates`: Does the same as the above but only on insertions, during Updates attributes marked with this modifier will be completely ignored. This is useful for `CreatedAt` fields where you only want them to be set once when first creating the record.
+- `skipUpdates`: Will ignore fields on updates.
+- `skipInserts`: Will ignore fields on inserts.
+
+Here is an example of how a `User` struct might look like using some of these modifiers:
+
+```golang
+type user struct {
+	ID   uint   `ksql:"id"`
+	Name string `ksql:"name"`
+	Age  int    `ksql:"age"`
+
+	Address Address `ksql:"address,json"`
+
+	UpdatedAt time.Time `ksql:"updated_at,timeNowUTC"`
+	CreatedAt time.Time `ksql:"created_at,timeNowUTC/skipUpdates"`
+}
+```
+
+### Registering new Modifiers
+
+Registering a new Modifier is simple: Describe it using an instance of `ksqlmodifiers.AttrModifier` and register it on KSQL by calling the global function: `ksqlmodifiers.RegisterAttrModifier` as illustrated below:
+
+```golang
+func init() {
+	ksqlmodifiers.RegisterAttrModifier("my_modifier_name", ksqlmodifiers.AttrModifier{
+		SkipInserts: false, // set it to true if you want this modifier to cause the field to be ignored on inserts.
+
+		SkipUpdates: false, // set it to true if you want this modifier to cause the field to be ignored on updates.
+	
+		Scan: func(ctx context.Context, opInfo ksqlmodifiers.OpInfo, attrPtr interface{}, dbValue interface{}) error {
+			// Read the dbValue, modify it and then save it into the attrPtr argument using reflection.
+		},
+
+		Value: func(ctx context.Context, opInfo ksqlmodifiers.OpInfo, inputValue interface{}) (outputValue interface{}, _ error) {
+			// Read the inputValue, modify it and then return it so the database can save it.
+		},
+	})
+}
+```
+
+This registration should be performed inside your code before making any calls to the KSQL library. I recommend doing it inside a `init()` function since then it will run before `main()` starts.