4 # The author disclaims copyright to this source code. In place of
5 # a legal notice, here is a blessing:
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.
11 #--------------------------------------------------------------------------
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.
18 set ::fts5_docs_output ""
19 if {[info commands hd_putsnl
]==""} {
20 if {[llength $argv]>0} { set ::extract_api_docs_mode [lindex $argv 0] }
26 append ::fts5_docs_output "$text\n"
29 if {[info exists
::extract_api_docs_mode]==0} {set ::extract_api_docs_mode api
}
32 set input_file
[file join [file dir
[info script
]] fts5.h
]
33 set fd
[open $input_file]
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.
42 # iVersion {int iVersion} xUserData {void *(*xUserData)(Fts5Context*)} ...
44 proc get_struct_members
{data
} {
46 # Extract the structure definition from the fts5.h file.
47 regexp "struct Fts5ExtensionApi {(.*?)};" $data -> defn
49 # Remove all comments from the structure definition
50 regsub -all {/[*].
*?
[*]/} $defn {} defn2
53 foreach member
[split $defn2 {;}] {
55 set member
[string trim
$member]
57 catch { set name
[lindex $member end
] }
58 regexp {.
*?
[(][*]([^
)]*)[)]} $member -> name
59 lappend res
$name $member
66 proc get_struct_docs
{data names
} {
67 # Extract the structure definition from the fts5.h file.
68 regexp {EXTENSION API FUNCTIONS
(.
*?
)[*]/} $data -> docs
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" }
80 if {$current_doc != ""} {
81 lappend res
$current_header $current_doc
85 regexp {^
*([[:alpha
:]]*)} $line -> subject
86 if {[lsearch $names $subject]>=0} {
87 set current_header
$subject
89 set current_header
[string trim
$line]
94 if {$current_doc != ""} {
95 lappend res
$current_header $current_doc
101 proc get_tokenizer_docs
{data
} {
102 regexp {(xCreate
:.
*?
)[*]/} $data -> docs
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"
111 if {[regexp {SYNONYM SUPPORT
} $line]} {
112 set line
"</dl><h3>Synonym Support</h3>"
114 if {[string trim
$line] == ""} {
124 proc get_api_docs
{data
} {
125 # Initialize global array M as a map from Fts5StructureApi member name
126 # to member definition. i.e.
128 # iVersion -> {int iVersion}
129 # xUserData -> {void *(*xUserData)(Fts5Context*)}
132 array set M
[get_struct_members
$data]
134 # Initialize global list D as a map from section name to documentation
135 # text. Most (all?) section names are structure member names.
137 set D
[get_struct_docs
$data [array names M
]]
140 foreach {sub docs
} $D {
141 if {[info exists M
($sub)]} {
148 #output "<hr color=#eeeee style=\"margin:1em 8.4ex 0 8.4ex;\"$link>"
149 #set style "padding-left:6ex;font-size:1.4em;display:block"
150 #output "<h style=\"$style\"><pre>$hdr</pre></h>"
152 regsub -line {^
*[)]} $hdr ")" hdr
153 output
"<dt style=\"white-space:pre;font-family:monospace;font-size:120%\""
155 output
"<b>$hdr</b></dt><dd>"
158 set margin
" style=margin-top:0.1em"
159 foreach line
[split [string trim
$docs] "\n"] {
160 if {[string trim
$line]==""} {
161 if {$mode != ""} {output
"</$mode>"}
163 } elseif
{$mode == ""} {
164 if {[regexp {^
} $line]} {
169 output
"<$mode$margin>"
174 if {$mode != ""} {output
"</$mode>"}
180 proc get_fts5_struct
{data start end
} {
183 foreach line
[split $data "\n"] {
185 if {[regexp $start $line]} {
195 if {[regexp $end $line]} {
201 set map
[list /* <i
>/* */ */</i
>]
206 switch $::extract_api_docs_mode {
208 output
[get_fts5_struct
$data "typedef struct fts5_api" "^\};"]
212 output
[get_fts5_struct
$data "typedef struct Fts5Tokenizer" "^\};"]
213 output
[get_fts5_struct
$data \
214 "Flags that may be passed as the third argument to xTokenize()" \
215 "#define FTS5_TOKEN_COLOCATED"
220 output
[get_fts5_struct
$data "typedef.*Fts5ExtensionApi" "^.;"]
224 set struct
[get_fts5_struct
$data "^struct Fts5ExtensionApi" "^.;"]
226 foreach {k v
} [get_struct_members
$data] {
227 if {[string match x
* $k]==0} continue
228 lappend map
$k "<a href=#$k>$k</a>"
230 output
[string map
$map $struct]
238 output
[get_tokenizer_docs
$data]
247 set ::fts5_docs_output