Documentation Source Text

Check-in [a0b50e2c3d]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Enhance the sessions documentation to show the methods of objects.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: a0b50e2c3d0dcffc9285c2239fe1b1dbf5055c8e6ab97f56c2ff8af6c020b78a
User & Date: drh 2018-02-28 22:21:53
Context
2018-03-08
00:33
Add the documentation about SQLite Archive files. Updates to the change log. check-in: f49396b55b user: drh tags: trunk
2018-02-28
22:21
Enhance the sessions documentation to show the methods of objects. check-in: a0b50e2c3d user: drh tags: trunk
21:50
Fix the sessions documentation generator so that code snippets are indented correctly. check-in: f3445c7d01 user: drh tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to pages/capi3ref.in.

    14     14   set inrow 0        ;# In a row of a table
    15     15   set rowbody {}     ;# Content of a row
    16     16   set rowtag {}      ;# 
    17     17   set exflag 0       ;# True for experimental interfaces 
    18     18   set obsflag 0      ;# True for obsolete interfaces
    19     19   unset -nocomplain keyword
    20     20   unset -nocomplain supported   ;# 0: stable.  1: experimental  2: deprecated
    21         -unset -nocomplain fcons
    22         -unset -nocomplain fdest
    23     21   unset -nocomplain fmeth
    24     22   
    25     23   # End a table row or the complete table.
    26     24   #
    27     25   proc endrow {} {
    28     26     global inrow body rowbody rowtag keyword dflt_parent
    29     27     if {$inrow} {

Changes to pages/session.in.

    19     19   set inrow 0        ;# In a row of a table
    20     20   set rowbody {}     ;# Content of a row
    21     21   set rowtag {}      ;# 
    22     22   set exflag 0       ;# True for experimental interfaces 
    23     23   set obsflag 0      ;# True for obsolete interfaces
    24     24   unset -nocomplain keyword
    25     25   unset -nocomplain supported   ;# 0: stable.  1: experimental  2: deprecated
           26  +unset -nocomplain fmeth
    26     27   
    27     28   # End a table row or the complete table.
    28     29   #
    29     30   proc endrow {} {
    30     31     global inrow body rowbody rowtag keyword dflt_parent
    31     32     if {$inrow} {
    32     33       set rowbody [string trim $rowbody]
................................................................................
    69     70       # record the interface title and then switch to "phase 1".
    70     71       #
    71     72       if {[regexp {^\*\* CAPI3REF: +(.*)} $line all tx]} {
    72     73         set title $tx
    73     74         set dflt_parent {}
    74     75         regexp {<([AHLS]\d\d\d\d\d)>} $title all dflt_parent
    75     76         set title_lineno $lineno
           77  +      set method {}
           78  +      set destructor {}
           79  +      set constructor {}
    76     80         set phase 1
    77     81       }
    78     82     } elseif {$phase==1} {
    79     83       if {[string range $line 0 1]=="**"} {
    80     84         # Record all lines of column following the CAPI3REF keyword as the
    81     85         # description of the interface.  Except, look for special keywords
    82     86         # CATEGORY, KEYWORDS, INVARIANTS, and ASSUMPTIONS and process them
................................................................................
    89     93           foreach k $kx {
    90     94             set keyword($k) 1
    91     95           }
    92     96         } elseif {[regexp {^EXPERIMENTAL} $lx]} {
    93     97           set exflag 1
    94     98         } elseif {[regexp {^DEPRECATED} $lx]} {
    95     99           set obsflag 1
          100  +      } elseif {[regexp {^CONSTRUCTOR: +(.*)} $lx all nm]} {
          101  +        set constructor $nm
          102  +      } elseif {[regexp {^METHOD: +(.*)} $lx all nm]} {
          103  +        set method $nm
          104  +      } elseif {[regexp {^DESTRUCTOR: +(.*)} $lx all nm]} {
          105  +        set destructor $nm
    96    106         } else {
    97    107           append body $lx\n
    98    108         }
    99    109       } elseif {[string range $line 0 1]=="*/"} {
   100    110         # When we reach the end of the block comment that contained the
   101    111         # CAPI3REF keyword, that ends the description.  Switch to phase 3
   102    112         # in order to begin picking up the interface definition.
................................................................................
   158    168         } elseif {[regexp {^struct (sqlite3[0-9a-z_]+)} $line all kx]} {
   159    169           set type datatype
   160    170           set keyword($kx) 1
   161    171           incr dcnt
   162    172         } elseif {[regexp {^[a-z].*[ *](sqlite3[a-z0-9_]+)\(} $line all kx]} {
   163    173           set type function
   164    174           set keyword($kx) 1
          175  +        if {$constructor ne ""} {lappend fmeth(c:$constructor) $kx}
          176  +        if {$destructor ne ""}  {lappend fmeth(d:$destructor) $kx}
          177  +        if {$method ne ""}      {lappend fmeth(m:$method) $kx}
   165    178           incr dcnt
   166    179         } elseif {[regexp {^[a-z].*[ *](sqlite3[a-z0-9_]+);} $line all kx]} {
   167    180           set type datatype
   168    181           set keyword($kx) 1
   169    182           incr dcnt
   170    183         } elseif {[regexp {^SQLITE_EXTERN .*(sqlite[0-9a-z_]+);} $line all kx]} {
   171    184           set type datatype
................................................................................
   362    375   hd_putsnl {<p>Other lists:
   363    376   <a href="constlist.html">Constants</a> and
   364    377   <a href="objlist.html">Objects</a>.</p>}
   365    378   hd_enable_main 1
   366    379   hd_close_aux
   367    380   hd_putsnl {<hr>}
   368    381   
          382  +# Convert a fragment text label into a fragment name
          383  +#
          384  +proc hd_fragname {lbl} {
          385  +  regsub -all {[^a-z0-9]} [string tolower $lbl] {} lbl2
          386  +  return $lbl2
          387  +}
          388  +
          389  +# Show constructors, destructors or methods for an object
          390  +#
          391  +proc show_methods_of_object {key label} {
          392  +  global fmeth
          393  +  if {![info exists fmeth($key)]} return
          394  +  set lx [lsort $fmeth($key)]
          395  +  set n [llength $lx]
          396  +  if {$n==0} return
          397  +  if {$n==1} {
          398  +    hd_resolve "<p>$label: \[[lindex $lx 0]()\]</p>\n"
          399  +    return
          400  +  }
          401  +  if {$n<=4} {
          402  +    hd_puts "<p>${label}s:\n"
          403  +    set sep { }
          404  +    foreach x $lx {
          405  +      hd_puts $sep
          406  +      set sep ",\n"
          407  +      hd_resolve \[${x}()\]
          408  +    }
          409  +    hd_puts "</p>\n"
          410  +    return
          411  +  }
          412  +  set flst {}
          413  +  foreach x $lx {
          414  +    lappend flst [list $x $x 0]
          415  +  }
          416  +  hd_list_of_links "${label}s:" 350 $flst
          417  +  hd_puts "</p>\n"
          418  +}
   369    419   
   370    420   # Output all the records
   371    421   #
   372    422   foreach c [lsort $content] {
   373    423     foreach {key title type keywords body code} $c break
   374    424     set kw [preferred_keyword [lsort $keywords]]
   375    425     hd_fragment $kw
................................................................................
   386    436     hd_puts "</pre></blockquote>"
   387    437     if {$supported($kw)==1} {
   388    438       hd_resolve {<p><b>Important:</b> This interface is [experimental] }
   389    439       hd_resolve {and is subject to change without notice.</p>}
   390    440     }
   391    441     regsub -all "\n\n+" $body "</p>\n\n<p>" body
   392    442     hd_resolve <p>$body</p>
          443  +  show_methods_of_object c:$kw Constructor
          444  +  show_methods_of_object d:$kw Destructor
          445  +  show_methods_of_object m:$kw Method
   393    446     hd_enable_main 0
   394    447     hd_puts {<p>See also lists of
   395    448     <a href="objlist.html">Objects</a>,
   396    449     <a href="constlist.html">Constants</a>, and
   397    450     <a href="funclist.html">Functions</a>.</p>}
   398    451     hd_enable_main 1
   399    452     hd_close_aux
   400    453     hd_puts "<hr>"
   401    454   }
   402    455   </tcl>

Changes to pages/sessionintro.in.

    73     73   <li><p> SQLite allows <a href=nulls.html>NULL values</a> to be stored in
    74     74           PRIMARY KEY columns. However, the session extension ignores all
    75     75           such rows. No changes affecting rows with one or more NULL values
    76     76           in PRIMARY KEY columns are recorded by the sessions module.
    77     77   </ul>
    78     78   
    79     79   <h1>Concepts</h1>
           80  +
           81  +<tcl>hd_fragment changeset {changeset} {changesets} {patchset} {patchsets}</tcl>
    80     82   <h2 id=changesets_and_patchsets>Changesets and Patchsets</h2>
    81     83   <p> The sessions module revolves around creating and manipulating 
    82     84   changesets. A changeset is a blob of data that encodes a series of 
    83     85   changes to a database. Each change in a changeset is one of the 
    84     86   following:
    85     87   
    86     88   <ul>