[open-ils-commits] r13102 - trunk/docs/Guides (kgs)
svn at svn.open-ils.org
svn at svn.open-ils.org
Fri May 8 15:54:40 EDT 2009
Author: kgs
Date: 2009-05-08 15:54:37 -0400 (Fri, 08 May 2009)
New Revision: 13102
Added:
trunk/docs/Guides/compugrammar.xpr
trunk/docs/Guides/grammar.html
trunk/docs/Guides/grammar.xml
trunk/docs/Guides/grammar2.html
trunk/docs/Guides/grammar2.pdf
trunk/docs/Guides/grammar2.xml
trunk/docs/Guides/grammar3.xml
Log:
setting up guides sync
Added: trunk/docs/Guides/compugrammar.xpr
===================================================================
--- trunk/docs/Guides/compugrammar.xpr (rev 0)
+++ trunk/docs/Guides/compugrammar.xpr 2009-05-08 19:54:37 UTC (rev 13102)
@@ -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>
Added: trunk/docs/Guides/grammar.html
===================================================================
--- trunk/docs/Guides/grammar.html (rev 0)
+++ trunk/docs/Guides/grammar.html 2009-05-08 19:54:37 UTC (rev 13102)
@@ -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>
Added: trunk/docs/Guides/grammar.xml
===================================================================
--- trunk/docs/Guides/grammar.xml (rev 0)
+++ trunk/docs/Guides/grammar.xml 2009-05-08 19:54:37 UTC (rev 13102)
@@ -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>
Added: trunk/docs/Guides/grammar2.html
===================================================================
--- trunk/docs/Guides/grammar2.html (rev 0)
+++ trunk/docs/Guides/grammar2.html 2009-05-08 19:54:37 UTC (rev 13102)
@@ -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
Added: trunk/docs/Guides/grammar2.pdf
===================================================================
(Binary files differ)
Property changes on: trunk/docs/Guides/grammar2.pdf
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: trunk/docs/Guides/grammar2.xml
===================================================================
--- trunk/docs/Guides/grammar2.xml (rev 0)
+++ trunk/docs/Guides/grammar2.xml 2009-05-08 19:54:37 UTC (rev 13102)
@@ -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>
Added: trunk/docs/Guides/grammar3.xml
===================================================================
--- trunk/docs/Guides/grammar3.xml (rev 0)
+++ trunk/docs/Guides/grammar3.xml 2009-05-08 19:54:37 UTC (rev 13102)
@@ -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>
More information about the open-ils-commits
mailing list