aip

package
v0.0.0-...-a301a9c Latest Latest
Warning

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

 Go to latest Published: Jun 20, 2024 License: Apache-2.0 Imports: 8 Imported by: 0

Documentation

Overview

Package aip contains utilities used to comply with API Improvement Proposals (AIPs) from https://google.aip.dev/. This includes an AIP-160 filter parser and SQL generator and AIP-132 order by clause parser and SQL generator.

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

Index

Constants

This section is empty.

Variables

This section is empty.

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 Column 

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

Column represents the schema of a Database column.

type ColumnBuilder 

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

func NewColumn 

func NewColumn() *ColumnBuilder

NewColumn starts building a new column.

func (*ColumnBuilder) Bool 

func (c *ColumnBuilder) Bool() *ColumnBuilder

Bool specifies this column has bool type in the database.

func (*ColumnBuilder) Build 

func (c *ColumnBuilder) Build() *Column

Build returns the built column.

func (*ColumnBuilder) Filterable 

func (c *ColumnBuilder) Filterable() *ColumnBuilder

Filterable specifies this column can be filtered on.

func (*ColumnBuilder) FilterableImplicitly 

func (c *ColumnBuilder) FilterableImplicitly() *ColumnBuilder

FilterableImplicitly specifies this column can be filtered on implicitly. This means that AIP-160 filter expressions not referencing any particular field will try to search in this column.

func (*ColumnBuilder) KeyValue 

func (c *ColumnBuilder) KeyValue() *ColumnBuilder

KeyValue specifies this column is an array of structs with two string members: key and value. The key is exposed as a field on the column name, the value can be queried with :, = and != Example query: tag.key=value

func (*ColumnBuilder) Sortable 

func (c *ColumnBuilder) Sortable() *ColumnBuilder

Sortable specifies this column can be sorted on.

func (*ColumnBuilder) WithArgumentSubstitutor 

func (c *ColumnBuilder) WithArgumentSubstitutor(f func(sub string) string) *ColumnBuilder

WithArgumentSubstitutor specifies a substitution that should happen to the user-specified filter argument before it is matched against the database value. If this option is enabled, the filter operators permitted will be limited to = (equals) and != (not equals).

func (*ColumnBuilder) WithDatabaseName 

func (c *ColumnBuilder) WithDatabaseName(name string) *ColumnBuilder

WithDatabaseName specifies the database name of the column. Important: Only pass safe values (e.g. compile-time constants) to this field. User input MUST NOT flow to this field, as it will be used directly in SQL statements and would allow the user to perform SQL injection attacks.

func (*ColumnBuilder) WithFieldPath 

func (c *ColumnBuilder) WithFieldPath(segments ...string) *ColumnBuilder

WithFieldPath specifies the field path the column maps to in the returned resource. Field paths are described in AIP-161.

For convenience, the field path is described here as a set of segments where each segment is joined by the traversal operator (.). E.g. the field path "metrics.`some-metric`.value" would be specified as ["metrics", "some-metric", "value"].

type ColumnType 

type ColumnType int32

ColumnType is an enum for the type of a column. Valid values are in the const block above. 

const (
	// ColumnTypeString is a column of type string.
	ColumnTypeString ColumnType = iota
	// ColumnTypeBool is a column of type boolean.  NULL values are mapped to FALSE.
	ColumnTypeBool = iota
)

func (ColumnType) String 

func (t ColumnType) 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 FieldPath 

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

FieldPath represents the path to a field in a message.

For example, for the given message: 

message MyThing {
   message Bar {
       string foobar = 2;
   }
   string foo = 1;
   Bar bar = 2;
   map<string, Bar> named_bars = 3;
}

Some valid paths would be: foo, bar.foobar and named_bars.`bar-key`.foobar.

func NewFieldPath 

func NewFieldPath(segments ...string) FieldPath

NewFieldPath initialises a new field path with the given segments.

func (FieldPath) Equals 

func (f FieldPath) Equals(other FieldPath) bool

Equals returns iff two field paths refer to exactly the same field.

func (FieldPath) String 

func (f FieldPath) String() string

String returns a canoncial representation of the field path, following AIP-132 / AIP-161 syntax.

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 OrderBy 

type OrderBy struct {
	// The field path. This is the path of the field in the
	// resource message that the AIP-132 List RPC is listing.
	FieldPath FieldPath
	// Whether the field should be sorted in descending order.
	Descending bool
}

OrderBy represents a part of an AIP-132 order_by clause.

func MergeWithDefaultOrder 

func MergeWithDefaultOrder(defaultOrder []OrderBy, order []OrderBy) []OrderBy

MergeWithDefaultOrder merges the specified order with the given defaultOrder. The merge occurs as follows:

  • Ordering specified in `order` takes precedence.
  • For columns not specified in the `order` that appear in `defaultOrder`, ordering is applied in the order they apply in defaultOrder.

func ParseOrderBy 

func ParseOrderBy(text string) ([]OrderBy, error)

ParseOrderBy parses an AIP-132 order_by list. The method validates the syntax is correct and each identifier appears at most once, but it does not validate the identifiers themselves are valid.

type QueryParameter 

type QueryParameter struct {
	Name  string
	Value string
}

QueryParameter represents a query parameter.

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 Table 

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

Table represents the schema of a Database table, view or query.

func (*Table) FilterableColumnByFieldPath 

func (t *Table) FilterableColumnByFieldPath(path FieldPath) (*Column, error)

FilterableColumnByFieldPath returns the database name of the filterable column with the given field path.

func (*Table) OrderByClause 

func (t *Table) OrderByClause(order []OrderBy) (string, error)

OrderByClause returns a Standard SQL Order by clause, including "ORDER BY" and trailing new line (if an order is specified). If no order is specified, returns "".

The returned order clause is safe against SQL injection; only strings appearing from Table appear in the output.

func (*Table) SortableColumnByFieldPath 

func (t *Table) SortableColumnByFieldPath(path FieldPath) (*Column, error)

SortableColumnByFieldPath returns the sortable database column with the given externally-visible field path.

func (*Table) WhereClause 

func (t *Table) WhereClause(filter *Filter, parameterPrefix string) (string, []QueryParameter, error)

WhereClause creates a Standard SQL WHERE clause fragment for the given filter.

The fragment will be enclosed in parentheses and does not include the "WHERE" keyword. For example: (column LIKE @param1) Also returns the query parameters which need to be given to the database.

All field names are replaced with the safe database column names from the specified table. All user input strings are passed via query parameters, so the returned query is SQL injection safe.

type TableBuilder 

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

func NewTable 

func NewTable() *TableBuilder

NewTable starts building a new table.

func (*TableBuilder) Build 

func (t *TableBuilder) Build() *Table

Build returns the built table.

func (*TableBuilder) WithColumns 

func (t *TableBuilder) WithColumns(columns ...*Column) *TableBuilder

WithColumns specifies the columns in the table.

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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.