translate

README

translate 🗺️

Object TranslationUtilities for Go

This library maps data from one variable into another. requires a schema for both input and output values, which must be compatable with schema Getter and Setter interfaces. The best way to use this library is with a mapof.Any which already includes these interfaces.

Mapping Utilities

Path

{"path":"original.path", "target":"target.path"}

Value

{"value":"FIXED VALUE HERE", "target":"target.path"}

Expression

{"path":"{{go template expression}}", "target":"target.path"}

Conditionals

{"if":"{{go template expression}}", "then":[/* additional rules */], "else":[/* additional rules */]}

ForEach

{"path":"original.path", "target":"target.path", "filter":"{{go template expression}}", "rules":[/* additional rules*/]}

Pull Requests Welcome

This library is a work in progress, and will benefit from your experience reports, use cases, and contributions. If you have an idea for making this library better, send in a pull request. We're all in this together! 🗺️

Documentation

Index

• type Pipeline
  • func New(rules ...Rule) Pipeline
  • func NewFromJSON(jsonString string) (Pipeline, error)
  • func NewFromMap(rules ...map[string]any) (Pipeline, error)
  • func (pipeline Pipeline) Execute(inSchema schema.Schema, inObject any, outSchema schema.Schema, outObject any) error
  • func (pipeline Pipeline) IsEmpty() bool
  • func (pipeline Pipeline) NotEmpty() bool
• type Rule
  • func Condition(condition string, thenRules []Rule, elseRules []Rule) Rule
  • func Expression(expression string, target string) Rule
  • func ForEach(sourcePath string, targetPath string, filter string, rulesMap []map[string]any) Rule
  • func Path(from string, target string) Rule
  • func Value(value any, target string) Rule
  • func (rule *Rule) UnmarshalJSON(data []byte) error
  • func (rule *Rule) UnmarshalMap(data mapof.Any) error
• type Runner

Examples

• New
• NewFromJSON
• NewFromMap
• Pipeline.Execute

Types

type Pipeline

type Pipeline []Rule

Pipeline represents a slice of Rule objects

func New

func New(rules ...Rule) Pipeline

New returns a new Pipeline object, populated with the provided rules

Example

// Define rules for the translation Pipeline
rules := []Rule{
	Expression("{{.firstName}} {{.lastName}}", "fullName"),
	Path("email", "email"),
	Value("person", "type"),
	Condition(`{{eq "M" .gender}}`, []Rule{
		Expression("{{.firstName}} is Male", "comment"),
	}, []Rule{
		Expression("{{.firstName}} is not Malr", "comment"),
	}),
}

// Add all of the rules to a new Pipeline
translator := New(rules...)
fmt.Println(translator)

func NewFromJSON

func NewFromJSON(jsonString string) (Pipeline, error)

NewFromJSON reads a JSON string and returns a Pipeline object

Example

// Import JSON from external source
rulesJSON := `[
		{"expression": "{{.firstName}} {{.lastName}}", "target": "fullName"},
		{"path": "email", "target": "email"},
		{"value": "person", "target": "type"},
		{"if": "{{eq \"M\" .gender}}", "then": [
			{"target": "comment", "expression": "{{.firstName}} is Male"}
		], "else": [
			{"target": "comment", "expression": "{{.firstName}} is not Male"}
		]}
	]`

// Unmarshal JSON directly into a Pipeline
rules, _ := NewFromMap()
if json.Unmarshal([]byte(rulesJSON), &rules) != nil {
	fmt.Println("Error parsing JSON")
}

// Success!
fmt.Println(rules)

func NewFromMap

func NewFromMap(rules ...map[string]any) (Pipeline, error)

NewFromMap parses a slice of mapof.Any objects into a Pipeline

Example

// Define rules as a mapof.Any
rules := []map[string]any{
	{"expression": "{{.firstName}} {{.lastName}}", "target": "fullName"},
	{"path": "email", "target": "email"},
	{"value": "person", "target": "type"},
	{"if": `{{eq "M" .gender}}`, "then": []mapof.Any{
		{"target": "comment", "expression": "{{.firstName}} is Male"},
	}, "else": []mapof.Any{
		{"target": "comment", "expression": "{{.firstName}} is not Male"},
	}},
}

// Create a new Pipeline from the rules
if translator, err := NewFromMap(rules...); err != nil {
	fmt.Println(err)
} else {
	fmt.Println(translator)
}

func (Pipeline) Execute

func (pipeline Pipeline) Execute(inSchema schema.Schema, inObject any, outSchema schema.Schema, outObject any) error

Execute runs each of the rules in the Pipeline

Example

// SOURCE DATA
sourceValue := mapof.Any{
	"firstName": "John",
	"lastName":  "Connor",
	"email":     "john@connor.mil",
	"gender":    "M",
}

// TARGET CONFIGURATION
targetSchema := schema.New(schema.Object{
	Properties: schema.ElementMap{
		"fullName": schema.String{},
		"email":    schema.String{Format: "email"},
		"type":     schema.String{},
		"comment":  schema.String{},
	},
})
targetValue := mapof.Any{}

// CREATE MAPPING RULES
rules, err := NewFromMap(
	mapof.Any{"expression": "{{.firstName}} {{.lastName}}", "target": "fullName"},
	mapof.Any{"path": "email", "target": "email"},
	mapof.Any{"value": "person", "target": "type"},
	mapof.Any{"if": "{{eq \"M\" .gender}}", "then": []mapof.Any{
		{"target": "comment", "expression": "{{.firstName}} is Male"},
	}, "else": []mapof.Any{
		{"target": "comment", "expression": "{{.firstName}} is not Male"},
	}},
)
derp.Report(err)

// MAP DATA FROM SOURCE TO TARGET
err = rules.Execute(schema.Wildcard(), sourceValue, targetSchema, &targetValue)
derp.Report(err)

// OUTPUT RESULTS
fmt.Println(targetValue.GetString("fullName"))
fmt.Println(targetValue.GetString("email"))
fmt.Println(targetValue.GetString("type"))
fmt.Println(targetValue.GetString("comment"))

Output:

John Connor
john@connor.mil
person
John is Male

func (Pipeline) IsEmpty

func (pipeline Pipeline) IsEmpty() bool

func (Pipeline) NotEmpty

func (pipeline Pipeline) NotEmpty() bool

type Rule

type Rule struct {
	Runner
}

Rule represents a single mapping rule

func Condition

func Condition(condition string, thenRules []Rule, elseRules []Rule) Rule

Condition creates a new Rule that executes a condition, and then runs a set of rules based on the result

func Expression

func Expression(expression string, target string) Rule

Expression creates a new Rule that executes a template expression

func ForEach

func ForEach(sourcePath string, targetPath string, filter string, rulesMap []map[string]any) Rule

ForEach creates a new Rule that copies a value from one location to another

func Path

func Path(from string, target string) Rule

Path creates a new Rule that copies a value from one location to another

func Value

func Value(value any, target string) Rule

Value creates a new Rule that writes a constant value to the output object

func (*Rule) UnmarshalJSON

func (rule *Rule) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the json.Unmarshaller interface

func (*Rule) UnmarshalMap

func (rule *Rule) UnmarshalMap(data mapof.Any) error

UnmarshalMap populates this object from a mapof.Any

type Runner

type Runner interface {

	// Execute runs the rule on the input object, and writes the result to the output object
	Execute(inSchema schema.Schema, inObject any, outSchema schema.Schema, outObject any) error
}

Runner in the interface for objects that implement Rules