docs/Guides/grammar2.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2
   3 <article version="5.0" xmlns="http://docbook.org/ns/docbook"
   4         xmlns:xi="http://www.w3.org/2003/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink">
   5
   6         <title>Grammar of JSON Queries</title>
   7
   8         <para>
   9                 <author>
  10                         <personname>
  11                                 <firstname>Scott</firstname>
  12                                 <surname>McKellar</surname>
  13                         </personname>
  14                         <affiliation>
  15                                 <orgname>Equinox Software, Inc.</orgname>
  16                         </affiliation>
  17                 </author>
  18         </para>
  19
  20         <para>
  21                 <info>
  22                         <copyright>
  23                                 <year>2009</year>
  24                                 <holder>Creative Commons Attribution-Share Alike 3.0 United States License.</holder>
  25                         </copyright>
  26                 </info>
  27         </para>
  28
  29
  30
  31         <sect1>
  32                 <title>Introduction</title>
  33                 <para> The format of this grammar approximates Extended Backus-Naur notation. However it is
  34                         intended as input to human beings, not to parser generators such as Lex or Yacc. Do not
  35                         expect formal rigor. Sometimes narrative text will explain things that are clumsy to
  36                         express in formal notation. More often, the text will restate or summarize the formal
  37                         productions. </para>
  38                 <para> Conventions: </para>
  39                 <orderedlist>
  40                         <listitem>
  41                                 <para>The grammar is a series of productions.</para>
  42                         </listitem>
  43                         <listitem>
  44                                 <para>A production consists of a name, followed by "::=", followed by a definition
  45                                         for the name. The name identifies a grammatical construct that can appear on the
  46                                         right side of another production.</para>
  47                         </listitem>
  48                         <listitem>
  49                                 <para>Literals (including punctuation) are enclosed in 'single quotes', or in
  50                                         "double quotes" if case is not significant.</para>
  51                         </listitem>
  52                         <listitem>
  53                                 <para>A single quotation mark within a literal is escaped with a preceding
  54                                         backslash: 'dog\'s tail'.</para>
  55                         </listitem>
  56                         <listitem>
  57                                 <para>If a construct can be defined more than one way, then the alternatives may
  58                                         appear in separate productions; or, they may appear in the same production,
  59                                         separated by pipe symbols. The choice between these representations is of only
  60                                         cosmetic significance.</para>
  61                         </listitem>
  62                         <listitem>
  63                                 <para>A construct enclosed within square brackets is optional.</para>
  64                         </listitem>
  65                         <listitem>
  66                                 <para>A construct enclosed within curly braces may be repeated zero or more
  67                                         times.</para>
  68                         </listitem>
  69                         <listitem>
  70                                 <para>JSON allows arbitrary white space between tokens. To avoid ugly clutter, this
  71                                         grammar ignores the optional white space. </para>
  72                         </listitem>
  73                         <listitem>
  74                                 <para>In many cases a production defines a JSON object, i.e. a list of name-value
  75                                         pairs, separated by commas. Since the order of these name/value pairs is not
  76                                         significant, the grammar will not try to show all the possible sequences. In
  77                                         general it will present the required pairs first, if any, followed by any
  78                                         optional elements.</para>
  79                         </listitem>
  80                 </orderedlist>
  81
  82                 <para> Since both EBNF and JSON use curly braces and square brackets, pay close attention to
  83                         whether these characters are in single quotes. If they're in single quotes, they are
  84                         literal elements of the JSON notation. Otherwise they are elements of the EBNF notation.
  85                 </para>
  86         </sect1>
  87
  88         <sect1>
  89                 <title>Primitives</title>
  90                 <para> We'll start by defining some primitives, to get them out of the way. They're mostly
  91                         just what you would expect. </para>
  92
  93                 <productionset>
  94                         <production xml:id="ebnf.string">
  95                                 <lhs> string </lhs>
  96                                 <rhs> '"' chars '"' </rhs>
  97                         </production>
  98
  99                         <production xml:id="ebnf.chars">
 100                                 <lhs> chars </lhs>
 101                                 <rhs> any valid sequence of UTF-8 characters, with certain special characters
 102                                         escaped according to JSON rules </rhs>
 103                         </production>
 104
 105                         <production xml:id="ebnf.int_literal">
 106                                 <lhs> integer_literal </lhs>
 107                                 <rhs> [ sign ] digit { digit } </rhs>
 108                         </production>
 109
 110                         <production xml:id="ebnf.sign">
 111                                 <lhs> sign </lhs>
 112                                 <rhs> '+' | '-' </rhs>
 113                         </production>
 114
 115                         <production xml:id="ebnf.digits">
 116                                 <lhs> digit </lhs>
 117                                 <rhs>digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9'</rhs>
 118                         </production>
 119
 120                         <production xml:id="ebnf.int_string">
 121                                 <lhs> integer_string </lhs>
 122                                 <rhs> '"' integer_literal '"' </rhs>
 123                         </production>
 124
 125                         <production xml:id="ebnf.int">
 126                                 <lhs> integer </lhs>
 127                                 <rhs> integer_literal | integer_string </rhs>
 128                         </production>
 129
 130                         <production xml:id="ebnf.num">
 131                                 <lhs> number </lhs>
 132                                 <rhs> any valid character sequence that is numeric according to JSON rules </rhs>
 133                         </production>
 134
 135                 </productionset>
 136
 137                 <para> When json_query requires an integral value, it will usually accept a quoted string
 138                         and convert it to an integer by brute force – to zero if necessary. Likewise it may
 139                         truncate a floating point number to an integral value. Scientific notation will be
 140                         accepted but may not give the intended results. </para>
 141
 142                 <productionset>
 143
 144                         <production xml:id="ebnf.bool">
 145                                 <lhs> boolean </lhs>
 146                                 <rhs> 'true' | 'false' | string | number </rhs>
 147                         </production>
 148
 149                 </productionset>
 150
 151                 <para> The preferred way to encode a boolean is with the JSON reserved word true or false,
 152                         in lower case without quotation marks. The string <literal>true</literal>, in upper,
 153                         lower, or mixed case, is another way to encode true. Any other string evaluates to
 154                         false. </para>
 155                 <para> As an accommodation to perl, numbers may be used as booleans. A numeric value of 1
 156                         means true, and any other numeric value means false. </para>
 157                 <para> Any other valid JSON value, such as an array, will be accepted as a boolean but
 158                         interpreted as false. </para>
 159                 <para> The last couple of primitives aren't really very primitive, but we introduce them
 160                         here for convenience: </para>
 161
 162                 <productionset>
 163
 164                         <production xml:id="ebnf.classname">
 165                                 <lhs> class_name </lhs>
 166                                 <rhs> string </rhs>
 167                         </production>
 168
 169                 </productionset>
 170
 171                 <para> A class_name is a special case of a string: the name of a class as defined by the
 172                         IDL. The class may refer either to a database table or to a source_definition, which is
 173                         a subquery. </para>
 174
 175                 <productionset>
 176
 177                         <production xml:id="ebnf.field_name">
 178                                 <lhs> field_name </lhs>
 179                                 <rhs> string </rhs>
 180                         </production>
 181
 182                 </productionset>
 183
 184                 <para> A field_name is another special case of a string: the name of a non-virtual field as
 185                         defined by the IDL. A field_name is also a column name for the table corresponding to
 186                         the relevant class. </para>
 187
 188         </sect1>
 189
 190         <sect1>
 191                 <title>Query</title>
 192
 193                 <para> The following production applies not only to the main query but also to most
 194                         subqueries. </para>
 195
 196                 <productionset>
 197
 198                         <production xml:id="ebnf.query">
 199                                 <lhs> query </lhs>
 200                                 <rhs> '{'<sbr/> '"from"' ':' from_list<sbr/> [ ',' '"select"' ':' select_list
 201                                         ]<sbr/> [ ',' '"where"' ':' where_condition ]<sbr/> [ ',' '"having"' ':'
 202                                         where_condition ]<sbr/> [ ',' '"order_by"' ':' order_by_list ]<sbr/> [ ','
 203                                         '"limit"' ':' integer ]<sbr/> [ ',' '"offset"' ':' integer ]<sbr/> [ ','
 204                                         '"distinct"' ':' boolean ]<sbr/> [ ',' '"no_i18n"' ':' boolean ]<sbr/> '}'
 205                                 </rhs>
 206                         </production>
 207
 208                 </productionset>
 209
 210                 <para> Except for the <literal>"distinct"</literal> and <literal>no_i18n</literal> entries,
 211                         each name/value pair represents a major clause of the SELECT statement. The name/value
 212                         pairs may appear in any order. </para>
 213                 <para> There is no name/value pair for the GROUP BY clause, because json_query generates it
 214                         automatically according to information encoded elsewhere. </para>
 215                 <para> The <literal>"distinct"</literal> entry, if present and true, tells json_query that
 216                         it may have to create a GROUP BY clause. If not present, it defaults to false. </para>
 217                 <para> The <literal>"no_i18n"</literal> entry, if present and true, tells json_query to
 218                         suppress internationalization. If not present, it defaults to false. (Note that
 219                                 <literal>"no_i18n"</literal> contains the digit one, not the letter ell.) </para>
 220                 <para> The values for <literal>limit</literal> and <literal>offset</literal> provide the
 221                         arguments of the LIMIT and OFFSET clauses, respectively, of the SQL statement. Each
 222                         value should be non-negative, if present, or else the SQL won't work. </para>
 223
 224         </sect1>
 225
 226
 227 </article>