mold

README

Package mold

Package mold is a general library to help modify or set data within data structures and other objects.

How can this help me you ask, please see the examples here

Requirements

• Go 1.18+

Installation

Use go get.

go get -u github.com/go-playground/mold/v4

Examples

Example	Description
simple	A basic example with custom function.
full	A more real life example combining the usage of multiple packages.

Modifiers

These functions modify the data in-place.

Name	Description
camel	Camel Cases the data.
default	Sets the provided default value only if the data is equal to it's default datatype value.
empty	Sets the field equal to the datatype default value. e.g. 0 for int.
lcase	lowercases the data.
ltrim	Trims spaces from the left of the data provided in the params.
rtrim	Trims spaces from the right of the data provided in the params.
set	Set the provided value.
slug	Converts the field to a slug
snake	Snake Cases the data.
strip_alpha	Strips all ascii characters from the data.
strip_alpha_unicode	Strips all unicode characters from the data.
strip_num	Strips all ascii numeric characters from the data.
strip_num_unicode	Strips all unicode numeric characters from the data.
strip_punctuation	Strips all ascii punctuation from the data.
title	Title Cases the data.
tprefix	Trims a prefix from the value using the provided param value.
trim	Trims space from the data.
tsuffix	Trims a suffix from the value using the provided param value.
ucase	Uppercases the data.
ucfirst	Upper cases the first character of the data.

Special Notes: default and set modifiers are special in that they can be used to set the value of a field or underlying type information or attributes and both use the same underlying function to set the data.

Setting a Param will have the following special effects on data types where it's not just the value being set:

• Chan - param used to set the buffer size, default = 0.
• Slice - param used to set the capacity, default = 0.
• Map - param used to set the size, default = 0.
• time.Time - param used to set the time format OR value, default = time.Now(), utc = time.Now().UTC(), other tries to parse using RFC3339Nano and set a time value.

Scrubbers

These functions obfuscate the specified types within the data for pii purposes.

Name	Description
emails	Scrubs multiple emails from data.
email	Scrubs the data from and specifies the sha name of the same name.
text	Scrubs the data from and specifies the sha name of the same name.
name	Scrubs the data from and specifies the sha name of the same name.
fname	Scrubs the data from and specifies the sha name of the same name.
lname	Scrubs the data from and specifies the sha name of the same name.

Special Information

• To use a comma(,) within your params replace use it's hex representation instead '0x2C' which will be replaced while caching.

Contributing

I am definitely interested in the communities help in adding more scrubbers and modifiers. Please send a PR with tests, and preferably no extra dependencies, at lease until a solid base has been built.

Complimentary Software

Here is a list of software that compliments using this library post decoding.

• validator - Go Struct and Field validation, including Cross Field, Cross Struct, Map, Slice and Array diving.
• form - Decodes url.Values into Go value(s) and Encodes Go value(s) into url.Values. Dual Array and Full map support.

License

Distributed under MIT License, please see license file in code for more details.

Documentation

Index

• Variables
• func HasValue(field reflect.Value) bool
• type ErrInvalidTag
  • func (e *ErrInvalidTag) Error() string
• type ErrInvalidTransformValue
  • func (e *ErrInvalidTransformValue) Error() string
• type ErrInvalidTransformation
  • func (e *ErrInvalidTransformation) Error() string
• type ErrUndefinedTag
  • func (e *ErrUndefinedTag) Error() string
• type FieldLevel
• type Func
• type InterceptorFunc
• type StructLevel
• type StructLevelFunc
• type Transform
• type Transformer
  • func New() *Transformer
  • func (t *Transformer) Field(ctx context.Context, v interface{}, tags string) (err error)
  • func (t *Transformer) Register(tag string, fn Func)
  • func (t *Transformer) RegisterAlias(alias, tags string)
  • func (t *Transformer) RegisterInterceptor(fn InterceptorFunc, types ...interface{})
  • func (t *Transformer) RegisterStructLevel(fn StructLevelFunc, types ...interface{})
  • func (t *Transformer) SetTagName(tagName string)
  • func (t *Transformer) Struct(ctx context.Context, v interface{}) error

Variables

var (
	// ErrInvalidDive describes an invalid dive tag configuration
	ErrInvalidDive = errors.New("invalid dive tag configuration")

	// ErrUndefinedKeysTag describes an undefined keys tag when and endkeys tag defined
	ErrUndefinedKeysTag = errors.New("'" + endKeysTag + "' tag encountered without a corresponding '" + keysTag + "' tag")

	// ErrInvalidKeysTag describes a misuse of the keys tag
	ErrInvalidKeysTag = errors.New("'" + keysTag + "' tag must be immediately preceeded by the '" + diveTag + "' tag")
)

Functions

func HasValue

func HasValue(field reflect.Value) bool

HasValue determines if a reflect.Value is it's default value

Types

type ErrInvalidTag

type ErrInvalidTag struct {
	// contains filtered or unexported fields
}

ErrInvalidTag defines a bad value for a tag being used

