Merge pull request #14 from calyptia/update-docs

Update documentation

README.md

@@ -1,21 +1,112 @@
 # go-fluentbit-config
 
-Library for parsing a fluentbit configuration file according to the specs presented here [0]
+This library parses fluent-bit configuration in three different formats:
 
-[0] https://docs.fluentbit.io/manual/administration/configuring-fluent-bit/format-schema
+  * INI: the standard INI like format (legacy).
+  * YAML: the new YAML format
+  * JSON: a JSON format derived from the YAML formats structure.
+
+It consists of 2 functions for each format as well as the NewFromBytes
+function which is supported for applications which already use it which
+invokes the ParseINI function.
+
+  * INI
+    * ParseINI([]byte) (*Config, error)
+    * DumpINI(*Config) ([]byte, error)
+  * YAML
+    * ParseYAML([]byte) (*Config, error)
+    * DumpYAML(*Config) ([]byte, error)
+  * JSON
+    * ParseJSON([]byte) (*Config, error)
+    * DumpJSON(*Config) ([]byte, error)
+
+The Parse functions return a pointer to a Config structure which holds
+a series of sections.
+
+```go
+type Config struct {
+	Sections    []ConfigSection
+}
+```
+
+These sections describe a single section of the configuration file:
+
+```go
+const (
+	NoneSection ConfigSectionType = iota
+	ServiceSection
+	InputSection
+	FilterSection
+	OutputSection
+	CustomSection
+	ParserSection
+)
+
+type ConfigSection struct {
+	Type   ConfigSectionType
+	ID     string
+	Fields []Field
+}
+```
+
+Each Field has a Key and a set of Values. Most fields contain a single,
+but some exceptions, like the `Rewrite_Tag` property `Rule`, have
+multiple Values.
+
+```go
+type Field struct {
+	Key    string
+	Values []*Value
+}
+
+type Value struct {
+	String     *string
+	DateTime   *string
+	Date       *string
+	Time       *string
+	TimeFormat *string
+	Topic      *string
+	Regex      *string
+	Bool       *bool
+	Number     *float64
+	Float      *float64
+	List       []*Value
+}
+```
+
+The Value type has a two receiver methods that which make using values
+easier.
+
+```go
+func (a *Value) Equals(b *Value) bool
+func (v *Value) Value() interface{}
+```
+
+The `Equals` receiver can be used to compare two `Value`s, and the `Value`
+receiver can be used to return an interface{} which can be type switched.
 
 ## example usage
 ```go
-    import (
-        "github.com/calyptia/go-fluentbit-config"
-    )
-
-    cfg, err := fluentbit_config.NewFromBytes([]byte(`[INPUT] ....`))
-    if err != nil {
-    }
-
-    for name, filters := range cfg.Filters {
-	    for name, property := range filters {
-            }
-    }   	
+import (
+	fbitconf "github.com/calyptia/go-fluentbit-config"
+)
+
+cfg, err := fbitconf.ParseINI([]byte(`[INPUT] ....`))
+if err != nil {
+	panic(err)
+}
+
+for _, section := range cfg.Sections {
+	if section.Type == fbitconf.FilterSection {
+		for _, field := section.Fields {
+			if field.Key == "Name" {
+				fmt.Printf("filter: %s\n", field.Key)
+			}
+		}
+	}
+}
 ```
+
+References:
+
+  * Fluentbit schema: https://docs.fluentbit.io/manual/administration/configuring-fluent-bit/format-schema

parser.go

@@ -16,7 +16,7 @@ var (
 		{"DateTime", `\d\d\d\d-\d\d-\d\dT\d\d:\d\d:\d\d(\.\d+)?(-\d\d:\d\d)?`, nil},
 		{"Date", `\d\d\d\d-\d\d-\d\d`, nil},
 		{"Time", `\d\d:\d\d:\d\d(\.\d+)?`, nil},
-		{"TimeFormat", `((%[dbYHMSz])(\:|\/|\ |\-|))+`, nil},
+		{"TimeFormat", `((%([aAbBhcCdeDHIjmMnprRStTUwWxXyYLz]|E[cCxXyY]|O[deHImMSUwWy]))(\:|\/| |\-|T|Z|\.|))+`, nil},
 		{"Ident", `[a-zA-Z_\.\*\-0-9\/\{\}]+`, nil},
 		{"String", `[a-zA-Z0-9_\.\/\*\-]+`, nil},
 		{"Number", `[-+]?[.0-9]+\b`, nil},

parser_test.go

@@ -924,6 +924,13 @@ func TestNewConfigFromBytes(t *testing.T) {
 					Time_Key    time
 					Time_Format %b %d %H:%M:%S
 					Time_Keep   On
+				[PARSER]
+					Name        mongodb
+					Format      regex
+					Regex       ^(?<time>[^ ]*)\s+(?<severity>\w)\s+(?<component>[^ ]+)\s+\[(?<context>[^\]]+)]\s+(?<message>.*?) *(?<ms>(\d+))?(:?ms)?$
+					Time_Format %Y-%m-%dT%H:%M:%S.%L
+					Time_Keep   On
+					Time_Key    time
 			`),
 			expected: Config{
 				Sections: []ConfigSection{{
@@ -948,6 +955,28 @@ func TestNewConfigFromBytes(t *testing.T) {
 							String: stringPtr("On"),
 						}}},
 					},
+				}, {
+					Type: ParserSection,
+					Fields: []Field{
+						{Key: "Name", Values: []*Value{{
+							String: stringPtr("mongodb"),
+						}}},
+						{Key: "Format", Values: []*Value{{
+							String: stringPtr("regex"),
+						}}},
+						{Key: "Regex", Values: []*Value{{
+							Regex: stringPtr(`^(?<time>[^ ]*)\s+(?<severity>\w)\s+(?<component>[^ ]+)\s+\[(?<context>[^\]]+)]\s+(?<message>.*?) *(?<ms>(\d+))?(:?ms)?$`),
+						}}},
+						{Key: "Time_Format", Values: []*Value{{
+							TimeFormat: stringPtr("%Y-%m-%dT%H:%M:%S.%L"),
+						}}},
+						{Key: "Time_Keep", Values: []*Value{{
+							String: stringPtr("On"),
+						}}},
+						{Key: "Time_Key", Values: []*Value{{
+							String: stringPtr("time"),
+						}}},
+					},
 				}},
 			},
 			expectedError: false,