docs/Guides/grammar.html

   1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Grammar of JSON Queries</title><meta name="generator" content="DocBook XSL Stylesheets V1.74.3"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="id1165551"></a>Grammar of JSON Queries</h1></div><div><div class="author"><h3 class="author"><span class="firstname">Scott</span> <span class="surname">McKellar</span></h3></div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#id1165745">Introduction</a></span></dt><dt><span class="sect1"><a href="#id1165792">Primitives</a></span></dt><dt><span class="sect1"><a href="#id1165795">Query</a></span></dt></dl></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id1165745"></a>Introduction</h2></div></div></div><p>
   2                         The format of this grammar approximates Extended Backus-Naur notation.  However it
   3                         is intended as input to human beings, not to parser generators such as Lex or
   4                         Yacc.  Do not expect formal rigor.  Sometimes narrative text will explain things
   5                         that are clumsy to express in formal notation.  More often, the text will restate
   6                         or summarize the formal productions.
   7                 </p><p>
   8                         Conventions:
   9                 </p><div class="orderedlist"><ol type="1"><li>
  10                                 The grammar is a series of productions.
  11                         </li><li>
  12                                 A production consists of a name, followed by "::=", followed by a
  13                                 definition for the name.  The name identifies a grammatical construct that can
  14                                 appear on the right side of another production.
  15                         </li><li>
  16                                 Literals (including punctuation) are enclosed in single quotes, or in double
  17                                 quotes if case is not significant.
  18                         </li><li>
  19                                 A single quotation mark within a literal is escaped with a preceding backslash.
  20                         </li><li>
  21                                 If a construct can be defined more than one way, then the alternatives may appear
  22                                 in separate productions; or, they may appear in the same production, separated by
  23                                 pipe symbols.  The choice between these representations is of only cosmetic
  24                                 significance.
  25                         </li><li>
  26                                 A construct enclosed within square brackets is optional.
  27                         </li><li>
  28                                 A construct enclosed within curly braces may be repeated zero or more times.
  29                         </li><li>
  30                                 JSON allows arbitrary white space between tokens.  To avoid ugly clutter, this
  31                                 grammar ignores the optional white space.
  32                         </li><li>
  33                                 In many cases a production defines a JSON object, i.e. a list of name-value pairs,
  34                                 separated by commas.  Since the order of these name/value pairs is not significant,
  35                                 the grammar will not try to show all the possible sequences.  In general it will
  36                                 present the required pairs first, if any, followed by any optional elements.
  37                         </li></ol></div><p>
  38                         Since both EBNF and JSON use curly braces and square brackets, pay close attention to
  39                         whether these characters are in single quotes.  If they're in single quotes, they are
  40                         literal elements of the JSON notation.  Otherwise they are elements of the EBNF notation.
  41                 </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id1165792"></a>Primitives</h2></div></div></div><p>
  42                         We'll start by defining some primitives, to get them out of the way.  They're
  43                         mostly just what you would expect.
  44                 </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[1]</td><td align="right" valign="top" width="10%">
  45                                         string
  46                                 </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%">
  47                                         '&#8221;' chars '&#8221;'
  48                                 </td><td align="left" valign="top" width="30%"> </td></tr><tr><td align="left" valign="top" width="3%">[2]</td><td align="right" valign="top" width="10%">
  49                                         chars
  50                                 </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%">
  51                                         any valid sequence of UTF-8 characters, with certain special characters
  52                                         escaped according to JSON rules
  53                                 </td><td align="left" valign="top" width="30%"> </td></tr><tr><td align="left" valign="top" width="3%">[3]</td><td align="right" valign="top" width="10%">
  54                                         integer_literal
  55                                 </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%">
  56                                         [ sign ] digit { digit }
  57                                 </td><td align="left" valign="top" width="30%"> </td></tr><tr><td align="left" valign="top" width="3%">[4]</td><td align="right" valign="top" width="10%">
  58                                         sign
  59                                 </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%">
  60                                         '+' | '-'
  61                                 </td><td align="left" valign="top" width="30%"> </td></tr><tr><td align="left" valign="top" width="3%">[5]</td><td align="right" valign="top" width="10%">
  62                                         digit
  63                                 </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%">
  64                                 </td><td align="left" valign="top" width="30%"> </td></tr><tr><td align="left" valign="top" width="3%">[6]</td><td align="right" valign="top" width="10%">
  65                                         integer_string
  66                                 </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%">
  67                                         '&#8221;'  integer_literal  '&#8221;'
  68                                 </td><td align="left" valign="top" width="30%"> </td></tr><tr><td align="left" valign="top" width="3%">[7]</td><td align="right" valign="top" width="10%">
  69                                         integer
  70                                 </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%">
  71                                         integer_literal  |  integer_string
  72                                 </td><td align="left" valign="top" width="30%"> </td></tr><tr><td align="left" valign="top" width="3%">[8]</td><td align="right" valign="top" width="10%">
  73                                         number
  74                                 </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%">
  75                                         any valid character sequence that is numeric according to JSON rules
  76                                 </td><td align="left" valign="top" width="30%"> </td></tr></table></td></tr></table><p>
  77                         When json_query requires an integral value, it will usually accept a quoted string and
  78                         convert it to an integer by brute force &#8211; to zero if necessary.  Likewise it may
  79                         truncate a floating point number to an integral value.  Scientific notation will be
  80                         accepted but may not give the intended results.
  81                 </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[9]</td><td align="right" valign="top" width="10%">
  82                                         boolean
  83                                 </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%">
  84                                         'true'  |  'false'  |  string  |  number
  85                                 </td><td align="left" valign="top" width="30%"> </td></tr></table></td></tr></table><p>
  86                         The preferred way to encode a boolean is with the JSON reserved word true or false,
  87                         in lower case without quotation marks.  The string &#8220;<code class="literal">trueK</code>&#8221;, in
  88                         upper, lower, or mixed case, is another way to encode true.  Any other string
  89                         evaluates to false.
  90                 </p><p>
  91                         As an accommodation to perl, numbers may be used as booleans.  A numeric value of 1
  92                         means true, and any other numeric value means false.
  93                 </p><p>
  94                         Any other valid JSON value, such as an array, will be accepted as a boolean but interpreted
  95                         as false.
  96                 </p><p>
  97                         The last couple of primitives aren't really very primitive, but we introduce them here
  98                         for convenience:
  99                 </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[10]</td><td align="right" valign="top" width="10%">
 100                                         class_name
 101                                 </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%">
 102                                         string
 103                                 </td><td align="left" valign="top" width="30%"> </td></tr></table></td></tr></table><p>
 104                         A class_name is a special case of a string: the name of a class as defined
 105                         by the IDL.  The class may refer either to a database table or to a
 106                         source_definition, which is a subquery.
 107                 </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[11]</td><td align="right" valign="top" width="10%">
 108                                         field_name
 109                                 </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%">
 110                                         string
 111                                 </td><td align="left" valign="top" width="30%"> </td></tr></table></td></tr></table><p>
 112                         A field_name is another special case of a string: the name of a non-virtual
 113                         field as defined by the IDL.  A field_name is also a column name for the
 114                         table corresponding to the relevant class.
 115                 </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id1165795"></a>Query</h2></div></div></div><p>
 116                         The following production applies not only to the main query but also to
 117                         most subqueries.
 118                 </p><table width="100%" cellpadding="5" bgcolor="#F5DCB3" border="1" class="productionset" summary="EBNF"><tr><td><table border="0" width="99%" cellpadding="0" bgcolor="#F5DCB3" class="productionset" summary="EBNF productions"><tr><td align="left" valign="top" width="3%">[12]</td><td align="right" valign="top" width="10%">
 119                                         query
 120                                 </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%">
 121                                         '{'<br>
 122                                         '&#8221;from&#8221;'  ':'  from_list<br>
 123                                         [ ','  '&#8221;select&#8221;'    ':'  select_list ]<br>
 124                                         [ ','  '&#8221;where&#8221;'     ':'  where_condition ]<br>
 125                                         [ ','  '&#8221;having&#8221;'    ':'  where_condition ]<br>
 126                                         [ ','  '&#8221;order_by&#8221;'  ':'  order_by_list ]<br>
 127                                         [ ','  '&#8221;limit&#8221;'     ':'  integer ]<br>
 128                                         [ ','  '&#8221;offset&#8221;'    ':'  integer ]<br>
 129                                         [ ','  '&#8221;distinct&#8221;'  ':'  boolean ]<br>
 130                                         [ ','  '&#8221;no_i18n&#8221;'   ':'  boolean ]<br>
 131                                         '}'
 132                                 </td><td align="left" valign="top" width="30%"> </td></tr></table></td></tr></table><p>
 133                         Except for the <code class="literal">&#8220;distinct&#8221;</code> and <code class="literal">&#8220;no_i18n&#8221;</code>
 134                         entries, each name/value pair represents a major clause of the SELECT statement.
 135                         The name/value pairs may appear in any order.
 136                 </p><p>
 137                         There is no name/value pair for the GROUP BY clause, because json_query
 138                         generates it automatically according to information encoded elsewhere.
 139                 </p><p>
 140                         The <code class="literal">&#8220;distinct&#8221;</code> entry, if present and true, tells json_query
 141                         that it may have to create a GROUP BY clause.  If not present, it defaults to false.
 142                 </p><p>
 143                         The <code class="literal">&#8220;no_i18n&#8221;</code> entry, if present and true, tells json_query to
 144                         suppress internationalization.  If not present, it defaults to false.  (Note that
 145                         <code class="literal">&#8220;no_i18n&#8221;</code> contains the digit one, not the letter ell.)
 146                 </p><p>
 147                         The values for <code class="literal">&#8220;limit&#8221;</code> and <code class="literal">&#8220;offset&#8221;</code>
 148                         provide the arguments of the LIMIT and OFFSET clauses, respectively, of the
 149                         SQL statement.  Each value should be non-negative, if present, or else the
 150                         SQL won't work.
 151                 </p></div></div></body></html>