filters

Documentation

Overview

Package filters defines a syntax and parser that can be used for the filtration of items across the containerd API. The core is built on the concept of protobuf field paths, with quoting. Several operators allow the user to flexibly select items based on field presence, equality, inequality and regular expressions. Flexible adaptors support working with any type.

The syntax is fairly familiar, if you've used container ecosystem projects. At the core, we base it on the concept of protobuf field paths, augmenting with the ability to quote portions of the field path to match arbitrary labels. These "selectors" come in the following syntax:

``` <fieldpath>[<operator><value>] ```

A basic example is as follows:

``` name==foo ```

This would match all objects that have a field `name` with the value `foo`. If we only want to test if the field is present, we can omit the operator. This is most useful for matching labels in containerd. The following will match objects that have the field "labels" and have the label "foo" defined:

``` labels.foo ```

We also allow for quoting of parts of the field path to allow matching of arbitrary items:

``` labels."very complex label"==something ```

We also define `!=` and `~=` as operators. The `!=` will match all objects that don't match the value for a field and `~=` will compile the target value as a regular expression and match the field value against that.

Selectors can be combined using a comma, such that the resulting selector will require all selectors are matched for the object to match. The following example will match objects that are named `foo` and have the label `bar`:

``` name==foo,labels.bar ```

Index

• type AdapterFunc
  • func (fn AdapterFunc) Field(fieldpath []string) (string, bool)
• type Adaptor
• type All
  • func (m All) Match(adaptor Adaptor) bool
• type Any
  • func (m Any) Match(adaptor Adaptor) bool
• type Filter
  • func Parse(s string) (Filter, error)
  • func ParseAll(ss ...string) (Filter, error)
• type FilterFunc
  • func (fn FilterFunc) Match(adaptor Adaptor) bool

Types

type AdapterFunc

type AdapterFunc func(fieldpath []string) (string, bool)

AdapterFunc allows implementation specific matching of fieldpaths

func (AdapterFunc) Field

func (fn AdapterFunc) Field(fieldpath []string) (string, bool)

Field returns the field name and true if it exists

type Adaptor

type Adaptor interface {
	Field(fieldpath []string) (value string, present bool)
}

Adaptor specifies the mapping of fieldpaths to a type. For the given field path, the value and whether it is present should be returned. The mapping of the fieldpath to a field is deferred to the adaptor implementation, but should generally follow protobuf field path/mask semantics.

type All

type All []Filter

All allows multiple filters to be matched against the object

func (All) Match

func (m All) Match(adaptor Adaptor) bool

Match only returns true if all filters match the object

type Any

type Any []Filter

Any allows multiple filters to be matched against the object

func (Any) Match

func (m Any) Match(adaptor Adaptor) bool

Match returns true if any of the provided filters are true

type Filter

type Filter interface {
	Match(adaptor Adaptor) bool
}

Filter matches specific resources based the provided filter

func Parse

func Parse(s string) (Filter, error)

Parse the strings into a filter that may be used with an adaptor.

The filter is made up of zero or more selectors.

The format is a comma separated list of expressions, in the form of `<fieldpath><op><value>`, known as selectors. All selectors must match the target object for the filter to be true.

We define the operators "==" for equality, "!=" for not equal and "~=" for a regular expression. If the operator and value are not present, the matcher will test for the presence of a value, as defined by the target object.

The formal grammar is as follows:

selectors := selector ("," selector)* selector := fieldpath (operator value) fieldpath := field ('.' field)* field := quoted | [A-Za-z] [A-Za-z0-9_]+ operator := "==" | "!=" | "~=" value := quoted | [^\s,]+ quoted := <go string syntax>

func ParseAll

func ParseAll(ss ...string) (Filter, error)

ParseAll parses each filter in ss and returns a filter that will return true if any filter matches the expression.

If no filters are provided, the filter will match anything.

type FilterFunc

type FilterFunc func(Adaptor) bool

FilterFunc is a function that handles matching with an adaptor

var Always FilterFunc = func(adaptor Adaptor) bool {
	return true
}

Always is a filter that always returns true for any type of object

func (FilterFunc) Match

func (fn FilterFunc) Match(adaptor Adaptor) bool

Match matches the FilterFunc returning true if the object matches the filter