}
append body \n
set intab 1
}
# Read sqlite3.c line by line and extract interface definition
# information (found in what was originally sqlite3.h).
#
while {![eof $in]} {
set line [gets $in]
if {[regexp {^/\*+ Begin file sqlite3session} $line]} {
while {![regexp {^/\*+ End of sqlite3session } $line] && ![eof $in]} {
set line [gets $in]
incr lineno
}
continue
}
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 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 trim [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 {^FRAGMENT: +(.*)} $lx all kx]} {
set fragname [lindex $kx 0]
append body "\n"
} 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-zA-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
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} {
regsub {_FILE} $oldname {_stdiofile} oldname
set oldname [string tolower $oldname]
regsub {^sqlite_} $oldname {c_} oldname
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 {}
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 {}
for {set j $start} {$j<$end} {incr j} {
set entry [lindex $lx $j]
if {$entry!=""} {
foreach {link label s} $entry break
if {$s==1} {
hd_resolve "- \[$link|$label\] "
hd_resolve "\[experimental | (exp)\]
"
} elseif {$s==2} {
hd_resolve "- \[$link|$label\] "
hd_resolve "\[deprecated | (obs)\]
"
} else {
hd_resolve "- \[$link|$label\]
"
}
hd_puts \n
}
}
hd_putsnl { | }
}
hd_putsnl {
}
}
hd_open_aux c3ref/intro.html
hd_header Introduction
hd_enable_main 0
hd_keywords *capi3ref {C-language Interface}
These pages define the C-language interface to SQLite.
This is not a tutorial. These
pages are designed to be precise, not easy to read.
For a tutorial introduction see
[quickstart | SQLite In 3 Minutes Or Less] and/or
the [cintro | Introduction To The SQLite C/C++ Interface].
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 all abstract objects and datatypes used by the
SQLite library. There are couple dozen objects in total, but
the three most important objects are:
A database connection object [sqlite3],
prepared statement object [sqlite3_stmt], and the 64-bit integer
type [sqlite3_int64].
List Of Constants.
This is a list of numeric constants used by SQLite and represented by
#defines in the sqlite3.h header file. These constants
are things such as numeric return parameters from
various interfaces (ex: [SQLITE_OK] or flags passed
into functions to control behavior
(ex: [SQLITE_OPEN_READONLY]).
List Of Functions.
This is a list of all functions and methods operating on the
objects and using and/or
returning constants. There
are many functions, but most applications only use a handful.
hd_close_aux
hd_enable_main 1
This page defined the C-language interface to SQLite.
This is not a tutorial. These
pages are designed to be precise, not easy to read.
For a tutorial introduction see
[quickstart | SQLite In 3 Minutes Or Less] and/or
the [cintro | Introduction To The SQLite C/C++ Interface].
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 files.
# Find the preferred keyword for a page given a list of
# acceptable keywords.
#
proc preferred_keyword {keyword_list} {
set kw {}
foreach kw $keyword_list {
if {[regexp -nocase {^sqlite} $kw]} break
}
return $kw
}
# Do a page explaining what "experimental" means.
hd_open_aux c3ref/experimental.html
hd_header {Experimental Interfaces}
hd_enable_main 0
hd_puts {SQLite C Interface
}
hd_enable_main 1
hd_keywords experimental deprecated
Experimental And Deprecated Interfaces
SQLite interfaces can be subdivided into three categories:
- Stable
- Experimental
- Deprecated
Stable interfaces will be maintained indefinitely in a backwards
compatible way. An application that uses only stable interfaces
should always be able to relink against a newer version of SQLite
without any changes.
Experimental interfaces are subject to change.
Applications that use experimental interfaces
may need to be modified when upgrading to a newer SQLite release, though
this is rare.
When new interfaces are added to SQLite, they generally begin
as experimental interfaces. After an interface has been in use for
a while and the developers are confident that the design of the interface
is sound and worthy of long-term support, the interface is marked
as stable.
Deprecated interfaces have been superceded by better methods of
accomplishing the same thing and should be avoided in new applications.
Deprecated interfaces continue to be supported for the sake of
backwards compatibility. At some point in the future, it is possible
that deprecated interfaces may be removed.
Key points:
- Experimental interfaces are subject to change and/or removal
at any time.
- Deprecated interfaces should not be used in new code and might
be removed in some future release.
hd_close_aux
hd_puts {
}
# 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 -nocase $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 c3ref/objlist.html
hd_header {List Of SQLite Objects}
hd_enable_main 0
hd_putsnl {SQLite C Interface
}
hd_enable_main 1
Objects:
Note: Objects marked with "[experimental | exp]"
are [experimental] and objects marked with
"[deprecated | (obs)]" are [deprecated].
output_list 3 [lsort -nocase $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] && ![regexp {[^A-Z_0-9]} $kw]} {
lappend clist [list $kw $kw $s]
}
}
}
hd_open_aux c3ref/constlist.html
hd_header {List Of SQLite Constants}
hd_enable_main 0
hd_putsnl {SQLite C Interface
}
hd_enable_main 1
Constants:
Note: Constants marked with "[experimental | (exp)]"
are [experimental] and constants marked with
"[deprecated | (obs)]" are [deprecated]
set clist [lsort -index 1 $clist]
output_list 2 $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 c3ref/funclist.html
hd_header {List Of SQLite Functions}
hd_keywords *capi3ref_funclist {C-API function list}
hd_enable_main 0
hd_putsnl {SQLite C Interface
}
hd_enable_main 1
Functions:
Note: Functions marked with "[experimental | (exp)]"
are [experimental] and functions marked with
[deprecated | (obs)] are [deprecated].
set funclist [lsort -index 1 $funclist]
output_list 3 $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
}
# Output all the records
#
foreach c [lsort $content] {
foreach {key title type keywords body code} $c break
set kw [preferred_keyword [lsort $keywords]]
if {$kw==""} {error "no keyword for $c"}
hd_fragment $kw
hd_open_aux c3ref/[convert_keyword_to_filename $kw]
hd_header $title
hd_enable_main 0
hd_puts {SQLite 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
set body
$body
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 {See also lists of
Objects,
Constants, and
Functions.
}
hd_enable_main 1
hd_close_aux
hd_puts "
"
}