Date: Fri, 8 May 2009 19:54:37 +0000 Subject: [PATCH] setting up guides sync git-svn-id: svn://svn.open-ils.org/ILS/trunk@13102 dcc99617-32d9-48b4-a31d-7c20da2025e4 --- docs/Guides/compugrammar.xpr | 259 +++++++++++++++ docs/Guides/grammar.html | 151 +++++++++ docs/Guides/grammar.xml | 291 +++++++++++++++++ docs/Guides/grammar2.html | 56 ++++ docs/Guides/grammar2.pdf | Bin 0 -> 15319 bytes docs/Guides/grammar2.xml | 227 +++++++++++++ docs/Guides/grammar3.xml | 755 +++++++++++++++++++++++++++++++++++++++++++ 7 files changed, 1739 insertions(+) create mode 100644 docs/Guides/compugrammar.xpr create mode 100644 docs/Guides/grammar.html create mode 100644 docs/Guides/grammar.xml create mode 100644 docs/Guides/grammar2.html create mode 100644 docs/Guides/grammar2.pdf create mode 100644 docs/Guides/grammar2.xml create mode 100644 docs/Guides/grammar3.xml diff --git a/docs/Guides/compugrammar.xpr b/docs/Guides/compugrammar.xpr new file mode 100644 index 0000000000..6235c751e1 --- /dev/null +++ b/docs/Guides/compugrammar.xpr @@ -0,0 +1,259 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/Guides/grammar.html b/docs/Guides/grammar.html new file mode 100644 index 0000000000..36587da957 --- /dev/null +++ b/docs/Guides/grammar.html @@ -0,0 +1,151 @@ +Grammar of JSON Queries

Grammar of JSON Queries

Scott McKellar

Table of Contents

Introduction
Primitives
Query

Introduction

+ 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. +

+ Conventions: +

+ The grammar is a series of productions. +
+ 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. +
+ Literals (including punctuation) are enclosed in single quotes, or in double + quotes if case is not significant. +
+ A single quotation mark within a literal is escaped with a preceding backslash. +
+ 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. +
+ A construct enclosed within square brackets is optional. +
+ A construct enclosed within curly braces may be repeated zero or more times. +
+ JSON allows arbitrary white space between tokens. To avoid ugly clutter, this + grammar ignores the optional white space. +
+ 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. +

+ 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. +

Primitives

+ We'll start by defining some primitives, to get them out of the way. They're + mostly just what you would expect. +

[1]	+ string +	`::=`	+ '”' chars '”' +
[2]	+ chars +	`::=`	+ any valid sequence of UTF-8 characters, with certain special characters + escaped according to JSON rules +
[3]	+ integer_literal +	`::=`	+ [ sign ] digit { digit } +
[4]	+ sign +	`::=`	+ '+' \| '-' +
[5]	+ digit +	`::=`	+
[6]	+ integer_string +	`::=`	+ '”' integer_literal '”' +
[7]	+ integer +	`::=`	+ integer_literal \| integer_string +
[8]	+ number +	`::=`	+ any valid character sequence that is numeric according to JSON rules +

+ 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. +

[9] + boolean + ::= + 'true' | 'false' | string | number +

+ The preferred way to encode a boolean is with the JSON reserved word true or false, + in lower case without quotation marks. The string “trueK”, in + upper, lower, or mixed case, is another way to encode true. Any other string + evaluates to false. +

+ 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. +

+ Any other valid JSON value, such as an array, will be accepted as a boolean but interpreted + as false. +

+ The last couple of primitives aren't really very primitive, but we introduce them here + for convenience: +

[10] + class_name + ::= + string +

+ 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. +

[11] + field_name + ::= + string +

+ 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. +

Query

+ The following production applies not only to the main query but also to + most subqueries. +

[12] + query + ::= + '{'
+ '”from”' ':' from_list
+ [ ',' '”select”' ':' select_list ]
+ [ ',' '”where”' ':' where_condition ]
+ [ ',' '”having”' ':' where_condition ]
+ [ ',' '”order_by”' ':' order_by_list ]
+ [ ',' '”limit”' ':' integer ]
+ [ ',' '”offset”' ':' integer ]
+ [ ',' '”distinct”' ':' boolean ]
+ [ ',' '”no_i18n”' ':' boolean ]
+ '}' +

+ Except for the “distinct” and “no_i18n” + entries, each name/value pair represents a major clause of the SELECT statement. + The name/value pairs may appear in any order. +

+ There is no name/value pair for the GROUP BY clause, because json_query + generates it automatically according to information encoded elsewhere. +

+ The “distinct” 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. +

+ The “no_i18n” entry, if present and true, tells json_query to + suppress internationalization. If not present, it defaults to false. (Note that + “no_i18n” contains the digit one, not the letter ell.) +

+ The values for “limit” and “offset” + 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. +

diff --git a/docs/Guides/grammar.xml b/docs/Guides/grammar.xml new file mode 100644 index 0000000000..2601682f90 --- /dev/null +++ b/docs/Guides/grammar.xml @@ -0,0 +1,291 @@ + + + +

diff --git a/docs/Guides/grammar2.html b/docs/Guides/grammar2.html new file mode 100644 index 0000000000..163431bf89 --- /dev/null +++ b/docs/Guides/grammar2.html @@ -0,0 +1,56 @@ + + + Grammar of JSON Queries

Grammar of JSON Queries

Table of Contents

Introduction
Primitives
Query

