Add native function to library

Author: guoyao

README.md

@@ -19,6 +19,8 @@ import pathToRegexp "github.com/soongo/path-to-regexp"
 // pathToRegexp.Parse(path, options) // options can be nil
 // pathToRegexp.Compile(path, options) // options can be nil
 // pathToRegexp.MustCompile(path, options) // like Compile but panics if the error is non-nil
+// pathToRegexp.Match(path, options) // options can be nil
+// pathToRegexp.MustMatch(path, options) // like Match but panics if the error is non-nil
 // pathToRegexp.Must(regexp, err) // wraps a call to a function returning (*regexp2.Regexp, error) and panics if the error is non-nil.
 ```
 
@@ -39,6 +41,8 @@ import pathToRegexp "github.com/soongo/path-to-regexp"
   - **Delimiter** The default delimiter for segments. (default: `'/'`)
   - **EndsWith** Optional character, or list of characters, to treat as "end" characters.
   - **Whitelist** List of characters to consider delimiters when parsing. (default: `nil`, any character)
+  - **Encode** How to encode uri. (default: `pathToRegexp.EncodeURIComponent`)
+  - **Encode** How to decode uri. (default: `pathToRegexp.DecodeURIComponent`)
 
 ```go
 var tokens []pathToRegexp.Token
@@ -200,9 +204,22 @@ fmt.Println(match)
 
 **Tip:** Backslashes need to be escaped with another backslash in Go strings.
 
+### Match
+
+The `match` function will return a function for transforming paths into parameters:
+
+```go
+match := pathToRegexp.MustMatch("/user/:id")
+
+fmt.Printf("%#v\n", match("/user/123"))
+//=> &pathtoregexp.MatchResult{Path:"/user/123", Index:0, Params:map[interface {}]interface {}{"id":"123"}}
+
+match("/invalid") //=> nil
+```
+
 ### Parse
 
-The parse function is exposed via `pathToRegexp.Parse`. This will return a slice of strings and tokens.
+The `Parse` function will return a list of strings and tokens from a path string:
 
 ```go
 tokens := pathToRegexp.Parse("/route/:foo/(.*)", nil)
@@ -221,7 +238,7 @@ fmt.Printf("%#v\n", tokens[2])
 
 ### Compile ("Reverse" Path-To-RegExp)
 
-Path-To-RegExp exposes a compile function for transforming a string into a valid path.
+The `Compile` function will return a function for transforming parameters into a valid path:
 
 ```go
 falseValue := false

path_to_regexp.go

@@ -65,6 +65,21 @@ type Options struct {
 
 	// how to encode uri
 	Encode func(uri string, token interface{}) string
+
+	// how to decode uri
+	Decode func(str string, token interface{}) string
+}
+
+// MatchResult contains the result of match function
+type MatchResult struct {
+	// matched url path
+	Path string
+
+	// matched start index
+	Index int
+
+	// matched params in url
+	Params map[interface{}]interface{}
 }
 
 // defaultDelimiter is the default delimiter of path.
@@ -174,13 +189,76 @@ func Compile(str string, o *Options) (func(interface{}, *Options) string, error)
 // MustCompile is like Compile but panics if the expression cannot be compiled.
 // It simplifies safe initialization of global variables.
 func MustCompile(str string, o *Options) func(interface{}, *Options) string {
-	f, err := tokensToFunction(Parse(str, o), o)
+	f, err := Compile(str, o)
 	if err != nil {
 		panic(`pathtoregexp: Compile(` + quote(str) + `): ` + err.Error())
 	}
 	return f
 }
 
