morph

type ArgRewriter ¶

type ArgRewriter struct {
	Capture   []Variable
	Formatter string
}

ArgRewriter either describes how an outer function rewrites its inputs before passing them to a wrapped inner function, or how an outer function rewrites the outputs of a wrapped inner function before returning them from the outer function.

It does this through capturing arguments into temporary variables, and formatting a new list of arguments or return values.

This is a low-level implementation for advanced use. The functions in morph/funcwrappers.go provide nicer APIs for many use cases.

A WrappedFunction uses two ArgRewriters in the following sequence, in pseudocode:

func outerfunc(args) (returns) { // step 0, a call to outerfunc
    inputs... = Input ArgRewriter captured args // step 1
    results... = innerfunc(Input ArgWriter formats inputs) // step 2
    outputs = Output ArgRewriter captured results // step 3
    return Output ArgRewriter formats outputs // step 4
}

At each step, an ArgRewriter can retrieve the results of a previous step (and only the immediately previous step) by "$" token notation, accessing a named argument by "$name", and an argument by index by "$n" for some decimal n. At each step, a WrappedFunction uses an ArgRewriter to transform the result of the previous values.

In step 1, the results retrieved by "$" token notation are the input arguments to the outerfunc. In step 2, they are the captured arguments from step 1. In step 3, they are the return values from the innerfunc call. In step 4, they are the captured arguments from step 3.

Capture is a list of Field elements which describe how to temporarily store inputs to or outputs of invocations of the inner function. Only the Name, Type, and Value fields on each capture are used, and each is optional.

If a Name is given, a subsequent step can refer to the result by "$name", not just by index "$n".

The Value of the capture is a code expression of how it stores an input or output. In most cases, this will be simply correspond to the value of a matching input or output, unchanged. Here, inputs and named outputs can be referred to using "$" token notation by name e.g. "$name", or by index e.g. "$0". A value need not refer to any previous step, e.g. can be a literal like "2", or some function call like "time.Now()". For a single-valued result that is used only once, it may be better to do this in Formatter.

A capture with an empty string for a Value at position i in the capture slice captures the argument at position i in the previous step. Likewise, a capture with an empty Type at position i in the capture slice has the type of the argument at position i in the previous step.

The capture arg's Type is a comma-separated list of types that the Value produces. If the type list has more than one entry, e.g. "int, error" then the captured value captures a tuple result type instead of a single value. Each field in the tuple can be accessed by index by adding ".N" for any decimal N to a "$" replacement token e.g. "$name.0" or "$0.3".

All inputs and outputs must be accounted for. This can be achieved by capturing a value, or part of a tuple value, to a capture field with a type of "_". For a tuple value, each discarded element of the tuple must be explicitly discarded, for example with a capture type specified like "int, _, _".

Formatter describes how the captured arguments or results are rewritten as the input arguments to the inner function, or as the outer function's return arguments.

For example, given some function `Foo(x float64) float64`, you can imagine some outer wrapping function using an ArgRewriters that converts it into `func(x float64) (float64, float64) => math.Modf(Foo(x))`, with the following ArgRewriter values:

Input: ArgRewriter{
    Capture: []Field{{Name: "x", Type: "float64", Value: "$x"},},
    Formatter: "$0",
}

Output: ArgRewriter{
    Capture: []Field{
        {Type: "float64, float64", Value: "math.Modf($x)"},
    },
    Formatter: "$0.0, $0.1",
}

type Argument ¶

type Argument struct {
	Name string
	Type string
}

Argument represents a named and typed argument e.g. a type constraint or an argument to a function.

type BuiltinFieldExpression ¶

type BuiltinFieldExpression string

BuiltinFieldExpression is a FieldExpression-like value with a constant builtin FieldExpressionType.

type Field ¶

type Field struct {
	Name    string
	Type    string
	Tag     string
	Comment string

	// For fields appearing in structs that have been mapped only...
	Reverse FieldMapper

	Converter BuiltinFieldExpression // x=y;  See [StructConverter].
	Comparer  BuiltinFieldExpression // x==y; See [Struct.Comparer].
	Copier    BuiltinFieldExpression // x=x;  See [Struct.Copier].
	Orderer   BuiltinFieldExpression // x<y;  See [Struct.Orderer].
	Zeroer    BuiltinFieldExpression // x=0;  See [Struct.Zeroer].
	Truther   BuiltinFieldExpression // x!=0; See [Struct.Truther].

	// Custom are field expressions indexed by the FieldExpressionType's Name.
	// If set, they define a custom operation on the field.
	Custom []FieldExpression
}

