uri

Documentation

Overview

Package uri provides support for constructing URI references to be used within problems.

Index

• type Builder
  • func Build() Builder
  • func (b *Builder) AddQueries(queries url.Values) *Builder
  • func (b *Builder) AddQuery(key string, value any) *Builder
  • func (b *Builder) AddQueryf(key, format string, args ...any) *Builder
  • func (b *Builder) Base(base any) *Builder
  • func (b *Builder) BaseURL(base *url.URL) *Builder
  • func (b *Builder) Basef(format string, args ...any) *Builder
  • func (b *Builder) Clone() *Builder
  • func (b *Builder) Fragment(fragment any) *Builder
  • func (b *Builder) Fragmentf(format string, args ...any) *Builder
  • func (b *Builder) Path(path any) *Builder
  • func (b *Builder) PathValue(name string, value any) *Builder
  • func (b *Builder) PathValuef(name, format string, args ...any) *Builder
  • func (b *Builder) PathValues(pathValues map[string]string) *Builder
  • func (b *Builder) Pathf(format string, args ...any) *Builder
  • func (b *Builder) Queries(queries url.Values) *Builder
  • func (b *Builder) Query(key string, value any) *Builder
  • func (b *Builder) Queryf(key, format string, args ...any) *Builder
  • func (b *Builder) Reset() *Builder
  • func (b *Builder) String() string
  • func (b *Builder) TrailingSlash(trailingSlash ...bool) *Builder
  • func (b *Builder) URL() *url.URL

Types

type Builder

type Builder struct {
	// contains filtered or unexported fields
}

Builder is used to construct a URI reference.

func Build

func Build() Builder

Build returns a Builder.

func (*Builder) AddQueries

func (b *Builder) AddQueries(queries url.Values) *Builder

AddQueries adds the entries from the given map to the query parameters to be used when building a URI reference.

Builder.Queries can be used to replace the values of any previously set query parameter whose key is present in queries, if needed.

func (*Builder) AddQuery

func (b *Builder) AddQuery(key string, value any) *Builder

AddQuery adds the given key and value to a query parameter with the given key and value to be used when building a URI reference.

value is typically a string, otherwise it is passed to fmt.Sprint and its resulting string is used instead.

Builder.Query can be used to replace the value of any previously set query parameter with the same key, if needed.

func (*Builder) AddQueryf

func (b *Builder) AddQueryf(key, format string, args ...any) *Builder

AddQueryf adds the given key and formatted value to a query parameter with the given key and value to be used when building a URI reference.

Builder.Queryf can be used to replace the value of any previously set query parameter with the same key, if needed.

func (*Builder) Base

func (b *Builder) Base(base any) *Builder

Base sets the given base to be used when building a URI reference.

Any query or fragment segments within base are ignored. These should be specified using the relevant Builder methods. Its path is retained, however, can be overridden and/or expanded using the Builder.Path and Builder.PathValue methods.

base is typically a string or url.URL (or pointers to them), otherwise it is passed to fmt.Sprint and its resulting string is used instead.

base is parsed as an url.URL and passed to Builder.BaseURL, however, any error returned by url.Parse is ignored therefore it is recommended to parse base as a url.URL and then pass it directly to Builder.BaseURL so that any error can be handled.

func (*Builder) BaseURL

func (b *Builder) BaseURL(base *url.URL) *Builder

BaseURL sets the given base to be used when building a URI reference.

Any query or fragment segments within base are ignored. These should be specified using the relevant Builder methods. Its path is retained, however, can be overridden and/or expanded using the Builder.Path and Builder.PathValue methods.

func (*Builder) Basef

func (b *Builder) Basef(format string, args ...any) *Builder

Basef sets the given formatted base to be used when building a URI reference.

Any query or fragment segments within the formatted base are ignored. These should be specified using the relevant Builder methods. Its path is retained, however, can be overridden and/or expanded using the Builder.Path and Builder.PathValue methods.

The formatted base is parsed as an url.URL and passed to Builder.BaseURL, however, any error returned by url.Parse is ignored therefore it is recommended to format and then parse the base as a url.URL and then pass it directly to Builder.BaseURL so that any error can be handled.

