| 1 |
// Copyright 2013 Joshua Tacoma. 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 |
|
| 5 |
// Package uritemplates is a level 4 implementation of RFC 6570 (URI |
| 6 |
// Template, http://tools.ietf.org/html/rfc6570). |
| 7 |
// |
| 8 |
// To use uritemplates, parse a template string and expand it with a value |
| 9 |
// map: |
| 10 |
// |
| 11 |
// template, _ := uritemplates.Parse("https://api.github.com/repos{/user,repo}") |
| 12 |
// values := make(map[string]interface{}) |
| 13 |
// values["user"] = "jtacoma" |
| 14 |
// values["repo"] = "uritemplates" |
| 15 |
// expanded, _ := template.ExpandString(values) |
| 16 |
// fmt.Printf(expanded) |
| 17 |
// |
| 18 |
package uritemplates |
| 19 |
|
| 20 |
import ( |
| 21 |
"bytes" |
| 22 |
"errors" |
| 23 |
"fmt" |
| 24 |
"reflect" |
| 25 |
"regexp" |
| 26 |
"strconv" |
| 27 |
"strings" |
| 28 |
) |
| 29 |
|
| 30 |
var ( |
| 31 |
unreserved = regexp.MustCompile("[^A-Za-z0-9\\-._~]") |
| 32 |
reserved = regexp.MustCompile("[^A-Za-z0-9\\-._~:/?#[\\]@!$&'()*+,;=]") |
| 33 |
validname = regexp.MustCompile("^([A-Za-z0-9_\\.]|%[0-9A-Fa-f][0-9A-Fa-f])+$") |
| 34 |
hex = []byte("0123456789ABCDEF") |
| 35 |
) |
| 36 |
|
| 37 |
func pctEncode(src []byte) []byte { |
| 38 |
dst := make([]byte, len(src)*3) |
| 39 |
for i, b := range src { |
| 40 |
buf := dst[i*3 : i*3+3] |
| 41 |
buf[0] = 0x25 |
| 42 |
buf[1] = hex[b/16] |
| 43 |
buf[2] = hex[b%16] |
| 44 |
} |
| 45 |
return dst |
| 46 |
} |
| 47 |
|
| 48 |
func escape(s string, allowReserved bool) (escaped string) { |
| 49 |
if allowReserved { |
| 50 |
escaped = string(reserved.ReplaceAllFunc([]byte(s), pctEncode)) |
| 51 |
} else { |
| 52 |
escaped = string(unreserved.ReplaceAllFunc([]byte(s), pctEncode)) |
| 53 |
} |
| 54 |
return escaped |
| 55 |
} |
| 56 |
|
| 57 |
// A UriTemplate is a parsed representation of a URI template. |
| 58 |
type UriTemplate struct { |
| 59 |
raw string |
| 60 |
parts []templatePart |
| 61 |
} |
| 62 |
|
| 63 |
// Parse parses a URI template string into a UriTemplate object. |
| 64 |
func Parse(rawtemplate string) (template *UriTemplate, err error) { |
| 65 |
template = new(UriTemplate) |
| 66 |
template.raw = rawtemplate |
| 67 |
split := strings.Split(rawtemplate, "{") |
| 68 |
template.parts = make([]templatePart, len(split)*2-1) |
| 69 |
for i, s := range split { |
| 70 |
if i == 0 { |
| 71 |
if strings.Contains(s, "}") { |
| 72 |
err = errors.New("unexpected }") |
| 73 |
break |
| 74 |
} |
| 75 |
template.parts[i].raw = s |
| 76 |
} else { |
| 77 |
subsplit := strings.Split(s, "}") |
| 78 |
if len(subsplit) != 2 { |
| 79 |
err = errors.New("malformed template") |
| 80 |
break |
| 81 |
} |
| 82 |
expression := subsplit[0] |
| 83 |
template.parts[i*2-1], err = parseExpression(expression) |
| 84 |
if err != nil { |
| 85 |
break |
| 86 |
} |
| 87 |
template.parts[i*2].raw = subsplit[1] |
| 88 |
} |
| 89 |
} |
| 90 |
if err != nil { |
| 91 |
template = nil |
| 92 |
} |
| 93 |
return template, err |
| 94 |
} |
| 95 |
|
| 96 |
type templatePart struct { |
| 97 |
raw string |
| 98 |
terms []templateTerm |
| 99 |
first string |
| 100 |
sep string |
| 101 |
named bool |
| 102 |
ifemp string |
| 103 |
allowReserved bool |
| 104 |
} |
| 105 |
|
| 106 |
type templateTerm struct { |
| 107 |
name string |
| 108 |
explode bool |
| 109 |
truncate int |
| 110 |
} |
| 111 |
|
| 112 |
func parseExpression(expression string) (result templatePart, err error) { |
| 113 |
switch expression[0] { |
| 114 |
case '+': |
| 115 |
result.sep = "," |
| 116 |
result.allowReserved = true |
| 117 |
expression = expression[1:] |
| 118 |
case '.': |
| 119 |
result.first = "." |
| 120 |
result.sep = "." |
| 121 |
expression = expression[1:] |
| 122 |
case '/': |
| 123 |
result.first = "/" |
| 124 |
result.sep = "/" |
| 125 |
expression = expression[1:] |
| 126 |
case ';': |
| 127 |
result.first = ";" |
| 128 |
result.sep = ";" |
| 129 |
result.named = true |
| 130 |
expression = expression[1:] |
| 131 |
case '?': |
| 132 |
result.first = "?" |
| 133 |
result.sep = "&" |
| 134 |
result.named = true |
| 135 |
result.ifemp = "=" |
| 136 |
expression = expression[1:] |
| 137 |
case '&': |
| 138 |
result.first = "&" |
| 139 |
result.sep = "&" |
| 140 |
result.named = true |
| 141 |
result.ifemp = "=" |
| 142 |
expression = expression[1:] |
| 143 |
case '#': |
| 144 |
result.first = "#" |
| 145 |
result.sep = "," |
| 146 |
result.allowReserved = true |
| 147 |
expression = expression[1:] |
| 148 |
default: |
| 149 |
result.sep = "," |
| 150 |
} |
| 151 |
rawterms := strings.Split(expression, ",") |
| 152 |
result.terms = make([]templateTerm, len(rawterms)) |
| 153 |
for i, raw := range rawterms { |
| 154 |
result.terms[i], err = parseTerm(raw) |
| 155 |
if err != nil { |
| 156 |
break |
| 157 |
} |
| 158 |
} |
| 159 |
return result, err |
| 160 |
} |
| 161 |
|
| 162 |
func parseTerm(term string) (result templateTerm, err error) { |
| 163 |
if strings.HasSuffix(term, "*") { |
| 164 |
result.explode = true |
| 165 |
term = term[:len(term)-1] |
| 166 |
} |
| 167 |
split := strings.Split(term, ":") |
| 168 |
if len(split) == 1 { |
| 169 |
result.name = term |
| 170 |
} else if len(split) == 2 { |
| 171 |
result.name = split[0] |
| 172 |
var parsed int64 |
| 173 |
parsed, err = strconv.ParseInt(split[1], 10, 0) |
| 174 |
result.truncate = int(parsed) |
| 175 |
} else { |
| 176 |
err = errors.New("multiple colons in same term") |
| 177 |
} |
| 178 |
if !validname.MatchString(result.name) { |
| 179 |
err = errors.New("not a valid name: " + result.name) |
| 180 |
} |
| 181 |
if result.explode && result.truncate > 0 { |
| 182 |
err = errors.New("both explode and prefix modifers on same term") |
| 183 |
} |
| 184 |
return result, err |
| 185 |
} |
| 186 |
|
| 187 |
// Expand expands a URI template with a set of values to produce a string. |
| 188 |
func (self *UriTemplate) Expand(value interface{}) (string, error) { |
| 189 |
values, ismap := value.(map[string]interface{}) |
| 190 |
if !ismap { |
| 191 |
if m, ismap := struct2map(value); !ismap { |
| 192 |
return "", errors.New("expected map[string]interface{}, struct, or pointer to struct.") |
| 193 |
} else { |
| 194 |
return self.Expand(m) |
| 195 |
} |
| 196 |
} |
| 197 |
var buf bytes.Buffer |
| 198 |
for _, p := range self.parts { |
| 199 |
err := p.expand(&buf, values) |
| 200 |
if err != nil { |
| 201 |
return "", err |
| 202 |
} |
| 203 |
} |
| 204 |
return buf.String(), nil |
| 205 |
} |
| 206 |
|
| 207 |
func (self *templatePart) expand(buf *bytes.Buffer, values map[string]interface{}) error { |
| 208 |
if len(self.raw) > 0 { |
| 209 |
buf.WriteString(self.raw) |
| 210 |
return nil |
| 211 |
} |
| 212 |
var zeroLen = buf.Len() |
| 213 |
buf.WriteString(self.first) |
| 214 |
var firstLen = buf.Len() |
| 215 |
for _, term := range self.terms { |
| 216 |
value, exists := values[term.name] |
| 217 |
if !exists { |
| 218 |
continue |
| 219 |
} |
| 220 |
if buf.Len() != firstLen { |
| 221 |
buf.WriteString(self.sep) |
| 222 |
} |
| 223 |
switch v := value.(type) { |
| 224 |
case string: |
| 225 |
self.expandString(buf, term, v) |
| 226 |
case []interface{}: |
| 227 |
self.expandArray(buf, term, v) |
| 228 |
case map[string]interface{}: |
| 229 |
if term.truncate > 0 { |
| 230 |
return errors.New("cannot truncate a map expansion") |
| 231 |
} |
| 232 |
self.expandMap(buf, term, v) |
| 233 |
default: |
| 234 |
if m, ismap := struct2map(value); ismap { |
| 235 |
if term.truncate > 0 { |
| 236 |
return errors.New("cannot truncate a map expansion") |
| 237 |
} |
| 238 |
self.expandMap(buf, term, m) |
| 239 |
} else { |
| 240 |
str := fmt.Sprintf("%v", value) |
| 241 |
self.expandString(buf, term, str) |
| 242 |
} |
| 243 |
} |
| 244 |
} |
| 245 |
if buf.Len() == firstLen { |
| 246 |
original := buf.Bytes()[:zeroLen] |
| 247 |
buf.Reset() |
| 248 |
buf.Write(original) |
| 249 |
} |
| 250 |
return nil |
| 251 |
} |
| 252 |
|
| 253 |
func (self *templatePart) expandName(buf *bytes.Buffer, name string, empty bool) { |
| 254 |
if self.named { |
| 255 |
buf.WriteString(name) |
| 256 |
if empty { |
| 257 |
buf.WriteString(self.ifemp) |
| 258 |
} else { |
| 259 |
buf.WriteString("=") |
| 260 |
} |
| 261 |
} |
| 262 |
} |
| 263 |
|
| 264 |
func (self *templatePart) expandString(buf *bytes.Buffer, t templateTerm, s string) { |
| 265 |
if len(s) > t.truncate && t.truncate > 0 { |
| 266 |
s = s[:t.truncate] |
| 267 |
} |
| 268 |
self.expandName(buf, t.name, len(s) == 0) |
| 269 |
buf.WriteString(escape(s, self.allowReserved)) |
| 270 |
} |
| 271 |
|
| 272 |
func (self *templatePart) expandArray(buf *bytes.Buffer, t templateTerm, a []interface{}) { |
| 273 |
if len(a) == 0 { |
| 274 |
return |
| 275 |
} else if !t.explode { |
| 276 |
self.expandName(buf, t.name, false) |
| 277 |
} |
| 278 |
for i, value := range a { |
| 279 |
if t.explode && i > 0 { |
| 280 |
buf.WriteString(self.sep) |
| 281 |
} else if i > 0 { |
| 282 |
buf.WriteString(",") |
| 283 |
} |
| 284 |
var s string |
| 285 |
switch v := value.(type) { |
| 286 |
case string: |
| 287 |
s = v |
| 288 |
default: |
| 289 |
s = fmt.Sprintf("%v", v) |
| 290 |
} |
| 291 |
if len(s) > t.truncate && t.truncate > 0 { |
| 292 |
s = s[:t.truncate] |
| 293 |
} |
| 294 |
if self.named && t.explode { |
| 295 |
self.expandName(buf, t.name, len(s) == 0) |
| 296 |
} |
| 297 |
buf.WriteString(escape(s, self.allowReserved)) |
| 298 |
} |
| 299 |
} |
| 300 |
|
| 301 |
func (self *templatePart) expandMap(buf *bytes.Buffer, t templateTerm, m map[string]interface{}) { |
| 302 |
if len(m) == 0 { |
| 303 |
return |
| 304 |
} |
| 305 |
if !t.explode { |
| 306 |
self.expandName(buf, t.name, len(m) == 0) |
| 307 |
} |
| 308 |
var firstLen = buf.Len() |
| 309 |
for k, value := range m { |
| 310 |
if firstLen != buf.Len() { |
| 311 |
if t.explode { |
| 312 |
buf.WriteString(self.sep) |
| 313 |
} else { |
| 314 |
buf.WriteString(",") |
| 315 |
} |
| 316 |
} |
| 317 |
var s string |
| 318 |
switch v := value.(type) { |
| 319 |
case string: |
| 320 |
s = v |
| 321 |
default: |
| 322 |
s = fmt.Sprintf("%v", v) |
| 323 |
} |
| 324 |
if t.explode { |
| 325 |
buf.WriteString(escape(k, self.allowReserved)) |
| 326 |
buf.WriteRune('=') |
| 327 |
buf.WriteString(escape(s, self.allowReserved)) |
| 328 |
} else { |
| 329 |
buf.WriteString(escape(k, self.allowReserved)) |
| 330 |
buf.WriteRune(',') |
| 331 |
buf.WriteString(escape(s, self.allowReserved)) |
| 332 |
} |
| 333 |
} |
| 334 |
} |
| 335 |
|
| 336 |
func struct2map(v interface{}) (map[string]interface{}, bool) { |
| 337 |
value := reflect.ValueOf(v) |
| 338 |
switch value.Type().Kind() { |
| 339 |
case reflect.Ptr: |
| 340 |
return struct2map(value.Elem().Interface()) |
| 341 |
case reflect.Struct: |
| 342 |
m := make(map[string]interface{}) |
| 343 |
for i := 0; i < value.NumField(); i++ { |
| 344 |
tag := value.Type().Field(i).Tag |
| 345 |
var name string |
| 346 |
if strings.Contains(string(tag), ":") { |
| 347 |
name = tag.Get("uri") |
| 348 |
} else { |
| 349 |
name = strings.TrimSpace(string(tag)) |
| 350 |
} |
| 351 |
if len(name) == 0 { |
| 352 |
name = value.Type().Field(i).Name |
| 353 |
} |
| 354 |
m[name] = value.Field(i).Interface() |
| 355 |
} |
| 356 |
return m, true |
| 357 |
} |
| 358 |
return nil, false |
| 359 |
} |