varouter

README

varouter

Description

Package varouter implements a flexible path matching router with support for variables and wildcards that does not suffer on performance with large number of registered items. It uses maps for path element matching, one per depth level.

Varouter is not a mux, it's a matcher that can be easily adapted to a custom mux that supports any type of Handler.

The additional servemux package demonstrates wrapping varouter into a mux compatible with http.ServeMux.

Example

vr := New()
vr.Register("/+")
vr.Register("/home/:username/+")

templates, params, matched := vr.Match("/home/vedran/.config")

fmt.Printf("Templates: '%v', Params: '%v', Matched: '%t'\n", templates, params, matched)
// Output: Templates: '[/+ /home/:username/+]', Params: 'map[username:vedran]', Matched: 'true'

Features

• Relaxed over Restrictive. Tries to be maximally flexible in the smallest package and API possible.
• Parse tokens are configurable in hope of broadening package use cases.
• Matches are matched exactly but wildcards can be specified in which case multiple matches are possible.
• Overrides can be defined to force single matches.

Status

Work in progress.

• API could still change, but really, not by a lot.
• Will add possibility to register multiple wildcards from a single template.
• Requires further testing and few bugs to remove.

License

MIT. See included LICENSE file.

Documentation

Overview

Package varouter implements a flexible path matching router with support for variables and wildcards that does not suffer on performance with large number of registered items.

Index

• type PlaceholderMap
• type Varouter
  • func New() *Varouter
  • func NewVarouter(override, separator, placeholder, wildcard byte) *Varouter
  • func (vr *Varouter) DefinedTemplates() (a []string)
  • func (vr *Varouter) Match(path string) (matches []string, params PlaceholderMap, matched bool)
  • func (vr *Varouter) NumTemplates() int
  • func (vr *Varouter) Register(template string) (err error)

Examples

• Varouter

Types

type PlaceholderMap

type PlaceholderMap map[string]string

PlaceholderMap is a map of Placeholder names to their values parsed from a Match path.

type Varouter

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

Varouter is a flexible path matching router with support for path element variables and wildcards for matching multiple templates that does not suffer on large number of registered items.

Register parses a template path, splits it on path separators and builds a tree of registered paths using maps.

Match matches specified path against registered templates and returns a list of matched templates and any placeholders parsed from the path.

Adapters for handlers of various packages can easily be built.

For details on use see Register and Match.

Example

vr := New()
vr.Register("/+")
vr.Register("/home/:username/+")

templates, params, matched := vr.Match("/home/vedran/.config")
fmt.Printf("Templates: '%v', Params: '%v', Matched: '%t'\n", templates, params, matched)

Output:

Templates: '[/+ /home/:username/+]', Params: 'map[username:vedran]', Matched: 'true'

func New

func New() *Varouter

New returns a new *Varouter instance with default configuration.

func NewVarouter

func NewVarouter(override, separator, placeholder, wildcard byte) *Varouter

NewVarouter returns a new *Varouter instance with the given override, separator, placeholder and wildcard character.

func (*Varouter) DefinedTemplates

func (vr *Varouter) DefinedTemplates() (a []string)

DefinedTemplates returns a slice of defined templates.

func (*Varouter) Match

func (vr *Varouter) Match(path string) (matches []string, params PlaceholderMap, matched bool)

Match matches a path against registered templates and returns the names of matched templates, a map of parsed param names to param values and a bool indicating if a match occured and previous two result vars are valid.

Returned template names will consist of possibly one or more Wildcard templates that matched the path and possibly a template that matched the path exactly, regardless if template has any placeholders.

If no templates were matched the resulting templates will be nil. If no params were parsed from the path the resulting ParamMap wil be nil.

func (*Varouter) NumTemplates

func (vr *Varouter) NumTemplates() int

NumTemplates returns number of defined templates.

func (*Varouter) Register

func (vr *Varouter) Register(template string) (err error)

Register registers a template which will be matched against a path specified by Match method. If an error occurs during registration it is returned and no template was registered.

Template must be a rooted path, starting with the defined Separator. Match path is matched exactly, including any possibly multiple Separators anywhere in the registered template and dotdot names. For example, all of the following registration templates are legal: "/home", "/home/", "/home//", "/home////users//", "../home", "/what/./the".

A Wildcard template which will match a path if it is prefixed by it can be defined by adding a Wildcard character suffix to the template where the suffix appears as if instead of a name, e.g. "/home/users/+".

Wildcard characters as part of the path element name are legal and registered as is and are left to be interpreted by the user. For example: "/usr/lib+", "/usr/lib+/bash", "/tests/+_test.go", "/home/users/+/.config".

Template path elements can be defined as Placeholders by prefixing the path element with a Placeholder which matches the whole path element as a value of the named path element and are returned as a map. For example: "/home/users/:user", "/:item/:action/", "/movies/:id/comments/".

Templates can be defined as overrides by prefixing the template with the override character. This forces Match to return only one template regardless if the path matches multiple templates and it will be an override template. If more than one override templates Match a path, the override template with the longest prefix wins. More specific matches of templates that are not overrides after a matched override template are not considered.

Only one Placeholder per registered template tree path element level is allowed. For example: "/edit/:user" and "/export/:user" is allowed but "/edit/:user" and "/edit/:admin" is not.