router

README

Go-Router

Package router implements regex based route matching.

The Router itself does nothing but breaks down a method/path into a series of route alias's which all share the same ID.

Matches can either return the ID of the route or return a router.

Response that contains status code information and resolved variables for that path.

Import the router

    $ go get -u gitlab.com/krobolt/go-router

Creating the Router

    package main

    import router "gitlab.com/krobolt/go-router"
    
    func main(){
        router := router.NewRouter("/baseuri")
    }

Adding Routes

    router.Add("method", "/path")

Grouping Routes

		router.Group("/group-path",func(){
			router.Add("method","/path")
			router.Add("another-method","/another-path")
		})

Adding Required Fields

Required fields are started with router.RouterOptions.VarSep, default ':'

Allowed chars are then specified within brackets:

		`(a-z)` = lowercase `a` to `z` cast variable as string
		`(A-Z)` = uppercase `A` to `Z` cast variable as string
		`(0-9)` = int only 0,1,2,..9 case variable to int64
		`(a-zA-z0-9-.)` = allow 0-9, upper and lower case. Allow `.`, `-` case as string

The name for that variable is then followed by the hypen -VARNAME

Variable name can be uppper/lowercase/numbers and contain .,_,- this can be changed by updating router.RouterOptions.AllowedVars

		router.Add("GET", "/some/path/:(a-z)-variable")

Would match:

		/some/path/lowercaseword
		map["variable"] = "lowercaseword"

Example:

		router.Add("GET", "/blog/post/:(0-9)-year|/:(a-z\-)-title")

Matches:

		/blog/post/2018
		/blog/post/2018/my-blog-title
		/blog/post/2018/another-blog-title
		/blog/post/2018/another-blog-title-with-int-898222

