13.33 guile-tools read-scheme-source

Usage: read-scheme-source FILE1 FILE2 ...

This program parses each FILE and writes to stdout sexps that describe the
top-level structures of the file: scheme forms, single-line comments, and
hash-bang comments.  You can further process these (to associate comments
w/ scheme forms as a kind of documentation, for example).

The output sexps have one of these forms:

   (quote (filename FILENAME))

   (quote (comment :line LINUM
                   :leading-semicolons N
                   :text LINE))

   (quote (whitespace :line LINUM
                      :text LINE))

   (quote (hash-bang-comment :line LINUM
                             :line-count N
                             :text-list (LINE1 LINE2 ...)))

   (quote (following-form-properties :line LINUM
                                     :line-count N
                                     :type TYPE
                                     :signature SIGNATURE
                                     :std-int-doc DOCSTRING))

   SEXP

The first four are straightforward (both FILENAME and LINE are strings sans
newline, while LINUM and N are integers).  The last two always go together,
in that order.  SEXP is scheme code processed only by `read' and then
`write'.

The :type field may be omitted if the form is not recognized.  Otherwise,
TYPE may be one of: procedure, alias, define-module, variable.

The :signature field may be omitted if the form is not a procedure.
Otherwise, SIGNATURE is a list showing the procedure's signature.
For `define-syntax' forms, the signature is always `(NAME ...)'; i.e.,
a list of two symbols, the second being ellipses.

If the type is `procedure' and the form has a standard internal docstring
(first body form a string), that is extracted in full -- including any
embedded newlines -- and recorded by field :std-int-doc.


Usage from a program: The output list of sexps can be retrieved by scheme
programs w/o having to capture stdout, like so:

   (use-modules (scripts read-scheme-source))
   (define source-forms (read-scheme-source-silently "FILE1" "FILE2" ...))

There are also two convenience procs exported for use by Scheme programs:

(clump-comments FORMS) --- filter FORMS combining contiguous comment forms
                           that have the same number of leading semicolons.

(quoted? SYM FORM) --- see if FORM looks like: "(quote (SYM ...))", parse
                       the ":tags", and return alist of (TAG . VAL) elems.