| 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]))]))))) |