README.md

rql-parser

A Java Resource Query Language (RQL) parser using ANTLR 4.

Requirements

• Java 11 or higher

Grammar

The ANTLR grammar file can be viewed here.

Usage

Creating a parser

RqlLexer and RqlParser are generated by ANTLR and extend the ANTLR Lexer and Parser class respectively. For more information see the ANTLR documentation.

public class RQLParserExample {
    public RqlParser createParser(String rql) {
        // create a lexer and set its input stream from an RQL string
        CharStream inputStream = CharStreams.fromString(rql);
        RqlLexer lexer = new RqlLexer(inputStream);
        // throw on lexer errors
        lexer.addErrorListener(new ThrowWithDetailsErrorListener());

        // get a token stream for the lexer
        CommonTokenStream tokenStream = new CommonTokenStream(lexer);

        // create a parser
        RqlParser parser = new RqlParser(tokenStream);
        // throw on parser errors
        parser.addErrorListener(new ThrowWithDetailsErrorListener());

        return parser;
    }
}

Implement a visitor

RqlBaseVisitor implements the ANTLR interface ParseTreeVisitor. For more information see the ANTLR documentation.

public class RQLParserExample {
    public void visit(RqlParser parser) {
        RqlBaseVisitor<DesiredType> visitor = new RqlBaseVisitor<>() {
            // extend me
        };

        DesiredType result = visitor.visit(parser.query());
    }
}

Filter a list

See also ListFilterTest

public class RQLParserExample {

    final QueryVisitor<Person> visitor = new QueryVisitor<>(this::getProperty);

    // you could use Apache BeanUtils for this
    Object getProperty(Person item, String propertyName) {
        switch (propertyName) {
            case "name":
                return item.getName();
            default:
                throw new IllegalArgumentException("Unknown property");
        }
    }

    public List<Person> filterList(List<Person> input) {
        RqlParser parser = createParser("name=John");
        StreamFilter<Person> filter = visitor.visit(parser.query());

        return filter.apply(input.stream())
                .collect(Collectors.toList());
    }
}

Legacy usage

Note: The RQLParser class is still available in version 1.x, you can still use it to generate a tree of ASTNode .

The parser generates an ASTNode object representing the root node of an Abstract Syntax Tree (AST). Create a class that implements ASTVisitor<R,A> in order to traverse the tree.

public class RQLParserExample {
    public void parse() {
        RQLParser parser = new RQLParser();
        MyVisitor visitor = new MyVisitor();
        ASTNode node = parser.parse("(name=jack|name=jill)&age>30");
        Object result = node.accept(visitor);
    }
}

Maven Central Repository coordinates

Find the latest version on Maven Central.

<dependency>
    <groupId>net.jazdw</groupId>
    <artifactId>rql-parser</artifactId>
    <version>${rql.version}</version>
</dependency>