luci: Index | Files

package mask

import ""

Package mask provides utility functions for google protobuf field mask

Supports 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: "" means field "name" of field "publisher"
  - String map keys: "metadata.year" means string key 'year' of map field
  - 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
- 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:

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 = '*'


Package Files

mask.go parse.go

type Inclusiveness Uses

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.
    // IncludeEntirely indicates the entire field value is included.

type Mask Uses

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 "". A Field Mask with paths ["a","b.c"] is parsed as

  /    \
"a"    "b"

Zero value is not valid. Use IsEmpty() to check if the mask is zero.

func All Uses

func All(targetMsg proto.Message) Mask

All returns a field mask that selects all fields.

func FromFieldMask Uses

func FromFieldMask(fieldMask *field_mask.FieldMask, targetMsg proto.Message, isFieldNameJSON bool, isUpdateMask bool) (Mask, error)

FromFieldMask parses a field mask to a mask.

Trailing stars will be removed, e.g. parses ['a.*'] as ['a']. Redundant paths will be removed, e.g. parses ['a', 'a.b'] as ['a'].

If isFieldNameJSON is set to true, json name will be used instead of canonical name defined in proto during parsing (e.g. "fooBar" instead of "foo_bar"). However, the child field name in return mask will always be in canonical form.

If isUpdateMask is set to true, a repeated field is allowed only as the last field in a path string.

func MustFromReadMask Uses

func MustFromReadMask(targetMsg proto.Message, paths ...string) Mask

MustFromReadMask is a shortcut FromFieldMask with isFieldNameJSON and isUpdateMask as false, that accepts field mask a variadic paths and that panics if the mask is invalid. It is useful when the mask is hardcoded.

func (Mask) Includes Uses

func (m Mask) Includes(path string) (Inclusiveness, error)

Includes tells the Inclusiveness of a field value at the given path.

The path must have canonical field names, i.e. not JSON names. Returns error if path parsing fails.

func (Mask) IsEmpty Uses

func (m Mask) IsEmpty() bool

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 Uses

func (m Mask) Merge(src, dest proto.Message) error

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) Submask Uses

func (m Mask) Submask(path string) (Mask, error)

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.

func (Mask) Trim Uses

func (m Mask) Trim(msg proto.Message) error

Trim clears protobuf message fields that are not in the mask.

If mask is empty, this is a noop. It returns error when the supplied message is nil or has a different message descriptor from that of mask. It uses Includes to decide what to trim, see its doc.

Package mask imports 9 packages (graph) and is imported by 4 packages. Updated 2020-10-01. Refresh now. Tools for package owners.