Documentation Source Text

Check-in [e9c7eaba3b]
Login

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

Overview
Comment:Update the API decoder to identify and cross-reference methods on objects.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: e9c7eaba3b20e29a7cc61a40ec1684dc77f22133
User & Date: drh 2015-04-14 15:14:34
Context
2015-04-23
16:40
Merge changes from 3.8.9. check-in: a0579664f6 user: drh tags: trunk
2015-04-14
15:14
Update the API decoder to identify and cross-reference methods on objects. check-in: e9c7eaba3b user: drh tags: trunk
13:24
Improvements to the cintro.html document. check-in: 4dfdc948ef user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to pages/capi3ref.in.

13
14
15
16
17
18
19



20
21
22
23
24
25
26
..
70
71
72
73
74
75
76



77
78
79
80
81
82
83
..
90
91
92
93
94
95
96






97
98
99
100
101
102
103
...
149
150
151
152
153
154
155



156
157
158
159
160
161
162
...
165
166
167
168
169
170
171



172
173
174
175
176
177
178
...
199
200
201
202
203
204
205
206
207



208
209
210
211
212
213
214
...
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
...
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
...
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
...
514
515
516
517
518
519
520































521
522
523
524
525
526
527
...
547
548
549
550
551
552
553



554
555
556
557
558
559
560
561
562
563
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






      } elseif {[regexp {^FRAGMENT: +(.*)} $lx all kx]} {
        set fragname [lindex $kx 0]
        append body "<a name=\"$fragname\"></a>\n"
        
      } else {
        append body $lx\n
      }
