parth

package module
v2.0.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 15, 2024 License: MIT Imports: 3 Imported by: 0

README

parth

Moved to daved/parth

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
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

Examples

Constants

This section is empty.

Variables

View Source
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

func Segment(path string, i int, v interface{}) error

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
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

func Sequent(path, key string, v interface{}) error

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
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

func Span(path string, i, j int) (string, error)

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
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

func SubSeg(path, key string, i int, v interface{}) error

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
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

func SubSpan(path, key string, i, j int) (string, error)

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
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
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 New

func New(path string) *Parth

New constructs a pointer to an instance of Parth around the provided path.

func NewBySpan

func NewBySpan(path string, i, j int) *Parth

NewBySpan constructs a pointer to an instance of Parth after preprocessing the provided path with Span.

func NewBySubSpan

func NewBySubSpan(path, key string, i, j int) *Parth

NewBySubSpan constructs a pointer to an instance of Parth after preprocessing the provided path with SubSpan.

func (*Parth) Err

func (p *Parth) Err() error

Err returns the first error encountered by the *Parth receiver.

func (*Parth) Segment

func (p *Parth) Segment(i int, v interface{})

Segment operates the same as the package-level function Segment.

func (*Parth) Sequent

func (p *Parth) Sequent(key string, v interface{})

Sequent operates the same as the package-level function Sequent.

func (*Parth) Span

func (p *Parth) Span(i, j int) string

Span operates the same as the package-level function Span.

func (*Parth) SubSeg

func (p *Parth) SubSeg(key string, i int, v interface{})

SubSeg operates the same as the package-level function SubSeg.

func (*Parth) SubSpan

func (p *Parth) SubSpan(key string, i, j int) string

SubSpan operates the same as the package-level function SubSpan.

type Unmarshaler

type Unmarshaler interface {
	UnmarshalSegment(string) error
}

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
/*
	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)
Output:

/zero/1/2/key/nn4.4nn/5.5
[110 110 52 46 52 110 110] == "nn4.4nn" (parth_test.mytype)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL