Debian Codegraph @

lib/text/info.scm

raw
1 ;;;
2 ;;; info.scm - parse info file
3 ;;;
4 ;;; Copyright (c) 2000-2024 Shiro Kawai <[email protected]>
5 ;;;
6 ;;; Redistribution and use in source and binary forms, with or without
7 ;;; modification, are permitted provided that the following conditions
8 ;;; are met:
9 ;;;
10 ;;; 1. Redistributions of source code must retain the above copyright
11 ;;; notice, this list of conditions and the following disclaimer.
12 ;;;
13 ;;; 2. Redistributions in binary form must reproduce the above copyright
14 ;;; notice, this list of conditions and the following disclaimer in the
15 ;;; documentation and/or other materials provided with the distribution.
16 ;;;
17 ;;; 3. Neither the name of the authors nor the names of its contributors
18 ;;; may be used to endorse or promote products derived from this
19 ;;; software without specific prior written permission.
20 ;;;
21 ;;; THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22 ;;; "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23 ;;; LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
24 ;;; A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
25 ;;; OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
26 ;;; SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
27 ;;; TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
28 ;;; PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
29 ;;; LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
30 ;;; NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
31 ;;; SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32 ;;;
33
34 (define-module text.info
35 (use srfi.13)
36 (use scheme.charset)
37 (use text.parse)
38 (use gauche.process)
39 (use file.util)
40 (use util.match)
41 (cond-expand
42 [gauche.sys.zlib
43 (use rfc.zlib)]
44 [else])
45 (export <info-document> <info-node>
46 open-info-document info-get-node info-parse-menu
47 info-index-add! info-index-ref info-index-keys info-index->alist
48 info-extract-definition
49 )
50 )
51 (select-module text.info)
52
53 ;; NB: node-table maps node name (string) => <info-node> or
54 ;; subinfo-file (string).
55 (define-class <info-document> ()
56 ((path :init-keyword :path
57 :immutable #t)
58 (directory :init-keyword :directory
59 :immutable #t)
60 (node-table :init-form (make-hash-table 'string=?)
61 :immutable #t)
62 (index :init-form (make-hash-table 'string=?)
63 :immutable #t)
64 ))
65
66 (define-class <info-node> ()
67 ((name :init-keyword :name :immutable #t)
68 (next :init-keyword :next :init-value #f :immutable #t)
69 (prev :init-keyword :prev :init-value #f :immutable #t)
70 (up :init-keyowrd :up :init-value #f :immutable #t)
71 (file :init-keyword :file :immutable #t)
72 (content :init-keyword :content :immutable #t)
73 ))
74
75 ;; Find bzip2 location
76 (define bzip2 (find-file-in-paths "bzip2"))
77
78 (cond-expand
79 [gauche.sys.zlib]
80 [else
81 (define gzip (find-file-in-paths "gzip"))])
82
83 ;; Read an info file FILE, and returns a list of strings splitted by ^_ (#\u001f)
84 ;; If FILE is not found, look for compressed one.
85 (define (read-info-file-split file opts)
86 (define (with-input-from-info thunk)
87 (cond [(file-exists? file)
88 (with-input-from-file file thunk)]
89 [(file-exists? #"~|file|.gz")
90 (cond-expand
91 [gauche.sys.zlib
92 (call-with-input-file #"~|file|.gz"
93 (^p (let1 zp (open-inflating-port p :window-bits 31) ;force gzip format
94 (unwind-protect (with-input-from-port zp thunk)
95 (close-input-port zp)))))]
96 [else
97 (with-input-from-process #"~gzip -c -d ~|file|.gz" thunk)])]
98 [(and bzip2 (file-exists? #"~|file|.bz2"))
99 (with-input-from-process #"~bzip2 -c -d ~|file|.bz2" thunk)]
100 [else (error "can't find info file" file)]))
101 (with-input-from-info
102 (^[]
103 (let loop ([c (skip-while (char-set-complement #[\u001f]))]
104 [r '()])
105 (if (eof-object? c)
106 (reverse! r)
107 (let* ([head (next-token #[\u001f\n] '(#[\u001f\n] *eof*))]
108 [body (next-token #[\n] '(#[\u001f] *eof*))])
109 (loop (read-char) (acons head body r)))))))
110 )
111
112 (define (read-master-info-file file opts)
113 (let1 parts (read-info-file-split file opts)
114 (when (null? parts)
115 (error "file is not an info file" file))
116 (rlet1 info (make <info-document> :path file :directory (sys-dirname file))
117 (if (string=? (caar parts) "Indirect:")
118 (let1 indirect-table (parse-indirect-table (cdar parts))
119 (parse-tag-table info indirect-table (cdr (cadr parts))))
120 (parse-nodes info parts)))))
121
122 (define (parse-indirect-table indirects)
123 (with-input-from-string indirects
124 (cut generator-map
125 (^[line] (rxmatch-case line
126 [#/^([^:]+):\s+(\d+)/ (#f file count)
127 (cons (x->integer count) file)]
128 [else '()]))
129 read-line)))
130
131 (define (parse-tag-table info indirect tags)
132 (define (find-file count)
133 (let loop ([indirect indirect]
134 [prev #f])
135 (cond [(null? indirect) prev]
136 [(< count (caar indirect)) prev]
137 [else (loop (cdr indirect) (cdar indirect))])))
138 (with-input-from-string tags
139 (cut generator-for-each
140 (^[line]
141 (rxmatch-case line
142 [#/^Node: ([^\u007f]+)\u007f(\d+)/ (#f node count)
143 (hash-table-put! (~ info 'node-table)
144 node
145 (find-file (x->integer count)))]
146 [else line #f]))
147 read-line)))
148
149 (define (read-sub-info-file info file opts)
150 (let1 parts (read-info-file-split file opts)
151 (when (null? parts)
152 (error "file is not an info file" file))
153 (parse-nodes info parts)))
154
155 (define (parse-nodes info parts)
156 (dolist [p parts]
157 (unless (string=? (car p) "Tag Table:")
158 (parse-node info p))))
159
160 (define (parse-node info part)
161 (rxmatch-case (car part)
162 [#/File: [^,]+, Node: ([^,]+)(, Next: ([^,]+))?, Prev: ([^,]+), Up: ([^,]+)/
163 (#f node #f next prev up)
164 (rlet1 info-node (make <info-node>
165 :name node :next next :prev prev :up up :file info
166 :content (cdr part))
167 (hash-table-put! (~ info 'node-table) node info-node))]
168 [else #f]))
169
170 ;; API
171 ;; Returns <info-document>
172 (define (open-info-document file)
173 (read-master-info-file file '()))
174
175 ;; API
176 ;; Returns <info-node>
177 (define-method info-get-node ((info <info-document>) nodename)
178 (if-let1 node (hash-table-get (~ info 'node-table) nodename #f)
179 (cond [(is-a? node <info-node>) node]
180 [else
181 ;; The entry is in subfile yet to be read. NODE has the
182 ;; subfile name.
183 (read-sub-info-file info
184 (build-path (~ info 'directory) node)
185 '())
186 ;; Now the hashtable should contain real node.
187 (hash-table-get (~ info 'node-table) nodename #f)])
188 #f))
189
190 ;; API
191 ;; Search menu in the given node, and returns list of menu entries.
192 ;; Menu entry:
193 ;; (<entry-name> <node-name> [<line-number>])
194 ;; Where <entry-name> is either a node name, function or macro name,
195 ;; module name,
196 (define-method info-parse-menu ((info <info-node>))
197 (with-input-from-string (~ info 'content)
198 (^[]
199 (define (skip line)
200 (cond [(eof-object? line) '()]
201 [(string=? line "* Menu:") (menu (read-line) '())]
202 [else (skip (read-line))]))
203 (define (menu line r)
204 (rxmatch-case line
205 [test eof-object? (reverse! r)]
206 [#/^\* (.+)::/ (#f node)
207 (menu (read-line) `((,node ,node) ,@r))]
208 [#/^\* (.+):\s+(.+)\.(?:\s*\(line\s+(\d+)\))?/ (#f index node line)
209 (if line
210 (menu (read-line) `((,index ,node ,(x->integer line)) ,@r))
211 ;; The '(line \d+)' may be in the next line.
212 (let1 line2 (read-line)
213 (if-let1 m (and (string? line2)
214 (#/^\s+\(line\s+(\d+)\)/ line2))
215 (menu (read-line) `((,index ,node ,(x->integer (m 1))) ,@r))
216 (menu line2 `((,index ,node) ,@r)))))]
217 [else (menu (read-line) r)]))
218 (skip (read-line)))))
219
220 ;; API
221 ;; Read the named node and adds its menu into the index table.
222 ;; It is particularly useful to give the index page of the info doc,
223 ;; so that you'll be able to lookup particular term (e.g. function name)
224 ;; quickly.
225 ;; KEY-MODIFIER is a procedure applied to the entry-name to obtain a key
226 ;; in the index table. Sometimes the index uses different entry name
227 ;; from the actual name; e.g. Gauche's class index lists class names without
228 ;; surrounding '<' and '>', since using the actual name makes all class names
229 ;; being listed below '<' subheading, which isn't very useful.
230 ;; You can pass (^e #"<~|e|>") as key-modifier to recover the actual
231 ;; class name to be used as the key.
232 ;; If there are more than one entries per key, both are saved in the
233 ;; index table. See info-lookup-index below.
234 (define (info-index-add! info-doc index-node-name
235 :optional (key-modifier identity))
236 ;; When there are more than one entry with the same name, texinfo appends
237 ;; " <n>" in the index entry. We want to strip it.
238 (define (entry-name e)
239 (if-let1 m (#/ <\d+>$/ e) (rxmatch-before m) e))
240
241 (if-let1 n (info-get-node info-doc index-node-name)
242 (dolist [p (info-parse-menu n)]
243 (let ([key (key-modifier (entry-name (car p)))]
244 [node&line (cdr p)])
245 ;; Sometimes variations of the API of a function is listed using
246 ;; @defunx. Then we'll have multiple (node line) for the same key.
247 ;; We only need the first one, so we check if we already have the
248 ;; same node.
249 ($ hash-table-update! (~ info-doc'index) key
250 (^[lis] (if (find (^e (equal? (car node&line) (car e))) lis)
251 lis
252 (cons node&line lis)))
253 '())))
254 (error "No such info node:" index-node-name)))
255
256 ;; API
257 ;; Lookup index with the given key. Returns a list of
258 ;; (<node-name> <line-number>).
259 (define (info-index-ref info-doc key)
260 ;; This reverses the order of node&line list, but they're pushed
261 ;; in the reverse order so we'll get eariler entry first.
262 (fold (^[e r]
263 (match e
264 [(node-name line-number) (cons e r)]
265 [(node-name) (cons `(,node-name 1) r)]
266 [_ r]))
267 '()
268 (hash-table-get (~ info-doc'index) key '())))
269
270 ;; API
271 ;; Retuns a list of keys in the index.
272 (define (info-index-keys info-doc)
273 (hash-table-keys (~ info-doc'index)))
274
275 ;; API
276 ;; Raturns ((key (node line) ...) ...)
277 (define (info-index->alist info-doc)
278 (hash-table->alist (~ info-doc'index)))
279
280 ;; API
281 ;; Extract one definition from the node's content. Assumes the definition
282 ;; begins from the specified line; then we go forward to find the end of
283 ;; the definition. The end of definition is when we see the end of content,
284 ;; or we see a line begins with less than or equal to 3 whitespaces.
285 ;; (Except the 'defunx'-type multi entry)
286 (define (info-extract-definition info-node start-line)
287
288 ;; Skip the lines before the entry.
289 ;; START-LINE counts from the beginning of the info doc; the first 3 lines
290 ;; are taken by the node header and the node's content doesn't include them.
291 ;; Also note that line count starts from 1.
292 ;;
293 ;; Caveat: If the entry header spans multiple lines because of large
294 ;; number of arguments, the texinfo menu's line number somehow points to the
295 ;; last line of the entry header. For example, the entry of http-get
296 ;; begins with this:
297 ;;
298 ;; -- Function: http-get server request-uri :key sink flusher
299 ;; redirect-handler secure ...
300 ;;
301 ;; And the texinfo menu's line points to "redirect-handler secure ..." line
302 ;; instead of "-- Function: http-get" line. So we have to check the lines
303 ;; to find out the last #/^ --/ line before START-LINE.
304 (define (entry-line? line)
305 (or (#/^ --/ line) ; start of entry line
306 (#/^ {10}/ line) ; folded entry line
307 (#/^ {5}\.\.\.$/ line) ; dots between entry line
308 (#/^ {5}\u2026$/ line))) ; dots between entry line (unicode)
309 (define (skip-lines)
310 (let loop ([n (- start-line 3)]
311 [lines '()])
312 (if (<= n 0)
313 (let1 line (read-line)
314 (for-each print (reverse lines))
315 line)
316 (let1 line (read-line)
317 (cond [(eof-object? line) line] ; something's wrong, but tolerate.
318 [(entry-line? line) (loop (- n 1) (cons line lines))]
319 [else (loop (- n 1) '())])))))
320
321 ;; Once the start line is found, we find the start of description (since
322 ;; the entry may have multiple entry line, e.g. @defunx.) then scan the
323 ;; description until we get an emtpy line.
324 (with-string-io (~ info-node'content)
325 (^[]
326 (let entry ([line (skip-lines)])
327 (cond [(eof-object? line)]
328 [(entry-line? line) (print line) (entry (read-line))]
329 [(#/^$/ line)] ; no description
330 [(#/^ {5}\S/ line) ; start description
331 (print line)
332 (let desc ([line (read-line)])
333 (cond [(eof-object? line)]
334 [(#/^$/ line) (print) (desc (read-line))]
335 [(#/^ {4}/ line) (print line) (desc (read-line))]
336 [else]))])))))