Documentation ¶
Overview ¶
Package parth provides path parsing for segment unmarshaling and slicing. In other words, parth provides simple and flexible access to (URL) path parameters.
Along with string, all basic non-alias types are supported. An interface is available for implementation by user-defined types. When handling an int, uint, or float of any size, the first valid value within the specified segment will be used.
Example ¶
package main import ( "fmt" "net/http" "os" "github.com/h2non/parth" ) var r, rErr = http.NewRequest("GET", "/zero/1/2/key/nn4.4nn/5.5", nil) func main() { var s string if err := parth.Segment(r.URL.Path, 4, &s); err != nil { fmt.Fprintln(os.Stderr, err) } fmt.Println(r.URL.Path) fmt.Printf("%v (%T)\n", s, s) }
Output: /zero/1/2/key/nn4.4nn/5.5 nn4.4nn (string)
Index ¶
- Variables
- func Segment(path string, i int, v interface{}) error
- func Sequent(path, key string, v interface{}) error
- func Span(path string, i, j int) (string, error)
- func SubSeg(path, key string, i int, v interface{}) error
- func SubSpan(path, key string, i, j int) (string, error)
- type Parth
- type Unmarshaler
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrUnknownType = errors.New("unknown type provided") ErrFirstSegNotFound = errors.New("first segment not found by index") ErrLastSegNotFound = errors.New("last segment not found by index") ErrSegOrderReversed = errors.New("first segment must precede last segment") ErrKeySegNotFound = errors.New("segment not found by key") ErrDataUnparsable = errors.New("data cannot be parsed") )
Err{Name} values facilitate error identification.
Functions ¶
func Segment ¶
Segment locates the path segment indicated by the index i and unmarshals it into the provided type v. If the index is negative, the negative count begins with the last segment. An error is returned if: 1. The type is not a pointer to an instance of one of the basic non-alias types and does not implement the Unmarshaler interface; 2. The index is out of range of the path; 3. The located path segment data cannot be parsed as the provided type or if an error is returned when using a provided Unmarshaler implementation.
Example ¶
package main import ( "fmt" "net/http" "os" "github.com/h2non/parth" ) var r, rErr = http.NewRequest("GET", "/zero/1/2/key/nn4.4nn/5.5", nil) func main() { var s string if err := parth.Segment(r.URL.Path, 4, &s); err != nil { fmt.Fprintln(os.Stderr, err) } fmt.Println(r.URL.Path) fmt.Printf("%v (%T)\n", s, s) }
Output: /zero/1/2/key/nn4.4nn/5.5 nn4.4nn (string)
func Sequent ¶
Sequent is similar to Segment, but uses a key to locate a segment and then unmarshal the subsequent segment. It is a simple wrapper over SubSeg with an index of 0.
Example ¶
package main import ( "fmt" "net/http" "os" "github.com/h2non/parth" ) var r, rErr = http.NewRequest("GET", "/zero/1/2/key/nn4.4nn/5.5", nil) func main() { var f float32 if err := parth.Sequent(r.URL.Path, "key", &f); err != nil { fmt.Fprintln(os.Stderr, err) } fmt.Println(r.URL.Path) fmt.Printf("%v (%T)\n", f, f) }
Output: /zero/1/2/key/nn4.4nn/5.5 4.4 (float32)
func Span ¶
Span returns the path segments between two segment indexes i and j including the first segment. If an index is negative, the negative count begins with the last segment. Providing a 0 for the last index j is a special case which acts as an alias for the end of the path. If the first segment does not begin with a slash and it is part of the requested span, no slash will be added. An error is returned if: 1. Either index is out of range of the path; 2. The first index i does not precede the last index j.
Example ¶
package main import ( "fmt" "net/http" "os" "github.com/h2non/parth" ) var r, rErr = http.NewRequest("GET", "/zero/1/2/key/nn4.4nn/5.5", nil) func main() { s, err := parth.Span(r.URL.Path, 2, 4) if err != nil { fmt.Fprintln(os.Stderr, err) } fmt.Println(r.URL.Path) fmt.Println(s) }
Output: /zero/1/2/key/nn4.4nn/5.5 /2/key
func SubSeg ¶
SubSeg is similar to Segment, but only handles the portion of the path subsequent to the provided key. For example, to access the segment immediately after a key, an index of 0 should be provided (see Sequent). An error is returned if the key cannot be found in the path.
Example ¶
package main import ( "fmt" "net/http" "os" "github.com/h2non/parth" ) var r, rErr = http.NewRequest("GET", "/zero/1/2/key/nn4.4nn/5.5", nil) func main() { var f float64 if err := parth.SubSeg(r.URL.Path, "key", 1, &f); err != nil { fmt.Fprintln(os.Stderr, err) } fmt.Println(r.URL.Path) fmt.Printf("%v (%T)\n", f, f) }
Output: /zero/1/2/key/nn4.4nn/5.5 5.5 (float64)
func SubSpan ¶
SubSpan is similar to Span, but only handles the portion of the path subsequent to the provided key. An error is returned if the key cannot be found in the path.
Example ¶
package main import ( "fmt" "net/http" "os" "github.com/h2non/parth" ) var r, rErr = http.NewRequest("GET", "/zero/1/2/key/nn4.4nn/5.5", nil) func main() { s0, err := parth.SubSpan(r.URL.Path, "zero", 2, 4) if err != nil { fmt.Fprintln(os.Stderr, err) } s1, err := parth.SubSpan(r.URL.Path, "1", 1, 3) if err != nil { fmt.Fprintln(os.Stderr, err) } fmt.Println(r.URL.Path) fmt.Println(s0) fmt.Println(s1) }
Output: /zero/1/2/key/nn4.4nn/5.5 /key/nn4.4nn /key/nn4.4nn
Types ¶
type Parth ¶
type Parth struct {
// contains filtered or unexported fields
}
Parth manages path and error data for processing a single path multiple times while error checking only once. Only the first encountered error is stored as all subsequent calls to Parth methods that can error are elided.
Example ¶
package main import ( "fmt" "net/http" "os" "github.com/h2non/parth" ) var r, rErr = http.NewRequest("GET", "/zero/1/2/key/nn4.4nn/5.5", nil) func main() { var s string var f float32 p := parth.New(r.URL.Path) p.Segment(0, &s) p.SubSeg("key", 1, &f) if err := p.Err(); err != nil { fmt.Fprintln(os.Stderr, err) } fmt.Println(r.URL.Path) fmt.Printf("%v (%T)\n", s, s) fmt.Printf("%v (%T)\n", f, f) }
Output: /zero/1/2/key/nn4.4nn/5.5 zero (string) 5.5 (float32)
func NewBySpan ¶
NewBySpan constructs a pointer to an instance of Parth after preprocessing the provided path with Span.
func NewBySubSpan ¶
NewBySubSpan constructs a pointer to an instance of Parth after preprocessing the provided path with SubSpan.
type Unmarshaler ¶
Unmarshaler is the interface implemented by types that can unmarshal a path segment representation of themselves. It is safe to assume that the segment data will not include slashes.
Example ¶
package main import ( "fmt" "net/http" "os" "github.com/h2non/parth" ) var r, rErr = http.NewRequest("GET", "/zero/1/2/key/nn4.4nn/5.5", nil) func main() { /* type mytype []byte func (m *mytype) UnmarshalSegment(seg string) error { *m = []byte(seg) } */ var m mytype if err := parth.Segment(r.URL.Path, 4, &m); err != nil { fmt.Fprintln(os.Stderr, err) } fmt.Println(r.URL.Path) fmt.Printf("%v == %q (%T)\n", m, m, m) } type mytype []byte func (m *mytype) UnmarshalSegment(seg string) error { *m = []byte(seg) return nil }
Output: /zero/1/2/key/nn4.4nn/5.5 [110 110 52 46 52 110 110] == "nn4.4nn" (parth_test.mytype)