| 1 |
# |
| 2 |
# 2014 August 24 |
| 3 |
# |
| 4 |
# The author disclaims copyright to this source code. In place of |
| 5 |
# a legal notice, here is a blessing: |
| 6 |
# |
| 7 |
# May you do good and not evil. |
| 8 |
# May you find forgiveness for yourself and forgive others. |
| 9 |
# May you share freely, never taking more than you give. |
| 10 |
# |
| 11 |
#-------------------------------------------------------------------------- |
| 12 |
# |
| 13 |
# This script extracts the documentation for the API used by fts5 auxiliary |
| 14 |
# functions from header file fts5.h. It outputs html text on stdout that |
| 15 |
# is included in the documentation on the web. |
| 16 |
# |
| 17 |
|
| 18 |
set ::fts5_docs_output "" |
| 19 |
if {[info commands hd_putsnl]==""} { |
| 20 |
if {[llength $argv]>0} { set ::extract_api_docs_mode [lindex $argv 0] } |
| 21 |
proc output {text} { |
| 22 |
puts $text |
| 23 |
} |
| 24 |
} else { |
| 25 |
proc output {text} { |
| 26 |
append ::fts5_docs_output "$text\n" |
| 27 |
} |
| 28 |
} |
| 29 |
if {[info exists ::extract_api_docs_mode]==0} {set ::extract_api_docs_mode api} |
| 30 |
|
| 31 |
|
| 32 |
set input_file [file join [file dir [info script]] fts5.h] |
| 33 |
set fd [open $input_file] |
| 34 |
set data [read $fd] |
| 35 |
close $fd |
| 36 |
|
| 37 |
|
| 38 |
# Argument $data is the entire text of the fts5.h file. This function |
| 39 |
# extracts the definition of the Fts5ExtensionApi structure from it and |
| 40 |
# returns a key/value list of structure member names and definitions. i.e. |
| 41 |
# |
| 42 |
# iVersion {int iVersion} xUserData {void *(*xUserData)(Fts5Context*)} ... |
| 43 |
# |
| 44 |
proc get_struct_members {data} { |
| 45 |
|
| 46 |
# Extract the structure definition from the fts5.h file. |
| 47 |
regexp "struct Fts5ExtensionApi {(.*?)};" $data -> defn |
| 48 |
|
| 49 |
# Remove all comments from the structure definition |
| 50 |
regsub -all {/[*].*?[*]/} $defn {} defn2 |
| 51 |
|
| 52 |
set res [list] |
| 53 |
foreach member [split $defn2 {;}] { |
| 54 |
|
| 55 |
set member [string trim $member] |
| 56 |
if {$member!=""} { |
| 57 |
catch { set name [lindex $member end] } |
| 58 |
regexp {.*?[(][*]([^)]*)[)]} $member -> name |
| 59 |
lappend res $name $member |
| 60 |
} |
| 61 |
} |
| 62 |
|
| 63 |
set res |
| 64 |
} |
| 65 |
|
| 66 |
proc get_struct_docs {data names} { |
| 67 |
# Extract the structure definition from the fts5.h file. |
| 68 |
regexp {EXTENSION API FUNCTIONS(.*?)[*]/} $data -> docs |
| 69 |
|
| 70 |
set current_doc "" |
| 71 |
set current_header "" |
| 72 |
|
| 73 |
foreach line [split $docs "\n"] { |
| 74 |
regsub {[*]*} $line {} line |
| 75 |
if {[regexp {^ } $line]} { |
| 76 |
append current_doc "$line\n" |
| 77 |
} elseif {[string trim $line]==""} { |
| 78 |
if {$current_header!=""} { append current_doc "\n" } |
| 79 |
} else { |
| 80 |
if {$current_doc != ""} { |
| 81 |
lappend res $current_header $current_doc |
| 82 |
set current_doc "" |
| 83 |
} |
| 84 |
set subject n/a |
| 85 |
regexp {^ *([[:alnum:]_]*)} $line -> subject |
| 86 |
if {[lsearch $names $subject]>=0} { |
| 87 |
set current_header $subject |
| 88 |
} else { |
| 89 |
set current_header [string trim $line] |
| 90 |
} |
| 91 |
} |
| 92 |
} |
| 93 |
|
| 94 |
if {$current_doc != ""} { |
| 95 |
lappend res $current_header $current_doc |
| 96 |
} |
| 97 |
|
| 98 |
set res |
| 99 |
} |
| 100 |
|
| 101 |
proc get_tokenizer_docs {data} { |
| 102 |
regexp {(xCreate:.*?)[*]/} $data -> docs |
| 103 |
|
| 104 |
set res "<dl>\n" |
| 105 |
foreach line [split [string trim $docs] "\n"] { |
| 106 |
regexp {[*][*](.*)} $line -> line |
| 107 |
if {[regexp {^ ?x.*:} $line]} { |
| 108 |
append res "<dt><b>$line</b></dt><dd><p style=margin-top:0>\n" |
| 109 |
continue |
| 110 |
} |
| 111 |
if {[regexp {FTS5_TOKENIZER} $line]} { |
| 112 |
set line </dl><p> |
| 113 |
} |
| 114 |
if {[regexp {SYNONYM SUPPORT} $line]} { |
| 115 |
set line "<h3>Synonym Support</h3>" |
| 116 |
} |
| 117 |
if {[string trim $line] == ""} { |
| 118 |
append res "<p>\n" |
| 119 |
} else { |
| 120 |
append res "$line\n" |
| 121 |
} |
| 122 |
} |
| 123 |
|
| 124 |
set res |
| 125 |
} |
| 126 |
|
| 127 |
proc get_api_docs {data} { |
| 128 |
# Initialize global array M as a map from Fts5StructureApi member name |
| 129 |
# to member definition. i.e. |
| 130 |
# |
| 131 |
# iVersion -> {int iVersion} |
| 132 |
# xUserData -> {void *(*xUserData)(Fts5Context*)} |
| 133 |
# ... |
| 134 |
# |
| 135 |
array set M [get_struct_members $data] |
| 136 |
|
| 137 |
# Initialize global list D as a map from section name to documentation |
| 138 |
# text. Most (all?) section names are structure member names. |
| 139 |
# |
| 140 |
set D [get_struct_docs $data [array names M]] |
| 141 |
|
| 142 |
output "<dl>" |
| 143 |
foreach {sub docs} $D { |
| 144 |
if {[info exists M($sub)]} { |
| 145 |
set hdr $M($sub) |
| 146 |
set link " id=$sub" |
| 147 |
} else { |
| 148 |
set link "" |
| 149 |
} |
| 150 |
|
| 151 |
#output "<hr color=#eeeee style=\"margin:1em 8.4ex 0 8.4ex;\"$link>" |
| 152 |
#set style "padding-left:6ex;font-size:1.4em;display:block" |
| 153 |
#output "<h style=\"$style\"><pre>$hdr</pre></h>" |
| 154 |
|
| 155 |
regsub -line {^ *[)]} $hdr ")" hdr |
| 156 |
output "<dt style=\"white-space:pre;font-family:monospace;font-size:120%\"" |
| 157 |
output "$link>" |
| 158 |
output "<b>$hdr</b></dt><dd>" |
| 159 |
|
| 160 |
set mode "" |
| 161 |
set margin " style=margin-top:0.1em" |
| 162 |
foreach line [split [string trim $docs] "\n"] { |
| 163 |
if {[string trim $line]==""} { |
| 164 |
if {$mode != ""} {output "</$mode>"} |
| 165 |
set mode "" |
| 166 |
} elseif {$mode == ""} { |
| 167 |
if {[regexp {^ } $line]} { |
| 168 |
set mode codeblock |
| 169 |
} else { |
| 170 |
set mode p |
| 171 |
} |
| 172 |
output "<$mode$margin>" |
| 173 |
set margin "" |
| 174 |
} |
| 175 |
output $line |
| 176 |
} |
| 177 |
if {$mode != ""} {output "</$mode>"} |
| 178 |
output "</dd>" |
| 179 |
} |
| 180 |
output "</dl>" |
| 181 |
} |
| 182 |
|
| 183 |
proc get_fts5_struct {data start end} { |
| 184 |
set res "" |
| 185 |
set bOut 0 |
| 186 |
foreach line [split $data "\n"] { |
| 187 |
if {$bOut==0} { |
| 188 |
if {[regexp $start $line]} { |
| 189 |
set bOut 1 |
| 190 |
} |
| 191 |
} |
| 192 |
|
| 193 |
if {$bOut} { |
| 194 |
append res "$line\n" |
| 195 |
} |
| 196 |
|
| 197 |
if {$bOut} { |
| 198 |
if {[regexp $end $line]} { |
| 199 |
set bOut 0 |
| 200 |
} |
| 201 |
} |
| 202 |
} |
| 203 |
|
| 204 |
set map [list /* <i>/* */ */</i>] |
| 205 |
string map $map $res |
| 206 |
} |
| 207 |
|
| 208 |
proc main {data} { |
| 209 |
switch $::extract_api_docs_mode { |
| 210 |
fts5_api { |
| 211 |
output [get_fts5_struct $data "typedef struct fts5_api" "^\};"] |
| 212 |
} |
| 213 |
|
| 214 |
fts5_tokenizer { |
| 215 |
output [get_fts5_struct $data "typedef struct Fts5Tokenizer" "^\};"] |
| 216 |
output [get_fts5_struct $data \ |
| 217 |
"Flags that may be passed as the third argument to xTokenize()" \ |
| 218 |
"#define FTS5_TOKEN_COLOCATED" |
| 219 |
] |
| 220 |
} |
| 221 |
|
| 222 |
fts5_extension { |
| 223 |
output [get_fts5_struct $data "typedef.*Fts5ExtensionApi" "^.;"] |
| 224 |
} |
| 225 |
|
| 226 |
Fts5ExtensionApi { |
| 227 |
set struct [get_fts5_struct $data "^struct Fts5ExtensionApi" "^.;"] |
| 228 |
set map [list] |
| 229 |
set lKey [list] |
| 230 |
foreach {k v} [get_struct_members $data] { |
| 231 |
if {[string match x* $k]==0} continue |
| 232 |
lappend lKey $k |
| 233 |
} |
| 234 |
foreach k [lsort -decr $lKey] { lappend map $k "<a href=#$k>$k</a>" } |
| 235 |
output [string map $map $struct] |
| 236 |
} |
| 237 |
|
| 238 |
api { |
| 239 |
get_api_docs $data |
| 240 |
} |
| 241 |
|
| 242 |
tokenizer_api { |
| 243 |
output [get_tokenizer_docs $data] |
| 244 |
} |
| 245 |
|
| 246 |
default { |
| 247 |
} |
| 248 |
} |
| 249 |
} |
| 250 |
main $data |
| 251 |
|
| 252 |
set ::fts5_docs_output |
| 253 |
|
| 254 |
|
| 255 |
|
| 256 |
|
| 257 |
|