ksql

README

ksql

Is a JSON data expression lexer, parser, cli and library.

Requirements

• Go 1.18+

How to install CLI

~ go install github.com/go-playground/ksql/cmd/ksql

Usage

package main

import (
	"fmt"

	"github.com/go-playground/ksql"
)

func main() {
	expression := []byte(`.properties.employees > 20`)
	input := []byte(`{"name":"MyCompany", "properties":{"employees": 50}`)
	ex, err := ksql.Parse(expression)
	if err != nil {
		panic(err)
	}

	result, err := ex.Calculate(input)
	if err != nil {
		panic(err)
	}
	fmt.Printf("%v\n", result)
}

CLI Usage

~ ksql '(.field1 + 1) /2' '{"field1": 1}'
or
echo '{"field1": 1}' | ksql '(.field1 + 1) /2'

Expressions

Expressions support most mathematical and string expressions see below for details:

Syntax & Rules

Token	Example	Syntax Rules
Equals	==	supports both == and =.
Add	+	N/A
Subtract	-	N/A
Multiply	*	N/A
Divide	/	N/A
Gt	>	N/A
Gte	>=	N/A
Lt	<	N/A
Lte	<=	N/A
OpenParen	(	N/A
CloseParen	)	N/A
OpenBracket	[	N/A
CloseBracket	]	N/A
Comma	,	N/A
QuotedString	"sample text"	Must start and end with an unescaped " character
Number	123.45	Must start and end with a space or '+' or '-' when hard coded value in expression and supports 0-9 +- e characters for numbers and exponent notation.
BooleanTrue	true	Accepts true as a boolean only.
BooleanFalse	false	Accepts false as a boolean only.
SelectorPath	.selector_path	Starts with a . and ends with whitespace blank space. This crate currently uses gjson and so the full gjson syntax for identifiers is supported.
And	&&	N/A
Not	!	Must be before Boolean identifier or expression or be followed by an operation
Or	||	N/A
Contains	CONTAINS	Ends with whitespace blank space.
ContainsAny	CONTAINS_ANY	Ends with whitespace blank space.
ContainsAll	CONTAINS_ALL	Ends with whitespace blank space.
In	IN	Ends with whitespace blank space.
Between	BETWEEN	Starts & ends with whitespace blank space. example 1 BETWEEN 0 10
StartsWith	STARTSWITH	Ends with whitespace blank space.
EndsWith	ENDSWITH	Ends with whitespace blank space.
NULL	NULL	N/A
Coerce	COERCE	Coerces one data type into another using in combination with 'Identifier'. Syntax is COERCE <expression> _identifer_.
Identifier	_identifier_	Starts and end with an _ used with 'COERCE' to cast data types. Currently the onyl supported Identifier is _datetime_.

#### License

<sup>
Licensed under either of <a href="LICENSE-APACHE">Apache License, Version
2.0</a> or <a href="LICENSE-MIT">MIT license</a> at your option.
</sup>

<br>

<sub>
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in Proteus by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.
</sub>

Documentation

Index

• Constants
• type ErrInvalidBool
  • func (e ErrInvalidBool) Error() string
• type ErrInvalidIdentifier
  • func (e ErrInvalidIdentifier) Error() string
• type ErrInvalidKeyword
  • func (e ErrInvalidKeyword) Error() string
• type ErrInvalidNumber
  • func (e ErrInvalidNumber) Error() string
• type ErrInvalidSelectorPath
  • func (e ErrInvalidSelectorPath) Error() string
• type ErrUnsupportedCharacter
  • func (e ErrUnsupportedCharacter) Error() string
• type ErrUnsupportedCoerce
  • func (e ErrUnsupportedCoerce) Error() string
• type ErrUnsupportedTypeComparison
  • func (e ErrUnsupportedTypeComparison) Error() string
• type ErrUnterminatedString
  • func (e ErrUnterminatedString) Error() string
• type Expression
  • func Parse(expression []byte) (Expression, error)
• type LexerResult
• type Token
• type TokenKind
• type Tokenizer
  • func NewTokenizer(src []byte) *Tokenizer
  • func (t *Tokenizer) Next() (token Token, err error)

Constants

const (
	SelectorPath = iota
	QuotedString
	Number
	BooleanTrue
	BooleanFalse
	Null
	Equals
	Add
	Subtract
	Multiply
	Divide
	Gt
	Gte
	Lt
	Lte
	And
	Or
	Not
	Contains
	ContainsAny
	ContainsAll
	In
	Between
	StartsWith
	EndsWith
	OpenBracket
	CloseBracket
	Comma
	OpenParen
	CloseParen
	Coerce
	Identifier
)

Types

type ErrInvalidBool

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

ErrInvalidBool represents an invalid boolean

func (ErrInvalidBool) Error

func (e ErrInvalidBool) Error() string

type ErrInvalidIdentifier

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

ErrInvalidIdentifier represents an invalid identifier

func (ErrInvalidIdentifier) Error

func (e ErrInvalidIdentifier) Error() string

type ErrInvalidKeyword

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

ErrInvalidKeyword represents an invalid keyword keyword

func (ErrInvalidKeyword) Error

func (e ErrInvalidKeyword) Error() string

type ErrInvalidNumber

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

ErrInvalidNumber represents an invalid number

func (ErrInvalidNumber) Error

func (e ErrInvalidNumber) Error() string

type ErrInvalidSelectorPath

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

ErrInvalidSelectorPath represents an invalid selector string

func (ErrInvalidSelectorPath) Error

func (e ErrInvalidSelectorPath) Error() string

type ErrUnsupportedCharacter

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

ErrUnsupportedCharacter represents an unsupported character is expression being lexed.

func (ErrUnsupportedCharacter) Error

func (e ErrUnsupportedCharacter) Error() string

type ErrUnsupportedCoerce

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

ErrUnsupportedCoerce represents a comparison of incompatible types type casts

func (ErrUnsupportedCoerce) Error

func (e ErrUnsupportedCoerce) Error() string

type ErrUnsupportedTypeComparison

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

ErrUnsupportedTypeComparison represents a comparison of incompatible types

func (ErrUnsupportedTypeComparison) Error

func (e ErrUnsupportedTypeComparison) Error() string

type ErrUnterminatedString

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

ErrUnterminatedString represents an unterminated string

func (ErrUnterminatedString) Error

func (e ErrUnterminatedString) Error() string

type Expression

type Expression interface {

	// Calculate will execute the parsed expression and apply it against the supplied data.
	//
	// # Errors
	//
	// Will return `Err` if the expression cannot be applied to the supplied data due to invalid
	// data type comparisons.
	Calculate(src []byte) (any, error)
}

func Parse

func Parse(expression []byte) (Expression, error)

Parse lex's' the provided expression and returns an Expression to be used/applied to data.

type LexerResult

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

LexerResult represents a token lexed result

type Token

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

Token represents a lexed token

type TokenKind

type TokenKind uint8

TokenKind is the type of token lexed.

type Tokenizer

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

Tokenizer is a lexer for the KSQL expression syntax.

func NewTokenizer

func NewTokenizer(src []byte) *Tokenizer

NewTokenizer creates a new tokenizer for use

func (*Tokenizer) Next

func (t *Tokenizer) Next() (token Token, err error)