13.34 guile-tools read-text-outline

Usage: read-text-outline OUTLINE

Scan OUTLINE file and display a list of trees, the structure of
each reflecting the "levels" in OUTLINE.  The recognized outline
format (used to indicate outline headings) is zero or more pairs of
leading spaces followed by "-".  Something like:

   - a                  0
     - b                1
       - c              2
     - d                1
   - e                  0
     - f                1
       - g              2
     - h                1

In this example the levels are shown to the right.  The output for
such a file would be the single line:

  (("a" ("b" "c") "d") ("e" ("f" "g") "h"))

Basically, anything at the beginning of a list is a parent, and the
remaining elements of that list are its children.  Generally, the
output is displayed with `(pretty-print TREE #:escape-strings? #t)'.


Usage from a Scheme program: These two procs are exported:

  (read-text-outline . args)           ; only first arg is used
  (read-text-outline-silently port)
  (make-text-outline-reader re specs)

`make-text-outline-reader' returns a proc that reads from PORT and
returns a list of trees (similar to `read-text-outline-silently').

RE is a regular expression (string) that is used to identify a header
line of the outline (as opposed to a whitespace line or intervening
text).  RE must begin w/ a sub-expression to match the "level prefix"
of the line.  You can use `level-submatch-number' in SPECS (explained
below) to specify a number other than 1, the default.

Normally, the level of the line is taken directly as the length of
its level prefix.  This often results in adjacent levels not mapping
to adjacent numbers, which confuses the tree-building portion of the
program, which expects top-level to be 0, first sub-level to be 1,
etc.  You can use `level-substring-divisor' or `compute-level' in
SPECS to specify a constant scaling factor or specify a completely
alternative procedure, respectively.

SPECS is an alist which may contain the following key/value pairs:

- level-submatch-number NUMBER
- level-substring-divisor NUMBER
- compute-level PROC
- body-submatch-number NUMBER
- extra-fields ((FIELD-1 . SUBMATCH-1) (FIELD-2 . SUBMATCH-2) ...)
- more-lines? BOOL

The PROC value associated with key `compute-level' should take a
Scheme match structure (as returned by `regexp-exec') and return a
number, the normalized level for that line.  If this is specified,
it takes precedence over other level-computation methods.

Use `body-submatch-number' if RE specifies the whole body, or if you
want to make use of the extra fields parsing.  The `extra-fields'
value is a sub-alist, whose keys name additional fields that are to
be recognized.  These fields along with `level' are set as object
properties of the final string ("body") that is consed into the tree.
If a field name ends in "?" the field value is set to be #t if there
is a match and the result is not an empty string, and #f otherwise.

Normally, only header lines are considered.  Use `more-lines?' with
a non-#f value to specify that non-header lines be included as well.
The structure of the output will be the same, however headers that
are not immediately followed by another will result in strings with
embedded (and possibly trailing) newline characters.


Bugs and caveats:

(1) Only the first file specified on the command line is scanned.
(2) TAB characters at the beginnings of lines are not recognized.
(3) Outlines that "skip" levels signal an error.  In other words,
    this will fail:

           - a               0
             - b             1
                 - c         3       <-- skipped 2 -- error!
             - d             1


TODO: Determine what's the right thing to do for skips.
      Handle TABs.
      Make line format customizable via longopts.