guile/modules/system/documentation/output.scm

   1 ;;; output.scm  --  Output documentation "snarffed" from C files in Texi/GDF.
   2 ;;;
   3 ;;; Copyright 2006, 2007, 2010 Free Software Foundation, Inc.
   4 ;;;
   5 ;;;
   6 ;;; This program is free software; you can redistribute it and/or modify
   7 ;;; it under the terms of the GNU General Public License as published by
   8 ;;; the Free Software Foundation; either version 3 of the License, or
   9 ;;; (at your option) any later version.
  10 ;;;
  11 ;;; This program is distributed in the hope that it will be useful,
  12 ;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 ;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 ;;; GNU General Public License for more details.
  15 ;;;
  16 ;;; You should have received a copy of the GNU General Public License
  17 ;;; along with this program; if not, write to the Free Software
  18 ;;; Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA
  19
  20 (define-module (system documentation output)
  21   :use-module (srfi srfi-1)
  22   :use-module (srfi srfi-13)
  23   :use-module (srfi srfi-39)
  24   :autoload   (system documentation c-snarf) (run-cpp-and-extract-snarfing)
  25
  26   :export (schemify-name scheme-procedure-texi-line
  27            procedure-gdf-string procedure-texi-documentation
  28            output-procedure-texi-documentation-from-c-file
  29            *document-c-functions?*))
  30
  31 ;;; Author:  Ludovic Courtès
  32 ;;;
  33 ;;; Commentary:
  34 ;;;
  35 ;;; This module provides support function to issue Texinfo or GDF (Guile
  36 ;;; Documentation Format) documentation from "snarffed" C files.
  37 ;;;
  38 ;;; Code:
  39
  40 \f
  41 ;;;
  42 ;;; Utility.
  43 ;;;
  44
  45 (define (schemify-name str)
  46   "Turn @var{str}, a C variable or function name, into a more ``Schemey''
  47 form, e.g., one with dashed instead of underscores, etc."
  48   (string-map (lambda (chr)
  49                 (if (eq? chr #\_)
  50                     #\-
  51                     chr))
  52               (if (string-suffix? "_p" str)
  53                   (string-append (substring str 0
  54                                             (- (string-length str) 2))
  55                                  "?")
  56                   str)))
  57
  58 \f
  59 ;;;
  60 ;;; Issuing Texinfo and GDF-formatted doc (i.e., `guile-procedures.texi').
  61 ;;; GDF = Guile Documentation Format
  62 ;;;
  63
  64 (define *document-c-functions?*
  65   ;; Whether to mention C function names along with Scheme procedure names.
  66   (make-parameter #t))
  67
  68 (define (scheme-procedure-texi-line proc-name args
  69                                     required-args optional-args
  70                                     rest-arg?)
  71   "Return a Texinfo string describing the Scheme procedure named
  72 @var{proc-name}, whose arguments are listed in @var{args} (a list of strings)
  73 and whose signature is defined by @var{required-args}, @var{optional-args}
  74 and @var{rest-arg?}."
  75   (string-append "@deffn {Scheme Procedure} " proc-name " "
  76                  (string-join (take args required-args) " ")
  77                  (string-join (take (drop args required-args)
  78                                     (+ optional-args
  79                                        (if rest-arg? 1 0)))
  80                               " [" 'prefix)
  81                  (if rest-arg? "...]" "")
  82                  (make-string optional-args #\])))
  83
  84 (define (procedure-gdf-string proc-doc)
  85   "Issue a Texinfo/GDF docstring corresponding to @var{proc-doc}, a
  86 documentation alist as returned by @code{parse-snarfed-line}.  To produce
  87 actual GDF-formatted doc, the resulting string must be processed by
  88 @code{makeinfo}."
  89   (let* ((proc-name     (assq-ref proc-doc 'scheme-name))
  90          (args          (assq-ref proc-doc 'arguments))
  91          (signature     (assq-ref proc-doc 'signature))
  92          (required-args (assq-ref signature 'required))
  93          (optional-args (assq-ref signature 'optional))
  94          (rest-arg?     (assq-ref signature 'rest?))
  95          (location      (assq-ref proc-doc 'location))
  96          (file-name     (car location))
  97          (line          (cadr location))
  98          (documentation (assq-ref proc-doc 'documentation)))
  99     (string-append "\f" ;; form feed
 100                    proc-name (string #\newline)
 101                    (format #f "@c snarfed from ~a:~a~%"
 102                            file-name line)
 103
 104                    (scheme-procedure-texi-line proc-name
 105                                                (map schemify-name args)
 106                                                required-args optional-args
 107                                                rest-arg?)
 108
 109                    (string #\newline)
 110                    documentation (string #\newline)
 111                    "@end deffn" (string #\newline))))
 112
 113 (define (procedure-texi-documentation proc-doc)
 114   "Issue a Texinfo docstring corresponding to @var{proc-doc}, a documentation
 115 alist as returned by @var{parse-snarfed-line}.  The resulting Texinfo string
 116 is meant for use in a manual since it also documents the corresponding C
 117 function."
 118   (let* ((proc-name     (assq-ref proc-doc 'scheme-name))
 119          (c-name        (assq-ref proc-doc 'c-name))
 120          (args          (assq-ref proc-doc 'arguments))
 121          (signature     (assq-ref proc-doc 'signature))
 122          (required-args (assq-ref signature 'required))
 123          (optional-args (assq-ref signature 'optional))
 124          (rest-arg?     (assq-ref signature 'rest?))
 125          (location      (assq-ref proc-doc 'location))
 126          (file-name     (car location))
 127          (line          (cadr location))
 128          (documentation (assq-ref proc-doc 'documentation)))
 129   (string-append (string #\newline)
 130                  (format #f "@c snarfed from ~a:~a~%"
 131                          file-name line)
 132
 133                  ;; document the Scheme procedure
 134                  (scheme-procedure-texi-line proc-name
 135                                              (map schemify-name args)
 136                                              required-args optional-args
 137                                              rest-arg?)
 138                  (string #\newline)
 139
 140                  (if (*document-c-functions?*)
 141                      (string-append
 142                       ;; document the C function
 143                       "@deffnx {C Function} " c-name " ("
 144                       (if (null? args)
 145                           "void"
 146                           (string-join (map (lambda (arg)
 147                                               (string-append "SCM " arg))
 148                                             args)
 149                                        ", "))
 150                       ")" (string #\newline))
 151                      "")
 152
 153                  documentation (string #\newline)
 154                  "@end deffn" (string #\newline))))
 155
 156 \f
 157 ;;;
 158 ;;; Very high-level interface.
 159 ;;;
 160
 161 (define (output-procedure-texi-documentation-from-c-file c-file cpp cflags
 162                                                          port)
 163   (for-each (lambda (texi-string)
 164               (display texi-string port))
 165             (map procedure-texi-documentation
 166                  (run-cpp-and-extract-snarfing cpp c-file cflags))))
 167
 168
 169 ;;; output.scm ends here
 170
 171 ;;; Local Variables:
 172 ;;; mode: scheme
 173 ;;; coding: latin-1
 174 ;;; End:
 175
 176 ;;; arch-tag: 20ca493a-6f1a-4d7f-9d24-ccce0d32df49