+// Match creates path match function from `path-to-regexp` spec.
+func Match(path interface{}, o *Options) (func(string, *Options) *MatchResult, error) {
+	var tokens []Token
+	re, err := PathToRegexp(path, &tokens, o)
+	if err != nil {
+		return nil, err
+	}
+
+	return regexpToFunction(re, tokens), nil
+}
+
+// MustMatch is like Match but panics if err occur in match function.
+func MustMatch(path interface{}, o *Options) func(string, *Options) *MatchResult {
+	f, err := Match(path, o)
+	if err != nil {
+		panic(err)
+	}
+	return f
+}
+
+// Create a path match function from `path-to-regexp` output.
+func regexpToFunction(re *regexp2.Regexp, tokens []Token) func(string, *Options) *MatchResult {
+	return func(pathname string, options *Options) *MatchResult {
+		m, err := re.FindStringMatch(pathname)
+		if m == nil || m.GroupCount() == 0 || err != nil {
+			return nil
+		}
+
+		path := m.Groups()[0].String()
+		index := m.Index
+		params := make(map[interface{}]interface{})
+		decode := DecodeURIComponent
+		if options != nil && options.Decode != nil {
+			decode = options.Decode
+		}
+
+		for i := 1; i < m.GroupCount(); i++ {
+			group := m.Groups()[i]
+			if len(group.Captures) == 0 {
+				continue
+			}
+
+			token := tokens[i-1]
+			matchedStr := group.String()
+
+			if token.Repeat {
+				arr := strings.Split(matchedStr, token.Delimiter)
+				length := len(arr)
+				if length > 0 {
+					for i, str := range arr {
+						arr[i] = decode(str, token)
+					}
+					params[token.Name] = arr
+				}
+			} else {
+				params[token.Name] = decode(matchedStr, token)
+			}
+		}
+
+		return &MatchResult{Path: path, Index: index, Params: params}
+	}
+}
+
 // Expose a method for transforming tokens into the path function.
 func tokensToFunction(tokens []interface{}, o *Options) (
 	func(interface{}, *Options) string, error) {
@@ -200,7 +278,7 @@ func tokensToFunction(tokens []interface{}, o *Options) (
 
 	return func(data interface{}, o *Options) string {
 		t := true
-		path, validate, encode := "", &t, encodeURIComponent
+		path, validate, encode := "", &t, EncodeURIComponent
 		if o != nil {
 			if o.Encode != nil {
 				encode = o.Encode
@@ -355,12 +433,20 @@ func toMap(data interface{}) map[interface{}]interface{} {
 	return m
 }
 
-func encodeURIComponent(str string, token interface{}) string {
+func EncodeURIComponent(str string, token interface{}) string {
 	r := url.QueryEscape(str)
 	r = strings.Replace(r, "+", "%20", -1)
 	return r
 }
 
+func DecodeURIComponent(str string, token interface{}) string {
+	r, err := url.QueryUnescape(str)
+	if err != nil {
+		panic(err)
+	}
+	return r
+}
+
 // Escape a regular expression string.
 func escapeString(str string) string {
 	str, err := escapeRegexp.Replace(str, "\\$1", -1, -1)
@@ -408,11 +494,16 @@ func Must(r *regexp2.Regexp, err error) *regexp2.Regexp {
 // Pull out tokens from a regexp.
 func regexpToRegexp(path *regexp2.Regexp, tokens *[]Token) *regexp2.Regexp {
 	if tokens != nil {
-		m, _ := tokenRegexp.FindStringMatch(path.String())
-		if m != nil && m.GroupCount() > 0 {
-			newTokens := make([]Token, 0, len(*tokens)+m.GroupCount())
-			newTokens = append(newTokens, *tokens...)
-			for i := 0; i < m.GroupCount(); i++ {
+		totalGroupCount := 0
+		for m, _ := tokenRegexp.FindStringMatch(path.String()); m != nil; m,
+			_ = tokenRegexp.FindNextMatch(m) {
+			totalGroupCount += m.GroupCount()
+		}
+
+		if totalGroupCount > 0 {
+			newTokens := append(make([]Token, 0), *tokens...)
+
+			for i := 0; i < totalGroupCount; i++ {
 				newTokens = append(newTokens, Token{
 					Name:      i,
 					Prefix:    "",
@@ -422,6 +513,7 @@ func regexpToRegexp(path *regexp2.Regexp, tokens *[]Token) *regexp2.Regexp {
 					Pattern:   "",
 				})
 			}
+
 			hdr := (*reflect.SliceHeader)(unsafe.Pointer(tokens))
 			*hdr = *(*reflect.SliceHeader)(unsafe.Pointer(&newTokens))
 		}