cmd/bpa-operator/vendor/github.com/imdario/mergo/README.md

   1 # Mergo
   2
   3 A helper to merge structs and maps in Golang. Useful for configuration default values, avoiding messy if-statements.
   4
   5 Also a lovely [comune](http://en.wikipedia.org/wiki/Mergo) (municipality) in the Province of Ancona in the Italian region of Marche.
   6
   7 ## Status
   8
   9 It is ready for production use. [It is used in several projects by Docker, Google, The Linux Foundation, VMWare, Shopify, etc](https://github.com/imdario/mergo#mergo-in-the-wild).
  10
  11 [![GoDoc][3]][4]
  12 [![GoCard][5]][6]
  13 [![Build Status][1]][2]
  14 [![Coverage Status][7]][8]
  15 [![Sourcegraph][9]][10]
  16 [![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fimdario%2Fmergo.svg?type=shield)](https://app.fossa.io/projects/git%2Bgithub.com%2Fimdario%2Fmergo?ref=badge_shield)
  17
  18 [1]: https://travis-ci.org/imdario/mergo.png
  19 [2]: https://travis-ci.org/imdario/mergo
  20 [3]: https://godoc.org/github.com/imdario/mergo?status.svg
  21 [4]: https://godoc.org/github.com/imdario/mergo
  22 [5]: https://goreportcard.com/badge/imdario/mergo
  23 [6]: https://goreportcard.com/report/github.com/imdario/mergo
  24 [7]: https://coveralls.io/repos/github/imdario/mergo/badge.svg?branch=master
  25 [8]: https://coveralls.io/github/imdario/mergo?branch=master
  26 [9]: https://sourcegraph.com/github.com/imdario/mergo/-/badge.svg
  27 [10]: https://sourcegraph.com/github.com/imdario/mergo?badge
  28
  29 ### Latest release
  30
  31 [Release v0.3.7](https://github.com/imdario/mergo/releases/tag/v0.3.7).
  32
  33 ### Important note
  34
  35 Please keep in mind that in [0.3.2](//github.com/imdario/mergo/releases/tag/0.3.2) Mergo changed `Merge()`and `Map()` signatures to support [transformers](#transformers). An optional/variadic argument has been added, so it won't break existing code.
  36
  37 If you were using Mergo **before** April 6th 2015, please check your project works as intended after updating your local copy with ```go get -u github.com/imdario/mergo```. I apologize for any issue caused by its previous behavior and any future bug that Mergo could cause (I hope it won't!) in existing projects after the change (release 0.2.0).
  38
  39 ### Donations
  40
  41 If Mergo is useful to you, consider buying me a coffee, a beer or making a monthly donation so I can keep building great free software. :heart_eyes:
  42
  43 <a href='https://ko-fi.com/B0B58839' target='_blank'><img height='36' style='border:0px;height:36px;' src='https://az743702.vo.msecnd.net/cdn/kofi1.png?v=0' border='0' alt='Buy Me a Coffee at ko-fi.com' /></a>
  44 [![Beerpay](https://beerpay.io/imdario/mergo/badge.svg)](https://beerpay.io/imdario/mergo)
  45 [![Beerpay](https://beerpay.io/imdario/mergo/make-wish.svg)](https://beerpay.io/imdario/mergo)
  46 <a href="https://liberapay.com/dario/donate"><img alt="Donate using Liberapay" src="https://liberapay.com/assets/widgets/donate.svg"></a>
  47
  48 ### Mergo in the wild
  49
  50 - [moby/moby](https://github.com/moby/moby)
  51 - [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes)
  52 - [vmware/dispatch](https://github.com/vmware/dispatch)
  53 - [Shopify/themekit](https://github.com/Shopify/themekit)
  54 - [imdario/zas](https://github.com/imdario/zas)
  55 - [matcornic/hermes](https://github.com/matcornic/hermes)
  56 - [OpenBazaar/openbazaar-go](https://github.com/OpenBazaar/openbazaar-go)
  57 - [kataras/iris](https://github.com/kataras/iris)
  58 - [michaelsauter/crane](https://github.com/michaelsauter/crane)
  59 - [go-task/task](https://github.com/go-task/task)
  60 - [sensu/uchiwa](https://github.com/sensu/uchiwa)
  61 - [ory/hydra](https://github.com/ory/hydra)
  62 - [sisatech/vcli](https://github.com/sisatech/vcli)
  63 - [dairycart/dairycart](https://github.com/dairycart/dairycart)
  64 - [projectcalico/felix](https://github.com/projectcalico/felix)
  65 - [resin-os/balena](https://github.com/resin-os/balena)
  66 - [go-kivik/kivik](https://github.com/go-kivik/kivik)
  67 - [Telefonica/govice](https://github.com/Telefonica/govice)
  68 - [supergiant/supergiant](supergiant/supergiant)
  69 - [SergeyTsalkov/brooce](https://github.com/SergeyTsalkov/brooce)
  70 - [soniah/dnsmadeeasy](https://github.com/soniah/dnsmadeeasy)
  71 - [ohsu-comp-bio/funnel](https://github.com/ohsu-comp-bio/funnel)
  72 - [EagerIO/Stout](https://github.com/EagerIO/Stout)
  73 - [lynndylanhurley/defsynth-api](https://github.com/lynndylanhurley/defsynth-api)
  74 - [russross/canvasassignments](https://github.com/russross/canvasassignments)
  75 - [rdegges/cryptly-api](https://github.com/rdegges/cryptly-api)
  76 - [casualjim/exeggutor](https://github.com/casualjim/exeggutor)
  77 - [divshot/gitling](https://github.com/divshot/gitling)
  78 - [RWJMurphy/gorl](https://github.com/RWJMurphy/gorl)
  79 - [andrerocker/deploy42](https://github.com/andrerocker/deploy42)
  80 - [elwinar/rambler](https://github.com/elwinar/rambler)
  81 - [tmaiaroto/gopartman](https://github.com/tmaiaroto/gopartman)
  82 - [jfbus/impressionist](https://github.com/jfbus/impressionist)
  83 - [Jmeyering/zealot](https://github.com/Jmeyering/zealot)
  84 - [godep-migrator/rigger-host](https://github.com/godep-migrator/rigger-host)
  85 - [Dronevery/MultiwaySwitch-Go](https://github.com/Dronevery/MultiwaySwitch-Go)
  86 - [thoas/picfit](https://github.com/thoas/picfit)
  87 - [mantasmatelis/whooplist-server](https://github.com/mantasmatelis/whooplist-server)
  88 - [jnuthong/item_search](https://github.com/jnuthong/item_search)
  89 - [bukalapak/snowboard](https://github.com/bukalapak/snowboard)
  90
  91 ## Installation
  92
  93     go get github.com/imdario/mergo
  94
  95     // use in your .go code
  96     import (
  97         "github.com/imdario/mergo"
  98     )
  99
 100 ## Usage
 101
 102 You can only merge same-type structs with exported fields initialized as zero value of their type and same-types maps. Mergo won't merge unexported (private) fields but will do recursively any exported one. It won't merge empty structs value as [they are not considered zero values](https://golang.org/ref/spec#The_zero_value) either. Also maps will be merged recursively except for structs inside maps (because they are not addressable using Go reflection).
 103
 104 ```go
 105 if err := mergo.Merge(&dst, src); err != nil {
 106     // ...
 107 }
 108 ```
 109
 110 Also, you can merge overwriting values using the transformer `WithOverride`.
 111
 112 ```go
 113 if err := mergo.Merge(&dst, src, mergo.WithOverride); err != nil {
 114     // ...
 115 }
 116 ```
 117
 118 Additionally, you can map a `map[string]interface{}` to a struct (and otherwise, from struct to map), following the same restrictions as in `Merge()`. Keys are capitalized to find each corresponding exported field.
 119
 120 ```go
 121 if err := mergo.Map(&dst, srcMap); err != nil {
 122     // ...
 123 }
 124 ```
 125
 126 Warning: if you map a struct to map, it won't do it recursively. Don't expect Mergo to map struct members of your struct as `map[string]interface{}`. They will be just assigned as values.
 127
 128 More information and examples in [godoc documentation](http://godoc.org/github.com/imdario/mergo).
 129
 130 ### Nice example
 131
 132 ```go
 133 package main
 134
 135 import (
 136         "fmt"
 137         "github.com/imdario/mergo"
 138 )
 139
 140 type Foo struct {
 141         A string
 142         B int64
 143 }
 144
 145 func main() {
 146         src := Foo{
 147                 A: "one",
 148                 B: 2,
 149         }
 150         dest := Foo{
 151                 A: "two",
 152         }
 153         mergo.Merge(&dest, src)
 154         fmt.Println(dest)
 155         // Will print
 156         // {two 2}
 157 }
 158 ```
 159
 160 Note: if test are failing due missing package, please execute:
 161
 162     go get gopkg.in/yaml.v2
 163
 164 ### Transformers
 165
 166 Transformers allow to merge specific types differently than in the default behavior. In other words, now you can customize how some types are merged. For example, `time.Time` is a struct; it doesn't have zero value but IsZero can return true because it has fields with zero value. How can we merge a non-zero `time.Time`?
 167
 168 ```go
 169 package main
 170
 171 import (
 172         "fmt"
 173         "github.com/imdario/mergo"
 174         "reflect"
 175         "time"
 176 )
 177
 178 type timeTransfomer struct {
 179 }
 180
 181 func (t timeTransfomer) Transformer(typ reflect.Type) func(dst, src reflect.Value) error {
 182         if typ == reflect.TypeOf(time.Time{}) {
 183                 return func(dst, src reflect.Value) error {
 184                         if dst.CanSet() {
 185                                 isZero := dst.MethodByName("IsZero")
 186                                 result := isZero.Call([]reflect.Value{})
 187                                 if result[0].Bool() {
 188                                         dst.Set(src)
 189                                 }
 190                         }
 191                         return nil
 192                 }
 193         }
 194         return nil
 195 }
 196
 197 type Snapshot struct {
 198         Time time.Time
 199         // ...
 200 }
 201
 202 func main() {
 203         src := Snapshot{time.Now()}
 204         dest := Snapshot{}
 205         mergo.Merge(&dest, src, mergo.WithTransformers(timeTransfomer{}))
 206         fmt.Println(dest)
 207         // Will print
 208         // { 2018-01-12 01:15:00 +0000 UTC m=+0.000000001 }
 209 }
 210 ```
 211
 212
 213 ## Contact me
 214
 215 If I can help you, you have an idea or you are using Mergo in your projects, don't hesitate to drop me a line (or a pull request): [@im_dario](https://twitter.com/im_dario)
 216
 217 ## About
 218
 219 Written by [Dario Castañé](http://dario.im).
 220
 221 ## Top Contributors
 222
 223 [![0](https://sourcerer.io/fame/imdario/imdario/mergo/images/0)](https://sourcerer.io/fame/imdario/imdario/mergo/links/0)
 224 [![1](https://sourcerer.io/fame/imdario/imdario/mergo/images/1)](https://sourcerer.io/fame/imdario/imdario/mergo/links/1)
 225 [![2](https://sourcerer.io/fame/imdario/imdario/mergo/images/2)](https://sourcerer.io/fame/imdario/imdario/mergo/links/2)
 226 [![3](https://sourcerer.io/fame/imdario/imdario/mergo/images/3)](https://sourcerer.io/fame/imdario/imdario/mergo/links/3)
 227 [![4](https://sourcerer.io/fame/imdario/imdario/mergo/images/4)](https://sourcerer.io/fame/imdario/imdario/mergo/links/4)
 228 [![5](https://sourcerer.io/fame/imdario/imdario/mergo/images/5)](https://sourcerer.io/fame/imdario/imdario/mergo/links/5)
 229 [![6](https://sourcerer.io/fame/imdario/imdario/mergo/images/6)](https://sourcerer.io/fame/imdario/imdario/mergo/links/6)
 230 [![7](https://sourcerer.io/fame/imdario/imdario/mergo/images/7)](https://sourcerer.io/fame/imdario/imdario/mergo/links/7)
 231
 232
 233 ## License
 234
 235 [BSD 3-Clause](http://opensource.org/licenses/BSD-3-Clause) license, as [Go language](http://golang.org/LICENSE).
 236
 237
 238 [![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fimdario%2Fmergo.svg?type=large)](https://app.fossa.io/projects/git%2Bgithub.com%2Fimdario%2Fmergo?ref=badge_large)