From: kgs <kgs@dcc99617-32d9-48b4-a31d-7c20da2025e4> Date: Fri, 8 May 2009 19:54:37 +0000 (+0000) Subject: setting up guides sync X-Git-Url: https://old-git.evergreen-ils.org/?a=commitdiff_plain;h=36894e63fb84ee6a8179009a99c5023a6994b533;p=evergreen%2Fmasslnc.git setting up guides sync git-svn-id: svn://svn.open-ils.org/ILS/trunk@13102 dcc99617-32d9-48b4-a31d-7c20da2025e4 --- diff --git a/docs/Guides/compugrammar.xpr b/docs/Guides/compugrammar.xpr new file mode 100644 index 0000000000..6235c751e1 --- /dev/null +++ b/docs/Guides/compugrammar.xpr @@ -0,0 +1,259 @@ +<?xml version="1.0" encoding="UTF-8"?> +<project> + <meta> + <filters directoryPatterns="CVS" filePatterns="" + positiveFilePatterns="" showHiddenFiles="false"/> + <options/> + </meta> + <projectTree name="compugrammar.xpr"> + <folder name="css"> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/css/sample1.css"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/css/sample1.xhtml"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/css/sample2.css"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/css/sample2.xhtml"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/css/sample3.css"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/css/sample3.xhtml" + /> + </folder> + <folder name="fo"> + <folder name="Basic Font Attributes"> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/fo/Basic%20Font%20Attributes/bold.fo"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/fo/Basic%20Font%20Attributes/bold.xml" + /> + </folder> + <folder name="Block Properties"> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/fo/Block%20Properties/borders.fo"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/fo/Block%20Properties/borders.xml" + /> + </folder> + <folder name="Character Sets"> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/fo/Character%20Sets/adobe-standard.fo"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/fo/Character%20Sets/adobe-standard.xml" + /> + </folder> + <folder name="Extended Font Attributes"> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/fo/Extended%20Font%20Attributes/aspect.fo"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/fo/Extended%20Font%20Attributes/aspect.xml" + /> + </folder> + <folder name="Invoice"> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/fo/Invoice/invoice.xml"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/fo/Invoice/invoice.xsd"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/fo/Invoice/invoice.xsl" + /> + </folder> + <folder name="Miscellaneous"> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/fo/Miscellaneous/fontAttributes.fo"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/fo/Miscellaneous/helloWorld.fo"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/fo/Miscellaneous/leaders.fo"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/fo/Miscellaneous/pageLayout.fo"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/fo/Miscellaneous/table.fo" + /> + </folder> + <folder name="Paragraph Attributes"> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/fo/Paragraph%20Attributes/pagebreak.fo"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/fo/Paragraph%20Attributes/pagebreak.xml" + /> + </folder> + <folder name="Text Block Attributes"> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/fo/Text%20Block%20Attributes/align.fo"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/fo/Text%20Block%20Attributes/align.xml" + /> + </folder> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/fo/macro.xsl" + /> + </folder> + <folder name="nvdl"> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/nvdl/xhtml-xforms.nvdl"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/nvdl/xhtml-xforms.xml" + /> + </folder> + <folder name="relaxng"> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/relaxng/personal.rnc"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/relaxng/personal.rng"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/relaxng/personal.xml" + /> + </folder> + <folder name="schematron"> + <folder name="1.5"> + <folder name="attributes"> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/1.5/attributes/followed-bad.xml"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/1.5/attributes/followed-good.xml"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/1.5/attributes/followed.dtd"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/1.5/attributes/followed.sch"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/1.5/attributes/length-bad.xml"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/1.5/attributes/length-bad1.xml"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/1.5/attributes/length-bad2.xml"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/1.5/attributes/length-good.xml"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/1.5/attributes/length.dtd"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/1.5/attributes/length.sch"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/1.5/attributes/name-bad.xml"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/1.5/attributes/name.dtd"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/1.5/attributes/name.sch"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/1.5/attributes/present-bad.xml"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/1.5/attributes/present.dtd"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/1.5/attributes/present.sch"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/1.5/attributes/required-bad1.xml"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/1.5/attributes/required-bad2.xml"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/1.5/attributes/required-good.xml"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/1.5/attributes/required.dtd"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/1.5/attributes/required.sch" + /> + </folder> + <folder name="author"> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/1.5/author/author.sch"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/1.5/author/source1.xml"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/1.5/author/source2.xml" + /> + </folder> + <folder name="paragraph"> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/1.5/paragraph/paragraph.sch"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/1.5/paragraph/source1.xml"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/1.5/paragraph/source2.xml" + /> + </folder> + <folder name="percent"> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/1.5/percent/percent-bad1.xml"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/1.5/percent/percent-bad2.xml"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/1.5/percent/percent-good.xml"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/1.5/percent/percent.dtd"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/1.5/percent/percent.sch" + /> + </folder> + <folder name="po"> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/1.5/po/po-bad.xml"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/1.5/po/po-schema.sch"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/1.5/po/po.xml"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/1.5/po/po.xsd" + /> + </folder> + <folder name="tournament"> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/1.5/tournament/tournament-schema.sch"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/1.5/tournament/Tournament.rng"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/1.5/tournament/Tournament.xml"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/1.5/tournament/Tournament.xsd" + /> + </folder> + </folder> + <folder name="iso"> + <folder name="tournament"> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/iso/tournament/tournament-schema.sch"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/iso/tournament/Tournament.rng"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/iso/tournament/Tournament.xml"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/schematron/iso/tournament/Tournament.xsd" + /> + </folder> + </folder> + </folder> + <folder name="svg"> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/svg/batik3D.svg"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/svg/sales.xml"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/svg/sales.xsl" + /> + </folder> + <folder + path="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/dita/"/> + <folder + path="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/docbook/"/> + <folder + path="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/ooxml/"/> + <folder + path="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/tei/"/> + <folder + path="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/xhtml/"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/personal-schema.css"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/personal-schema.xml"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/personal.css"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/personal.dtd"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/personal.xml"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/personal.xsd"/> + <file + name="../../Documents%20and%20Settings/KAREN%20SCHNEIDER/OxygenXMLAuthor/samples/personal.xsl" + /> + </projectTree> +</project> diff --git a/docs/Guides/grammar.html b/docs/Guides/grammar.html new file mode 100644 index 0000000000..36587da957 --- /dev/null +++ b/docs/Guides/grammar.html @@ -0,0 +1,151 @@ +<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> + 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. + </p><p> + Conventions: + </p><div class="orderedlist"><ol type="1"><li> + The grammar is a series of productions. + </li><li> + A production consists of a name, followed by "::=", followed by a + definition for the name. The name identifies a grammatical construct that can + appear on the right side of another production. + </li><li> + Literals (including punctuation) are enclosed in single quotes, or in double + quotes if case is not significant. + </li><li> + A single quotation mark within a literal is escaped with a preceding backslash. + </li><li> + If a construct can be defined more than one way, then the alternatives may appear + in separate productions; or, they may appear in the same production, separated by + pipe symbols. The choice between these representations is of only cosmetic + significance. + </li><li> + A construct enclosed within square brackets is optional. + </li><li> + A construct enclosed within curly braces may be repeated zero or more times. + </li><li> + JSON allows arbitrary white space between tokens. To avoid ugly clutter, this + grammar ignores the optional white space. + </li><li> + In many cases a production defines a JSON object, i.e. a list of name-value pairs, + separated by commas. Since the order of these name/value pairs is not significant, + the grammar will not try to show all the possible sequences. In general it will + present the required pairs first, if any, followed by any optional elements. + </li></ol></div><p> + 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. + </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> + We'll start by defining some primitives, to get them out of the way. They're + mostly just what you would expect. + </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%"> + string + </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> + '”' chars '”' + </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%"> + chars + </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> + any valid sequence of UTF-8 characters, with certain special characters + escaped according to JSON rules + </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%"> + integer_literal + </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> + [ sign ] digit { digit } + </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%"> + sign + </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> + '+' | '-' + </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%"> + digit + </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> + </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%"> + integer_string + </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> + '”' integer_literal '”' + </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%"> + integer + </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> + integer_literal | integer_string + </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%"> + number + </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> + any valid character sequence that is numeric according to JSON rules + </td><td align="left" valign="top" width="30%"> </td></tr></table></td></tr></table><p> + 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. + </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%"> + boolean + </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> + 'true' | 'false' | string | number + </td><td align="left" valign="top" width="30%"> </td></tr></table></td></tr></table><p> + The preferred way to encode a boolean is with the JSON reserved word true or false, + in lower case without quotation marks. The string “<code class="literal">trueK</code>”, in + upper, lower, or mixed case, is another way to encode true. Any other string + evaluates to false. + </p><p> + 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. + </p><p> + Any other valid JSON value, such as an array, will be accepted as a boolean but interpreted + as false. + </p><p> + The last couple of primitives aren't really very primitive, but we introduce them here + for convenience: + </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%"> + class_name + </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> + string + </td><td align="left" valign="top" width="30%"> </td></tr></table></td></tr></table><p> + 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. + </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%"> + field_name + </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> + string + </td><td align="left" valign="top" width="30%"> </td></tr></table></td></tr></table><p> + 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. + </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> + The following production applies not only to the main query but also to + most subqueries. + </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%"> + query + </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> + '{'<br> + '”from”' ':' from_list<br> + [ ',' '”select”' ':' select_list ]<br> + [ ',' '”where”' ':' where_condition ]<br> + [ ',' '”having”' ':' where_condition ]<br> + [ ',' '”order_by”' ':' order_by_list ]<br> + [ ',' '”limit”' ':' integer ]<br> + [ ',' '”offset”' ':' integer ]<br> + [ ',' '”distinct”' ':' boolean ]<br> + [ ',' '”no_i18n”' ':' boolean ]<br> + '}' + </td><td align="left" valign="top" width="30%"> </td></tr></table></td></tr></table><p> + Except for the <code class="literal">“distinct”</code> and <code class="literal">“no_i18n”</code> + entries, each name/value pair represents a major clause of the SELECT statement. + The name/value pairs may appear in any order. + </p><p> + There is no name/value pair for the GROUP BY clause, because json_query + generates it automatically according to information encoded elsewhere. + </p><p> + The <code class="literal">“distinct”</code> 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. + </p><p> + The <code class="literal">“no_i18n”</code> entry, if present and true, tells json_query to + suppress internationalization. If not present, it defaults to false. (Note that + <code class="literal">“no_i18n”</code> contains the digit one, not the letter ell.) + </p><p> + The values for <code class="literal">“limit”</code> and <code class="literal">“offset”</code> + 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. + </p></div></div></body></html> diff --git a/docs/Guides/grammar.xml b/docs/Guides/grammar.xml new file mode 100644 index 0000000000..2601682f90 --- /dev/null +++ b/docs/Guides/grammar.xml @@ -0,0 +1,291 @@ +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> + +<article xmlns="http://docbook.org/ns/docbook"> + + <artheader> + <title>Grammar of JSON Queries</title> + <author> + <firstname>Scott</firstname> + <surname>McKellar</surname> + </author> + </artheader> + + <sect1><title>Introduction</title> + <para> + 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. + </para> + <para> + Conventions: + </para> + <orderedlist> + <listitem> + The grammar is a series of productions. + </listitem> + <listitem> + A production consists of a name, followed by "::=", followed by a + definition for the name. The name identifies a grammatical construct that can + appear on the right side of another production. + </listitem> + <listitem> + Literals (including punctuation) are enclosed in single quotes, or in double + quotes if case is not significant. + </listitem> + <listitem> + A single quotation mark within a literal is escaped with a preceding backslash. + </listitem> + <listitem> + If a construct can be defined more than one way, then the alternatives may appear + in separate productions; or, they may appear in the same production, separated by + pipe symbols. The choice between these representations is of only cosmetic + significance. + </listitem> + <listitem> + A construct enclosed within square brackets is optional. + </listitem> + <listitem> + A construct enclosed within curly braces may be repeated zero or more times. + </listitem> + <listitem> + JSON allows arbitrary white space between tokens. To avoid ugly clutter, this + grammar ignores the optional white space. + </listitem> + <listitem> + In many cases a production defines a JSON object, i.e. a list of name-value pairs, + separated by commas. Since the order of these name/value pairs is not significant, + the grammar will not try to show all the possible sequences. In general it will + present the required pairs first, if any, followed by any optional elements. + </listitem> + </orderedlist> + + <para> + 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. + </para> + </sect1> + + <sect1><title>Primitives</title> + <para> + We'll start by defining some primitives, to get them out of the way. They're + mostly just what you would expect. + </para> + + <productionset> + <production> + <lhs> + string + </lhs> + <rhs> + 'â' chars 'â' + </rhs> + </production> + + <production> + <lhs> + chars + </lhs> + <rhs> + any valid sequence of UTF-8 characters, with certain special characters + escaped according to JSON rules + </rhs> + </production> + + <production> + <lhs> + integer_literal + </lhs> + <rhs> + [ sign ] digit { digit } + </rhs> + </production> + + <production> + <lhs> + sign + </lhs> + <rhs> + '+' | '-' + </rhs> + </production> + + <production> + <lhs> + digit + </lhs> + digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' + <rhs> + </rhs> + </production> + + <production> + <lhs> + integer_string + </lhs> + <rhs> + 'â' integer_literal 'â' + </rhs> + </production> + + <production> + <lhs> + integer + </lhs> + <rhs> + integer_literal | integer_string + </rhs> + </production> + + <production> + <lhs> + number + </lhs> + <rhs> + any valid character sequence that is numeric according to JSON rules + </rhs> + </production> + + </productionset> + + <para> + 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. + </para> + + <productionset> + + <production> + <lhs> + boolean + </lhs> + <rhs> + 'true' | 'false' | string | number + </rhs> + </production> + + </productionset> + + <para> + The preferred way to encode a boolean is with the JSON reserved word true or false, + in lower case without quotation marks. The string â<literal>true</literal>â, in + upper, lower, or mixed case, is another way to encode true. Any other string + evaluates to false. + </para> + <para> + 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. + </para> + <para> + Any other valid JSON value, such as an array, will be accepted as a boolean but interpreted + as false. + </para> + <para> + The last couple of primitives aren't really very primitive, but we introduce them here + for convenience: + </para> + + <productionset> + + <production> + <lhs> + class_name + </lhs> + <rhs> + string + </rhs> + </production> + + </productionset> + + <para> + 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. + </para> + + <productionset> + + <production> + <lhs> + field_name + </lhs> + <rhs> + string + </rhs> + </production> + + </productionset> + + <para> + 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. + </para> + + </sect1> + + <sect1><title>Query</title> + + <para> + The following production applies not only to the main query but also to + most subqueries. + </para> + + <productionset> + + <production> + <lhs> + query + </lhs> + <rhs> + '{'<sbr/> + 'âfromâ' ':' from_list<sbr/> + [ ',' 'âselectâ' ':' select_list ]<sbr/> + [ ',' 'âwhereâ' ':' where_condition ]<sbr/> + [ ',' 'âhavingâ' ':' where_condition ]<sbr/> + [ ',' 'âorder_byâ' ':' order_by_list ]<sbr/> + [ ',' 'âlimitâ' ':' integer ]<sbr/> + [ ',' 'âoffsetâ' ':' integer ]<sbr/> + [ ',' 'âdistinctâ' ':' boolean ]<sbr/> + [ ',' 'âno_i18nâ' ':' boolean ]<sbr/> + '}' + </rhs> + </production> + + </productionset> + + <para> + Except for the <literal>âdistinctâ</literal> and <literal>âno_i18nâ</literal> + entries, each name/value pair represents a major clause of the SELECT statement. + The name/value pairs may appear in any order. + </para> + <para> + There is no name/value pair for the GROUP BY clause, because json_query + generates it automatically according to information encoded elsewhere. + </para> + <para> + The <literal>âdistinctâ</literal> 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. + </para> + <para> + The <literal>âno_i18nâ</literal> entry, if present and true, tells json_query to + suppress internationalization. If not present, it defaults to false. (Note that + <literal>âno_i18nâ</literal> contains the digit one, not the letter ell.) + </para> + <para> + The values for <literal>âlimitâ</literal> and <literal>âoffsetâ</literal> + 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. + </para> + + </sect1> + +</article> diff --git a/docs/Guides/grammar2.html b/docs/Guides/grammar2.html new file mode 100644 index 0000000000..163431bf89 --- /dev/null +++ b/docs/Guides/grammar2.html @@ -0,0 +1,56 @@ +<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-NS Stylesheets V1.74.3-pre"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d0e1"></a>Grammar of JSON Queries</h2></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="#d0e28">Introduction</a></span></dt><dt><span class="sect1"><a href="#d0e65">Primitives</a></span></dt><dt><span class="sect1"><a href="#d0e194">Query</a></span></dt></dl></div><p> + <span class="author"><span class="firstname">Scott</span> <span class="surname">McKellar</span></span> + </p><p> + + </p><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e28"></a>Introduction</h2></div></div></div><p> 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. </p><p> Conventions: </p><div class="orderedlist"><ol type="1"><li><p>The grammar is a series of productions.</p></li><li><p>A production consists of a name, followed by "::=", followed by a definition + for the name. The name identifies a grammatical construct that can appear on the + right side of another production.</p></li><li><p>Literals (including punctuation) are enclosed in 'single quotes', or in + "double quotes" if case is not significant.</p></li><li><p>A single quotation mark within a literal is escaped with a preceding + backslash: 'dog\'s tail'.</p></li><li><p>If a construct can be defined more than one way, then the alternatives may + appear in separate productions; or, they may appear in the same production, + separated by pipe symbols. The choice between these representations is of only + cosmetic significance.</p></li><li><p>A construct enclosed within square brackets is optional.</p></li><li><p>A construct enclosed within curly braces may be repeated zero or more + times.</p></li><li><p>JSON allows arbitrary white space between tokens. To avoid ugly clutter, this + grammar ignores the optional white space. </p></li><li><p>In many cases a production defines a JSON object, i.e. a list of name-value + pairs, separated by commas. Since the order of these name/value pairs is not + significant, the grammar will not try to show all the possible sequences. In + general it will present the required pairs first, if any, followed by any + optional elements.</p></li></ol></div><p> 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. + </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e65"></a>Primitives</h2></div></div></div><p> We'll start by defining some primitives, to get them out of the way. They're mostly + just what you would expect. </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%"><a name="ebnf.string"></a> string </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> '"' chars '"' </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%"><a name="ebnf.chars"></a> chars </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> any valid sequence of UTF-8 characters, with certain special characters + escaped according to JSON rules </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%"><a name="ebnf.int_literal"></a> integer_literal </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> [ sign ] digit { digit } </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%"><a name="ebnf.sign"></a> sign </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> '+' | '-' </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%"><a name="ebnf.digits"></a> digit </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%">digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9'</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%"><a name="ebnf.int_string"></a> integer_string </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> '"' integer_literal '"' </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%"><a name="ebnf.int"></a> integer </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> integer_literal | integer_string </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%"><a name="ebnf.num"></a> number </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> any valid character sequence that is numeric according to JSON rules </td><td align="left" valign="top" width="30%"> </td></tr></table></td></tr></table><p> 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. </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%"><a name="ebnf.bool"></a> boolean </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> 'true' | 'false' | string | number </td><td align="left" valign="top" width="30%"> </td></tr></table></td></tr></table><p> The preferred way to encode a boolean is with the JSON reserved word true or false, + in lower case without quotation marks. The string <code class="literal">true</code>, in upper, + lower, or mixed case, is another way to encode true. Any other string evaluates to + false. </p><p> 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. </p><p> Any other valid JSON value, such as an array, will be accepted as a boolean but + interpreted as false. </p><p> The last couple of primitives aren't really very primitive, but we introduce them + here for convenience: </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%"><a name="ebnf.classname"></a> class_name </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> string </td><td align="left" valign="top" width="30%"> </td></tr></table></td></tr></table><p> 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. </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%"><a name="ebnf.field_name"></a> field_name </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> string </td><td align="left" valign="top" width="30%"> </td></tr></table></td></tr></table><p> 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. </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="d0e194"></a>Query</h2></div></div></div><p> The following production applies not only to the main query but also to most + subqueries. </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%"><a name="ebnf.query"></a> query </td><td valign="top" width="5%" align="center"><code>::=</code></td><td valign="top" width="52%"> '{'<br> '"from"' ':' from_list<br> [ ',' '"select"' ':' select_list + ]<br> [ ',' '"where"' ':' where_condition ]<br> [ ',' '"having"' ':' + where_condition ]<br> [ ',' '"order_by"' ':' order_by_list ]<br> [ ',' + '"limit"' ':' integer ]<br> [ ',' '"offset"' ':' integer ]<br> [ ',' + '"distinct"' ':' boolean ]<br> [ ',' '"no_i18n"' ':' boolean ]<br> '}' + </td><td align="left" valign="top" width="30%"> </td></tr></table></td></tr></table><p> Except for the <code class="literal">"distinct"</code> and <code class="literal">no_i18n</code> entries, + each name/value pair represents a major clause of the SELECT statement. The name/value + pairs may appear in any order. </p><p> There is no name/value pair for the GROUP BY clause, because json_query generates it + automatically according to information encoded elsewhere. </p><p> The <code class="literal">"distinct"</code> 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. </p><p> The <code class="literal">"no_i18n"</code> entry, if present and true, tells json_query to + suppress internationalization. If not present, it defaults to false. (Note that + <code class="literal">"no_i18n"</code> contains the digit one, not the letter ell.) </p><p> The values for <code class="literal">limit</code> and <code class="literal">offset</code> 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. </p></div></div></body></html> \ No newline at end of file diff --git a/docs/Guides/grammar2.pdf b/docs/Guides/grammar2.pdf new file mode 100644 index 0000000000..cc42294a17 Binary files /dev/null and b/docs/Guides/grammar2.pdf differ diff --git a/docs/Guides/grammar2.xml b/docs/Guides/grammar2.xml new file mode 100644 index 0000000000..5dd2215185 --- /dev/null +++ b/docs/Guides/grammar2.xml @@ -0,0 +1,227 @@ +<?xml version="1.0" encoding="utf-8"?> + +<article version="5.0" xmlns="http://docbook.org/ns/docbook" + xmlns:xi="http://www.w3.org/2003/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink"> + + <title>Grammar of JSON Queries</title> + + <para> + <author> + <personname> + <firstname>Scott</firstname> + <surname>McKellar</surname> + </personname> + <affiliation> + <orgname>Equinox Software, Inc.</orgname> + </affiliation> + </author> + </para> + + <para> + <info> + <copyright> + <year>2009</year> + <holder>Creative Commons Attribution-Share Alike 3.0 United States License.</holder> + </copyright> + </info> + </para> + + + + <sect1> + <title>Introduction</title> + <para> 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. </para> + <para> Conventions: </para> + <orderedlist> + <listitem> + <para>The grammar is a series of productions.</para> + </listitem> + <listitem> + <para>A production consists of a name, followed by "::=", followed by a definition + for the name. The name identifies a grammatical construct that can appear on the + right side of another production.</para> + </listitem> + <listitem> + <para>Literals (including punctuation) are enclosed in 'single quotes', or in + "double quotes" if case is not significant.</para> + </listitem> + <listitem> + <para>A single quotation mark within a literal is escaped with a preceding + backslash: 'dog\'s tail'.</para> + </listitem> + <listitem> + <para>If a construct can be defined more than one way, then the alternatives may + appear in separate productions; or, they may appear in the same production, + separated by pipe symbols. The choice between these representations is of only + cosmetic significance.</para> + </listitem> + <listitem> + <para>A construct enclosed within square brackets is optional.</para> + </listitem> + <listitem> + <para>A construct enclosed within curly braces may be repeated zero or more + times.</para> + </listitem> + <listitem> + <para>JSON allows arbitrary white space between tokens. To avoid ugly clutter, this + grammar ignores the optional white space. </para> + </listitem> + <listitem> + <para>In many cases a production defines a JSON object, i.e. a list of name-value + pairs, separated by commas. Since the order of these name/value pairs is not + significant, the grammar will not try to show all the possible sequences. In + general it will present the required pairs first, if any, followed by any + optional elements.</para> + </listitem> + </orderedlist> + + <para> 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. + </para> + </sect1> + + <sect1> + <title>Primitives</title> + <para> We'll start by defining some primitives, to get them out of the way. They're mostly + just what you would expect. </para> + + <productionset> + <production xml:id="ebnf.string"> + <lhs> string </lhs> + <rhs> '"' chars '"' </rhs> + </production> + + <production xml:id="ebnf.chars"> + <lhs> chars </lhs> + <rhs> any valid sequence of UTF-8 characters, with certain special characters + escaped according to JSON rules </rhs> + </production> + + <production xml:id="ebnf.int_literal"> + <lhs> integer_literal </lhs> + <rhs> [ sign ] digit { digit } </rhs> + </production> + + <production xml:id="ebnf.sign"> + <lhs> sign </lhs> + <rhs> '+' | '-' </rhs> + </production> + + <production xml:id="ebnf.digits"> + <lhs> digit </lhs> + <rhs>digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9'</rhs> + </production> + + <production xml:id="ebnf.int_string"> + <lhs> integer_string </lhs> + <rhs> '"' integer_literal '"' </rhs> + </production> + + <production xml:id="ebnf.int"> + <lhs> integer </lhs> + <rhs> integer_literal | integer_string </rhs> + </production> + + <production xml:id="ebnf.num"> + <lhs> number </lhs> + <rhs> any valid character sequence that is numeric according to JSON rules </rhs> + </production> + + </productionset> + + <para> 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. </para> + + <productionset> + + <production xml:id="ebnf.bool"> + <lhs> boolean </lhs> + <rhs> 'true' | 'false' | string | number </rhs> + </production> + + </productionset> + + <para> The preferred way to encode a boolean is with the JSON reserved word true or false, + in lower case without quotation marks. The string <literal>true</literal>, in upper, + lower, or mixed case, is another way to encode true. Any other string evaluates to + false. </para> + <para> 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. </para> + <para> Any other valid JSON value, such as an array, will be accepted as a boolean but + interpreted as false. </para> + <para> The last couple of primitives aren't really very primitive, but we introduce them + here for convenience: </para> + + <productionset> + + <production xml:id="ebnf.classname"> + <lhs> class_name </lhs> + <rhs> string </rhs> + </production> + + </productionset> + + <para> 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. </para> + + <productionset> + + <production xml:id="ebnf.field_name"> + <lhs> field_name </lhs> + <rhs> string </rhs> + </production> + + </productionset> + + <para> 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. </para> + + </sect1> + + <sect1> + <title>Query</title> + + <para> The following production applies not only to the main query but also to most + subqueries. </para> + + <productionset> + + <production xml:id="ebnf.query"> + <lhs> query </lhs> + <rhs> '{'<sbr/> '"from"' ':' from_list<sbr/> [ ',' '"select"' ':' select_list + ]<sbr/> [ ',' '"where"' ':' where_condition ]<sbr/> [ ',' '"having"' ':' + where_condition ]<sbr/> [ ',' '"order_by"' ':' order_by_list ]<sbr/> [ ',' + '"limit"' ':' integer ]<sbr/> [ ',' '"offset"' ':' integer ]<sbr/> [ ',' + '"distinct"' ':' boolean ]<sbr/> [ ',' '"no_i18n"' ':' boolean ]<sbr/> '}' + </rhs> + </production> + + </productionset> + + <para> Except for the <literal>"distinct"</literal> and <literal>no_i18n</literal> entries, + each name/value pair represents a major clause of the SELECT statement. The name/value + pairs may appear in any order. </para> + <para> There is no name/value pair for the GROUP BY clause, because json_query generates it + automatically according to information encoded elsewhere. </para> + <para> The <literal>"distinct"</literal> 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. </para> + <para> The <literal>"no_i18n"</literal> entry, if present and true, tells json_query to + suppress internationalization. If not present, it defaults to false. (Note that + <literal>"no_i18n"</literal> contains the digit one, not the letter ell.) </para> + <para> The values for <literal>limit</literal> and <literal>offset</literal> 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. </para> + + </sect1> + + +</article> diff --git a/docs/Guides/grammar3.xml b/docs/Guides/grammar3.xml new file mode 100644 index 0000000000..32b6e22438 --- /dev/null +++ b/docs/Guides/grammar3.xml @@ -0,0 +1,755 @@ +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> + +<article xmlns="http://docbook.org/ns/docbook"> + + <artheader> + <title>Grammar of JSON Queries</title> + <author> + <firstname>Scott</firstname> + <surname>McKellar</surname> + </author> + </artheader> + + <sect1><title>Introduction</title> + <para> + 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. + </para> + <para> + Conventions: + </para> + <orderedlist> + <listitem> + The grammar is a series of productions. + </listitem> + <listitem> + A production consists of a name, followed by "::=", followed by a + definition for the name. The name identifies a grammatical construct that can + appear on the right side of another production. + </listitem> + <listitem> + Literals (including punctuation) are enclosed in single quotes, or in double + quotes if case is not significant. + </listitem> + <listitem> + A single quotation mark within a literal is escaped with a preceding backslash. + </listitem> + <listitem> + If a construct can be defined more than one way, then the alternatives may appear + in separate productions; or, they may appear in the same production, separated by + pipe symbols. The choice between these representations is of only cosmetic + significance. + </listitem> + <listitem> + A construct enclosed within square brackets is optional. + </listitem> + <listitem> + A construct enclosed within curly braces may be repeated zero or more times. + </listitem> + <listitem> + JSON allows arbitrary white space between tokens. To avoid ugly clutter, this + grammar ignores the optional white space. + </listitem> + <listitem> + In many cases a production defines a JSON object, i.e. a list of name-value pairs, + separated by commas. Since the order of these name/value pairs is not significant, + the grammar will not try to show all the possible sequences. In general it will + present the required pairs first, if any, followed by any optional elements. + </listitem> + </orderedlist> + + <para> + 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. + </para> + </sect1> + + <sect1><title>Primitives</title> + <para> + We'll start by defining some primitives, to get them out of the way. They're + mostly just what you would expect. + </para> + + <productionset> + <production> + <lhs> + string + </lhs> + <rhs> + 'â' chars 'â' + </rhs> + </production> + + <production> + <lhs> + chars + </lhs> + <rhs> + any valid sequence of UTF-8 characters, with certain special characters + escaped according to JSON rules + </rhs> + </production> + + <production> + <lhs> + integer_literal + </lhs> + <rhs> + [ sign ] digit { digit } + </rhs> + </production> + + <production> + <lhs> + sign + </lhs> + <rhs> + '+' | '-' + </rhs> + </production> + + <production> + <lhs> + digit + </lhs> + digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' + <rhs> + </rhs> + </production> + + <production> + <lhs> + integer_string + </lhs> + <rhs> + 'â' integer_literal 'â' + </rhs> + </production> + + <production> + <lhs> + integer + </lhs> + <rhs> + integer_literal | integer_string + </rhs> + </production> + + <production> + <lhs> + number + </lhs> + <rhs> + any valid character sequence that is numeric according to JSON rules + </rhs> + </production> + + </productionset> + + <para> + 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. + </para> + + <productionset> + + <production> + <lhs> + boolean + </lhs> + <rhs> + 'true' | 'false' | string | number + </rhs> + </production> + + </productionset> + + <para> + The preferred way to encode a boolean is with the JSON reserved word true or false, + in lower case without quotation marks. The string â<literal>true</literal>â, in + upper, lower, or mixed case, is another way to encode true. Any other string + evaluates to false. + </para> + <para> + 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. + </para> + <para> + Any other valid JSON value, such as an array, will be accepted as a boolean but interpreted + as false. + </para> + <para> + The last couple of primitives aren't really very primitive, but we introduce them here + for convenience: + </para> + + <productionset> + + <production> + <lhs> + class_name + </lhs> + <rhs> + string + </rhs> + </production> + + </productionset> + + <para> + 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. + </para> + + <productionset> + + <production> + <lhs> + field_name + </lhs> + <rhs> + string + </rhs> + </production> + + </productionset> + + <para> + 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. + </para> + + </sect1> + + <sect1><title>Query</title> + + <para> + The following production applies not only to the main query but also to + most subqueries. + </para> + + <productionset> + + <production> + <lhs> + query + </lhs> + <rhs> + '{'<sbr/> + 'âfromâ' ':' from_list<sbr/> + [ ',' 'âselectâ' ':' select_list ]<sbr/> + [ ',' 'âwhereâ' ':' where_condition ]<sbr/> + [ ',' 'âhavingâ' ':' where_condition ]<sbr/> + [ ',' 'âorder_byâ' ':' order_by_list ]<sbr/> + [ ',' 'âlimitâ' ':' integer ]<sbr/> + [ ',' 'âoffsetâ' ':' integer ]<sbr/> + [ ',' 'âdistinctâ' ':' boolean ]<sbr/> + [ ',' 'âno_i18nâ' ':' boolean ]<sbr/> + '}' + </rhs> + </production> + + </productionset> + + <para> + Except for the <literal>âdistinctâ</literal> and <literal>âno_i18nâ</literal> + entries, each name/value pair represents a major clause of the SELECT statement. + The name/value pairs may appear in any order. + </para> + <para> + There is no name/value pair for the GROUP BY clause, because json_query + generates it automatically according to information encoded elsewhere. + </para> + <para> + The <literal>âdistinctâ</literal> 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. + </para> + <para> + The <literal>âno_i18nâ</literal> entry, if present and true, tells json_query to + suppress internationalization. If not present, it defaults to false. (Note that + <literal>âno_i18nâ</literal> contains the digit one, not the letter ell.) + </para> + <para> + The values for <literal>âlimitâ</literal> and <literal>âoffsetâ</literal> + 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. + </para> + + </sect1> + + <sect1><title>FROM Clause</title> + <para> + The object identified by <literal>âfromâ</literal> encodes the FROM clause of + the SQL. The associated value may be a string, an array, or a JSON object. + </para> + + <productionset> + + <production> + <lhs> + from_list + </lhs> + <rhs> + class_name + </rhs> + </production> + + </productionset> + + <para> + If <literal>from_list</literal> is a <literal>class_name</literal>, the + json_query inserts the corresponding table name or subquery into the FROM + clause, using the <literal>class_name</literal> as an alias for the table + or subquery. The class must be defined as non-virtual in the IDL. + </para> + + <productionset> + + <production> + <lhs> + from_list + </lhs> + <rhs> + '[' string { ',' parameter } ']' + </rhs> + </production> + + <production> + <lhs> + parameter + </lhs> + <rhs> + string | number | 'null' + </rhs> + </production> + + </productionset> + + <para> + If from_list is a JSON array, then it represents a table-like function from + which the SQL statement will select rows, using a SELECT clause consisting + of âSELECT *â (regardless of the select_list supplied by the method parameter). + </para> + <para> + The first entry in the array is the name of the function. It must be a string + naming a stored function. Each subsequent entry is a function parameter. If + it is a string or a number, json_query will insert it into a comma-separated + parameter list, enclosed in quotes, with any special characters escaped as needed. + If it is the JSON reserved word <literal>null</literal>, json_query will insert + it into the parameter list as a null value. + </para> + <para> + If <literal>from_list</literal> is a JSON object, it must contain exactly one entry. + The key of this entry must be the name of a non-virtual class defined in the IDL. + This class will be the top-level class of the FROM clause, the only one named + outside of a JOIN clause. + </para> + + <productionset> + + <production> + <lhs> + from_list + </lhs> + <rhs> + '{' class_name ':' join_list '}' + </rhs> + </production> + + <production> + <lhs> + join_list + </lhs> + <rhs> + class_name + </rhs> + </production> + + <production> + <lhs> + join_list + </lhs> + <rhs> + '{' join_def { ',' join_def } '}' + </rhs> + </production> + + </productionset> + + <para> + If the associated data is a <literal>class_name</literal>, json_query will + construct an INNER JOIN clause joining the class to the top-level clause, + using the columns specified by the IDL for such a join. + </para> + <para> + Otherwise, the associated data must be a JSON object with one or more entries, + each entry defining a join: + </para> + + <productionset> + + <production> + <lhs> + join_def + </lhs> + <rhs> + class_name ':'<sbr/> + '{'<sbr/> + [ 'âtypeâ' ':' string ]<sbr/> + [ 'âfieldâ' ':' field_name ]<sbr/> + [ 'âfkeyâ' ':' field_name ]<sbr/> + [ 'âfilterâ' ':' where_condition ]<sbr/> + [ 'âfilter_opâ' ':' string ]<sbr/> + [ 'âjoinâ' ':' join_list ]<sbr/> + '}' + + </rhs> + </production> + + </productionset> + + <para> + The data portion of the <literal>âjoin_typeâ</literal> entry tells json_query + whether to use a left join, right join, full join, or inner join. The values + <literal>âleftâ</literal>, <literal>ârightâ</literal>, and <literal>âfullâ</literal>, + in upper, lower, or mixed case, have the obvious meanings. If the + <literal>âjoin_typeâ</literal> entry has any other value, or is not present, + json_query constructs an inner join. + </para> + <para> + The <literal>âfieldâ</literal> and <literal>âfkeyâ</literal> attributes specify the + columns to be equated in the join condition. The <literal>âfieldâ</literal> + attribute refers to the column in the joined table, i.e. the one named by the + <literal>join_def</literal>. The <literal>âfkeyâ</literal> attribute refers to the + corresponding column in the other table, i.e. the one named outside the + <literal>join_def</literal> â either the top-level table or a table named by some + other <literal>join_def</literal>. + </para> + <para> + It may be tempting to suppose that <literal>âfkeyâ</literal> stands for âforeign keyâ, + and therefore refers to a column in the child table that points to the key of a + parent table. Resist the temptation; the labels are arbitrary. The json_query + method doesn't care which table is the parent and which is the child. + </para> + <para> + These relationships are best explained with an example. The following <literal>from_list</literal>: + </para> + + <informalexample><programlisting language="JSON"> + { + "aou": { + "asv": { + "type" : "left", + "fkey" : "id", + "field" : "owner" + } + } + } + </programlisting></informalexample> + + <para> + ...turns into the following FROM clause: + </para> + + <informalexample><programlisting language="SQL"> + FROM + actor.org_unit AS "aou" + LEFT JOIN action.survey AS "asv" + ON ( "asv".owner = "aou".id ) + </programlisting></informalexample> + + <para> + Note in this example that <literal>âfkeyâ</literal> refers to a column of the + class <literal>âaouâ</literal>, and <literal>âfieldâ</literal> refers to a + column of the class <literal>âasvâ</literal>. + </para> + <para> + If you specify only one of the two columns, json_query will try to identify the + other one from the IDL. However, if you specify only the column from the parent + table, this attempt will probably fail. + </para> + <para> + If you specify both columns, json_query will use the column names you specify, + without verifying them with a lookup in the IDL. By this means you can perform + a join using a linkage that the IDL doesn't define. Of course, if the columns + don't exist in the database, the query will fail when json_query tries to execute it. + </para> + <para> + Using the columns specified, either explicitly or implicitly, the json_query + method constructs a join condition. With raw SQL it is possible (though + rarely useful) to join two tables by an inequality. However the json_query + method always uses a simple equality condition. + </para> + <para> + Using a <literal>âfilterâ</literal> entry in the join_def, you can apply one + or more additional conditions to the JOIN clause, typically to restrict the + join to certain rows of the joined table. The data associated with the + <literal>âfilterâ</literal> key is the same sort of + <literal>where_condition</literal> that you use for a WHERE clause + (discussed below). + </para> + <para> + If the string associated with the <literal>âfilter_opâ</literal> entry is + <literal>âORâ</literal> in upper, lower, or mixed case, then the json_query + method uses OR to connect the standard join condition to any additional + conditions supplied by a <literal>âfilterâ</literal> entry. + </para> + <para> + (Note that if the <literal>where_condition</literal> supplies multiple + conditions, they will be connected by AND. You will probably want to move + them down a layer â enclose them in parentheses, in effect â to avoid a + confusing mixture of ANDs and ORs.) + </para> + <para> + If the <literal>âfilter_opâ</literal> entry carries any other value, or if + it is absent, then the json_query method uses AND. In the absence of a + <literal>âfilterâ</literal> entry, <literal>âfilter_opâ</literal> has no effect. + </para> + <para> + A <literal>âjoinâ</literal> entry in a <literal>join_def</literal> specifies + another layer of join. The class named in the subjoin is joined to the class + named by the <literal>join_def</literal> to which it is subordinate. By this + means you can encode multiple joins in a hierarchy. + </para> + </sect1> + + <sect1><title>SELECT Clause</title> + <para> + If a query does not contain an entry for <literal>âselectâ</literal>, json_query + will construct a default SELECT clause. The default includes every non-virtual + field from the top-level class of the FROM clause, as defined by the IDL. The + result is similar to SELECT *, except: + </para> + + <itemizedlist> + <listitem> + The default includes only the fields defined in the IDL. + </listitem> + <listitem> + The columns will appear in the same order in which they appear in the IDL, + regardless of the order in which the database defines them. + </listitem> + </itemizedlist> + + <para> + There are other ways to specify a default SELECT list, as shown below. + </para> + <para> + If a <literal>âselectâ</literal> entry is present, the associated value must + be a JSON object, keyed on class names: + </para> + + <productionset> + + <production> + <lhs> + select_list + </lhs> + <rhs> + '{' class_name ':' field_list { ',' class_name ':' field_list } '}' + </rhs> + </production> + + </productionset> + + <para> + The <literal>class_name</literal> must identify either the top-level class or + a class belonging to one of the joins. Otherwise json_query will silently + ignore the <literal>select_list</literal>. + </para> + + <productionset> + + <production> + <lhs> + field_list + </lhs> + <rhs> + 'null' | 'â*â' + </rhs> + </production> + + </productionset> + + <para> + If a field_list is either the JSON reserved word <literal>null</literal> + (in lower case) or an asterisk in double quotes, json_query constructs a + default SELECT list â provided that the class is the top-level class of the + query. If the class belongs to a join somewhere, json_query ignores the + <literal>field_list</literal>. + </para> + <para> + More commonly, the <literal>field_list</literal> is a JSON array of zero or + more field specifications: + </para> + + <productionset> + + <production> + <lhs> + field_list + </lhs> + <rhs> + '[' [ field_spec { ',' field_spec } ] ']' + </rhs> + </production> + + </productionset> + + <para> + If the array is empty, json_query will construct a default SELECT list for + the class â again, provided that the class is the top-level class in the query. + </para> + <para> + In the simplest case, a field specification may name a non-virtual field + defined in the IDL: + </para> + + <productionset> + + <production> + <lhs> + field_spec + </lhs> + <rhs> + field_name + </rhs> + </production> + + </productionset> + + <para> + In some cases json_query constructs a call to the + <literal>oils_i18n_xlate</literal> function to internationalize the value of the + selected column. Specifically, it does so if all the following are true: + </para> + + <itemizedlist> + <listitem> + the settings file defines a locale; + </listitem> + <listitem> + in the field definition for the field in the IDL, the tag + <literal>âil8nâ</literal> is present and true; + </listitem> + <listitem> + the query does <emphasis>not</emphasis> include the + <literal>âno_il8nâ</literal> tag (or includes it with a value of false). + </listitem> + </itemizedlist> + + <para> + A field specification may be a JSON object: + </para> + + <productionset> + + <production> + <lhs> + field_spec + </lhs> + <rhs> + '{'<sbr/> + 'âcolumnâ' ':' <sbr/> + [ ',' 'âaliasâ' ':' string ]<sbr/> + [ ',' 'âaggregateâ' ':' boolean ]<sbr/> + [ ',' transform_spec ]<sbr/> + '}' + + </rhs> + </production> + + </productionset> + + <para> + The <literal>âcolumnâ</literal> entry provides the column name, which must + be defined as non-virtual in the IDL. + </para> + <para> + The <literal>âaliasâ</literal> entry provides a column alias. If no alias + is specified, json_query uses the column name as its own alias. + </para> + <para> + The <literal>âaggregateâ</literal> entry has no effect on the SELECT clause + itself. Rather, it affects the construction of a GROUP BY class. If there + is an <literal>âaggregateâ</literal> entry for any field, then json_query builds + a GROUP BY clause listing every column that is <emphasis>not</emphasis> tagged + for aggregation (or that carries an <literal>âaggregateâ</literal> entry with + a value of false). If <emphasis>all</emphasis> columns are tagged for + aggregation, then json_query omits the GROUP BY clause. + </para> + + <productionset> + + <production> + <lhs> + transform_spec + </lhs> + <rhs> + 'âtransformâ' ':' string ]<sbr/> + [ ',' 'âresult_fieldâ ':' string ]<sbr/> + [ ',' 'âparamsâ ':' param_list ] + </rhs> + </production> + + </productionset> + + <para> + When a <literal>transform_spec</literal> is present, json_query selects the + return value of a function instead of selecting the column directly. The entry + for <literal>âtransformâ</literal> provides the name of the function, and the + column name (as specified by the <literal>âcolumnâ</literal> tag), qualified by + the class name, is the argument to the function. For example, you might use such + a function to format a date or time, or otherwise transform a column value. + You might also use an aggregate function such as SUM, COUNT, or MAX (possibly + together with the <literal>âaggregateâ</literal> tag). + </para> + <para> + The <literal>âresult_fieldâ</literal> entry, when present, specifies a subcolumn + of the function's return value. The resulting SQL encloses the function call + in parentheses, and follows it with a period and the subcolumn name. + </para> + <para> + The <literal>âparamsâ</literal> entry, if present, provides a possibly empty + array of additional parameter values, either strings, numbers, or nulls: + </para> + + <productionset> + + <production> + <lhs> + param_list + </lhs> + <rhs> + '[' [ parameter { ',' parameter } ] ']' + </rhs> + </production> + + </productionset> + + <para> + Such parameter values are enclosed in single quotes, with any special characters + escaped as needed, and inserted after the column name as additional parameters + to the function. You might, for example, use an additional parameter to provide + a format string for a reformatting function. + </para> + </sect1> + + <sect1><title>WHERE Clause</title> + </sect1> + + <sect1><title>ORDER BY Clause</title> + </sect1> + +</article>