syntax

Documentation

Overview

Package syntax defines a scanner and parser for the CometBFT event filter query language. A query selects events by their types and attribute values.

Grammar

The grammar of the query language is defined by the following EBNF:

query      = conditions EOF
conditions = condition {"AND" condition}
condition  = tag comparison
comparison = equal / order / contains / "EXISTS"
equal      = "=" (date / number / time / value)
order      = cmp (date / number / time)
contains   = "CONTAINS" value
cmp        = "<" / "<=" / ">" / ">="

The lexical terms are defined here using RE2 regular expression notation:

// The name of an event attribute (type.value)
tag    = #'\w+(\.\w+)*'

// A datestamp (YYYY-MM-DD)
date   = #'DATE \d{4}-\d{2}-\d{2}'

// A number with optional fractional parts (0, 10, 3.25)
number = #'\d+(\.\d+)?'

// An RFC3339 timestamp (2021-11-23T22:04:19-09:00)
time   = #'TIME \d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}([-+]\d{2}:\d{2}|Z)'

// A quoted literal string value ('a b c')
value  = #'\'[^\']*\''

Index

• Constants
• func ParseDate(s string) (time.Time, error)
• func ParseTime(s string) (time.Time, error)
• type Arg
  • func (a *Arg) Number() *big.Float
  • func (a *Arg) String() string
  • func (a *Arg) Time() time.Time
  • func (a *Arg) Value() string
• type Condition
  • func (c Condition) String() string
• type Parser
  • func NewParser(r io.Reader) *Parser
  • func (p *Parser) Parse() (Query, error)
• type Query
  • func Parse(s string) (Query, error)
  • func (q Query) String() string
• type Scanner
  • func NewScanner(r io.Reader) *Scanner
  • func (s *Scanner) Err() error
  • func (s *Scanner) Next() error
  • func (s *Scanner) Pos() int
  • func (s *Scanner) Text() string
  • func (s *Scanner) Token() Token
• type Token
  • func (t Token) String() string

Constants

const (
	TInvalid  = iota // invalid or unknown token
	TTag             // field tag: x.y
	TString          // string value: 'foo bar'
	TNumber          // number: 0, 15.5, 100
	TTime            // timestamp: TIME yyyy-mm-ddThh:mm:ss([-+]hh:mm|Z)
	TDate            // datestamp: DATE yyyy-mm-dd
	TAnd             // operator: AND
	TContains        // operator: CONTAINS
	TExists          // operator: EXISTS
	TEq              // operator: =
	TLt              // operator: <
	TLeq             // operator: <=
	TGt              // operator: >
	TGeq             // operator: >=

)

const (
	// TimeFormat is the format string used for timestamp values.
	TimeFormat = time.RFC3339

	// DateFormat is the format string used for datestamp values.
	DateFormat = "2006-01-02"
)

Functions

func ParseDate

func ParseDate(s string) (time.Time, error)

ParseDate parses s as a date string in the format used by DATE values.

func ParseTime

func ParseTime(s string) (time.Time, error)

ParseTime parses s as a timestamp in the format used by TIME values.

Types

type Arg

type Arg struct {
	Type Token
	// contains filtered or unexported fields
}

An Arg is the argument of a comparison operator.

func (*Arg) Number

func (a *Arg) Number() *big.Float

Number returns the value of the argument text as a number, or nil if the text does not encode a valid number value.

func (*Arg) String

func (a *Arg) String() string

func (*Arg) Time

func (a *Arg) Time() time.Time

Time returns the value of the argument text as a time, or the zero value if the text does not encode a timestamp or datestamp.

func (*Arg) Value

func (a *Arg) Value() string

Value returns the value of the argument text as a string, or "".

type Condition

type Condition struct {
	Tag string
	Op  Token
	Arg *Arg
	// contains filtered or unexported fields
}

A Condition is a single conditional expression, consisting of a tag, a comparison operator, and an optional argument. The type of the argument depends on the operator.

func (Condition) String

func (c Condition) String() string

type Parser

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

Parser is a query expression parser. The grammar for query expressions is defined in the syntax package documentation.

func NewParser

func NewParser(r io.Reader) *Parser

NewParser constructs a new parser that reads the input from r.

func (*Parser) Parse

func (p *Parser) Parse() (Query, error)

Parse parses the complete input and returns the resulting query.

type Query

type Query []Condition

Query is the root of the parse tree for a query. A query is the conjunction of one or more conditions.

func Parse

func Parse(s string) (Query, error)

Parse parses the specified query string. It is shorthand for constructing a parser for s and calling its Parse method.

func (Query) String

func (q Query) String() string

type Scanner

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

Scanner reads lexical tokens of the query language from an input stream. Each call to Next advances the scanner to the next token, or reports an error.

func NewScanner

func NewScanner(r io.Reader) *Scanner

NewScanner constructs a new scanner that reads from r.

func (*Scanner) Err

func (s *Scanner) Err() error

Err returns the last error reported by Next, if any.

func (*Scanner) Next

func (s *Scanner) Next() error

Next advances s to the next token in the input, or reports an error. At the end of input, Next returns io.EOF.

func (*Scanner) Pos

func (s *Scanner) Pos() int

Pos returns the start offset of the current token in the input.

func (*Scanner) Text

func (s *Scanner) Text() string

Text returns the text of the current input token.

func (*Scanner) Token

func (s *Scanner) Token() Token

Token returns the type of the current input token.

type Token

type Token byte

Token is the type of a lexical token in the query grammar.

func (Token) String

func (t Token) String() string