Paramgen

paramgen/README.md

@@ -0,0 +1,170 @@
+# ParamGen
+
+ParamGen is a conduit tool that generates the code to return the parameters map from a certain Go struct.
+
+## Installation
+
+Once you have installed Go, install the paramgen tool.
+
+**Note:** If you have not done so already be sure to add `$GOPATH/bin` to your `PATH`.
+
+```
+go install github.com/conduitio/conduit-commons/paramgen@latest
+```
+
+## Usage
+
+ParamGen has one required argument, which is the struct name, and two optional flags for the path and the output file name.
+
+```
+paramgen [-path] [-output] structName
+```
+
+Example:
+
+```
+paramgen -path=./source -output=source_params.go SourceConfig
+```
+
+This example will search for a struct called `SourceConfig` in the path `./source`, it will create a parameter map of
+only the exported fields, and generate the code to return this map in the file `source_params.go` under the same folder.
+
+### Parameter Tags
+
+In order to give your parameter a name, a default value, or add some validations to it, tags are the way to go.
+We have three tags that can be parsed:
+
+1. `json`: this tag is used to rename the parameter.
+
+   ```go
+   Name string `json:"first-name"`
+   ```
+
+2. `default`: sets the default value for the parameter.
+
+   ```go
+   Name string `default:"conduit"`
+   ```
+
+3. `validate`: adds builtin validations to the parameter, these validations will be executed by conduit once a connector
+   is configured. Validations are separated by a comma, and have 6 main types:
+    * `required`: a boolean tag to indicate if a field is required or not. If it is added to the validate tag without a
+    value, then we assume the field is required.
+
+      ```go
+      NameRequired    string `validate:"required"`
+      NameRequired2   string `validate:"required=true"`
+      NameNotRequired string `validate:"required=false"`
+      ```
+
+    * `lt` or `less-than`: takes an int or a float value, indicated that the parameter should be less than the value provided.
+    * `gt` or `greater-than`: takes an int or a float value, indicated that the parameter should be greater than the value provided.
+
+      ```go
+      Age int `validate:"gt=0,lt=200"`
+      Age2 float `validate:"greater-than=0,less-than=200.2"`
+      ```
+
+    * `inclusion`: validates that the parameter value is included in a specified list, this list values are separated
+      using a pipe character `|`.
+
+      ```go
+      Gender string `validate:"inclusion=male|female|other"`
+      ```
+
+   * `exclusion`: validates that the parameter value is NOT included in a specified list, this list values are separated
+      using a pipe character `|`.
+
+      ```go
+      Color string `validate:"exclusion=red|green"`
+      ```
+
+   * `regex`: validates that the parameter value matches the regex pattern.
+
+      ```go
+      Email string `validate:"regex=^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$"`
+      ```
+
+## Example
+
+Assume we have this configuration struct:
+
+```go
+package source
+type SourceConfig struct {
+	InnerConfig
+	// Param1 my param1 description
+	Param1 int `validate:"required,gt=0,lt=100" default:"10"`
+	// comment about param2
+	Param2 bool   `validate:"inclusion=true|t,exclusion=false|f" default:"t"`
+	Param3 string `validate:"regex=.*" default:"yes"`
+
+	// this will be ignored because it's not exported
+	privateParam string
+}
+
+type InnerConfig struct {
+	Name string `validate:"required" json:"my-name"`
+}
+```
+
+And you call ParamGen:
+
+```
+paramgen -path ./source SourceConfig
+```
+
+A file called `paramgen.go` will be created under `./source`:
+
+```go
+// Code generated by ParamGen. DO NOT EDIT.
+// Source: github.com/conduitio/conduit-commons/tree/main/paramgen
+
+package source
+
+import (
+	"regexp"
+
+	"github.com/conduitio/conduit-commons/config"
+)
+
+func (SourceConfig) Parameters() map[string]config.Parameter {
+	return map[string]config.Parameter{
+		"my-name": {
+			Default:     "",
+			Description: "",
+			Type:        config.ParameterTypeString,
+			Validations: []config.Validation{
+				config.ValidationRequired{},
+			},
+		},
+		"param1": {
+			Default:     "10",
+			Description: "param1 my param1 description",
+			Type:        config.ParameterTypeInt,
+			Validations: []config.Validation{
+				config.ValidationRequired{},
+				config.ValidationGreaterThan{V: 0},
+				config.ValidationLessThan{V: 100},
+			},
+		},
+		"param2": {
+			Default:     "t",
+			Description: "comment about param2",
+			Type:        config.ParameterTypeBool,
+			Validations: []config.Validation{
+				config.ValidationInclusion{List: []string{"true", "t"}},
+				config.ValidationExclusion{List: []string{"false", "f"}},
+			},
+		},
+		"param3": {
+			Default:     "yes",
+			Description: "",
+			Type:        config.ParameterTypeString,
+			Validations: []config.Validation{
+				config.ValidationRegex{Regex: regexp.MustCompile(".*")},
+			},
+		},
+	}
+}
+```