textra

README

Textra

Textra is a zero-dependency, simple and fast struct tags parser library. It also has json tags for all structs, in case of JSON output.

Initially I built it for another private project, but decided to try to open source it, since it could be useful for someone. Because of that, it has some features that feel redundant, like having field type as a part of returned data

Installation

go get github.com/ravsii/textra

Examples

Basic usage:

type Tester struct {
 NoTags   bool
 WithTag  string `json:"with_tag,omitempty"`
 WithTags string `json:"with_tags"          sql:"with_tag"`
 SqlOnly  string `sql:"sql_only"`
}

func main() {
 basic := textra.Extract((*Tester)(nil))
 for _, field := range basic {
  fmt.Println(field)
 }
}

NoTags(bool):[]
WithTag(string):[json:"with_tag,omitempty"]
WithTags(string):[json:"with_tags" sql:"with_tag"]
SqlOnly(string):[sql:"sql_only"]

You can look at return types at pkg.go.dev, but basically it returns a slice of fields with its types (as strings) and a slice of Tags for each field.

Now let's apply some functions:

 removed := basic.RemoveEmpty()
 for _, field := range removed {
  fmt.Println(field)
 }

SqlOnly(*[]string):[pg:"sql_only" sql:"sql_only"]
WithTag(string):[json:"with_tag,omitempty"]
WithTags(*string):[json:"with_tags" sql:"with_tag"]

What if we care only about SQL tags?

 onlySQL := removed.OnlyTag("sql")
 for _, field := range onlySQL {
  fmt.Println(field)
 }

SqlOnly(*[]string):sql:"sql_only"
WithTags(*string):sql:"with_tag"

Only() is a bit special as it returns a Field of a different type, with Tag rather than Tags(=[]Tag)

API is built like standard's time package, where chaining function will create new values, instead of modifying them.

Although it may be redundant, it also parses types a their string representation (for easier comparison or output, if you need it)

type Types struct {
 intType        int
 intPType       *int
 byteType       byte
 bytePType      *byte
 byteArrType    []byte
 byteArrPType   []*byte
 bytePArrPType  *[]*byte
 runeType       rune
 runePType      *rune
 stringType     string
 stringPType    *string
 booleanType    bool
 booleanPType   *bool
 mapType        map[string]string
 mapPType       map[*string]*string
 mapPImportType map[*string]*time.Time
 chanType       chan int
 funcType       func() error
 funcParamsType func(arg1 int, arg2 string, arg3 map[*string]*time.Time) (int, error)
 importType     time.Time
 pointerType    *string
}

func main() {
 fields := textra.Extract((*Types)(nil))
 for _, field := range fields {
  fmt.Println(field.Name, field.Type)
 }
}

intType int
intPType *int
byteType uint8
bytePType *uint8
byteArrType []uint8
byteArrPType []*uint8
bytePArrPType *[]*uint8
runeType int32
runePType *int32
stringType string
stringPType *string
booleanType bool
booleanPType *bool
mapType map[string]string
mapPType map[*string]*string
mapPImportType map[*string]*time.Time
chanType chan
funcType func() error
funcParamsType func(int, string, map[*string]*time.Time) int, error
importType time.Time
pointerType *string

TODO

• Examples for go.dev
• ...?

Documentation

Index

• type Field
  • func (f Field) String() string
• type FieldTag
  • func (f FieldTag) String() string
• type Struct
  • func Extract(src interface{}) Struct
  • func (s Struct) ByTagName(tag string) Struct
  • func (s Struct) ByTagNameAll(tags ...string) Struct
  • func (s Struct) ByTagNameAny(tags ...string) Struct
  • func (s Struct) Field(name string) (Field, bool)
  • func (s Struct) FilterFunc(fn func(Field) bool) Struct
  • func (s Struct) OnlyTag(name string) []FieldTag
  • func (s Struct) RemoveEmpty() Struct
  • func (s Struct) RemoveFields(fields ...string) Struct
  • func (s Struct) String() string
• type Tag
  • func (t Tag) Ignored() bool
  • func (t Tag) OmitEmpty() bool
  • func (t Tag) String() string
• type Tags
  • func (t Tags) ByName(name string) (Tag, bool)
  • func (t Tags) String() string

Types

type Field

type Field struct {
	Name string `json:"name"`
	// Type is a type of a field, like "time.Time" or "*string"
	Type string `json:"type"`
	Tags Tags   `json:"tags,omitempty"`
}

Field represents one struct field.

func (Field) String

func (f Field) String() string

type FieldTag

type FieldTag struct {
	Name string `json:"name"`
	// Type is a type of a field, like "time.Time" or "*string"
	Type string `json:"type"`
	Tag  Tag    `json:"tag,omitempty"`
}

FieldTag is like Field but it has only one tag. It's used as an output of some functions (like Only()).

func (FieldTag) String

func (f FieldTag) String() string

type Struct

type Struct []Field

Struct represents a single struct.

func Extract

func Extract(src interface{}) Struct

Extract accept a struct (or a pointer to a struct) and returns a map of fields and their tags. If src is not a struct or a pointer to a struct, nil is returned.

func (Struct) ByTagName

func (s Struct) ByTagName(tag string) Struct

ByTagName returns a slice of fields which contain given tag.

func (Struct) ByTagNameAll

func (s Struct) ByTagNameAll(tags ...string) Struct

ByTagNameAll returns a slice of fields which contain all of the tags.

func (Struct) ByTagNameAny

func (s Struct) ByTagNameAny(tags ...string) Struct

ByTagNameAny returns a slice of fields which contain at least one tag.

func (Struct) Field

func (s Struct) Field(name string) (Field, bool)

Field returns a field by name.

func (Struct) FilterFunc

func (s Struct) FilterFunc(fn func(Field) bool) Struct

FilterFunc returns a slice of fields, filtered by fn(field) == true.

func (Struct) OnlyTag

func (s Struct) OnlyTag(name string) []FieldTag

OnlyTag returns a slice of fields that match the given tag name. FieldTag is returned (instead of Struct like other filters) because the expected output is a slice of fields with only one tag.

func (Struct) RemoveEmpty

func (s Struct) RemoveEmpty() Struct

RemoveEmpty removes any field from a Struct that has an empty "Tags" field.

func (Struct) RemoveFields

func (s Struct) RemoveFields(fields ...string) Struct

RemoveFields removes fields by their names from a Struct and returns a new Struct.

func (Struct) String

func (s Struct) String() string

type Tag

type Tag struct {
	// Tag holds tag's name.
	Tag   string `json:"tag"`
	Value string `json:"value"`
	// Optional holds the rest of the value which comes after the comma.
	// Example: In a tag like
	// 	`json:"id,pk,omitempty"`
	// Optional will contain
	// 	["pk", "omitempty"]
	Optional []string `json:"optional,omitempty"`
}

Tag represents a single struct tag, like

`json:"value"`.

func (Tag) Ignored

func (t Tag) Ignored() bool

Ignored is a shortcut for t.Value == "-".

func (Tag) OmitEmpty

func (t Tag) OmitEmpty() bool

OmitEmpty returns true if t.Optional contains "omitempty".

func (Tag) String

func (t Tag) String() string

type Tags

type Tags []Tag

Tags is a slice of tags.

func (Tags) ByName

func (t Tags) ByName(name string) (Tag, bool)

ByName returns a tag by its name, if it exists.

func (Tags) String

func (t Tags) String() string