func (*ErrInvalidTag) Error

func (e *ErrInvalidTag) Error() string

Error returns the InvalidTag error text

type ErrInvalidTransformValue

type ErrInvalidTransformValue struct {
	// contains filtered or unexported fields
}

An ErrInvalidTransformValue describes an invalid argument passed to Struct or Var. (The argument passed must be a non-nil pointer.)

func (*ErrInvalidTransformValue) Error

func (e *ErrInvalidTransformValue) Error() string

type ErrInvalidTransformation

type ErrInvalidTransformation struct {
	// contains filtered or unexported fields
}

ErrInvalidTransformation describes an invalid argument passed to `Struct` or `Field`

func (*ErrInvalidTransformation) Error

func (e *ErrInvalidTransformation) Error() string

Error returns ErrInvalidTransformation message

type ErrUndefinedTag

type ErrUndefinedTag struct {
	// contains filtered or unexported fields
}

ErrUndefinedTag defines a tag that does not exist

func (*ErrUndefinedTag) Error

func (e *ErrUndefinedTag) Error() string

Error returns the UndefinedTag error text

type FieldLevel

type FieldLevel interface {
	// Transformer represents a subset of the current *Transformer that is executing the current transformation.
	Transformer() Transform

	//
	// Parent returns the top level parent of the current value return by Field()
	//
	// This is used primarily for having the ability to nil out pointer type values.
	//
	// NOTE: that is there are several layers of abstractions eg. interface{} of interface{} of interface{} this
	//       function returns the first interface{}
	//
	Parent() reflect.Value

	// Field returns the current field value being modified.
	Field() reflect.Value

	// Param returns the param associated wth the given function modifier.
	Param() string
}

FieldLevel represents the interface for field level modifier function

type Func

type Func func(ctx context.Context, fl FieldLevel) error

Func defines a transform function for use.

type InterceptorFunc

type InterceptorFunc func(current reflect.Value) (inner reflect.Value)

InterceptorFunc is a way to intercept custom types to redirect the functions to be applied to an inner typ/value. eg. sql.NullString, the manipulation should be done on the inner string.

type StructLevel

type StructLevel interface {
	// Transformer represents a subset of the current *Transformer that is executing the current transformation.
	Transformer() Transform

	//
	// Parent returns the top level parent of the current value return by Struct().
	//
	// This is used primarily for having the ability to nil out pointer type values.
	//
	// NOTE: that is there are several layers of abstractions eg. interface{} of interface{} of interface{} this
	//       function returns the first interface{}.
	//
	Parent() reflect.Value

	// Struct returns the value of the current struct being modified.
	Struct() reflect.Value
}

StructLevel represents the interface for struct level modifier function

type StructLevelFunc

type StructLevelFunc func(ctx context.Context, sl StructLevel) error

StructLevelFunc accepts all values needed for struct level manipulation.

Why does this exist? For structs for which you may not have access or rights to add tags too, from other packages your using.

type Transform

type Transform interface {
	Struct(ctx context.Context, v interface{}) error
	Field(ctx context.Context, v interface{}, tags string) error
}

Transform represents a subset of the current *Transformer that is executing the current transformation.

type Transformer

type Transformer struct {
	// contains filtered or unexported fields
}

Transformer is the base controlling object which contains all necessary information

func New

func New() *Transformer

New creates a new Transform object with default tag name of 'mold'

func (*Transformer) Field

func (t *Transformer) Field(ctx context.Context, v interface{}, tags string) (err error)

Field applies the provided transformations against the variable

func (*Transformer) Register

func (t *Transformer) Register(tag string, fn Func)

Register adds a transformation with the given tag

NOTES: - if the key already exists, the previous transformation function will be replaced. - this method is not thread-safe it is intended that these all be registered before hand

func (*Transformer) RegisterAlias

func (t *Transformer) RegisterAlias(alias, tags string)

RegisterAlias registers a mapping of a single transform tag that defines a common or complex set of transformations to simplify adding transforms to structs.

NOTE: this function is not thread-safe it is intended that these all be registered before hand

func (*Transformer) RegisterInterceptor

func (t *Transformer) RegisterInterceptor(fn InterceptorFunc, types ...interface{})

RegisterInterceptor registers a new interceptor functions agains one or more types. This InterceptorFunc allows one to intercept the incoming to to redirect the application of modifications to an inner type/value.

eg. sql.NullString

func (*Transformer) RegisterStructLevel

func (t *Transformer) RegisterStructLevel(fn StructLevelFunc, types ...interface{})

RegisterStructLevel registers a StructLevelFunc against a number of types. Why does this exist? For structs for which you may not have access or rights to add tags too, from other packages your using.

NOTES: - this method is not thread-safe it is intended that these all be registered prior to any validation

func (*Transformer) SetTagName

func (t *Transformer) SetTagName(tagName string)

SetTagName sets the given tag name to be used. Default is "trans"

func (*Transformer) Struct

func (t *Transformer) Struct(ctx context.Context, v interface{}) error

Struct applies transformations against the provided struct