Table of Contents
The format of this grammar approximates Extended Backus-Naur notation. However it is intended as input to human beings, not to parser generators such as Lex or Yacc. Do not expect formal rigor. Sometimes narrative text will explain things that are clumsy to express in formal notation. More often, the text will restate or summarize the formal productions.
Conventions:
Since both EBNF and JSON use curly braces and square brackets, pay close attention to whether these characters are in single quotes. If they're in single quotes, they are literal elements of the JSON notation. Otherwise they are elements of the EBNF notation.
We'll start by defining some primitives, to get them out of the way. They're mostly just what you would expect.
|
When json_query requires an integral value, it will usually accept a quoted string and convert it to an integer by brute force – to zero if necessary. Likewise it may truncate a floating point number to an integral value. Scientific notation will be accepted but may not give the intended results.
|
The preferred way to encode a boolean is with the JSON reserved word true or false,
in lower case without quotation marks. The string “trueK
”, in
upper, lower, or mixed case, is another way to encode true. Any other string
evaluates to false.
As an accommodation to perl, numbers may be used as booleans. A numeric value of 1 means true, and any other numeric value means false.
Any other valid JSON value, such as an array, will be accepted as a boolean but interpreted as false.
The last couple of primitives aren't really very primitive, but we introduce them here for convenience:
|
A class_name is a special case of a string: the name of a class as defined by the IDL. The class may refer either to a database table or to a source_definition, which is a subquery.
|
A field_name is another special case of a string: the name of a non-virtual field as defined by the IDL. A field_name is also a column name for the table corresponding to the relevant class.
The following production applies not only to the main query but also to most subqueries.
|
Except for the “distinct”
and “no_i18n”
entries, each name/value pair represents a major clause of the SELECT statement.
The name/value pairs may appear in any order.
There is no name/value pair for the GROUP BY clause, because json_query generates it automatically according to information encoded elsewhere.
The “distinct”
entry, if present and true, tells json_query
that it may have to create a GROUP BY clause. If not present, it defaults to false.
The “no_i18n”
entry, if present and true, tells json_query to
suppress internationalization. If not present, it defaults to false. (Note that
“no_i18n”
contains the digit one, not the letter ell.)
The values for “limit”
and “offset”
provide the arguments of the LIMIT and OFFSET clauses, respectively, of the
SQL statement. Each value should be non-negative, if present, or else the
SQL won't work.