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 Unified Diffs Show Whitespace Changes Patch

Changes to pages/capi3ref.in.

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

# End a table row or the complete table.
#
proc endrow {} {
  global inrow body rowbody rowtag keyword dflt_parent
  if {$inrow} {







<
<







14
15
16
17
18
19
20


21
22
23
24
25
26
27
set inrow 0        ;# In a row of a table
set rowbody {}     ;# Content of a row
set rowtag {}      ;# 
set exflag 0       ;# True for experimental interfaces 
set obsflag 0      ;# True for obsolete interfaces
unset -nocomplain keyword
unset -nocomplain supported   ;# 0: stable.  1: experimental  2: deprecated


unset -nocomplain fmeth

# End a table row or the complete table.
#
proc endrow {} {
  global inrow body rowbody rowtag keyword dflt_parent
  if {$inrow} {

Changes to pages/session.in.

19
20
21
22
23
24
25

26
27
28
29
30
31
32
..
69
70
71
72
73
74
75



76
77
78
79
80
81
82
..
89
90
91
92
93
94
95






96
97
98
99
100
101
102
...
158
159
160
161
162
163
164



165
166
167
168
169
170
171
...
362
363
364
365
366
367
368





































369
370
371
372
373
374
375
...
386
387
388
389
390
391
392



393
394
395
396
397
398
399
400
401
402
set inrow 0        ;# In a row of a table
set rowbody {}     ;# Content of a row
set rowtag {}      ;# 
set exflag 0       ;# True for experimental interfaces 
set obsflag 0      ;# True for obsolete interfaces
unset -nocomplain keyword
unset -nocomplain supported   ;# 0: stable.  1: experimental  2: deprecated


# End a table row or the complete table.
#
proc endrow {} {
  global inrow body rowbody rowtag keyword dflt_parent
  if {$inrow} {
    set rowbody [string trim $rowbody]
................................................................................
    # record the interface title and then switch to "phase 1".
    #
    if {[regexp {^\*\* CAPI3REF: +(.*)} $line all tx]} {
      set title $tx
      set dflt_parent {}
      regexp {<([AHLS]\d\d\d\d\d)>} $title all dflt_parent
      set title_lineno $lineno



      set phase 1
    }
  } elseif {$phase==1} {
    if {[string range $line 0 1]=="**"} {
      # Record all lines of column following the CAPI3REF keyword as the
      # description of the interface.  Except, look for special keywords
      # CATEGORY, KEYWORDS, INVARIANTS, and ASSUMPTIONS and process them
................................................................................
        foreach k $kx {
          set keyword($k) 1
        }
      } elseif {[regexp {^EXPERIMENTAL} $lx]} {
        set exflag 1
      } elseif {[regexp {^DEPRECATED} $lx]} {
        set obsflag 1






      } else {
        append body $lx\n
      }
    } elseif {[string range $line 0 1]=="*/"} {
      # When we reach the end of the block comment that contained the
      # CAPI3REF keyword, that ends the description.  Switch to phase 3
      # in order to begin picking up the interface definition.
................................................................................
      } elseif {[regexp {^struct (sqlite3[0-9a-z_]+)} $line all kx]} {
        set type datatype
        set keyword($kx) 1
        incr dcnt
      } elseif {[regexp {^[a-z].*[ *](sqlite3[a-z0-9_]+)\(} $line all kx]} {
        set type function
        set keyword($kx) 1



        incr dcnt
      } elseif {[regexp {^[a-z].*[ *](sqlite3[a-z0-9_]+);} $line all kx]} {
        set type datatype
        set keyword($kx) 1
        incr dcnt
      } elseif {[regexp {^SQLITE_EXTERN .*(sqlite[0-9a-z_]+);} $line all kx]} {
        set type datatype
................................................................................
hd_putsnl {<p>Other lists:
<a href="constlist.html">Constants</a> and
<a href="objlist.html">Objects</a>.</p>}
hd_enable_main 1
hd_close_aux
hd_putsnl {<hr>}







































# Output all the records
#
foreach c [lsort $content] {
  foreach {key title type keywords body code} $c break
  set kw [preferred_keyword [lsort $keywords]]
  hd_fragment $kw
................................................................................
  hd_puts "</pre></blockquote>"
  if {$supported($kw)==1} {
    hd_resolve {<p><b>Important:</b> This interface is [experimental] }
    hd_resolve {and is subject to change without notice.</p>}
  }
  regsub -all "\n\n+" $body "</p>\n\n<p>" body
  hd_resolve <p>$body</p>



  hd_enable_main 0
  hd_puts {<p>See also lists of
  <a href="objlist.html">Objects</a>,
  <a href="constlist.html">Constants</a>, and
  <a href="funclist.html">Functions</a>.</p>}
  hd_enable_main 1
  hd_close_aux
  hd_puts "<hr>"
}
</tcl>







>







 







>
>
>







 







>
>
>
>
>
>







 







>
>
>







 







>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>







 







>
>
>










19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
..
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
..
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
...
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
...
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
...
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
set inrow 0        ;# In a row of a table
set rowbody {}     ;# Content of a row
set rowtag {}      ;# 
set exflag 0       ;# True for experimental interfaces 
set obsflag 0      ;# True for obsolete interfaces
unset -nocomplain keyword
unset -nocomplain supported   ;# 0: stable.  1: experimental  2: deprecated
unset -nocomplain fmeth

# End a table row or the complete table.
#
proc endrow {} {
  global inrow body rowbody rowtag keyword dflt_parent
  if {$inrow} {
    set rowbody [string trim $rowbody]
................................................................................
    # record the interface title and then switch to "phase 1".
    #
    if {[regexp {^\*\* CAPI3REF: +(.*)} $line all tx]} {
      set title $tx
      set dflt_parent {}
      regexp {<([AHLS]\d\d\d\d\d)>} $title all dflt_parent
      set title_lineno $lineno
      set method {}
      set destructor {}
      set constructor {}
      set phase 1
    }
  } elseif {$phase==1} {
    if {[string range $line 0 1]=="**"} {
      # Record all lines of column following the CAPI3REF keyword as the
      # description of the interface.  Except, look for special keywords
      # CATEGORY, KEYWORDS, INVARIANTS, and ASSUMPTIONS and process them
................................................................................
        foreach k $kx {
          set keyword($k) 1
        }
      } elseif {[regexp {^EXPERIMENTAL} $lx]} {
        set exflag 1
      } elseif {[regexp {^DEPRECATED} $lx]} {
        set obsflag 1
      } elseif {[regexp {^CONSTRUCTOR: +(.*)} $lx all nm]} {
        set constructor $nm
      } elseif {[regexp {^METHOD: +(.*)} $lx all nm]} {
        set method $nm
      } elseif {[regexp {^DESTRUCTOR: +(.*)} $lx all nm]} {
        set destructor $nm
      } else {
        append body $lx\n
      }
    } elseif {[string range $line 0 1]=="*/"} {
      # When we reach the end of the block comment that contained the
      # CAPI3REF keyword, that ends the description.  Switch to phase 3
      # in order to begin picking up the interface definition.
................................................................................
      } elseif {[regexp {^struct (sqlite3[0-9a-z_]+)} $line all kx]} {
        set type datatype
        set keyword($kx) 1
        incr dcnt
      } elseif {[regexp {^[a-z].*[ *](sqlite3[a-z0-9_]+)\(} $line all kx]} {
        set type function
        set keyword($kx) 1
        if {$constructor ne ""} {lappend fmeth(c:$constructor) $kx}
        if {$destructor ne ""}  {lappend fmeth(d:$destructor) $kx}
        if {$method ne ""}      {lappend fmeth(m:$method) $kx}
        incr dcnt
      } elseif {[regexp {^[a-z].*[ *](sqlite3[a-z0-9_]+);} $line all kx]} {
        set type datatype
        set keyword($kx) 1
        incr dcnt
      } elseif {[regexp {^SQLITE_EXTERN .*(sqlite[0-9a-z_]+);} $line all kx]} {
        set type datatype
................................................................................
hd_putsnl {<p>Other lists:
<a href="constlist.html">Constants</a> and
<a href="objlist.html">Objects</a>.</p>}
hd_enable_main 1
hd_close_aux
hd_putsnl {<hr>}

# Convert a fragment text label into a fragment name
#
proc hd_fragname {lbl} {
  regsub -all {[^a-z0-9]} [string tolower $lbl] {} lbl2
  return $lbl2
}

# Show constructors, destructors or methods for an object
#
proc show_methods_of_object {key label} {
  global fmeth
  if {![info exists fmeth($key)]} return
  set lx [lsort $fmeth($key)]
  set n [llength $lx]
  if {$n==0} return
  if {$n==1} {
    hd_resolve "<p>$label: \[[lindex $lx 0]()\]</p>\n"
    return
  }
  if {$n<=4} {
    hd_puts "<p>${label}s:\n"
    set sep { }
    foreach x $lx {
      hd_puts $sep
      set sep ",\n"
      hd_resolve \[${x}()\]
    }
    hd_puts "</p>\n"
    return
  }
  set flst {}
  foreach x $lx {
    lappend flst [list $x $x 0]
  }
  hd_list_of_links "${label}s:" 350 $flst
  hd_puts "</p>\n"
}

# Output all the records
#
foreach c [lsort $content] {
  foreach {key title type keywords body code} $c break
  set kw [preferred_keyword [lsort $keywords]]
  hd_fragment $kw
................................................................................
  hd_puts "</pre></blockquote>"
  if {$supported($kw)==1} {
    hd_resolve {<p><b>Important:</b> This interface is [experimental] }
    hd_resolve {and is subject to change without notice.</p>}
  }
  regsub -all "\n\n+" $body "</p>\n\n<p>" body
  hd_resolve <p>$body</p>
  show_methods_of_object c:$kw Constructor
  show_methods_of_object d:$kw Destructor
  show_methods_of_object m:$kw Method
  hd_enable_main 0
  hd_puts {<p>See also lists of
  <a href="objlist.html">Objects</a>,
  <a href="constlist.html">Constants</a>, and
  <a href="funclist.html">Functions</a>.</p>}
  hd_enable_main 1
  hd_close_aux
  hd_puts "<hr>"
}
</tcl>

Changes to pages/sessionintro.in.

73
74
75
76
77
78
79


80
81
82
83
84
85
86
<li><p> SQLite allows <a href=nulls.html>NULL values</a> to be stored in
        PRIMARY KEY columns. However, the session extension ignores all
        such rows. No changes affecting rows with one or more NULL values
        in PRIMARY KEY columns are recorded by the sessions module.
</ul>

<h1>Concepts</h1>


<h2 id=changesets_and_patchsets>Changesets and Patchsets</h2>
<p> The sessions module revolves around creating and manipulating 
changesets. A changeset is a blob of data that encodes a series of 
changes to a database. Each change in a changeset is one of the 
following:

<ul>







>
>







73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
<li><p> SQLite allows <a href=nulls.html>NULL values</a> to be stored in
        PRIMARY KEY columns. However, the session extension ignores all
        such rows. No changes affecting rows with one or more NULL values
        in PRIMARY KEY columns are recorded by the sessions module.
</ul>

<h1>Concepts</h1>

<tcl>hd_fragment changeset {changeset} {changesets} {patchset} {patchsets}</tcl>
<h2 id=changesets_and_patchsets>Changesets and Patchsets</h2>
<p> The sessions module revolves around creating and manipulating 
changesets. A changeset is a blob of data that encodes a series of 
changes to a database. Each change in a changeset is one of the 
following:

<ul>