Prefixing/Suffixing Variable Routes

	use '!` to denote
	router.Add("GET", "/blog/post/year-!:(0-9)-year)

	would match:
	/blog/post/year-1999
	with var ['year'] = 1999

	router.Add("GET", "/blog/post/:(0-9)-year!-year)

	would match:
	/blog/post/1999-year
	with var ['year'] = 1999

Matching Routes

		router.Response = r.Match(method, post)

		router.Response.GetStatusCode()
		router.Response.GetVars()
		router.Response.GetRoute()
		router.Response.GetRoute().GetID()

Customising the router

		options := router.NewDefaultOptions()

		options.VarSep:       `:`,
		options.OptionalSep:  `&`,
		options.DefaultInput:  `1-9`,
		options.AllowedVars:   `a-z`,
		options.VarSearch:    options.VarSep + `\(([` + options.DefaultInput + `+]+)\)` + `-(` + `[` + options.AllowedVars + `]+` +  `)`,
		options.Seperator:    `0`,

Documentation

Overview

Package router implements regex based route matching. go The Router itself does nothing but breaks down a method/path into a series of route alias's which all share the same ID.

Matches can either return the ID of the route or return a router.

Response that contains status code information and resolved variables for that path.

Creating the Router

router := router.NewRouter("/baseuri")

Adding Routes

router.Add("method", "/path")

Grouping Routes

router.Group("/group-path",func(){
	router.Add("method","/path")
	router.Add("another-method","/another-path")
})

Adding Required Fields

Required fields are started with router.RouterOptions.VarSep, default ':'

Allowed chars are then specified within brackets:

`(a-z)` = lowercase `a` to `z` cast variable as string
`(A-Z)` = uppercase `A` to `Z` cast variable as string
`(0-9)` = int only 0,1,2,..9 case variable to int64
`(a-zA-z0-9-.)` = allow 0-9, upper and lower case. Allow `.`, `-` case as string

The name for that variable is then followed by the hypen `-VARNAME`

Variable name can be uppper/lowercase/numbers and contain `.`,`_`,`-` this can be changed by updating router.RouterOptions.AllowedVars

router.Add("GET", "/some/path/:(a-z)-variable")

Would match:

/some/path/lowercaseword
map["variable"] = "lowercaseword"

Examples

router.Add("GET", "/blog/post/:(0-9)-year|/:(a-z\-)-title")

/blog/post/2018
/blog/post/2018/my-blog-title
/blog/post/2018/another-blog-title
/blog/post/2018/another-blog-title-with-int-898222

Prefixing/Suffixing Variable Routes

use '!` to denote
router.Add("GET", "/blog/post/year-!:(0-9)-year)

would match:
/blog/post/year-1999
with var ['year'] = 1999

router.Add("GET", "/blog/post/:(0-9)-year!-year)

would match:
/blog/post/1999-year
with var ['year'] = 1999

Matching Routes

router.Response = r.Match(method, post)

router.Response.GetStatusCode()
router.Response.GetVars()
router.Response.GetRoute()
router.Response.GetRoute().GetID()

Customising the router

options := router.NewDefaultOptions()

options.VarSep:       `:`,
options.OptionalSep:  `&`,
options.DefaultInput:  `1-9`,
options.AllowedVars:   `a-z`,
options.VarSearch:    options.VarSep + `\(([` + options.DefaultInput + `+]+)\)` + `-(` + `[` + options.AllowedVars + `]+` +  `)`,
options.Seperator:    `0`,

Index

• func CreateID(method string, path string) (string, error)
• func NewRouteAlias(id string, uri string, len int) *alias
• func NewRouter(path string, options Options) *router
• type Options
  • func NewDefaultOptions() Options
• type Response
  • func NewResponse(status int, r Route, vars map[string]interface{}) Response
• type Route
  • func NewRoute(method string, path string, p []RouteParam, a []RouteAlias, id string) Route
• type RouteAlias
• type RouteParam
  • func CreateParamFromString(varSearch string, separator string, group string, s string, index int) (RouteParam, error)
  • func NewParam(group string, source string, regex string, path string, name string, index int) RouteParam
• type Router

Functions

func CreateID

func CreateID(method string, path string) (string, error)

CreateID creates an ident string from provided method and path

func NewRouteAlias

func NewRouteAlias(id string, uri string, len int) *alias

NewRouteAlias creates a new route alias id string of route uri string of alias len int arg count

func NewRouter

func NewRouter(path string, options Options) *router

NewRouter to create router with default settings. Router only aceppts method and path and returns a route with a unique id @see dispatcher

Types

type Options

type Options struct {
	VarSep          string //     	`:`
	OptionalSep     string //  	 	`|`
	AllowedChars    string // 		`a-z\-_AZ0-9`
	AllowedVarChars string //		`a-z\-_AZ0-9`
	Separator       string //   	 "/"
	// : + `\(([` + `a-z\-_AZ0-9` + `+]+)\)` + varOpen + `[` + varLoopuk + `]+` + varClose
	//`:` + `\(([` + `a-zAZ0-9.\-_` + `+]+)\)` + `-(` + `[` + `a-zAZ0-9.\-_` + `]+` + `)`
	Pattern string
}

func NewDefaultOptions

func NewDefaultOptions() Options

NewDefaultOptions creates router with common settings

type Response

type Response interface {
	GetRoute() Route
	GetStatusCode() int
	GetVars() map[string]interface{}
}

Response is returned from a Router::matchRoute A Response from the router only contains the underlying route information and url variables This needs to be upgraded to a Dispatcher.Response in order to contaner handler information @see gitlab.com/krobolt/go-distpatcher

func NewResponse

func NewResponse(status int, r Route, vars map[string]interface{}) Response

NewResponse returns a new Response

type Route

type Route interface {
	GetID() string
	GetMethod() string
	GetPath() string
	GetBase() string
	GetParams() []RouteParam
	GetAliases() []RouteAlias
}

Route interface defines only basic root information ID: unique ident for url Alias: Additional possible routes (e.g. optional fields) are given alias with the same id as the parent route.

func NewRoute

func NewRoute(method string, path string, p []RouteParam, a []RouteAlias, id string) Route

NewRoute helper function

type RouteAlias

type RouteAlias interface {
	//GetID returns id for the alias/parent route
	GetID() string
	//GetURI returns uri string of current route.
	GetURI() string
	//GetIndex returns the number of params in this alias.
	GetArgCount() int
}

RouteAlias is a reference to it's parent route. They all share the same ID. Alias's are created for each possible match for that route. Optional param's will results in additional alias's

type RouteParam

type RouteParam interface {
	GetName() string
	GetGroup() string
	GetRegex() string
	GetPath() string
	GetSource() string
	GetIndex() int
	SetPartional(s string)
	PartialURI() string
}

RouteParam is the basic parts of the path provided

func CreateParamFromString

func CreateParamFromString(varSearch string, separator string, group string, s string, index int) (RouteParam, error)

CreateParamFromString returns Param from provided arguments

func NewParam

func NewParam(group string, source string, regex string, path string, name string, index int) RouteParam

NewParam returns instance of RouteParam, router.param group: group name e.g base, optional, required souce: original input e.g. (a-z)-varname regex: replacement pattern e.g. [a-z]+ path: path name e.g. varname name: name of variable if set e.g varname

type Router

type Router interface {
	//Group routes together under a common directory/name
	Group(path string, callback func())
	//Add Route to router
	Add(method string, path string) (Route, error)
	//Match route and return the id as string, status as int
	//Status Codes:
	//0 - No Match
	//1 - Match but wrong method
	//2 - Match with correct method
	Find(method string, path string) (string, int)
	//Match route and return a router.Respons
	Match(method string, path string) Response
	//WithOptions updates router settings after initialisation
	GetOptions() Options
	//GetBase returns base path
	GetBase() string
}

Router interface