From: kgs Date: Fri, 8 May 2009 19:58:32 +0000 (+0000) Subject: removing extraneous file X-Git-Url: https://old-git.evergreen-ils.org/?a=commitdiff_plain;h=0616cd4ae9fe790967beb9cdea1f7bcd710465c3;p=evergreen%2Fmasslnc.git removing extraneous file git-svn-id: svn://svn.open-ils.org/ILS/trunk@13105 dcc99617-32d9-48b4-a31d-7c20da2025e4 --- diff --git a/docs/Guides/compugrammar.xpr b/docs/Guides/compugrammar.xpr deleted file mode 100644 index 6235c751e1..0000000000 --- a/docs/Guides/compugrammar.xpr +++ /dev/null @@ -1,259 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/Guides/grammar.html b/docs/Guides/grammar.html deleted file mode 100644 index 36587da957..0000000000 --- a/docs/Guides/grammar.html +++ /dev/null @@ -1,151 +0,0 @@ -Grammar of JSON Queries

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: -

  1. - The grammar is a series of productions. -
  2. - 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. -
  3. - Literals (including punctuation) are enclosed in single quotes, or in double - quotes if case is not significant. -
  4. - A single quotation mark within a literal is escaped with a preceding backslash. -
  5. - 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. -
  6. - A construct enclosed within square brackets is optional. -
  7. - A construct enclosed within curly braces may be repeated zero or more times. -
  8. - JSON allows arbitrary white space between tokens. To avoid ugly clutter, this - grammar ignores the optional white space. -
  9. - 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 deleted file mode 100644 index 2601682f90..0000000000 --- a/docs/Guides/grammar.xml +++ /dev/null @@ -1,291 +0,0 @@ - - - -
- - - 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. - - - - -
diff --git a/docs/Guides/grammar2.xml b/docs/Guides/grammar2.xml deleted file mode 100644 index 5dd2215185..0000000000 --- a/docs/Guides/grammar2.xml +++ /dev/null @@ -1,227 +0,0 @@ - - -
- - 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 deleted file mode 100644 index 32b6e22438..0000000000 --- a/docs/Guides/grammar3.xml +++ /dev/null @@ -1,755 +0,0 @@ - - - -
- - - 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 - - -