13.8 guile-tools bit-field-diagram

Usage: bit-field-diagram [--file FILE | BITSPEC]

Display a bit field diagram representing BITSPEC.  Option `--file'
means read the bitspec from FILE.  A BITSPEC is a Scheme list of
the form:

  (CONFIGURATION* [FIELD-SPEC...])

CONFIGURATION is an optionally-omitted list with car #:config
followed by CONFIG-SPEC forms, described below.  FIELD-SPEC is a
list (NAME WIDTH), where NAME is a symbol or string, and WIDTH an
integer.

For example:
$ guile-tools bit-field-diagram "((hello 5) (there 10))"
 hello     there
+---------+-------------------+
| | | | | | | | | | | | | | | |
+---------+-------------------+

Specifying CONFIG-SPEC forms, each a keyword/value pair, changes
the appearance of the output.  Currently supported:

  #:columns-per-bit       2       this includes a bar "|"
  #:suppress-sep-bars     #f      omit internal "|"
  #:field-name-justify    #:left  can also be #:right
  #:field-name-placement  #:over  can also be #:internal or #:under
  #:height                1       lines for the body of the field
  #:group                 #f      number of bits in a group, or #f
  #:merge-group-borders?  #f      merge internal borders

When #:merge-group-borders? is set, #:field-name-placement must be
#:internal, otherwise an error is signalled.  A #:field-name-placement
of #:internal automatically sets #:suppress-sep-bars.  When #:group is
specified, an error is signalled if the fields do not align to it.

Here is a more complicated example.  This form is placed in a file:

  ((#:config (#:columns-per-bit . 3)
             (#:field-name-justify . #:right)
             (#:field-name-placement . #:internal)
             (#:height . 3)
             (#:group . 16)
             (#:merge-group-borders? . #t))
   (hello 6)
   (there 10)
   (how 2)
   (are 3)
   (you 8)
   (doing 3)
   ("well i hope?" 11))

The result is:

  +-----------------+-----------------------------+
  |            hello|                        there|
  |                 |                             |
  |                 |                             |
  +-----+--------+--+--------------------+--------+
  |  how|     are|                    you|   doing|
  |     |        |                       |        |
  |     |        |                       |        |
  +-----+--------+-----------------+-----+--------+
  |                    well i hope?|
  |                                |
  |                                |
  +--------------------------------+


Usage from a Scheme program:

  (bit-field-diagram out spec/port)

OUT specifies where to write the output.  OUT #f means return a
string, otherwise the return value is unspecified.  SPEC/PORT is
either a BITSPEC sexp or a port where a BITSPEC can be `read'.


TODO: Support #:group-justify, #:border-style, #:bit-numbering,
              #:endian, per-group #:prefix and #:suffix, etc. etc.