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

{"expression":"{{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 NewSliceOfPipelines(slices [][]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) MarshalJSON() ([]byte, error)
  • func (pipeline Pipeline) MarshalSliceOfMap() []map[string]any
  • func (pipeline Pipeline) NotEmpty() bool
• type Rule
  • func Append(append any, target string) 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) MarshalJSON() ([]byte, error)
  • func (rule *Rule) MarshalMap() map[string]any
  • 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 NewSliceOfPipelines

func NewSliceOfPipelines(slices [][]map[string]any) ([]Pipeline, error)

NewSliceOfPipelines parses a slice of maps into a slice of Pipelines. If any of the maps DOES NOT represent a valid Pipeline, then the function will return an error.

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{"target": "fullName", "expression": "{{.firstName}} {{.lastName}}"},
	mapof.Any{"target": "email", "path": "email"},
	mapof.Any{"target": "type", "value": "person"},
	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) MarshalJSON

func (pipeline Pipeline) MarshalJSON() ([]byte, error)

func (Pipeline) MarshalSliceOfMap

func (pipeline Pipeline) MarshalSliceOfMap() []map[string]any

func (Pipeline) NotEmpty

func (pipeline Pipeline) NotEmpty() bool

type Rule

type Rule struct {
	Runner
}

Rule represents a single mapping rule

func Append

func Append(append any, target string) Rule

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

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) MarshalJSON

func (rule *Rule) MarshalJSON() ([]byte, error)

func (*Rule) MarshalMap

func (rule *Rule) MarshalMap() map[string]any

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

	// MarshalMap converts the object to a mapof.Any
	MarshalMap() map[string]any
}

Runner in the interface for objects that implement Rules