Documentation Source Text

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

docdir:
	mkdir -p doc 

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:	

        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 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 {</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>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 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 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 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>

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 {

  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]










  PutsHeader $title

































































  regsub -all {<tcl>} $in "\175; eval \173" in
  regsub -all {</tcl>} $in "\175; puts \173" in
  eval "puts \173$in\175"
  cd $::HOMEDIR

  PutsFooter $infile



  close $::OUT
}