grouping

[Thien-Thi Nguyen]

folks,

API scanning is the first step in knowing yourself (if you are a package
like guile).  next is developing some discernment on how these interface
elements are grouped, for this is the basis for a more fine-grained and
robust philosophical development (this is applicable to humans, too).

to do this we use a mechanism that allows us to separate the expression
of group membership predicates from the mundane record-keeping task of
recording these in a reliable way (see new script annotate-api-groupings
for that (in cvs HEAD)).

please see below for a preliminary (experimental) set of definitions
that everyone is invited to augment and refine -- this will eventually
be checked into doc/groupings.alist and maintained there.

to play, grab annotate-api-groupings and some guile-api.alist file, and
invoke like so:

  annotate-api-groupings guile-api.alist groupings.alist

see commentary in annotate-api-groupings for more info.

thi


__________________________________________________
;; groupings.alist
;; -*-scheme-*-

;; This file describes groupings of available bindings (both Scheme and C).
;; The overall structure is an alist.  Each entry has the form:
;;
;;   (NAME (description "DESCRIPTION") (members SYM...))
;;
;; All of these should be proper subsets of guile-api.alist.
;; Because of this property, it is an SMOP to annotate that alist,
;; and so the Scheme/C distinction need not be maintained here.
;;
;; In addition to `description' and `members' forms, the entry may
;; optionally include:
;;
;;   (grok USE-MODULES (lambda (x) CODE))
;;
;; where CODE implements a group-membership predicate applied to `x', which is
;; an API element object (this will be encapsulated into a closure before
;; release).  If this "grok procedure" produces the same set as the `members'
;; form, you can omit the `members' form entirely.  [When evaluated, CODE can
;; assume (use-modules MODULE) has been executed where MODULE is an element of
;; USE-MODULES, a list.  [NOT YET IMPLEMENTED!]]
;;
;; Currently, there are two convenience predicates that operate on `x':
;;   (in-group? x GROUP)
;;   (name-prefix? x PREFIX)
;;
;;+ When `x' is converted into a closure, the names of these predicates
;;+ will be maintained as first arg keys, e.g., "(in-group? x GROUP)" will
;;+ be expressed as "(x 'in-group? GROUP)".
;;
;; TODO: Move this text to annotate-api-groupings commentary; point there.

(

(C+scheme                       ;; This group should have no members!
 (description "in both groups `scheme' and `C'")
 (grok () (lambda (x)
            (and (in-group? x 'scheme) (in-group? x 'C)))))

(libguile-internal
 (description "begins with scm_i_")
 (grok () (lambda (x)
            (name-prefix? x "scm_i_"))))

(math
 (description "math functions")
 (members $abs $acos $acosh $asin $asinh $atan $atan2 $atanh $cos $cosh
          $exp $expt $log $sin $sinh $sqrt $tan $tanh))

(favorite
 (description "my favorite procs")
 (grok () (lambda (x)
            (and (in-group? x 'math) (in-group? x 'scheme)))))

;; Add new grouping descriptions here.
)

;; groupings.alist ends here