url

Documentation

Overview

Package URL parses URLs and implements query escaping. See RFC 3986.

Index

• func EscapeUserinfo(user, password string) string
• func QueryEscape(s string) string
• func QueryUnescape(s string) (string, os.Error)
• func UnescapeUserinfo(rawUserinfo string) (user, password string, err os.Error)
• type Error
  • func (e *Error) String() string
• type EscapeError
  • func (e EscapeError) String() string
• type URL
  • func Parse(rawurl string) (url *URL, err os.Error)
  • func ParseRequest(rawurl string) (url *URL, err os.Error)
  • func ParseWithReference(rawurlref string) (url *URL, err os.Error)
  • func (u *URL) EncodedPath() string
  • func (url *URL) IsAbs() bool
  • func (base *URL) Parse(ref string) (*URL, os.Error)
  • func (u *URL) Query() Values
  • func (base *URL) ResolveReference(ref *URL) *URL
  • func (url *URL) String() string
• type Values
  • func ParseQuery(query string) (m Values, err os.Error)
  • func (v Values) Add(key, value string)
  • func (v Values) Del(key string)
  • func (v Values) Encode() string
  • func (v Values) Get(key string) string
  • func (v Values) Set(key, value string)

Functions

func EscapeUserinfo

func EscapeUserinfo(user, password string) string

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 QueryEscape

func QueryEscape(s string) string

QueryEscape escapes the string so it can be safely placed inside a URL query.

func QueryUnescape

func QueryUnescape(s string) (string, os.Error)

QueryUnescape does the inverse transformation of QueryEscape, converting %AB into the byte 0xAB and '+' into ' ' (space). It returns an error if any % is not followed by two hexadecimal digits.

func UnescapeUserinfo

func UnescapeUserinfo(rawUserinfo string) (user, password string, err os.Error)

UnescapeUserinfo parses the RawUserinfo field of a URL 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.”

Types

type Error

type Error struct {
	Op    string
	URL   string
	Error os.Error
}

Error reports an error and the operation and URL that caused it.

func (*Error) String

func (e *Error) String() string

type EscapeError

type EscapeError string

func (EscapeError) String

func (e EscapeError) String() string

type URL

type URL struct {
	Raw          string // the original string
	Scheme       string // scheme
	RawAuthority string // [userinfo@]host
	RawUserinfo  string // userinfo
	Host         string // host
	RawPath      string // /path[?query][#fragment]
	Path         string // /path
	OpaquePath   bool   // path is opaque (unrooted when scheme is present)
	RawQuery     string // query
	Fragment     string // fragment
}

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.

The various Raw values are supplied in wire format because clients typically have to split them into pieces before further decoding.

func Parse

func Parse(rawurl string) (url *URL, err os.Error)

Parse parses rawurl into a URL structure. 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 ParseRequest

func ParseRequest(rawurl string) (url *URL, err os.Error)

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 ParseWithReference

func ParseWithReference(rawurlref string) (url *URL, err os.Error)

ParseWithReference is like Parse but allows a trailing #fragment.

func (*URL) EncodedPath

func (u *URL) EncodedPath() string

EncodedPath returns the URL's path in "URL path encoded" form.

func (*URL) IsAbs

func (url *URL) IsAbs() bool

IsAbs returns true if the URL is absolute.

func (*URL) Parse

func (base *URL) Parse(ref string) (*URL, os.Error)

Parse parses a URL in the context of a base URL. The URL in ref may be relative or absolute. Parse returns nil, err on parse failure, otherwise its return value is the same as ResolveReference.

func (*URL) Query

func (u *URL) Query() Values

Query parses RawQuery and returns the corresponding values.

func (*URL) ResolveReference

func (base *URL) ResolveReference(ref *URL) *URL

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 base or reference. If ref is an absolute URL, then ResolveReference ignores base and returns a copy of ref.

func (*URL) String

func (url *URL) String() string

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.

type Values

type Values map[string][]string

Values maps a string key to a list of values. It is typically used for query parameters and form values. Unlike in the http.Header map, the keys in a Values map are case-sensitive.

func ParseQuery

func ParseQuery(query string) (m Values, err os.Error)

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 (Values) Add

func (v Values) Add(key, value string)

Add adds the key to value. It appends to any existing values associated with key.

func (Values) Del

func (v Values) Del(key string)

Del deletes the values associated with key.

func (Values) Encode

func (v Values) Encode() string

Encode encodes the values into “URL encoded” form. e.g. "foo=bar&bar=baz"

func (Values) Get

func (v Values) Get(key 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 (Values) Set

func (v Values) Set(key, value string)

Set sets the key to value. It replaces any existing values.