protopath

Documentation

Overview

Package protopath implements facilities to retrieve values from Protocol Buffer messages using proto paths - lists of Unicode characters that encodes a series of segments. Each segment represent an access operations on Protocol Buffers composite type (message, list or map), that when executed will retrieve a specific value.

Although proto paths are similar to JSON paths (RFC 9535) they are more lightweight as they focus purely on accessing values and omit any complex sematic (like conditions or transformations) to from a viable alternative to Protocol Buffer field maps. Main difference between proto paths and field maps is that the former can work not only on messages but also on (and within) lists (repeated fields) and maps.

Index

• Variables
• func Access(base proto.Message, path Segments) (any, error)
• func AccessMutable(base proto.Message, path Segments) (any, error)
• func Get(base proto.Message, path Segments) (any, error)
• func JoinPaths(paths ...string) string
• func Mutable(base proto.Message, path Segments) (any, error)
• func NewErrInPath(path string, err error) error
• type EncodingOption
  • func ForceSquareBracketsWrapping() EncodingOption
  • func PreferSquareBracketsWrapping() EncodingOption
• type ErrInPath
  • func (e *ErrInPath) Error() string
  • func (e *ErrInPath) Unwrap() error
• type ErrInvalidSegment
  • func (e *ErrInvalidSegment) Error() string
• type ErrNotFound
  • func (e *ErrNotFound) Error() string
• type Segment
  • func NewSegment(value string, opts ...EncodingOption) Segment
  • func (s Segment) Compare(o Segment) int
  • func (s Segment) Encoded() string
  • func (s Segment) Equal(o Segment) bool
  • func (s Segment) IsValid() bool
  • func (s Segment) Value() string
• type Segments
  • func Parse(path string) (Segments, error)
  • func (ss Segments) Compare(o Segments) int
  • func (ss Segments) Encode() string
  • func (ss Segments) Equal(o Segments) bool
  • func (ss Segments) First() Segment
  • func (ss Segments) FollowingSegments(n int) Segments
  • func (ss Segments) FollowingSegmentsWithCurrent(n int) Segments
  • func (ss Segments) Index(n int) Segment
  • func (ss Segments) Last() Segment
  • func (ss Segments) PrecedingSegments(n int) Segments
  • func (ss Segments) PrecedingSegmentsWithCurrent(n int) Segments

Variables

var ErrAccessToNonCompositeType = errors.New("connot descend into specified item; attempted to access a sub-value in an entity that is not an instance of a message, list or map")

ErrAccessToNonCompositeType error returned during child access attempt on non-composite value (value of type other then message, list or map).

var ErrMutationOfReadOnlyValue = errors.New("connot mutate read-only value")

ErrMutationOfReadOnlyValue error returned when accessing read-only child using mutable operation.

Functions

func Access

func Access(base proto.Message, path Segments) (any, error)

Access retrieves value specified by the given path segments from the provided base message. While accessing in may allocate missing messages as long as they are not part of oneof. When no path segments are provided function returns base message. If any of the values along the path do not exists or any accessed value is not a composite type (message, list or map) function return error.

func AccessMutable

func AccessMutable(base proto.Message, path Segments) (any, error)

AccessMutable retrieves value specified by the given path segments from the provided base message. While accessing it will create any missing message values, including the ones that are part of oneofs. When no path segments are provided function returns base message. If any of the values along the path do not exists or any accessed value is not a composite type (message, list or map) function return error.

func Get

func Get(base proto.Message, path Segments) (any, error)

Get retrieves value specified by the given path segments from the provided base message. When no path segments are provided function returns base message. If any of the values along the path do not exists function return error.

func JoinPaths

func JoinPaths(paths ...string) string

JoinPaths create a new encoded path by concatenating all provided paths.

func Mutable

func Mutable(base proto.Message, path Segments) (any, error)

Mutable retrieves value specified by the given path segments from the provided base message. It uses mutable access, creating any missing message values, including the ones that are part of oneofs. If any of the values along the path do not exists or the given message is read only function return error.

func NewErrInPath

func NewErrInPath(path string, err error) error

NewErrInPath function that can wrap into ErrInPath the provided error and the given path. If the provided error is ErrInPath it will join all paths together.

Types

type EncodingOption

type EncodingOption interface {
	// contains filtered or unexported methods
}

EncodingOption option that configures segments encoding.

