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.Register("/+")
vr.Register("/dir/:var/+")
templates, params, matched := vr.Match("/dir/val/abc")
fmt.Printf("Templates: '%v', Params: '%v', Matched: '%t'\n", templates, params, matched)
// Output: Templates: '[/+ /dir/:var/+]', Params: 'map[var:val]', 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
Complete. May be further optimized but is quick as it is.
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 (greatly) on performance with large number of registered items.
Index ¶
- type Varouter
- func (vr *Varouter) DefinedTemplates() (a []string)
- func (vr *Varouter) Match(path string) (matches []string, vars Vars, matched bool)
- func (vr *Varouter) MatchTo(path *string, matches *[]string, vars *Vars) bool
- func (vr *Varouter) NumTemplates() int
- func (vr *Varouter) Register(template string) (err error)
- type Vars
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
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 (greatly) 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("/dir/:var/+")
templates, params, matched := vr.Match("/dir/val/abc")
fmt.Printf("Templates: '%v', Params: '%v', Matched: '%t'\n", templates, params, matched)
Output: Templates: '[/+ /dir/:var/+]', Params: 'map[var:val]', Matched: 'true'
func NewVarouter ¶
func NewVarouter(usewildcards bool, override, separator, variable, prefix, wildcardone, wildcardmany byte) *Varouter
NewVarouter returns a new *Varouter instance with the given override, separator, variable, prefix, wildcard-one and wildcard-many characters.
func (*Varouter) DefinedTemplates ¶
DefinedTemplates returns a slice of defined templates.
func (*Varouter) Match ¶
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.
See Register for details on how the path is matched against templates.
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) MatchTo ¶ added in v0.0.3
MatchTo is a potentially faster version of Match that takes pointers to preallocated inputs and outputs. All paramaters must be valid pointers. Path is a pointer to a string to match registered templates against. Matches is a pointer to a slice that needs to have enough match capacity. Vars is a pointer to a map into which parsed variables will be stored into. Returns a boolean denoting if anything was matched.
func (*Varouter) NumTemplates ¶
NumTemplates returns number of defined templates.
func (*Varouter) Register ¶
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 Prefix template which will match a path if it is prefixed by it can be defined by adding a Prefix character suffix to the template. For example: "/+", "/edit+", "/home/+"
Prefix characters as part of the path element name are not allowed and can appear exclusively as a single suffix to the template being registered.
Template path elements can be defined as Variables by prefixing the path element with a Variable character which matches the whole path element as a value of the named path element. 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. Override characters as part of template name are allowed.
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.
Source Files
Directories