encode.go 9.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357
  1. // Copyright 2013 The Go Authors. All rights reserved.
  2. // Use of this source code is governed by a BSD-style
  3. // license that can be found in the LICENSE file.
  4. // Package query implements encoding of structs into URL query parameters.
  5. //
  6. // As a simple example:
  7. //
  8. // type Options struct {
  9. // Query string `url:"q"`
  10. // ShowAll bool `url:"all"`
  11. // Page int `url:"page"`
  12. // }
  13. //
  14. // opt := Options{ "foo", true, 2 }
  15. // v, _ := query.Values(opt)
  16. // fmt.Print(v.Encode()) // will output: "q=foo&all=true&page=2"
  17. //
  18. // The exact mapping between Go values and url.Values is described in the
  19. // documentation for the Values() function.
  20. package query
  21. import (
  22. "bytes"
  23. "fmt"
  24. "net/url"
  25. "reflect"
  26. "strconv"
  27. "strings"
  28. "time"
  29. )
  30. var timeType = reflect.TypeOf(time.Time{})
  31. var encoderType = reflect.TypeOf(new(Encoder)).Elem()
  32. // Encoder is an interface implemented by any type that wishes to encode
  33. // itself into URL values in a non-standard way.
  34. type Encoder interface {
  35. EncodeValues(key string, v *url.Values) error
  36. }
  37. // Values returns the url.Values encoding of v.
  38. //
  39. // Values expects to be passed a struct, and traverses it recursively using the
  40. // following encoding rules.
  41. //
  42. // Each exported struct field is encoded as a URL parameter unless
  43. //
  44. // - the field's tag is "-", or
  45. // - the field is empty and its tag specifies the "omitempty" option
  46. //
  47. // The empty values are false, 0, any nil pointer or interface value, any array
  48. // slice, map, or string of length zero, and any type (such as time.Time) that
  49. // returns true for IsZero().
  50. //
  51. // The URL parameter name defaults to the struct field name but can be
  52. // specified in the struct field's tag value. The "url" key in the struct
  53. // field's tag value is the key name, followed by an optional comma and
  54. // options. For example:
  55. //
  56. // // Field is ignored by this package.
  57. // Field int `url:"-"`
  58. //
  59. // // Field appears as URL parameter "myName".
  60. // Field int `url:"myName"`
  61. //
  62. // // Field appears as URL parameter "myName" and the field is omitted if
  63. // // its value is empty
  64. // Field int `url:"myName,omitempty"`
  65. //
  66. // // Field appears as URL parameter "Field" (the default), but the field
  67. // // is skipped if empty. Note the leading comma.
  68. // Field int `url:",omitempty"`
  69. //
  70. // For encoding individual field values, the following type-dependent rules
  71. // apply:
  72. //
  73. // Boolean values default to encoding as the strings "true" or "false".
  74. // Including the "int" option signals that the field should be encoded as the
  75. // strings "1" or "0".
  76. //
  77. // time.Time values default to encoding as RFC3339 timestamps. Including the
  78. // "unix" option signals that the field should be encoded as a Unix time (see
  79. // time.Unix()). The "unixmilli" and "unixnano" options will encode the number
  80. // of milliseconds and nanoseconds, respectively, since January 1, 1970 (see
  81. // time.UnixNano()). Including the "layout" struct tag (separate from the
  82. // "url" tag) will use the value of the "layout" tag as a layout passed to
  83. // time.Format. For example:
  84. //
  85. // // Encode a time.Time as YYYY-MM-DD
  86. // Field time.Time `layout:"2006-01-02"`
  87. //
  88. // Slice and Array values default to encoding as multiple URL values of the
  89. // same name. Including the "comma" option signals that the field should be
  90. // encoded as a single comma-delimited value. Including the "space" option
  91. // similarly encodes the value as a single space-delimited string. Including
  92. // the "semicolon" option will encode the value as a semicolon-delimited string.
  93. // Including the "brackets" option signals that the multiple URL values should
  94. // have "[]" appended to the value name. "numbered" will append a number to
  95. // the end of each incidence of the value name, example:
  96. // name0=value0&name1=value1, etc. Including the "del" struct tag (separate
  97. // from the "url" tag) will use the value of the "del" tag as the delimiter.
  98. // For example:
  99. //
  100. // // Encode a slice of bools as ints ("1" for true, "0" for false),
  101. // // separated by exclamation points "!".
  102. // Field []bool `url:",int" del:"!"`
  103. //
  104. // Anonymous struct fields are usually encoded as if their inner exported
  105. // fields were fields in the outer struct, subject to the standard Go
  106. // visibility rules. An anonymous struct field with a name given in its URL
  107. // tag is treated as having that name, rather than being anonymous.
  108. //
  109. // Non-nil pointer values are encoded as the value pointed to.
  110. //
  111. // Nested structs are encoded including parent fields in value names for
  112. // scoping. e.g:
  113. //
  114. // "user[name]=acme&user[addr][postcode]=1234&user[addr][city]=SFO"
  115. //
  116. // All other values are encoded using their default string representation.
  117. //
  118. // Multiple fields that encode to the same URL parameter name will be included
  119. // as multiple URL values of the same name.
  120. func Values(v interface{}) (url.Values, error) {
  121. values := make(url.Values)
  122. val := reflect.ValueOf(v)
  123. for val.Kind() == reflect.Ptr {
  124. if val.IsNil() {
  125. return values, nil
  126. }
  127. val = val.Elem()
  128. }
  129. if v == nil {
  130. return values, nil
  131. }
  132. if val.Kind() != reflect.Struct {
  133. return nil, fmt.Errorf("query: Values() expects struct input. Got %v", val.Kind())
  134. }
  135. err := reflectValue(values, val, "")
  136. return values, err
  137. }
  138. // reflectValue populates the values parameter from the struct fields in val.
  139. // Embedded structs are followed recursively (using the rules defined in the
  140. // Values function documentation) breadth-first.
  141. func reflectValue(values url.Values, val reflect.Value, scope string) error {
  142. var embedded []reflect.Value
  143. typ := val.Type()
  144. for i := 0; i < typ.NumField(); i++ {
  145. sf := typ.Field(i)
  146. if sf.PkgPath != "" && !sf.Anonymous { // unexported
  147. continue
  148. }
  149. sv := val.Field(i)
  150. tag := sf.Tag.Get("url")
  151. if tag == "-" {
  152. continue
  153. }
  154. name, opts := parseTag(tag)
  155. if name == "" {
  156. if sf.Anonymous {
  157. v := reflect.Indirect(sv)
  158. if v.IsValid() && v.Kind() == reflect.Struct {
  159. // save embedded struct for later processing
  160. embedded = append(embedded, v)
  161. continue
  162. }
  163. }
  164. name = sf.Name
  165. }
  166. if scope != "" {
  167. name = scope + "[" + name + "]"
  168. }
  169. if opts.Contains("omitempty") && isEmptyValue(sv) {
  170. continue
  171. }
  172. if sv.Type().Implements(encoderType) {
  173. // if sv is a nil pointer and the custom encoder is defined on a non-pointer
  174. // method receiver, set sv to the zero value of the underlying type
  175. if !reflect.Indirect(sv).IsValid() && sv.Type().Elem().Implements(encoderType) {
  176. sv = reflect.New(sv.Type().Elem())
  177. }
  178. m := sv.Interface().(Encoder)
  179. if err := m.EncodeValues(name, &values); err != nil {
  180. return err
  181. }
  182. continue
  183. }
  184. // recursively dereference pointers. break on nil pointers
  185. for sv.Kind() == reflect.Ptr {
  186. if sv.IsNil() {
  187. break
  188. }
  189. sv = sv.Elem()
  190. }
  191. if sv.Kind() == reflect.Slice || sv.Kind() == reflect.Array {
  192. var del string
  193. if opts.Contains("comma") {
  194. del = ","
  195. } else if opts.Contains("space") {
  196. del = " "
  197. } else if opts.Contains("semicolon") {
  198. del = ";"
  199. } else if opts.Contains("brackets") {
  200. name = name + "[]"
  201. } else {
  202. del = sf.Tag.Get("del")
  203. }
  204. if del != "" {
  205. s := new(bytes.Buffer)
  206. first := true
  207. for i := 0; i < sv.Len(); i++ {
  208. if first {
  209. first = false
  210. } else {
  211. s.WriteString(del)
  212. }
  213. s.WriteString(valueString(sv.Index(i), opts, sf))
  214. }
  215. values.Add(name, s.String())
  216. } else {
  217. for i := 0; i < sv.Len(); i++ {
  218. k := name
  219. if opts.Contains("numbered") {
  220. k = fmt.Sprintf("%s%d", name, i)
  221. }
  222. values.Add(k, valueString(sv.Index(i), opts, sf))
  223. }
  224. }
  225. continue
  226. }
  227. if sv.Type() == timeType {
  228. values.Add(name, valueString(sv, opts, sf))
  229. continue
  230. }
  231. if sv.Kind() == reflect.Struct {
  232. if err := reflectValue(values, sv, name); err != nil {
  233. return err
  234. }
  235. continue
  236. }
  237. values.Add(name, valueString(sv, opts, sf))
  238. }
  239. for _, f := range embedded {
  240. if err := reflectValue(values, f, scope); err != nil {
  241. return err
  242. }
  243. }
  244. return nil
  245. }
  246. // valueString returns the string representation of a value.
  247. func valueString(v reflect.Value, opts tagOptions, sf reflect.StructField) string {
  248. for v.Kind() == reflect.Ptr {
  249. if v.IsNil() {
  250. return ""
  251. }
  252. v = v.Elem()
  253. }
  254. if v.Kind() == reflect.Bool && opts.Contains("int") {
  255. if v.Bool() {
  256. return "1"
  257. }
  258. return "0"
  259. }
  260. if v.Type() == timeType {
  261. t := v.Interface().(time.Time)
  262. if opts.Contains("unix") {
  263. return strconv.FormatInt(t.Unix(), 10)
  264. }
  265. if opts.Contains("unixmilli") {
  266. return strconv.FormatInt((t.UnixNano() / 1e6), 10)
  267. }
  268. if opts.Contains("unixnano") {
  269. return strconv.FormatInt(t.UnixNano(), 10)
  270. }
  271. if layout := sf.Tag.Get("layout"); layout != "" {
  272. return t.Format(layout)
  273. }
  274. return t.Format(time.RFC3339)
  275. }
  276. return fmt.Sprint(v.Interface())
  277. }
  278. // isEmptyValue checks if a value should be considered empty for the purposes
  279. // of omitting fields with the "omitempty" option.
  280. func isEmptyValue(v reflect.Value) bool {
  281. switch v.Kind() {
  282. case reflect.Array, reflect.Map, reflect.Slice, reflect.String:
  283. return v.Len() == 0
  284. case reflect.Bool:
  285. return !v.Bool()
  286. case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
  287. return v.Int() == 0
  288. case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64, reflect.Uintptr:
  289. return v.Uint() == 0
  290. case reflect.Float32, reflect.Float64:
  291. return v.Float() == 0
  292. case reflect.Interface, reflect.Ptr:
  293. return v.IsNil()
  294. }
  295. type zeroable interface {
  296. IsZero() bool
  297. }
  298. if z, ok := v.Interface().(zeroable); ok {
  299. return z.IsZero()
  300. }
  301. return false
  302. }
  303. // tagOptions is the string following a comma in a struct field's "url" tag, or
  304. // the empty string. It does not include the leading comma.
  305. type tagOptions []string
  306. // parseTag splits a struct field's url tag into its name and comma-separated
  307. // options.
  308. func parseTag(tag string) (string, tagOptions) {
  309. s := strings.Split(tag, ",")
  310. return s[0], s[1:]
  311. }
  312. // Contains checks whether the tagOptions contains the specified option.
  313. func (o tagOptions) Contains(option string) bool {
  314. for _, s := range o {
  315. if s == option {
  316. return true
  317. }
  318. }
  319. return false
  320. }