matcher

README

Supported Format

• string
• glob
• regexp
• simple patterns

Depending on the symbol at the start of the string, the matcher will use one of the supported formats.

matcher	short format	long format
string	=	string
glob	*	glob
regexp	~	regexp
simple patterns		simple_patterns

Example:

• * pattern: It will use the glob matcher to find the pattern in the string.

Syntax

Tip: Read ::= as is defined as.

Short Syntax
     [ <not> ] <format> <space> <expr>
     
     <not>       ::= '!'
                       negative expression
     <format>    ::= [ '=', '~', '*' ]
                       '=' means string match
                       '~' means regexp match
                       '*' means glob match
     <space>     ::= { ' ' | '\t' | '\n' | '\n' | '\r' }
     <expr>      ::= any string

 Long Syntax
     [ <not> ] <format> <separator> <expr>
     
     <format>    ::= [ 'string' | 'glob' | 'regexp' | 'simple_patterns' ]
     <not>       ::= '!'
                       negative expression
     <separator> ::= ':'
     <expr>      ::= any string

When using the short syntax, you can enable the glob format by starting the string with a *, while in the long syntax you need to define it more explicitly. The following examples are identical. simple_patterns can be used only with the long syntax.

Examples:

• Short Syntax: '* * '
• Long Syntax: 'glob:*'

String matcher

The string matcher reports whether the given value equals to the string.

Examples:

• '= foo' matches only if the string is foo.
• '!= bar' matches any string that is not bar.

String matcher means exact match of the string. There are other string match related cases:

• string has prefix something
• string has suffix something
• string contains something

This is achievable using the glob matcher:

• * PREFIX*, means that it matches with any string that starts with PREFIX, e.g PREFIXnetdata
• * *SUFFIX, means that it matches with any string that ends with SUFFIX, e.g netdataSUFFIX
• * *SUBSTRING*, means that it matches with any string that contains SUBSTRING, e.g netdataSUBSTRINGnetdata

Glob matcher

The glob matcher reports whether the given value matches the wildcard pattern. It uses the standard golang library path. You can read more about the library in the golang documentation, where you can also practice with the library in order to learn the syntax and use it in your Netdata configuration.

The pattern syntax is:

    pattern:
        { term }
    term:
        '*'         matches any sequence of characters
        '?'         matches any single character
        '[' [ '^' ] { character-range } ']'
        character class (must be non-empty)
        c           matches character c (c != '*', '?', '\\', '[')
        '\\' c      matches character c

    character-range:
        c           matches character c (c != '\\', '-', ']')
        '\\' c      matches character c
        lo '-' hi   matches character c for lo <= c <= hi

Examples:

• * ? matches any string that is a single character.
• '?a' matches any 2 character string that starts with any character and the second character is a, like ba but not bb or bba.
• '[^abc]' matches any character that is NOT a,b,c. '[abc]' matches only a, b, c.
• '*[a-d]' matches any string (*) that ends with a character that is between a and d (i.e a,b,c,d).

Regexp matcher

The regexp matcher reports whether the given value matches the RegExp pattern ( use regexp.Match ).

The RegExp syntax is described at https://golang.org/pkg/regexp/syntax/.

Learn more about regular expressions at RegexOne.

Simple patterns matcher

The simple patterns matcher reports whether the given value matches the simple patterns.

Simple patterns are a space separated list of words. Each word may use any number of wildcards *. Simple patterns allow negative matches by prefixing a word with !.

Examples:

• !*bad* * matches anything, except all those that contain the word bad.
• *foobar* !foo* !*bar * matches everything containing foobar, except strings that start with foo or end with bar.

Documentation

Overview

Package matcher implements vary formats of string matcher.

Supported Format

string
glob
regexp
simple patterns

The string matcher reports whether the given value equals to the string ( use == ).

The glob matcher reports whether the given value matches the wildcard pattern. The pattern syntax is:

pattern:
    { term }
term:
    '*'         matches any sequence of characters
    '?'         matches any single character
    '[' [ '^' ] { character-range } ']'
    character class (must be non-empty)
    c           matches character c (c != '*', '?', '\\', '[')
    '\\' c      matches character c

character-range:
    c           matches character c (c != '\\', '-', ']')
    '\\' c      matches character c
    lo '-' hi   matches character c for lo <= c <= hi

The regexp matcher reports whether the given value matches the RegExp pattern ( use regexp.Match ). The RegExp syntax is described at https://golang.org/pkg/regexp/syntax/.

The simple patterns matcher reports whether the given value matches the simple patterns. The simple patterns is a custom format used in netdata, it's syntax is described at https://docs.netdata.cloud/libnetdata/simple_pattern/.

Index

• Variables
• type Expr
• type Format
• type Matcher
  • func And(lhs, rhs Matcher, others ...Matcher) Matcher
  • func FALSE() Matcher
  • func Must(m Matcher, err error) Matcher
  • func New(format Format, expr string) (Matcher, error)
  • func NewGlobMatcher(expr string) (Matcher, error)
  • func NewRegExpMatcher(expr string) (Matcher, error)
  • func NewSimplePatternsMatcher(expr string) (Matcher, error)
  • func NewStringMatcher(s string, startWith, endWith bool) (Matcher, error)
  • func Not(m Matcher) Matcher
  • func Or(lhs, rhs Matcher, others ...Matcher) Matcher
  • func Parse(line string) (Matcher, error)
  • func TRUE() Matcher
  • func WithCache(m Matcher) Matcher
• type SimpleExpr
  • func (s *SimpleExpr) Empty() bool
  • func (s *SimpleExpr) Parse() (Matcher, error)

Examples

• New (Glob_format)
• New (Regexp_format)
• New (Simple_patterns_format)
• New (String_format)

