Documentation Source Text

Check-in [ef1fcd862b]
Login

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

Overview
Comment:Early attempts at requirements.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: ef1fcd862b871b2aa04ca06172a8e2461c3639cb
User & Date: drh 2007-12-01 19:23:41
Context
2007-12-02
12:57
Add the "See Also" sidebar on the About page. The "features" link goes to the Features page, not to the About page. check-in: 53144a576e user: drh tags: trunk
2007-12-01
19:23
Early attempts at requirements. check-in: ef1fcd862b user: drh tags: trunk
2007-11-30
01:34
Fix website typos and external hyperlink changes. check-in: e4ae9bdfda user: drh tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to pages/capi3ref.in.

     1      1   <title>C/C++ Interface For SQLite Version 3</title>
     2      2   
     3      3   <h2 class=pdf_section>C/C++ Interface For SQLite Version 3</h2>
     4      4   
     5      5   <tcl>
     6      6   set in [open sqlite3.h]
     7         -set title {}
     8         -set type {}
     9         -set body {}
    10         -set code {}
    11         -set phase 0
    12         -set content {}
    13         -set lineno 0
    14         -set reqdb [open reqdb.sql w]
            7  +set title {}       ;# title of a section of interface definition
            8  +set type {}        ;# one of: constant datatype function
            9  +set body {}        ;# human-readable description
           10  +set code {}        ;# C code of the definition
           11  +set phase 0        ;# Phase used by the parser 
           12  +set content {}     ;# List of records, one record per definition
           13  +set dcnt 0         ;# Number of individual declarations
           14  +set lineno 0       ;# input file line number
           15  +
           16  +# Read sqlite3.h line by line and extract interface definition
           17  +# information.
           18  +#
    15     19   while {![eof $in]} {
    16     20     set line [gets $in]
    17     21     incr lineno
    18     22     if {$phase==0} {
    19     23       # Looking for the CAPI3REF: keyword
    20     24       if {[regexp {^\*\* CAPI3REF: +(.*)} $line all tx]} {
    21     25         set title $tx
................................................................................
    38     42         set phase 2
    39     43       }
    40     44     } elseif {$phase==2} {
    41     45       if {$line==""} {
    42     46         set kwlist [lsort [array names keyword]]
    43     47         unset -nocomplain keyword
    44     48         set key $type:$kwlist
    45         -      if {[regexp {\{([\w.]+)\}} $title all tag]} {
    46         -        regsub { *\{[\w.]+\}} $title {} title
    47         -        set qtitle '[string map {' ''} \
    48         -            $title\n<blockquote><pre>\n$code\n</pre></blockquote>]'
    49         -        real_puts $reqdb "INSERT INTO req\
    50         -           VALUES('$tag','sqlite3.h',$lineno,$qtitle);"
    51         -      }
    52         -      regsub -all { *\{[a-zA-Z0-9.]+\}} $body {} body
           49  +      regsub { *\{[\w.]+\}} $title {} title
           50  +      regsub -all { *\{[\w.]+\}} $body {} body
    53     51         lappend content [list $key $title $type $kwlist $body $code]
    54     52         set title {}
    55     53         set keywords {}
    56     54         set type {}
    57     55         set body {}
    58     56         set code {}
    59     57         set phase 0
           58  +      set dcnt 0
    60     59       } else {
    61     60         if {[regexp {^#define (SQLITE_[A-Z0-9_]+)} $line all kx]} {
    62     61           set type constant
    63     62           set keyword($kx) 1
           63  +        incr dcnt
    64     64         } elseif {[regexp {^typedef .*(sqlite[0-9a-z_]+);} $line all kx]} {
    65     65           set type datatype
    66     66           set keyword($kx) 1
           67  +        incr dcnt
    67     68         } elseif {[regexp {^[a-z].*[ *](sqlite3_[a-z0-9_]+)\(} $line all kx]} {
    68     69           set type function
    69     70           set keyword($kx) 1
           71  +        incr dcnt
    70     72         } elseif {[regexp {^SQLITE_EXTERN .*(sqlite[0-9a-z_]+);} $line all kx]} {
    71     73           set type datatype
    72     74           set keyword($kx) 1
           75  +        incr dcnt
    73     76         }
    74     77         append code $line\n
    75     78       }
    76     79     }
    77     80   }
    78     81   
    79     82   

Added pages/requirements.in.

            1  +<title>SQLite Requirements</title>
            2  +
            3  +<h2>SQLite Requirements</h2>
            4  +
            5  +<p>This document is a work in progress.</p>
            6  +
            7  +<p>The goal of this document is to provide an precise and exact
            8  +definition of what SQLite does, how it works, and what to expect
            9  +from SQLite for any given input.  When completed, this document
           10  +will become the authoritative reference for using SQLite.</p>
           11  +
           12  +<h3>The C/C++ Interface</h3>
           13  +
           14  +<table cellspacing="20" border="0">
           15  +
           16  +<tcl>
           17  +# Extract requirements from the sqlite3.h header file
           18  +#
           19  +set in [open sqlite3.h]
           20  +set title {}       ;# Title of an interface
           21  +set body {}        ;# human-readable description
           22  +set code {}        ;# C code of the definition
           23  +set phase 0        ;# Phase used by the parser 
           24  +set reqlist {}     ;# List of requirements, on record per requirement entry
           25  +set dcnt 0         ;# Number of individual declarations
           26  +set lineno 0       ;# input file line number
           27  +
           28  +# Split the input string $in at the first {...} marker.  Store the text
           29  +# before the marker in the prefixvar.  Store the content of the marker
           30  +# in tagvar.  And store the text after the marker in tailvar.
           31  +#
           32  +proc split_text {in prefixvar tagvar tailvar} {
           33  +  if {[regexp -indices {\{[\w.]+\}} $in i]} {
           34  +    upvar 1 $prefixvar prefix
           35  +    upvar 1 $tagvar tag
           36  +    upvar 1 $tailvar tail
           37  +    foreach {front back} $i break
           38  +    set x0 [expr {$front-1}]
           39  +    set prefix [string range $in 0 $x0]
           40  +    set x1 [expr {$front+1}]
           41  +    set x2 [expr {$back-1}]
           42  +    set tag [string range $in $x1 $x2]
           43  +    set x3 [expr {$back+1}]
           44  +    set tail [string range $in $x3 end]
           45  +    return 1
           46  +  } else {
           47  +    return 0
           48  +  }
           49  +}
           50  +
           51  +# Read sqlite3.h line by line and extract interface definition
           52  +# information.
           53  +#
           54  +while {![eof $in]} {
           55  +  set line [gets $in]
           56  +  incr lineno
           57  +  if {$phase==0} {
           58  +    # Looking for the CAPI3REF: keyword
           59  +    if {[regexp {^\*\* CAPI3REF: +(.*)} $line all tx]} {
           60  +      set title $tx
           61  +      set title_lineno $lineno
           62  +      set phase 1
           63  +    }
           64  +  } elseif {$phase==1} {
           65  +    if {[string range $line 0 1]=="**"} {
           66  +      set lx [string trim [string range $line 3 end]]
           67  +      if {[regexp {^CATEGORY: +([a-z]*)} $lx all cx]} {
           68  +        set type $cx
           69  +      } elseif {[regexp {^KEYWORDS: +(.*)} $lx all kx]} {
           70  +        foreach k $kx {
           71  +          set keyword($k) 1
           72  +        }
           73  +      } else {
           74  +        append body $lx\n
           75  +      }
           76  +    } elseif {[string range $line 0 1]=="*/"} {
           77  +      set phase 2
           78  +    }
           79  +  } elseif {$phase==2} {
           80  +    if {$line==""} {
           81  +      set kwlist [lsort [array names keyword]]
           82  +      unset -nocomplain keyword
           83  +      set key $type:$kwlist
           84  +      if {[regexp {\{([\w.]+)\}} $title all tag]} {
           85  +        regsub { *\{[\w.]+\}} $title {} title
           86  +        if {$dcnt>1} {set d declarations} {set d {a declaration}}
           87  +        set req "The \"sqlite3.h\" header file\
           88  +            shall contain $d equivalent to the following:\
           89  +            \n<blockquote><pre>\n$code</pre></blockquote>"
           90  +        regexp {\d+} $tag key
           91  +        lappend reqlist [list $key $tag sqlite3.h $title_lineno $req {}]
           92  +      }
           93  +      set x $body
           94  +      while {[split_text $x prefix tag suffix]} {
           95  +        if {![split_text $suffix req endtag tail]} {
           96  +          set req $suffix
           97  +          set x {}
           98  +          set ex {}
           99  +        } elseif {$endtag=="END"} {
          100  +          set ex {}
          101  +          set x $tail
          102  +        } elseif {$endtag=="EX"} {
          103  +          if {![split_text $tail ex end2 tail2]} {
          104  +            set ex $tail
          105  +            set x {}
          106  +          } elseif {$end2=="END"} {
          107  +            set x $tail2
          108  +          } else {
          109  +            set x "{$end2} $tail2"
          110  +          }
          111  +        } else {
          112  +          set ex {}
          113  +          set x "{$endtag} $tail"
          114  +        }
          115  +        regsub -all {\[([^]|]+\|)?([^]]+)\]} $req {\2} req
          116  +        regsub -all {\s+} $req { } req
          117  +        set req [string trim $req]
          118  +        regsub -all {\[([^]|]+\|)?([^]]+)\]} $ex {\2} ex
          119  +        regsub -all {\s+} $ex { } ex
          120  +        set ex [string trim $ex]
          121  +        regexp {\d+} $tag key
          122  +        lappend reqlist [list $key $tag sqlite3.h $title_lineno $req $ex]
          123  +      }
          124  +      set title {}
          125  +      set keywords {}
          126  +      set type {}
          127  +      set body {}
          128  +      set code {}
          129  +      set phase 0
          130  +      set dcnt 0
          131  +    } else {
          132  +      if {[regexp {^#define (SQLITE_[A-Z0-9_]+)} $line all kx]} {
          133  +        set type constant
          134  +        set keyword($kx) 1
          135  +        incr dcnt
          136  +      } elseif {[regexp {^typedef .*(sqlite[0-9a-z_]+);} $line all kx]} {
          137  +        set type datatype
          138  +        set keyword($kx) 1
          139  +        incr dcnt
          140  +      } elseif {[regexp {^[a-z].*[ *](sqlite3_[a-z0-9_]+)\(} $line all kx]} {
          141  +        set type function
          142  +        set keyword($kx) 1
          143  +        incr dcnt
          144  +      } elseif {[regexp {^SQLITE_EXTERN .*(sqlite[0-9a-z_]+);} $line all kx]} {
          145  +        set type datatype
          146  +        set keyword($kx) 1
          147  +        incr dcnt
          148  +      }
          149  +      append code $line\n
          150  +    }
          151  +  }
          152  +}
          153  +
          154  +foreach req [lsort -index 0 $reqlist] {
          155  +  foreach {key tag file lineno text ex} $req break
          156  +  puts "<tr><td valign=\"top\">$tag</td>"
          157  +  puts "<td valign=\"top\"><b>$text</b>"
          158  +  if {$ex!=""} {
          159  +    puts "<p>$ex</p>"
          160  +  }
          161  +  puts "</td></tr>"
          162  +}
          163  +</tcl>
          164  +
          165  +</table>