structtags

README

StructTags

structtags provides a way of parsing struct tag Go fields.

The goal is to provide some ways to parse struct tags:

• Some projects need a full parsing (key, values)
• Some others only need the key and the raw value.
• Other projects need to escape the comma.
• Etc.

Why this library?

fatih/structtag is a great library, but it's not extensible, it was build around JSON tags, and it was designed to modify tags.

For example, the Tag struct inside fatih/structtag that represents a tag is:

type Tag struct {
    // Key is the tag key, such as json, xml, etc..
    // i.e: `json:"foo,omitempty". Here key is: "json"
    Key string
    
    // Name is a part of the value
    // i.e: `json:"foo,omitempty". Here name is: "foo"
    Name string
    
    // Options is a part of the value. It contains a slice of tag options i.e:
    // `json:"foo,omitempty". Here options is: ["omitempty"]
    Options []string
}

Name and Options are related to JSON tags (and other marshaling/unmarshalling libraries).

But the first element in a struct tag value is not necessarily a name.

Example:

type Foo struct {
  Field1 float64  `minimum:"10.5" example:"20.6" required:"true"`
  Field2 string   `jsonschema:"required"`
  Field3 string   `description:"This is a description"`
}

Also, most projects don't need to modify the struct tags, but only to read them.

There are some limitations with fatih/structtag when there is comma inside the value.

Example:

type Foo struct {
  Field1 string   `regexp:"[a-z\\,.]"`
}

ldez/structtags provides straightforward ways to parse and read struct tags, and a compatibility layer with fatih/structtag if you need it.

Instead of rewriting the wheel for each project, I also provided a package with the plumbing:

• parser.Tag(): extracted from reflect.StructTag for the base parsing.
• parser.Value(): to parse the value (support optional comma escaping).

Usage

• structtags.ParseToMap(tag):
  • Parses a struct tag to a map[string]string.
• structtags.ParseToMapMultikeys(tag):
  • Parses a struct tag to a map[string][]string.
  • For non-conventional tags where the key is repeated.
• structtags.ParseToMapValues(tag, escapeComma):
  • Parses a struct tag to a map[string][]string.
  • The value is split on a comma.
  • Option: comma escaped by backslash.
• structtags.ParseToSlice(tag):
  • Parses a struct tag to a slice of type Tag struct { Key, Value string }.
• structtags.ParseToSliceValues(tag, escapeComma):
  • Parses a struct tag to a slice of type Tag struct { Key string, Value []string }.
  • The value is split on a comma.
  • Option: comma escaped by backslash.
• structtags.ParseToFatih(tag, escapeComma):
  • Parses a struct tag to a *structtag.Tags.
  • The value is split on a comma.
  • Option: comma escaped by backslash.

The parser package provides the tooling to parse a struct tag and its associated value.

To implement a custom parser, you can implement the parser.Filler interface.

Plan

This is the first version of the module, and I want to extend it based on feedback so that the API can evolve and break.

Notes

The struct tag specifications say that struct tags can be any string.

The key/value syntax, the comma separator, and the space separator are conventions based on reflect.StructTag and json implementation.

reflect.StructTag behaves like the struct tags are map[string]string, but with one difference: The first key always wins if there are multiple keys with the same name.

We can say that the reflect.StructTag doesn't support multiple keys with the same name. But some rare projects/libraries use multiple keys with the same name.

Also, the specification doesn't talk about comma escaping inside the value.

Maybe the specification should clarify those points.

References

• https://go.dev/ref/spec#Struct_types
• https://go.dev/ref/spec#string_lit
• https://github.com/golang/go/blob/411c250d64304033181c46413a6e9381e8fe9b82/src/reflect/type.go#L1030-L1108
• https://github.com/golang/tools/blob/master/go/analysis/passes/structtag/structtag.go
• https://github.com/fatih/structtag/blob/master/tags.go

Documentation

Index

• func ParseToFatih(tag string, escapeComma bool) (*structtag.Tags, error)
• func ParseToMap(tag string) (map[string]string, error)
• func ParseToMapMultikeys(tag string) (map[string][]string, error)
• func ParseToMapValues(tag string, escapeComma bool) (map[string][]string, error)
• func ParseToSlice(tag string) ([]sliceraw.Tag, error)
• func ParseToSliceValues(tag string, escapeComma bool) ([]slicevalues.Tag, error)

Functions

func ParseToFatih

func ParseToFatih(tag string, escapeComma bool) (*structtag.Tags, error)

ParseToFatih parses a struct tag to a *structtag.Tags. The value is split on comma.

func ParseToMap

func ParseToMap(tag string) (map[string]string, error)

ParseToMap parses a struct tag to a `map[string]string`.

func ParseToMapMultikeys

func ParseToMapMultikeys(tag string) (map[string][]string, error)

ParseToMapMultikeys parses a struct tag to a `map[string][]string`. For non-conventional tags where the key is repeated.

func ParseToMapValues

func ParseToMapValues(tag string, escapeComma bool) (map[string][]string, error)

ParseToMapValues parses a struct tag to a `map[string][]string`. The value is split on comma.

func ParseToSlice

func ParseToSlice(tag string) ([]sliceraw.Tag, error)

ParseToSlice parses a struct tag to a slice of parser.Tag.

func ParseToSliceValues

func ParseToSliceValues(tag string, escapeComma bool) ([]slicevalues.Tag, error)

ParseToSliceValues parses a struct tag to a slice of slicevalues.Tag. The value is split on comma.