{"id":15678154,"url":"https://github.com/chanced/labeler","last_synced_at":"2025-12-14T20:58:47.339Z","repository":{"id":57546959,"uuid":"298018467","full_name":"chanced/labeler","owner":"chanced","description":"Go struct tags for marshaling and unmarshaling map[string]string","archived":false,"fork":false,"pushed_at":"2020-11-15T22:00:17.000Z","size":339,"stargazers_count":12,"open_issues_count":4,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-31T05:26:10.772Z","etag":null,"topics":["go","golang"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chanced.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-09-23T15:45:27.000Z","updated_at":"2021-09-24T17:15:33.000Z","dependencies_parsed_at":"2022-09-05T12:30:31.125Z","dependency_job_id":null,"html_url":"https://github.com/chanced/labeler","commit_stats":null,"previous_names":["chanced/labels"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chanced%2Flabeler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chanced%2Flabeler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chanced%2Flabeler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chanced%2Flabeler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chanced","download_url":"https://codeload.github.com/chanced/labeler/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252800503,"owners_count":21806174,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["go","golang"],"created_at":"2024-10-03T16:17:46.820Z","updated_at":"2025-12-14T20:58:47.244Z","avatar_url":"https://github.com/chanced.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# labeler 🏷 [![Go Report Card](https://goreportcard.com/badge/github.com/chanced/labeler)](https://goreportcard.com/report/github.com/chanced/labeler)\n\nA Go package for marshaling and unmarshaling `map[string]string` with struct tags.\n\nRequires go version 1.13+ for `errors.As` and `errors.Is`\n\n```bash\ngo get github.com/chanced/labeler\n```\n\n```go\npackage main\nimport (\n \"fmt\"\n \"github.com/chanced/labeler\"\n)\n\n// The simplest implementation uses a container for labels,\n// denoted with a tag marked as `label:\"*\"`\ntype Struct struct {\n\tLabels map[string]string `label:\"*\"`\n\tField string `label:\"field\"`\n}\n\nfunc main() {\n labels := map[string]string{\"field\": \"val\"}\n v := Struct{}\n labeler.Unmarshal(labels, \u0026v)\n result, err := labeler.Marshal(\u0026v)\n\n _ = err\n fmt.Println(\"v.Field: \", v.Field)\n for key, value := range labels {\n fmt.Printf(\"labels[%s]: %s result[%s]: %s\\n\", key, labels[key], key, result[key])\n }\n}\n```\n\n- [Motivation](#motivation)\n- [Value: `interface{}` defined](#value-interface-defined)\n - [Fields](#fields)\n - [Labels](#labels)\n- [Unmarshal Input](#input-unmarshal)\n- [Labeler Instance](#labeler-instance)\n- [Examples](#examples)\n - [Basic with accessor / mutator for labels](#basic-example-with-accessor-mutator-for-labels)\n - [With an enum](#example-with-an-enum)\n - [Using a container tag](#example-using-a-container-tag)\n - [Using multiple tags](#example-using-multiple-tags)\n- [Options](#options)\n - [Settings](#settings)\n - [Tokens](#tokens)\n- [Notes](#notes)\n - [Prior Art](#prior-art)\n- [License (MIT)](#license)\n\n## Motivation\n\nI am developing a project on Google Cloud Platform. Resources on GCP can have\nlabels, which I use in a number of ways to classify and organize with. The gRPC\nclient responses come with a `GetLabels()map[string]string` method. This project\nwas built as a means to interpret `map[string]string` into a well-defined `struct`.\n\nThe package has worked really well for config values coming in from Environ \u0026 elsewhere.\n\n## Value: `interface{}` defined\n\nBoth Marshal and Unmarshal accept `v interface{}`, the value to marshal from or unmarshal\ninto. `v` must be pointer to a `struct` or a `type` that implements\n`labeler.MarshalWithOpts`, `labeler.Marshal`, `labeler.UnmarshalWithOpts`, or\n`labeler.Unmarshal` respectively.\n\n### Fields\n\nlabeler is fairly flexible when it comes to what all you can tag. It supports the following types:\n\n| Interface / Type | Signature | Usage |\n| :---------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- | --------: |\n| `labeler.MarshalerWithOpts` | `MarshalLabels(o labeler.Options) map[string]string` | Marshal |\n| `labeler.Marshaler` | `MarshalLabels() map[string]string` | Marshal |\n| `fmt.Stringer` | `String() string` | Marshal |\n| `encoding.TextMarshaler` | `MarshalText() (text []byte, err error)` | Marshal |\n| `labeler.UnmarshalerWithOpts` | `UnmarshalLabels(v map[string]string, opts Options) error` | Unmarshal |\n| `labeler.Unmarshaler` | `UnmarshalLabels(l map[string]string) error` | Unmarshal |\n| `labeler.Stringee` | `FromString(s string) error` | Unmarshal |\n| `encoding.TextUnmarshaler` | `UnmarshalText(text []byte) error` | Unmarshal |\n| `struct` | can either implement any of the above interfaces or have fields with tags. Supports `n` level of nesting | Both |\n| basic types | `string`, `bool`, `int`, `int64`, `int32`, `int16`, `int8`, `float64`, `float32`, `uint`, `uint64`, `uint32`, `uint16`, `uint8`, `complex128`, `complex64`, | Both |\n| time | `time.Time`, `time.Duration` | Both |\n| pointer | pointer to any of the above | Both |\n| slices \u0026 arrays | slices / arrays composed of any type above | Both |\n\n### Labels\n\nWhen unmarshaling, labeler needs a way to persist labels, regardless of whether or not they\nhave been assigned to tagged fields. By default, labeler will retain all labels unless\n`Options.KeepLabels` is set to `false` (See [Options](#options)). This is to ensure\ndata integrity for labels that have not been unmarshaled into fields.\n\nYour available choices for `v` are:\n\n| Interface / Type | Signature |\n| :------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `labeler.UnmarshalerWithOpts` | `UnmarshalLabels(v map[string]string, opts Options) error` |\n| `labeler.Unmarshaler` | `UnmarshalLabels(l map[string]string) error` |\n| `labeler.Labelee` | `SetLabels(labels map[string]string)` |\n| `labeler.StrictLabelee` | `SetLabels(labels map[string]string) error` |\n| `labeler.GenericLabelee` | `SetLabels(labels map[string]string, tag string) error` |\n| `struct` with a container field | A `struct` with a field marked as being the container using `Options.ContainerToken` on any level of `v` or a field with the name matching `Options.ContainerField` that is any `type` above or an accessible `map[string]string`. (See [Options](#options)). |\n\nWhile marshaling, labeler will prioritize field values over those stored in your label\ncontainer. This means that values in the `map[string]string` will be overridden\nif there is a key with a matching tag.\n\nlabeler ignores the case of keys by default, but this is configurable. (See [Options](#options))\n\n## Input (Unmarshal)\n\nFor `Unmarshal`, you also need to pass `input interface{}` which provides a means of\naccessing the labels `map[string]string`.\n\n`input` must satisfy one of the following:\n\n| Interface / Type | Signature | Example |\n| :--------------------------- | :---------------------------------------- | ---------------------------------------------------------- |\n| `labeler.Labeled` | `GetLabels() map[string]string` | [example](#basic-example-with-accessor-mutator-for-labels) |\n| `labeler.GenericallyLabeled` | `GetLabels(tag string) map[string]string` | [example](#example-using-multiple-tags) |\n| `map[string]string` | Any type derived from `map[string]string` | [example](#example-using-a-container-tag) |\n\n## Labeler Instance\n\nIf you need to change any Option, consider creating an instance of labeler as there will be a bit\nof extra pre-processing for each call to `Marshal` and `Unmarshal` otherwise.\n\n```go\nenviron := labeler.NewLabeler(OptTag(\"env\"))\n// then use environ.Unmarshal(in, v) and environ.Marshal(v)\n_ = environ\n```\n\n## Examples\n\n### Basic example with accessor / mutator for labels\n\n```go\npackage main\n\nimport (\n \"fmt\"\n\n \"github.com/chanced/labeler\"\n)\n\ntype ExampleInput struct {\n\tLabels map[string]string\n}\n\nfunc (e ExampleInput) GetLabels() map[string]string {\n\treturn e.Labels\n}\n\ntype NestedExample struct {\n\tField string `label:\"nested_field\"`\n}\n\ntype Example struct {\n\tName string `label:\"name\"`\n\tDuration time.Duration `label:\"duration\"`\n\tTime time.Time `label:\"time, format: 01/02/2006 03:04PM\"`\n\tDedupe string `label:\"dedupe, discard\"`\n\tCaSe string `label:\"CaSe, casesensitive\"`\n\tFloatWithFormat float64 `label:\"FloatWithFormat, format:b\"`\n\tFloat64 float64 `label:\"float64\"`\n\tFloat32 float32 `label:\"float32\"`\n\tInt int `label:\"int\"`\n\tInt64 int64 `label:\"int64\"`\n\tInt32 int32 `label:\"int32\"`\n\tInt16 int16 `label:\"int16\"`\n\tInt8 int8 `label:\"int8\"`\n\tBool bool `label:\"bool\"`\n\tUint uint `label:\"uint\"`\n\tUint64 uint64 `label:\"uint64\"`\n\tUint32 uint32 `label:\"uint32\"`\n\tUint16 uint16 `label:\"uint16\"`\n\tUint8 uint8 `label:\"uint8\"`\n\tStrSlice []string `label:\"str_slice\"`\n\tIntArray [8]int `label:\"int_array\"`\n\tNested NestedExample\n\tLabels map[string]string // SetLabels is used instead of the container\n}\nfunc (e *Example) SetLabels(l map[string]string) {\n\te.Labels = l\n}\nfunc (e *Example) GetLabels() map[string]string {\n\treturn e.Labels\n}\n\nfunc main() {\n\tlabels := map[string]string{\n\t\t\"name\": \"Bart\",\n\t\t\"imp\": \"important field\",\n\t\t\"enum\": \"ValueB\",\n\t\t\"int\": \"123456789\",\n\t\t\"int64\": \"1234567890\",\n\t\t\"int32\": \"12345\",\n\t\t\"int16\": \"123\",\n\t\t\"int8\": \"1\",\n\t\t\"bool\": \"true\",\n\t\t\"duration\": \"1s\",\n\t\t\"float64\": \"1.1234567890\",\n\t\t\"float32\": \"1.123\",\n\t\t\"time\": \"09/26/2020 10:10PM\",\n\t\t\"uint\": \"1234\",\n\t\t\"uint64\": \"1234567890\",\n\t\t\"uint32\": \"1234567\",\n\t\t\"uint16\": \"123\",\n\t\t\"uint8\": \"1\",\n\t\t\"FloatWithFormat\": \"123.234823484\",\n\t\t\"dedupe\": \"Will be removed from the Labels after field value is set\",\n\t\t\"case\": \"value should not be set due to not matching case\",\n\t\t\"nested_field\": \"nested value\",\n\t\t\"int_array\": \"0,1,2,3,4,5,6,7\"\n\t\t\"str_slice\": \"red,blue,green\"\n\t}\n\n\tinput := ExampleInput {\n\t\tLabels: labels,\n\t}\n v := \u0026Example{}\n\n err := labeler.Unmarshal(input, v)\n\n if err != nil {\n var pErr *labeler.ParsingError\n select {\n case errors.As(err, \u0026pErr):\n for _, fieldErr := range pErr.Errors {\n // fieldErr has the field's Name (string) and Tag (labeler.Tag)\n // as well as Err, the underlying Error which unwraps\n }\n case errors.Is(err, ErrInvalidInput):\n // bad input\n }\n }\n\n l, err := labeler.Unmarshal(v)\n\n if err != nil {\n //handle err\n }\n\n fmt.Println(l) // map[string]string\n}\n```\n\n### Example using a container tag\n\nIf you don't want to use accessors and mutators on your input and value, you can opt instead for a container tag that is of `map[string]string` or implements the appropriate `interface` to retrieve and set labels. You can also pass in a `map[string]string` directly as your input for Unmarshal.\n\nThe container token is configurable with the `ContainerToken` option. See [Options](#options) for more info.\n\n```go\npackage main\n\nimport (\n \"fmt\"\n \"github.com/chanced/labeler\"\n)\n\ntype Example2 struct {\n\tName string `label:\"name\"`\n\tDefaulted string `label:\"defaulted, default: my default value\"` // spaces are trimmed\n\tLabels map[string]string `label:\"*\"`\n}\n\nfunc main() {\n l := map[string]string { name: \"Homer\" }\n\n v := \u0026Example2{}\n\n err := labeler.Unmarshal(l, v)\n if err != nil {\n // handle err\n _ = err\n }\n fmt.Println(\"Name is: \", v.Name)\n fmt.Println(len(v.Labels), \" Labels\")\n labels, err := labeler.Marshal(v, l)\n if err != nil {\n _ = err\n }\n\n}\n```\n\n### Example with an enum\n\nThe only important bit is that `Color` implements `String() string` and\n`FromString(s string) error`. `Color` could have also implemented\n`UnmarshalText(text []byte) error` and `MarshalText() (text []byte, err error)`.\n\n```go\npackage main\n\ntype Color int\n\nconst (\n\tColorUnknown Color = iota\n\tColorRed\n\tColorBlue\n)\n\ntype Example3 struct {\n\tColor Color `label:\"color\"`\n\tLabels map[string]string `label:\"*\"`\n}\n\nvar colorMapToStr map[Color]string = map[Color]string{\n\tColorUnknown: \"Unknown\",\n\tColorBlue: \"Blue\",\n\tColorRed: \"Red\",\n}\n\n\nfunc getColorMapFromStr() map[string]Color {\n\tm := make(map[string]Color)\n\tfor k, v := range colorMapToStr {\n\t\tm[v] = k\n\t}\n\treturn m\n}\n\nvar colormMapFromStr map[string]Color = getColorMapFromStr()\n\nfunc (c Color) String() string {\n\treturn colorMapToStr[my]\n}\n\nfunc (c *Color) FromString(s string) error {\n\tif v, ok := colorMapFromStr[s]; ok {\n\t\t*my = v\n\t\treturn nil\n\t}\n\treturn errors.New(\"Invalid value\")\n}\n\ntype Example3 struct {\n}\n\n```\n\n### Example using multiple tags\n\nSay you have multiple sources of labels and you want to unmarshal them into the same `struct`. This is achievable by setting the option `Tag`! See [Options](#options) for more info.\n\n```go\nimport (\n\n \"github.com/chanced/labeler\"\n)\n\ntype Example4 struct {\n Name string `property:\"name\"`\n Color string `attribute:\"color\"`\n Characteristics map[string]string\n Attributes map[string]string\n}\n\nfunc (e *Example4) GetLabels(t string){\n switch t {\n case \"property\":\n return e.Characteristics\n case \"attribute\":\n return e.Attributes\n }\n}\nfunc (e *Example4) SetLabels(l map[string]string, t string) error{\n switch t {\n case \"property\":\n e.Characteristics = l\n case \"attribute\":\n e.Attributes = l\n }\n}\n\nfunc main() {\n properties := map[string]string { name: \"Homer\" }\n attributes := map[string]string { color: \"Yellow\" }\n v := \u0026Example4{}\n\n err := labeler.Unmarshal(v, properties, OptTag(\"property\"))\n if err != nil {\n _ = err\n }\n err := labeler.Unmarshal(v, attributes, OptTag(\"attribute\"))\n if err != nil {\n _ = err\n }\n\n}\n```\n\n## Options\n\n### Settings\n\n| Option | Default | Details | Option `func` |\n| :--------------- | :-------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------- |\n| `Tag` | `\"label\"` | `Tag` is the name of the tag to lookup. This is especially handy if you have multiple sources of labels | `OptTag(t string)` |\n| `Separator` | `\",\"` | Seperates the tag attributes. Configurable incase you have a tag that contains commas. | `OptSeparator(v string)` |\n| `Split` | `\",\"` | String used to split and join arrays and slices | `OptSplit(v string)` |\n| `ContainerField` | `\"\"` | `ContainerField` determines the field to set and retrieve the labels in the form of `map[string]string`. If `ContainerField` is set, labeler will assume that `GetLabels` and `SetLabels` should not be utilized. To set the `ContainerField` of a nested field, use dot notation (`Root.Labels`). \u003cbr\u003e`ContainerField` is not required if `input` implements the appropriate `interface` to retrieve and set labels. | `OptContainerField(s string)` |\n| `ContainerToken` | `\"*\"` | Used in place of the `ContainerField` option, indicating the container field via tag instead. It must derive from `map[string]string`. This option is only required if you do not wish to implement mutator/accessor interfaces. This can also be used to set some options such as `TimeFormat`, `FloatFormat`, `ComplexFormat`, `CaseSensitive`, `IntBase`, `UintBase` using the appropriate tokens. | `OptContainerToken(v string)` |\n| `AssignmentStr` | `\":\"` | Used to assign values. This is in the event that a default value needs to contain `\":\"` | `OptAssignmentStr(v string)` |\n| `KeepLabels` | `true` | Indicates whether or not labels that have been assigned to values are kept in the labels `map[string]string` when unmarshaling. | `OptKeepLabels()` `OptDiscardLabels()` |\n| `IgnoreCase` | `true` | If `true`, label keys are matched regardless of case. Setting this to `false` makes all keys case sensitive. This can be overridden at the field level. | `OptCaseSensitive()` |\n| `OmitEmpty` | `true` | Determines whether or not to set zero-value when marshaling and unmarshaling. | `OptOmitEmpty()` `OptIncludeEmpty()` |\n| `TimeFormat` | `\"\"` | Default format / layout to use when formatting `time.Time`. Field level formats can be provided with either `format` (configurable) or `timeformat` (configurable) | `OptTimeFormat(v string)` |\n| `IntBase` | `10` | default base while parsing `int`, `int64`, `int32`, `int16`, `int8` | `OptIntBase(b int)` |\n| `UintBase` | `10` | default base while parsing `uint`, `uint64`, `uint32`, `uint16`, `uint8` | `OptUintBase(b int)` |\n| `ComplexFormat` | `'f'` | Default format to use when formatting `complex` values. | `OptComplexFormat(f byte)` |\n| `FloatFormat` | `'f'` | Default format to use when formatting `float` values. | `OptFloatFormat(f byte)` |\n\n### Tokens\n\n| Option | Default | Details | Option `func` |\n| :------------------- | :---------------: | :------------------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------- |\n| `KeepToken` | `\"keep\"` | Token used to set `KeepLabels` to `true` | `OptKeepToken(v string)` |\n| `DiscardToken` | `\"discard\"` | Token used to set `KeepLabels` to `false` | `OptDiscardToken(v string)` |\n| `DefaultToken` | `\"default\"` | Token to provide a default value if one is not set. | `OptDefaultToken(v string)` |\n| `SplitToken` | `\"split\"` | Token used to set `Split` to `v` | `OptSplitToken(v string)` |\n| `CaseSensitiveToken` | `\"casesensitive\"` | Token used to set `IgnoreCase` to `false` | `OptCaseSensitiveToken(v string)` |\n| `IgnoreCaseToken` | `\"ignorecase\"` | Token used to determine whether or not to ignore case of the field's (or all fields if on container) key | `OptIgnoreCaseToken(v string)` |\n| `OmitEmptyToken` | `\"omitempty\"` | Token used to determine whether or not to assign empty / zero-value labels | `OptOmitEmptyToken(v string)` |\n| `IncludeEmptyToken` | `\"includeempty\"` | Token used to determine whether or not to assign empty / zero-value labels | `OptIncludeEmptyToken(v string)` |\n| `FormatToken` | `\"format\"` | Token to set the field-level formatting for `time` and `float`. | `OptFormatToken(v string)` |\n| `TimeFormatToken` | `\"timeformat\"` | Token used to set `TimeFormat`. `FormatToken` can be used on non-container fields instead. | `OptTimeFormatToken(v string)` |\n| `FloatFormatToken` | `\"floatformat\"` | Token used to set `FloatFormat`. `FormatToken` can be used on non-container fields instead. | `OptFloatFormatToken(v string)` |\n| `ComplexFormatToken` | `\"complexformat\"` | Token used to set `ComplexFormat`. `FormatToken` can be used on non-container fields instead. | `OptComplexFormatToken(v string)` |\n| `BaseToken` | `\"base\"` | sets the token for parsing base of `int`, `int64`, `int32`, `int16`, `int8`, `uint`, `uint64`, `uint32`, `uint16`, and `uint8` at the field level | `OptBaseToken(v string)` |\n| `IntBaseToken` | `\"intbase\"` | sets the token for parsing base of `int`, `int64`, `int32`, `int16`, `int8`, at the container or field level | `OptIntBaseToken(v string)` |\n| `UintBaseToken` | `\"uintbase\"` | sets the token for parsing base of `uint`, `uint64`, `uint32`, `uint16`, `uint8`, at the container or field level | `OptUintBaseToken(v string)` |\n\n## Notes\n\n### Prior Art\n\n- [go-env](https://github.com/Netflix/go-env) by Netflix. This is the only package that I looked at that does something similar. It was a huge help in getting started.\n\nIf you run into any issues or have any questions, please do submit a ticket.\n\n## License\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nDo with it as you wish.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchanced%2Flabeler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchanced%2Flabeler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchanced%2Flabeler/lists"}