Field represents a named and typed field in a struct, with optional struct tags, comments, and various "expressions" describing operations on fields of that type.

Fields should be considered readonly, except inside a FieldMapper.

The Tag, if any, does not include surrounding quote marks, and the Comment, if any, does not have a trailing new line or comment characters such as "//", a starting "/*", or an ending "*/".

A field appearing in a struct may also define a reverse function, which is a FieldMapper that performs the opposite conversion of a FieldMapper applied to the field. It is not necessary that the result of applying a reverse function is itself reversible. Not all mappings are reversible, so this may be set to nil.

For example, if a FieldMapper applies a transformation with

Converter == "$dest.$ = $src.$ * 2"

Then the reverse function should apply a transformation with

Converter == "$dest.$ = $src.$ / 2"

When creating a reverse function, care should be taken to not overwrite a field's existing reverse function. This can be achieved by composing the two functions with the Compose function in the fieldmappers sub package, for example:

myNewField.Reverse = fieldmappers.Compose(newfunc, myOldField.Reverse))

(this is safe even when myOldField.Reverse is nil).

func (f *Field) AppendComments(comments ...string)

func (f *Field) AppendTags(tags ...string)

func (f Field) Copy() Field

func (f Field) GetCustomExpression(name string) *FieldExpression

func (f *Field) Rewrite(input Field)

func (f *Field) SetCustomExpression(expression FieldExpression)

type FieldExpression ¶

type FieldExpression struct {
	Type    *FieldExpressionType
	Pattern string // e.g. "$dest.$ = append([]$src.$.$type(nil), $src.$)"
}

FieldExpression is an instruction describing how to assign, compare, or inspect, or perform some other operation on a field or fields.

Most users will just call [Struct.Converter], Struct.Comparer, etc. and do not need to use this unless using Morph to make their own custom function generators.

A field expression's Type defines what the expression does e.g. compare, convert, etc.

An expression may apply to either a single field on one struct value, or on two matching fields on two struct values, depending on the Type.

Note one important limitation: expressions of the same Type overwrite each other and do not nest. Two field mappings are incompatible if they touch the same expressions on the same fields. When making multiple incompatible mappings, you must create intermediate temporary struct types.

A field expression's Pattern defines how a field expression of that Type is applied to a specific field or fields.

These are either boolean comparison expressions (like [Field.Comparer] and [Field.Orderer]) that return true or false, value assignment expressions (like [Field.Converter] and [Field.Copier]) which assign values to a destination value, or void inspection expressions that don't return anything (but may panic). Fields are inspected in the order they appear in a source struct.

In any expression, if the pattern is the special value "skip", then it means explicitly ignore that field for expressions of that type instead of applying the default pattern for that expression type.

A field expression's pattern may contain "$-token" replacements that are replaced with a computed string when generating the source code for a new function:

• "$a" and "$b" are replaced inside two-target boolean expressions with the name of two input struct value arguments.

• "$src" and "$dest" are replaced inside two-target value assignment expressions with the name of the input and output struct value arguments.

• "$self" is replaced inside a single-target expression with the name of the single target struct value argument.

• "$this" is replaced inside a single-target boolean or void expression with the qualified field name on the single input for the field currently being mapped.

• The tokens "$a", "$b", "$src", "$dest", and "$self" may be followed by a dot and another token specifying a named field (e.g. "$src.Foo"), which is then replaced with a qualified field name on the appropriate target (e.g. "myStruct.Foo").

• Alternatively, instead of a named field, the tokens "$a", "$b", "$src", "$dest", and "$self" may instead be followed by a dot and "$" when not followed by any Go identifier (e.g. "$src.$.foo" is okay, but "$src.$foo" is not), which is then replaced with the qualified field name on the appropriate target for the source field currently being mapped.

Additionally:

• Any token that would otherwise be replaced by any previous pattern may also be followed by a dot and "$type", in which case they are instead replaced with the type of the referenced struct value or field value.

• Any token that would otherwise be replaced by any previous pattern, including with the ".$type" suffix, may also be followed by a dot and "$title" or "$untitle", in which case the replacement has the first character forced into an uppercase or lowercase variant, respectively.

In cases where a $-token is ambiguous, use parentheses e.g. "$(foo)Bar". For example, to call a method on "$src", use "$(src).Method()", and to call a function that is a field, use "$(src.Method)()".

type FieldExpressionType ¶

