fix: do not fail with empty inputs (#7)

Author: manuelarte

README.md

@@ -11,7 +11,7 @@ A powerful `filter` query parameter implementation based on [RFC 8040][rfc8040]
 > [!NOTE]  
 > This repository only contains the lexer-parser.
 >
-> To check the current data-layer implementations check [Implementation](#-implementation).
+> To check the current data-layer implementations, check [Implementations](#-implementations).
 
 ## 🚀 Features
 
@@ -53,10 +53,21 @@ Then it's expected to filter the following conditions:
 | `age gt 18 and age lt 65` |    ✅    |    ❌    |    ❌     |   ✅    |
 | `age le 18 or age gt 65`  |    ❌    |    ✅    |    ✅     |   ❌    |
 
-## 🔧 Implementation
+## 🔧 Implementations
 
 GoQrius is designed to be easily integrated into your REST API endpoints.
-The filter parameter parses the expression and converts it into executable conditions for your data layer.
+By using:
+
+```go
+filter := "name eq 'John'" // e.g. value retrieved from a query parameter. 
+e, err := goqrius.Parse(filter)
+if err != nil {
+ ...
+}
+...
+```
+
+You get the GoQrius expression that can be transformed to a filtering clause in your data layer.
 
 The current data layers implementations for GoQrius are:
 

goqrius.go

@@ -0,0 +1,46 @@
+// Package goqrius
+package goqrius
+
+import (
+	"strings"
+
+	"github.com/golaxo/goqrius/lexer"
+)
+
+// Parse the input filter expression to a goqrius Expression.
+func Parse(input string) (Expression, error) {
+	if input == "" {
+		//nolint:nilnil // TODO think about returning something like EmptyExpression{}, nil.
+		return nil, nil
+	}
+
+	l := lexer.New(input)
+	p := New(l)
+	e := p.Parse()
+
+	var err error
+	if len(p.Errors()) > 0 {
+		err = ParseError{errors: p.Errors()}
+	}
+
+	return e, err
+}
+
+func MustParse(input string) Expression {
+	e, err := Parse(input)
+	if err != nil {
+		panic(err)
+	}
+
+	return e
+}
+
+var _ error = new(ParseError)
+
+type ParseError struct {
+	errors []string
+}
+
+func (p ParseError) Error() string {
+	return strings.Join(p.errors, ",")
+}

nodes.go

@@ -0,0 +1,66 @@
+package goqrius
+
+import (
+	"fmt"
+
+	"github.com/golaxo/goqrius/token"
+)
+
+type (
+	Node interface {
+		String() string
+	}
+
+	Expression interface {
+		Node
+		expressionNode()
+	}
+)
+
+func (i *Identifier) String() string  { return i.Value }
+func (i *Identifier) expressionNode() {}
+
+func (il *IntegerLiteral) String() string  { return il.Value }
+func (il *IntegerLiteral) expressionNode() {}
+
+func (sl *StringLiteral) String() string  { return fmt.Sprintf("'%s'", sl.Value) }
+func (sl *StringLiteral) expressionNode() {}
+
+type (
+	// Identifier is the Expression to indicate the key of a filter clause, e.g. `name`.
+	Identifier struct {
+		Value string
+	}
+
+	// IntegerLiteral is the Expression to indicate an int value of a filter clause, e.g. `1`.
+	IntegerLiteral struct {
+		Value string
+	}
+
+	// StringLiteral is the Expression to indicate an int value of a filter clause, e.g. `'John'`.
+	StringLiteral struct {
+		Value string
+	}
+)
+
+type (
+	// NotExpr negates an Expression.
+	NotExpr struct {
+		Right Expression
+	}
+
+	// FilterExpr represents a key and operator and a value in a filter clause.
+	FilterExpr struct {
+		Left     Expression
+		Operator token.Type
+		Right    Expression
+	}
+)
+
+func (ne *NotExpr) String() string  { return fmt.Sprintf("(not %s)", ne.Right.String()) }
+func (ne *NotExpr) expressionNode() {}
+
+func (ie *FilterExpr) String() string {
+	return fmt.Sprintf("(%s %s %s)", ie.Left.String(), string(ie.Operator), ie.Right.String())
+}
+func (ie *FilterExpr) expressionNode() {}

parser/parser.go parser.goparser/parser.go renamed to parser.go

@@ -1,5 +1,4 @@
-// Package parser parse the filter expression.
-package parser
+package goqrius
 
 import (
 	"fmt"
@@ -11,72 +10,34 @@ import (
 // Precedences.
 const (
 	_ int = iota
-	LOWEST
-	OR      // or
-	AND     // and
-	PREFIX  // not
-	COMPARE // eq, ne, gt, ge, lt, le
+	lowest
+	or      // or
+	and     // and
+	prefix  // not
+	compare // eq, ne, gt, ge, lt, le
 )
 
 //nolint:exhaustive,gochecknoglobals // no need to put all the tokens.
 var precedences = map[token.Type]int{
-	token.Or:                 OR,
-	token.And:                AND,
-	token.Eq:                 COMPARE,
-	token.NotEq:              COMPARE,
-	token.GreaterThan:        COMPARE,
-	token.GreaterThanOrEqual: COMPARE,
-	token.LessThan:           COMPARE,
-	token.LessThanOrEqual:    COMPARE,
+	token.Or:                 or,
+	token.And:                and,
+	token.Eq:                 compare,
+	token.NotEq:              compare,
+	token.GreaterThan:        compare,
+	token.GreaterThanOrEqual: compare,
+	token.LessThan:           compare,
+	token.LessThanOrEqual:    compare,
 }
 
-// AST nodes
-
-type Node interface{ String() string }
-
-type Expression interface {
-	Node
-	expressionNode()
-}
-
-type Identifier struct{ Value string }
-
-func (i *Identifier) String() string  { return i.Value }
-func (i *Identifier) expressionNode() {}
-
-type IntegerLiteral struct{ Value string }
-
-func (il *IntegerLiteral) String() string  { return il.Value }
-func (il *IntegerLiteral) expressionNode() {}
-
-type StringLiteral struct{ Value string }
-
-func (sl *StringLiteral) String() string  { return fmt.Sprintf("'%s'", sl.Value) }
-func (sl *StringLiteral) expressionNode() {}
-
-type NotExpr struct{ Right Expression }
-
-func (ne *NotExpr) String() string  { return fmt.Sprintf("(not %s)", ne.Right.String()) }
-func (ne *NotExpr) expressionNode() {}
-
-type InfixExpr struct {
-	Left     Expression
-	Operator token.Type
-	Right    Expression
-}
-
-func (ie *InfixExpr) String() string {
-	return fmt.Sprintf("(%s %s %s)", ie.Left.String(), string(ie.Operator), ie.Right.String())
-}
-func (ie *InfixExpr) expressionNode() {}
-
 type Parser struct {
 	l         *lexer.Lexer
 	curToken  token.Token
 	peekToken token.Token
 	errors    []string
 }
 
+// New creates a new Parser based on a Lexer.
+// It's recommended to use goqrius.Parse instead of this.
 func New(l *lexer.Lexer) *Parser {
 	p := &Parser{
 		l:      l,
@@ -99,7 +60,7 @@ func (p *Parser) Parse() Expression {
 		p.nextToken()
 	}
 
-	expr := p.parseExpression(LOWEST)
+	expr := p.parseExpression(lowest)
 
 	// consume trailing tokens until EOF
 	for p.peekToken.Type != token.EOF {
@@ -128,15 +89,15 @@ func (p *Parser) peekPrecedence() int {
 		return pr
 	}
 
-	return LOWEST
+	return lowest
 }
 
 func (p *Parser) curPrecedence() int {
 	if pr, ok := precedences[p.curToken.Type]; ok {
 		return pr
 	}
 
-	return LOWEST
+	return lowest
 }
 
 func (p *Parser) peekError(t token.Type) {
@@ -156,12 +117,12 @@ func (p *Parser) parseExpression(precedence int) Expression {
 		leftExp = &StringLiteral{Value: p.curToken.Literal}
 	case token.Not:
 		p.nextToken()
-		right := p.parseExpression(PREFIX)
+		right := p.parseExpression(prefix)
 		leftExp = &NotExpr{Right: right}
 	case token.Lparen:
 		p.nextToken()
 
-		leftExp = p.parseExpression(LOWEST)
+		leftExp = p.parseExpression(lowest)
 		if !p.expectPeek(token.Rparen) {
 			return nil
 		}
@@ -182,7 +143,7 @@ func (p *Parser) parseExpression(precedence int) Expression {
 			prec := p.curPrecedence()
 			p.nextToken() // advance to the right expression's first token
 			right := p.parseExpression(prec)
-			leftExp = &InfixExpr{Left: leftExp, Operator: op, Right: right}
+			leftExp = &FilterExpr{Left: leftExp, Operator: op, Right: right}
 		default:
 			return leftExp
 		}

parser/parser_test.go parser_test.goparser/parser_test.go renamed to parser_test.go

@@ -1,4 +1,4 @@
-package parser
+package goqrius
 
 import (
 	"testing"
@@ -51,25 +51,35 @@ func TestParseExpressions(t *testing.T) {
 		t.Run(name, func(t *testing.T) {
 			t.Parallel()
 
-			l := lexer.New(tt.input)
-			p := New(l)
-			expr := p.Parse()
+			expr, err := Parse(tt.input)
+			if err != nil {
+				t.Fatalf("err not expected; error=%v", err)
+			}
 
 			if expr == nil {
-				t.Fatalf("expected non-nil expression; errors=%v", p.Errors())
+				t.Fatalf("expected non-nil expression")
 			}
 
 			if got := expr.String(); got != tt.expectedString {
 				t.Fatalf("unexpected AST string. expected=%q got=%q", tt.expectedString, got)
 			}
-
-			if len(p.Errors()) != 0 {
-				t.Fatalf("unexpected parser errors: %v", p.Errors())
-			}
 		})
 	}
 }
 
+func TestEmptyInput(t *testing.T) {
+	t.Parallel()
+
+	expr, err := Parse("")
+	if err != nil {
+		t.Fatalf("err not expected; error=%v", err)
+	}
+
+	if expr != nil {
+		t.Fatalf("expected nil expression")
+	}
+}
+
 func TestParseErrors(t *testing.T) {
 	t.Parallel()