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

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    This section is empty.

    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