type FieldExpressionType struct {
	// Targets specifies that this is an operation over this many input and/or
	// output struct values.
	//
	// Don't count any incidental input or output arguments e.g. database
	// handles or an error return value. These can be specified in a
	// function signature later.
	//
	// Allowed values are 1 and 2.
	Targets int

	// Name uniquely identifies the operation e.g. "Append". A [Field] can
	// only ever have one custom FieldExpression per given Name, and every
	// FieldExpression in a struct's list of fields that share this name must
	// have type fields that all point to the same FieldExpressionType.
	Name string

	// Default is a pattern applied if a pattern on a FieldExpression is the
	// empty string (indicating default behaviour).
	//
	// All "$"-tokens are replaced according to the rules specified by the
	// [FieldExpression] doc comment.
	//
	// An empty Default is treated as "skip".
	Default string

	// Returns specifies if the function is a boolean comparison expression,
	// value assignment expression, or a void inspection expression
	// (see [FieldExpression]).
	//
	// Allowed values are FieldExpressionTypeVoid, FieldExpressionTypeBool,
	// and FieldExpressionTypeValue.
	//
	// If the type is FieldExpressionTypeVoid, then Targets must be less than
	// 2.
	Type string

	// Comment is an optional comment set on a generated function e.g.
	// "$ converts [$src.$type] to [$dest.$type]". Leading "//" tokens are not
	// required, and the comment may contain linebreaks.
	//
	// The "$"-tokens "$a", "$b", "$src", "$dest", and "$self" appearing in
	// Comment are replaced according to the rules specified by the
	// [FieldExpression] doc comment.
	//
	// Additionally, the token "$", when not preceded by a dot, is (at a later
	// time) replaced by the name of the generated function when formatting a
	// function.
	Comment string

	// FieldComment is an optional comment generated above each expression for
	// each field e.g. "does $a.$ equal $b.$?". Leading "//" tokens are not
	// required, and the comment may contain linebreaks.
	//
	// All "$"-tokens are replaced according to the rules specified by the
	// [FieldExpression] doc comment.
	FieldComment string

	// Collect is a logical operator applied to all boolean results when
	// Returns is set to "bool". This must be set to a string representing
	// the Go boolean logical operator "&&" or "||". If set to "||", the
	// generated function returns true immediately on the first true value. If
	// set to "&&", the generated function returns false immediately on the
	// first false value.
	Collect string

	// Accessor returns the pattern of a FieldExpression of this type on a
	// given field, if one exists. If nil, calls [Field.GetCustomExpression]
	// with the FieldExpressionType.Name as an argument. It's likely that you
	// want to leave this as nil.
	Accessor func(f Field) string

	// Setter sets the field expression on a field of this FieldExpressionType.
	// If nil, calls [Field.SetCustomExpression] with the
	// FieldExpressionType.Name as an argument. It's likely that you want to
	// leave this as nil.
	Setter func(f *Field, pattern string)
}

FieldExpressionType describes some operation (e.g. copier, comparer, appender) on a struct value or on two struct values that can be implemented for a specific field by a FieldExpression. This controls how to generate the Go source code for a function that performs that operation.

Most users will just call [Struct.Converter], Struct.Comparer, etc. and do not need to use this unless using Morph to generate their own custom types of functions.

type FieldMapper ¶

type FieldMapper func(input Field, emit func(output Field))

FieldMapper maps fields on a struct to fields on another struct.

A FieldMapper is called once for each field defined on an input struct. Each invocation of the emit callback function generates a field on the output struct.

As a shortcut, a "$" appearing in an emitted Field's Name or Type is replaced with the name or type of the input Field, respectively.

It is permitted to call the emit function zero, one, or more than one time to produce zero, one, or more fields from a single input field.

For example, for an input:

Field{Name: "Foo", Type: "int64"},

Then calling emit with the argument:

emit(Field{Name: "$Slice", Type: "[]$"})

Would generate a Field with the name "FooSlice" and type `[]int64`.

package main

import (
	"fmt"

	"github.com/tawesoft/morph"
	"github.com/tawesoft/morph/fieldmappers"
	"github.com/tawesoft/morph/structmappers"
)

func must[X any](value X, err error) X {
	if err != nil {
		panic(err)
	}
	return value
}

func main() {
	source := `
package example

type Apple struct {
    Picked    time.Time
    LastEaten time.Time
    Weight    weight.Weight
}
`

	apple := must(morph.ParseStruct("test.go", source, ""))

	WeightToInt64 := func(input morph.Field, emit func(output morph.Field)) {
		if input.Type == "weight.Weight" {
			output := input       // copy
			output.Type = "int64" // rewrite the type
			emit(output)
		} else {
			emit(input)
		}
	}

	orange := apple.Map(
		structmappers.Rename("Orange"),
	).MapFields(
		fieldmappers.TimeToInt64,
		WeightToInt64,
	)
	fmt.Println(orange)

}

Output:

