Clark C. Evans  committed 09b5b0f

pulling out section on nulls
collapsing logical expressions

  • Participants
  • Parent commits e7277a1
  • Branches default

Comments (0)

Files changed (1)

File doc/tutorial.rst

-Predicate Expressions
+Logical Expressions
 A *filter* refines results by including or excluding data by specific
 criteria.  This section reviews comparison operators, boolean
+The *in* operator (``={}``) can be thought of as equality over a set.
+This example, we return courses that are in neither the "Art History"
+nor the "Studio Art" department (PC6_)::
+    /course?department!={'arthis','stdart'}
+.. _PC6:
+    /course?department!={'arthis','stdart'}
 Use the *greater-than* (``>``) operator to request courses with more
-than 3 credits (PC6_):: 
+than 3 credits (PC7_):: 
      stdart     | 411       | Underwater Basket Weaving | 4         
-.. _PC6:
+.. _PC7:
 Use the *greater-than-or-equal-to* (``>=``) operator request courses
-that have three credits or more (PC7_)::
+that have three credits or more (PC8_)::
-.. _PC7:
+.. _PC8:
 Using comparison operators with strings tells HTSQL to compare them
 alphabetically (once again, dependent upon database's collation).  For
 example, the *greater-than* (``>``) operator can be used to request
-departments whose ``code`` follows ``'me'`` in the alphabet (PC8_)::
+departments whose ``code`` follows ``'me'`` in the alphabet (PC9_)::
     poli  | Political Science | la    
-.. _PC8:
+.. _PC9:
-Compound Expressions
 The precedence rules for boolean operators follow typical programming
 convention, negation binds more tightly than conjunction, which binds
 more tightly than alternation.  Parenthesis can be used to override this
-default grouping rule or to better clarify intent (PB1_)::
-    /{ true() | false()&false() , (true()|false()) & false() }
-   -------------------------------------------------
-   true()|false()&false() | (true()|false())&false()
-   -----------------------+-------------------------
-   true                   | false                   
-                                             (1 row)
-.. _PB1:
-    /{true()|false()&false(),(true()|false())&false()}
-Hence, the following request shows courses that are in "Art History"
-or "Studio Art" having more than three credits (PB2_)::
+default grouping rule or to better clarify intent.  The next example
+returns that are in "Art History" or "Studio Art" having more than three
+credits (PA6_)::
     stdart     | 614    | Drawing Master Class          | 5       
-.. _PB2:
+.. _PA6:
-Without the parenthesis, the expression above would show all
-courses from ``'arthis'`` regardless of credits (PB3_)::
+Without the parenthesis, the expression above would show all courses
+from ``'arthis'`` regardless of credits (PA7_)::
     arthis     | 623    | Contemporary Latin American Art | 3        
-.. _PB3:
+.. _PA7:
-Negation (``!``) lets you find all courses that are NOT in either 
-"Art History" or "Studio Art" (PB4_)::
+When a non-boolean is used in a logical expression, it is implicitly
+cast as a *boolean*.  As part of this cast, tri-value logic is
+flattened, ``null()`` is converted into ``false()``.  For strings, the
+empty string (``''``) is also treated as ``false()``.  This conversion
+rule shortens URLs and makes them more readable.
-    /course?!(department='arthis'|department='stdart')
-.. _PB4:
-    /course?!(department='arthis'|department='stdart')
-Equivalently, using ``={}`` list notation (PB5_)::
-    /course?department!={'arthis','stdart'}
-.. _PB5:
-    /course?department!={'arthis','stdart'}
-Empty Strings and NULLs
-HTSQL supports tri-value logic with ``NULL`` carefully.  To match
-typical expectations, an implicit predicate treats ``NULL`` and the
-empty string ``''`` as ``false()``.  For example, the following request
-returns only ``course`` records having a ``description`` (PN1_)::
+For example, this query returns only ``course`` records having a
+``description`` (PA8_)::
-.. _PN1:
+.. _PA8:
 The predicate ``?description`` is treated as a short-hand for
 ``?(!is_null(description)&description!='')``.  The negated variant of
-this shortcut is more illustrative (PN2_)::
+this shortcut is more illustrative (PA9_)::
     /course{department,number,description}? !description
     me         |    627 | ""         
                              (2 rows)
-.. _PN2:
+.. _PA9:
     /course{department,number,description}? !description
-That said, HTSQL's equality operator (``=``) is null-regular, that is,
-if either operand is ``null()`` the result is ``null()``. This can cause
-frustration when trying to check for equality.  Consider the following
-query template where ``$school`` is a parameter::
+Types and Functions
+HTSQL supports *boolean*, *date*, *numeric*, and *text* data types, as
+well as variants.  The pluggable type system can be used to augment the
+core types provided. 
+Working with NULLs
+HTSQL provides a rich function set for handling ``NULL`` expressions;
+however, careful attention must be paid.  For starters, the standard
+equality operator (``=``) is null-regular, that is, if either operand is
+``null()`` the result is ``null()``.  The following request always
+returns 0 rows (WN1_)::
-   /department?school=$school
+   /department?school=null()
-This query works as expected, returning departments in a given school,
-unless ``$school`` is ``null()``.  In this case, the predicate
-expression ``school=null()`` is evaluated as ``null()`` and, by the rule
-above, is treated as ``false()``.   Hence, if ``$school`` is ``null()``,
-no rows are returned, omitting records with a ``NULL`` ``school``.  
+    department
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    code    | name              
+    --------+-------------------
+                          0 rows
-The *is not distinct from* operator , (``==``), is roughly equivalent to
-``(is_null($school)&is_null(school)) | $school=school``, and can be used
-for these sorts of tests (PN3_)::
+.. _WN1:
+    /department?school=null()
+While you wouldn't directly write that query, it could be the final
+result after parameter substitution for a templatized query such as
+``/department?school=$var``.  For cases like this, use *total equality*
+operator (``==``) which treats ``NULL`` values as equivalent (WN2_)::
     parent  | Parents & Alumni  
                         (3 rows)
-.. _PN3:
+.. _WN2:
-The ``!==`` operator lists the *complement*, including records with a
- ``NULL`` for the field tested (PN4_)::
+The ``!==`` operator lists the complement, including records with a
+``NULL`` for the field tested (WN3_)::
     capmrk | Capital Markets        | bus   
-.. _PN4:
+.. _WN3:
+Odds & Ends
+There are a few more items that are important to know about, but for
+which we don't document yet (but will before release candidate).
+* untyped literals, ``/{1='1'}``
+* single-quote escaping, ``/{'Bursar''s Office'}``
+* percent-encoding, ``/{'%25'}``
+* functions vs methods
+* sort expression, ``/course.sort(credits)``
+* limit/offset, ``/course.limit(5,20)``