+ Scott McKellar +

+ +

Introduction

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.

Conventions:

The grammar is a series of productions.
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.
Literals (including punctuation) are enclosed in 'single quotes', or in + "double quotes" if case is not significant.
A single quotation mark within a literal is escaped with a preceding + backslash: 'dog\'s tail'.
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.
A construct enclosed within square brackets is optional.
A construct enclosed within curly braces may be repeated zero or more + times.
JSON allows arbitrary white space between tokens. To avoid ugly clutter, this + grammar ignores the optional white space.
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.

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. +

Primitives

We'll start by defining some primitives, to get them out of the way. They're mostly + just what you would expect.

[1]	string	`::=`	'"' chars '"'
[2]	chars	`::=`	any valid sequence of UTF-8 characters, with certain special characters + escaped according to JSON rules
[3]	integer_literal	`::=`	[ sign ] digit { digit }
[4]	sign	`::=`	'+' \| '-'
[5]	digit	`::=`	digit = '0' \| '1' \| '2' \| '3' \| '4' \| '5' \| '6' \| '7' \| '8' \| '9'
[6]	integer_string	`::=`	'"' integer_literal '"'
[7]	integer	`::=`	integer_literal \| integer_string
[8]	number	`::=`	any valid character sequence that is numeric according to JSON rules

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.

[9] boolean ::= 'true' | 'false' | string | number

The preferred way to encode a boolean is with the JSON reserved word true or false, + in lower case without quotation marks. The string true, in upper, + lower, or mixed case, is another way to encode true. Any other string evaluates to + false.

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.

Any other valid JSON value, such as an array, will be accepted as a boolean but + interpreted as false.

The last couple of primitives aren't really very primitive, but we introduce them + here for convenience:

[10] class_name ::= string

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.

[11] field_name ::= string

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.

Query

The following production applies not only to the main query but also to most + subqueries.

[12] query ::= '{'
'"from"' ':' from_list
[ ',' '"select"' ':' select_list + ]
[ ',' '"where"' ':' where_condition ]
[ ',' '"having"' ':' + where_condition ]
[ ',' '"order_by"' ':' order_by_list ]
[ ',' + '"limit"' ':' integer ]
[ ',' '"offset"' ':' integer ]
[ ',' + '"distinct"' ':' boolean ]
[ ',' '"no_i18n"' ':' boolean ]
'}' +

Except for the "distinct" and no_i18n entries, + each name/value pair represents a major clause of the SELECT statement. The name/value + pairs may appear in any order.

There is no name/value pair for the GROUP BY clause, because json_query generates it + automatically according to information encoded elsewhere.

The "distinct" 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.

The "no_i18n" entry, if present and true, tells json_query to + suppress internationalization. If not present, it defaults to false. (Note that + "no_i18n" contains the digit one, not the letter ell.)

The values for limit and offset 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.

