}
append body \n
set intab 1
}
# Read sqlite3session.h line by line and extract interface
# definition information.
#
while {![eof $in]} {
set line [gets $in]
incr lineno
if {$phase==0} {
# Looking for the CAPI3REF: keyword. This marks the beginning of
# an interface definition. When the CAPI3REF keywords is seen,
# 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
# separately.
#
set lx [string range $line 3 end]
if {[regexp {^CATEGORY: +([a-z]*)} $lx all cx]} {
set type $cx
} elseif {[regexp {^KEYWORDS: +(.*)} $lx all kx]} {
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.
#
set phase 2
}
} elseif {$phase==2} {
# Reading in an interface definition. Stop reading at the first blank
# line.
#
# Ignore API tags.
regsub {^SQLITE_DEPRECATED } $line {} line
regsub {^SQLITE_EXPERIMENTAL } $line {} line
regsub {^SQLITE_API } $line {} line
if {$line==""} {
set reqtag {}
set reqdf {}
if {[regexp {\{([AHLS]\d\d\d\d\d)\}} $title all reqtag]} {
regsub { *\{[AHLS]\d\d\d\d\d\}} $title {} title
while {[regexp {<([AHLS]\d\d\d\d\d)>} $title all df]} {
append reqdf <$df>
regsub { *<[AHLS]\d\d\d\d\d>} $title {} title
}
# set keyword($reqtag) 1
}
set kwlist [lsort [array names keyword]]
unset -nocomplain keyword
if {$exflag} {
foreach kw $kwlist {set supported($kw) 1}
} elseif {$obsflag} {
foreach kw $kwlist {set supported($kw) 2}
} else {
foreach kw $kwlist {set supported($kw) 0}
}
set exflag 0
set obsflag 0
set key $type:$kwlist
regsub -all { *\{[\w.]+\}} $body {} body
set body [string map \
{ {(TODO: } )} $body]
set code [string map {& & < < > >} $code]
lappend content [list $key $title $type $kwlist $body $code]
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-z_]+);} $line all kx]} {
set type datatype
set keyword($kx) 1
incr dcnt
} 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
set keyword($kx) 1
incr dcnt
}
append code $line\n
}
}
}
# Convert a tag name into the filename used for the
# multi-file version.
#
# Constants begin with SQLITE_. The names are converted
# to lower case and prefixed with "c_". If we did not
# do this, then the names "SQLITE_BLOB" and "sqlite3_blob"
# would collide.
#
proc convert_keyword_to_filename {oldname} {
set oldname [string tolower $oldname]
regsub {^sqlite_} $oldname {c_} oldname
regsub {^sqlite3_} $oldname {} name
return $name.html
}
hd_open_aux session/intro.html
hd_header Introduction
hd_enable_main 0
hd_keywords *session-capi {Session Extension C-language Interface}
These pages define the C-language interface for the SQLite
[session extension].
This is not a tutorial. These pages are designed to be precise, not
easy to read. A tutorial is [session|available separately].
This version of the C-language interface reference is
broken down into small pages for easy viewing. The
same content is also available as a
single large HTML file
for those who prefer that format.
The content on these pages is extracted from comments
in the source code.
The interface is broken down into three categories:
List Of Objects.
This is a list of the three abstract objects used by the SQLite session
module.
List Of Constants.
This is a list of numeric constants used by the SQLite session module
and represented by #defines in the sqlite3session.h header file. There
are constants passed to conflict handler callbacks to indicate the type
of conflict, and constants returned by the conflict handler to indicate
how the conflict should be resolved.
List Of Functions.
This is a list of all SQLite session module functions.
hd_close_aux
hd_enable_main 1
This page defines the C-language interface to the SQLite
[session extension].
This is not a tutorial. These pages are designed to be precise, not easy
to read. A tutorial is [session extension|available separately].
This page contains all C-language interface information
in a single HTML file. The same information is also
available broken out into lots of small pages
for easier viewing, if you prefer.
This document is created by a script which scans comments in the source
code file sqlite3session.h.
# Find the preferred keyword for a page given a list of
# acceptable keywords.
#
proc preferred_keyword {keyword_list} {
foreach kw $keyword_list {
if {[regexp -nocase {^sqlite} $kw]} break
}
return $kw
}
# Do a table of contents for objects
#
set objlist {}
foreach c $content {
foreach {key title type keywords body code} $c break
if {$type!="datatype"} continue
set keywords [lsort $keywords]
set k [preferred_keyword $keywords]
set s $supported($k)
foreach kw $keywords {
if {[regexp {^sqlite} $kw]} {
lappend objlist [list $k $kw $s]
}
}
}
hd_open_aux session/objlist.html
hd_header {List Of SQLite Objects}
hd_enable_main 0
hd_putsnl {Session Module C Interface
}
hd_enable_main 1
Objects:
hd_list_of_links {} 300 [lsort $objlist]
hd_enable_main 0
hd_putsnl {Other lists:
Constants and
Functions.}
hd_close_aux
hd_enable_main 1
hd_putsnl {
}
# Do a table of contents for constants
#
set clist {}
foreach c $content {
foreach {key title type keywords body code} $c break
if {$type!="constant"} continue
set keywords [lsort $keywords]
set k [preferred_keyword $keywords]
set s $supported($k)
foreach kw $keywords {
if {[regexp {^SQLITE_} $kw]} {
lappend clist [list $k $kw $s]
}
}
}
hd_open_aux session/constlist.html
hd_header {List Of SQLite Constants}
hd_enable_main 0
hd_putsnl {Session Module C Interface
}
hd_enable_main 1
Constants:
set clist [lsort -index 1 $clist]
hd_list_of_links {} 400 $clist
hd_enable_main 0
hd_putsnl {Other lists:
Objects and
Functions.
}
hd_enable_main 1
hd_close_aux
hd_putsnl {
}
# Do a table of contents for functions
#
set funclist {}
foreach c $content {
foreach {key title type keywords body code} $c break
if {$type!="function"} continue
set keywords [lsort $keywords]
set k [preferred_keyword $keywords]
set s $supported($k)
foreach kw $keywords {
if {[regexp {^sqlite} $kw]} {
lappend funclist [list $k $kw $s]
}
}
}
hd_open_aux session/funclist.html
hd_header {List Of SQLite Functions}
hd_keywords *session_funclist {Session Module C-API function list}
hd_enable_main 0
hd_putsnl {Session Module C Interface
}
hd_enable_main 1
Functions:
set funclist [lsort -index 1 $funclist]
hd_list_of_links {} 300 $funclist
hd_enable_main 0
hd_putsnl {Other lists:
Constants and
Objects.
}
hd_enable_main 1
hd_close_aux
hd_putsnl {
}
# 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 "$label: \[[lindex $lx 0]()\]
\n"
return
}
if {$n<=4} {
hd_puts "${label}s:\n"
set sep { }
foreach x $lx {
hd_puts $sep
set sep ",\n"
hd_resolve \[${x}()\]
}
hd_puts "
\n"
return
}
set flst {}
foreach x $lx {
lappend flst [list $x $x 0]
}
hd_list_of_links "${label}s:" 350 $flst
hd_puts "\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_open_aux session/[convert_keyword_to_filename $kw]
hd_header $title
hd_enable_main 0
hd_puts {Session Module C Interface
}
hd_enable_main 1
eval hd_keywords $keywords
hd_puts "$title
"
hd_puts ""
hd_puts "$code"
hd_puts "
"
if {$supported($kw)==1} {
hd_resolve {Important: This interface is [experimental] }
hd_resolve {and is subject to change without notice.
}
}
regsub -all "\n\n+" $body "\n\n" body
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 {See also lists of
Objects,
Constants, and
Functions.
}
hd_enable_main 1
hd_close_aux
hd_puts "
"
}