aip160

Documentation

Overview

Package aip160 contains utilities used to comply with API Improvement Proposals (AIPs) from https://google.aip.dev/160. This includes an AIP-160 filter parser.

Index

• func NewLexer(input string) *filterLexer
• type Arg
  • func (v *Arg) String() string
• type Comparable
  • func (v *Comparable) String() string
• type Expression
  • func (v *Expression) String() string
• type Factor
  • func (v *Factor) String() string
• type Filter
  • func ParseFilter(filter string) (*Filter, error)
  • func (v *Filter) String() string
• type Member
  • func (v *Member) String() string
• type Restriction
  • func (v *Restriction) String() string
• type Sequence
  • func (v *Sequence) String() string
• type Simple
  • func (v *Simple) String() string
• type Term
  • func (v *Term) String() string

Functions

func NewLexer

func NewLexer(input string) *filterLexer

Types

type Arg

type Arg struct {
	Comparable *Comparable
	// Composite is a parenthesized expression, commonly used to group
	// terms or clarify operator precedence.
	//
	// Example: `(msg.endsWith('world') AND retries < 10)`
	Composite *Expression
}

func (*Arg) String

func (v *Arg) String() string

type Comparable

type Comparable struct {
	Member *Member
}

Comparable may either be a member or function. As functions are not currently supported, it is always a member.

func (*Comparable) String

func (v *Comparable) String() string

type Expression

type Expression struct {
	// Sequences are always joined by an AND operator
	Sequences []*Sequence
}

Expressions may either be a conjunction (AND) of sequences or a simple sequence.

Note, the AND is case-sensitive.

Example: `a b AND c AND d`

The expression `(a b) AND c AND d` is equivalent to the example.

func (*Expression) String

func (v *Expression) String() string

type Factor

type Factor struct {
	// Terms are always joined by an OR operator
	Terms []*Term
}

Factors may either be a disjunction (OR) of terms or a simple term.

Note, the OR is case-sensitive.

Example: `a < 10 OR a >= 100`

func (*Factor) String

func (v *Factor) String() string

type Filter

type Filter struct {
	Expression *Expression // Optional, may be nil.
}

Filter, possibly empty

func ParseFilter

func ParseFilter(filter string) (*Filter, error)

Parse an AIP-160 filter string into an AST.

func (*Filter) String

func (v *Filter) String() string

type Member

type Member struct {
	Value  string
	Fields []string
}

Member expressions are either value or DOT qualified field references.

Example: `expr.type_map.1.type`

func (*Member) String

func (v *Member) String() string

type Restriction

type Restriction struct {
	Comparable *Comparable
	// Comparators supported by list filters: <=, <. >=, >, !=, =, :
	Comparator string
	Arg        *Arg
}

Restrictions express a relationship between a comparable value and a single argument. When the restriction only specifies a comparable without an operator, this is a global restriction.

Note, restrictions are not whitespace sensitive.

Examples: * equality : `package=com.google` * inequality : `msg != 'hello'` * greater than : `1 > 0` * greater or equal : `2.5 >= 2.4` * less than : `yesterday < request.time` * less or equal : `experiment.rollout <= cohort(request.user)` * has : `map:key` * global : `prod`

In addition to the global, equality, and ordering operators, filters also support the has (`:`) operator. The has operator is unique in that it can test for presence or value based on the proto3 type of the `comparable` value. The has operator is useful for validating the structure and contents of complex values.

func (*Restriction) String

func (v *Restriction) String() string

type Sequence

type Sequence struct {
	// Factors are always joined by an (implicit) AND operator
	Factors []*Factor
}

Sequence is composed of one or more whitespace (WS) separated factors.

A sequence expresses a logical relationship between 'factors' where the ranking of a filter result may be scored according to the number factors that match and other such criteria as the proximity of factors to each other within a document.

When filters are used with exact match semantics rather than fuzzy match semantics, a sequence is equivalent to AND.

Example: `New York Giants OR Yankees`

The expression `New York (Giants OR Yankees)` is equivalent to the example.

func (*Sequence) String

func (v *Sequence) String() string

type Simple

type Simple struct {
	Restriction *Restriction
	// Composite is a parenthesized expression, commonly used to group
	// terms or clarify operator precedence.
	//
	// Example: `(msg.endsWith('world') AND retries < 10)`
	Composite *Expression
}

Simple expressions may either be a restriction or a nested (composite) expression.

func (*Simple) String

func (v *Simple) String() string

type Term

type Term struct {
	Negated bool
	Simple  *Simple
}

Terms may either be unary or simple expressions.

Unary expressions negate the simple expression, either mathematically `-` or logically `NOT`. The negation styles may be used interchangeably.

Note, the `NOT` is case-sensitive and must be followed by at least one whitespace (WS).

Examples: * logical not : `NOT (a OR b)` * alternative not : `-file:".java"` * negation : `-30`

func (*Term) String

func (v *Term) String() string