2 ;;; Copyright (C) 2013 Andy Wingo <wingo@pobox.com>
4 ;;; Figl is free software: you can redistribute it and/or modify it
5 ;;; under the terms of the GNU Lesser General Public License as
6 ;;; published by the Free Software Foundation, either version 3 of the
7 ;;; License, or (at your option) any later version.
9 ;;; Figl is distributed in the hope that it will be useful, but WITHOUT
10 ;;; ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
11 ;;; or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General
12 ;;; Public License for more details.
14 ;;; You should have received a copy of the GNU Lesser General Public
15 ;;; License along with this program. If not, see
16 ;;; <http://www.gnu.org/licenses/>.
20 ;; figl is the Foreign Interface to GL.
24 (define-module (figl parse)
25 #:use-module (figl config)
26 #:use-module (sxml simple)
27 #:use-module ((sxml xpath) #:hide (filter))
28 #:use-module (sxml transform)
29 #:use-module (sxml fold)
30 #:use-module ((srfi srfi-1) #:select (filter fold append-map filter-map))
31 #:use-module (srfi srfi-9)
32 #:use-module (texinfo docbook)
33 #:use-module (ice-9 ftw)
34 #:use-module (ice-9 rdelim)
35 #:use-module (ice-9 match)
36 #:export (gl-definition?
39 gl-definition-prototypes
40 gl-definition-documentation
41 gl-definition-copyright
46 gl-enumeration-category
48 parse-gl-enumerations))
50 (define-record-type gl-definition
51 (make-gl-definition name prototypes documentation copyright)
53 (name gl-definition-name)
54 (prototypes gl-definition-prototypes)
55 (documentation gl-definition-documentation)
56 (copyright gl-definition-copyright))
58 ;; values := (name . number) ...
59 (define-record-type gl-enumeration
60 (make-gl-enumeration category values)
62 (category gl-enumeration-category)
63 (values gl-enumeration-values))
66 '((mml . "http://www.w3.org/1998/Math/MathML")))
69 '(;; From http://www.w3.org/TR/MathML2/mmlextra.html
70 (af . "\u2061") ;; Function application.
71 (it . "\u2062") ;; Invisible times.
72 ;; http://www.w3.org/TR/MathML2/isonum.html
73 (plus . "\u002B") ;; Plus sign.
74 (times . "\u00D7") ;; Multiplication sign.
75 ;; http://www.w3.org/TR/MathML2/isotech.html
76 (Prime . "\u2033") ;; Double prime.
77 (le . "\u2264") ;; Less than or equal to.
78 (ne . "\u2260") ;; Not equal to.
79 (minus . "\u2212") ;; Minus sign.
80 ;; http://www.w3.org/TR/MathML2/isoamsc.html
81 (lceil . "\u2308") ;; Left ceiling.
82 (rceil . "\u2309") ;; Right ceiling.
83 (lfloor . "\u230A") ;; Left floor.
84 (rfloor . "\u230B") ;; Right floor.
85 ;; http://www.w3.org/TR/MathML2/mmlalias.html
86 (DoubleVerticalBar . "\u2225") ;; Parallel to.
87 (LeftFloor . "\u230A") ;; Left floor.
88 (RightFloor . "\u230B") ;; Right floor.
89 (LeftCeiling . "\u2308") ;; Left ceiling.
90 (RightCeiling . "\u2309") ;; Right ceiling.
91 (CenterDot . "\u00B7") ;; Middle dot.
92 (VerticalBar . "\u2223") ;; Divides.
93 (PartialD . "\u2202") ;; Partial derivative.
94 ;; http://www.w3.org/TR/MathML2/mmlextra.html
95 (Hat . "\u005E") ;; Circumflex accent.
96 ;; http://www.w3.org/TR/MathML2/isogrk3.html
97 (Delta . "\u0394") ;; Greek capital letter delta.
98 (Sigma . "\u03A3") ;; Greek capital letter sigma.
103 (define (default-entity-handler port name)
104 (format (current-warning-port)
105 "~a:~a:~a: undefined entitity: &~a;\n"
106 (or (port-filename port) "<unknown file>")
107 (port-line port) (port-column port)
109 (symbol->string name))
112 "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd")
114 (define (docbook-with-mathml-handler docname systemid internal)
115 (unless (equal? systemid dbmathml)
116 (warn "unexpected doctype" docname systemid internal))
117 (values #:entities *entities* #:namespaces *namespaces*))
119 (define (trim-whitespace-left str)
120 (let ((first (and (not (string-null? str))
121 (string-ref str 0))))
122 (if (and first (char-whitespace? first))
123 (string-append (string first) (string-trim str char-whitespace?))
126 (define (trim-whitespace-right str)
127 (let ((last (and (not (string-null? str))
128 (string-ref str (1- (string-length str))))))
129 (if (and last (char-whitespace? last))
130 (string-append (string-trim-right str char-whitespace?) (string last))
133 (define (trim-whitespace str)
134 (trim-whitespace-left
135 (trim-whitespace-right str)))
137 (define (zap-whitespace sxml)
138 (define (not-whitespace x)
139 (or (not (string? x))
140 (not (string-every char-whitespace? x))))
142 `((*default* . ,(lambda (tag . body)
144 (filter not-whitespace body))))
145 (*text* . ,(lambda (tag text)
147 (trim-whitespace text)
150 (define (parse-man-xml version filename)
151 (define subdir (format #f "man~A" version))
152 (call-with-input-file (in-vicinity (upstream-doc)
153 (in-vicinity subdir filename))
156 (xml->sxml port #:declare-namespaces? #t
157 #:default-entity-handler default-entity-handler
158 #:doctype-handler docbook-with-mathml-handler)))))
160 (define (xml-files version)
161 (define subdir (format #f "man~A" version))
162 (scandir (in-vicinity (upstream-doc) subdir)
163 (lambda (x) (string-suffix? ".xml" x))))
165 (define (take-first proc)
167 (let ((res (proc xml)))
168 (and (pair? res) (car res)))))
171 (take-first (sxpath '(refentry refnamediv refname *text*))))
174 (take-first (sxpath '(refentry refnamediv refpurpose *text*))))
176 (define xml-funcprototypes
177 (sxpath '(refentry refsynopsisdiv funcsynopsis funcprototype)))
179 (define xml-parameters
180 (take-first (sxpath '(refentry (refsect1 (@ id (equal? "parameters")))))))
182 (define xml-description
183 (take-first (sxpath '(refentry (refsect1 (@ id (equal? "description")))))))
186 (take-first (sxpath '(refentry (refsect1 (@ id (equal? "errors")))))))
188 (define xml-copyright
189 (take-first (sxpath '(refentry (refsect1 (@ id (equal? "Copyright")))))))
191 (define (string->gl-type str)
193 (string-join (string-split (string-trim-both str) #\space) "-")))
195 (define (parse-prototypes sxml)
198 ((('funcprototype ('funcdef return-type ('function names))
203 (define (redundant-variant? s shun-suffix prefer-suffix)
204 (and (string-suffix? shun-suffix s)
205 (member (string-append (substring s 0 (- (string-length s)
206 (string-length shun-suffix)))
212 ;; Skip double variants if we have a float variant.
213 ;; (http://www.opengl.org/wiki/Common_Mistakes#GL_DOUBLE).
214 (redundant-variant? s "d" "f")
216 ;; Skip byte variants if there is a short variant.
217 (redundant-variant? s "b" "s")
219 ;; Skip short variants if there is an int variant.
220 (redundant-variant? s "s" "i")
222 ;; Skip packed setters like glVertex3fv if e.g. glVertex3f exists.
223 (redundant-variant? s "v" "")
224 (redundant-variant? s "dv" "fv")
225 (redundant-variant? s "bv" "sv")
226 (redundant-variant? s "sv" "iv")))
231 (('funcprototype ('funcdef return-type ('function (? skip?)))
234 (('funcprototype ('funcdef return-type ('function name))
235 ('paramdef ('parameter "void")))
236 `(,(string->symbol name)
237 -> ,(string->gl-type return-type)))
238 (('funcprototype ('funcdef return-type ('function name))
239 ('paramdef ptype ('parameter pname))
241 `(,(string->symbol name)
242 ,@(map (lambda (pname ptype)
243 (list (string->symbol pname)
244 (string->gl-type ptype)))
246 -> ,(string->gl-type return-type)))))
249 (define (collapse-fragments nodeset)
251 ((('*fragment* elts ...) nodes ...)
252 (append (collapse-fragments elts)
253 (collapse-fragments nodes)))
254 ((((and tag (? symbol?)) elts ...) nodes ...)
255 (acons tag (collapse-fragments elts) (collapse-fragments nodes)))
257 (cons elt (collapse-fragments nodes)))
260 (define (list-intersperse src-l elem)
261 (if (null? src-l) src-l
262 (let loop ((l (cdr src-l)) (dest (cons (car src-l) '())))
263 (if (null? l) (reverse dest)
264 (loop (cdr l) (cons (car l) (cons elem dest)))))))
266 (define (lift-tables sdocbook)
267 ;; Like sdocbook-flatten, but tweaked to lift tables from inside
268 ;; paras, but not paras from inside tables. Pretty hacky stuff.
269 (define *sdocbook-block-commands*
270 '(informaltable programlisting variablelist))
272 (define (inline-command? command)
273 (not (memq command *sdocbook-block-commands*)))
275 (define (fhere str accum block cont)
276 (values (cons str accum)
279 (define (fdown node accum block cont)
281 ((command (and attrs ('% . _)) body ...)
283 (lambda (accum block)
285 `(,command ,attrs ,@(reverse accum))
289 (lambda (accum block)
291 `(,command ,@(reverse accum))
293 (define (fup node paccum pblock pcont kaccum kblock kcont)
294 (call-with-values (lambda () (kcont kaccum kblock))
296 (if (inline-command? (car ret))
297 (values (cons ret paccum) (append kblock pblock) pcont)
298 (values paccum (append kblock (cons ret pblock)) pcont)))))
300 (lambda () (foldts*-values fdown fup fhere sdocbook '() '() #f))
301 (lambda (accum block cont)
302 (append (reverse accum)
309 . ,(lambda (tag id . body)
310 (append-map (lambda (nodeset)
313 (pre-post-order x *rules*))
317 ((('title _) body ...) body)
321 . ,(lambda (tag term . body)
322 `(entry (% (heading ,@(cdar term))) ,@(apply append body))))
324 . ,(lambda (tag . body)
331 . ,(lambda (tag . rest)
333 . ,(lambda (tag . body)
334 `(table (% (formatter (asis))) ,@body)))
337 ((_ ('@ ('class "copyright"))) '(copyright))))
339 . ,(lambda (tag body)
342 . ,(lambda (tag body)
345 . ,(lambda (tag . body)
348 . ,(lambda (tag . body)
351 . ,(lambda (tag body . ignored)
352 (or (null? ignored) (warn "ignored function tail" ignored))
357 ((_ ('@ ('role "bold")) (and body (? string?)))
358 `(strong ,(string-trim-both body)))
359 ((_ ('@ ('role "bold")) . body) `(strong ,@body))
360 ((_ body) `(var ,body))))
362 . ,(lambda (tag contents)
365 . ,(lambda (tag contents)
368 . ,(lambda (tag contents)
371 . ,(lambda (tag contents)
374 . ,(lambda (tag attrs tgroup)
378 . ,(lambda (tag . rows)
384 . ,(lambda (tag . rows)
387 . ,(lambda (tag first . rest)
388 `(entry (% (heading ,@first))
391 (list-intersperse rest '(", ")))))))
396 ((_ ('@ . _) x ...) x)
398 . ,(lambda (tag attrs . contents)
399 `(table (% (formatter (asis)))
400 ,@(apply append (filter identity contents)))))
402 ;; Poor man's mathml.
404 . ,(lambda (tag . contents)
405 `(r . ,(collapse-fragments contents))))
407 . ,(lambda (tag n . rest)
409 `(*fragment* ,n . ,rest)
415 ((tag attrs contents)
417 (('@ (mathvariant "italic"))
419 (_ `(code ,contents))))))
420 ;; It would be possible to represent a matrix as a @multitable, but
421 ;; Guile doesn't really have support for that. So instead print
422 ;; each row in parentheses.
425 . ,(lambda (tag . body)
426 `("(" ,@(list-intersperse body " ") ")")))
429 ((tag ('@ . _) body ...)
430 `(*fragment* ,@body))
432 `(*fragment* ,@body)))))
433 . ,(lambda (tag . rows)
434 ;; Rely on outer mfence for outer parens, if any
435 (let ((rows (if (and (pair? rows) (eq? (caar rows) '@))
438 `(*fragment* ,@(apply append (list-intersperse rows '(", ")))))))
443 . ,(lambda (tag base exponent)
444 `(*fragment* ,base "^" ,exponent)))
446 . ,(lambda (tag base exponent)
447 `(*fragment* ,base "_" ,exponent)))
449 . ,(lambda (tag base over)
450 `(*fragment* ,base ,over)))
452 . ,(lambda (tag under base over)
453 `(*fragment* ,under ,base ,over)))
455 . ,(lambda (tag num denom)
456 `(*fragment* ,num "/" ,denom)))
458 . ,(lambda (tag base)
459 `(*fragment* "√" ,base)))
464 . ,(lambda (tag operator)
467 . ,(lambda (tag . contents)
468 `(*fragment* . ,contents)))
470 . ,(lambda (tag attrs left . right)
471 `(*fragment* ,@(assq-ref attrs 'open)
475 ,@(assq-ref attrs 'close))))
477 . ,(lambda (tag text)
479 ,@*sdocbook->stexi-rules*))
481 (define (sdocbook->stexi sdocbook)
482 (pre-post-order sdocbook *rules*))
484 ;; Produces an stexinfo fragment.
485 (define (generate-documentation purpose parameters description errors)
487 (para ,(string-append (string (char-upcase (string-ref purpose 0)))
488 (substring purpose 1)
490 ,@(if parameters (sdocbook->stexi parameters) '())
491 ,@(if description (sdocbook->stexi description) '())
492 ,@(if errors (sdocbook->stexi errors) '())))
494 (define (xml->definition xml)
495 (let ((prototypes (parse-prototypes (xml-funcprototypes xml))))
496 (and (pair? prototypes)
497 (make-gl-definition (xml-name xml)
499 (generate-documentation (xml-purpose xml)
501 (xml-description xml)
503 (and=> (xml-copyright xml)
505 `(*fragment* ,@(sdocbook->stexi c))))))))
507 (define (parse-gl-definitions version)
508 (filter-map (lambda (file)
509 (xml->definition (parse-man-xml version file)))
510 (xml-files version)))
512 (define (trim-comment line)
514 ((string-index line #\#)
515 => (lambda (idx) (substring line 0 idx)))
518 (define (expand-camel-case s)
519 (define (add-humps humps out more?)
525 (cons* head #\- out)))
527 (let ((out (if (null? out)
529 (append tail (cons #\- out)))))
533 (let lp ((in (string->list s)) (humps '()) (out '()))
536 (list->string (reverse (add-humps humps out #f))))
538 (if (and (char-lower-case? c)
539 ;; Try to keep subtokens like 12x3 in one piece.
541 (not (and-map char-numeric? humps))))
542 (lp in '() (cons c (add-humps humps out #t)))
543 (lp in (cons (char-downcase c) humps) out))))))
545 (define (mangle-name name)
547 (string-join (map expand-camel-case (string-split name #\_))
550 (define (parse-number num)
552 ((equal? "0xFFFFFFFFu" num)
554 ((equal? "0xFFFFFFFFFFFFFFFFull" num)
556 ((string-prefix? "0x" num)
557 (string->number (substring num 2) 16))
558 ((string-prefix? "GL_" num)
559 (cons #f (mangle-name (substring num 3))))
561 (string->number num))))
563 (define (read-line-and-trim-comment port)
564 (let ((line (read-line port)))
565 (if (eof-object? line)
567 (string-trim-both (trim-comment line)))))
569 (define (resolve-enumerations enums)
570 ;; We shouldn't fail to resolve anything, but there are a couple bugs
571 ;; in enum.spec currently:
572 ;; http://www.khronos.org/bugzilla/show_bug.cgi?id=787. Until they
573 ;; are fixed, allow resolution to fail.
574 (define (resolve-value category name value)
579 ((#f . (and name (? symbol?)))
580 (resolve-value category name category))
582 (resolve-value value name (assq-ref (assq-ref enums value) name)))))
583 (let lp ((in enums) (out '()))
587 (((category (name . value) ...) . in)
589 (cons (make-gl-enumeration
593 (and=> (resolve-value category name value)
599 (define (merge-alists in)
601 (define (collect-values key values in)
602 (let lp ((in in) (values values))
606 (if (eq? (caar in) key)
607 (append values (cdar in))
609 (let lp ((in in) (out '()))
611 ((null? in) (reverse out))
612 ((assq (caar in) out) (lp (cdr in) out))
615 (collect-values (caar in) (cdar in) (cdr in))
618 (define (parse-enumerations-from-port port)
619 (define (finish-block headers enums accum)
622 (fold (lambda (header accum)
623 (acons header (reverse enums) accum))
626 (let lp ((current-headers '()) (current-enums '()) (accum '()))
627 (let ((line (read-line-and-trim-comment port)))
630 (resolve-enumerations
632 (reverse (finish-block current-headers current-enums accum)))))
633 ((string-index line #\:)
635 (let* ((ws (or (string-index-right line char-whitespace? 0 pos) 0))
636 (headers (map string-trim-both
637 (string-split (substring line 0 ws) #\,)))
638 (def (substring line (1+ ws) pos)))
639 (match (cons def headers)
640 (("define" headers ...)
643 (finish-block current-headers current-enums accum)))
644 (("enum" headers ...)
645 (if (null? current-enums)
646 (lp (append current-headers (map mangle-name headers))
649 (lp (map mangle-name headers)
651 (finish-block current-headers current-enums accum))))
652 (x (error "qux." x))))))
654 (lp current-headers current-enums accum))
656 (match (filter (compose not string-null?)
657 (string-split (trim-comment line) char-whitespace?))
660 (acons (mangle-name enum)
661 (or (parse-number value)
662 (error "failed to parse" value))
667 (acons (mangle-name enum)
673 (define (parse-gl-enumerations spec)
674 (call-with-input-file (in-vicinity (upstream-doc)
675 (in-vicinity "spec" spec))
676 parse-enumerations-from-port))