\ No newline at end of file diff --git a/docs/Guides/grammar2.pdf b/docs/Guides/grammar2.pdf new file mode 100644 index 0000000000000000000000000000000000000000..cc42294a17bd5c000aa045fc3919e6bea3963786 GIT binary patch literal 15319 zcmd6OcRbbK|F|NgkdcwfB}B%Z?nOpsvNze{8o6BK+99&CitN2dLLxJSkYvl=J2N4x z^t+dK@6YG^{yiSw$K&_&$MHDNbIx;}=Xu`qd_K>MRY^jM8_WYEVSSwUB%cHZ00Gdq zZj%TKk^t2#FeoH|{kolzm6eel0Bs78QB_m`C_5nSERgmbBtTIIj5*p4z^-bH#$W*Q z#5uKLiD#xWstEIzuu7FRTk$L$Lj~OnZ zW+R~-mPHIPYJ5tAEkKY*xM#WO? z&{kKH0e1JV^oRu4;eAbxsJO`t##4$3p8vQrs7p`V!Y8Dez*?r*5>pD3ZwJY=GvD-v zXgsq2$fa}VQ!J94e*@wpNZ)GTK85@+Gje%4grBk|ILwfqcAj{r0#d_fd=GQO?^+Xj zrilKI0vwM$e1vDtUeyG}Z5+-H@#da(!JCk7G5F98)Oy=N)k@yj{#KiZk|jHUo=sQP zFXRzb&}2u4{CrU3TM!u{q-pD|w@;N#~5S#ev{u=jfE zeU1;`c8t>Z@m!^sVBBf=r0Ee$iuW`N`FwEC-^$`Fp5D?irK&IfZH7R+z-KiMWbU>X zEAQy5yqe-Ny!Slde`^AtC@)1gu`x;AU%yzz)H90L~DM_8M>W=Xty z-9BZrdwMR}e}|Fiz~Led#b=h90APfqL~E8DKrZUJ&TFcG6R~1`*LITQcE}qJG6pN6 z?hoxybVg|%&ty7x&Ep~-`xOenNjDSD&NcT_P1o^v+k(1cV-oi}ybs(p%jFJU)3A7k z8ef-ylv66VFUNh>J`MxmNnXQWyvDGAPxX?Z^d&_(9{B|RaZ&aF0$W4ygg5oWV-f&b z>buWV=pwxH4KL>qI;2p*?!j&7FkZ$JFg_w4uU12Xkz*<#vZT8lA4uL_JLBW~`pj7s ze+)qU_4#MMS`Qg!@K1`Nw{Xsiq4$3+$M4m3XA$Whu($ zlzV4gi7tUoX4Ppwr9ho1HdN#z4)vj}Yxw}-W90EJdl_kif9K4qk77gg1cerfh*vhn z-7^#dX+a z65dNS4hDzPdCHw?{sraOnYCc@#*GiH>&P9cJLDe3BB9Al z>{P)g3w)%-t{8ErhIdNw$(GAHi?UE|1t`3-NxNI_r*%V6LQwHMYYnTiv?&Xm!;6K< zifQF?BJ(J7HQ-T;lnJ?=;7z$PF>AJDrt!0QakoJFmRfwlN^0WcYVm!aPZ?zD&GOe%ipA$M+Kv548XkqU=a_7QvoO34UmRE~ zw<_;dLS36&m0f*ZS6sI@PwsJjVfk`luX<0FP=Jt$@C0E#VHxSVA6El)gPz|Pzrv8< zkXylUItO|ohz67l)Q+&`t+5n?+ahk7b{pEYQ5(O3$U{f1TnA6XixINmJTL>qzwN@? z6LVE<{@k533N&Itgh32)ls%7P8&Jql?QZUS+^4v!xRP(uYc=Xv6)%?UnOmU~tw+t> zoBeK4nX8)j7;og|$8z_VHhmh>{ir)$kvH$y;cjha-CQyznA_|dth>2HcK{6HmEh-rD?vh@n_31K+vTAD;Cq1W7w|o2e?eWapYao)_&f)9=$~E+i}L zN11(+`NV;KHQZ74%B|CXifUGM#eQ6~12I_k&go6Z7}|H7!?VQm;aB)qhGW{tM()nt z&ArzAGSbUkG$ZAN=sQtz?>2AAIw2+-X~Wl_9#(CT&Yzlh^7Zb#+qsguT_4;KB4O_gUP82d%Gq*CYNyJLrNOMg;n@*J$pKj3X+#Jy?ZJd8g zvq?X&CxGgeL$mR8`gHtMHtinQNQI4Hop37O$ z;QQS7*Z5Nt2-`Qi?`A%i%`Qi+@~l!N5uu6D;cIVz^NK7LY>}6RWE|zkk_2O?l2pPz zs=cI9JC&5Zm))0Hqi{-oIQbKY5L>knesoxjt(r7N*2#UybLa-dzxZu&U~xukLiCC* zoRx%<7b!j%^sK58HrUa7_m#vmeMsDNlobdp^X2yIv~_))&~@<;cLT756= zI=wEP6rHD~hM3IxH+$-xk2CXJHJ1u`w1sM#&~0ANeV$ubda{@BZ~^aB@R;f;hG}%g zr4?;?Ea?QD4U}v|z{^oN!vRC=1AOHct67ib8D*VWX=U?eIc3JtbJjIGk!_lh2JS=Q zCCI05Q&AlnZ#5?SmWD^lF0gCzbO0HLFFvcbCo;a?5*mFqdijNtk*0E4&{NrGvfA{z zgL+7%=g$}29b~qoLp0^x@=aH=hWe{qstT9a2YNKJ)it%ZtqTp;+FWb*+6mMB0^MWW z`S&lvr4XMy+x99eZlvdyyl?QB^my+TfbZTG+SbM$$BoRl$;)u~Xjos@I_~V*Gunj8 zLuZ#oUp(&5;(yUIerIK?LDb*v!PC$Zce5QmE28J=8B~k9WBl(TyIEI4mo5sQb1o@s z&di>6YhBxB>=Dwi*PV49JXwD~jVf7TE;&Is(qZxa`5(!`w9hC&c!BV$|9SsP;8nd<`Xt1i zslffn9?j~)q$(PlmG0M{!zP!M`_W_4+W4O9x1vkg8aJa@nV5#*Qn8_U1H--r4I(wD(KzH+VPhq@4PVK;^K->#-=E;dL2P#%dfGBLs!;Vz}B4!1CeKrMN>UvI6@!&~dm z>#3lKGxi#7iNpYIAYMB8RCPK`byz(G<8*!w$g|w?3Qq@&K&Dhn_nBRn1 zL|D*Sz}d>i3QJBHiyI(lXJRU#A|Z9y`K1qVwnACk3z!%SF`HvBHUdDPje{ME2W@8t zG%*GuQAjJKHO3wY<^cnl0XQ5+x6lq4A!g?9h;X<}j0G^bKtlLG#1Vp6T;FEkcscsR ztuj6eB7}dBE)J)EANqX(R&~frxAos=eOvuMiGVepe-^>n$ObC{ z=)Z`7T`F)G9wKp3+<)7EKW6?S*pCskof;aA68@J_rXcXog@54ue*XRqXTQz;N45Q; zL@ec>2kz&I#rg^%W;^V8{M&zk!9V=N&xjQloU8m}ybAc~5S$a*v~|!Ua2k*8!ZRNs zs!#G|dWEhrc8|i$DNqOo+D2vux)Q%><-9Pq%7LxYFKce>_j^;NEoKDBMS(OTf&TLz zWVyE7LEHE6)&UxW3rIOgcU)I7`ubiiq6?l}r#ieX{`l=%s-66>2Sh zgL@YPoV`WfRDp!GL=32DL$~Ip8m>E=nejheove>#8VhsvTqj$HzrgD-p!6KqH@Ndf z&#)rYp_)^F-b)h7CRc6KDkF@;2FM6S@N+J=%u_35HFz+bcrUr| zwf*C=IoH(~aUD^W+tq*YaZT+B13M+suaDhGZ^!7ghyKwMLJ>?fiJ*D#>eY zQH%9~Yy#j@{vN>ar=+<-1#!zyxk$-3B`3oS&TRH}T2tV4q^#WF^Q^}f#g;ioz}V+EfeDokeyaGowVsjN4e9v>HW>&6=&Yf$6My-#MfF8u6zZ5 z9@VvqT6r3^`Qk$Tb9zCo(gw;4z-OZ`9nL%5@~@kWI!)oxe!fOS<2>;=u_|Ajtu86k zxhac)LMAUipL3KJ(odLL=*@0&9=s^tBz;L@b}~8!=-jo2&%<@}?D@sHRQ0BCXC$NAFgFM);K4Tz|zq+h;sCC~FP2HoQpX4T$}# zSAY&TNA3nbzD}T#Qu5>$uQ$7XuWvwb0@?B5l4Z);o|HQAsOjk8%1oC~CxX!;Dt*ze zjqFm?tHCsU33KMv4;XElZJUf(W2phjHPC1FkV&}_=y+lC&mWh~Wh!S!dBnizWS%;(&@Rl3#_d{(}6K5TUU)w5%cvbJ33 zzBsyFeSNk3vEb5JX&P(9n<+KF?5bt`CzfPW_wCh|Sxyj_z|ptePMbX!lK{`$L?a`m z+tu#dzX~vGPMSnvbfWmv%|frME+(hm5|rE_b!O`s8W(D_ByFUZ@RmKHY&xF}D&Y~Q zx?K8&1#`Z;uu}N-?ODeY#M*f)xwqUj)KS@rLazamDW_?DL@#hT5e}*OXH;ZU89PXv zel5%Di~oqunBx_@1YX{1$TLw%-iL%&m&|Xz*E0JodykH=>*Gf+dg+V^Gg)Kzmhe=>@FBpxtms71hRV7$!E)aPfPh5yd*OzS&6Y3mw zww}zam(8*pPf~cIGQL2aE!ItQ@AV+MyHcqBxxiqyh97nKf>*AIl;T=*cgue22lS}M z#V*(-nU|bhx2?N8ZhIKMFuhhs6`lC3Xz4{O+=_0;@l4|l%1wqE%4aT<12S9q=I0(X z+xd_BOdD6+J7z9eD={ssY!sKHUvN zkY_HSr}4PDo@Y+p6(36I=l8lY}#z_muJLs5TMX%-J00ydO!0t>e$N#(rwEce#4*32I!|titoEEO$}0iEF1~ zUFDX%=mS)RdpxD5$Nndl$$s5(!TS@HpISFky~ATXXO>m#AC{z0DX5JyY0>0)NJoZ! z%$Ms-eJ&%)rf|tu;VkehYB_tasHum!QGv`s|HA5kFsDi80@&pRul(B-Gum3>v>=&Y1n9mVaAuqYw@80xrG)_8M>FepR1M2shl6$Je z1;LxIim3V>bT#i|!gB(tVm{zOR-{^BP4_7$2pXB`@x$b%<0c+5%SZqpvcH*H6wZsI zL5~$Z(7&F*X)CX!WI4P&`Q$|Q+L=dvu*lSamL-eVnaHt=l2`BbEjP0Z#dz~^PrlVj zep8Pr6yV9#B9pHyS6JK#QYv_Ij3X0b@)a@fDzH` zC9nIAc4NJ>9tOp=5+e@n!!AT=X1-mKy&GBgYuv_~BwZd=*se#vrg~QyFVgX)ewM?l zsz8W%5;eJF9e!Hy#evmlHiy}v9pVA)tTtbO!H^F>rOJ(E?8!LLfTWA``C$E-mz{!7PXy7k?xD9miPP724BBuXY~5Pmx<$pmgT^aaLd0$xYmA{J3R6`NR(bvc%E2Zi){2|XtnG+%biYPd=T%Y1&>(JX}^Q=I}@kxlnT?U zxpMvC;A}&Uo{g}6XmGGW$h}q9{8I>@U=H60e(}S$Z$G|}n$F$bi|%~DNx5muFZ}_@ z%P4C0@kPhhjkxuv^547zyc00 z+bX!4&-dv3usDRPAVGNf;Xi;lCUHQ1IPVYG_ktM&&d>h?_&xd;6#OobsI@g3L-I4K zm$R_8B*DsWi~;CiOHm*m5CD#V@W8+b02t2C1A_tJeAw^~+ttIC)39@J@`G?4F|?ft zwp#TIL=*r%%q@@rr2)VjB)`M*RSG{=c$L4E0{JzxIx@Hax;sZo!O=cq;5W;dhGWV(MaX;fq0A2gKEi-dO+n`(7eC6#{ufOeynHS{z3D0 zq33SJ*WE>xgx0iGqGq@#RP}^Ko=x1DH)Nb05f}POSBF1a8@#nVs1$%V7R4^=yab=M zh_$IFHqw(EzYuT#yc!kvOyJY3lvN_D*qJ;5PLp$P3LLTl@5_r`10_$&OW%I>%%#X= z43G7=W}Bfpblp%rG%u_Cv7b79gF0)$I$~%UU{ZZ9|Ov-G^?xXsy93i zpL|TI*=Ui;mrtD?IaLBl(D3VdW1~&4AUjz?jcZ^EveP9nxmJ_O#~^MgL+#*~C3L

xMy*au!qu_OMIf} zv{y5P;9~2UIkg0t^rytd?yy^I5^+z1sRV$Mw4^!kGjofdw{rtdK)X87B>7f|G5FkSAi^0;mwDYFv51;a2$?&n@$b=n&jKj*UzlkvYw+Qlw z{AW^(bbsStho(+m(nghHM2!G(_8SFQyZo7icmN+l)W+I-YJ{M%;$)yb74Qz(l8Py0n@VJ+y?yjvhx>X5)um*LPA?7+F(%Ks&gJB&Gh9r}E6a*W)bf!7BR;DI zNybWQwyj+3h9cbL6un(ZdZ1-4a*B6d>9el4oxP|wlfxX~L;3JNY2v*=z*!klt_Uw( zcKkXezwk+R`p~0>f}P$g9NXLv55qM#lp!24Y?3V*?6Id=AElZ=B7((Q*l~?{M6eXD zA#4F14>uxUX&{#NQ+{|l9Y8N73JLZyp~G(h5r%__&MSqboAAl_rJE4QNTuMKG!vGi z<_ItK5negJaAkIS-=n6BojxSI3qY@M4U%xzgzs334N3SUHA@4Bw4dt3(`EqrcI-gv z5n8@)Xn)165+N6eB) zIER1cf9fzWMC67BHOY5C+JlOebUP1n1GY#C5$Zjgg^;f$yQu?fE3G|Nv7c5f!%cMC z4MN!FZoj5V3|oJ`^pc@%5|O%Mf9c9>&((KT2O*2|O?jJ%I^&x2;$vL14YK_OPX;5m zRQ4un2v<#KvU@6A4dNDqt`$YE#ZQ%Um$oJper!vQ-rMciWmS4#blYxt!z6Yqd9lb@ zli*E+*MYCA%0;3_G=LQ-_o~*MxUGF^c3%e8ij7UQfe z?zhj1JLvO>zZ3SF4qaVZRD#VK#lY+9l9T0~TAdoPar+qJ)TD96IMAnQz+L}hH19H3 z*j+vYjfCWA8q}v~@h>G@2EJT;v|G<|?<%i?0?B#sFVAORG1PWIn|_ivpYh$4s-eH* z15IjYF9;dTnp|%^-O$Xq802tl*1&kO=v@E7mIX%F!RA~HLte$gpnssYaZN$!TA*>> z0dt0RGC$L;4?!4Zq|BT^`l-$8z6H|0-Okj5hO-Am><3LAZfDcp4vc%A_3`D3<8Tu#*jl0(d7=g_s!41 ztDYinPeJ=Nmk>=Mbebi+?QhQ}^EAubTO>BccZ>vgMLM+9Qx`0TIdL+4R*9}Gkbmb^ z*f}hVgzqjfXu_w+)YeftdaGjUf*Wr}s&eJ^-A>39_OFDNoCoGsuRm_}Pmg8vv!OCc zF;5FYs8y=ciV{LIfz2mDAu_}9ceIaNPTxK_U!6N@Zc2q2_e!WrPaB)b_L9`G(`aA5 z6n{&sx&~^N?V8+QMO!`Lsw4Em#a>8lU}p9}px0r4f*)VSIvWD2=$o4$SE^3^)5 z=k~!&F26#`qX_+c2cvf6N>cfGV4Ump>@wrm#k>iDA_Lv-A)c7{%+7(&B@qg20%9FX z*M;MjG^?ol(l0w?KI%HQ;n$9izUg#~N^zE>ceQ7-V5q+ZG7mSIGu4cYpRj?>l5XpD z3DWpZmo9bL(tg4-g$Fr?kOigdqITZdeuY`nJr|0wZh9x|94=3xs~FA_XtO_Y!&3H~ zt|CrbrJvhcwp(h5a>wQa?N}-6 z@S~~~B7Apjceeo5zPoD?yH(EVpZ<)qKyjB1@X0hUzDv!MrrFkkkG@R(WrCA>g5J0)^*OP2&Doi~7r~2}d^yZCREHx=T(Wk zb=WhFRc4!}*qz>5ZL?xhTKl46`k4GvvBXf}dpQYs zWUSPqT1CyJ{<*i>d=_S&GAnW83bqe=-(N4(u6k1{o?La|S$*kcg-Q&S0_>85(7v>x zMOZE66O&37qD7R{c4yY(PP*p?>#I1RIZ*d8}=J z*_oMFEbE@VR+>x~M`*|A|D>5!#7U^JhHqd^hEOOpcDO!?V=ts5G3Qf@k{f-2pYblh zW%pgj_)hre@~so?^=qurt{R2K2BGr&!*fJ=j*0}yRM9wTQ*^_;*y986fWM7T>lWZ@`UcO}3 zBu6xAp_4RMFkC-=5Lv&xeli<1GEbXqMf^2{xlOu0pjR8y=)qlZT_jzSxvJyFlO;A0 zgzUO=qm7B)rbV!Od8FF(R#RA#lsGyncACY>gk16^CDg+|v!s$h?fNH=^~_FPvqzbm zeeq2SO{tIL-3_lDl=mLvyx8m<&FTJ_Cp9)ZhUk4!<+A@H7usD$)7Py!^BeV6H)3es-AXd_MaV;5w{xXul0$rwR$pAsjv5ik^Rmc zDqL#h_ZJe_DE=s$qC)~c4DLt{vlS{Nhlv90zoR@2a030FSb`koWqwI49mcV^91;}92l<{ag8Y=`XTW=yz4#Z!UUfaiVGy-@N8wZF zn^(Mw64&}~PfT7yyp&wlgHgz(49nDgq1W{E5nT_9EV8GK%*s?G41H|FU)?_5 zG^8+=4d+jak_&nm69?bgez%`nSJwum8rFECu|7vIYe^NM-oWL{${9H1mQk~N}IU3F^ z_r$uC`+{s{f~Ef38G#(c12Ev&)rchMkH6YCvR61 zkD+z4n^{T>Ro>?@_UhOB$4Wwzb9^bpOm5pR6M@vI*a=oSxzB0nutAh#7nl-3Y#Mk3yn!;ALIHfi6C=zb}ev6{8oD|g!1{a8;^bH!Y>c&~RV{w3p9e&}#izRAIx zz%Q)t-UK-^G4>J-5N#YQ*Byy5|5q#YsN{eTQ-mIf! zrKMZh`n~y`_rZIGa>2O_^PXzp(reYGemWo6cFGQDoT=V1^4+=o72inL=E2{-0`lEg zU_VRv|0ivHcx-=58$)o17I(T4kRKUhC@$lMgB@np{)bO00KjiaYUsBtHBbTRi~&Fo zUw)7PfT92>E{%#K3i$TY>~QQ4{AxzGuwQOqKiK%5;^x4v{S&j29nukS$Q{;ceWP>a zuMX)P`Q2aW{F;^f_G!osYs}%xAq@7TjQ>pHJM%}P9Qk@2iEml!Ur79xH$PI95;mJ} zfw6GJeQ@%hWcbeY5rJ=R7)RhJ1N;ktpLT@JK_3yoea_S>HqI)K zQpr--q5`h>x~eFusJ91)N}ni@HvFe=x@07nLl)zeQ^{WK-) zxp%O_Di?%Zhou2v2Xo+5iq+G%KIEtm`QC>f_7C;`L-9W~|J_bRjd30UTkZk?ucOt_ zBtQv(&bOTdYTeWZU@Ki902B`8fr1eHd;n_)6iV+G{tg|(50`fM3ih8c9$Casgm5s7 z2ZVt0BmPGCtHej9{BIC~d7(TAC=6R-`IEy#FZ_ScA(lBFKE8iI_v;~$vaqwq+C5II zIL9n!gzFud=`X(L9|}kRp!7dggn(fyjS&8SP?578(v$=QfPqOsKmM?lC0-~mz!Y!< z14CgjETgzTfb|a;FBr?pA22u^%l&UKYzMcif50HPOaAXL2tVjgd{~B|SS$W*9vBRR zVRiC549bVA+x`Xv!4dF3*Mgw@{D0Af^W%O<|5(e<`xnnx^ZFA8hVmo+rpwR&CtWZY z%J=755CRPSQ(iC(#QP@<`;jBIF8c?62pH~A{l+tv1pl8f5Q3NYZy22KPyK-qd^o@Q zJ3cTR=k9)oL12IJ2L{7=|I`5(0{?4&!7!{9{fQ3-`P+sd@V{*h27&*n129%CfAI|A z`+F^fALmzpmjep=do2|Fmz{#45M22A$6DyGHi@w_vOr;f^swF+sA}Pg#GNCc3L1?8 zV3mR^Lf^19MFWm5LckkXZzw1R6~z{^#l;X{32{CN5Fei;pSUPL1SBa5g(Adw#e@O> c^OQrMX^%0o!yKMoFbsP@NmyAW6{Sf24{-KwQ~&?~ literal 0 HcmV?d00001 diff --git a/docs/Guides/grammar2.xml b/docs/Guides/grammar2.xml new file mode 100644 index 0000000000..5dd2215185 --- /dev/null +++ b/docs/Guides/grammar2.xml @@ -0,0 +1,227 @@ + + +

+ + Grammar of JSON Queries + + + + + Scott + McKellar + + + Equinox Software, Inc. + + + + + + + + 2009 + Creative Commons Attribution-Share Alike 3.0 United States License. + + + + + + + + Introduction + 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. + Conventions: + + + The grammar is a series of productions. + + + 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. + + + Literals (including punctuation) are enclosed in 'single quotes', or in + "double quotes" if case is not significant. + + + A single quotation mark within a literal is escaped with a preceding + backslash: 'dog\'s tail'. + + + 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. + + + A construct enclosed within square brackets is optional. + + + A construct enclosed within curly braces may be repeated zero or more + times. + + + JSON allows arbitrary white space between tokens. To avoid ugly clutter, this + grammar ignores the optional white space. + + + 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. + + + + 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. + + + + + Primitives + We'll start by defining some primitives, to get them out of the way. They're mostly + just what you would expect. + + + + string + '"' chars '"' + + + + chars + any valid sequence of UTF-8 characters, with certain special characters + escaped according to JSON rules + + + + integer_literal + [ sign ] digit { digit } + + + + sign + '+' | '-' + + + + digit + digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' + + + + integer_string + '"' integer_literal '"' + + + + integer + integer_literal | integer_string + + + + number + any valid character sequence that is numeric according to JSON rules + + + + + 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. + + + + + boolean + 'true' | 'false' | string | number + + + + + The preferred way to encode a boolean is with the JSON reserved word true or false, + in lower case without quotation marks. The string true, in upper, + lower, or mixed case, is another way to encode true. Any other string evaluates to + false. + 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. + Any other valid JSON value, such as an array, will be accepted as a boolean but + interpreted as false. + The last couple of primitives aren't really very primitive, but we introduce them + here for convenience: + + + + + class_name + string + + + + + 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. + + + + + field_name + string + + + + + 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. + + + + + Query + + The following production applies not only to the main query but also to most + subqueries. + + + + + query + '{' '"from"' ':' from_list [ ',' '"select"' ':' select_list + ] [ ',' '"where"' ':' where_condition ] [ ',' '"having"' ':' + where_condition ] [ ',' '"order_by"' ':' order_by_list ] [ ',' + '"limit"' ':' integer ] [ ',' '"offset"' ':' integer ] [ ',' + '"distinct"' ':' boolean ] [ ',' '"no_i18n"' ':' boolean ] '}' + + + + + + Except for the "distinct" and no_i18n entries, + each name/value pair represents a major clause of the SELECT statement. The name/value + pairs may appear in any order. + There is no name/value pair for the GROUP BY clause, because json_query generates it + automatically according to information encoded elsewhere. + The "distinct" 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. + The "no_i18n" entry, if present and true, tells json_query to + suppress internationalization. If not present, it defaults to false. (Note that + "no_i18n" contains the digit one, not the letter ell.) + The values for limit and offset 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. + + + + +

diff --git a/docs/Guides/grammar3.xml b/docs/Guides/grammar3.xml new file mode 100644 index 0000000000..32b6e22438 --- /dev/null +++ b/docs/Guides/grammar3.xml @@ -0,0 +1,755 @@ + + + +

+ + + Grammar of JSON Queries + + Scott + McKellar + + + + Introduction + + 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. + + + Conventions: + + + + The grammar is a series of productions. + + + 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. + + + Literals (including punctuation) are enclosed in single quotes, or in double + quotes if case is not significant. + + + A single quotation mark within a literal is escaped with a preceding backslash. + + + 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. + + + A construct enclosed within square brackets is optional. + + + A construct enclosed within curly braces may be repeated zero or more times. + + + JSON allows arbitrary white space between tokens. To avoid ugly clutter, this + grammar ignores the optional white space. + + + 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. + + + + + 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. + + + + Primitives + + We'll start by defining some primitives, to get them out of the way. They're + mostly just what you would expect. + + + + + + string + + + 'â' chars 'â' + + + + + + chars + + + any valid sequence of UTF-8 characters, with certain special characters + escaped according to JSON rules + + + + + + integer_literal + + + [ sign ] digit { digit } + + + + + + sign + + + '+' | '-' + + + + + + digit + + digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' + + + + + + + integer_string + + + 'â' integer_literal 'â' + + + + + + integer + + + integer_literal | integer_string + + + + + + number + + + any valid character sequence that is numeric according to JSON rules + + + + + + + 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. + + + + + + + boolean + + + 'true' | 'false' | string | number + + + + + + + The preferred way to encode a boolean is with the JSON reserved word true or false, + in lower case without quotation marks. The string âtrueâ, in + upper, lower, or mixed case, is another way to encode true. Any other string + evaluates to false. + + + 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. + + + Any other valid JSON value, such as an array, will be accepted as a boolean but interpreted + as false. + + + The last couple of primitives aren't really very primitive, but we introduce them here + for convenience: + + + + + + + class_name + + + string + + + + + + + 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. + + + + + + + field_name + + + string + + + + + + + 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. + + + + + Query + + + The following production applies not only to the main query but also to + most subqueries. + + + + + + + query + + + '{' + 'âfromâ' ':' from_list + [ ',' 'âselectâ' ':' select_list ] + [ ',' 'âwhereâ' ':' where_condition ] + [ ',' 'âhavingâ' ':' where_condition ] + [ ',' 'âorder_byâ' ':' order_by_list ] + [ ',' 'âlimitâ' ':' integer ] + [ ',' 'âoffsetâ' ':' integer ] + [ ',' 'âdistinctâ' ':' boolean ] + [ ',' 'âno_i18nâ' ':' boolean ] + '}' + + + + + + + Except for the âdistinctâ and âno_i18nâ + entries, each name/value pair represents a major clause of the SELECT statement. + The name/value pairs may appear in any order. + + + There is no name/value pair for the GROUP BY clause, because json_query + generates it automatically according to information encoded elsewhere. + + + The âdistinctâ 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. + + + The âno_i18nâ entry, if present and true, tells json_query to + suppress internationalization. If not present, it defaults to false. (Note that + âno_i18nâ contains the digit one, not the letter ell.) + + + The values for âlimitâ and âoffsetâ + 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. + + + + + FROM Clause + + The object identified by âfromâ encodes the FROM clause of + the SQL. The associated value may be a string, an array, or a JSON object. + + + + + + + from_list + + + class_name + + + + + + + If from_list is a class_name, the + json_query inserts the corresponding table name or subquery into the FROM + clause, using the class_name as an alias for the table + or subquery. The class must be defined as non-virtual in the IDL. + + + + + + + from_list + + + '[' string { ',' parameter } ']' + + + + + + parameter + + + string | number | 'null' + + + + + + + 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). + + + 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 null, json_query will insert + it into the parameter list as a null value. + + + If from_list 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. + + + + + + + from_list + + + '{' class_name ':' join_list '}' + + + + + + join_list + + + class_name + + + + + + join_list + + + '{' join_def { ',' join_def } '}' + + + + + + + If the associated data is a class_name, 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. + + + Otherwise, the associated data must be a JSON object with one or more entries, + each entry defining a join: + + + + + + + join_def + + + class_name ':' + '{' + [ 'âtypeâ' ':' string ] + [ 'âfieldâ' ':' field_name ] + [ 'âfkeyâ' ':' field_name ] + [ 'âfilterâ' ':' where_condition ] + [ 'âfilter_opâ' ':' string ] + [ 'âjoinâ' ':' join_list ] + '}' + + + + + + + + The data portion of the âjoin_typeâ entry tells json_query + whether to use a left join, right join, full join, or inner join. The values + âleftâ, ârightâ, and âfullâ, + in upper, lower, or mixed case, have the obvious meanings. If the + âjoin_typeâ entry has any other value, or is not present, + json_query constructs an inner join. + + + The âfieldâ and âfkeyâ attributes specify the + columns to be equated in the join condition. The âfieldâ + attribute refers to the column in the joined table, i.e. the one named by the + join_def. The âfkeyâ attribute refers to the + corresponding column in the other table, i.e. the one named outside the + join_def â either the top-level table or a table named by some + other join_def. + + + It may be tempting to suppose that âfkeyâ 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. + + + These relationships are best explained with an example. The following from_list: + + + + { + "aou": { + "asv": { + "type" : "left", + "fkey" : "id", + "field" : "owner" + } + } + } + + + + ...turns into the following FROM clause: + + + + FROM + actor.org_unit AS "aou" + LEFT JOIN action.survey AS "asv" + ON ( "asv".owner = "aou".id ) + + + + Note in this example that âfkeyâ refers to a column of the + class âaouâ, and âfieldâ refers to a + column of the class âasvâ. + + + 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. + + + 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. + + + 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. + + + Using a âfilterâ 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 + âfilterâ key is the same sort of + where_condition that you use for a WHERE clause + (discussed below). + + + If the string associated with the âfilter_opâ entry is + âORâ 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 âfilterâ entry. + + + (Note that if the where_condition 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.) + + + If the âfilter_opâ entry carries any other value, or if + it is absent, then the json_query method uses AND. In the absence of a + âfilterâ entry, âfilter_opâ has no effect. + + + A âjoinâ entry in a join_def specifies + another layer of join. The class named in the subjoin is joined to the class + named by the join_def to which it is subordinate. By this + means you can encode multiple joins in a hierarchy. + + + + SELECT Clause + + If a query does not contain an entry for âselectâ, 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: + + + + + The default includes only the fields defined in the IDL. + + + 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. + + + + + There are other ways to specify a default SELECT list, as shown below. + + + If a âselectâ entry is present, the associated value must + be a JSON object, keyed on class names: + + + + + + + select_list + + + '{' class_name ':' field_list { ',' class_name ':' field_list } '}' + + + + + + + The class_name must identify either the top-level class or + a class belonging to one of the joins. Otherwise json_query will silently + ignore the select_list. + + + + + + + field_list + + + 'null' | 'â*â' + + + + + + + If a field_list is either the JSON reserved word null + (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 + field_list. + + + More commonly, the field_list is a JSON array of zero or + more field specifications: + + + + + + + field_list + + + '[' [ field_spec { ',' field_spec } ] ']' + + + + + + + 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. + + + In the simplest case, a field specification may name a non-virtual field + defined in the IDL: + + + + + + + field_spec + + + field_name + + + + + + + In some cases json_query constructs a call to the + oils_i18n_xlate function to internationalize the value of the + selected column. Specifically, it does so if all the following are true: + + + + + the settings file defines a locale; + + + in the field definition for the field in the IDL, the tag + âil8nâ is present and true; + + + the query does not include the + âno_il8nâ tag (or includes it with a value of false). + + + + + A field specification may be a JSON object: + + + + + + + field_spec + + + '{' + 'âcolumnâ' ':' + [ ',' 'âaliasâ' ':' string ] + [ ',' 'âaggregateâ' ':' boolean ] + [ ',' transform_spec ] + '}' + + + + + + + + The âcolumnâ entry provides the column name, which must + be defined as non-virtual in the IDL. + + + The âaliasâ entry provides a column alias. If no alias + is specified, json_query uses the column name as its own alias. + + + The âaggregateâ entry has no effect on the SELECT clause + itself. Rather, it affects the construction of a GROUP BY class. If there + is an âaggregateâ entry for any field, then json_query builds + a GROUP BY clause listing every column that is not tagged + for aggregation (or that carries an âaggregateâ entry with + a value of false). If all columns are tagged for + aggregation, then json_query omits the GROUP BY clause. + + + + + + + transform_spec + + + 'âtransformâ' ':' string ] + [ ',' 'âresult_fieldâ ':' string ] + [ ',' 'âparamsâ ':' param_list ] + + + + + + + When a transform_spec is present, json_query selects the + return value of a function instead of selecting the column directly. The entry + for âtransformâ provides the name of the function, and the + column name (as specified by the âcolumnâ 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 âaggregateâ tag). + + + The âresult_fieldâ 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. + + + The âparamsâ entry, if present, provides a possibly empty + array of additional parameter values, either strings, numbers, or nulls: + + + + + + + param_list + + + '[' [ parameter { ',' parameter } ] ']' + + + + + + + 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. + + + + WHERE Clause + + + ORDER BY Clause + + +

-- 2.11.0