type Orange struct {
	Picked    int64 // time in seconds since Unix epoch
	LastEaten int64 // time in seconds since Unix epoch
	Weight    int64
}

func (mapper FieldMapper) StructMapper() StructMapper

type Function ¶

type Function struct {
	Signature FunctionSignature
	Body      string
}

Function contains a parsed function signature and the raw source code of its body, excluding the enclosing "{" and "}" braces.

func StructConverter(signature string, from Struct, to Struct) (Function, error)

func (fn Function) String() string

// Foo bars a baz.
func Foo(baz Baz) Bar {
    /* function body */
}

func (f Function) Wrap() WrappedFunction

type FunctionError ¶

type FunctionError struct {
	Message   string
	Signature FunctionSignature
	Reason    error
}

func (e FunctionError) Error() string

type FunctionSignature ¶

type FunctionSignature struct {
	Comment   string
	Name      string
	Type      []Argument
	Arguments []Argument
	Returns   []Argument
	Receiver  Argument
}

FunctionSignature represents a parsed function signature, including any arguments, return types, method receiver, generic type constraints, etc.

func ParseFirstFunctionSignature(filename string, src any) (result FunctionSignature, err error)

func ParseFunctionSignature(filename string, src any, name string) (result FunctionSignature, err error)

func ParseMethodSignature(filename string, src any, Type string, name string) (result FunctionSignature, err error)

func (fs FunctionSignature) Copy() FunctionSignature

func (fs FunctionSignature) Inputs() []Argument

func (fs FunctionSignature) String() string

func (fs FunctionSignature) Value() (string, error)

type FunctionWrapper ¶

type FunctionWrapper func(in WrappedFunction) (WrappedFunction, error)

type Struct ¶

type Struct struct {
	Comment    string
	Name       string
	TypeParams []Field
	Fields     []Field
	Reverse    StructMapper
}

Struct represents a Go struct - it's type name, type constraints (if using generics), doc comment, and fields.

If the struct has been renamed, From is its previous name. Otherwise, it is the empty string.

func ParseStruct(filename string, src any, name string) (result Struct, err error)

package main

import (
	"fmt"

	"github.com/tawesoft/morph"
)

func must[X any](value X, err error) X {
	if err != nil {
		panic(err)
	}
	return value
}

func main() {
	animal := must(morph.ParseStruct("examples_doc_test.go", nil, "Animal"))
	fmt.Println(animal)

}

Output:

type Animal struct {
	Name string
	Born time.Time
}

package main

import (
	"fmt"

	"github.com/tawesoft/morph"
)

func must[X any](value X, err error) X {
	if err != nil {
		panic(err)
	}
	return value
}

func main() {
	source := `
package example

type Apple struct {
    Picked    time.Time
    LastEaten time.Time
    Weight    weight.Weight
    Price     price.Price
}
`

	apple := must(morph.ParseStruct("test.go", source, "Apple"))
	fmt.Println(apple)

}

Output:

type Apple struct {
	Picked    time.Time
	LastEaten time.Time
	Weight    weight.Weight
	Price     price.Price
}

func (s Struct) Comparer(signature string) (Function, error)

func (s Struct) Copier(signature string) (Function, error)

func (s Struct) Copy() Struct

func (s Struct) CustomBinaryFunction(operation string, signature string, other Struct) (Function, error)

func (s Struct) CustomUnaryFunction(operation string, signature string) (Function, error)

func (s Struct) Map(mappers ...StructMapper) Struct

func (s Struct) MapFields(mappers ...FieldMapper) Struct

func (s Struct) Orderer(signature string) (Function, error)

func (s Struct) Signature() string

func (s Struct) String() string

// Foo is a thing that bars.
type Foo struct {
    Field Type `tag:"value"` // Comment
}

func (s Struct) Truther(signature string) (Function, error)

func (s Struct) Zeroer(signature string) (Function, error)

type StructMapper ¶

type StructMapper func(in Struct) Struct

StructMapper maps a Struct to another Struct.

type Variable ¶

type Variable struct {
	Name  string
	Type  string
	Value string
}

Variable represents a named and typed variable with a value.

type WrappedFunction ¶

type WrappedFunction struct {
	Signature FunctionSignature
	Inputs    ArgRewriter // Rewritten inputs to wrapped function
	Outputs   ArgRewriter // Rewritten outputs from wrapped function
	Wraps     *WrappedFunction
}

func (w WrappedFunction) Format() (string, error)

func (w WrappedFunction) Function() (Function, error)

func (w WrappedFunction) String() string

func (f WrappedFunction) Wrap(wrappers ...FunctionWrapper) (WrappedFunction, error)