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 valid 0-9 digit.
Boolen	true	Accepts true or false as a boolean only.
Identifier	.identifier	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.
In	IN	Ends with whitespace blank space.
StartsWith	STARTSWITH	Ends with whitespace blank space.
EndsWith	ENDSWITH	Ends with whitespace blank space.
NULL	NULL	N/A

#### 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 ErrUnsupportedCharacter
  • func (e ErrUnsupportedCharacter) 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
  • func Tokenize(src []byte) (tokens []Token, err error)
• type TokenKind
• type Tokenizer

Constants

const (
	Identifier = iota
	String
	Number
	Boolean
	Null
	Equals
	Add
	Subtract
	Multiply
	Divide
	Gt
	Gte
	Lt
	Lte
	And
	Or
	Not
	Contains
	In
	StartsWith
	EndsWith
	OpenBracket
	CloseBracket
	Comma
	OpenParen
	CloseParen
)

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 string

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 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 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 with value

func Tokenize

func Tokenize(src []byte) (tokens []Token, err error)

Tokenize tokenizes the input and returns tokens or error lexing them.

type TokenKind

type TokenKind uint8

TokenKind is the type of token lexed.

type Tokenizer

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