func ForceSquareBracketsWrapping

func ForceSquareBracketsWrapping() EncodingOption

ForceSquareBracketsWrapping returns an encoding option forces usage of square brackets wrapping even if no wrapping or escaping is required.

This option is conflicting with PreferSquareBracketsWrapping. When it appears after this option will override it.

func PreferSquareBracketsWrapping

func PreferSquareBracketsWrapping() EncodingOption

PreferSquareBracketsWrapping returns an encoding option that triggers usage of square brackets wrapping while encoding when path segment value contains dot character. By default, without this option, characters escaping is always performed.

This option is conflicting with ForceSquareBracketsWrapping. When it appears after this option will override it.

type ErrInPath

type ErrInPath struct {
	Path  string // path under which error was encountered
	Cause error  // underlying error
}

ErrInPath wrapping error that adds information about path under which some error occurred.

func (*ErrInPath) Error

func (e *ErrInPath) Error() string

func (*ErrInPath) Unwrap

func (e *ErrInPath) Unwrap() error

type ErrInvalidSegment

type ErrInvalidSegment struct {
	Encoded string // encoded value of the segment
}

ErrInvalidSegment error indicating that some segment is invalid.

func (*ErrInvalidSegment) Error

func (e *ErrInvalidSegment) Error() string

type ErrNotFound

type ErrNotFound struct {
	Kind  string // kind of not found item ("field", "index" or "key")
	Value string // value that was not found
}

ErrNotFound error indicating that the given entity (message field, list index or map key) was not found.

func (*ErrNotFound) Error

func (e *ErrNotFound) Error() string

type Segment

type Segment struct {
	// contains filtered or unexported fields
}

Segment is a single fragment of the path.

func NewSegment

func NewSegment(value string, opts ...EncodingOption) Segment

NewSegment creates a new segment, by encoding the provided value. Newly created segments belong to a path made of a single segment - the newly created one. Returned segments are always valid - if the provided value contains a rune that is not properly UTF-8 encoded, is out of range, or is not the shortest possible UTF-8 encoding for that rune, the rune will be replaced by the Unicode replacement character. Otherwise, the segment decoded value will match the given value.

func (Segment) Compare

func (s Segment) Compare(o Segment) int

func (Segment) Encoded

func (s Segment) Encoded() string

Encoded returns encoded (marshaled) value of the segment (as is appears in proto path).

func (Segment) Equal

func (s Segment) Equal(o Segment) bool

func (Segment) IsValid

func (s Segment) IsValid() bool

IsValid informs if the segment is valid. Invalid segments have improperly encoded segment value, that cannot be decoded.

func (Segment) Value

func (s Segment) Value() string

Value returns decoded (unmarshaled) value of the segment (usable value).

type Segments

type Segments []Segment

Segments represents a parsed proto path value.

func Parse

func Parse(path string) (Segments, error)

Parse convert the given string path to slice of segments and validates all of them.

func (Segments) Compare

func (ss Segments) Compare(o Segments) int

func (Segments) Encode

func (ss Segments) Encode() string

Encode encodes slice of segments into string path.

func (Segments) Equal

func (ss Segments) Equal(o Segments) bool

func (Segments) First

func (ss Segments) First() Segment

First returns the first segment in path.

func (Segments) FollowingSegments

func (ss Segments) FollowingSegments(n int) Segments

FollowingSegments returns a slice of segments composed of the segments after a segment with the provided index.

func (Segments) FollowingSegmentsWithCurrent

func (ss Segments) FollowingSegmentsWithCurrent(n int) Segments

FollowingSegmentsWithCurrent returns a slice of segments that includes a segment with the provided index and all segments after it.

func (Segments) Index

func (ss Segments) Index(n int) Segment

Index returns the n'th segment in path. Negative indexes returns segments starting from the back.

func (Segments) Last

func (ss Segments) Last() Segment

Last returns the last segment in path.

func (Segments) PrecedingSegments

func (ss Segments) PrecedingSegments(n int) Segments

PrecedingSegments returns a slice of segments composed of the segments before a segment with the provided index.

func (Segments) PrecedingSegmentsWithCurrent

func (ss Segments) PrecedingSegmentsWithCurrent(n int) Segments

PrecedingSegmentsWithCurrent returns a slice of segments that includes a segment with the provided index and all segments before it.