................................................................................
      set title {}
      set keywords {}
      set type {}
      set body {}
      set code {}
      set phase 0
      set dcnt 0



    } else {
      if {[regexp {^#define (SQLITE_[A-Z0-9_]+)} $line all kx]} {
        set type constant
        set keyword($kx) 1
        incr dcnt
      } elseif {[regexp {^typedef .*(sqlite[0-9a-zA-Z_]+);} $line all kx]} {
        set type datatype
................................................................................
      } 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
................................................................................
  regsub {^sqlite3_} $oldname {} oldname
  regsub { } $oldname _ name
  return $name.html
}

# Output HTML that displays the list $lx in $N columns
#
proc output_list {N lx} {
  hd_putsnl {<table width="100%" cellpadding="5"><tr>}



  set len [llength $lx]
  set n [expr {($len + $N - 1)/$N}]
  for {set i 0} {$i<$N} {incr i} {
    set start [expr {$i*$n}]
    set end [expr {($i+1)*$n}]
    hd_puts {<td valign="top"><ul>}
    for {set j $start} {$j<$end} {incr j} {
................................................................................
hd_header {List Of SQLite Objects}
hd_enable_main 0
hd_putsnl {<a href="intro.html"><h2>SQLite C Interface</h2></a>}
hd_enable_main 1
</tcl>
<h2>List Of Objects:</h2>
<tcl>
output_list 3 [lsort -nocase $objlist]
hd_enable_main 0
hd_putsnl {<p>Other lists:
<a href="constlist.html">Constants</a> and
<a href="funclist.html">Functions</a> and
<a href="../rescode.html">Result Codes</a>.}
hd_close_aux
hd_enable_main 1
................................................................................
hd_putsnl {<a href="intro.html"><h2>SQLite C Interface</h2></a>}
hd_enable_main 1
</tcl>
<h2>List Of Constants:</h2>
<p>Also available: [error codes|list of error codes]</p>
<tcl>
set clist [lsort -index 1 $clist]
output_list 2 $clist
hd_enable_main 0
hd_putsnl {<p>Other lists:
<a href="objlist.html">Objects</a> and
<a href="funclist.html">Functions</a> and
<a href="../rescode.html">Result Codes</a>.</p>}
hd_enable_main 1
hd_close_aux
................................................................................
</tcl>
<h2>List Of Functions:</h2>
<p>Note: Functions marked with "[experimental | <small><i>(exp)</i></small>]"
are [experimental] and functions marked with
[deprecated | <small><i>(obs)</i></small>] are [deprecated].</p>
<tcl>
set funclist [lsort -index 1 $funclist]
output_list 3 $funclist
hd_enable_main 0
hd_putsnl {<p>Other lists:
<a href="constlist.html">Constants</a> and
<a href="objlist.html">Objects</a> and
<a href="../rescode.html">Result Codes</a></p>}
hd_enable_main 1
hd_close_aux
................................................................................

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

































# Output all the records
#
foreach c [lsort $content] {
  foreach {key title type keywords body code} $c break
  set kw [preferred_keyword [lsort $keywords]]
................................................................................
  while {[regexp {^(.*?)\[\[([^]]*)\]\](.*)$} $body all fore anchor aft]} {
    hd_resolve $fore
    set anchor [string trim $anchor]
    hd_fragment [hd_fragname $anchor] $anchor
    set body $aft
  }
  hd_resolve $body



  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>







>
>
>







 







>
>
>







 







>
>
>
>
>
>







 







>
>
>







 







>
>
>







 







|
|
>
>
>







 







|







 







|







 







|







 







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







 







>
>
>










13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
..
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
..
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
...
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
...
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
...
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
...
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
...
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
...
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
...
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
...
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
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} {
    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
      } elseif {[regexp {^FRAGMENT: +(.*)} $lx all kx]} {
        set fragname [lindex $kx 0]
        append body "<a name=\"$fragname\"></a>\n"
        
      } else {
        append body $lx\n
      }
................................................................................
      set title {}
      set keywords {}
      set type {}
      set body {}
      set code {}
      set phase 0
      set dcnt 0
      set constructor {}
      set destructor {}
      set method {}
    } else {
      if {[regexp {^#define (SQLITE_[A-Z0-9_]+)} $line all kx]} {
        set type constant
        set keyword($kx) 1
        incr dcnt
      } elseif {[regexp {^typedef .*(sqlite[0-9a-zA-Z_]+);} $line all kx]} {
        set type datatype
................................................................................
      } 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
................................................................................
  regsub {^sqlite3_} $oldname {} oldname
  regsub { } $oldname _ name
  return $name.html
}

# Output HTML that displays the list $lx in $N columns
#
proc output_list {title N lx} {
  hd_putsnl {<table width="100%" cellpadding="0"><tr>}
  if {$title!=""} {
    hd_putsnl "<td colspan=$N>$title</td></tr><tr>"
  }
  set len [llength $lx]
  set n [expr {($len + $N - 1)/$N}]
  for {set i 0} {$i<$N} {incr i} {
    set start [expr {$i*$n}]
    set end [expr {($i+1)*$n}]
    hd_puts {<td valign="top"><ul>}
    for {set j $start} {$j<$end} {incr j} {
................................................................................
hd_header {List Of SQLite Objects}
hd_enable_main 0
hd_putsnl {<a href="intro.html"><h2>SQLite C Interface</h2></a>}
hd_enable_main 1
</tcl>
<h2>List Of Objects:</h2>
<tcl>
output_list "" 3 [lsort -nocase $objlist]
hd_enable_main 0
hd_putsnl {<p>Other lists:
<a href="constlist.html">Constants</a> and
<a href="funclist.html">Functions</a> and
<a href="../rescode.html">Result Codes</a>.}
hd_close_aux
hd_enable_main 1
................................................................................
hd_putsnl {<a href="intro.html"><h2>SQLite C Interface</h2></a>}
hd_enable_main 1
</tcl>
<h2>List Of Constants:</h2>
<p>Also available: [error codes|list of error codes]</p>
<tcl>
set clist [lsort -index 1 $clist]
output_list "" 2 $clist
hd_enable_main 0
hd_putsnl {<p>Other lists:
<a href="objlist.html">Objects</a> and
<a href="funclist.html">Functions</a> and
<a href="../rescode.html">Result Codes</a>.</p>}
hd_enable_main 1
hd_close_aux
................................................................................
</tcl>
<h2>List Of Functions:</h2>
<p>Note: Functions marked with "[experimental | <small><i>(exp)</i></small>]"
are [experimental] and functions marked with
[deprecated | <small><i>(obs)</i></small>] are [deprecated].</p>
<tcl>
set funclist [lsort -index 1 $funclist]
output_list "" 3 $funclist
hd_enable_main 0
hd_putsnl {<p>Other lists:
<a href="constlist.html">Constants</a> and
<a href="objlist.html">Objects</a> and
<a href="../rescode.html">Result Codes</a></p>}
hd_enable_main 1
hd_close_aux
................................................................................

# 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]
  }
  output_list ${label}s: 3 $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]]
................................................................................
  while {[regexp {^(.*?)\[\[([^]]*)\]\](.*)$} $body all fore anchor aft]} {
    hd_resolve $fore
    set anchor [string trim $anchor]
    hd_fragment [hd_fragname $anchor] $anchor
    set body $aft
  }
  hd_resolve $body
  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>