[open-ils-commits] r13105 - trunk/docs/Guides (kgs)
svn at svn.open-ils.org
svn at svn.open-ils.org
Fri May 8 15:58:36 EDT 2009
Author: kgs
Date: 2009-05-08 15:58:32 -0400 (Fri, 08 May 2009)
New Revision: 13105
Removed:
trunk/docs/Guides/compugrammar.xpr
trunk/docs/Guides/grammar.html
trunk/docs/Guides/grammar.xml
trunk/docs/Guides/grammar2.xml
trunk/docs/Guides/grammar3.xml
Log:
removing extraneous file
Deleted: trunk/docs/Guides/compugrammar.xpr
===================================================================
--- trunk/docs/Guides/compugrammar.xpr 2009-05-08 19:58:02 UTC (rev 13104)
+++ trunk/docs/Guides/compugrammar.xpr 2009-05-08 19:58:32 UTC (rev 13105)
@@ -1,259 +0,0 @@
-<?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>
Deleted: trunk/docs/Guides/grammar.html
===================================================================
--- trunk/docs/Guides/grammar.html 2009-05-08 19:58:02 UTC (rev 13104)
+++ trunk/docs/Guides/grammar.html 2009-05-08 19:58:32 UTC (rev 13105)
@@ -1,151 +0,0 @@
-<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>
Deleted: trunk/docs/Guides/grammar.xml
===================================================================
--- trunk/docs/Guides/grammar.xml 2009-05-08 19:58:02 UTC (rev 13104)
+++ trunk/docs/Guides/grammar.xml 2009-05-08 19:58:32 UTC (rev 13105)
@@ -1,291 +0,0 @@
-<?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>
Deleted: trunk/docs/Guides/grammar2.xml
===================================================================
--- trunk/docs/Guides/grammar2.xml 2009-05-08 19:58:02 UTC (rev 13104)
+++ trunk/docs/Guides/grammar2.xml 2009-05-08 19:58:32 UTC (rev 13105)
@@ -1,227 +0,0 @@
-<?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>
Deleted: trunk/docs/Guides/grammar3.xml
===================================================================
--- trunk/docs/Guides/grammar3.xml 2009-05-08 19:58:02 UTC (rev 13104)
+++ trunk/docs/Guides/grammar3.xml 2009-05-08 19:58:32 UTC (rev 13105)
@@ -1,755 +0,0 @@
-<?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