RSQL / FIQL parser

RESTful Service Query Language (RSQL) is my language and library that is designed for searching entries in RESTful services. RSQL is based on URI-friendly syntax FIQL (Feed Item Query Language) - IETF Internet-Draft of syntax for expressing filters across the entries in an Atom Feed. FIQL is great for use in URL because it doesn’t contain unsafe characters, so URL encoding isn’t necessary. On the other side, it’s not very intuitive and URL encoding isn’t always that big deal, so RSQL provides also more common alternative syntax.

This is complete parser for RSQL written in JavaCC and Java. Since RSQL is based on FIQL, it can be used for FIQL as well. RSQL-parser is related with RSQL-hibernate - library for translating RSQL expression to Hibernate’s Criteria query.

Grammar and semantic

Expression

Expression is composed of one or more constraints, related to each other with Boolean operators.

expression = [ "(" ],
             ( constraint | expression ),
             [ logical-operator, ( constraint | expression ) ],
             [ ")" ];

Logical operators are:

AND : ; or and
OR : , or or

logical-operator = ";" | " and " | "," | " or ";

By default, the AND operator takes precedence (i.e., it is evaluated before any OR operators are). However, a parenthesized expression can be used to change precedence, yielding whatever the contained expression yields.

Constraint

A constraint is composed of a selector, which identifies an entry’s element, and a comparison/argument pair, which refines the constraint.

constraint = selector, comparison-operator, argument;

Comparison operators are:

Equal to : == or =
Not equal to : !=
Less than : =lt= or <
Less than or equal to : =le= or <=
Greater than operator : =gt= or >
Greater than or equal to: =ge= or >=

comparison-operator = "==" | "=" | "!=" | "=lt=" | "<" | "=le=" | "<=" | "=gt=" | ">" | "=ge=" | ">=";

A selector can be a single Local Name (e.g. course), QName (e.g. my:course) or path (e.g. course/name, my:course/my:name). It may contain a link “dereference” via dot-notation (eg. course/department.code).

selector   = qname, { ("/" | "."), qname };
qname      = identifier, [ ":", identifier ];
identifier = ? ["a"-"z","A"-"Z","_","0"-"9","-"]+ ?

An argument can be of two types. Any character sequence between single or double quotation marks, or unquoted sequence without whitespace, parentheses, comma or semicolon.

argument    = arg_ws | arg_sq | arg_dq;
argument-ws = ? ( ~["(", ")", ";", ",", " "] )+ ?;
argument-sq = ? "'" ~["'"]+ "'" ?;
argument-dq = ? "\"" ~["\""]+ "\"" ?;

Examples

Let’s look at few examples of RSQL expressions in both FIQL-like and alternative syntax (you can also combine them):

- code==MI-MDW;credits=gt=4
- code=MI-MDW and credits>4
- name=="Programming in Java";(completion==CLFD_CREDIT,completion==CREDIT)
- name="Programming in Java" and (completion=CLFD_CREDIT or completion=CREDIT)
- teachers/instructor==jirutjak;department.code==KSI
- teachers/instructor=jirutjak and department.code=KSI
- kos:capacity=lt=100,kos:capacity=ge=50
- kos:capacity<100 or kos:capacity>=50

For more examples see RSQL-hibernate.

How to use

RSQL-parser uses Maven2 as its build tool. Java sources for parser itself are generated by javacc-maven-plugin during build process.

<dependency>
    <groupId>cz.jirutka.rsql</groupId>
    <artifactId>rsql-parser</artifactId>
    <version>1.0.1</version>
</dependency>

<repository>
    <id>cvut-local-repos</id>
    <name>CVUT Repository Local</name>
    <url>http://repository.fit.cvut.cz/maven/local-repos/</url>
</repository>

The main class is RSQLParser and method parse(String rsql).

License

This project is licensed under MIT license.