Debian Codegraph @

guile/modules/system/documentation/c-snarf.scm

raw
1 ;;; c-snarf.scm -- Parsing documentation "snarffed" from C files.
2 ;;;
3 ;;; Copyright 2006-2025 Free Software Foundation, Inc.
4 ;;;
5 ;;; This file is part of Guile-GnuTLS.
6 ;;;
7 ;;; This program is free software: you can redistribute it and/or modify
8 ;;; it under the terms of the GNU General Public License as published by
9 ;;; the Free Software Foundation, either version 3 of the License, or
10 ;;; (at your option) any later version.
11 ;;;
12 ;;; This program is distributed in the hope that it will be useful,
13 ;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
14 ;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 ;;; GNU General Public License for more details.
16 ;;;
17 ;;; You should have received a copy of the GNU General Public License
18 ;;; along with this program. If not, see <https://www.gnu.org/licenses/>.
19
20 (define-module (system documentation c-snarf)
21 :use-module (ice-9 popen)
22 :use-module (ice-9 rdelim)
23
24 :use-module (srfi srfi-13)
25 :use-module (srfi srfi-14)
26 :use-module (srfi srfi-39)
27
28 :export (run-cpp-and-extract-snarfing
29 parse-snarfing
30 parse-snarfed-line))
31
32 ;;; Author: Ludovic Courtès
33 ;;;
34 ;;; Commentary:
35 ;;;
36 ;;; This module provides tools to parse and otherwise manipulate
37 ;;; documentation "snarffed" from C files, i.e., information obtained by
38 ;;; running the C preprocessor with the @code{-DSCM_MAGIC_SNARF_DOCS} flag.
39 ;;;
40 ;;; Code:
41
42
43
44 ;;;
45 ;;; High-level API.
46 ;;;
47
48 (define (run-cpp-and-extract-snarfing file cpp cpp-flags)
49 (let ((pipe (apply open-pipe* OPEN_READ
50 (cons cpp (append cpp-flags (list file))))))
51 (parse-snarfing pipe)))
52
53
54 ;;;
55 ;;; Parsing magic-snarffed CPP output.
56 ;;;
57
58 (define (parse-c-argument-list arg-string)
59 "Parse @var{arg-string} (a string representing a ANSI C argument list,
60 e.g., @var{(const SCM first, SCM second_arg)}) and return a list of strings
61 denoting the argument names."
62 (define %c-symbol-char-set
63 (char-set-adjoin char-set:letter+digit #\_))
64
65 (let loop ((args (string-tokenize (string-trim-both arg-string #\space)
66 %c-symbol-char-set))
67 (type? #t)
68 (result '()))
69 (if (null? args)
70 (reverse! result)
71 (let ((the-arg (car args)))
72 (cond ((and type? (string=? the-arg "const"))
73 (loop (cdr args) type? result))
74 ((and type? (string=? the-arg "SCM"))
75 (loop (cdr args) (not type?) result))
76 (type? ;; any other type, e.g., `void'
77 (loop (cdr args) (not type?) result))
78 (else
79 (loop (cdr args) (not type?) (cons the-arg result))))))))
80
81 (define (parse-documentation-item item)
82 "Parse @var{item} (a string), a single function string produced by the C
83 preprocessor. The result is an alist whose keys represent specific aspects
84 of a procedure's documentation: @code{c-name}, @code{scheme-name},
85 @code{documentation} (a Texinfo documentation string), etc."
86
87 (define (read-strings)
88 ;; Read several subsequent strings and return their concatenation.
89 (let loop ((str (read))
90 (result '()))
91 (if (or (eof-object? str)
92 (not (string? str)))
93 (string-concatenate (reverse! result))
94 (loop (read) (cons str result)))))
95
96 (let* ((item (string-trim-both item #\space))
97 (space (string-index item #\space)))
98 (if (not space)
99 (error "invalid documentation item" item)
100 (let ((kind (substring item 0 space))
101 (rest (substring item space (string-length item))))
102 (cond ((string=? kind "cname")
103 (cons 'c-name (string-trim-both rest #\space)))
104 ((string=? kind "fname")
105 (cons 'scheme-name
106 (with-input-from-string rest read-strings)))
107 ((string=? kind "type")
108 (cons 'type (with-input-from-string rest read)))
109 ((string=? kind "location")
110 (cons 'location
111 (with-input-from-string rest
112 (lambda ()
113 (let loop ((str (read))
114 (result '()))
115 (if (eof-object? str)
116 (reverse! result)
117 (loop (read) (cons str result))))))))
118 ((string=? kind "arglist")
119 (cons 'arguments
120 (parse-c-argument-list rest)))
121 ((string=? kind "argsig")
122 (cons 'signature
123 (with-input-from-string rest
124 (lambda ()
125 (let ((req (read)) (opt (read)) (rst? (read)))
126 (list (cons 'required req)
127 (cons 'optional opt)
128 (cons 'rest? (= 1 rst?))))))))
129 (else
130 ;; docstring (may consist of several C strings which we
131 ;; assume to be equivalent to Scheme strings)
132 (cons 'documentation
133 (with-input-from-string item read-strings))))))))
134
135 (define (parse-snarfed-line line)
136 "Parse @var{line}, a string that contains documentation returned for a
137 single function by the C preprocessor with the @code{-DSCM_MAGIC_SNARF_DOCS}
138 option. @var{line} is assumed to be a complete \"^^ { ... ^^ }\" sequence."
139 (define (caret-split str)
140 (let loop ((str str)
141 (result '()))
142 (if (string=? str "")
143 (reverse! result)
144 (let ((caret (string-index str #\^))
145 (len (string-length str)))
146 (if caret
147 (if (and (> (- len caret) 0)
148 (eq? (string-ref str (+ caret 1)) #\^))
149 (loop (substring str (+ 2 caret) len)
150 (cons (string-take str (- caret 1)) result))
151 (error "single caret not allowed" str))
152 (loop "" (cons str result)))))))
153
154 (let ((items (caret-split (substring line 4
155 (- (string-length line) 4)))))
156 (map parse-documentation-item items)))
157
158
159 (define (parse-snarfing port)
160 "Read C preprocessor (where the @code{SCM_MAGIC_SNARF_DOCS} macro is
161 defined) output from @var{port} a return a list of alist, each of which
162 contains information about a specific function described in the C
163 preprocessor output."
164 (define start-marker "^^ {")
165 (define end-marker "^^ }")
166
167 (define (read-snarf-lines start)
168 ;; Read the snarf lines that follow START until and end marker is found.
169 (let loop ((line start)
170 (result '()))
171 (cond ((eof-object? line)
172 ;; EOF in the middle of a "^^ { ... ^^ }" sequence; shouldn't
173 ;; happen.
174 line)
175 ((string-contains line end-marker)
176 =>
177 (lambda (end)
178 (let ((result (cons (string-take line (+ 3 end))
179 result)))
180 (string-concatenate-reverse result))))
181 ((string-prefix? "#" line)
182 ;; Presumably a "# LINENUM" directive; skip it.
183 (loop (read-line port) result))
184 (else
185 (loop (read-line port)
186 (cons line result))))))
187
188 (let loop ((line (read-line port))
189 (result '()))
190 (cond ((eof-object? line)
191 result)
192 ((string-contains line start-marker)
193 =>
194 (lambda (start)
195 (let ((line
196 (read-snarf-lines (string-drop line start))))
197 (loop (read-line port)
198 (cons (parse-snarfed-line line) result)))))
199 (else
200 (loop (read-line port) result)))))
201
202
203 ;;; c-snarf.scm ends here
204
205 ;;; Local Variables:
206 ;;; mode: scheme
207 ;;; coding: utf-8
208 ;;; End:
209
210 ;;; arch-tag: dcba2446-ee43-46d8-a47e-e6e12f121988