Debian Codegraph @

ext/fts5/extract_api_docs.tcl

raw
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