url

Documentation

Overview

Package urlpath matches paths against a template. It's meant for applications that take in REST-like URL paths, and need to validate and extract data from those paths.

See New for documentation of the syntax for creating paths. See Match for how to validate and parse an inputted path.

This package is dirctly copied from the library `https://github.com/ucarion/urlpath`.

Index

• type Match
• type Path
  • func New(path string) Path
  • func (p *Path) Build(m Match) (string, bool)
  • func (p *Path) Match(s string) (Match, bool)
• type Segment

Types

type Match

type Match struct {
	// The segments in the input corresponding to parameterized segments in Path.
	Params map[string]string

	// The trailing segments from the input. Note that the leading slash from the
	// trailing segments is not included, since it's implied.
	//
	// An exception to this leading slash rule is made if the Path was constructed
	// as New("*"), in which case Trailing will be identical to the inputted
	// string.
	Trailing string
}

Match represents the data extracted by matching an input against a Path.

To construct instances of Match, see the Match method on Path.

type Path

type Path struct {
	// A sequence of constraints on what valid segments must look like.
	Segments []Segment

	// Whether additional, trailing segments after Segments are acceptable.
	Trailing bool
}

Path is a representation of a sequence of segments.

To construct instances of Path, see New.

func New

func New(path string) Path

New constructs a new Path from its human-readable string representation.

The syntax for paths looks something like the following:

/shelves/:shelf/books/:book

This would match inputs like:

/shelves/foo/books/bar
/shelves/123/books/456
/shelves/123/books/
/shelves//books/456
/shelves//books/

But not any of the following:

/shelves/foo/books
/shelves/foo/books/bar/
/shelves/foo/books/bar/pages/baz
/SHELVES/foo/books/bar
shelves/foo/books/bar

Optionally, a path can allow for "trailing" segments in the input. This is done using a segment simply named "*". For example, this path:

/users/:user/files/*

Would match inputs like:

/users/foo/files/
/users/foo/files/foo/bar/baz.txt
/users/foo/files////

But not:

/users/foo
/users/foo/files

The asterisk syntax for trailing segments only takes effect on the last segment. If an asterisk appears in any other segment, it carries no special meaning.

In more formal terms, the string representation of a path is a sequence of segments separated by slashes. Segments starting with colon (":") are treated as "parameter" segments (see Match).

If the final segment is just the character asterisk ("*"), it is treated as an indication that the path accepts trailing segments, and not included in the Segments of the return value. Instead, Trailing in the return value is marked as true.

func (*Path) Build

func (p *Path) Build(m Match) (string, bool)

Build is the inverse of Match. Given parameter and trailing segment information, Build returns a string which satifies this information.

The second parameter indicates whether the inputted match has the parameters the path specifies. If any of the parameters in the path are not found in the provided Match's Params, then false is returned.

func (*Path) Match

func (p *Path) Match(s string) (Match, bool)

Match checks if the input string satisfies a Path's constraints, and returns parameter and trailing segment information.

The second return value indicates whether the inputted string matched the path. The first return value is meaningful only if the match was successful.

If the match was a success, all parameterized segments in Path have a corresponding entry in the Params of Match. If the path allows for trailing segments in the input, these will be in Trailing.

type Segment

type Segment struct {
	// Whether this segment is parameterized.
	IsParam bool

	// The name of the parameter this segment will be mapped to.
	Param string

	// The constant value the segment is expected to take.
	Const string
}

Segment is a constraint on a single segment in a path.