func (*Builder) Clone

func (b *Builder) Clone() *Builder

Clone returns a clone of the Builder.

func (*Builder) Fragment

func (b *Builder) Fragment(fragment any) *Builder

Fragment sets the given fragment to be used when a building a URI reference.

fragment is typically a string, otherwise it is passed to fmt.Sprint and its resulting string is used instead.

func (*Builder) Fragmentf

func (b *Builder) Fragmentf(format string, args ...any) *Builder

Fragmentf sets the given formatted fragment to be used when a building a URI reference.

func (*Builder) Path

func (b *Builder) Path(path any) *Builder

Path sets the given path to be used when a building a URI reference.

path is typically a string, otherwise it is passed to fmt.Sprint and its resulting string is used instead.

When not empty, path will take precedence over that of the base, where specified.

func (*Builder) PathValue

func (b *Builder) PathValue(name string, value any) *Builder

PathValue sets a path value with the given name and value to be used when building a URI reference.

value is typically a string, otherwise it is passed to fmt.Sprint and its resulting string is used instead.

Any path value given is replaced in the path of the URI reference when built. The name of the path value is looked up as with a colon (:) prefix and replaced with the value after being passed through url.PathEscape.

func (*Builder) PathValuef

func (b *Builder) PathValuef(name, format string, args ...any) *Builder

PathValuef sets a path value with the given name and formatted value to be used when building a URI reference.

Any path value given is replaced in the path of the URI reference when built. The name of the path value is looked up as with a colon (:) prefix and replaced with the value after being passed through url.PathEscape.

func (*Builder) PathValues

func (b *Builder) PathValues(pathValues map[string]string) *Builder

PathValues sets the path values with the entries within the given map to be used when building a URI reference.

Any path value given is replaced in the path of the URI reference when built. The name of the path value is looked up as with a colon (:) prefix and replaced with the value after being passed through url.PathEscape.

func (*Builder) Pathf

func (b *Builder) Pathf(format string, args ...any) *Builder

Pathf sets the given formatted path to be used when a building a URI reference.

When not empty, the formatted will take precedence over that of the base, where specified.

func (*Builder) Queries

func (b *Builder) Queries(queries url.Values) *Builder

Queries sets the query parameters with the entries within the given map to be used when building a URI reference.

While queries is a multi-value map, Queries will replace the values of any previously set query parameter whose key is present in queries. Builder.AddQueries can be used to add additional values to the same keys, if needed.

func (*Builder) Query

func (b *Builder) Query(key string, value any) *Builder

Query sets a query parameter with the given key and value to be used when building a URI reference.

value is typically a string, otherwise it is passed to fmt.Sprint and its resulting string is used instead.

Query will replace the value of any previously set query parameter with the same key. Builder.AddQuery can be used to add additional values to the same key, resulting in a multi-value query parameter, if needed.

func (*Builder) Queryf

func (b *Builder) Queryf(key, format string, args ...any) *Builder

Queryf sets a query parameter with the given key and formatted value to be used when building a URI reference.

Queryf will replace the value of any previously set query parameter with the same key. Builder.AddQueryf can be used to add additional formatted values to the same key, resulting in a multi-value query parameter, if needed.

func (*Builder) Reset

func (b *Builder) Reset() *Builder

Reset clears all information used to build a URI reference.

func (*Builder) String

func (b *Builder) String() string

String constructs a URI reference and returns its string representation.

func (*Builder) TrailingSlash

func (b *Builder) TrailingSlash(trailingSlash ...bool) *Builder

TrailingSlash sets whether a trailing slash is enforced at the end of the path when building a URI reference.

By default, the presence of such a trailing slash is entirely optional and not added or removed when constructed.

If nothing is passed to TrailingSlash, this is considered equal to passing true. If true, a trailing slash will be enforced at the end of the path. If false, any trailing slash at the end of the pth will be removed.

func (*Builder) URL

func (b *Builder) URL() *url.URL

URL constructs a URI reference and returns its url.URL representation.