code review 4893043: url: new package

src/pkg/url/url.go

 // Copyright 2009 The Go Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// Parse URLs (actually URIs, but that seems overly pedantic).
-// RFC 3986
-
-package http
+// Package URL parses and escapes URLs (actually URIs).

[dsymonds, 2011/08/15 09:20:23]

to be more pedantic, although the objects that this package manipulates are
URIs, there are URIs that this package doesn't handle. It only handles the
subset of URIs called URLs.

+// See RFC 3986.
+package url
 
 import (
         "os"
         "strconv"
         "strings"
 )
 
-// URLError reports an error and the operation and URL that caused it.
-type URLError struct {
+// Error reports an error and the operation and URL that caused it.
+type Error struct {
         Op    string
         URL   string
         Error os.Error
 }
 
-func (e *URLError) String() string { return e.Op + " " + e.URL + ": " + e.Error.String() }
+func (e *Error) String() string { return e.Op + " " + e.URL + ": " + e.Error.String() }
 
 func ishex(c byte) bool {
         switch {
         case '0' <= c && c <= '9':
                 return true
         case 'a' <= c && c <= 'f':
                 return true
         case 'A' <= c && c <= 'F':
                 return true
         }
@@ skipping 15 matching lines @@
 type encoding int
 
 const (
         encodePath encoding = 1 + iota
         encodeUserPassword
         encodeQueryComponent
         encodeFragment
         encodeOpaque
 )
 
-type URLEscapeError string
+type EscapeError string
 
-func (e URLEscapeError) String() string {
+func (e EscapeError) String() string {
         return "invalid URL escape " + strconv.Quote(string(e))
 }
 
 // Return true if the specified character should be escaped when
 // appearing in a URL string, according to RFC 2396.
 // When 'all' is true the full range of reserved characters are matched.
 func shouldEscape(c byte, mode encoding) bool {
         // RFC 2396 §2.3 Unreserved characters (alphanum)
         if 'A' <= c && c <= 'Z' || 'a' <= c && c <= 'z' || '0' <= c && c <= '9' {
                 return false
@@ skipping 34 matching lines @@
                         // except that the leading / must be escaped.
                         // (We implement that case in String.)
                         return false
                 }
         }
 
         // Everything else must be escaped.
         return true
 }
 
-// URLUnescape unescapes a string in ``URL encoded'' form,
+// Unescape unescapes a string in ``URL encoded'' form,
 // converting %AB into the byte 0xAB and '+' into ' ' (space).
 // It returns an error if any % is not followed
 // by two hexadecimal digits.
 // Despite the name, this encoding applies only to individual
 // components of the query portion of the URL.
-func URLUnescape(s string) (string, os.Error) {
-        return urlUnescape(s, encodeQueryComponent)
+func Unescape(s string) (string, os.Error) {
+        return unescape(s, encodeQueryComponent)
 }
 
-// urlUnescape is like URLUnescape but mode specifies
+// unescape is like Unescape but mode specifies
 // which section of the URL is being unescaped.
-func urlUnescape(s string, mode encoding) (string, os.Error) {
+func unescape(s string, mode encoding) (string, os.Error) {
         // Count %, check that they're well-formed.
         n := 0
         hasPlus := false
         for i := 0; i < len(s); {
                 switch s[i] {
                 case '%':
                         n++
                         if i+2 >= len(s) || !ishex(s[i+1]) || !ishex(s[i+2]) {
                                 s = s[i:]
                                 if len(s) > 3 {
                                         s = s[0:3]
                                 }
-                                return "", URLEscapeError(s)
+                                return "", EscapeError(s)
                         }
                         i += 3
                 case '+':
                         hasPlus = mode == encodeQueryComponent
                         i++
                 default:
                         i++
                 }
         }
 
@@ skipping 19 matching lines @@
                         i++
                 default:
                         t[j] = s[i]
                         j++
                         i++
                 }
         }
         return string(t), nil
 }
 
-// URLEscape converts a string into ``URL encoded'' form.
+// Escape converts a string into ``URL encoded'' form.
 // Despite the name, this encoding applies only to individual
 // components of the query portion of the URL.
-func URLEscape(s string) string {
-        return urlEscape(s, encodeQueryComponent)
+func Escape(s string) string {
+        return escape(s, encodeQueryComponent)
 }
 
-func urlEscape(s string, mode encoding) string {
+// EncodedPath returns the URL's path in "URL path encoded" form.

[dsymonds, 2011/08/15 09:20:23]

this method seems odd all the way up here. move it down below with the other
methods on *URL.

+func (u *URL) EncodedPath() string {
+        return escape(u.Path, encodePath)
+}
+
+func escape(s string, mode encoding) string {
         spaceCount, hexCount := 0, 0
         for i := 0; i < len(s); i++ {
                 c := s[i]
                 if shouldEscape(c, mode) {
                         if c == ' ' && mode == encodeQueryComponent {
                                 spaceCount++
                         } else {
                                 hexCount++
                         }
                 }
@@ skipping 27 matching lines @@
 // as the form user or user:password and unescapes and returns
 // the two halves.
 //
 // This functionality should only be used with legacy web sites.
 // RFC 2396 warns that interpreting Userinfo this way
 // ``is NOT RECOMMENDED, because the passing of authentication
 // information in clear text (such as URI) has proven to be a
 // security risk in almost every case where it has been used.''
 func UnescapeUserinfo(rawUserinfo string) (user, password string, err os.Error) {
         u, p := split(rawUserinfo, ':', true)
-        if user, err = urlUnescape(u, encodeUserPassword); err != nil {
+        if user, err = unescape(u, encodeUserPassword); err != nil {
                 return "", "", err
         }
-        if password, err = urlUnescape(p, encodeUserPassword); err != nil {
+        if password, err = unescape(p, encodeUserPassword); err != nil {
                 return "", "", err
         }
         return
 }
 
 // EscapeUserinfo combines user and password in the form
 // user:password (or just user if password is empty) and then
 // escapes it for use as the URL.RawUserinfo field.
 //
 // This functionality should only be used with legacy web sites.
 // RFC 2396 warns that interpreting Userinfo this way
 // ``is NOT RECOMMENDED, because the passing of authentication
 // information in clear text (such as URI) has proven to be a
 // security risk in almost every case where it has been used.''
 func EscapeUserinfo(user, password string) string {
-        raw := urlEscape(user, encodeUserPassword)
+        raw := escape(user, encodeUserPassword)
         if password != "" {
-                raw += ":" + urlEscape(password, encodeUserPassword)
+                raw += ":" + escape(password, encodeUserPassword)
         }
         return raw
 }
 
 // A URL represents a parsed URL (technically, a URI reference).
 // The general form represented is:
 //      scheme://[userinfo@]host/path[?query][#fragment]
 // The Raw, RawAuthority, RawPath, and RawQuery fields are in "wire format"
 // (special characters must be hex-escaped if not meant to have special meaning).
 // All other fields are logical values; '+' or '%' represent themselves.
@@ skipping 49 matching lines @@
                 if s[i] == c {
                         if cutc {
                                 return s[0:i], s[i+1:]
                         }
                         return s[0:i], s[i:]
                 }
         }
         return s, ""
 }
 
 // ParseURL parses rawurl into a URL structure.

[dsymonds, 2011/08/15 09:20:23]

update name

 // The string rawurl is assumed not to have a #fragment suffix.
 // (Web browsers strip #fragment before sending the URL to a web server.)
 // The rawurl may be relative or absolute.
-func ParseURL(rawurl string) (url *URL, err os.Error) {
-        return parseURL(rawurl, false)
+func Parse(rawurl string) (url *URL, err os.Error) {
+        return parse(rawurl, false)
 }
 
-// ParseRequestURL parses rawurl into a URL structure.  It assumes that
+// ParseRequest parses rawurl into a URL structure.  It assumes that
 // rawurl was received from an HTTP request, so the rawurl is interpreted
 // only as an absolute URI or an absolute path.
 // The string rawurl is assumed not to have a #fragment suffix.
 // (Web browsers strip #fragment before sending the URL to a web server.)
-func ParseRequestURL(rawurl string) (url *URL, err os.Error) {
-        return parseURL(rawurl, true)
+func ParseRequest(rawurl string) (url *URL, err os.Error) {
+        return parse(rawurl, true)
 }
 
-// parseURL parses a URL from a string in one of two contexts.  If
+// parse parses a URL from a string in one of two contexts.  If
 // viaRequest is true, the URL is assumed to have arrived via an HTTP request,
 // in which case only absolute URLs or path-absolute relative URLs are allowed.
 // If viaRequest is false, all forms of relative URLs are allowed.
-func parseURL(rawurl string, viaRequest bool) (url *URL, err os.Error) {
+func parse(rawurl string, viaRequest bool) (url *URL, err os.Error) {
         var (
                 leadingSlash bool
                 path         string
         )
 
         if rawurl == "" {
                 err = os.NewError("empty url")
                 goto Error
         }
         url = new(URL)
         url.Raw = rawurl
 
         // Split off possible leading "http:", "mailto:", etc.
         // Cannot contain escaped characters.
         if url.Scheme, path, err = getscheme(rawurl); err != nil {
                 goto Error
         }
         leadingSlash = strings.HasPrefix(path, "/")
 
         if url.Scheme != "" && !leadingSlash {
                 // RFC 2396:
                 // Absolute URI (has scheme) with non-rooted path
                 // is uninterpreted.  It doesn't even have a ?query.
                 // This is the case that handles mailto:name@example.com.
                 url.RawPath = path
 
-                if url.Path, err = urlUnescape(path, encodeOpaque); err != nil {
+                if url.Path, err = unescape(path, encodeOpaque); err != nil {
                         goto Error
                 }
                 url.OpaquePath = true
         } else {
                 if viaRequest && !leadingSlash {
                         err = os.NewError("invalid URI for request")
                         goto Error
                 }
 
                 // Split off query before parsing path further.
@@ skipping 24 matching lines @@
                 // instead.  Clients that wish to use RawAuthority will have to
                 // interpret it themselves: RFC 2396 does not define the meaning.
 
                 if strings.Contains(rawHost, "%") {
                         // Host cannot contain escaped characters.
                         err = os.NewError("hexadecimal escape in host")
                         goto Error
                 }
                 url.Host = rawHost
 
-                if url.Path, err = urlUnescape(path, encodePath); err != nil {
+                if url.Path, err = unescape(path, encodePath); err != nil {
                         goto Error
                 }
         }
         return url, nil
 
 Error:
-        return nil, &URLError{"parse", rawurl, err}
+        return nil, &Error{"parse", rawurl, err}
 
 }
 
-// ParseURLReference is like ParseURL but allows a trailing #fragment.
-func ParseURLReference(rawurlref string) (url *URL, err os.Error) {
+// ParseWithReference is like Parse but allows a trailing #fragment.
+func ParseWithReference(rawurlref string) (url *URL, err os.Error) {
         // Cut off #frag.
         rawurl, frag := split(rawurlref, '#', false)
-        if url, err = ParseURL(rawurl); err != nil {
+        if url, err = Parse(rawurl); err != nil {
                 return nil, err
         }
         url.Raw += frag
         url.RawPath += frag
         if len(frag) > 1 {
                 frag = frag[1:]
-                if url.Fragment, err = urlUnescape(frag, encodeFragment); err != nil {
-                        return nil, &URLError{"parse", rawurl, err}
+                if url.Fragment, err = unescape(frag, encodeFragment); err != nil {
+                        return nil, &Error{"parse", rawurl, err}
                 }
         }
         return url, nil
 }
 
 // String reassembles url into a valid URL string.
 //
 // There are redundant fields stored in the URL structure:
 // the String method consults Scheme, Path, Host, RawUserinfo,
 // RawQuery, and Fragment, but not Raw, RawPath or RawAuthority.
@@ skipping 13 matching lines @@
                         result += info + "@"
                 }
                 result += url.Host
         }
         if url.OpaquePath {
                 path := url.Path
                 if strings.HasPrefix(path, "/") {
                         result += "%2f"
                         path = path[1:]
                 }
-                result += urlEscape(path, encodeOpaque)
+                result += escape(path, encodeOpaque)
         } else {
-                result += urlEscape(url.Path, encodePath)
+                result += escape(url.Path, encodePath)
         }
         if url.RawQuery != "" {
                 result += "?" + url.RawQuery
         }
         if url.Fragment != "" {
-                result += "#" + urlEscape(url.Fragment, encodeFragment)
+                result += "#" + escape(url.Fragment, encodeFragment)
         }
         return result
 }
 
+// Values maps a string key to a list of values.
+// It is typically used for query parameters and form values.
+// Unlike in the Header map, the keys in a Values map

[dsymonds, 2011/08/15 09:20:23]

s/Header/http.Header/

+// are case-sensitive.
+type Values map[string][]string
+
+// Get gets the first value associated with the given key.
+// If there are no values associated with the key, Get returns
+// the empty string. To access multiple values, use the map
+// directly.
+func (v Values) Get(key string) string {
+        if v == nil {
+                return ""
+        }
+        vs, ok := v[key]
+        if !ok || len(vs) == 0 {
+                return ""
+        }
+        return vs[0]
+}
+
+// Set sets the key to value. It replaces any existing
+// values.
+func (v Values) Set(key, value string) {
+        v[key] = []string{value}
+}
+
+// Add adds the key to value. It appends to any existing
+// values associated with key.
+func (v Values) Add(key, value string) {
+        v[key] = append(v[key], value)
+}
+
+// Del deletes the values associated with key.
+func (v Values) Del(key string) {
+        v[key] = nil, false
+}
+
+// ParseQuery parses the URL-encoded query string and returns
+// a map listing the values specified for each key.
+// ParseQuery always returns a non-nil map containing all the
+// valid query parameters found; err describes the first decoding error
+// encountered, if any.
+func ParseQuery(query string) (m Values, err os.Error) {
+        m = make(Values)
+        err = parseQuery(m, query)
+        return
+}
+
+func parseQuery(m Values, query string) (err os.Error) {
+        for _, kv := range strings.Split(query, "&") {
+                if len(kv) == 0 {
+                        continue
+                }
+                kvPair := strings.SplitN(kv, "=", 2)
+
+                var key, value string
+                var e os.Error
+                key, e = Unescape(kvPair[0])
+                if e == nil && len(kvPair) > 1 {
+                        value, e = Unescape(kvPair[1])
+                }
+                if e != nil {
+                        err = e
+                        continue
+                }
+                m[key] = append(m[key], value)
+        }
+        return err
+}
+
 // Encode encodes the values into ``URL encoded'' form.
 // e.g. "foo=bar&bar=baz"
 func (v Values) Encode() string {
         if v == nil {
                 return ""
         }
         parts := make([]string, 0, len(v)) // will be large enough for most uses
         for k, vs := range v {
-                prefix := URLEscape(k) + "="
+                prefix := Escape(k) + "="
                 for _, v := range vs {
-                        parts = append(parts, prefix+URLEscape(v))
+                        parts = append(parts, prefix+Escape(v))
                 }
         }
         return strings.Join(parts, "&")
 }
 
 // resolvePath applies special path segments from refs and applies
 // them to base, per RFC 2396.
 func resolvePath(basepath string, refpath string) string {
         base := strings.Split(basepath, "/")
         refs := strings.Split(refpath, "/")
@@ skipping 20 matching lines @@
                 }
         }
         return strings.Join(base, "/")
 }
 
 // IsAbs returns true if the URL is absolute.
 func (url *URL) IsAbs() bool {
         return url.Scheme != ""
 }
 
 // ParseURL parses a URL in the context of a base URL.  The URL in ref

[dsymonds, 2011/08/15 09:20:23]

update name

 // may be relative or absolute.  ParseURL returns nil, err on parse
 // failure, otherwise its return value is the same as ResolveReference.
-func (base *URL) ParseURL(ref string) (*URL, os.Error) {
-        refurl, err := ParseURL(ref)
+func (base *URL) Parse(ref string) (*URL, os.Error) {
+        refurl, err := Parse(ref)
         if err != nil {
                 return nil, err
         }
         return base.ResolveReference(refurl), nil
 }
 
 // ResolveReference resolves a URI reference to an absolute URI from
 // an absolute base URI, per RFC 2396 Section 5.2.  The URI reference
 // may be relative or absolute.  ResolveReference always returns a new
 // URL instance, even if the returned URL is identical to either the
@@ skipping 41 matching lines @@
         }
         url.Raw = url.String()
         return url
 }
 
 // Query parses RawQuery and returns the corresponding values.
 func (u *URL) Query() Values {
         v, _ := ParseQuery(u.RawQuery)
         return v
 }