Documentation
¶
Overview ¶
Package parser translates the ANTLR4-generated Cypher parse tree into the typed AST defined in github.com/FlavioCFOliveira/GoGraph/cypher/ast. The generated sources (under cypher/parser/gen/) are produced by the ANTLR4 tool and must not be hand-edited.
Build the parser from the grammar with:
go generate ./cypher/parser/...
Error Recovery Contract ¶
The parser uses ANTLR's default single-token insertion/deletion strategy (antlr.DefaultErrorStrategy). Under this strategy:
On a syntax error the parser attempts to recover by either inserting a missing single token or deleting the current token. This allows parsing to continue past isolated mistakes and collect further errors.
A maximum of [maxParseErrors] errors (currently 5) are collected per parse. Once the cap is reached, additional errors are silently dropped. This prevents cascading error floods on pathological inputs where a single structural mistake causes the parser to mis-identify every subsequent token as erroneous.
When at least one error is present the parse tree may be partial: some subtrees may have been constructed using the inserted/deleted tokens produced by error recovery. Callers must not rely on the AST being semantically correct when errors are returned.
Parse returns only the first error. ParseStrict returns all collected errors (up to the cap) and is intended for tooling such as editors and linters that benefit from seeing multiple errors at once.
Concurrency ¶
Parse and ParseStrict are safe to call concurrently. Each invocation creates independent lexer, parser, and error-listener instances; no state is shared between calls.
Package parser translates the antlr4-generated parse tree into the typed AST defined in github.com/FlavioCFOliveira/GoGraph/cypher/ast.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Parse ¶
Parse lexes and parses a Cypher query string and converts the resulting parse tree into a typed AST node. It returns the first error encountered.
Errors:
- *ParseError — syntax error from the ANTLR lexer/parser.
- *SemaError — unsupported grammar rule encountered during tree walking.
Example ¶
ExampleParse demonstrates basic Cypher parsing. The returned AST can be inspected or pretty-printed by downstream tooling.
package main
import (
"fmt"
"github.com/FlavioCFOliveira/GoGraph/cypher/parser"
)
func main() {
q, err := parser.Parse("MATCH (n:Person) RETURN n.name")
if err != nil {
fmt.Println("error:", err)
return
}
fmt.Println("ok, type:", fmt.Sprintf("%T", q))
}
Output: ok, type: *ast.SingleQuery
Example (InspectAST) ¶
ExampleParse_inspectAST shows how to inspect the AST root that Parse returns. A single-part query parses to *ast.SingleQuery, whose reading clauses and RETURN can then be walked by downstream stages.
package main
import (
"fmt"
"github.com/FlavioCFOliveira/GoGraph/cypher/ast"
"github.com/FlavioCFOliveira/GoGraph/cypher/parser"
)
func main() {
q, err := parser.Parse("MATCH (n:Person) RETURN n.name")
if err != nil {
fmt.Println("error:", err)
return
}
sq, ok := q.(*ast.SingleQuery)
if !ok {
fmt.Printf("unexpected root: %T\n", q)
return
}
fmt.Println("reading clauses:", len(sq.ReadingClauses))
fmt.Println("has RETURN:", sq.Return != nil)
if _, isMatch := sq.ReadingClauses[0].(*ast.Match); isMatch {
fmt.Println("first clause: MATCH")
}
}
Output: reading clauses: 1 has RETURN: true first clause: MATCH
func ParseStrict ¶
ParseStrict lexes and parses a Cypher query string and returns all syntax errors encountered rather than only the first. When the query is syntactically valid the AST is walked for semantic errors; a single *SemaError is returned in that case.
This function is intended for tooling (editors, linters) that need the full error set. Application code should use Parse.
Errors:
- One or more *ParseError — syntax errors from lexer/parser.
- A single *SemaError — unsupported grammar rule or structural violation.
Example ¶
ExampleParseStrict demonstrates multi-error collection for tooling use cases such as editors and linters. ParseStrict reports all syntax errors (up to the internal cap) rather than stopping at the first.
package main
import (
"errors"
"fmt"
"github.com/FlavioCFOliveira/GoGraph/cypher/parser"
)
func main() {
// Two independent syntax errors separated by a semicolon.
_, errs := parser.ParseStrict("RETURN , ; RETURN ,")
if len(errs) == 0 {
fmt.Println("no errors")
return
}
for _, e := range errs {
var pe *parser.ParseError
if errors.As(e, &pe) {
fmt.Printf("syntax error at %d:%d\n", pe.Line, pe.Column)
}
}
}
Output: syntax error at 1:7 syntax error at 1:11
Types ¶
type ParseError ¶
type ParseError struct {
// Line and Column of the first problematic token (1-based line, 0-based column).
Line int
Column int
// OffendingToken is the text of the token that triggered the error.
// It is empty for lexer errors where no token was formed.
OffendingToken string
// Expected is the human-readable list of token names that were valid at
// the error position. It is nil when the expected set cannot be determined
// (e.g. lexer errors).
Expected []string
// Message is the raw ANTLR error message, included as a fallback.
Message string
}
ParseError wraps ANTLR syntax errors reported during lexing or parsing.
func AsParseErrors ¶
func AsParseErrors(errs []error) ([]*ParseError, []error)
AsParseErrors returns all *ParseError values from an error slice produced by ParseStrict. Non-ParseError values are included as-is.
This is a convenience helper for callers that need to separate parse errors from sema errors.
func (*ParseError) Error ¶
func (e *ParseError) Error() string
Error returns a human-readable description of the syntax error.
Format: "unexpected '<token>' at <line>:<col>, expected one of {A, B, C}" When OffendingToken is empty the "unexpected" clause is omitted. When Expected is empty the "expected" clause is omitted.
type SemaError ¶
type SemaError struct {
// Rule is the grammar rule name that triggered the error (e.g. "foreach").
Rule string
// Pos is the source position of the offending node.
Pos ast.Position
// Message is a human-readable description of the problem.
Message string
}
SemaError is returned by the visitor when a parse-tree node corresponds to a grammar rule that is not supported in the read+write+DDL+procedure scope (FOREACH, CALL{}, multi-graph) or when a structural semantic constraint is violated.
Source Files
Directories