Documentation Source Text

Check-in [ae0c38c662]
Login

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

Overview
Comment:Generate C interface reference document both as the single big file and also as lots of individual small files.
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: ae0c38c66299089a0bee3dec5fca6ee3bf910f77
User & Date: drh 2007-11-12 20:38:33.000
Context
2007-11-13
01:24
Cleaned up the famous users webpage. Work on the about page. (check-in: 8a34ae6a2f user: drh tags: trunk)
2007-11-12
20:38
Generate C interface reference document both as the single big file and also as lots of individual small files. (check-in: ae0c38c662 user: drh tags: trunk)
15:32
Complete reorganization of the documentation sources. (check-in: 275febef8f user: drh tags: trunk)
Changes
Side-by-Side Diff Show Whitespace Changes Patch
Changes to main.mk.
︙
33
34
35
36
37
38
39
40

41
42
43
44
45
46
47

33
34
35
36
37
38
39

40
41
42
43
44
45
46
47








-
+









capi3ref.html:	$(DOC)/mkapidoc.tcl sqlite3.h
	tclsh $(DOC)/mkapidoc.tcl <sqlite3.h >capi3ref.html

docdir:
	mkdir -p doc 

doc:	docdir always
doc:	sqlite3.h docdir always
	rm -rf doc/images
	cp -r $(DOC)/images doc
	cp $(DOC)/rawpages/* doc
	tclsh $(DOC)/wrap.tcl $(DOC) $(SRC) doc $(DOC)/pages/*.in

always:
︙
Changes to pages/capi3ref.in.
︙
51
52
53
54
55
56
57



58
59
60
61
62
63




















64
65
66


67
68
69
70
71
72
73
74
75
76
77





78

79
80
81
82
83
84























































































85
86
87
88
89
90
91
92
93
94
95
96
97
98
99


100






101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116

117






118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134

135






136

137

138
139
140
141
142
143
144
145
146
147
148
149






















150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166





167















168

51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88

89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106

107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213


214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237

238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261

262
263
264
265
266
267
268
269
270
271

272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345








+
+
+






+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+


-
+
+











+
+
+
+
+
-
+






+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+













-
-
+
+

+
+
+
+
+
+















-
+

+
+
+
+
+
+
















-
+

+
+
+
+
+
+

+
-
+












+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

















+
+
+
+
+

+
+
+
+
+
+
+
+
+
+
+
+
+
+
+


        set keyword($kx) 1
      } elseif {[regexp {^typedef .* (sqlite[0-9a-z_]+);} $line all kx]} {
        set type datatype
        set keyword($kx) 1
      } elseif {[regexp {^[a-z].*[ *](sqlite3_[a-z0-9_]+)\(} $line all kx]} {
        set type function
        set keyword($kx) 1
      } elseif {[regexp {^SQLITE_EXTERN .*(sqlite[0-9a-z_]+);} $line all kx]} {
        set type datatype
        set keyword($kx) 1
      }
      append code $line\n
    }
  }
}


# Convert a tag name into the filename used for the
# multi-file version.
#
proc convert_tag_name {oldname} {
  regsub -nocase {^sqlite3?_} $oldname {} name
  return $name.html
}

# Compute a mapping from keywords to filenames.
#
unset -nocomplain keyword_to_file
foreach c [lsort $content] {
  foreach {key title type keywords body code} $c break
  set file [convert_tag_name [lindex $keywords 0]]
  foreach k $keywords {
    set keyword_to_file($k) $file
  }
}

# Output HTML that displays the given list in N columns
#
proc output_list {N lx} {
proc output_list {N lx multi} {
  global keyword_to_file
  puts {<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}]
    puts {<td valign="top"><ul>}
    for {set j $start} {$j<$end} {incr j} {
      set entry [lindex $lx $j]
      if {$entry!=""} {
        foreach {link label} $entry break
        if {$multi} {
          set link $keyword_to_file($link)
        } else {
          set link "#link"
        }
        puts "<li><a href=\"#$link\">$label</a></li>"
        puts "<li><a href=\"$link\">$label</a></li>"
      }
    }
    puts {</ul></td>}
  }
  puts {</tr></table>}
}

# Open a separate output file for a single interface
#
proc c3ref_open_file {filename title} {
  global DEST OUT save_OUT
  file mkdir $DEST/c3ref
  set save_OUT $OUT
  set OUT [open $DEST/c3ref/$filename w]
  PutsHeader "SQLite C Interface: $title" ../
  puts {<a href="intro.html"><h2>SQLite C Interface</h2></a>}
  puts "<h3>$title</h3>"
}
proc c3ref_close_file {} {
  global HOMEDIR OUT save_OUT
  PutsFooter $HOMEDIR/sqlite3.h
  close $OUT
  set OUT $save_OUT
}

c3ref_open_file intro.html Introduction
</tcl>

<p>These pages defined the C-language interface to SQLite.
These pages are intended as a reference to what SQLite
is suppose to do.  This is not a tutorial.  These
pages are designed to be precise, not easy to read.</p>

<p>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
<a href="../capi3ref.html">single large HTML file</a>
for those who prefer that format.</p>

<p>The content on these pages is extracted from comments
in the source code.</p>

<p>The interface is broken down into three catagories:</p>

<ol>
<li><p><a href="objlist.html"><b>List Of Objects.</b></a>
    All abstract objects and datatypes used by the
    SQLite library.  There are a handful of objects, but
    only three which most users need to be aware of:
    A database connection object
    <a href="sqlite3.html">sqlite3</a>, a prepared statement
    object <a href="stmt.html">sqlite3_stmt</a>, and the 64-bit integer
    type <a href="int64.html">sqlite3_int64</a>.</p></li>

<li><p><a href="constlist.html"><b>List Of Constants.</b></a>
    Numeric constants just 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: 
    <a href="ABORT.html">SQLITE_OK</a>) or flags passed
    into functions to control behavior
    (ex: <a href="OPEN_CREATE.html">SQLITE_OPEN_READONLY</a>).</p></li>

<li><p><a href="funclist.html"><b>List Of Functions.</b></a>
    Functions and/or methods operating on the 
    <a href="objlist.html">objects</a> and using and/or
    returning <a href="constlist.html">constants</a>.  There
    are many function, but most applications only use a handful.
    </p></li>
</ol>

<tcl>
c3ref_close_file

</tcl>

<p>This page defined the C-language interface to SQLite.
This page is intended as a reference to what SQLite
is suppose to do.  This is not a tutorial.  This
page is designed to be precise, not easy to read.</p>

<p>This page contains all C-language interface information
in a single HTML file.  The same information is also
available broken out into 
<a href="c3ref/intro.html">lots of small pages</a>
for easier viewing, if you prefer.</p>

<p>The content on this document is extracted from comments
in the source code.</p>

<hr>

<tcl>

# 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 [lindex $keywords 0]
  foreach kw $keywords {
    lappend objlist [list $k $kw]
  }
}
puts {<h2>Datatypes:</h2>}
output_list 3 $objlist
puts {<h2>Objects:</h2>}
output_list 3 $objlist 0
puts {<hr>}
c3ref_open_file objlist.html Objects
output_list 3 $objlist 1
puts {<p>Other lists:
<a href="constlist.html">Constants</a> and
<a href="funclist.html">Functions</a>.}
c3ref_close_file

# 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 [lindex $keywords 0]
  foreach kw $keywords {
    lappend clist [list $k $kw]
  }
}
puts {<h2>Constants:</h2>}
set clist [lsort -index 1 $clist]
output_list 3 $clist
output_list 2 $clist 0
puts {<hr>}
c3ref_open_file constlist.html Constants
output_list 2 $clist 1
puts {<p>Other lists:
<a href="objlist.html">Objects</a> and
<a href="funclist.html">Functions</a>.</p>}
c3ref_close_file


# 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 [lindex $keywords 0]
  foreach kw $keywords {
    lappend funclist [list $k $kw]
  }
}
puts {<h2>Functions:</h2>}
set funclist [lsort -index 1 $funclist]
output_list 3 $funclist
output_list 3 $funclist 0
puts {<hr>}
c3ref_open_file funclist.html Functions
output_list 3 $funclist 1
puts {<p>Other lists:
<a href="constlist.html">Constants</a> and
<a href="objlist.html">Objects</a>.</p>}
c3ref_close_file


# Resolve links
# Resolve links to anchors in the single-file spec.
#
proc resolve_links {args} {
  set tag [lindex $args 0]
  regsub -all {[^a-zA-Z0-9_]} $tag {} tag
  set x "<a href=\"#$tag\">"
  if {[llength $args]>2} {
    append x [lrange $args 2 end]</a>
  } else {
    append x [lindex $args 0]</a>
  }
  return $x
}

# Resolve links to anchors in the multi-file spec.
#
proc resolve_m_links {args} {
  set tag [lindex $args 0]
  regsub -all {[^a-zA-Z0-9_]} $tag {} tag
  global keyword_to_file
  if {[info exists keyword_to_file($tag)]} {
    set tag $keyword_to_file($tag)
    set begin "<a href=\"$tag\">"
    set end "</a>"
  } else {
    set begin ""
    set end ""
  }
  if {[llength $args]>2} {
    append x $begin[lrange $args 2 end]$end
  } else {
    append x $begin[lindex $args 0]$end
  }
  return $x
}

# Output all the records
#
foreach c [lsort $content] {
  foreach {key title type keywords body code} $c break
  foreach k $keywords {
    puts "<a name=\"$k\"></a></a>"
  }
  puts "<h2>$title</h2>"
  puts "<blockquote><pre>"
  puts "$code"
  puts "</pre></blockquote>"
  regsub -all "\n\n+" $body {</p>\1<p>} body
  regsub -all {\[} <p>$body</p> {[resolve_links } body
  set body [subst -novar -noback $body]
  puts "$body"
  puts "<hr>"
  set fkey [lindex $keywords 0]
  if {![info exists keyword_to_file($fkey)]} {
    real_puts fkey=$fkey
    real_puts c=$c
    exit
}
  c3ref_open_file $::keyword_to_file($fkey) $title
  puts "<blockquote><pre>"
  puts "$code"
  puts "</pre></blockquote>"
  set body [lindex $c 4]
  regsub -all "\n\n+" $body {</p>\1<p>} body
  regsub -all {\[} <p>$body</p> {[resolve_m_links } body
  set body [subst -novar -noback $body]
  puts "$body"
  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>}
  c3ref_close_file
}
</tcl>
Changes to wrap.tcl.
︙
26
27
28
29
30
31
32



























































































33
34
35
36
37
38
39

26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130








+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+








set DEST [lindex $argv 2]
set HOMEDIR [pwd]
rename puts real_puts
proc puts {text} {
  real_puts $::OUT $text
  flush $::OUT
}
proc putsin4 {text} {
  regsub -all "\n    " $text \n text
  real_puts $::OUT [uplevel 1 [list subst -noback -nocom $text]]
  flush $::OUT
}
proc PutsHeader {title {relpath {}}} {
  puts {<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">}
  puts {<html><head>}
  puts "<title>$title</title>"
  putsin4 {<style type="text/css">
    body {
        max-width: 800px; /* not supported in IE 6 */
        margin: auto;
        font-family: "Verdana" "sans-serif";
        padding: 8px 1%;
    }
    
    a { color: #4F7263 }
    a:visited { color: #80a796 }
    
    .logo { position:absolute; margin:3px; }
    .tagline {
      float:right;
      text-align:right;
      font-style:italic;
      width:240px;
      margin:12px;
      margin-top:58px;
    }
    
    .toolbar {
      background-color: #80a796;
      position: relative;
      font-variant: small-caps;
      clear: both;
      text-align: center;
      line-height: 1.6em;
      margin-bottom: 5px;
      padding:1px 8px;
      height:1%; /* IE hack to fix rounded corner positions */
    }
    .toolbar a { color: white; text-decoration: none; padding: 6px 4px; }
    .toolbar a:visited { color: white; }
    .toolbar a:hover { color: #80a796; background: white; }
    
    .content    { margin: 5%; }
    .content dt { font-weight:bold; }
    .content dd { margin-bottom: 25px; margin-left:20%; }
    .content ul { padding:0px; padding-left: 15px; margin:0px; }
    
    /* rounded corners */
    .se,.ne,.nw,.sw { position: absolute; width:8px; height:8px; 
                      font-size:7px; /* IE hack to ensure height=8px */ }
    .se  { background-image: url(${relpath}se.png); bottom: 0px; right: 0px; }
    .ne  { background-image: url(${relpath}ne.png); top: 0px;    right: 0px; }
    .sw  { background-image: url(${relpath}sw.png); bottom: 0px; left: 0px; }
    .nw  { background-image: url(${relpath}nw.png); top: 0px;    left: 0px; }
    </style>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8">
  }
  puts {</head>}
  putsin4 {<body>
    <div><!-- container div to satisfy validator -->
    
    <img class="logo" src="${relpath}SQLite.gif" alt="SQLite Logo">
    <div><!-- IE hack to prevent disappearing logo--></div>
    <div class="tagline">The World's Most Used SQL Database.</div>
    
    <div class="toolbar">
      <a href="${relpath}index.html">Home</a>
      <a href="${relpath}about.html">About</a>
      <a href="${relpath}docs.html">Documentation</a>
      <a href="${relpath}download.html">Download</a>
      <a href="${relpath}copyright.html">License</a>
      <a href="${relpath}press.html">Advocacy</a>
      <a href="${relpath}devhome.html">Developers</a>
      <a href="${relpath}news.html">News</a>
      <a href="${relpath}support.html">Support</a>
      <!-- rounded corners -->
      <div class="ne"></div><div class="se"></div><div class="nw">
      </div><div class="sw"></div>
    </div>
  }
}
proc PutsFooter {srcfile} {
  puts {<hr><small><i>}
  set mtime [file mtime $srcfile]
  set date [clock format $mtime -format {%Y/%m/%d %H:%M:%S UTC} -gmt 1]
  puts "This page last modified $date"
  puts {</i></small></div></body></html>}
}

# The following proc is used to ensure consistent formatting in the 
# HTML generated by lang.tcl and pragma.tcl.
#
proc Syntax {args} {
  puts {<table cellpadding="10" class=pdf_syntax>}
  foreach {rule body} $args {
︙
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84

85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155

156
157
158
159
160

158
159
160
161
162
163
164











165

































































166
167
168
169


170



171
172








-
-
-
-
-
-
-
-
-
-
-
+
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-




-
-
+
-
-
-



  set in [read $fd]
  close $fd
  set title {No Title}
  regexp {<title>([^\n]*)</title>} $in all title
  regsub {<title>[^\n]*</title>} $in {} in
  set outfile [file root [file tail $infile]].html
  set ::OUT [open $::DEST/$outfile w]
  puts {<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">}
  puts {<html><head>}
  puts "<title>$title</title>"
  puts {<style type="text/css">
    body {
        max-width: 800px; /* not supported in IE 6 */
        margin: auto;
        font-family: "Verdana" "sans-serif";
        padding: 8px 1%;
    }
    
  PutsHeader $title
    a { color: #4F7263 }
    a:visited { color: #80a796 }
    
    .logo { position:absolute; margin:3px; }
    .tagline {
      float:right;
      text-align:right;
      font-style:italic;
      width:240px;
      margin:12px;
      margin-top:58px;
    }
    
    .toolbar {
      background-color: #80a796;
      position: relative;
      font-variant: small-caps;
      clear: both;
      text-align: center;
      line-height: 1.6em;
      margin-bottom: 50px;
      padding:1px 8px;
      height:1%; /* IE hack to fix rounded corner positions */
    }
    .toolbar a { color: white; text-decoration: none; padding: 6px 4px; }
    .toolbar a:visited { color: white; }
    .toolbar a:hover { color: #80a796; background: white; }
    
    .content    { margin: 5%; }
    .content dt { font-weight:bold; }
    .content dd { margin-bottom: 25px; margin-left:20%; }
    .content ul { padding:0px; padding-left: 15px; margin:0px; }
    
    /* rounded corners */
    .se,.ne,.nw,.sw { position: absolute; width:8px; height:8px; 
                      font-size:7px; /* IE hack to ensure height=8px */ }
    .se             { background-image: url(se.png); bottom: 0px; right: 0px; }
    .ne             { background-image: url(ne.png); top: 0px;    right: 0px; }
    .sw             { background-image: url(sw.png); bottom: 0px; left: 0px; }
    .nw             { background-image: url(nw.png); top: 0px; left: 0px; }
    </style>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8">
  }
  puts {</head>}
  puts {<body>
    <div><!-- container div to satisfy validator -->
    
    <img class="logo" src="http://www.sqlite.org/SQLite.gif" alt="SQLite Logo">
    <div><!-- IE hack to prevent disappearing logo--></div>
    <div class="tagline">The World's Most Used SQL Database.</div>
    
    <div class="toolbar">
      <a href="index.html">Home</a>
      <a href="about.html">About</a>
      <a href="docs.html">Documentation</a>
      <a href="download.html">Download</a>
      <a href="copyright.html">License</a>
      <a href="press.html">Advocacy</a>
      <a href="devhome.html">Developers</a>
      <a href="news.html">News</a>
      <a href="support.html">Support</a>
      <!-- rounded corners -->
      <div class="ne"></div><div class="se"></div><div class="nw"></div><div class="sw"></div>
    </div>
  }
  regsub -all {<tcl>} $in "\175; eval \173" in
  regsub -all {</tcl>} $in "\175; puts \173" in
  eval "puts \173$in\175"
  cd $::HOMEDIR
  puts {<hr><small><i>}
  set mtime [file mtime $infile]
  PutsFooter $infile
  set date [clock format $mtime -format {%Y/%m/%d %H:%M:%S UTC} -gmt 1]
  puts "This page last modified $date"
  puts {</i></small></div></body></html>}
  close $::OUT
}