Documentation
¶
Overview ¶
Package mask provides utility functions for google protobuf field masks.
Index ¶
- type Inclusiveness
- type Mask
- func (m *Mask) Children() map[string]*Mask
- func (m *Mask) Includes(path string) (Inclusiveness, error)
- func (m *Mask) IsEmpty() bool
- func (m *Mask) Merge(src, dest proto.Message) error
- func (m *Mask) MustIncludes(path string) Inclusiveness
- func (m *Mask) MustSubmask(path string) *Mask
- func (m *Mask) Submask(path string) (*Mask, error)
- func (m *Mask) Trim(msg proto.Message) error
- type Option
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Inclusiveness ¶
type Inclusiveness int8
Inclusiveness tells if a field value at the given path is included.
const ( // Exclude indicates the field value is excluded. Exclude Inclusiveness = iota // IncludePartially indicates some subfields of the field value are included. IncludePartially // IncludeEntirely indicates the entire field value is included. IncludeEntirely )
type Mask ¶
type Mask struct {
// contains filtered or unexported fields
}
Mask is a tree representation of a field Mask. Serves as a tree node too. Each node represents a segment of a path, e.g. "bar" in "foo.bar.qux". A Field Mask with paths ["a","b.c"] is parsed as
<root>
/ \
"a" "b"
/
"c"
Zero value is not valid. Use IsEmpty() to check if the mask is zero.
func FromFieldMask ¶
func FromFieldMask(fieldMask *fieldmaskpb.FieldMask, targetMsg proto.Message, opts ...Option) (*Mask, error)
FromFieldMask parses a field mask, matching it to the given proto message descriptor.
targetMsg is only used for its type. Use Trim to actually apply a mask to a proto message.
func MustFromReadMask ¶
MustFromReadMask is a shortcut FromFieldMask that accepts field mask as variadic paths and that panics if the mask is invalid.
It is useful when the mask is hardcoded. Understands advanced semantics.
func (*Mask) Includes ¶
func (m *Mask) Includes(path string) (Inclusiveness, error)
Includes tells the Inclusiveness of a field value at the given path.
Returns error if path parsing fails.
func (*Mask) IsEmpty ¶
IsEmpty reports whether a mask is of empty value. Such mask implies keeping everything when calling Trim, merging nothing when calling Merge and always returning IncludeEntirely when calling Includes
func (*Mask) Merge ¶
Merge merges masked fields from src to dest.
If mask is empty, this is a noop. It returns error when one of src or dest message is nil or has different message descriptor from that of mask. Empty field will be merged as long as they are present in the mask. Repeated fields or map fields will be overwritten entirely. Partial updates are not supported for such field.
func (*Mask) MustIncludes ¶
func (m *Mask) MustIncludes(path string) Inclusiveness
MustIncludes tells the Inclusiveness of a field value at the given path.
This is essentially the same as Includes, but panics if the given path is invalid.
func (*Mask) MustSubmask ¶
MustSubmask returns a sub-mask given a path from the received mask to it.
This is essentially the same as Submask, but panics if the given path is invalid or exlcuded from the received mask.
func (*Mask) Submask ¶
Submask returns a sub-mask given a path from the received mask to it.
For example, for a mask ["a.b.c"], m.submask("a.b") will return a mask ["c"].
If the received mask includes the path entirely, returns a Mask that includes everything. For example, for mask ["a"], m.submask("a.b") returns a mask without children.
Returns error if path parsing fails or path is excluded from the received mask.
type Option ¶
type Option interface {
// contains filtered or unexported methods
}
Option is implemented by options that can be passed to FromFieldMask.
func AdvancedSemantics ¶
func AdvancedSemantics() Option
AdvancedSemantics enables non-standard field mask semantics.
WARNING: advanced field masks never became standard and FieldMask messages that contain `*` or other non-standard syntax are not supported by Go's jsonpb decoder (it fails to unmarshal them). Using them requires hacks, such as go.chromium.org/luci/common/proto.UnmarshalJSONWithNonStandardFieldMasks.
Advanced field mask semantics:
- Refer to fields and map keys using . literals:
- Supported map key types: string, integer, bool. (double, float, enum, and bytes keys are not supported by protobuf or this implementation)
- Fields: "publisher.name" means field "name" of field "publisher"
- String map keys: "metadata.year" means string key 'year' of map field metadata
- Integer map keys (e.g. int32): 'year_ratings.0' means integer key 0 of a map field year_ratings
- Bool map keys: 'access_text.true' means boolean key true of a map field access_text
- String map keys that cannot be represented as an unquoted string literal, must be quoted using backticks: metadata.`year.published`, metadata.`17`, metadata.“. Backtick can be escaped with “: a.`b“c` means map key "b`c" of map field a.
- Refer to all map keys using a * literal: "topics.*.archived" means field "archived" of all map values of map field "topic".
- Refer to all elements of a repeated field using a * literal: authors.*.name
- Refer to all fields of a message using * literal: publisher.*.
- Prohibit addressing a single element in repeated fields: authors.0.name
Advanced FieldMask.paths string grammar:
path = segment {'.' segment}
segment = literal | star | quoted_string;
literal = string | integer | boolean
string = (letter | '_') {letter | '_' | digit}
integer = ['-'] digit {digit};
boolean = 'true' | 'false';
quoted_string = '`' { utf8-no-backtick | '``' } '`'
star = '*'
Source Files