matcher

README

Supported Format

• string
• glob
• regexp
• simple patterns

Syntax

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

String matcher

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

Glob matcher

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

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/.

Simple patterns matcher

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/.

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 {
	// Perform match against given []byte
	Match(b []byte) bool
	// Perform 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 parse the given matchers in Includes and Excludes