Variables

var (
	ErrEmptyExpr = errors.New("empty expression")
)

Types

type Expr

type Expr interface {
	Parse() (Matcher, error)
}

type Format

type Format string

Format matcher format

const (
	// FmtString is a string match format.
	FmtString Format = "string"
	// FmtGlob is a glob match format.
	FmtGlob Format = "glob"
	// FmtRegExp is a regex match format.
	FmtRegExp Format = "regexp"
	// FmtSimplePattern is a simple pattern match format
	// https://docs.netdata.cloud/libnetdata/simple_pattern/
	FmtSimplePattern Format = "simple_patterns"

	// Separator is a separator between match format and expression.
	Separator = ":"
)

type Matcher

type Matcher interface {
	// Match performs match against given []byte
	Match(b []byte) bool
	// MatchString performs match against given string
	MatchString(string) bool
}

Matcher is an interface that wraps MatchString method.

func And

func And(lhs, rhs Matcher, others ...Matcher) Matcher

And returns a matcher which returns true only if all of it's sub-matcher return true

func FALSE

func FALSE() Matcher

FALSE returns a matcher which always returns false

func Must

func Must(m Matcher, err error) Matcher

Must is a helper that wraps a call to a function returning (Matcher, error) and panics if the error is non-nil. It is intended for use in variable initializations such as

var m = matcher.Must(matcher.New(matcher.FmtString, "hello world"))

func New

func New(format Format, expr string) (Matcher, error)

New create a matcher

Example (Glob_format)

package main

import (
	"github.com/netdata/go.d.plugin/pkg/matcher"
)

func main() {
	// create a glob matcher, which perform wildcard match
	m, err := matcher.New(matcher.FmtString, "hello*")
	if err != nil {
		panic(err)
	}
	m.MatchString("hello")       // => true
	m.MatchString("hello world") // => true
	m.MatchString("Hello world") // => false
}

Example (Regexp_format)

package main

import (
	"github.com/netdata/go.d.plugin/pkg/matcher"
)

func main() {
	// create a regexp matcher, which perform wildcard match
	m, err := matcher.New(matcher.FmtRegExp, "[0-9]+")
	if err != nil {
		panic(err)
	}
	m.MatchString("1")  // => true
	m.MatchString("1a") // => true
	m.MatchString("a")  // => false
}

Example (Simple_patterns_format)

package main

import (
	"github.com/netdata/go.d.plugin/pkg/matcher"
)

func main() {
	// create a simple patterns matcher, which perform wildcard match
	m, err := matcher.New(matcher.FmtSimplePattern, "hello* !*world *")
	if err != nil {
		panic(err)
	}
	m.MatchString("hello")        // => true
	m.MatchString("hello world")  // => true
	m.MatchString("Hello world")  // => false
	m.MatchString("Hello world!") // => false
}

Example (String_format)

package main

import (
	"github.com/netdata/go.d.plugin/pkg/matcher"
)

func main() {
	// create a string matcher, which perform full text match
	m, err := matcher.New(matcher.FmtString, "hello")
	if err != nil {
		panic(err)
	}
	m.MatchString("hello")       // => true
	m.MatchString("hello world") // => false
}

func NewGlobMatcher

func NewGlobMatcher(expr string) (Matcher, error)

NewGlobMatcher create a new matcher with glob format

func NewRegExpMatcher

func NewRegExpMatcher(expr string) (Matcher, error)

NewRegExpMatcher create new matcher with RegExp format

func NewSimplePatternsMatcher

func NewSimplePatternsMatcher(expr string) (Matcher, error)

NewSimplePatternsMatcher creates new simple patterns. It returns error in case one of patterns has bad syntax.

func NewStringMatcher

func NewStringMatcher(s string, startWith, endWith bool) (Matcher, error)

NewStringMatcher create a new matcher with string format

func Not

func Not(m Matcher) Matcher

Not returns a matcher which positive the sub-matcher's result

func Or

func Or(lhs, rhs Matcher, others ...Matcher) Matcher

Or returns a matcher which returns true if any of it's sub-matcher return true

func Parse

func Parse(line string) (Matcher, error)

Parse parses line and returns appropriate matcher based on matched format.

Short Syntax

<line>      ::= [ <not> ] <format> <space> <expr>
<not>       ::= '!'
                  negative expression
<format>    ::= [ '=', '~', '*' ]
                  '=' means string match
                  '~' means regexp match
                  '*' means glob match
<space>     ::= { ' ' | '\t' | '\n' | '\n' | '\r' }
<expr>      ::= any string

Long Syntax

<line>      ::= [ <not> ] <format> <separator> <expr>
<format>    ::= [ 'string' | 'glob' | 'regexp' | 'simple_patterns' ]
<not>       ::= '!'
                  negative expression
<separator> ::= ':'
<expr>      ::= any string

func TRUE

func TRUE() Matcher

TRUE returns a matcher which always returns true

func WithCache

func WithCache(m Matcher) Matcher

WithCache adds cache to the matcher.

type SimpleExpr

type SimpleExpr struct {
	Includes []string `yaml:"includes" json:"includes"`
	Excludes []string `yaml:"excludes" json:"excludes"`
}

SimpleExpr is a simple expression to describe the condition:

(includes[0].Match(v) || includes[1].Match(v) || ...) && !(excludes[0].Match(v) || excludes[1].Match(v) || ...)

func (*SimpleExpr) Empty

func (s *SimpleExpr) Empty() bool

Empty returns true if both Includes and Excludes are empty. You can't

func (*SimpleExpr) Parse

func (s *SimpleExpr) Parse() (Matcher, error)

Parse parses the given matchers in Includes and Excludes